81 lines
3.5 KiB
Markdown
81 lines
3.5 KiB
Markdown
# AGENTS.md
|
|
|
|
## What this is
|
|
|
|
A Pi coding agent extension that provides a file-claiming mechanism to prevent conflicts when working with files. Not a standalone app — it runs inside Pi's extension host.
|
|
|
|
## Type checking
|
|
|
|
```
|
|
npm run typecheck # tsc --noEmit
|
|
```
|
|
|
|
No build step needed — Pi loads extensions via [jiti](https://github.com/unjs/jiti), which compiles TypeScript at runtime. `index.ts` is the entry point directly.
|
|
|
|
## Entry point
|
|
|
|
`index.ts` at repo root (not `src/`). Exports a default function receiving `ExtensionAPI`.
|
|
|
|
## External dependencies
|
|
|
|
The extension imports from Pi SDK packages (not in `package.json` — provided by the host):
|
|
|
|
- `@earendil-works/pi-coding-agent` — `ExtensionAPI`, `ExtensionContext`, `ExtensionCommandContext`, etc.
|
|
- `@earendil-works/pi-agent-core` — `AgentMessage`, `ToolResultMessage`, etc.
|
|
- `@earendil-works/pi-tui` — TUI components (if needed)
|
|
- `typebox` — `Type` for tool parameter schema definitions
|
|
|
|
The extension has no external npm dependencies — all locking logic is self-contained.
|
|
|
|
## Source structure
|
|
|
|
- `index.ts` — extension entry, registry implementation, event bus, command registration, config command
|
|
- `src/` — all logic modules:
|
|
- `config.ts` — typed configuration with defaults, file persistence, validation
|
|
- `diagnostics.ts` — LSP-inspired diagnostic system for lock status
|
|
- `edge-cases.ts` — crash recovery, race condition prevention, path resolution, lock migration
|
|
- `event-handlers.ts` — Pi lifecycle event handlers (tool_call, turn_end, session_shutdown, etc.)
|
|
- `lock-acquisition.ts` — lock acquisition, auto-claim, blocking, conflict resolution
|
|
- `lock-manager.ts` — atomic file operations, cross-process coordination
|
|
- `lock-types.ts` — all TypeScript interfaces and types
|
|
- `notifications.ts` — notification system for lock events
|
|
- `system-prompt.ts` — system prompt injection for lock claiming protocol
|
|
- `tools.ts` — LLM-callable tools (file_claiming_claim, release, list, check)
|
|
- `user-interaction.ts` — interactive lock query UI components
|
|
- `tests/` — all test files
|
|
|
|
## Lock types
|
|
|
|
Three lock types with increasing exclusivity:
|
|
|
|
- **read** — Shared read access. Multiple tools can hold read claims simultaneously.
|
|
- **write** — Exclusive write access. Only one write claim per file path.
|
|
- **exclusive** — Full exclusive access. No other claim of any type allowed.
|
|
|
|
## Runtime state
|
|
|
|
All runtime state lives in memory within the registry (`ClaimRegistry`). Configuration is persisted to `{lockDir}/config.json` (defaults to `~/.pi/agent/locks/config.json`).
|
|
|
|
## Tools registered
|
|
|
|
The extension registers four LLM-callable tools:
|
|
|
|
- `file_claiming_claim` — claim a file with a lock
|
|
- `file_claiming_release` — release a claim by ID or path
|
|
- `file_claiming_list` — list all active claims
|
|
- `file_claiming_check` — check lock status for a specific file
|
|
|
|
## Commands registered
|
|
|
|
- `/file-claiming-config` — view or update configuration at runtime
|
|
- `/file-claiming-locks` — interactive lock management
|
|
|
|
## Events emitted
|
|
|
|
| Event | Payload | Description |
|
|
|--------------------|---------------|---------------------------------|
|
|
| `claim:acquired` | `ClaimEvent` | A claim was successfully acquired. |
|
|
| `claim:released` | `ClaimEvent` | A claim was released. |
|
|
| `claim:conflicted` | `ClaimEvent` | A claim could not be acquired. |
|
|
| `claim:expired` | `ClaimEvent` | A claim was auto-expired. |
|