mirror of
https://github.com/earendil-works/pi.git
synced 2026-10-28 17:54:40 +08:00
Christian Klotz
85c2ee3e76
## Summary The docs refresh (#9898) cut `docs/extensions.md` from about 3,100 lines to 130, dropping API reference and tool guidance. #11039 restored part of it. This PR restores the full guide and corrects it against current source. - **Structure:** the original sections, with the ASCII lifecycle diagram replaced by three Mermaid diagrams (run, turn, session) and ordered hook lists, plus a handler composition table. - **Merged:** content added after the cut: tool exposure, calling other tools, structured output, MCP servers, `registerToolRenderer`, virtual models, `provider_stream_event`, `before_agent_start` `messageType`. - **Corrected:** removed or renamed APIs (`modelRegistry.stream()`, prompt sections are `<tools>`/`<rules>`, `builtin:read` paths, `highlightCode`), wrong behavior claims (errors only by throwing, `model_select` on restore, `sendUserMessage` always triggering a turn, override warning, `truncateLine` bytes), examples that did not type-check, links to removed `tui.md` patterns and `rpc.md` anchors, and wrong API lists in the examples table. - **Kept:** anchors that other docs and changelogs link to, as `<a id>` tags. - **Fixed example:** `reload-runtime.ts` tool queued `/reload-runtime` with `deliverAs: "followUp"`. Queued text reaches the model as a plain user message, so the command never ran and Pi never reloaded. The tool now sets a flag and returns `terminate: true`; an `agent_settled` handler sends `/reload-runtime` with `expandPromptTemplates: true`, which runs after the settled handlers finish, while the agent is idle. In the long run it may be better to revisit how API reference is, provided to the agent, especially since more capable models do explore the source without it. ## Validation - `npm run check` - Edited TypeScript examples type-check against current types - All relative links and anchors in `extensions.md` resolve, including inbound anchors from other docs - `reload-runtime.ts`: faux-provider harness test (temporary, not committed) shows one reload after the run settles and no extra model request; the old version never reloads. Also verified in interactive mode with a real model. - Reviewed by GPT-6 Astra and GPT-5.6 Sol against source; all findings applied
Examples
Example code for the pi-coding-agent SDK, process integration, and extensions.
CLI integration
rpc-client.ts uses the typed RpcClient to run Pi in a child process, stream events, and wait for the run to settle.
Build the coding-agent package before running it from a repository checkout:
node examples/rpc-client.ts "Explain this repository"
Directories
sdk/
Programmatic usage via createAgentSession(). Shows how to customize models, prompts, tools, extensions, and session management.
extensions/
Example extensions demonstrating:
- Lifecycle event handlers (tool interception, safety gates, context modifications)
- Custom tools (todo lists, questions, subagents, output truncation)
- Commands and keyboard shortcuts
- Custom UI (footers, headers, editors, overlays)
- Git integration (checkpoints, auto-commit)
- System prompt modifications and custom compaction
- External integrations (SSH, file watchers, system theme sync)
- Custom providers (Anthropic with custom streaming, GitLab Duo)