@evandu/super-pi 0.1.1 → 0.1.2

package/dist/server/capability.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Proving that a dispatch request came from THIS server's primary agent, rather than from anything else on
+ * the machine that can open a socket to localhost.
+ *
+ * WHY THIS EXISTS, since the dispatch endpoint already looks like it authenticates. It does not. It
+ * validates ANCESTRY - that a claimed `parentRunId` names a real run belonging to the right conversation -
+ * and `docs/AGENT_LOOP_DESIGN.md` states the limit in as many words: "The current HTTP boundary validates
+ * supplied ancestry, not caller identity. A local process that omits both parentRunId and depth is
+ * indistinguishable from a primary caller." That is true, and it was tolerable while the only reachable
+ * primitive was a single dispatch. It stops being tolerable the moment an endpoint can trigger a SEQUENCE
+ * of dispatches: one unauthenticated POST becomes an unattended pipeline of sub-agents writing to the
+ * user's workspace, which is a far larger lever for the same missing check.
+ *
+ * WHY A CAPABILITY RATHER THAN A SHARED SECRET. `SUPER_PI_ACCESS_TOKEN` already exists and every endpoint
+ * already checks it - but it is SERVER-WIDE and optional: unset is the default, and when unset the whole
+ * server runs open on loopback, which is a reasonable choice for an app meant to be run by the person
+ * sitting at the machine. A dispatch capability is narrower and non-optional in the way that matters: it
+ * exists only for the duration of one turn, for one conversation, and only the primary agent's environment
+ * ever holds it. `SubagentSupervisor` passes no `env` to a child at all (`subagents.ts:371-380`), so a
+ * sub-agent - whose whole threat is that a model controls its inputs and therefore its shell commands -
+ * structurally cannot read it back out of its own environment and post it.
+ *
+ * WHAT THIS DOES NOT CLAIM. It is not defence against a compromised primary agent, which can read its own
+ * environment and would simply forward the capability. It is defence against the two neighbours of the
+ * primary that are NOT it: an unrelated local process, and a sub-agent that escaped its read-only
+ * allowlist. Neither is the primary, and neither is handed the token.
+ */
+/**
+ * The environment variable the capability travels in.
+ *
+ * Named on both sides of the wire rather than imported by the extension, for the reason every one of
+ * these names is written out twice: `agents/` is loaded by Pi's module loader and `src/` by tsc, so a
+ * relative import across the two would resolve differently under each. `scripts/task-tool.test.mjs`
+ * asserts the two copies agree, because a rename on one side would otherwise fail at dispatch time with a
+ * message nobody reads.
+ */
+export declare const TASK_CAPABILITY_ENV = "SUPER_PI_TASK_CAPABILITY";
+/**
+ * Mints the capability for one turn of one conversation, and returns it for the extension's environment.
+ *
+ * CALLED AT SPAWN, so the value is decided before the child exists and cannot be changed underneath it.
+ * A turn that never reaches the spawn mints nothing, which is correct: there is no process to hand it to.
+ *
+ * ROTATED EVERY TURN, and that is the property the duration would not give on its own. A token valid for
+ * the whole server lifetime would still be a token an unrelated process could not guess - but a token
+ * valid only while its holder is alive is a token that stops being a credential the moment the turn ends,
+ * so there is no window in which a leaked value is still live.
+ */
+export declare function mintCapability(conversationId: string): string;
+/**
+ * Forgets a conversation's capability, at the end of its turn.
+ *
+ * CALLED FROM `answer()`'s `finally`, so it runs on every exit - a turn that answered, a turn that threw,
+ * and a turn whose child was killed. A capability that outlived its turn would keep working for a process
+ * that no longer exists, which is precisely the shape of a credential with no owner.
+ */
+export declare function releaseCapability(conversationId: string): void;
+/** Forgets every capability. Called on shutdown, so nothing survives the process that minted it. */
+export declare function releaseAllCapabilities(): void;
+/**
+ * The capability currently valid for a conversation, or `undefined` when no primary turn is running.
+ *
+ * Exported for the endpoint's own diagnostics and for a test that needs to assert the lifecycle without
+ * reading a primary turn's environment. Not exported as a way to READ a conversation's capability and use
+ * it - a caller in this process is already inside the trust boundary it protects.
+ */
+export declare function capabilityFor(conversationId: string): string | undefined;
+/** The outcome of a check, with a message written for whoever the refusal will be shown to. */
+export type CapabilityVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Checks a presented capability against the one this conversation's turn was given.
+ *
+ * `timingSafeEqual` rather than `===`, because `===` on a token short-circuits at the first differing byte
+ * and turns the comparison into a timing oracle for the value itself. The length check runs first because
+ * `timingSafeEqual` throws on mismatched lengths rather than returning false.
+ *
+ * THE MESSAGE NAMES BOTH HALVES OF THE PROBLEM, because the reader is a model about to retry and there
+ * are two genuinely different failures here. A conversation with no live capability is being dispatched
+ * from OUTSIDE a turn - the request never came from a primary agent. A conversation with one, and the
+ * presented value does not match it, is a turn whose value was not carried through. An extension that
+ * silently omitted the header would otherwise be indistinguishable from an attacker, and would keep
+ * retrying forever.
+ */
+export declare function verifyCapability(conversationId: string, presented: unknown): CapabilityVerdict;

