88 lines
3.3 KiB
Markdown
88 lines
3.3 KiB
Markdown
# File Claiming
|
|
|
|
A Pi extension that provides a file-claiming mechanism to prevent conflicts when working with files. Tracks read, write, and exclusive claims on file paths.
|
|
|
|
```bash
|
|
pi install npm:@mikefreno/file-claiming
|
|
```
|
|
|
|
## Features
|
|
|
|
- **Three lock types**: `read` (shared), `write` (exclusive write), `exclusive` (full exclusive)
|
|
- **Auto-claim on edit**: Automatically claims files on first edit/write operation
|
|
- **Auto-release at turn end**: Claims are automatically released when your turn ends
|
|
- **TTL-based expiry**: Configurable auto-release timeout (default: 5 minutes)
|
|
- **Conflict detection**: Clear error messages when locks conflict
|
|
- **Diagnostics widget**: Real-time lock status in the diagnostics footer
|
|
- **LLM-callable tools**: Tools for agents to claim, release, list, and check locks
|
|
- **Interactive commands**: Slash commands for manual lock management
|
|
- **Cross-session awareness**: Detects concurrent access across Pi sessions
|
|
|
|
## How it works
|
|
|
|
### Lock Protocol
|
|
|
|
1. **Before editing** a file, check if it has an active claim
|
|
2. **Claim the file** with the appropriate lock type
|
|
3. **Edit with confidence** — other tools will be blocked from conflicting operations
|
|
4. **Release the claim** when done (or let auto-release handle it)
|
|
|
|
### Claim Types
|
|
|
|
| Type | Behavior |
|
|
|------|----------|
|
|
| `read` | Shared read access. Multiple read claims can coexist on the same file. |
|
|
| `write` | Exclusive write access. Only one write claim per file path. |
|
|
| `exclusive` | Full exclusive access. No other claim of any type allowed. |
|
|
|
|
### Conflict Resolution
|
|
|
|
If you try to claim a file that is locked by another tool, you will receive a conflict notification showing the blocker's claim ID, type, and owner. You can release conflicting claims manually or wait for auto-release.
|
|
|
|
## Usage
|
|
|
|
### Tools (LLM-callable)
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `file_claiming_claim` | Claim a file with read, write, or exclusive lock |
|
|
| `file_claiming_release` | Release a file claim by ID or path |
|
|
| `file_claiming_list` | List all active file claims |
|
|
| `file_claiming_check` | Check lock status for a specific file |
|
|
|
|
### Commands (interactive)
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `/file-claiming-config` | View or update configuration at runtime |
|
|
| `/file-claiming-locks` | Interactive lock management |
|
|
|
|
## Configuration
|
|
|
|
| Option | Type | Default | Description |
|
|
|--------|------|---------|-------------|
|
|
| `autoReleaseTTL` | number | `300000` (5 min) | Milliseconds before a claim is auto-released |
|
|
| `releaseOnTurnEnd` | boolean | `true` | Release all claims at turn end |
|
|
| `lockDir` | string | `~/.pi/agent/locks` | Directory for lock persistence files |
|
|
| `blockedTools` | string[] | `["edit", "write"]` | Tools blocked while locks exist |
|
|
| `showDiagnostics` | boolean | `true` | Show lock status in diagnostics footer |
|
|
|
|
Update config at runtime:
|
|
|
|
```
|
|
/file-claiming-config autoReleaseTTL=600000
|
|
/file-claiming-config releaseOnTurnEnd=false
|
|
/file-claiming-config showDiagnostics=false
|
|
```
|
|
|
|
## Events
|
|
|
|
The extension emits events on the shared extension bus:
|
|
|
|
| Event | Description |
|
|
|-------|-------------|
|
|
| `claim:acquired` | A claim was successfully acquired |
|
|
| `claim:released` | A claim was released |
|
|
| `claim:conflicted` | A claim could not be acquired |
|
|
| `claim:expired` | A claim was auto-expired |
|