@evandu/super-pi 0.1.1 → 0.1.2

package/agents/super-pi-task/core.ts

@@ -1,485 +1,748 @@
-/**
- * The `task` and `todowrite` tools' whole behaviour, with no Pi import anywhere in this file.
- *
- * WHY IT IS SPLIT OUT. `index.ts` is the Pi adapter: TypeBox schemas and `registerTool` calls.
- * Everything with a decision in it lives here instead, because `index.ts` can only be loaded by Pi -
- * Pi hands extensions `@sinclair/typebox` as a VIRTUAL MODULE (extensions/virtual-modules.ts), so the
- * adapter is unimportable from an ordinary Node process and therefore untestable from one. A file that
- * can only be exercised by starting a real Pi with a real model behind it does not get tested; this one
- * is driven end to end against a real server from `scripts/task-tool.test.mjs` and
- * `scripts/todo-tool.test.mjs`.
- *
- * WHAT IS BORROWED FROM OPENCODE, and where:
- *
- * - `tool/task.txt` is the basis of `TASK_DESCRIPTION`, INCLUDING its "When NOT to use" list. That list
- *   is the part that matters: a delegation tool with no stated cost model gets used for a one-line
- *   search, and each such use is a whole second Pi process. The guidance is kept nearly verbatim and in
- *   its original order because it was written by someone who had watched that happen.
- * - `tool/task.ts:64-79` `renderOutput` is `renderTaskResult`, including the `task_result` /
- *   `task_error` tag switch, so the model sees the same envelope shape it would from OpenCode.
- * - `tool/registry.ts:265-278` `describeTask()` is `describeTask()`: the tool's own description is where
- *   the roster goes, rather than the system prompt, so the list is refreshed with the tools and cannot
- *   outlive a roster that has changed.
- * - `tool/todowrite.txt` is the basis of `TODO_DESCRIPTION`, INCLUDING its "Use proactively when" list -
- *   see the long note above `TODO_DESCRIPTION` for why that list is the mechanism and is not paraphrased.
- * - `tool/todo.ts` is the shape of `executeTodo`: write the list, echo it back as JSON.
- *
- * THE ONE DELIBERATE DEVIATION on `task`: OpenCode puts `description` to work as a session title. Super
- * Pi's sub-agent record has no title field, and adding one is a persisted-shape change this step does not
- * need, so `description` is carried into the `<summary>` line of the envelope instead. It is still
- * shown to the model, still 3-5 words, and the parameter still means what its schema says.
- */
-
-/**
- * The environment contract with the server. The SAME four names are declared in
- * `src/server/task-tool.ts`, which is the other end; the two are written out rather than imported
- * because this file is loaded by Pi's module loader and that one by tsc, and a relative import across
- * the two would resolve differently under each. `scripts/task-tool.test.mjs` asserts they agree.
- */
-export const TASK_TOOL_NAME = "task";
-export const TASK_ENDPOINT_ENV = "SUPER_PI_TASK_ENDPOINT";
-export const TASK_ROSTER_ENV = "SUPER_PI_TASK_ROSTER";
-export const TASK_CONVERSATION_ENV = "SUPER_PI_TASK_CONVERSATION";
-export const TASK_DEPTH_ENV = "SUPER_PI_TASK_DEPTH";
-
-/**
- * The `todowrite` extension's half of the same environment contract, declared here for the reason the
- * four above are. `src/server/task-tool.ts` is the other end; `scripts/todo-tool.test.mjs` asserts they
- * agree, because a rename on one side fails at call time with a message nothing reads.
- */
-export const TODO_ENDPOINT_ENV = "SUPER_PI_TODO_ENDPOINT";
-
-/** The name the model calls, and the key Pi's tool allowlist matches on. OpenCode's name, kept. */
-export const TODO_TOOL_NAME = "todowrite";
-
-/** The parameters, OpenCode's `tool/todo.ts:6-8` minus its schema wrapper. */
-export type TodoParams = { todos: TodoEntry[] };
-
-/** One entry as the model writes it. `id` is OURS (see `normalizeTodos`), so it is absent here. */
-export type TodoEntry = { content: string; status: "pending" | "in_progress" | "completed"; priority?: "high" | "medium" | "low" };
-
-/** The three statuses Super Pi renders, as the model writes them. */
-const TODO_STATUSES = new Set(["pending", "in_progress", "completed"]);
-
-/** The parameters, exactly OpenCode's (`tool/task.ts:43-52`) minus the ones this step does not do. */
-export type TaskParams = {
-  description: string;
-  prompt: string;
-  subagent_type: string;
-  task_id?: string;
-  background?: boolean;
-};
-
-/** One dispatchable sub-agent, as the server read it from `agents/*.md` at spawn time. */
-export type RosterEntry = { id: string; name: string; description: string };
-
-/**
- * Reads a roster back out of an environment value.
- *
- * Anything unreadable is an EMPTY roster rather than a throw. An extension that throws while loading
- * takes Pi's whole extension host down with it, and a malformed environment variable is a far smaller
- * fault than "the primary agent cannot delegate at all".
- */
-export function parseRoster(raw: string | undefined): RosterEntry[] {
-  if (!raw) return [];
-  let parsed: unknown;
-  try { parsed = JSON.parse(raw); } catch { return []; }
-  if (!Array.isArray(parsed)) return [];
-  return parsed.filter((entry): entry is RosterEntry =>
-    typeof entry === "object" && entry !== null &&
-    typeof (entry as RosterEntry).id === "string" && (entry as RosterEntry).id !== "" &&
-    typeof (entry as RosterEntry).description === "string");
-}
-
-/**
- * The model's half of the contract, and the part that decides whether the tool is used well.
- *
- * The first paragraph says what the tool IS in one sentence, because a tool description is read once
- * and acted on. The "When NOT to use" list is OpenCode's, kept in its order and for its stated reason.
- * The usage notes are OpenCode's too, with `background` dropped - there is no background mode, every
- * dispatch is foreground and blocking, and offering a note about a mode that does not exist would be a
- * lie that costs a retry.
- */
-export const TASK_DESCRIPTION = `Launch a subagent to handle a complex, multistep task autonomously.
-
-You must specify a subagent_type to select which subagent to use.
-
-When NOT to use this tool:
-- If you want to read a specific file path, use the Read or Glob tool instead, to find the match more quickly
-- If you are searching for a specific class definition like "class Foo", use the Grep tool instead, to find the match more quickly
-- If you are searching for code within a specific file or set of 2-3 files, use the Read tool instead, to find the match more quickly
-- If no available subagent is a good fit for the task, use other tools directly
-
-Usage notes:
-1. Every dispatch starts a SEPARATE agent process that runs until it finishes, so the cost of a delegation is minutes rather than seconds. Delegate work that is genuinely substantial; do not delegate a lookup you could do in one tool call.
-2. Once you have delegated work to a subagent, do not duplicate that work yourself. Continue with non-overlapping tasks, or wait for the result.
-3. When the subagent is done it returns ONE message back to you, wrapped in a <task> element. That result is not visible to the user: if it matters to the user, say so in your own reply.
-4. Each dispatch starts with a FRESH context. Your prompt is all the subagent will know, so it must contain the full task, and it must say exactly what you want back in its final message.
-5. Tell the subagent whether you expect it to WRITE CODE or only to RESEARCH (search, file reads, web fetches), and how to verify its work if it writes. It is not aware of the user's intent.
-6. If a subagent's description says it should be used proactively, use it without being asked.`;
-
-/**
- * The roster block, OpenCode's `describeTask()` reduced to its two jobs: the ids that are legal, and
- * when to pick each one.
- *
- * `id` is printed, not `name`. The model has to type `subagent_type` exactly, and requiring it to
- * reproduce a Chinese label as a machine token would be a transcription exercise in front of any actual
- * work. The human-readable `name` is printed alongside because the ids in this repository are English
- * file names while the roles are described in Chinese, and a model reading only `scout` learns less
- * from it than from both.
- *
- * THE EMPTY CASE IS SPOKEN, NOT SILENT. With no sub-agents the tool still exists - Pi has already
- * declared it - so a description that just ended after the guidance would leave the model to guess
- * whether an empty roster is a bug or a fact about this install. It says so explicitly and tells the
- * model to do the work itself, which is the only correct action in that state.
- */
-export function rosterSection(roster: readonly RosterEntry[]): string {
-  if (!roster.length) {
-    return "\n\nAvailable subagent types: NONE. This install has no agents/*.md file with `mode: subagent`, so there is nobody to delegate to. Do not call this tool - do the work yourself with your other tools, and mention that no sub-agents are configured if the user asked for delegation.";
-  }
-  const lines = roster.map((entry) => `- ${entry.id} (${entry.name}): ${entry.description || "No description was given for this subagent."}`);
-  return `\n\nAvailable subagent types and when to use each:\n${lines.join("\n")}`;
-}
-
-/** The full model-facing description: the guidance, then the live roster. OpenCode's `describeTask()`. */
-export function describeTask(roster: readonly RosterEntry[]): string {
-  return `${TASK_DESCRIPTION}${rosterSection(roster)}`;
-}
-
-/**
- * The envelope the model reads, OpenCode's `renderOutput` (`tool/task.ts:64-79`).
- *
- * `state` is one of three words and the tag follows from it, so a model can tell a finished answer from
- * a failure by the tag alone without parsing prose. Super Pi's own run statuses (`stopped`, `failed`)
- * are folded into `error` here rather than passed through: `stopped` and `failed` are distinctions
- * Super Pi's UI needs and the model has no use for, and adding a fourth `state` value would break any
- * consumer expecting OpenCode's three.
- *
- * The child's text goes in verbatim. Trimming or wrapping it would mean the model receives something the
- * sub-agent did not say, which is the one transformation that cannot be undone by reading the record.
- */
-export function renderTaskResult(input: { id: string; state: "completed" | "error"; summary?: string; text: string }): string {
-  const tag = input.state === "error" ? "task_error" : "task_result";
-  return [
-    `<task id="${input.id}" state="${input.state}">`,
-    ...(input.summary ? [`<summary>${input.summary}</summary>`] : []),
-    `<${tag}>`,
-    input.text,
-    `</${tag}>`,
-    "</task>",
-  ].join("\n");
-}
-
-/** What the extension learns from its own environment before it can dispatch anything. */
-export type TaskToolConfig = {
-  endpoint: string;
-  conversationId: string;
-  depth: number;
-  roster: RosterEntry[];
-  /** The server's bearer token, when one is configured. Absent means the server runs open on loopback. */
-  token?: string;
-};
-
-export function readTaskConfig(env: Record<string, string | undefined>): TaskToolConfig {
-  const depth = Number.parseInt(env[TASK_DEPTH_ENV] ?? "0", 10);
-  const token = env.SUPER_PI_ACCESS_TOKEN;
-  return {
-    endpoint: env[TASK_ENDPOINT_ENV] ?? "",
-    conversationId: env[TASK_CONVERSATION_ENV] ?? "",
-    // An unreadable depth is 0, the primary agent's own value, rather than a number that would claim to
-    // be nested and trip the server's refusal for a reason that has nothing to do with this call.
-    depth: Number.isFinite(depth) ? depth : 0,
-    roster: parseRoster(env[TASK_ROSTER_ENV]),
-    ...(token ? { token } : {}),
-  };
-}
-
-/** The context slice the tool needs, so this file does not depend on Pi's `ExtensionToolContext`. */
-export type TaskToolContext = { cwd: string };
-
-export type TaskToolResult = { content: { type: "text"; text: string }[]; details: unknown; isError?: boolean };
-
-/** One HTTP seam, injected so a test can drive the tool without a socket and production uses global fetch. */
-export type TaskFetch = (url: string, init: { method: string; headers: Record<string, string>; body: string; signal?: AbortSignal }) => Promise<{ ok: boolean; status: number; text(): Promise<string> }>;
-
-const globalFetch: TaskFetch = (url, init) => fetch(url, init as RequestInit);
-
-/**
- * Refuses a call that cannot possibly work, in words the model can act on.
- *
- * The three cases are separated because the MODEL's next move differs in each: an empty roster means use
- * your own tools, an unknown id means pick one of the listed ones, and a missing endpoint means this
- * session was not started by Super Pi at all and no retry will change that. A single generic "dispatch
- * failed" would leave a model that retries the same call three times.
- */
-export function refuseTask(config: TaskToolConfig, params: TaskParams): string | undefined {
-  if (!config.endpoint) return `The task tool is not available in this session: ${TASK_ENDPOINT_ENV} is not set, so there is no Super Pi server to dispatch to. Do the work yourself with your other tools.`;
-  if (!config.conversationId) return `The task tool is not available in this session: ${TASK_CONVERSATION_ENV} is not set, so this run cannot be attributed to a conversation. Do the work yourself with your other tools.`;
-  if (!config.roster.length) return "This install has no dispatchable sub-agents (no agents/*.md with `mode: subagent`), so there is nobody to delegate to. Do the work yourself with your other tools.";
-  if (!params.subagent_type.trim()) return `subagent_type is required. Available: ${config.roster.map((entry) => entry.id).join(", ")}.`;
-  if (!config.roster.some((entry) => entry.id === params.subagent_type)) return `${JSON.stringify(params.subagent_type)} is not a dispatchable subagent_type. Available: ${config.roster.map((entry) => entry.id).join(", ")}. Pick one of those, or do the work yourself.`;
-  if (!params.prompt.trim()) return "prompt is required and must not be empty: the sub-agent starts with a fresh context and your prompt is everything it will know.";
-  return undefined;
-}
-
-/**
- * Runs one dispatch and returns the envelope the model reads.
- *
- * Returns rather than throws for EVERY outcome, including a malformed request. Pi treats a thrown tool
- * error and an `isError` result almost identically, so this is not about Pi - it is that the model
- * should see ONE shape for "the delegation did not work", with the reason inside it, instead of a stack
- * trace for some failures and prose for others.
- *
- * The request carries a CONVERSATION, never a directory. The server resolves the workspace from its own
- * stored state; a model that could name its own `cwd` would name a directory it can write, which is the
- * entire boundary this endpoint exists to keep. That is why `context.cwd` is read here at all: only to
- * be left out of the request.
- */
-export async function executeTask(
-  params: TaskParams,
-  context: TaskToolContext,
-  config: TaskToolConfig,
-  deps: { signal?: AbortSignal; fetch?: TaskFetch } = {},
-): Promise<TaskToolResult> {
-  const text = (body: string, isError?: boolean): TaskToolResult => ({ content: [{ type: "text", text: body }], details: undefined, ...(isError ? { isError: true } : {}) });
-  const refusal = refuseTask(config, params);
-  if (refusal) return text(renderTaskResult({ id: "refused", state: "error", text: refusal }), true);
-
-  const send = deps.fetch ?? globalFetch;
-  let response: Awaited<ReturnType<TaskFetch>>;
-  try {
-    response = await send(config.endpoint, {
-      method: "POST",
-      // The bearer token is the SAME check every other endpoint on this server applies, and the server
-      // enforces it BEFORE the loopback test, so an extension that forgot it would get a bare 401.
-      headers: { "content-type": "application/json", ...(config.token ? { authorization: `Bearer ${config.token}` } : {}) },
-      body: JSON.stringify({
-        conversationId: config.conversationId,
-        subagent_type: params.subagent_type,
-        prompt: params.prompt,
-        description: params.description,
-        depth: config.depth,
-        background: params.background === true,
-      }),
-      ...(deps.signal ? { signal: deps.signal } : {}),
-    });
-  } catch (error) {
-    // A failed CONNECTION is worth distinguishing from a refused dispatch: nothing ran, and no run
-    // record exists, so telling the model to look at the run would send it looking for something that
-    // was never created.
-    return text(renderTaskResult({ id: "unreachable", state: "error", text: `Could not reach the Super Pi server at ${config.endpoint}: ${error instanceof Error ? error.message : "unknown error"}` }), true);
-  }
-
-  /** The server answers JSON; a body that is not JSON means a proxy or an error page, not a verdict. */
-  let payload: { run?: { id?: string; status?: string; agentId?: string }; output?: string; error?: string; outputTruncated?: boolean };
-  try { payload = JSON.parse(await response.text()) as typeof payload; }
-  catch { return text(renderTaskResult({ id: "unreadable", state: "error", text: `The dispatch endpoint answered ${response.status} with something that is not JSON, so its result cannot be read.` }), true); }
-
-  // No run id means nothing ran: either the server refused before spawning, or the body was unreadable.
-  // "refused" says so, where "unknown" would imply a run exists somewhere whose output is merely absent.
-  const id = payload.run?.id ?? "refused";
-  if (params.background === true && payload.run?.status === "running") {
-    return text(`<task id="${id}" state="running">\n<summary>${params.description.trim() || params.subagent_type}</summary>\n<task_result>The task is working in the background. You will be notified automatically when it finishes. Do not sleep, poll for progress, ask the task for status, or duplicate this task's work. Continue with non-overlapping work.</task_result>\n</task>`);
-  }
-  const completed = payload.run?.status === "completed";
-  const body = completed
-    ? payload.output ?? ""
-    : payload.error ?? `The sub-agent run finished as ${JSON.stringify(payload.run?.status ?? "unknown")} without saying why.`;
-  return text(
-    renderTaskResult({
-      id,
-      state: completed ? "completed" : "error",
-      summary: params.description.trim() ? `${params.description.trim()} (${params.subagent_type})` : `${params.subagent_type}`,
-      text: payload.outputTruncated && completed ? `${body}\n\n[This answer was truncated at 50 KB by the server; the full run is recorded in Super Pi.]` : body,
-    }),
-    !completed,
-  );
-}
-
-// ---------------------------------------------------------------------------------------------
-// The `todowrite` tool: a task list the model maintains itself, and a person watches from the sidebar.
-//
-// THIS IS A PORT OF OPENCODE'S `tool/todo.ts` + `tool/todowrite.txt`, and the two files are 46 lines and
-// 44 lines respectively - almost all of the first one Effect plumbing, and the whole of the second one
-// prose the model reads. Only the prose ports intact, and that is the point of this file.
-//
-// THE PROACTIVE TRIGGER IS THE DESCRIPTION, and nothing else. This is the part of OpenCode's design that
-// is easy to get wrong by looking for a mechanism that isn't there: OpenCode does NOT inject the todo
-// list into any system prompt, does NOT have a scheduler, and does NOT nudge. `session/todo.ts` is a
-// per-session table that a tool call writes, and the ONLY thing that makes a model call it on its own is
-// the "Use proactively when" list in `todowrite.txt` - specifically the two entries that fire on work
-// happening rather than on a question being asked:
-//
-//   - "You start a task - mark it `in_progress` (only one at a time) before working"
-//   - "You finish a task - mark it `completed` and add any follow-ups discovered during the work"
-//
-// Those two lines ARE the design. Everything else here - the endpoint, the store, the sidebar - is
-// plumbing that makes those two lines possible. So they are carried over in OpenCode's own order and
-// wording, and the test asserts the sentences are PRESENT rather than paraphrased, because a reworded
-// trigger is a trigger that fires less often and no test would notice except this one.
-//
-// WHAT CHANGES FROM OPENCODE, and why each change is forced rather than chosen:
-//
-// - `cancelled` is GONE from the States section. Super Pi's list is replaced whole on every call
-//   (`normalizeTodos` in src/server/task-tool.ts), so "no longer needed" is expressed by not sending the
-//   item. Keeping a fourth status would mean a state the model can set that nothing ever takes off the
-//   screen, which is a row that says it was cancelled forever.
-// - The permission gate is gone. OpenCode asks `ctx.ask({ permission: "todowrite", patterns: ["*"] })`
-//   before every write (`tool/todo.ts:24-29`) and denies the tool to sub-agents that lack the permission
-//   (`agent/subagent-permissions.ts:19-24`). Super Pi's server has one permission story and it is
-//   bearer-token plus loopback, not a per-tool prompt, and a tool whose every call raises a modal is a
-//   tool a model stops calling - which would break the proactive trigger this file exists to preserve.
-//   The endpoint's loopback-and-token guards are what stands in that place; they are noted in
-//   `refuseTodo` so the model knows the rule rather than guessing at it.
-// - The list is per-install, not per-session (`AppState.todos` is one array). Stated in the report rather
-//   than hidden: switching conversations shows the previous conversation's list until the model rewrites
-//   it. Making it per-conversation is a persisted-shape change and is out of this task's scope.
-//
-// THE OUTPUT IS THE SERVER'S LIST, NOT THE MODEL'S. OpenCode echoes its own input
-// (`tool/todo.ts:38`). This tool echoes what the server actually STORED, which differs whenever the
-// server dropped an empty item, truncated a long one or filled in a missing id - and echoing the stored
-// copy is what stops the model from believing a row was saved when it was not.
-
-/**
- * The model-facing description. OpenCode's `todowrite.txt`, ported.
- *
- * Kept in English for the same reason `TASK_DESCRIPTION` above is: it is read by a model, and the rest
- * of this extension's model-facing text is English, so a Chinese paragraph here would be the only Chinese
- * instruction in the tool set. The paragraphs a person reads (the sidebar) are the Chinese ones.
- *
- * The one ADDED paragraph is the third one. OpenCode never tells the model that anyone is watching - its
- * description is written entirely in the imperative voice of a task list. Super Pi's list is on screen in
- * a panel a user is looking at while the agent works, and that is the reason to maintain it in real time
- * rather than at the end, so the description says so. This is the piece Super Pi has that OpenCode does
- * not, and it is stated to the model as a fact about the world rather than as a request.
- */
-export const TODO_DESCRIPTION = `Create and maintain a structured task list for the current coding session. Tracks progress, organizes multi-step work, and surfaces status to the user.
-
-## When to use
-Use proactively when:
-- The task requires 3+ distinct steps or actions (not just 3 tool calls for a single conceptual step)
-- The work is non-trivial and benefits from planning
-- The user provides multiple tasks (numbered or comma-separated) or explicitly asks for a todo list
-- New instructions arrive - capture them as todos
-- You start a task - mark it \`in_progress\` (only one at a time) before working
-- You finish a task - mark it \`completed\` and add any follow-ups discovered during the work
-
-## When NOT to use
-Skip when:
-- The work is a single, straightforward task (or <3 trivial steps)
-- The request is purely informational or conversational
-- Tracking adds no organizational value
-
-## States
-- \`pending\` - not started
-- \`in_progress\` - actively working (exactly ONE at a time)
-- \`completed\` - finished successfully
-
-To drop an item that is no longer needed, leave it out of the next call entirely: this tool replaces the whole list, so an item you do not send is an item that disappears.
-
-## Rules
-- Update status in real time; don't batch completions
-- Mark \`completed\` only after the required work is actually done, including any required verification. Never based on intent.
-- Keep exactly one \`in_progress\` while work remains
-- If blocked or partial, keep it \`in_progress\` and add a follow-up todo describing the blocker
-- Preserve user-provided commands verbatim (flags, args, order)
-- Items should be specific and actionable; break large work into smaller steps
-
-## The user is watching this list
-This list is rendered live in a panel beside the conversation, so a stale row is visible to the person you are working for while you are still working. That is why the triggers above are about PROGRESS and not about questions: update the list when a task starts, when it finishes, and when you discover a new step - not when the user asks where you are.
-
-## Examples
-
-Use it:
-- "Add a dark mode toggle and run the tests" -> multi-step feature + explicit verification
-- "Rename getCwd -> getCurrentWorkingDirectory across the repo" -> grep reveals 15 occurrences in 8 files
-- "Implement registration, catalog, cart, checkout" -> multiple complex features
-
-Skip it:
-- "How do I print Hello World in Python?" -> informational
-- "Add a comment to calculateTotal" -> single edit
-- "Run npm install and tell me what happened" -> one command
-
-When in doubt, use it.`;
-
-export type TodoToolConfig = { endpoint: string; conversationId: string; token?: string };
-
-/** What the extension learns from its own environment before it can write anything. */
-export function readTodoConfig(env: Record<string, string | undefined>): TodoToolConfig {
-  const token = env.SUPER_PI_ACCESS_TOKEN;
-  return { endpoint: env[TODO_ENDPOINT_ENV] ?? "", conversationId: env[TASK_CONVERSATION_ENV] ?? "", ...(token ? { token } : {}) };
-}
-
-/**
- * Refuses a call that cannot work, in words the model can act on.
- *
- * The server is authoritative over what the list may contain (`normalizeTodos`), so this file does NOT
- * re-check `content` or `status` and deliberately does not reject a list it dislikes: a list with one bad
- * entry is better stored than refused, because a refusal loses the twenty good ones with it. What is
- * checked here is only the things that make the call impossible - the same three-case split `refuseTask`
- * uses, for the same reason.
- */
-export function refuseTodo(config: TodoToolConfig, params: TodoParams): string | undefined {
-  if (!config.endpoint) return `The todowrite tool is not available in this session: ${TODO_ENDPOINT_ENV} is not set, so there is no Super Pi server to write the list to. Keep working and describe your plan in prose instead.`;
-  if (!config.conversationId) return `The todowrite tool is not available in this session: ${TASK_CONVERSATION_ENV} is not set. Keep working and describe your plan in prose instead.`;
-  if (!Array.isArray(params.todos)) return "todowrite requires a `todos` array. Send the WHOLE list every time - this tool replaces the list rather than adding to it.";
-  return undefined;
-}
-
-/** One HTTP seam, injected so a test can drive the tool without a socket and production uses global fetch. */
-export type TodoFetch = (url: string, init: { method: string; headers: Record<string, string>; body: string; signal?: AbortSignal }) => Promise<{ ok: boolean; status: number; text(): Promise<string> }>;
-
-/**
- * Runs one write and returns what the model reads.
- *
- * Returns rather than throws for every outcome, for the reason `executeTask` does: the model should see
- * ONE shape for "the list was not written", with the reason inside it.
- *
- * THE RETURNED LIST IS THE SERVER'S, and this is the one place the port departs from OpenCode's behaviour
- * on purpose. The server is the only party that has validated, truncated and id-stamped what was stored,
- * so echoing its copy is what tells the model the truth; echoing the input instead (OpenCode,
- * `tool/todo.ts:38`) would let it believe a 40,000-character row survived when it was cut to 400. The
- * dropped count rides along in the sentence for the same reason - a silent truncation reads as success.
- */
-export async function executeTodo(
-  params: TodoParams,
-  config: TodoToolConfig,
-  deps: { signal?: AbortSignal; fetch?: TodoFetch } = {},
-): Promise<TaskToolResult> {
-  const text = (body: string, isError?: boolean): TaskToolResult => ({ content: [{ type: "text", text: body }], details: undefined, ...(isError ? { isError: true } : {}) });
-  const refusal = refuseTodo(config, params);
-  if (refusal) return text(refusal, true);
-
-  const send = deps.fetch ?? globalFetch;
-  let response: Awaited<ReturnType<TodoFetch>>;
-  try {
-    response = await send(config.endpoint, {
-      method: "POST",
-      headers: { "content-type": "application/json", ...(config.token ? { authorization: `Bearer ${config.token}` } : {}) },
-      // The CONVERSATION is named so the server can attribute the write, never a directory: the same
-      // boundary `executeTask` keeps, and for the same reason - a model that could name its own cwd could
-      // write outside the workspace this app exists to keep it inside.
-      body: JSON.stringify({ conversationId: config.conversationId, todos: params.todos }),
-      ...(deps.signal ? { signal: deps.signal } : {}),
-    });
-  } catch (error) {
-    return text(`Could not reach the Super Pi server at ${config.endpoint}: ${error instanceof Error ? error.message : "unknown error"}. The todo list was NOT saved - carry your plan in prose this turn and try again.`, true);
-  }
-
-  let payload: { todos?: TodoEntry[]; dropped?: number; error?: string };
-  try { payload = JSON.parse(await response.text()) as typeof payload; }
-  catch { return text(`The todo endpoint answered ${response.status} with something that is not JSON, so the list cannot be confirmed as saved. Treat it as unsaved and retry.`, true); }
-  if (!response.ok || !Array.isArray(payload.todos)) {
-    return text(payload.error ?? `The todo endpoint answered ${response.status} without saving the list. Treat it as unsaved and retry.`, true);
-  }
-
-  // Only statuses this file knows are echoed, and only because the server's validator already enforces
-  // them - this is a type narrowing for the renderer below, not a second validation pass.
-  const stored = payload.todos.filter((todo): todo is TodoEntry => Boolean(todo) && typeof todo.content === "string" && TODO_STATUSES.has(todo.status));
-  const open = stored.filter((todo) => todo.status !== "completed").length;
-  const summary = !stored.length ? "0 个待办任务" : !open ? `全部完成：${stored.length} 个待办任务` : `${open} 个待办未完成，共 ${stored.length} 个`;
-  const dropped = typeof payload.dropped === "number" && payload.dropped > 0
-    ? `\n\n[${payload.dropped} of the entries you sent were dropped or truncated by the server - they are NOT in the saved list. The saved list is the JSON below.]`
-    : "";
-  return text(`${summary}${dropped}\n\n${JSON.stringify(stored, null, 2)}`);
-}
+/**
+ * The `task` and `todowrite` tools' whole behaviour, with no Pi import anywhere in this file.
+ *
+ * WHY IT IS SPLIT OUT. `index.ts` is the Pi adapter: TypeBox schemas and `registerTool` calls.
+ * Everything with a decision in it lives here instead, because `index.ts` can only be loaded by Pi -
+ * Pi hands extensions `@sinclair/typebox` as a VIRTUAL MODULE (extensions/virtual-modules.ts), so the
+ * adapter is unimportable from an ordinary Node process and therefore untestable from one. A file that
+ * can only be exercised by starting a real Pi with a real model behind it does not get tested; this one
+ * is driven end to end against a real server from `scripts/task-tool.test.mjs` and
+ * `scripts/todo-tool.test.mjs`.
+ *
+ * WHAT IS BORROWED FROM OPENCODE, and where:
+ *
+ * - `tool/task.txt` is the basis of `TASK_DESCRIPTION`, INCLUDING its "When NOT to use" list. That list
+ *   is the part that matters: a delegation tool with no stated cost model gets used for a one-line
+ *   search, and each such use is a whole second Pi process. The guidance is kept nearly verbatim and in
+ *   its original order because it was written by someone who had watched that happen.
+ * - `tool/task.ts:64-79` `renderOutput` is `renderTaskResult`, including the `task_result` /
+ *   `task_error` tag switch, so the model sees the same envelope shape it would from OpenCode.
+ * - `tool/registry.ts:265-278` `describeTask()` is `describeTask()`: the tool's own description is where
+ *   the roster goes, rather than the system prompt, so the list is refreshed with the tools and cannot
+ *   outlive a roster that has changed.
+ * - `tool/todowrite.txt` is the basis of `TODO_DESCRIPTION`, INCLUDING its "Use proactively when" list -
+ *   see the long note above `TODO_DESCRIPTION` for why that list is the mechanism and is not paraphrased.
+ * - `tool/todo.ts` is the shape of `executeTodo`: write the list, echo it back as JSON.
+ *
+ * THE ONE DELIBERATE DEVIATION on `task`: OpenCode puts `description` to work as a session title. Super
+ * Pi's sub-agent record has no title field, and adding one is a persisted-shape change this step does not
+ * need, so `description` is carried into the `<summary>` line of the envelope instead. It is still
+ * shown to the model, still 3-5 words, and the parameter still means what its schema says.
+ */
+
+/**
+ * The environment contract with the server. The SAME four names are declared in
+ * `src/server/task-tool.ts`, which is the other end; the two are written out rather than imported
+ * because this file is loaded by Pi's module loader and that one by tsc, and a relative import across
+ * the two would resolve differently under each. `scripts/task-tool.test.mjs` asserts they agree.
+ */
+export const TASK_TOOL_NAME = "task";
+export const TASK_ENDPOINT_ENV = "SUPER_PI_TASK_ENDPOINT";
+export const TASK_ROSTER_ENV = "SUPER_PI_TASK_ROSTER";
+export const TASK_CONVERSATION_ENV = "SUPER_PI_TASK_CONVERSATION";
+export const TASK_DEPTH_ENV = "SUPER_PI_TASK_DEPTH";
+
+/**
+ * The `todowrite` extension's half of the same environment contract, declared here for the reason the
+ * four above are. `src/server/task-tool.ts` is the other end; `scripts/todo-tool.test.mjs` asserts they
+ * agree, because a rename on one side fails at call time with a message nothing reads.
+ */
+export const TODO_ENDPOINT_ENV = "SUPER_PI_TODO_ENDPOINT";
+
+/**
+ * The `workflow` tool's half of the same contract, declared here for the same reason. The name the model
+ * types, the endpoint it dials, and the capability that proves the call came from a primary agent's own
+ * environment - `src/server/task-tool.ts` is the other end and `scripts/task-tool.test.mjs` asserts the
+ * copies agree.
+ */
+export const WORKFLOW_TOOL_NAME = "workflow";
+export const WORKFLOW_ENDPOINT_ENV = "SUPER_PI_WORKFLOW_ENDPOINT";
+export const TASK_CAPABILITY_ENV = "SUPER_PI_TASK_CAPABILITY";
+
+/** The name the model calls, and the key Pi's tool allowlist matches on. OpenCode's name, kept. */
+export const TODO_TOOL_NAME = "todowrite";
+
+/** The parameters, OpenCode's `tool/todo.ts:6-8` minus its schema wrapper. */
+export type TodoParams = { todos: TodoEntry[] };
+
+/** One entry as the model writes it. `id` is OURS (see `normalizeTodos`), so it is absent here. */
+export type TodoEntry = { content: string; status: "pending" | "in_progress" | "completed"; priority?: "high" | "medium" | "low" };
+
+/** The three statuses Super Pi renders, as the model writes them. */
+const TODO_STATUSES = new Set(["pending", "in_progress", "completed"]);
+
+/** The parameters, exactly OpenCode's (`tool/task.ts:43-52`) minus the ones this step does not do. */
+export type TaskParams = {
+  description: string;
+  prompt: string;
+  subagent_type: string;
+  task_id?: string;
+  background?: boolean;
+};
+
+/** One dispatchable sub-agent, as the server read it from `agents/*.md` at spawn time. */
+export type RosterEntry = { id: string; name: string; description: string };
+
+/**
+ * Reads a roster back out of an environment value.
+ *
+ * Anything unreadable is an EMPTY roster rather than a throw. An extension that throws while loading
+ * takes Pi's whole extension host down with it, and a malformed environment variable is a far smaller
+ * fault than "the primary agent cannot delegate at all".
+ */
+export function parseRoster(raw: string | undefined): RosterEntry[] {
+  if (!raw) return [];
+  let parsed: unknown;
+  try { parsed = JSON.parse(raw); } catch { return []; }
+  if (!Array.isArray(parsed)) return [];
+  return parsed.filter((entry): entry is RosterEntry =>
+    typeof entry === "object" && entry !== null &&
+    typeof (entry as RosterEntry).id === "string" && (entry as RosterEntry).id !== "" &&
+    typeof (entry as RosterEntry).description === "string");
+}
+
+/**
+ * The model's half of the contract, and the part that decides whether the tool is used well.
+ *
+ * The first paragraph says what the tool IS in one sentence, because a tool description is read once
+ * and acted on. The "When NOT to use" list is OpenCode's, kept in its order and for its stated reason.
+ * The usage notes are OpenCode's, with three additions and one correction, and each of those is stated
+ * below where it is made rather than left as a surprise.
+ *
+ * THE CORRECTION. OpenCode's note 1 says a dispatch "runs until it finishes", and this file used to say
+ * the same - while the schema carried a `background` parameter and the code implemented it. So a mode
+ * that existed was described as though it did not, and the model would never have used it. Note 2 below
+ * now states that the default is blocking AND that `background` exists, because "delegate several
+ * independent things at once" is exactly what this roster is shaped for and a model told it cannot.
+ *
+ * THE ADDITIONS, notes 7-9, are about COMPOSING dispatches. They were absent because there was
+ * previously nothing on the other end to compose into: the model delegated, read the result, and decided
+ * the next move itself, which it is perfectly capable of. What changed is that the server can now run a
+ * declared plan, and a model that has never been told a dispatch BLOCKS until the child finishes will
+ * fire three of them in parallel and find they all read the same pre-delegation state. Note 7 is the one
+ * that matters most: it is the difference between a chain that works and a chain where every step works
+ * from the same wrong assumptions.
+ */
+export const TASK_DESCRIPTION = `Launch a subagent to handle a complex, multistep task autonomously.
+
+You must specify a subagent_type to select which subagent to use.
+
+When NOT to use this tool:
+- If you want to read a specific file path, use the Read or Glob tool instead, to find the match more quickly
+- If you are searching for a specific class definition like "class Foo", use the Grep tool instead, to find the match more quickly
+- If you are searching for code within a specific file or set of 2-3 files, use the Read tool instead, to find the match more quickly
+- If no available subagent is a good fit for the task, use other tools directly
+
+Usage notes:
+1. Every dispatch starts a SEPARATE agent process that runs until it finishes, so the cost of a delegation is minutes rather than seconds. Delegate work that is genuinely substantial; do not delegate a lookup you could do in one tool call.
+2. Once you have delegated work to a subagent, do not duplicate that work yourself. Continue with non-overlapping tasks, or wait for the result.
+3. When the subagent is done it returns ONE message back to you, wrapped in a <task> element. That result is not visible to the user: if it matters to the user, say so in your own reply.
+4. Each dispatch starts with a FRESH context. Your prompt is all the subagent will know, so it must contain the full task, and it must say exactly what you want back in its final message.
+5. Tell the subagent whether you expect it to WRITE CODE or only to RESEARCH (search, file reads, web fetches), and how to verify its work if it writes. It is not aware of the user's intent.
+6. If a subagent's description says it should be used proactively, use it without being asked.
+7. BY DEFAULT A DISPATCH BLOCKS: the call does not return until that subagent has finished, and its answer comes back to you in this same turn. So you CAN dispatch several in one turn and use each answer before writing the next prompt - which is the normal way to chain specialists.
+8. A LATER DISPATCH MUST CARRY THE EARLIER ONE'S ANSWER IN ITS PROMPT, because the next subagent starts with a fresh context and cannot see what the first one found. The tool does not do this for you. Write the findings you need into the next prompt yourself.
+9. Pass background: true only for work that does not depend on anything and that you will not need before this turn ends. The result arrives later as a follow-up message; you are not told anything at call time. Do NOT sleep, poll, or ask for status.
+10. For three or more steps where each depends on the previous one, prefer the workflow tool: it runs the chain server-side and hands each step the previous step's output without you copying it through your context.`;
+
+/**
+ * The roster block, OpenCode's `describeTask()` reduced to its two jobs: the ids that are legal, and
+ * when to pick each one.
+ *
+ * `id` is printed, not `name`. The model has to type `subagent_type` exactly, and requiring it to
+ * reproduce a Chinese label as a machine token would be a transcription exercise in front of any actual
+ * work. The human-readable `name` is printed alongside because the ids in this repository are English
+ * file names while the roles are described in Chinese, and a model reading only `scout` learns less
+ * from it than from both.
+ *
+ * THE EMPTY CASE IS SPOKEN, NOT SILENT. With no sub-agents the tool still exists - Pi has already
+ * declared it - so a description that just ended after the guidance would leave the model to guess
+ * whether an empty roster is a bug or a fact about this install. It says so explicitly and tells the
+ * model to do the work itself, which is the only correct action in that state.
+ */
+export function rosterSection(roster: readonly RosterEntry[]): string {
+  if (!roster.length) {
+    return "\n\nAvailable subagent types: NONE. This install has no agents/*.md file with `mode: subagent`, so there is nobody to delegate to. Do not call this tool - do the work yourself with your other tools, and mention that no sub-agents are configured if the user asked for delegation.";
+  }
+  const lines = roster.map((entry) => `- ${entry.id} (${entry.name}): ${entry.description || "No description was given for this subagent."}`);
+  return `\n\nAvailable subagent types and when to use each:\n${lines.join("\n")}`;
+}
+
+/** The full model-facing description: the guidance, then the live roster. OpenCode's `describeTask()`. */
+export function describeTask(roster: readonly RosterEntry[]): string {
+  return `${TASK_DESCRIPTION}${rosterSection(roster)}`;
+}
+
+/**
+ * The envelope the model reads, OpenCode's `renderOutput` (`tool/task.ts:64-79`).
+ *
+ * `state` is one of three words and the tag follows from it, so a model can tell a finished answer from
+ * a failure by the tag alone without parsing prose. Super Pi's own run statuses (`stopped`, `failed`)
+ * are folded into `error` here rather than passed through: `stopped` and `failed` are distinctions
+ * Super Pi's UI needs and the model has no use for, and adding a fourth `state` value would break any
+ * consumer expecting OpenCode's three.
+ *
+ * The child's text goes in verbatim. Trimming or wrapping it would mean the model receives something the
+ * sub-agent did not say, which is the one transformation that cannot be undone by reading the record.
+ */
+export function renderTaskResult(input: { id: string; state: "completed" | "error"; summary?: string; text: string }): string {
+  const tag = input.state === "error" ? "task_error" : "task_result";
+  return [
+    `<task id="${input.id}" state="${input.state}">`,
+    ...(input.summary ? [`<summary>${input.summary}</summary>`] : []),
+    `<${tag}>`,
+    input.text,
+    `</${tag}>`,
+    "</task>",
+  ].join("\n");
+}
+
+/** What the extension learns from its own environment before it can dispatch anything. */
+export type TaskToolConfig = {
+  endpoint: string;
+  conversationId: string;
+  depth: number;
+  roster: RosterEntry[];
+  /** The server's bearer token, when one is configured. Absent means the server runs open on loopback. */
+  token?: string;
+  /**
+   * This turn's dispatch capability, minted by the server at spawn.
+   *
+   * SENT IN THE BODY rather than a header, which is a deliberate departure from every other header here.
+   * The bearer token is a header because it authenticates the SERVER, and headers are what authentication
+   * is. This authenticates the CALLER, and the server reads it alongside `conversationId` - the pair is
+   * what identifies a turn, because a capability is only ever valid for one conversation. Presenting them
+   * apart would be a second, looser thing to get wrong.
+   */
+  capability?: string;
+};
+
+export function readTaskConfig(env: Record<string, string | undefined>): TaskToolConfig {
+  const depth = Number.parseInt(env[TASK_DEPTH_ENV] ?? "0", 10);
+  const token = env.SUPER_PI_ACCESS_TOKEN;
+  const capability = env[TASK_CAPABILITY_ENV];
+  return {
+    endpoint: env[TASK_ENDPOINT_ENV] ?? "",
+    conversationId: env[TASK_CONVERSATION_ENV] ?? "",
+    // An unreadable depth is 0, the primary agent's own value, rather than a number that would claim to
+    // be nested and trip the server's refusal for a reason that has nothing to do with this call.
+    depth: Number.isFinite(depth) ? depth : 0,
+    roster: parseRoster(env[TASK_ROSTER_ENV]),
+    ...(token ? { token } : {}),
+    ...(capability ? { capability } : {}),
+  };
+}
+
+/** The context slice the tool needs, so this file does not depend on Pi's `ExtensionToolContext`. */
+export type TaskToolContext = { cwd: string };
+
+export type TaskToolResult = { content: { type: "text"; text: string }[]; details: unknown; isError?: boolean };
+
+/** One HTTP seam, injected so a test can drive the tool without a socket and production uses global fetch. */
+export type TaskFetch = (url: string, init: { method: string; headers: Record<string, string>; body: string; signal?: AbortSignal }) => Promise<{ ok: boolean; status: number; text(): Promise<string> }>;
+
+const globalFetch: TaskFetch = (url, init) => fetch(url, init as RequestInit);
+
+/**
+ * Refuses a call that cannot possibly work, in words the model can act on.
+ *
+ * The three cases are separated because the MODEL's next move differs in each: an empty roster means use
+ * your own tools, an unknown id means pick one of the listed ones, and a missing endpoint means this
+ * session was not started by Super Pi at all and no retry will change that. A single generic "dispatch
+ * failed" would leave a model that retries the same call three times.
+ */
+export function refuseTask(config: TaskToolConfig, params: TaskParams): string | undefined {
+  if (!config.endpoint) return `The task tool is not available in this session: ${TASK_ENDPOINT_ENV} is not set, so there is no Super Pi server to dispatch to. Do the work yourself with your other tools.`;
+  if (!config.conversationId) return `The task tool is not available in this session: ${TASK_CONVERSATION_ENV} is not set, so this run cannot be attributed to a conversation. Do the work yourself with your other tools.`;
+  if (!config.roster.length) return "This install has no dispatchable sub-agents (no agents/*.md with `mode: subagent`), so there is nobody to delegate to. Do the work yourself with your other tools.";
+  if (!params.subagent_type.trim()) return `subagent_type is required. Available: ${config.roster.map((entry) => entry.id).join(", ")}.`;
+  if (!config.roster.some((entry) => entry.id === params.subagent_type)) return `${JSON.stringify(params.subagent_type)} is not a dispatchable subagent_type. Available: ${config.roster.map((entry) => entry.id).join(", ")}. Pick one of those, or do the work yourself.`;
+  if (!params.prompt.trim()) return "prompt is required and must not be empty: the sub-agent starts with a fresh context and your prompt is everything it will know.";
+  return undefined;
+}
+
+/**
+ * Runs one dispatch and returns the envelope the model reads.
+ *
+ * Returns rather than throws for EVERY outcome, including a malformed request. Pi treats a thrown tool
+ * error and an `isError` result almost identically, so this is not about Pi - it is that the model
+ * should see ONE shape for "the delegation did not work", with the reason inside it, instead of a stack
+ * trace for some failures and prose for others.
+ *
+ * The request carries a CONVERSATION, never a directory. The server resolves the workspace from its own
+ * stored state; a model that could name its own `cwd` would name a directory it can write, which is the
+ * entire boundary this endpoint exists to keep. That is why `context.cwd` is read here at all: only to
+ * be left out of the request.
+ */
+export async function executeTask(
+  params: TaskParams,
+  context: TaskToolContext,
+  config: TaskToolConfig,
+  deps: { signal?: AbortSignal; fetch?: TaskFetch } = {},
+): Promise<TaskToolResult> {
+  const text = (body: string, isError?: boolean): TaskToolResult => ({ content: [{ type: "text", text: body }], details: undefined, ...(isError ? { isError: true } : {}) });
+  const refusal = refuseTask(config, params);
+  if (refusal) return text(renderTaskResult({ id: "refused", state: "error", text: refusal }), true);
+
+  const send = deps.fetch ?? globalFetch;
+  let response: Awaited<ReturnType<TaskFetch>>;
+  try {
+    response = await send(config.endpoint, {
+      method: "POST",
+      // The bearer token is the SAME check every other endpoint on this server applies, and the server
+      // enforces it BEFORE the loopback test, so an extension that forgot it would get a bare 401.
+      headers: { "content-type": "application/json", ...(config.token ? { authorization: `Bearer ${config.token}` } : {}) },
+      body: JSON.stringify({
+        conversationId: config.conversationId,
+        subagent_type: params.subagent_type,
+        prompt: params.prompt,
+        description: params.description,
+        depth: config.depth,
+        background: params.background === true,
+        // Always sent, even when undefined, so a body that omits the field is unambiguously a caller that
+        // did not have one - which the server treats as a refusal, not as a legacy request to let through.
+        capability: config.capability,
+      }),
+      ...(deps.signal ? { signal: deps.signal } : {}),
+    });
+  } catch (error) {
+    // A failed CONNECTION is worth distinguishing from a refused dispatch: nothing ran, and no run
+    // record exists, so telling the model to look at the run would send it looking for something that
+    // was never created.
+    return text(renderTaskResult({ id: "unreachable", state: "error", text: `Could not reach the Super Pi server at ${config.endpoint}: ${error instanceof Error ? error.message : "unknown error"}` }), true);
+  }
+
+  /** The server answers JSON; a body that is not JSON means a proxy or an error page, not a verdict. */
+  let payload: { run?: { id?: string; status?: string; agentId?: string }; output?: string; error?: string; outputTruncated?: boolean };
+  try { payload = JSON.parse(await response.text()) as typeof payload; }
+  catch { return text(renderTaskResult({ id: "unreadable", state: "error", text: `The dispatch endpoint answered ${response.status} with something that is not JSON, so its result cannot be read.` }), true); }
+
+  // No run id means nothing ran: either the server refused before spawning, or the body was unreadable.
+  // "refused" says so, where "unknown" would imply a run exists somewhere whose output is merely absent.
+  const id = payload.run?.id ?? "refused";
+  if (params.background === true && payload.run?.status === "running") {
+    return text(`<task id="${id}" state="running">\n<summary>${params.description.trim() || params.subagent_type}</summary>\n<task_result>The task is working in the background. You will be notified automatically when it finishes. Do not sleep, poll for progress, ask the task for status, or duplicate this task's work. Continue with non-overlapping work.</task_result>\n</task>`);
+  }
+  const completed = payload.run?.status === "completed";
+  const body = completed
+    ? payload.output ?? ""
+    : payload.error ?? `The sub-agent run finished as ${JSON.stringify(payload.run?.status ?? "unknown")} without saying why.`;
+  return text(
+    renderTaskResult({
+      id,
+      state: completed ? "completed" : "error",
+      summary: params.description.trim() ? `${params.description.trim()} (${params.subagent_type})` : `${params.subagent_type}`,
+      text: payload.outputTruncated && completed ? `${body}\n\n[This answer was truncated at 50 KB by the server; the full run is recorded in Super Pi.]` : body,
+    }),
+    !completed,
+  );
+}
+
+// ---------------------------------------------------------------------------------------------
+// The `todowrite` tool: a task list the model maintains itself, and a person watches from the sidebar.
+//
+// THIS IS A PORT OF OPENCODE'S `tool/todo.ts` + `tool/todowrite.txt`, and the two files are 46 lines and
+// 44 lines respectively - almost all of the first one Effect plumbing, and the whole of the second one
+// prose the model reads. Only the prose ports intact, and that is the point of this file.
+//
+// THE PROACTIVE TRIGGER IS THE DESCRIPTION, and nothing else. This is the part of OpenCode's design that
+// is easy to get wrong by looking for a mechanism that isn't there: OpenCode does NOT inject the todo
+// list into any system prompt, does NOT have a scheduler, and does NOT nudge. `session/todo.ts` is a
+// per-session table that a tool call writes, and the ONLY thing that makes a model call it on its own is
+// the "Use proactively when" list in `todowrite.txt` - specifically the two entries that fire on work
+// happening rather than on a question being asked:
+//
+//   - "You start a task - mark it `in_progress` (only one at a time) before working"
+//   - "You finish a task - mark it `completed` and add any follow-ups discovered during the work"
+//
+// Those two lines ARE the design. Everything else here - the endpoint, the store, the sidebar - is
+// plumbing that makes those two lines possible. So they are carried over in OpenCode's own order and
+// wording, and the test asserts the sentences are PRESENT rather than paraphrased, because a reworded
+// trigger is a trigger that fires less often and no test would notice except this one.
+//
+// WHAT CHANGES FROM OPENCODE, and why each change is forced rather than chosen:
+//
+// - `cancelled` is GONE from the States section. Super Pi's list is replaced whole on every call
+//   (`normalizeTodos` in src/server/task-tool.ts), so "no longer needed" is expressed by not sending the
+//   item. Keeping a fourth status would mean a state the model can set that nothing ever takes off the
+//   screen, which is a row that says it was cancelled forever.
+// - The permission gate is gone. OpenCode asks `ctx.ask({ permission: "todowrite", patterns: ["*"] })`
+//   before every write (`tool/todo.ts:24-29`) and denies the tool to sub-agents that lack the permission
+//   (`agent/subagent-permissions.ts:19-24`). Super Pi's server has one permission story and it is
+//   bearer-token plus loopback, not a per-tool prompt, and a tool whose every call raises a modal is a
+//   tool a model stops calling - which would break the proactive trigger this file exists to preserve.
+//   The endpoint's loopback-and-token guards are what stands in that place; they are noted in
+//   `refuseTodo` so the model knows the rule rather than guessing at it.
+// - The list is per-install, not per-session (`AppState.todos` is one array). Stated in the report rather
+//   than hidden: switching conversations shows the previous conversation's list until the model rewrites
+//   it. Making it per-conversation is a persisted-shape change and is out of this task's scope.
+//
+// THE OUTPUT IS THE SERVER'S LIST, NOT THE MODEL'S. OpenCode echoes its own input
+// (`tool/todo.ts:38`). This tool echoes what the server actually STORED, which differs whenever the
+// server dropped an empty item, truncated a long one or filled in a missing id - and echoing the stored
+// copy is what stops the model from believing a row was saved when it was not.
+
+/**
+ * The model-facing description. OpenCode's `todowrite.txt`, ported.
+ *
+ * Kept in English for the same reason `TASK_DESCRIPTION` above is: it is read by a model, and the rest
+ * of this extension's model-facing text is English, so a Chinese paragraph here would be the only Chinese
+ * instruction in the tool set. The paragraphs a person reads (the sidebar) are the Chinese ones.
+ *
+ * The one ADDED paragraph is the third one. OpenCode never tells the model that anyone is watching - its
+ * description is written entirely in the imperative voice of a task list. Super Pi's list is on screen in
+ * a panel a user is looking at while the agent works, and that is the reason to maintain it in real time
+ * rather than at the end, so the description says so. This is the piece Super Pi has that OpenCode does
+ * not, and it is stated to the model as a fact about the world rather than as a request.
+ */
+export const TODO_DESCRIPTION = `Create and maintain a structured task list for the current coding session. Tracks progress, organizes multi-step work, and surfaces status to the user.
+
+## When to use
+Use proactively when:
+- The task requires 3+ distinct steps or actions (not just 3 tool calls for a single conceptual step)
+- The work is non-trivial and benefits from planning
+- The user provides multiple tasks (numbered or comma-separated) or explicitly asks for a todo list
+- New instructions arrive - capture them as todos
+- You start a task - mark it \`in_progress\` (only one at a time) before working
+- You finish a task - mark it \`completed\` and add any follow-ups discovered during the work
+
+## When NOT to use
+Skip when:
+- The work is a single, straightforward task (or <3 trivial steps)
+- The request is purely informational or conversational
+- Tracking adds no organizational value
+
+## States
+- \`pending\` - not started
+- \`in_progress\` - actively working (exactly ONE at a time)
+- \`completed\` - finished successfully
+
+To drop an item that is no longer needed, leave it out of the next call entirely: this tool replaces the whole list, so an item you do not send is an item that disappears.
+
+## Rules
+- Update status in real time; don't batch completions
+- Mark \`completed\` only after the required work is actually done, including any required verification. Never based on intent.
+- Keep exactly one \`in_progress\` while work remains
+- If blocked or partial, keep it \`in_progress\` and add a follow-up todo describing the blocker
+- Preserve user-provided commands verbatim (flags, args, order)
+- Items should be specific and actionable; break large work into smaller steps
+
+## The user is watching this list
+This list is rendered live in a panel beside the conversation, so a stale row is visible to the person you are working for while you are still working. That is why the triggers above are about PROGRESS and not about questions: update the list when a task starts, when it finishes, and when you discover a new step - not when the user asks where you are.
+
+## Examples
+
+Use it:
+- "Add a dark mode toggle and run the tests" -> multi-step feature + explicit verification
+- "Rename getCwd -> getCurrentWorkingDirectory across the repo" -> grep reveals 15 occurrences in 8 files
+- "Implement registration, catalog, cart, checkout" -> multiple complex features
+
+Skip it:
+- "How do I print Hello World in Python?" -> informational
+- "Add a comment to calculateTotal" -> single edit
+- "Run npm install and tell me what happened" -> one command
+
+When in doubt, use it.`;
+
+export type TodoToolConfig = { endpoint: string; conversationId: string; token?: string };
+
+/** What the extension learns from its own environment before it can write anything. */
+export function readTodoConfig(env: Record<string, string | undefined>): TodoToolConfig {
+  const token = env.SUPER_PI_ACCESS_TOKEN;
+  return { endpoint: env[TODO_ENDPOINT_ENV] ?? "", conversationId: env[TASK_CONVERSATION_ENV] ?? "", ...(token ? { token } : {}) };
+}
+
+/**
+ * Refuses a call that cannot work, in words the model can act on.
+ *
+ * The server is authoritative over what the list may contain (`normalizeTodos`), so this file does NOT
+ * re-check `content` or `status` and deliberately does not reject a list it dislikes: a list with one bad
+ * entry is better stored than refused, because a refusal loses the twenty good ones with it. What is
+ * checked here is only the things that make the call impossible - the same three-case split `refuseTask`
+ * uses, for the same reason.
+ */
+export function refuseTodo(config: TodoToolConfig, params: TodoParams): string | undefined {
+  if (!config.endpoint) return `The todowrite tool is not available in this session: ${TODO_ENDPOINT_ENV} is not set, so there is no Super Pi server to write the list to. Keep working and describe your plan in prose instead.`;
+  if (!config.conversationId) return `The todowrite tool is not available in this session: ${TASK_CONVERSATION_ENV} is not set. Keep working and describe your plan in prose instead.`;
+  if (!Array.isArray(params.todos)) return "todowrite requires a `todos` array. Send the WHOLE list every time - this tool replaces the list rather than adding to it.";
+  return undefined;
+}
+
+/** One HTTP seam, injected so a test can drive the tool without a socket and production uses global fetch. */
+export type TodoFetch = (url: string, init: { method: string; headers: Record<string, string>; body: string; signal?: AbortSignal }) => Promise<{ ok: boolean; status: number; text(): Promise<string> }>;
+
+/**
+ * Runs one write and returns what the model reads.
+ *
+ * Returns rather than throws for every outcome, for the reason `executeTask` does: the model should see
+ * ONE shape for "the list was not written", with the reason inside it.
+ *
+ * THE RETURNED LIST IS THE SERVER'S, and this is the one place the port departs from OpenCode's behaviour
+ * on purpose. The server is the only party that has validated, truncated and id-stamped what was stored,
+ * so echoing its copy is what tells the model the truth; echoing the input instead (OpenCode,
+ * `tool/todo.ts:38`) would let it believe a 40,000-character row survived when it was cut to 400. The
+ * dropped count rides along in the sentence for the same reason - a silent truncation reads as success.
+ */
+export async function executeTodo(
+  params: TodoParams,
+  config: TodoToolConfig,
+  deps: { signal?: AbortSignal; fetch?: TodoFetch } = {},
+): Promise<TaskToolResult> {
+  const text = (body: string, isError?: boolean): TaskToolResult => ({ content: [{ type: "text", text: body }], details: undefined, ...(isError ? { isError: true } : {}) });
+  const refusal = refuseTodo(config, params);
+  if (refusal) return text(refusal, true);
+
+  const send = deps.fetch ?? globalFetch;
+  let response: Awaited<ReturnType<TodoFetch>>;
+  try {
+    response = await send(config.endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...(config.token ? { authorization: `Bearer ${config.token}` } : {}) },
+      // The CONVERSATION is named so the server can attribute the write, never a directory: the same
+      // boundary `executeTask` keeps, and for the same reason - a model that could name its own cwd could
+      // write outside the workspace this app exists to keep it inside.
+      body: JSON.stringify({ conversationId: config.conversationId, todos: params.todos }),
+      ...(deps.signal ? { signal: deps.signal } : {}),
+    });
+  } catch (error) {
+    return text(`Could not reach the Super Pi server at ${config.endpoint}: ${error instanceof Error ? error.message : "unknown error"}. The todo list was NOT saved - carry your plan in prose this turn and try again.`, true);
+  }
+
+  let payload: { todos?: TodoEntry[]; dropped?: number; error?: string };
+  try { payload = JSON.parse(await response.text()) as typeof payload; }
+  catch { return text(`The todo endpoint answered ${response.status} with something that is not JSON, so the list cannot be confirmed as saved. Treat it as unsaved and retry.`, true); }
+  if (!response.ok || !Array.isArray(payload.todos)) {
+    return text(payload.error ?? `The todo endpoint answered ${response.status} without saving the list. Treat it as unsaved and retry.`, true);
+  }
+
+  // Only statuses this file knows are echoed, and only because the server's validator already enforces
+  // them - this is a type narrowing for the renderer below, not a second validation pass.
+  const stored = payload.todos.filter((todo): todo is TodoEntry => Boolean(todo) && typeof todo.content === "string" && TODO_STATUSES.has(todo.status));
+  const open = stored.filter((todo) => todo.status !== "completed").length;
+  const summary = !stored.length ? "0 个待办任务" : !open ? `全部完成：${stored.length} 个待办任务` : `${open} 个待办未完成，共 ${stored.length} 个`;
+  const dropped = typeof payload.dropped === "number" && payload.dropped > 0
+    ? `\n\n[${payload.dropped} of the entries you sent were dropped or truncated by the server - they are NOT in the saved list. The saved list is the JSON below.]`
+    : "";
+  return text(`${summary}${dropped}\n\n${JSON.stringify(stored, null, 2)}`);
+}
+
+// ---------------------------------------------------------------------------------------------
+// The `workflow` tool: hand an ordered plan of sub-agent steps to the server and let it walk them.
+//
+// WHY IT EXISTS BESIDE `task`. `task` delegates ONE piece of work and hands the answer back to the model,
+// which then decides the next move. That works, and a model is entirely capable of chaining three `task`
+// calls - but every link in that chain has to pass through the model's context as prose, and a model that
+// drops one link produces a chain where every step ran from the same wrong assumptions, with nothing in
+// the transcript to show where it broke. This tool moves the loop to the server: the plan is written down
+// whole before the first step runs, each step is handed the previous step's output automatically, and the
+// timeline is on screen the whole way. See `src/server/workflow.ts` for the rules and
+// `docs/AGENT_LOOP_DESIGN.md` for what this deliberately does not do.
+//
+// WHAT IT IS NOT, stated in the description because a model will otherwise try: it is not a graph, it
+// cannot branch or loop back, and it does not run steps in parallel. A plan it cannot express is a plan to
+// dispatch with `task` directly - and that fallback is the reason this tool can be small. A richer
+// orchestration language would not remove that fallback, it would only add a second way to be wrong.
+
+/** What the model declares. The shape the server's validator accepts, minus everything it will refuse. */
+export type WorkflowParams = {
+  summary?: string;
+  onFailure?: string;
+  steps?: { agentId?: string; label?: string; prompt?: string }[];
+};
+
+/**
+ * The description, written to push the decision BACK toward `task`.
+ *
+ * THE TONE IS THE DESIGN. A model that reads "orchestrate pipelines" will reach for this tool on a
+ * two-step task and then discover it cannot express what it wanted. Every note here exists to make the
+ * smaller tool the default and this one the deliberate choice: `task` is named as the answer for most
+ * work, and the conditions under which a plan is genuinely better are given concretely rather than
+ * described abstractly.
+ *
+ * The failure policy is named as a THREE-way choice with its cost, because the model is choosing a
+ * behaviour it will not see again until the end: `stop` is the default and is what a plan that failed has
+ * honestly earned, `skip` hands the next subagent a hole, and `retry` costs another whole subagent run.
+ */
+export const WORKFLOW_DESCRIPTION = `Run an ordered plan of sub-agents, where each step is automatically handed the previous step's output.
+
+WHEN TO USE THIS, AND WHEN NOT:
+- Two steps, or a chain you can hold in your head: use the task tool, twice. You see each answer before you write the next prompt, which is more control than this gives you.
+- Three or more steps where each DEPENDS on the previous one: use this. The server runs the chain, hands each step the last step's output, and shows the user a timeline while it happens. Doing that by hand means copying every answer through your context, and a plan this shape is exactly where a dropped link stays invisible until the end.
+- Steps that are INDEPENDENT of each other: do not use this. Use the task tool with background: true, several times - that is what parallel is for.
+- Anything with branching, conditional steps, or a loop back to an earlier step: you cannot express that here. Use the task tool and decide the next step yourself.
+
+Usage notes:
+1. This call BLOCKS until the whole plan finishes, and every step is a separate sub-agent process that takes minutes. Three steps is often five to ten minutes.
+2. Steps run IN ORDER, one at a time. Each is a fresh subagent with a fresh context.
+3. You do NOT need to copy an earlier step's output into a later step's prompt. By default the server prepends every earlier step's agent, label, status and output to each step, so a later step can act on what came before. Write each prompt as the instruction for ITS OWN step.
+4. To control that instead, put {{previous}} in a prompt for just the previous step's output, or {{history}} for all of them. Using either one REPLACES the automatic block rather than adding to it.
+5. A step that COMPLETES has succeeded, whatever it says. If a verifier step comes back saying the work failed, the plan still ran to the end - read its output, then decide whether to run another round yourself. The server does not judge results for you.
+6. onFailure controls what happens when a step FAILS TO RUN: stop (the default) ends the plan and reports which step failed; skip goes past it and tells the next step it was skipped; retry:N tries it again up to N more times.
+7. label is optional and is only ever shown to the user. Say what the step is FOR in three or four words.
+8. agentId must be one of the dispatchable sub-agent types listed below.`;
+
+/** What the extension knows about the workflow endpoint before it can call anything. */
+export type WorkflowToolConfig = {
+  endpoint: string;
+  conversationId: string;
+  token?: string;
+  /** This turn's dispatch capability. See `TaskToolConfig.capability` for why it travels in the body. */
+  capability?: string;
+};
+
+/** What the extension learns from its own environment before it can run a plan. */
+export function readWorkflowConfig(env: Record<string, string | undefined>): WorkflowToolConfig {
+  const token = env.SUPER_PI_ACCESS_TOKEN;
+  const capability = env[TASK_CAPABILITY_ENV];
+  return {
+    endpoint: env[WORKFLOW_ENDPOINT_ENV] ?? "",
+    conversationId: env[TASK_CONVERSATION_ENV] ?? "",
+    ...(token ? { token } : {}),
+    ...(capability ? { capability } : {}),
+  };
+}
+
+/**
+ * Refuses a call that cannot work, in words the model can act on.
+ *
+ * SHALLOWER THAN `refuseTask` DELIBERATELY. Only the two conditions that make the call impossible are
+ * checked here - no endpoint, no conversation. The plan's shape is the SERVER's business, because the
+ * server is what has the roster: this file cannot know whether "scout" is a legal agentId on this install,
+ * and a check against a list hardcoded here would be a second list free to fall out of date with
+ * `agents/*.md`. So a bad plan comes back as a server refusal carrying the reason - the same shape the
+ * model would have got anyway, and the server's message, which names the ids that actually exist.
+ */
+export function refuseWorkflow(config: WorkflowToolConfig, params: WorkflowParams): string | undefined {
+  if (!config.endpoint) return `The workflow tool is not available in this session: ${WORKFLOW_ENDPOINT_ENV} is not set, so there is no Super Pi server to run the plan. Use the task tool, or do the steps yourself.`;
+  if (!config.conversationId) return `The workflow tool is not available in this session: ${TASK_CONVERSATION_ENV} is not set. Use the task tool, or do the steps yourself.`;
+  if (!Array.isArray(params.steps) || !params.steps.length) return "workflow requires a non-empty `steps` array. For a single sub-agent, use the task tool instead.";
+  return undefined;
+}
+
+/** One step as the server reports it back, which is the shape the envelope renders. */
+export type WorkflowStepEntry = {
+  n?: number;
+  agentId?: string;
+  label?: string;
+  status?: string;
+  attempts?: number;
+  output?: string;
+  outputTruncated?: boolean;
+  error?: string;
+};
+
+/**
+ * Renders the plan the model gets back, in the same `<task>` family as a single dispatch.
+ *
+ * THE SAME THREE STATES, and for the reason `renderTaskResult` folds Super Pi's stopped/failed into
+ * `error`: the envelope's state is a thing the model branches on, and a fourth value would break a
+ * consumer expecting the OpenCode three. What IS different is that a plan carries per-step detail the
+ * model needs - which step failed, how many tries it took, what each one said - and flattening all of
+ * that into one blob would throw away the part that makes a plan worth reading over three task calls.
+ *
+ * Each step is rendered with its own `<step>` element, and its attempts as a COUNT rather than as text: a
+ * retried step's earlier attempts are already in the run records and on the timeline, and re-sending a
+ * superseded answer here would have the model act on a failure it has already moved past.
+ */
+export function renderWorkflowResult(input: { id: string; state: "completed" | "error"; summary: string; steps: WorkflowStepEntry[]; text?: string }): string {
+  const tag = input.state === "error" ? "task_error" : "task_result";
+  const body: string[] = [];
+  for (const step of input.steps) {
+    const where = step.label ? `第 ${step.n} 步 · ${step.label}（${step.agentId}）` : `第 ${step.n} 步 · ${step.agentId}`;
+    const tries = (step.attempts ?? 0) > 1 ? `，尝试了 ${step.attempts} 次` : "";
+    const lines = [`<step n="${step.n ?? "?"}" agent="${step.agentId ?? "?"}" status="${step.status ?? "unknown"}">`];
+    lines.push(`<summary>${where}：${step.status ?? "unknown"}${tries}</summary>`);
+    if (step.output) lines.push(step.outputTruncated ? `${step.output}\n[这一步的输出被服务端截断，完整内容在运行记录里]` : step.output);
+    if (step.error) lines.push(`（这一步没能完成：${step.error}）`);
+    lines.push("</step>");
+    body.push(lines.join("\n"));
+  }
+  return [
+    `<task id="${input.id}" state="${input.state}">`,
+    `<summary>${input.summary}</summary>`,
+    `<${tag}>`,
+    ...body,
+    ...(input.text ? ["", input.text] : []),
+    `</${tag}>`,
+    "</task>",
+  ].join("\n");
+}
+
+/** One HTTP seam, injected for tests exactly as `TaskFetch` is. */
+export type WorkflowFetch = TaskFetch;
+
+/**
+ * Runs one plan and returns the envelope the model reads.
+ *
+ * RETURNS RATHER THAN THROWS for every outcome, for the reason `executeTask` does: Pi treats a thrown tool
+ * error and an isError result almost identically, so this is not about Pi - it is that the model should
+ * see ONE shape for "the delegation did not work", with the reason inside it.
+ *
+ * A PLAN THAT FAILED IS NOT AN ERROR IN THE TRANSPORT SENSE. The steps ran; some of them did not succeed.
+ * That is a result the model reasons about, so it comes back as state="error" with every step's output
+ * intact rather than as a refusal that would hide what did happen. The distinction matters most in the one
+ * case a model must handle well: a plan whose verifier came back negative still tells it everything it
+ * needs to decide whether to run another round.
+ */
+export async function executeWorkflow(
+  params: WorkflowParams,
+  config: WorkflowToolConfig,
+  deps: { signal?: AbortSignal; fetch?: WorkflowFetch } = {},
+): Promise<TaskToolResult> {
+  const text = (body: string, isError?: boolean): TaskToolResult => ({ content: [{ type: "text", text: body }], details: undefined, ...(isError ? { isError: true } : {}) });
+  const refusal = refuseWorkflow(config, params);
+  if (refusal) return text(renderWorkflowResult({ id: "refused", state: "error", summary: "workflow", steps: [], text: refusal }), true);
+
+  const send = deps.fetch ?? globalFetch;
+  let response: Awaited<ReturnType<WorkflowFetch>>;
+  try {
+    response = await send(config.endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...(config.token ? { authorization: `Bearer ${config.token}` } : {}) },
+      // The CONVERSATION, never a directory - the same boundary `executeTask` keeps, for the same reason.
+      body: JSON.stringify({
+        conversationId: config.conversationId,
+        summary: params.summary,
+        onFailure: params.onFailure,
+        steps: params.steps,
+        capability: config.capability,
+      }),
+      ...(deps.signal ? { signal: deps.signal } : {}),
+    });
+  } catch (error) {
+    return text(renderWorkflowResult({
+      id: "unreachable", state: "error", summary: params.summary?.trim() || "workflow", steps: [],
+      text: `Could not reach the Super Pi server at ${config.endpoint}: ${error instanceof Error ? error.message : "unknown error"}. Nothing ran, so there is no plan to look for.`,
+    }), true);
+  }
+
+  let payload: { workflow?: { id?: string; summary?: string; status?: string; steps?: WorkflowStepEntry[] }; error?: string };
+  try { payload = JSON.parse(await response.text()) as typeof payload; }
+  catch { return text(renderWorkflowResult({ id: "unreadable", state: "error", summary: "workflow", steps: [], text: `The workflow endpoint answered ${response.status} with something that is not JSON, so its result cannot be read.` }), true); }
+
+  // No workflow id means nothing ran: the server refused before writing a plan, so there is no timeline
+  // to point at, and saying so beats implying a run exists whose output is merely absent.
+  if (!payload.workflow?.id) {
+    return text(renderWorkflowResult({
+      id: "refused", state: "error", summary: params.summary?.trim() || "workflow", steps: [],
+      text: payload.error ?? `The workflow endpoint answered ${response.status} without starting a plan.`,
+    }), true);
+  }
+
+  const workflow = payload.workflow;
+  const steps = Array.isArray(workflow.steps) ? workflow.steps : [];
+  const completed = workflow.status === "completed";
+  const finished = steps.filter((step) => step.status === "completed" || step.status === "skipped").length;
+  return text(
+    renderWorkflowResult({
+      id: workflow.id,
+      state: completed ? "completed" : "error",
+      summary: workflow.summary || params.summary?.trim() || "workflow",
+      steps,
+      ...(completed ? {} : {
+        text: `The plan finished as ${JSON.stringify(workflow.status ?? "unknown")}: ${finished} of ${steps.length} steps completed. Nothing was lost - read each step above, then decide what happens next. If you need another round, dispatch it with the task tool.`,
+      }),
+    }),
+    !completed,
+  );
+}