mirror of
https://github.com/badlogic/pi-mono.git
synced 2026-11-05 23:37:25 +00:00
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 |
||
|---|---|---|
| .. | ||
| agent | ||
| ai | ||
| chord | ||
| codemode | ||
| coding-agent | ||
| durable | ||
| env | ||
| evals | ||
| mcp | ||
| telemetry | ||
| tui | ||