@evandu/super-pi 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,485 @@
+/**
+ * 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)}`);
+}

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

@@ -0,0 +1,141 @@
+import { Type } from "@sinclair/typebox";
+import {
+  TASK_TOOL_NAME,
+  describeTask,
+  executeTask,
+  readTaskConfig,
+  type TaskParams,
+} from "./core.ts";
+import {
+  TODO_DESCRIPTION,
+  TODO_TOOL_NAME,
+  executeTodo,
+  readTodoConfig,
+  type TodoParams,
+} from "./core.ts";
+
+/**
+ * The Pi adapter for the `task` and `todowrite` tools. Everything with a decision in it is in
+ * `./core.ts`; this file is the mounting hardware and nothing else.
+ *
+ * `@sinclair/typebox` is Pi's VIRTUAL MODULE (packages/coding-agent/src/core/extensions/virtual-modules.ts),
+ * which is why importing it works here and would not work anywhere else in this repository: it is not in
+ * `package.json` and is not installed in `node_modules`. Nothing outside Pi may import this file for that
+ * reason - `scripts/task-tool.test.mjs` drives `core.ts` instead, and reads this file as TEXT for the
+ * things that cannot be executed outside Pi.
+ *
+ * The parameter schema is OpenCode's `task.ts:43-52` verbatim, including `task_id`. `task_id` is
+ * accepted and ignored in this step: resuming a sub-agent's session would mean keeping its Pi process
+ * and its transcript alive between calls, and `runtime.ts` kills the primary's Pi after every turn, so
+ * there is nothing for a session id to point at yet. It is kept in the schema because removing it would
+ * make this tool incompatible with a model that has been told the OpenCode shape, and because the next
+ * step is precisely the thing that gives it meaning.
+ */
+const Parameters = Type.Object({
+  description: Type.String({ description: "A short (3-5 words) description of the task" }),
+  prompt: Type.String({ description: "The task for the agent to perform" }),
+  subagent_type: Type.String({ description: "The type of specialized agent to use for this task" }),
+  task_id: Type.Optional(Type.String({ description: "Resume a previous task when supported" })),
+  background: Type.Optional(Type.Boolean({ description: "Run asynchronously and deliver the result as a follow-up message" })),
+});
+
+/**
+ * The `todowrite` parameter schema, OpenCode's `tool/todo.ts:6-8` in the TypeBox dialect this adapter
+ * speaks. `todos` is the WHOLE list every time - it replaces the list rather than adding to it - which is
+ * stated in the per-property description, because a model that assumes it appends will send one item and
+ * watch the other forty disappear.
+ *
+ * `id` is absent from the schema on purpose and this is the ONE place Super Pi's copy differs from
+ * OpenCode's: OpenCode's `Todo.Info` carries only content/status/priority. Super Pi keeps those three and
+ * ADDS a stable id server-side (`normalizeTodos`), which the schema does not mention so the model is not
+ * invited to invent ids it will not control.
+ */
+const TodoParameters = Type.Object({
+  todos: Type.Array(Type.Object({
+    content: Type.String({ description: "The task text, specific and actionable" }),
+    status: Type.Union([Type.Literal("pending"), Type.Literal("in_progress"), Type.Literal("completed")], { description: "pending = not started, in_progress = being worked on now (exactly one at a time), completed = finished successfully" }),
+    priority: Type.Optional(Type.Union([Type.Literal("high"), Type.Literal("medium"), Type.Literal("low")], { description: "How urgent this item is" })),
+  }), { description: "The COMPLETE updated todo list - this replaces the previous list entirely, so include every item you still want on screen" }),
+});
+
+/**
+ * The only structural type this file needs, declared locally.
+ *
+ * It was `import type { ExtensionFactory } from "F:/code/open_agents_repo/pi/..."` before, which is an
+ * absolute path into one machine's checkout: fine there, unresolvable on any other, and it made this
+ * file impossible to open without that checkout present. Pi is a runtime, not a build dependency of
+ * Super Pi, so there is no package to import its types from - declaring the two shapes this file uses is
+ * the honest alternative, and `npm run check` would not have caught the old one because `agents/` is
+ * outside every tsconfig.
+ */
+type ExtensionToolDefinition = {
+  name: string;
+  label: string;
+  description: string;
+  parameters: unknown;
+  execute(toolCallId: string, params: unknown, signal: AbortSignal | undefined, onUpdate: unknown, context: { cwd: string }): Promise<unknown>;
+  prepareLoadout?(loadout: unknown): { descriptions?: Record<string, string> } | undefined;
+};
+type ExtensionApi = { registerTool(tool: ExtensionToolDefinition): void };
+
+const extension = (pi: ExtensionApi): void => {
+  // Read ONCE at load, not per call: the environment cannot change under a running Pi, and `prepareLoadout`
+  // is synchronous - it cannot await a fetch for a roster - so the roster has to already be here.
+  const config = readTaskConfig(process.env);
+  // Same rule for the todo tool, and for a stronger reason: the todo endpoint is derived from the same
+  // listen address as the task endpoint, so reading it per call would mean re-reading an environment
+  // that cannot have changed since the process started.
+  const todoConfig = readTodoConfig(process.env);
+
+  pi.registerTool({
+    name: TASK_TOOL_NAME,
+    label: "Task",
+    // The fallback for the seconds between registration and the first `prepareLoadout`: the guidance with
+    // no roster, which is still true text rather than a placeholder.
+    description: describeTask(config.roster),
+    promptSnippet: "delegate substantial work to a specialized subagent",
+    parameters: Parameters,
+    /**
+     * Injects the roster into the description the model is shown, on every loadout.
+     *
+     * Pi's own mechanism for a tool that lists other tools, and the reason it is used rather than
+     * editing the system prompt: `ToolDefinition.prepareLoadout` is documented for exactly this
+     * (types.ts:620-622 - "Tools that orchestrate other tools use it"), it is called whenever the active
+     * tools change, and a description that Pi receives is a description that cannot drift from the tool
+     * set it belongs to. `describeTask()` in OpenCode does the same thing one layer up, inside
+     * `registry.ts`.
+     *
+     * Read from the environment the server filled at spawn time, never from a list written here, so a
+     * sub-agent added to `agents/*.md` while the server runs is dispatchable on the next message.
+     */
+    prepareLoadout: () => ({ descriptions: { [TASK_TOOL_NAME]: describeTask(config.roster) } }),
+    execute: async (_toolCallId, params, signal, _onUpdate, context) =>
+      await executeTask(params as TaskParams, context, config, { signal: signal ?? undefined }),
+  });
+
+  /**
+   * `todowrite`, registered SECOND and for one reason: order in the tool list is the order a model reads
+   * them in, and a plan is worth more in front of the eye than a dispatcher is. Nothing depends on the
+   * order functionally - `runtime.ts` names both tools in its allowlist and Pi activates whichever of them
+   * the agent's own `tools:` map allows.
+   *
+   * NO `prepareLoadout`, and that is a decision rather than an omission. The task tool needs one because
+   * its description embeds the ROSTER, which changes on disk while the server runs; the todo description
+   * embeds nothing that changes, and the thing that does change - the current list - is the tool's own
+   * OUTPUT, which the model reads back from its own transcript on every subsequent turn. Re-injecting the
+   * list into the description would be a second source of truth for the same fact, and it would put a
+   * snapshot of the plan in front of the model that could disagree with the one its history already
+   * contains.
+   */
+  pi.registerTool({
+    name: TODO_TOOL_NAME,
+    label: "Todo",
+    description: TODO_DESCRIPTION,
+    promptSnippet: "track multi-step work as a live task list the user watches",
+    parameters: TodoParameters,
+    execute: async (_toolCallId, params, signal) =>
+      await executeTodo(params as TodoParams, todoConfig, { signal: signal ?? undefined }),
+  });
+};
+
+export default extension;

