@evandu/super-pi 0.0.0-stage → 0.1.0

package/dist/server/task-tool.d.ts

@@ -0,0 +1,196 @@
+import type { AgentDefinition, TodoItem } from "./types.js";
+/**
+ * The `task` tool: how a primary agent hands work to a sub-agent on its own initiative.
+ *
+ * WHY THIS FILE EXISTS. The pipe was already built - `subagents.ts` spawns a child and streams it,
+ * `subagent-runs.ts` records and publishes it, and a human can already press a button to use it. What
+ * was missing is the mouth: a primary agent had no way to reach any of it, so the ONLY way to use a
+ * sub-agent was for a person to type into a form. This module is the policy half of that mouth - the
+ * rules about WHO may dispatch, HOW DEEP, and WITH WHICH TOOLS - and it holds no I/O at all, so every
+ * rule here can be proved without spawning a process.
+ *
+ * WHAT IS BORROWED FROM OPENCODE, and what is not:
+ *
+ * - `tool/task.ts:104-117` - the depth walk and `depth >= subagent_depth` refusal. OpenCode counts
+ *   depth by walking session parents; Super Pi has one level of session, so depth is a number the
+ *   caller states and the server checks (see `checkSubagentDepth`).
+ * - `tool/task.ts:64-79` - the `<task id state><task_result>` envelope. Rendered on the EXTENSION side
+ *   (`agents/super-pi-task/core.ts`), because that is the tool's return value, not the server's.
+ * - `agent/subagent-permissions.ts:21-23` - a child inherits the parent's DENY rules. Note what that
+ *   file does NOT do: it never intersects the parent's ALLOWLIST into the child, because "the parent
+ *   agent's restrictions govern that agent" (its own header). Super Pi follows the same rule - see
+ *   `parentDeniedTools`.
+ * - `tool/registry.ts:265-278` - the roster injected into the model's view of the tool. Built here
+ *   from `readAgents`, injected through the environment, rendered by the extension.
+ */
+/** The name the model calls. Also the key Pi's tool allowlist matches on, and the deny key in `tools:`. */
+export declare const TASK_TOOL_NAME = "task";
+/**
+ * How many task hops are allowed below a primary agent.
+ *
+ * `1` means: a primary agent may dispatch a sub-agent, and that sub-agent may not dispatch anything.
+ * OpenCode's default is the same number (`task.ts:111`, `cfg.subagent_depth ?? 1`).
+ *
+ * WHY THE NUMBER IS NOT A LOOP WALK. OpenCode counts session parents because it runs the child as a
+ * session inside the same process. Super Pi runs the child as a SEPARATE Pi process
+ * (`subagents.ts`, research note 3), so a child has no parent session to walk. It is enforced three
+ * other ways instead, and this constant is the belt to those braces:
+ *
+ * 1. STRUCTURAL - only `PiRpcRuntime` passes `--extension`, and only the primary agent runs through
+ *    `PiRpcRuntime`. A child's argv never names the extension, so the child has no `task` tool at all.
+ * 2. ALLOWLIST - `toolFlags` adds `task` to the primary's `--tools` list and to nothing else's, so even
+ *    an agent that loads the extension cannot be handed the tool by inheritance.
+ * 3. DECLARED - `checkSubagentDepth` refuses a request that says it is already nested.
+ *
+ * All three agree, and (1) is the one that actually holds. Raising this constant alone would change
+ * nothing, which is deliberate: the constant is the server's statement of intent, and the wiring is
+ * the enforcement.
+ */
+export declare const DEFAULT_SUBAGENT_DEPTH = 1;
+/**
+ * The environment contract between the server and the Pi child that carries the extension.
+ *
+ * These four names are a WIRE between two files that live in the same repository and are loaded by two
+ * different module systems, so they are written out on both sides rather than imported. The extension
+ * side is `agents/super-pi-task/core.ts`; `scripts/task-tool.test.mjs` asserts the two copies agree,
+ * because a rename on one side would otherwise fail at dispatch time with a message no one reads.
+ */
+export declare const TASK_ENDPOINT_ENV = "SUPER_PI_TASK_ENDPOINT";
+/** JSON roster, read from `readAgents(dir, { mode: "subagent" })` at SPAWN time - never hardcoded. */
+export declare const TASK_ROSTER_ENV = "SUPER_PI_TASK_ROSTER";
+/** The conversation the dispatch belongs to. The server resolves the workspace from this itself. */
+export declare const TASK_CONVERSATION_ENV = "SUPER_PI_TASK_CONVERSATION";
+/** How many task hops deep this process already is. A primary is `0`. See `DEFAULT_SUBAGENT_DEPTH`. */
+export declare const TASK_DEPTH_ENV = "SUPER_PI_TASK_DEPTH";
+/**
+ * One entry of the roster the model is shown: what it types into `subagent_type`, and when to pick it.
+ *
+ * `id` is the `subagent_type` value, NOT `name`. `name` is a label a human reads; requiring the model
+ * to reproduce a Chinese label exactly would be a transcription task before it could do any work.
+ */
+export type SubagentRosterEntry = {
+    id: string;
+    name: string;
+    description: string;
+};
+/**
+ * The dispatchable roster, in the order it will be injected.
+ *
+ * `hidden` definitions are excluded, matching `readAgentCatalog`: a sub-agent marked hidden is
+ * documented as not for automatic dispatch, and the model's only channel for dispatching IS automatic.
+ * The sort is the one `readAgents` already applied, kept rather than re-sorted so the injected list
+ * reads the same way as the picker.
+ */
+export declare function subagentRoster(agents: AgentDefinition[]): SubagentRosterEntry[];
+/**
+ * The roster as one environment variable's worth of JSON.
+ *
+ * A CHILD PROCESS ENVIRONMENT IS NOT A CONFIG FILE. On Windows the whole environment block is capped at
+ * 32,768 characters, and a server that would spawn a primary Pi successfully and then fail to spawn
+ * one a moment later because a directory of agents grew would be a fault with no visible cause. So the
+ * payload is truncated at a budget that leaves the rest of the block alone, and the truncation is
+ * announced rather than silent: the injected list ends with a line saying it was cut short, because a
+ * roster that quietly omits an agent is a roster that makes the model pick wrongly with no way to know.
+ */
+export declare const ROSTER_ENV_BUDGET = 12000;
+export declare function rosterPayload(agents: AgentDefinition[]): string;
+/** Reads a roster back out of an environment value. Anything unreadable is an empty roster, never a throw. */
+export declare function parseRoster(raw: string | undefined): SubagentRosterEntry[];
+/**
+ * Refuses a dispatch that claims to be nested deeper than this install allows.
+ *
+ * `depth` is how many task hops the CALLER already is: a primary agent's extension is `0`, and anything
+ * that dispatched from inside a sub-agent would be `1` or more. `>=` rather than `>` is OpenCode's
+ * comparison (`task.ts:111`) and it is what makes the default mean "one layer of children".
+ *
+ * The message is the deliverable as much as the refusal is. It arrives as the tool's error text and is
+ * therefore read by a MODEL that is about to retry, so it names the number, says what to do about it,
+ * and does not say "invalid request".
+ */
+export declare function checkSubagentDepth(depth: number, maxDepth?: number): void;
+/**
+ * The tools a parent agent's own definition DENIES, as concrete Pi tool names.
+ *
+ * ONLY denies, never an allowlist - the same rule as OpenCode's `deriveSubagentSessionPermission`, whose
+ * header states why: "Parent agent restrictions only govern that agent; the subagent's own permissions
+ * determine its capabilities." A parent that narrowed itself to `{read}` has not expressed "everything
+ * else is forbidden everywhere", and copying that into every child would silently strip a child of the
+ * write tools its own author gave it.
+ *
+ * Read out of `toolFlags` rather than a kept copy of the raw frontmatter because `toolFlags` IS the
+ * translated decision: `{"bash": false}` has already become `--exclude-tools bash` by the time a
+ * definition exists, and re-deriving it from the map would be a second implementation of the
+ * translation rather than a reader of the first.
+ */
+export declare function parentDeniedTools(parent: AgentDefinition | undefined): string[];
+/**
+ * The name the model calls. OpenCode's name, kept: a model trained on OpenCode's tool set reaches for
+ * `todowrite` and not `todo`, and there is nothing to gain from renaming a tool whose description has
+ * already been written to explain that name.
+ */
+export declare const TODO_TOOL_NAME = "todowrite";
+/**
+ * The endpoint the `todowrite` extension dials. A FIFTH name in the same wire as the four above, written
+ * out on both sides for the same reason: `agents/super-pi-task/core.ts` is loaded by Pi's module loader
+ * and `src/server/task-tool.ts` by tsc, so a relative import across the two would resolve differently
+ * under each. `scripts/todo-tool.test.mjs` asserts the two copies agree.
+ *
+ * It is a SEPARATE variable rather than a path derived from `TASK_ENDPOINT_ENV` because a Pi can
+ * legitimately be started with a task endpoint and no todo endpoint - a test harness, a checkout from
+ * before this tool existed - and a derived path could not tell that apart from a misconfiguration. The
+ * tool then refuses in words instead of posting somewhere that does not exist.
+ */
+export declare const TODO_ENDPOINT_ENV = "SUPER_PI_TODO_ENDPOINT";
+/**
+ * How many todos may be stored, and how long one may be.
+ *
+ * NOT A LIMIT OPENCODE HAS, and the reason it exists here is specific to this app: `state.json` is
+ * serialized on EVERY broadcast - every text delta of every turn - and `snapshot()` is a structuredClone
+ * of the whole state per connected browser. An unbounded list written by a model in a loop is therefore
+ * not just a large file, it is a large file re-serialized thousands of times within one turn. Fifty items
+ * is more than a plan of any real size and 400 characters is more than a sidebar row shows before it
+ * truncates, so neither bound is one a person would notice being reached.
+ *
+ * Over the cap is TRUNCATED, not refused. The model is mid-task and its call was correct in kind;
+ * refusing would produce an error envelope about a limit it cannot reason about, while a truncated list
+ * still shows the first fifty steps and the call still succeeds. `dropped` travels back to the caller so
+ * the model is told rather than left to notice.
+ */
+export declare const TODO_MAX_ITEMS = 50;
+export declare const TODO_MAX_CONTENT = 400;
+/**
+ * What a `todowrite` body is allowed to become.
+ *
+ * Every field is checked because every field is rendered: `content` is the row a person reads, `status`
+ * chooses that row's colour and glyph, and `priority` is its badge. A list read straight out of
+ * `JSON.parse` would put `undefined` into all three, and a status of `"banana"` would fall through every
+ * colour rule in `styles.css` and render like a completed item - because "is this the completed style"
+ * is asked with `===`, and anything unknown is not it.
+ *
+ * THE FOUR RULES, and what each failure would cost:
+ *
+ * - A non-string or blank `content` is DROPPED. There is no safe default text: a row that says nothing is
+ *   a row the user cannot act on, and it also consumes a slot of the cap below.
+ * - An unknown `status` becomes `pending`, neither dropped nor thrown on. Dropping loses work the model is
+ *   about to do and throwing fails a call that was otherwise correct; `pending` is the state that claims
+ *   the least, so the row is visible and slightly wrong rather than invisible.
+ * - An unknown `priority` DELETES the key. Absent is a real state here - the badge is simply not drawn -
+ *   so there is nothing to repair, and inventing `"medium"` would put a badge on a row that never asked.
+ * - A missing `id` is FILLED IN, and an existing one is KEPT rather than regenerated, so the sidebar's
+ *   React keys stay stable and a status change does not remount the row it changed. Two identical lines
+ *   of text without ids would share one key, and React would reuse the first row's DOM for the second.
+ */
+export declare function normalizeTodos(raw: unknown): {
+    todos: TodoItem[];
+    dropped: number;
+};
+/**
+ * The sentence the model reads back, which is also what the sidebar's header says.
+ *
+ * OpenCode's title for this tool is `${n} todos` where n counts what is NOT completed
+ * (`tool/todo.ts:37`), and that number is kept - but alone it lies at the end of a task: "3 todos" after
+ * the only three steps are done reads as three things still owed. So the completed count is in the
+ * sentence too, and derived HERE rather than in the sidebar, so the tool's own answer and the sidebar's
+ * header are computed from the same stored list and cannot disagree.
+ */
+export declare function todoSummary(todos: readonly TodoItem[]): string;

