@tea-agent/loop-agent 0.43.0-next.9 → 0.43.0

package/dist/worker/console/chat/pi-runtime/custom-tools/browser-tools.js

@@ -0,0 +1,184 @@
+/**
+ * Session-independent Playwright browser tools shared by workflow and Pi chat
+ * modes. Actions use refs from the AI-mode aria snapshot and return a fresh
+ * snapshot. Screenshots are captured only by the explicit screenshot tool.
+ */
+const BROWSER_TOOLS_DESCRIPTION = "Operate the workspace-controlled visible external browser. The Console sidebar stays an iframe and does not proxy page input. `browser_navigate` opens a URL in the external window; `browser_snapshot` returns the current aria snapshot with element refs; `browser_act` clicks/fills/presses/hovers a ref; `browser_search` fills and submits the real search form; `browser_tabs`, `browser_scroll`, `browser_press`, `browser_dialog`, `browser_wait`, and `browser_screenshot` manage state. Use refs only from the immediately preceding snapshot. It never edits workspace files and does not execute page JavaScript.";
+export async function buildBrowserTools(options) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const automation = options.automation;
+    const urlParameter = Type.String({
+        description: "Absolute http(s) URL.",
+    });
+    const refParameter = Type.String({
+        description: "Element ref from the most recent browser_snapshot (for example e12).",
+    });
+    async function execute(operation) {
+        try {
+            const result = await operation();
+            return {
+                content: [{ type: "text", text: JSON.stringify(result) }],
+                details: result,
+            };
+        }
+        catch (error) {
+            const payload = {
+                error: error instanceof Error ? error.message : String(error),
+                code: error instanceof Error && "code" in error
+                    ? String(error.code)
+                    : "BROWSER_OPERATION_FAILED",
+            };
+            return {
+                content: [{ type: "text", text: JSON.stringify(payload) }],
+                details: payload,
+            };
+        }
+    }
+    return [
+        defineTool({
+            name: "browser_navigate",
+            label: "Browser navigate",
+            description: BROWSER_TOOLS_DESCRIPTION,
+            promptSnippet: BROWSER_TOOLS_DESCRIPTION,
+            parameters: Type.Object({ url: urlParameter }, { additionalProperties: false }),
+            async execute(_toolCallId, params) {
+                return execute(() => automation.navigate(params.url));
+            },
+        }),
+        defineTool({
+            name: "browser_search",
+            label: "Browser search",
+            description: BROWSER_TOOLS_DESCRIPTION,
+            promptSnippet: BROWSER_TOOLS_DESCRIPTION,
+            parameters: Type.Object({
+                query: Type.String({ description: "Search query." }),
+                engineUrl: Type.Optional(urlParameter),
+            }, { additionalProperties: false }),
+            async execute(_toolCallId, params) {
+                return execute(() => automation.search(params.query, params.engineUrl));
+            },
+        }),
+        defineTool({
+            name: "browser_snapshot",
+            label: "Browser snapshot",
+            description: BROWSER_TOOLS_DESCRIPTION,
+            promptSnippet: BROWSER_TOOLS_DESCRIPTION,
+            parameters: Type.Object({}, { additionalProperties: false }),
+            async execute() {
+                return execute(() => automation.snapshot({ screenshot: false }));
+            },
+        }),
+        defineTool({
+            name: "browser_act",
+            label: "Browser act",
+            description: BROWSER_TOOLS_DESCRIPTION,
+            promptSnippet: BROWSER_TOOLS_DESCRIPTION,
+            parameters: Type.Object({
+                type: Type.Union([
+                    Type.Literal("click"),
+                    Type.Literal("fill"),
+                    Type.Literal("press"),
+                    Type.Literal("hover"),
+                ]),
+                ref: refParameter,
+                value: Type.Optional(Type.String()),
+                key: Type.Optional(Type.String()),
+            }, { additionalProperties: false }),
+            async execute(_toolCallId, params) {
+                return execute(() => automation.act(params.type === "fill"
+                    ? { type: "fill", ref: params.ref, value: params.value ?? "" }
+                    : params.type === "press"
+                        ? { type: "press", ref: params.ref, key: params.key ?? "Enter" }
+                        : { type: params.type, ref: params.ref }));
+            },
+        }),
+        defineTool({
+            name: "browser_tabs",
+            label: "Browser tabs",
+            description: BROWSER_TOOLS_DESCRIPTION,
+            promptSnippet: BROWSER_TOOLS_DESCRIPTION,
+            parameters: Type.Object({
+                action: Type.Union([
+                    Type.Literal("list"),
+                    Type.Literal("new"),
+                    Type.Literal("select"),
+                    Type.Literal("close"),
+                ]),
+                tabId: Type.Optional(Type.Integer()),
+                url: Type.Optional(urlParameter),
+            }, { additionalProperties: false }),
+            async execute(_toolCallId, params) {
+                return execute(() => {
+                    if (params.action === "list")
+                        return automation.snapshot({ screenshot: false });
+                    if (params.action === "new")
+                        return automation.newTab(params.url);
+                    if (params.tabId === undefined)
+                        throw new Error("tabId is required");
+                    return params.action === "select"
+                        ? automation.selectTab(params.tabId)
+                        : automation.closeTab(params.tabId);
+                });
+            },
+        }),
+        defineTool({
+            name: "browser_scroll",
+            label: "Browser scroll",
+            description: BROWSER_TOOLS_DESCRIPTION,
+            promptSnippet: BROWSER_TOOLS_DESCRIPTION,
+            parameters: Type.Object({
+                direction: Type.Union([Type.Literal("up"), Type.Literal("down")]),
+                amount: Type.Optional(Type.Integer({ minimum: 50, maximum: 3000 })),
+            }, { additionalProperties: false }),
+            async execute(_toolCallId, params) {
+                return execute(() => automation.scroll(params));
+            },
+        }),
+        defineTool({
+            name: "browser_press",
+            label: "Browser press key",
+            description: BROWSER_TOOLS_DESCRIPTION,
+            promptSnippet: BROWSER_TOOLS_DESCRIPTION,
+            parameters: Type.Object({ key: Type.String() }, { additionalProperties: false }),
+            async execute(_toolCallId, params) {
+                return execute(() => automation.pressKey(params.key));
+            },
+        }),
+        defineTool({
+            name: "browser_dialog",
+            label: "Browser dialog",
+            description: BROWSER_TOOLS_DESCRIPTION,
+            promptSnippet: BROWSER_TOOLS_DESCRIPTION,
+            parameters: Type.Object({
+                action: Type.Union([Type.Literal("accept"), Type.Literal("dismiss")]),
+                promptText: Type.Optional(Type.String()),
+            }, { additionalProperties: false }),
+            async execute(_toolCallId, params) {
+                return execute(() => automation.handleDialog(params.action, params.promptText));
+            },
+        }),
+        defineTool({
+            name: "browser_wait",
+            label: "Browser wait",
+            description: BROWSER_TOOLS_DESCRIPTION,
+            promptSnippet: BROWSER_TOOLS_DESCRIPTION,
+            parameters: Type.Object({ ms: Type.Integer({ minimum: 0, maximum: 10_000 }) }, { additionalProperties: false }),
+            async execute(_toolCallId, params) {
+                return execute(() => automation.waitFor(params.ms));
+            },
+        }),
+        defineTool({
+            name: "browser_screenshot",
+            label: "Browser screenshot",
+            description: BROWSER_TOOLS_DESCRIPTION,
+            promptSnippet: BROWSER_TOOLS_DESCRIPTION,
+            parameters: Type.Object({}, { additionalProperties: false }),
+            async execute() {
+                return execute(() => automation.screenshot());
+            },
+        }),
+    ];
+}

