@evandu/super-pi 0.1.1 → 0.1.2

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

@@ -1,141 +1,198 @@
-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;
+import { Type } from "@sinclair/typebox";
+import {
+  TASK_TOOL_NAME,
+  describeTask,
+  executeTask,
+  readTaskConfig,
+  type TaskParams,
+} from "./core.ts";
+import {
+  WORKFLOW_DESCRIPTION,
+  WORKFLOW_TOOL_NAME,
+  executeWorkflow,
+  readWorkflowConfig,
+  type WorkflowParams,
+} 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;
+};
+/**
+ * The `workflow` parameter schema.
+ *
+ * `agentId` rather than `subagent_type`, and the difference is that it is REQUIRED here. A single
+ * dispatch can infer itself from its prompt - a model asking for one delegation is obvious about which
+ * agent it wants - but a plan of up to eight steps cannot: a step whose agent is unspecified would have to
+ * be guessed by the server, and a server that guesses which specialist to run is exactly the
+ * role-name branch this whole feature refuses to have.
+ *
+ * `onFailure` is a plain string rather than a TypeBox union so the SERVER owns the whitelist. A closed
+ * enum here would be a second list that could disagree with `parseFailurePolicy`, and the message a model
+ * gets for a bad value is better written by the side that knows the real options.
+ */
+const WorkflowParameters = Type.Object({
+  summary: Type.String({ description: "One line saying what this whole plan is for, shown to the user above the timeline" }),
+  onFailure: Type.Optional(Type.String({ description: "What to do when a step FAILS TO RUN: stop (default), skip, retry:1, retry:2 or retry:3" })),
+  steps: Type.Array(Type.Object({
+    agentId: Type.String({ description: "The dispatchable sub-agent type to run, e.g. scout" }),
+    label: Type.Optional(Type.String({ description: "3-4 words saying what this step is FOR, shown to the user only" })),
+    prompt: Type.String({ description: "The instruction for THIS step alone. Earlier steps' output is added for you." }),
+  }), { minItems: 1, maxItems: 8, description: "The steps, in the order they should run" }),
+});
+
+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);
+  // Same rule for the workflow tool: one read at load, because the environment cannot change under a
+  // running Pi. The capability it reads is minted for THIS turn and dies with it, so it is valid for
+  // exactly as long as this process is - which is the whole reason a sub-agent cannot present one.
+  const workflowConfig = readWorkflowConfig(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 }),
+  });
+
+  /**
+   * `workflow`, registered THIRD and last.
+   *
+   * Last on purpose: a tool list is read in order, and this is the one a model should reach for LAST. It
+   * is also the most expensive call available - it blocks a whole pipeline of sub-agent runs - so the
+   * entry before it in the list being `todowrite` (a plan, free) rather than `workflow` is doing real work:
+   * the cheap way to express a plan should be what a model sees first.
+   *
+   * NO `prepareLoadout`, unlike `task`, because unlike `task` its description embeds nothing that changes
+   * while the server runs. It does not list the roster: the ids it accepts are the same ones `task` lists
+   * one entry above, in the same loadout, so injecting them a second time would be the same fact in two
+   * places free to disagree - and its description points the model at that list rather than repeating it.
+   */
+  pi.registerTool({
+    name: WORKFLOW_TOOL_NAME,
+    label: "Workflow",
+    description: WORKFLOW_DESCRIPTION,
+    promptSnippet: "run an ordered plan of sub-agents, each handed the previous step's output",
+    parameters: WorkflowParameters,
+    execute: async (_toolCallId, params, signal) =>
+      await executeWorkflow(params as WorkflowParams, workflowConfig, { signal: signal ?? undefined }),
+  });
+};
+
+export default extension;