package/dist/server/task-tool.js

@@ -0,0 +1,285 @@
+/**
+ * The `task` tool: how a primary agent hands work to a sub-agent on its own initiative.
+ *
+ * WHY THIS FILE EXISTS. The pipe was already built - `subagents.ts` spawns a child and streams it,
+ * `subagent-runs.ts` records and publishes it, and a human can already press a button to use it. What
+ * was missing is the mouth: a primary agent had no way to reach any of it, so the ONLY way to use a
+ * sub-agent was for a person to type into a form. This module is the policy half of that mouth - the
+ * rules about WHO may dispatch, HOW DEEP, and WITH WHICH TOOLS - and it holds no I/O at all, so every
+ * rule here can be proved without spawning a process.
+ *
+ * WHAT IS BORROWED FROM OPENCODE, and what is not:
+ *
+ * - `tool/task.ts:104-117` - the depth walk and `depth >= subagent_depth` refusal. OpenCode counts
+ *   depth by walking session parents; Super Pi has one level of session, so depth is a number the
+ *   caller states and the server checks (see `checkSubagentDepth`).
+ * - `tool/task.ts:64-79` - the `<task id state><task_result>` envelope. Rendered on the EXTENSION side
+ *   (`agents/super-pi-task/core.ts`), because that is the tool's return value, not the server's.
+ * - `agent/subagent-permissions.ts:21-23` - a child inherits the parent's DENY rules. Note what that
+ *   file does NOT do: it never intersects the parent's ALLOWLIST into the child, because "the parent
+ *   agent's restrictions govern that agent" (its own header). Super Pi follows the same rule - see
+ *   `parentDeniedTools`.
+ * - `tool/registry.ts:265-278` - the roster injected into the model's view of the tool. Built here
+ *   from `readAgents`, injected through the environment, rendered by the extension.
+ */
+/** The name the model calls. Also the key Pi's tool allowlist matches on, and the deny key in `tools:`. */
+export const TASK_TOOL_NAME = "task";
+/**
+ * How many task hops are allowed below a primary agent.
+ *
+ * `1` means: a primary agent may dispatch a sub-agent, and that sub-agent may not dispatch anything.
+ * OpenCode's default is the same number (`task.ts:111`, `cfg.subagent_depth ?? 1`).
+ *
+ * WHY THE NUMBER IS NOT A LOOP WALK. OpenCode counts session parents because it runs the child as a
+ * session inside the same process. Super Pi runs the child as a SEPARATE Pi process
+ * (`subagents.ts`, research note 3), so a child has no parent session to walk. It is enforced three
+ * other ways instead, and this constant is the belt to those braces:
+ *
+ * 1. STRUCTURAL - only `PiRpcRuntime` passes `--extension`, and only the primary agent runs through
+ *    `PiRpcRuntime`. A child's argv never names the extension, so the child has no `task` tool at all.
+ * 2. ALLOWLIST - `toolFlags` adds `task` to the primary's `--tools` list and to nothing else's, so even
+ *    an agent that loads the extension cannot be handed the tool by inheritance.
+ * 3. DECLARED - `checkSubagentDepth` refuses a request that says it is already nested.
+ *
+ * All three agree, and (1) is the one that actually holds. Raising this constant alone would change
+ * nothing, which is deliberate: the constant is the server's statement of intent, and the wiring is
+ * the enforcement.
+ */
+export const DEFAULT_SUBAGENT_DEPTH = 1;
+/**
+ * The environment contract between the server and the Pi child that carries the extension.
+ *
+ * These four names are a WIRE between two files that live in the same repository and are loaded by two
+ * different module systems, so they are written out on both sides rather than imported. The extension
+ * side is `agents/super-pi-task/core.ts`; `scripts/task-tool.test.mjs` asserts the two copies agree,
+ * because a rename on one side would otherwise fail at dispatch time with a message no one reads.
+ */
+export const TASK_ENDPOINT_ENV = "SUPER_PI_TASK_ENDPOINT";
+/** JSON roster, read from `readAgents(dir, { mode: "subagent" })` at SPAWN time - never hardcoded. */
+export const TASK_ROSTER_ENV = "SUPER_PI_TASK_ROSTER";
+/** The conversation the dispatch belongs to. The server resolves the workspace from this itself. */
+export const TASK_CONVERSATION_ENV = "SUPER_PI_TASK_CONVERSATION";
+/** How many task hops deep this process already is. A primary is `0`. See `DEFAULT_SUBAGENT_DEPTH`. */
+export const TASK_DEPTH_ENV = "SUPER_PI_TASK_DEPTH";
+/**
+ * The dispatchable roster, in the order it will be injected.
+ *
+ * `hidden` definitions are excluded, matching `readAgentCatalog`: a sub-agent marked hidden is
+ * documented as not for automatic dispatch, and the model's only channel for dispatching IS automatic.
+ * The sort is the one `readAgents` already applied, kept rather than re-sorted so the injected list
+ * reads the same way as the picker.
+ */
+export function subagentRoster(agents) {
+    return agents
+        .filter((agent) => agent.mode === "subagent" && !agent.hidden)
+        .map((agent) => ({ id: agent.id, name: agent.name, description: agent.description }));
+}
+/**
+ * The roster as one environment variable's worth of JSON.
+ *
+ * A CHILD PROCESS ENVIRONMENT IS NOT A CONFIG FILE. On Windows the whole environment block is capped at
+ * 32,768 characters, and a server that would spawn a primary Pi successfully and then fail to spawn
+ * one a moment later because a directory of agents grew would be a fault with no visible cause. So the
+ * payload is truncated at a budget that leaves the rest of the block alone, and the truncation is
+ * announced rather than silent: the injected list ends with a line saying it was cut short, because a
+ * roster that quietly omits an agent is a roster that makes the model pick wrongly with no way to know.
+ */
+export const ROSTER_ENV_BUDGET = 12_000;
+export function rosterPayload(agents) {
+    const roster = subagentRoster(agents);
+    const json = JSON.stringify(roster);
+    if (json.length <= ROSTER_ENV_BUDGET)
+        return json;
+    const kept = [];
+    let used = 2;
+    for (const entry of roster) {
+        const size = JSON.stringify(entry).length + 1;
+        if (used + size > ROSTER_ENV_BUDGET - 160)
+            break;
+        kept.push(entry);
+        used += size;
+    }
+    return JSON.stringify([...kept, { id: "__truncated__", name: "(名单过长已截断)", description: `There were ${roster.length} sub-agents and only ${kept.length} fit into this session's environment; the rest were dropped rather than risk failing to start Pi.` }]);
+}
+/** Reads a roster back out of an environment value. Anything unreadable is an empty roster, never a throw. */
+export function parseRoster(raw) {
+    if (!raw)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    return parsed.filter((entry) => typeof entry === "object" && entry !== null &&
+        typeof entry.id === "string" && entry.id !== "" &&
+        typeof entry.description === "string");
+}
+/**
+ * Refuses a dispatch that claims to be nested deeper than this install allows.
+ *
+ * `depth` is how many task hops the CALLER already is: a primary agent's extension is `0`, and anything
+ * that dispatched from inside a sub-agent would be `1` or more. `>=` rather than `>` is OpenCode's
+ * comparison (`task.ts:111`) and it is what makes the default mean "one layer of children".
+ *
+ * The message is the deliverable as much as the refusal is. It arrives as the tool's error text and is
+ * therefore read by a MODEL that is about to retry, so it names the number, says what to do about it,
+ * and does not say "invalid request".
+ */
+export function checkSubagentDepth(depth, maxDepth = DEFAULT_SUBAGENT_DEPTH) {
+    if (Number.isFinite(depth) && depth < maxDepth)
+        return;
+    throw new Error(`Subagent depth limit reached (${maxDepth}). This agent is already running as a sub-agent, and a sub-agent may not dispatch another one. Ask whoever is driving the primary agent to make the call instead, or raise the limit deliberately if this really needs to nest.`);
+}
+/**
+ * The tools a parent agent's own definition DENIES, as concrete Pi tool names.
+ *
+ * ONLY denies, never an allowlist - the same rule as OpenCode's `deriveSubagentSessionPermission`, whose
+ * header states why: "Parent agent restrictions only govern that agent; the subagent's own permissions
+ * determine its capabilities." A parent that narrowed itself to `{read}` has not expressed "everything
+ * else is forbidden everywhere", and copying that into every child would silently strip a child of the
+ * write tools its own author gave it.
+ *
+ * Read out of `toolFlags` rather than a kept copy of the raw frontmatter because `toolFlags` IS the
+ * translated decision: `{"bash": false}` has already become `--exclude-tools bash` by the time a
+ * definition exists, and re-deriving it from the map would be a second implementation of the
+ * translation rather than a reader of the first.
+ */
+export function parentDeniedTools(parent) {
+    if (!parent)
+        return [];
+    const index = parent.toolFlags.indexOf("--exclude-tools");
+    if (index < 0)
+        return [];
+    const value = parent.toolFlags[index + 1];
+    return value ? value.split(",").map((name) => name.trim()).filter((name) => name !== "") : [];
+}
+// ---------------------------------------------------------------------------------------------
+// The `todowrite` tool: the model's own task list, which the right sidebar renders.
+//
+// WHAT IS BORROWED FROM OPENCODE, and what is not:
+//
+// - `tool/todo.ts` is 46 lines and almost all of it is Effect plumbing: a schema, an `ask()` for the
+//   `todowrite` permission, and a call into a per-session store. What survives the port is the two
+//   decisions that file makes - the tool's OUTPUT is the whole list as JSON (so the model's next turn
+//   reads the current plan back out of its own history rather than out of a UI), and the tool is
+//   REGISTERED per session rather than globally.
+// - `tool/todowrite.txt` is the description, and it is ported nearly verbatim (see
+//   `agents/super-pi-task/core.ts`). The "Use proactively when" list IS the mechanism: OpenCode never
+//   injects the todo list into a system prompt, so the trigger rules in the description are the only
+//   thing that makes a model update the list unprompted, and they are therefore not paraphrased here.
+// - OpenCode's `session/todo.ts` keys the list by session. Super Pi has one list, not one per
+//   conversation, because `AppState.todos` is a single array - see the note on `TodoItem` for what that
+//   costs and why it is not solved in this file.
+//
+// WHAT IS ADDED, and why it is here rather than in the extension: TRUST BOUNDARY. Everything in this
+// section runs on data that arrived over HTTP from a process the model controls the inputs of. The
+// extension cannot import this file (Pi hands extensions a different module system - see
+// `agents/super-pi-task/index.ts`), so if the rules lived there the server would be validating a list it
+// never checked, and `state.json` would carry whatever the model happened to send.
+/**
+ * The name the model calls. OpenCode's name, kept: a model trained on OpenCode's tool set reaches for
+ * `todowrite` and not `todo`, and there is nothing to gain from renaming a tool whose description has
+ * already been written to explain that name.
+ */
+export const TODO_TOOL_NAME = "todowrite";
+/**
+ * The endpoint the `todowrite` extension dials. A FIFTH name in the same wire as the four above, written
+ * out on both sides for the same reason: `agents/super-pi-task/core.ts` is loaded by Pi's module loader
+ * and `src/server/task-tool.ts` by tsc, so a relative import across the two would resolve differently
+ * under each. `scripts/todo-tool.test.mjs` asserts the two copies agree.
+ *
+ * It is a SEPARATE variable rather than a path derived from `TASK_ENDPOINT_ENV` because a Pi can
+ * legitimately be started with a task endpoint and no todo endpoint - a test harness, a checkout from
+ * before this tool existed - and a derived path could not tell that apart from a misconfiguration. The
+ * tool then refuses in words instead of posting somewhere that does not exist.
+ */
+export const TODO_ENDPOINT_ENV = "SUPER_PI_TODO_ENDPOINT";
+/**
+ * How many todos may be stored, and how long one may be.
+ *
+ * NOT A LIMIT OPENCODE HAS, and the reason it exists here is specific to this app: `state.json` is
+ * serialized on EVERY broadcast - every text delta of every turn - and `snapshot()` is a structuredClone
+ * of the whole state per connected browser. An unbounded list written by a model in a loop is therefore
+ * not just a large file, it is a large file re-serialized thousands of times within one turn. Fifty items
+ * is more than a plan of any real size and 400 characters is more than a sidebar row shows before it
+ * truncates, so neither bound is one a person would notice being reached.
+ *
+ * Over the cap is TRUNCATED, not refused. The model is mid-task and its call was correct in kind;
+ * refusing would produce an error envelope about a limit it cannot reason about, while a truncated list
+ * still shows the first fifty steps and the call still succeeds. `dropped` travels back to the caller so
+ * the model is told rather than left to notice.
+ */
+export const TODO_MAX_ITEMS = 50;
+export const TODO_MAX_CONTENT = 400;
+/**
+ * What a `todowrite` body is allowed to become.
+ *
+ * Every field is checked because every field is rendered: `content` is the row a person reads, `status`
+ * chooses that row's colour and glyph, and `priority` is its badge. A list read straight out of
+ * `JSON.parse` would put `undefined` into all three, and a status of `"banana"` would fall through every
+ * colour rule in `styles.css` and render like a completed item - because "is this the completed style"
+ * is asked with `===`, and anything unknown is not it.
+ *
+ * THE FOUR RULES, and what each failure would cost:
+ *
+ * - A non-string or blank `content` is DROPPED. There is no safe default text: a row that says nothing is
+ *   a row the user cannot act on, and it also consumes a slot of the cap below.
+ * - An unknown `status` becomes `pending`, neither dropped nor thrown on. Dropping loses work the model is
+ *   about to do and throwing fails a call that was otherwise correct; `pending` is the state that claims
+ *   the least, so the row is visible and slightly wrong rather than invisible.
+ * - An unknown `priority` DELETES the key. Absent is a real state here - the badge is simply not drawn -
+ *   so there is nothing to repair, and inventing `"medium"` would put a badge on a row that never asked.
+ * - A missing `id` is FILLED IN, and an existing one is KEPT rather than regenerated, so the sidebar's
+ *   React keys stay stable and a status change does not remount the row it changed. Two identical lines
+ *   of text without ids would share one key, and React would reuse the first row's DOM for the second.
+ */
+export function normalizeTodos(raw) {
+    if (!Array.isArray(raw))
+        return { todos: [], dropped: 0 };
+    const statuses = new Set(["pending", "in_progress", "completed"]);
+    const priorities = new Set(["high", "medium", "low"]);
+    const todos = [];
+    let dropped = 0;
+    for (const entry of raw) {
+        if (todos.length >= TODO_MAX_ITEMS) {
+            dropped++;
+            continue;
+        }
+        if (typeof entry !== "object" || entry === null) {
+            dropped++;
+            continue;
+        }
+        const item = entry;
+        const content = typeof item.content === "string" ? item.content.trim().slice(0, TODO_MAX_CONTENT) : "";
+        if (!content) {
+            dropped++;
+            continue;
+        }
+        const status = typeof item.status === "string" && statuses.has(item.status) ? item.status : "pending";
+        const priority = typeof item.priority === "string" && priorities.has(item.priority) ? item.priority : undefined;
+        const id = typeof item.id === "string" && item.id.trim() ? item.id.trim() : `todo_${crypto.randomUUID()}`;
+        todos.push({ id, content, status, ...(priority ? { priority } : {}) });
+    }
+    return { todos, dropped };
+}
+/**
+ * The sentence the model reads back, which is also what the sidebar's header says.
+ *
+ * OpenCode's title for this tool is `${n} todos` where n counts what is NOT completed
+ * (`tool/todo.ts:37`), and that number is kept - but alone it lies at the end of a task: "3 todos" after
+ * the only three steps are done reads as three things still owed. So the completed count is in the
+ * sentence too, and derived HERE rather than in the sidebar, so the tool's own answer and the sidebar's
+ * header are computed from the same stored list and cannot disagree.
+ */
+export function todoSummary(todos) {
+    const open = todos.filter((todo) => todo.status !== "completed").length;
+    if (!todos.length)
+        return "0 个待办任务";
+    if (!open)
+        return `全部完成：${todos.length} 个待办任务`;
+    return `${open} 个待办未完成，共 ${todos.length} 个`;
+}