package/dist/worker/console/chat/pi-runtime/custom-tools/explore-tools.js

@@ -0,0 +1,202 @@
+/**
+ * Session-less safe explore custom tools (safe-read / safe-grep / git-status /
+ * git-diff). Execution uses explore-tools.ts path guards and secret scrubbing.
+ * ConsolePiRuntime owns the sessionless cache.
+ */
+/**
+ * Build the safe explore custom tools (roadmap M0-A / G16): safe-read,
+ * safe-grep, gitStatus, gitDiff. These replace the bare SDK bash/read/grep so
+ * the model can probe the repo WITHOUT write escapes (echo redirect, tee,
+ * sed -i, node -e) and WITHOUT reading sensitive files (env files, key/pem,
+ * auth.json, sessions dir) — and every returned byte is secret-scrubbed
+ * before reaching the model context.
+ *
+ * gitStatus/gitDiff use a FIXED argv (typed, no shell) so they cannot be
+ * turned into an arbitrary-shell vector.
+ */
+export async function buildExploreCustomTools(options) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const { execFileSync } = await import("node:child_process");
+    const repoRoot = options.repoRoot;
+    const { safeReadFile, safeGrep, scrubSecrets } = await import("../../explore-tools.js");
+    function safeGit(args) {
+        try {
+            const stdout = execFileSync("git", args, {
+                cwd: repoRoot,
+                encoding: "utf8",
+                // Fixed argv, no shell, bounded output.
+                maxBuffer: 512 * 1024,
+                timeout: 10_000,
+                windowsHide: true,
+            });
+            return { ok: true, stdout };
+        }
+        catch (e) {
+            return {
+                ok: false,
+                code: "GIT_FAILED",
+                message: e instanceof Error ? e.message : String(e),
+            };
+        }
+    }
+    const safeReadTool = defineTool({
+        name: "safe-read",
+        label: "safe-read",
+        description: "Read a repo-relative file with sensitive-file denylist (.env*/*.key/*.pem/.git/**/auth.json/sessions/**) and secret scrubbing. Absolute paths and .. are rejected.",
+        promptSnippet: "safe-read: read a repo file (safe; secrets scrubbed)",
+        parameters: Type.Object({
+            path: Type.String({ description: "repo-relative file path" }),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const raw = String(params.path ?? "");
+            try {
+                const result = await safeReadFile(repoRoot, raw);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result) }],
+                    details: result,
+                };
+            }
+            catch (e) {
+                const err = e;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: err.message ?? String(e),
+                                code: err.code ?? "READ_FAILED",
+                            }),
+                        },
+                    ],
+                    details: {
+                        error: err.message ?? String(e),
+                        code: err.code ?? "READ_FAILED",
+                    },
+                };
+            }
+        },
+    });
+    const safeGrepTool = defineTool({
+        name: "safe-grep",
+        label: "safe-grep",
+        description: "Line search across the repo working tree with sensitive-file denylist and secret scrubbing. pattern is a JS regex source; optional glob filters paths.",
+        promptSnippet: "safe-grep: search repo files (safe; secrets scrubbed)",
+        parameters: Type.Object({
+            pattern: Type.String({ description: "regex source (no shell)" }),
+            caseInsensitive: Type.Optional(Type.Boolean()),
+            glob: Type.Optional(Type.String({ description: "optional glob filter e.g. *.ts" })),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            try {
+                const result = await safeGrep(repoRoot, String(params.pattern ?? ""), {
+                    caseInsensitive: Boolean(params.caseInsensitive),
+                    glob: params.glob ? String(params.glob) : undefined,
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result) }],
+                    details: result,
+                };
+            }
+            catch (e) {
+                const err = e;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: err.message ?? String(e),
+                                code: err.code ?? "GREP_FAILED",
+                            }),
+                        },
+                    ],
+                    details: {
+                        error: err.message ?? String(e),
+                        code: err.code ?? "GREP_FAILED",
+                    },
+                };
+            }
+        },
+    });
+    const gitStatusTool = defineTool({
+        name: "git-status",
+        label: "git-status",
+        description: "Typed `git status --porcelain` (fixed argv, no shell). Returns scrubbed working-tree status.",
+        promptSnippet: "git-status: working tree status (read-only)",
+        parameters: Type.Object({}, { additionalProperties: false }),
+        async execute() {
+            const r = safeGit(["status", "--porcelain"]);
+            if (!r.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ error: r.message, code: r.code }),
+                        },
+                    ],
+                    details: { error: r.message, code: r.code },
+                };
+            }
+            const { scrubbed, redactions } = scrubSecrets(r.stdout);
+            const payload = { status: scrubbed, redactions };
+            return {
+                content: [{ type: "text", text: JSON.stringify(payload) }],
+                details: payload,
+            };
+        },
+    });
+    const gitDiffTool = defineTool({
+        name: "git-diff",
+        label: "git-diff",
+        description: "Typed `git diff` (fixed argv: --stat or a single -- path; no shell). Returns scrubbed diff. path must be repo-relative and not sensitive.",
+        promptSnippet: "git-diff: diff (read-only, scrubbed)",
+        parameters: Type.Object({
+            path: Type.Optional(Type.String({
+                description: "optional repo-relative path to diff (default: whole tree --stat)",
+            })),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            let rawPath = params.path ? String(params.path) : undefined;
+            // If a path is supplied, validate it via the read-path guard so git diff
+            // cannot be aimed at sensitive files (.env* / auth.json / sessions).
+            if (rawPath) {
+                const { guardReadPath } = await import("../../explore-tools.js");
+                const g = await guardReadPath(repoRoot, rawPath);
+                if (!g.ok) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({ error: g.message, code: g.code }),
+                            },
+                        ],
+                        details: { error: g.message, code: g.code },
+                    };
+                }
+                rawPath = g.repoRelative;
+            }
+            const args = rawPath ? ["diff", "--", rawPath] : ["diff", "--stat"];
+            const r = safeGit(args);
+            if (!r.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ error: r.message, code: r.code }),
+                        },
+                    ],
+                    details: { error: r.message, code: r.code },
+                };
+            }
+            const { scrubbed, redactions } = scrubSecrets(r.stdout);
+            const payload = { diff: scrubbed, redactions };
+            return {
+                content: [{ type: "text", text: JSON.stringify(payload) }],
+                details: payload,
+            };
+        },
+    });
+    return [safeReadTool, safeGrepTool, gitStatusTool, gitDiffTool];
+}