package/agents/verifier.md

@@ -0,0 +1,21 @@
+---
+name: 验证员
+mode: subagent
+description: 跑命令做验证：执行测试、构建或检查入口，如实贴出命令原文、退出码和失败行，不改任何文件。改完代码要确认通没通、或者需要亲眼看一次真实输出时用它。
+color: "#5AC8FA"
+tools:
+  "*": false
+  read: true
+  ls: true
+  bash: true
+---
+
+你是一个只负责验证的子 agent。你能跑命令，但不能修改任何文件——发现问题也不要自己动手修。
+
+行为约束：
+
+- 只跑派活里说的命令，或者这个仓库里已经存在的检查入口（比如 `npm run check`）。不要为了「顺手看看」跑一堆别的。
+- 把真实输出贴出来：命令原文、退出码、失败那几行原文。不要写「应该没问题」「看起来正常」这种话——你没资格说这种话，你只看得见输出。
+- 测试失败时定位到具体是哪个测试、哪一行断言、期望值和实际值各是什么，然后停下。不要修。
+- 命令跑不起来时要分清是环境问题（缺依赖、端口占用、可执行文件找不到）还是测试失败，两者的结论完全不同，不要混着说。
+- 最后一行给结论：`通过`、`失败`、`无法验证`，三选一，不要含糊。