package/dist/server/capability.js

@@ -0,0 +1,136 @@
+import { randomUUID, timingSafeEqual } from "node:crypto";
+/**
+ * Proving that a dispatch request came from THIS server's primary agent, rather than from anything else on
+ * the machine that can open a socket to localhost.
+ *
+ * WHY THIS EXISTS, since the dispatch endpoint already looks like it authenticates. It does not. It
+ * validates ANCESTRY - that a claimed `parentRunId` names a real run belonging to the right conversation -
+ * and `docs/AGENT_LOOP_DESIGN.md` states the limit in as many words: "The current HTTP boundary validates
+ * supplied ancestry, not caller identity. A local process that omits both parentRunId and depth is
+ * indistinguishable from a primary caller." That is true, and it was tolerable while the only reachable
+ * primitive was a single dispatch. It stops being tolerable the moment an endpoint can trigger a SEQUENCE
+ * of dispatches: one unauthenticated POST becomes an unattended pipeline of sub-agents writing to the
+ * user's workspace, which is a far larger lever for the same missing check.
+ *
+ * WHY A CAPABILITY RATHER THAN A SHARED SECRET. `SUPER_PI_ACCESS_TOKEN` already exists and every endpoint
+ * already checks it - but it is SERVER-WIDE and optional: unset is the default, and when unset the whole
+ * server runs open on loopback, which is a reasonable choice for an app meant to be run by the person
+ * sitting at the machine. A dispatch capability is narrower and non-optional in the way that matters: it
+ * exists only for the duration of one turn, for one conversation, and only the primary agent's environment
+ * ever holds it. `SubagentSupervisor` passes no `env` to a child at all (`subagents.ts:371-380`), so a
+ * sub-agent - whose whole threat is that a model controls its inputs and therefore its shell commands -
+ * structurally cannot read it back out of its own environment and post it.
+ *
+ * WHAT THIS DOES NOT CLAIM. It is not defence against a compromised primary agent, which can read its own
+ * environment and would simply forward the capability. It is defence against the two neighbours of the
+ * primary that are NOT it: an unrelated local process, and a sub-agent that escaped its read-only
+ * allowlist. Neither is the primary, and neither is handed the token.
+ */
+/**
+ * The environment variable the capability travels in.
+ *
+ * Named on both sides of the wire rather than imported by the extension, for the reason every one of
+ * these names is written out twice: `agents/` is loaded by Pi's module loader and `src/` by tsc, so a
+ * relative import across the two would resolve differently under each. `scripts/task-tool.test.mjs`
+ * asserts the two copies agree, because a rename on one side would otherwise fail at dispatch time with a
+ * message nobody reads.
+ */
+export const TASK_CAPABILITY_ENV = "SUPER_PI_TASK_CAPABILITY";
+/**
+ * The live capability per conversation, while that conversation's primary turn is running.
+ *
+ * Keyed by CONVERSATION rather than being one global token, so two conversations being driven at once
+ * cannot dispatch as each other and so releasing one turn's capability cannot revoke another's. The value
+ * is replaced rather than accumulated: a conversation has one primary turn in flight, and a second spawn
+ * for the same conversation supersedes the first.
+ */
+const live = new Map();
+/** A fixed capability, for tests. See `seededCapability` for why this does not weaken anything. */
+const SEED = process.env.SUPER_PI_TASK_CAPABILITY_SEED;
+/** Announced once, because a capability that silently stopped rotating is a security change nobody agreed to. */
+let warnedSeed = false;
+/**
+ * Mints the capability for one turn of one conversation, and returns it for the extension's environment.
+ *
+ * CALLED AT SPAWN, so the value is decided before the child exists and cannot be changed underneath it.
+ * A turn that never reaches the spawn mints nothing, which is correct: there is no process to hand it to.
+ *
+ * ROTATED EVERY TURN, and that is the property the duration would not give on its own. A token valid for
+ * the whole server lifetime would still be a token an unrelated process could not guess - but a token
+ * valid only while its holder is alive is a token that stops being a credential the moment the turn ends,
+ * so there is no window in which a leaked value is still live.
+ */
+export function mintCapability(conversationId) {
+    if (SEED) {
+        if (!warnedSeed) {
+            warnedSeed = true;
+            console.warn(`Super Pi: SUPER_PI_TASK_CAPABILITY_SEED is set, so every dispatch capability is the same fixed value instead of being minted per turn. This is for tests - set it only on a server nothing else can reach.`);
+        }
+        live.set(conversationId, SEED);
+        return SEED;
+    }
+    const token = randomUUID();
+    live.set(conversationId, token);
+    return token;
+}
+/**
+ * Forgets a conversation's capability, at the end of its turn.
+ *
+ * CALLED FROM `answer()`'s `finally`, so it runs on every exit - a turn that answered, a turn that threw,
+ * and a turn whose child was killed. A capability that outlived its turn would keep working for a process
+ * that no longer exists, which is precisely the shape of a credential with no owner.
+ */
+export function releaseCapability(conversationId) {
+    live.delete(conversationId);
+}
+/** Forgets every capability. Called on shutdown, so nothing survives the process that minted it. */
+export function releaseAllCapabilities() {
+    live.clear();
+}
+/**
+ * The capability currently valid for a conversation, or `undefined` when no primary turn is running.
+ *
+ * Exported for the endpoint's own diagnostics and for a test that needs to assert the lifecycle without
+ * reading a primary turn's environment. Not exported as a way to READ a conversation's capability and use
+ * it - a caller in this process is already inside the trust boundary it protects.
+ */
+export function capabilityFor(conversationId) {
+    return live.get(conversationId);
+}
+/**
+ * Checks a presented capability against the one this conversation's turn was given.
+ *
+ * `timingSafeEqual` rather than `===`, because `===` on a token short-circuits at the first differing byte
+ * and turns the comparison into a timing oracle for the value itself. The length check runs first because
+ * `timingSafeEqual` throws on mismatched lengths rather than returning false.
+ *
+ * THE MESSAGE NAMES BOTH HALVES OF THE PROBLEM, because the reader is a model about to retry and there
+ * are two genuinely different failures here. A conversation with no live capability is being dispatched
+ * from OUTSIDE a turn - the request never came from a primary agent. A conversation with one, and the
+ * presented value does not match it, is a turn whose value was not carried through. An extension that
+ * silently omitted the header would otherwise be indistinguishable from an attacker, and would keep
+ * retrying forever.
+ */
+export function verifyCapability(conversationId, presented) {
+    // A seeded server accepts its fixed value for EVERY conversation, including one with no turn running.
+    // That relaxation is exactly the test affordance and nothing else: `SEED` is documented as test-only,
+    // and a process that can set it could set `SUPER_PI_ACCESS_TOKEN` instead and already have full control.
+    // The comparison below is still real - a wrong value is still refused - so a seeded server still catches
+    // a request that simply forgot the capability, which is the mistake a real extension is most likely to make.
+    const expected = live.get(conversationId) ?? SEED;
+    if (!expected) {
+        return {
+            ok: false,
+            message: `No primary turn is running for conversation ${conversationId}, so there is nothing that could have dispatched this. Dispatch happens from inside a turn: send the tool call during a turn rather than posting to the server directly.`,
+        };
+    }
+    if (typeof presented !== "string" || !presented) {
+        return { ok: false, message: `This dispatch carries no ${TASK_CAPABILITY_ENV}. The capability is passed from the primary agent's own environment; a request without it did not come from one. Do not retry the same call - it is not a transient failure.` };
+    }
+    const left = Buffer.from(expected);
+    const right = Buffer.from(presented);
+    if (left.length !== right.length || !timingSafeEqual(left, right)) {
+        return { ok: false, message: `The ${TASK_CAPABILITY_ENV} presented does not match the one this turn was given. It is minted per turn, so a value from an earlier turn - or from another conversation - is not accepted. Do not retry the same call.` };
+    }
+    return { ok: true };
+}