package/dist/worker/console/chat/pi-runtime/custom-tools/goal-tools.js

@@ -0,0 +1,79 @@
+/**
+ * Session-bound Goal tools (shared by workflow and Pi modes since
+ * 2026-09-10; see exec-plan 2026-09-10-console-chat-goal-for-pi-mode).
+ * create_goal still requires a consumed model-create grant from the registry.
+ */
+const GET_GOAL_DESCRIPTION = "Read the current session's durable cross-turn Goal, including revision, status, round limit, and whether this Console process is authorized to continue it.";
+const CREATE_GOAL_DESCRIPTION = "Create a durable cross-turn Goal only when the user explicitly asks to start or create a Goal. Never silently upgrade an ordinary request. A session may have only one unfinished Goal.";
+const UPDATE_GOAL_DESCRIPTION = "Finish or block the current durable Goal using its exact goalId and revision. Set complete only when the objective is genuinely achieved and no required work remains. Set blocked only when safe progress cannot continue; include the blocker.";
+export async function buildGoalTools(options) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const textResult = (value) => ({
+        content: [{ type: "text", text: JSON.stringify(value) }],
+        details: value,
+    });
+    return [
+        defineTool({
+            name: "get_goal",
+            label: "Get goal",
+            description: GET_GOAL_DESCRIPTION,
+            promptSnippet: GET_GOAL_DESCRIPTION,
+            parameters: Type.Object({}, { additionalProperties: false }),
+            async execute() {
+                return textResult({ goal: options.registry.get(options.sessionId) });
+            },
+        }),
+        defineTool({
+            name: "create_goal",
+            label: "Create goal",
+            description: CREATE_GOAL_DESCRIPTION,
+            promptSnippet: CREATE_GOAL_DESCRIPTION,
+            parameters: Type.Object({
+                objective: Type.String({
+                    description: "Concrete final objective and completion standard explicitly requested by the user.",
+                }),
+            }, { additionalProperties: false }),
+            async execute(_toolCallId, params) {
+                if (!options.registry.consumeModelCreateGrant(options.sessionId)) {
+                    return textResult({
+                        ok: false,
+                        code: "GOAL_EXPLICIT_REQUEST_REQUIRED",
+                        message: "create_goal requires an explicit user request to create or start a Goal",
+                    });
+                }
+                return textResult(options.registry.create({
+                    sessionId: options.sessionId,
+                    objective: params.objective,
+                }));
+            },
+        }),
+        defineTool({
+            name: "update_goal",
+            label: "Update goal",
+            description: UPDATE_GOAL_DESCRIPTION,
+            promptSnippet: UPDATE_GOAL_DESCRIPTION,
+            parameters: Type.Object({
+                goalId: Type.String(),
+                revision: Type.Number({ minimum: 1 }),
+                status: Type.Union([
+                    Type.Literal("complete"),
+                    Type.Literal("blocked"),
+                ]),
+                blocker: Type.Optional(Type.String()),
+            }, { additionalProperties: false }),
+            async execute(_toolCallId, params) {
+                return textResult(options.registry.update({
+                    sessionId: options.sessionId,
+                    goalId: params.goalId,
+                    expectedRevision: params.revision,
+                    phase: params.status,
+                    blocker: params.blocker,
+                    arm: false,
+                }));
+            },
+        }),
+    ];
+}

