Initial commit

AGENTS.md

@@ -0,0 +1,80 @@
+# 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.       |