package/dist/server/tool-calls.d.ts

@@ -0,0 +1,62 @@
+import type { ToolCallArg } from "./types.js";
+/**
+ * Turning one Pi tool call into something a human reads, and nothing more.
+ *
+ * WHY THIS IS ITS OWN MODULE. Two drain loops need exactly this derivation - the sub-agent supervisor
+ * (`subagents.ts`) and the PRIMARY agent's runtime (`runtime.ts`) - and `subagents.ts` already imports
+ * `runtime.ts` for `RpcChannel`, so the reverse import would be a cycle. One definition of "what does
+ * this call show" therefore has to live below both of them, or the two surfaces would drift: a `read`
+ * labelled by its path on a card and by its working directory on a call block is worse than either.
+ *
+ * The rule the whole module exists to enforce: DERIVED AND BOUNDED, NEVER COPIED. What Pi sends in
+ * `args` is an arbitrary object that may hold a file's contents, a multi-kilobyte patch or an entire
+ * shell script. What leaves here is short strings with a hard character cap, or a bare type word.
+ */
+/**
+ * The longest label one tool call may contribute. See `SubagentToolCall.detail` and `ToolCallBlock.detail`
+ * for why the argument is summarised rather than carried: the cap is what makes the bound structural
+ * instead of aspirational, because nothing downstream can grow past it.
+ */
+export declare const TOOL_DETAIL_CAP = 120;
+/**
+ * How many parameters one call block may list.
+ *
+ * A bound on the COUNT as well as on each value, for the same reason `TOOL_DETAIL_CAP` exists: without
+ * it, a tool that Pi sends a dozen arguments to would put twelve rows - and twelve times the cap - into a
+ * field that is rewritten on every text delta of the message it belongs to. Six covers every call shape
+ * this project has seen (`read`'s path/offset/limit, `bash`'s command/description/timeout) and truncating
+ * past it is announced by the caller through the row count rather than silently.
+ */
+export declare const TOOL_ARG_CAP = 6;
+/**
+ * The one line that tells a reader what a tool call was FOR: the file it opened, the pattern it searched
+ * for, the command it ran.
+ *
+ * Returns `undefined` rather than a placeholder when nothing is recognised, so a row omits the column
+ * instead of rendering a column of emptiness.
+ *
+ * Exported so the mapping can be asserted without spawning a child, which is the only way a table this
+ * shape can be regression-tested at all.
+ */
+export declare function describeToolCall(name: string, args: unknown): string | undefined;
+/**
+ * Every parameter of one call, as a bounded list of `key`/`value` pairs a block can show when expanded.
+ *
+ * THIS IS THE SAME LINE `describeToolCall` DRAWS, APPLIED PER KEY. `describeToolCall` answers "what was
+ * this aimed at" with one label; this answers "what was this given" with the whole bounded list, which is
+ * the difference between a row that says `bash` and a block that says which command, plus its timeout
+ * and description. Both are derived: a string is whitespace-collapsed and capped at `TOOL_DETAIL_CAP`, and
+ * anything that is not a string or a number or a boolean becomes a type word (see `describeShape`).
+ *
+ * Order is Pi's own key order rather than this module's table order, because once every key is listed the
+ * per-tool table has said everything it knows - and a reader scanning a list wants the order the caller
+ * wrote it in, not one this file invented.
+ *
+ * Capped at `TOOL_ARG_CAP` ENTRIES, and the cap is applied by taking the first N rather than by sampling
+ * across the object: a truncated tail is a prefix of the real argument list, so what is shown is never
+ * a selection that implies the omitted keys did not exist.
+ *
+ * Returns `undefined` when there is nothing readable at all, so a call with no usable arguments renders
+ * no parameter section rather than an empty one.
+ */
+export declare function describeToolCallArgs(args: unknown): ToolCallArg[] | undefined;