package/dist/worker/console/chat/pi-runtime/custom-tools/operator-tools.js

@@ -0,0 +1,94 @@
+/**
+ * Session-less operator-action custom tools (workflow-mode business tools).
+ * Definitions and execute() live here; ConsolePiRuntime owns caching and
+ * composition with session-bound tools.
+ */
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { scheduledGoalBookingSchema } from "../../scheduled-goal-booking.js";
+import { authorizeChatSessionTool, DEFAULT_CONSOLE_CHAT_SESSION_MODE, } from "../../session-mode.js";
+import { buildModelCallableToolSchemas } from "../../tool-adapter.js";
+/**
+ * Build Pi custom ToolDefinition objects for every whitelisted operator action.
+ * Each tool's execute() routes into the operator action dispatcher (Gate 3).
+ * Requires the `typebox` + `defineTool` packages (both bundled with the SDK).
+ */
+export async function buildCustomOperatorTools(options) {
+    // typebox is a transitive dep of @earendil-works/pi-coding-agent; Node's
+    // resolver hoists to the SDK's nested copy. defineTool is re-exported by SDK.
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const schemas = buildModelCallableToolSchemas().filter((schema) => schema.toolId !== "prepareScheduledTask");
+    const ctx = options.actionContext;
+    return schemas.map((schema) => {
+        // TypeBox schema is built dynamically; cast through unknown to the builder
+        // since Static<TParams> is structural and cannot be statically inferred here.
+        const parameters = Type.Object(schema.inputParams.reduce((acc, param) => {
+            // Carry the registry's param description into the tool schema so
+            // the model sees parameter semantics, not just names/types.
+            const desc = param.description?.trim()
+                ? { description: param.description }
+                : {};
+            let t;
+            if (schema.toolId === "prepareScheduledGoal" && param.name === "booking") {
+                // Provider adapters need every nested type (not an opaque object).
+                // Keep the strict service schema as the single input contract.
+                t = zodToJsonSchema(scheduledGoalBookingSchema, { $refStrategy: "none" });
+            }
+            else
+                switch (param.type) {
+                    case "string":
+                        t = Type.String(desc);
+                        break;
+                    case "boolean":
+                        t = Type.Boolean(desc);
+                        break;
+                    case "number":
+                        t = Type.Number(desc);
+                        break;
+                    case "array":
+                        t = Type.Array(Type.String({}), Object.keys(desc).length ? desc : {});
+                        break;
+                    default:
+                        t = Type.Object({}, { additionalProperties: true });
+                }
+            acc[param.name] = param.required ? t : Type.Optional(t);
+            return acc;
+        }, {}), { additionalProperties: false });
+        return defineTool({
+            name: schema.toolId,
+            label: schema.toolId,
+            description: `${schema.description} (kind=${schema.kind}; cli: ${schema.cli})`,
+            promptSnippet: schema.description,
+            parameters: parameters,
+            async execute(toolCallId, params) {
+                const decision = authorizeChatSessionTool(schema.toolId, options.sessionMode ?? DEFAULT_CONSOLE_CHAT_SESSION_MODE);
+                if (!decision.ok) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    error: decision.message,
+                                    code: decision.code,
+                                }),
+                            },
+                        ],
+                        details: { error: decision.message, code: decision.code },
+                    };
+                }
+                // Defer require to avoid circular import at module load.
+                const { dispatchChatToolCall } = await import("../../session-store.js");
+                const result = await dispatchChatToolCall(ctx, decision.toolId, params, toolCallId, options.sessionMode);
+                const payload = result.ok
+                    ? result.result
+                    : { error: result.message, code: result.errorCode };
+                return {
+                    content: [{ type: "text", text: JSON.stringify(payload) }],
+                    details: payload,
+                };
+            },
+        });
+    });
+}

