# Pi Extension API reference used by Intent Petri

Intent Petri targets `@earendil-works/pi-coding-agent` 0.80.6 during initial development.

## Installed official documentation

Resolved from the installed `@earendil-works/pi-coding-agent` package:

- `docs/extensions.md`
- `docs/tui.md`
- `docs/packages.md`
- `docs/session-format.md`

## APIs used in V2

- `pi.registerTool()` for `update_action_path`.
- `pi.registerCommand()` for `/intent-petri`.
- `pi.on("session_start")` and `pi.on("session_tree")` for branch-aware reconstruction.
- `pi.on("before_agent_start")` for non-persistent current-path context.
- `pi.on("tool_execution_start/update/end")` for transient elapsed/last-activity feedback written to `activity.json`; these events never become graph nodes.
- `pi.on("session_shutdown")` for idempotent resource cleanup.
- `ctx.sessionManager.getBranch()` as the branch authority.
- Tool result `details` as the persisted graph checkpoint.
- Intent Petri deliberately does not use `ctx.ui.setStatus()`, `ctx.ui.setWidget()`, `ctx.ui.custom()`, or Pi overlay APIs. Visualization is hosted by a Herdr plugin pane.

## Lifecycle constraints

- Do not open SQLite, start timers, sockets, or servers from the extension factory. The one-second activity heartbeat starts only while at least one tool is running and is cleared on tool completion or shutdown.
- Initialize session-scoped resources from `session_start`.
- Clean SQLite and runtime timers/subscriptions from `session_shutdown`, and mark the external activity projection closed.
- Custom entries and tool-result details do not enter the LLM context; per-turn system-prompt augmentation is used to tell the Agent the current graph revision and active path.

## Packaging constraints

Pi-provided packages stay in `peerDependencies` with `"*"` ranges. Development pins 0.80.6 for repeatable type checking and smoke tests. `beautiful-mermaid` is a normal runtime dependency. The package declares the Pi extension and external viewer CLI, while `herdr-plugin.toml` declares the Herdr action and pane:

```json
{
  "pi": {
    "extensions": ["./extensions/index.ts"]
  },
  "bin": {
    "intent-petri-viewer": "./bin/intent-petri-viewer.mjs"
  }
}
```