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
49 lines
1.6 KiB
TypeScript
49 lines
1.6 KiB
TypeScript
/**
|
|
* Reload Runtime Extension
|
|
*
|
|
* Demonstrates ctx.reload() from ExtensionCommandContext and an LLM-callable
|
|
* tool that requests a reload once the agent has settled.
|
|
*/
|
|
|
|
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
import { Type } from "typebox";
|
|
|
|
export default function (pi: ExtensionAPI) {
|
|
// Command entrypoint for reload.
|
|
// Treat reload as terminal for this handler.
|
|
pi.registerCommand("reload-runtime", {
|
|
description: "Reload extensions, skills, prompts, themes, and context files",
|
|
handler: async (_args, ctx) => {
|
|
await ctx.reload();
|
|
return;
|
|
},
|
|
});
|
|
|
|
// LLM-callable tool. Tools do not receive ExtensionCommandContext, so they cannot call
|
|
// ctx.reload(), and Pi cannot reload while the agent is running. The tool records the
|
|
// request and ends the run; the agent_settled handler then runs the command above.
|
|
let reloadRequested = false;
|
|
|
|
pi.registerTool({
|
|
name: "reload_runtime",
|
|
label: "Reload Runtime",
|
|
description: "Reload extensions, skills, prompts, themes, and context files",
|
|
parameters: Type.Object({}),
|
|
async execute() {
|
|
reloadRequested = true;
|
|
return {
|
|
content: [{ type: "text", text: "Reload requested. Pi reloads after this response." }],
|
|
details: {},
|
|
terminate: true,
|
|
};
|
|
},
|
|
});
|
|
|
|
pi.on("agent_settled", () => {
|
|
if (!reloadRequested) return;
|
|
reloadRequested = false;
|
|
// Sent from agent_settled, the command runs after every settled handler finishes, while
|
|
// the agent is idle. expandPromptTemplates dispatches it as a command, not as model input.
|
|
pi.sendUserMessage("/reload-runtime", { expandPromptTemplates: true });
|
|
});
|
|
}
|