package/dist/worker/console/chat/pi-runtime/custom-tools/scheduled-goal-tools.js

@@ -0,0 +1,22 @@
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { scheduledTaskRequestSchema } from "../../scheduled-goal-request.js";
+import { buildModelCallableToolSchemas } from "../../tool-adapter.js";
+/** Host-bound identity is not a model parameter and cannot leak across sessions. */
+export async function buildScheduledGoalTools(options) {
+    const { Type } = await import("typebox");
+    const { defineTool } = await import("@earendil-works/pi-coding-agent");
+    const schema = buildModelCallableToolSchemas().find((tool) => tool.action === "prepareScheduledTask");
+    if (!schema)
+        throw new Error("scheduled task capability missing");
+    return [defineTool({
+            name: schema.toolId, label: "准备定时任务", description: schema.description, promptSnippet: schema.description,
+            parameters: Type.Object({ request: zodToJsonSchema(scheduledTaskRequestSchema, { $refStrategy: "none" }) }, { additionalProperties: false }),
+            async execute(callId, params) {
+                const { dispatchChatToolCall } = await import("../../session-store.js");
+                const result = await dispatchChatToolCall({ ...options.actionContext, chatSessionRef: options.sessionId }, schema.toolId, params, callId, "workflow");
+                const value = result.ok ? result.result : { ok: false, error: result.message, code: result.errorCode,
+                    nextAction: "Correct the business request and retry prepareScheduledTask. Do not edit PRD/runtime files, substitute sleep/immediate execution, or claim a booking exists." };
+                return { isError: !result.ok, content: [{ type: "text", text: JSON.stringify(value) }], details: value };
+            },
+        })];
+}