package/dist/server/command-handler.js

@@ -113,6 +113,10 @@ export class CommandHandler {
             this.runService.stopSubagent(command.runId);
             return;
         }
+        if (command.type === "workflow.stop") {
+            this.runService.stopWorkflow(command.workflowId);
+            return;
+        }
         if (command.type === "extension.ui.answer") {
             const answer = command.cancelled
                 ? { cancelled: true }

package/dist/server/http-server.js

@@ -76,6 +76,26 @@ export function createHttpServer(options) {
             }
             return;
         }
+        if (url.pathname === "/api/workflow/run") {
+            if (request.method !== "POST" || !isLoopbackAddress(remote)) {
+                response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Workflow dispatch requires a loopback POST");
+                return;
+            }
+            let raw = "";
+            for await (const chunk of request)
+                raw += chunk;
+            const json = (status, body) => {
+                response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
+            };
+            try {
+                const result = await runService.runWorkflow(JSON.parse(raw));
+                json(result.status, result.body);
+            }
+            catch (error) {
+                json(400, { error: error instanceof Error ? error.message : "workflow dispatch failed" });
+            }
+            return;
+        }
         if (url.pathname === "/api/todos") {
             if (request.method !== "POST" || !isLoopbackAddress(remote)) {
                 response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Todo writes require a loopback POST");

package/dist/server/index.js

@@ -4,8 +4,10 @@ import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { defaultStorePath, Store } from "./store.js";
 import { PiRpcRuntime, WelcomeRuntime } from "./runtime.js";
+import { releaseAllCapabilities } from "./capability.js";
 import { SubagentSupervisor } from "./subagents.js";
 import { SubagentRunRecorder } from "./subagent-runs.js";
+import { WorkflowEngine } from "./workflow-engine.js";
 import { ExtensionUiService } from "./application/extension-ui-service.js";
 import { CatalogService } from "./application/catalog-service.js";
 import { RunService } from "./application/run-service.js";
@@ -30,6 +32,7 @@ const uploadsDir = join(dataDir, "uploads");
 await mkdir(uploadsDir, { recursive: true }).catch(() => { });
 const taskEndpoint = `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${port}/api/subagent/dispatch`;
 const todoEndpoint = `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${port}/api/todos`;
+const workflowEndpoint = `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${port}/api/workflow/run`;
 const paths = {
     dataDir,
     rootDir,
@@ -42,7 +45,7 @@ const paths = {
 const store = await Store.open(defaultStorePath(dataDir));
 const runtime = process.env.SUPER_PI_RUNTIME === "welcome"
     ? new WelcomeRuntime()
-    : new PiRpcRuntime(join(dataDir, "pi-sessions"), undefined, { dir: agentsDir, promptDir: agentPromptDir }, { endpoint: taskEndpoint, todoEndpoint, uploadsDir });
+    : new PiRpcRuntime(join(dataDir, "pi-sessions"), undefined, { dir: agentsDir, promptDir: agentPromptDir }, { endpoint: taskEndpoint, todoEndpoint, workflowEndpoint, uploadsDir });
 const broadcaster = new WsBroadcaster(() => store.snapshot());
 const extensionUiService = new ExtensionUiService(broadcaster);
 const supervisor = new SubagentSupervisor(join(dataDir, "pi-sessions"), undefined, {
@@ -58,9 +61,27 @@ const subagents = new SubagentRunRecorder(supervisor, {
     },
     host: (conversationId, runId) => extensionUiService.createHost(conversationId, runId),
 });
+/**
+ * The orchestration engine: walks a whole plan the primary agent declared, dispatching each step through
+ * the recorder above and handing each step's output to the next.
+ *
+ * Broadcasts `workflow.event` AND the full state, exactly as the recorder does for `subagent.event`. The
+ * extra state frame is what puts a plan into `AppState.workflows`, so a browser that reloads mid-plan
+ * rebuilds the timeline from the file rather than from the events it happened to receive - the same reason
+ * a run's card survives a refresh. It costs nothing in practice because the engine publishes twice per
+ * step rather than per delta.
+ */
+const workflows = new WorkflowEngine(subagents, {
+    store,
+    broadcast: (event) => {
+        broadcaster.broadcast(event);
+        if (event.type === "workflow.event")
+            broadcaster.broadcastState();
+    },
+});
 // ------------------------------------------------------------- Application services
 const catalogService = new CatalogService(runtime, broadcaster, agentsDir);
-const runService = new RunService(store, runtime, subagents, broadcaster, extensionUiService);
+const runService = new RunService(store, runtime, subagents, broadcaster, extensionUiService, agentsDir, workflows);
 const conversationService = new ConversationService(store, runtime, subagents, broadcaster, catalogService, runService, extensionUiService, agentsDir);
 const workspaceService = new WorkspaceService(store, runtime, broadcaster, catalogService, runService, extensionUiService, uploadsDir, agentsDir);
 const serverContext = {
@@ -85,6 +106,8 @@ function shutdown(reason) {
     shuttingDown = true;
     console.log(`Super Pi is shutting down (${reason}).`);
     runService.abortAll();
+    workflows.abortAll();
+    releaseAllCapabilities();
     for (const c of store.snapshot().conversations) {
         extensionUiService.cancelPendingUi(c.id, "aborted");
     }

package/dist/server/runtime.d.ts

@@ -612,6 +612,7 @@ export declare class PiRpcRuntime implements AgentRuntime {
     options?: {
         endpoint?: string;
         todoEndpoint?: string;
+        workflowEndpoint?: string;
         uploadsDir?: string;
     });
     /**

package/dist/server/runtime.js

@@ -3,8 +3,9 @@ import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { resolve, join } from "node:path";
 import { agentSpawnArgs, readAgents } from "./agents.js";
+import { TASK_CAPABILITY_ENV, mintCapability, releaseCapability } from "./capability.js";
 import { resolvePiCommand, shellQuote } from "./pi-command.js";
-import { TASK_CONVERSATION_ENV, TASK_DEPTH_ENV, TASK_ENDPOINT_ENV, TASK_ROSTER_ENV, TASK_TOOL_NAME, TODO_ENDPOINT_ENV, TODO_TOOL_NAME, rosterPayload, } from "./task-tool.js";
+import { TASK_CONVERSATION_ENV, TASK_DEPTH_ENV, TASK_ENDPOINT_ENV, TASK_ROSTER_ENV, TASK_TOOL_NAME, TODO_ENDPOINT_ENV, TODO_TOOL_NAME, WORKFLOW_ENDPOINT_ENV, WORKFLOW_TOOL_NAME, rosterPayload, } from "./task-tool.js";
 import { BLOCKING_UI_METHODS, EXTENSION_UI_METHODS, } from "./types.js";
 import { loadConversationImages } from "./upload.js";
 import { describeToolCall, describeToolCallArgs } from "./tool-calls.js";
@@ -683,6 +684,12 @@ export class PiRpcRuntime {
             [TASK_CONVERSATION_ENV]: conversationId,
             [TASK_DEPTH_ENV]: "0",
             [TODO_ENDPOINT_ENV]: this.options.todoEndpoint ?? "",
+            [WORKFLOW_ENDPOINT_ENV]: this.options.workflowEndpoint ?? "",
+            // MINTED HERE, AT SPAWN, rather than read from anywhere: this is the only moment the value is
+            // decided, so it cannot change underneath a running child. `SubagentSupervisor` never calls this
+            // function, so no sub-agent process is ever handed a capability - which is what makes a sub-agent
+            // unable to dispatch, however its allowlist is broken.
+            [TASK_CAPABILITY_ENV]: mintCapability(conversationId),
         };
     }
     async *answer({ conversation, prompt, signal, cwd, host, onPiQueue, onUserEntry, onToolCall, onToolEnd, images }) {
@@ -718,7 +725,7 @@ export class PiRpcRuntime {
         // other. They also share the extension's existence - `extensionArgs` is non-empty exactly when
         // `index.ts` is on disk and an endpoint was configured - so there is no case where one is mounted and
         // the other is not.
-        const agentArgs = await agentSpawnArgs(this.agents.promptDir, agent, { extraAllowedTools: extensionArgs.length ? [TASK_TOOL_NAME, TODO_TOOL_NAME] : [] });
+        const agentArgs = await agentSpawnArgs(this.agents.promptDir, agent, { extraAllowedTools: extensionArgs.length ? [TASK_TOOL_NAME, TODO_TOOL_NAME, WORKFLOW_TOOL_NAME] : [] });
         // Refused here, with the reason, rather than handed to the spawn: an ENOENT from `spawn` reads as
         // "the app is broken" and hides the one fact that matters, which is where it looked for Pi.
         if (!this.pi.found)
@@ -930,6 +937,10 @@ export class PiRpcRuntime {
         finally {
             signal.removeEventListener("abort", abort);
             this.runs.delete(conversation.id);
+            // The capability dies with the turn that was given it. In this `finally`, so it happens on every
+            // exit - a turn that answered, a turn that threw, and a turn whose child was killed - because a
+            // credential whose turn has ended is a credential with no owner.
+            releaseCapability(conversation.id);
             // A steer still unanswered when the turn ends is REJECTED, not left pending. The drain loop above
             // is the only reader of this child's stdout and it has stopped, so nothing would ever settle that
             // promise: the caller would wait for a timeout to learn something this process already knows. The

package/dist/server/store.d.ts

@@ -1,3 +1,4 @@
+import type { WorkflowRun } from "./workflow.js";
 import type { AppState, Conversation, Message, MessageImage, ModelSelection, QueuedMessage, SubagentRun, SubagentRunUpdate, TodoItem, ToolCallBlock, Workspace } from "./types.js";
 /** Mints the id a forked conversation will have, BEFORE its Pi transcript exists.
  *
@@ -31,6 +32,17 @@ export declare function newConversationId(): string;
  * re-deriving it.
  */
 export declare const SUBAGENT_RUN_RETENTION = 100;
+/**
+ * How many orchestrated plans are kept.
+ *
+ * SMALLER THAN THE RUN RETENTION, and deliberately so. A plan does not duplicate the runs it executed -
+ * it holds one row per STEP - so fifty plans point at runs that are themselves evicted at 100. Keeping
+ * more plans than runs would leave timelines whose cards have all been trimmed away, which is a worse
+ * outcome than forgetting the plan: an empty timeline reads as "nothing ran" rather than as "the details
+ * aged out". Fifty is also well past what one working day of orchestration produces, since a plan is a
+ * request that needed several specialists rather than a unit of work.
+ */
+export declare const WORKFLOW_RETENTION = 50;
 /**
  * Everything a revert decided, before anything is changed.
  *
@@ -365,6 +377,36 @@ export declare class Store {
      * back on disk, and one that trimmed on read would show a browser a roster the file still holds.
      */
     beginSubagentRun(run: SubagentRun): Promise<SubagentRun>;
+    /**
+     * Writes a whole plan BEFORE step one runs, and persists it.
+     *
+     * THE ORDER THIS EXISTS TO ENFORCE. A plan recorded only as it executes leaves a reload showing
+     * nothing recoverable - which steps were intended, in what order, under which failure policy - because
+     * a transcript of the model asking for a plan is not the plan. Writing it whole first makes the record
+     * a CLAIM the engine then makes good, exactly the relationship a run has to its child process, and it
+     * means an engine that dies mid-plan leaves a document a person can read instead of a gap.
+     *
+     * Steps arrive already in their pending form with empty `attempts`, rather than being built as the
+     * engine reaches them, so what lands on disk before anything runs is the whole intention.
+     *
+     * `structuredClone` on the way out, like `beginSubagentRun`: the engine mutates its own copy on every
+     * transition, and a caller holding a live reference would watch the record change under itself.
+     */
+    beginWorkflow(plan: WorkflowRun): Promise<WorkflowRun>;
+    /**
+     * Replaces a plan wholesale, and persists it.
+     *
+     * THE WHOLE PLAN RATHER THAN A FIELD PATCH, and the reason is that a plan's live state is three moving
+     * parts at once - `currentIndex`, the status of one step, and an appended attempt - so a patch type
+     * narrow enough to be safe for all three is a shape nothing could be typechecked against. Writing the
+     * plan also cannot forget a field, which is the failure a hand-maintained patch list invites as the
+     * plan grows new parts.
+     *
+     * The whole array is cloned before the write, for the same reason the recorder keeps its own copy of a
+     * run (`subagent-runs.ts:170`): the caller mutates the object it is about to hand back here, and a store
+     * that persisted by reference would write out those edits before they were ever announced.
+     */
+    setWorkflow(plan: WorkflowRun): Promise<WorkflowRun>;
     setBackgroundTask(summary: AppState["backgroundTasks"][number]): Promise<void>;
     removeBackgroundTask(id: string): Promise<void>;
     /**

package/dist/server/store.js

@@ -205,6 +205,96 @@ function trimSubagentRuns(runs, conversations) {
     }
     runs.splice(0, runs.length, ...runs.filter((run) => !doomed.has(run.id)));
 }
+/**
+ * How many orchestrated plans are kept.
+ *
+ * SMALLER THAN THE RUN RETENTION, and deliberately so. A plan does not duplicate the runs it executed -
+ * it holds one row per STEP - so fifty plans point at runs that are themselves evicted at 100. Keeping
+ * more plans than runs would leave timelines whose cards have all been trimmed away, which is a worse
+ * outcome than forgetting the plan: an empty timeline reads as "nothing ran" rather than as "the details
+ * aged out". Fifty is also well past what one working day of orchestration produces, since a plan is a
+ * request that needed several specialists rather than a unit of work.
+ */
+export const WORKFLOW_RETENTION = 50;
+/**
+ * Evicts settled plans down to `WORKFLOW_RETENTION`, newest first.
+ *
+ * A `running` plan is NEVER evicted, for the reason runs are not: that row is the claim startup
+ * reconciliation looks for, and forgetting it would leave a plan that claims to be executing with nothing
+ * executing it - the one state that is unreconcilable rather than merely stale.
+ *
+ * Unlike `trimSubagentRuns` this makes no attempt to favour live conversations. A plan's own steps name
+ * the runs they dispatched, so an evicted plan is the one thing that must survive as long as the cards it
+ * explains; the flat newest-N bound keeps that simple and keeps the bound honest.
+ */
+function trimWorkflows(workflows) {
+    const settled = workflows.filter((plan) => plan?.status !== "running");
+    const excess = settled.length - WORKFLOW_RETENTION;
+    if (excess <= 0)
+        return;
+    const doomed = new Set();
+    for (const plan of [...settled].reverse()) {
+        if (doomed.size >= excess)
+            break;
+        doomed.add(plan.id);
+    }
+    workflows.splice(0, workflows.length, ...workflows.filter((plan) => !doomed.has(plan.id)));
+}
+/**
+ * Why a plan the previous process left `running` is stopped rather than resumed, in the same spirit and
+ * for the same audience as `ORPHANED_RUN_ERROR`.
+ *
+ * It says the work was NOT finished, not that it failed. The distinction matters to the person reading
+ * it: a verifier that never reported is a question left open, while a patcher that reported and was then
+ * interrupted is a question already answered. The plan keeps every attempt it made, so what is actually
+ * known is still on the timeline underneath this line.
+ */
+const ORPHANED_WORKFLOW_ERROR = "服务器上次退出时这个编排仍在运行；它的步骤已经随进程消失，本次编排被标记为停止，没有自动续跑。";
+/**
+ * Startup reconciliation: every plan the previous process left `running` is an orphan.
+ *
+ * THE SAME ARGUMENT AS `reconcileSubagentRuns`, applied one level up. A plan marked `running` is a claim
+ * that a loop is walking it, and no such loop can survive the process that owned it.
+ *
+ * WHY `stopped` AND NOT `failed`, which is the one place this deliberately differs from a run. A failed
+ * step is a verdict the sub-agent reached; nothing here was reached, so calling it failed would report a
+ * conclusion that does not exist. `stopped` is the status this project already uses for work that was
+ * cut short rather than completed, and it is what the timeline's own stop button produces, so a plan
+ * abandoned by a crash looks like the thing it actually is: halted, with its steps' work intact.
+ *
+ * Steps are NOT rewritten. A step left `running` keeps that status - it is the true account of the child
+ * process that is gone - while every step still `pending` becomes `stopped`, because those never started
+ * and leaving them `pending` would show a plan as still having work ahead of it that nothing will do.
+ */
+function reconcileWorkflows(state) {
+    // LEFT ABSENT WHEN IT WAS ABSENT, which is the opposite of `reconcileSubagentRuns` and deliberate. That
+    // one assigns unconditionally because `subagentRuns` is a required field that must be an array. This one
+    // is optional, and the project rule for optional lists is the one `setTodos` states: absence and an
+    // empty list mean the same thing to every reader, so the key is DELETED rather than stored as `[]`. A
+    // server that has never run an orchestration should not leave behind a `workflows: []` claiming it has
+    // considered plans and found none - and writing one would mean this sweep marked the file changed and
+    // persisted it, for a key that did not need to exist.
+    if (!Array.isArray(state.workflows)) {
+        // A present-but-not-an-array value is still normalized, because `state.json` is read blind and a
+        // hand edit or an older build can leave anything here; ignoring it would let it reach every reader.
+        if (state.workflows !== undefined)
+            state.workflows = [];
+        return [];
+    }
+    const orphaned = [];
+    for (const plan of state.workflows) {
+        if (!plan || plan.status !== "running")
+            continue;
+        for (const step of plan.steps ?? []) {
+            if (step?.status === "pending")
+                step.status = "stopped";
+        }
+        plan.status = "stopped";
+        plan.finishedAt = now();
+        orphaned.push(plan);
+    }
+    return orphaned;
+}
 /**
  * Startup reconciliation for the follow-up queue: an entry the previous process left `sending` goes
  * back to `queued`.
@@ -350,6 +440,7 @@ export class Store {
             // Reconciling them in separate writes would put a file on disk in which one kind of orphan was fixed
             // and the other was not - a half-repaired state that still needs a second restart to finish.
             const orphaned = reconcileSubagentRuns(state);
+            const orphanedWorkflows = reconcileWorkflows(state);
             const interrupted = reconcileConversations(state);
             const requeued = reconcileQueuedMessages(state);
             const todos = reconcileTodos(state);
@@ -357,9 +448,11 @@ export class Store {
             // Persisted here, in `open`, rather than left for the first unrelated write: a reconciled record that
             // is only rewritten by a later mutation would still read `running` to anything that opened the file
             // in the meantime, and would be reconciled a SECOND time on the next restart.
-            if (orphaned.length || interrupted.length || requeued.recovered.length || requeued.changed || todos.changed) {
+            if (orphaned.length || orphanedWorkflows.length || interrupted.length || requeued.recovered.length || requeued.changed || todos.changed) {
                 for (const run of orphaned)
                     console.warn(`Super Pi: sub-agent run ${run.id} was still marked running when the last server stopped - it is now failed, because no child process survived it.`);
+                for (const plan of orphanedWorkflows)
+                    console.warn(`Super Pi: workflow ${plan.id} was still marked running when the last server stopped - it is now stopped, because no step can still be executing.`);
                 // Announced for the same reason: a conversation that failed while nobody was watching is invisible
                 // otherwise, and the user who was watching a spinner when the server died deserves to learn that
                 // their run is over rather than guessing from the fact that it stopped moving.
@@ -988,6 +1081,56 @@ export class Store {
         // store mutates in place on the next delta, or a run's "snapshot" would change under it.
         return structuredClone(run);
     }
+    /**
+     * Writes a whole plan BEFORE step one runs, and persists it.
+     *
+     * THE ORDER THIS EXISTS TO ENFORCE. A plan recorded only as it executes leaves a reload showing
+     * nothing recoverable - which steps were intended, in what order, under which failure policy - because
+     * a transcript of the model asking for a plan is not the plan. Writing it whole first makes the record
+     * a CLAIM the engine then makes good, exactly the relationship a run has to its child process, and it
+     * means an engine that dies mid-plan leaves a document a person can read instead of a gap.
+     *
+     * Steps arrive already in their pending form with empty `attempts`, rather than being built as the
+     * engine reaches them, so what lands on disk before anything runs is the whole intention.
+     *
+     * `structuredClone` on the way out, like `beginSubagentRun`: the engine mutates its own copy on every
+     * transition, and a caller holding a live reference would watch the record change under itself.
+     */
+    async beginWorkflow(plan) {
+        if (!this.state.workflows)
+            this.state.workflows = [];
+        if (this.state.workflows.some((item) => item?.id === plan.id))
+            throw new Error(`Workflow already recorded: ${plan.id}`);
+        this.state.workflows.unshift(plan);
+        trimWorkflows(this.state.workflows);
+        await this.persist();
+        return structuredClone(plan);
+    }
+    /**
+     * Replaces a plan wholesale, and persists it.
+     *
+     * THE WHOLE PLAN RATHER THAN A FIELD PATCH, and the reason is that a plan's live state is three moving
+     * parts at once - `currentIndex`, the status of one step, and an appended attempt - so a patch type
+     * narrow enough to be safe for all three is a shape nothing could be typechecked against. Writing the
+     * plan also cannot forget a field, which is the failure a hand-maintained patch list invites as the
+     * plan grows new parts.
+     *
+     * The whole array is cloned before the write, for the same reason the recorder keeps its own copy of a
+     * run (`subagent-runs.ts:170`): the caller mutates the object it is about to hand back here, and a store
+     * that persisted by reference would write out those edits before they were ever announced.
+     */
+    async setWorkflow(plan) {
+        if (!this.state.workflows)
+            this.state.workflows = [];
+        const stored = structuredClone(plan);
+        const index = this.state.workflows.findIndex((item) => item?.id === stored.id);
+        if (index < 0)
+            throw new Error(`Workflow not found: ${stored.id}`);
+        this.state.workflows[index] = stored;
+        trimWorkflows(this.state.workflows);
+        await this.persist();
+        return structuredClone(stored);
+    }
     async setBackgroundTask(summary) {
         const existing = this.state.backgroundTasks.find((item) => item.id === summary.id);
         if (existing)

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

@@ -62,6 +62,27 @@ export declare const TASK_ROSTER_ENV = "SUPER_PI_TASK_ROSTER";
 export declare const TASK_CONVERSATION_ENV = "SUPER_PI_TASK_CONVERSATION";
 /** How many task hops deep this process already is. A primary is `0`. See `DEFAULT_SUBAGENT_DEPTH`. */
 export declare const TASK_DEPTH_ENV = "SUPER_PI_TASK_DEPTH";
+/**
+ * The name the model calls to hand an ordered plan of sub-agent steps to the server.
+ *
+ * A THIRD tool rather than an extra parameter on `task`, and the reason is what the server does with the
+ * two. `task` is one delegation whose result the model reads back and acts on itself; `workflow` is a
+ * plan the server walks, carrying each step's output into the next without the model in the middle. One
+ * tool with a `steps` array would make every single delegation carry a shape it cannot use, and would make
+ * "dispatch one agent" and "run this pipeline" indistinguishable in the transcript - which is the opposite
+ * of what the model needs to choose between them.
+ */
+export declare const WORKFLOW_TOOL_NAME = "workflow";
+/**
+ * The endpoint the `workflow` tool dials. A FIFTH name in the same wire as the four above, written out on
+ * both sides for the same reason.
+ *
+ * A SEPARATE variable rather than a path derived from `TASK_ENDPOINT_ENV`, for the reason
+ * `TODO_ENDPOINT_ENV` already states: a Pi can legitimately be started with a dispatch endpoint and no
+ * workflow endpoint, and a derived path could not tell that apart from a misconfiguration. The tool then
+ * refuses in words instead of posting somewhere that does not exist.
+ */
+export declare const WORKFLOW_ENDPOINT_ENV = "SUPER_PI_WORKFLOW_ENDPOINT";
 /**
  * One entry of the roster the model is shown: what it types into `subagent_type`, and when to pick it.
  *