package/dist/worker/console/chat/pi-runtime/custom-tools/todo-write.js

@@ -0,0 +1,38 @@
+/**
+ * Session-bound todo_write custom tool.
+ * Description is mode-aware; ConsolePiRuntime owns when to register it.
+ */
+import { PI_TODO_WRITE_DESCRIPTION, } from "../../session-mode.js";
+const TODO_WRITE_DESCRIPTION = "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (no partial updates, no per-item edits). Before starting multi-step work, add one todo per concrete step. Keep at least one todo `in_progress` while work remains. Mark a todo `completed` immediately when it is done (do not batch completions) and resend the full list as progress or DAG state advances. Skip the list for simple Q&A, read-only lookups, and single-step tasks. Use it for multi-step implementation and whenever you prepare, run, or supervise a DAG — call `todo_write` before entering the DAG tool chain. Phrase DAG todos as user-facing phases users can understand, not copies of internal DAG nodes. Statuses: `pending` / `in_progress` / `completed`.";
+export async function buildTodoWriteTool(options) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const description = options.sessionMode === "pi"
+        ? PI_TODO_WRITE_DESCRIPTION
+        : TODO_WRITE_DESCRIPTION;
+    return defineTool({
+        name: "todo_write",
+        label: "Update todo list",
+        description,
+        promptSnippet: description,
+        parameters: Type.Object({
+            todos: Type.Array(Type.Object({
+                content: Type.String({ description: "Short imperative task description." }),
+                status: Type.Union([
+                    Type.Literal("pending"),
+                    Type.Literal("in_progress"),
+                    Type.Literal("completed"),
+                ]),
+            }, { additionalProperties: false })),
+        }, { additionalProperties: false }),
+        async execute(toolCallId, params) {
+            const result = options.registry.write(options.sessionId, toolCallId, params.todos);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result) }],
+                details: result,
+            };
+        },
+    });
+}

package/dist/worker/console/chat/pi-runtime/inspection-types.js

@@ -0,0 +1,28 @@
+/**
+ * Live runtime snapshot types and the structured critical-failure error.
+ * Projection and inventory collection live in inspection.ts; ConsolePiRuntime
+ * remains the owner of live session lookup and preference-cache refresh.
+ */
+export const THINKING_LEVELS = [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max",
+];
+/**
+ * Structured critical-failure error for snapshot projection (RF-02). Model
+ * enumeration or system prompt projection failures throw this so consuming
+ * routes can return 503 PI_RUNTIME_UNAVAILABLE instead of a fake-empty 200.
+ * Partial ResourceLoader / package-inventory failures are NOT critical — they
+ * keep the 200 snapshot and surface as structured diagnostics instead.
+ */
+export class RuntimeSnapshotUnavailableError extends Error {
+    code = "PI_RUNTIME_UNAVAILABLE";
+    constructor(message) {
+        super(message);
+        this.name = "RuntimeSnapshotUnavailableError";
+    }
+}