@evandu/super-pi 0.1.1 → 0.1.2

package/dist/server/task-tool.js

@@ -61,6 +61,27 @@ export const TASK_ROSTER_ENV = "SUPER_PI_TASK_ROSTER";
 export const TASK_CONVERSATION_ENV = "SUPER_PI_TASK_CONVERSATION";
 /** How many task hops deep this process already is. A primary is `0`. See `DEFAULT_SUBAGENT_DEPTH`. */
 export const TASK_DEPTH_ENV = "SUPER_PI_TASK_DEPTH";
+/**
+ * The 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 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 const WORKFLOW_ENDPOINT_ENV = "SUPER_PI_WORKFLOW_ENDPOINT";
 /**
  * The dispatchable roster, in the order it will be injected.
  *

package/dist/server/types.d.ts

@@ -1,3 +1,4 @@
+import type { WorkflowRun } from "./workflow.js";
 export type RunStatus = "idle" | "running" | "completed" | "stopped" | "failed";
 export type MessageRole = "user" | "assistant" | "tool" | "system";
 /**
@@ -477,6 +478,16 @@ export type BackgroundTaskSummary = {
     startedAt: string;
     resultBlockId: string;
 };
+/**
+ * Orchestrated plans, optional for the same reason `todos` is: a `state.json` written before this
+ * feature existed has no `workflows` key, and must read correctly rather than looking like an install
+ * that has considered a plan and found none. Absence and an empty list mean the same thing to every
+ * reader, so the store deletes the key rather than storing `[]`.
+ *
+ * The workflow's own types live in `workflow.ts` next to the rules that build them. This is a type-only
+ * import and is erased at compile time, so it does not close a runtime cycle with the rules that
+ * construct them - the same relationship `SubagentRun` already has with `subagent-runs.ts`.
+ */
 export type AppState = {
     workspaces: Workspace[];
     conversations: Conversation[];
@@ -484,6 +495,7 @@ export type AppState = {
     queuedMessages: QueuedMessage[];
     backgroundTasks: BackgroundTaskSummary[];
     todos?: TodoItem[];
+    workflows?: WorkflowRun[];
 };
 export type TodoItem = {
     id?: string;
@@ -790,6 +802,12 @@ export type ClientCommand = {
     type: "subagent.stop";
     runId: string;
 }
+/** Stops one orchestrated plan. Distinct from `subagent.stop` because the engine holds the loop and
+ *  the signal, and stopping only the run would leave the plan marching on to the next step. */
+ | {
+    type: "workflow.stop";
+    workflowId: string;
+}
 /** Asks for the `mode: subagent` half of the agent directory. Answered by `subagent.catalog`. */
  | {
     type: "subagent.catalog.fetch";
@@ -905,6 +923,22 @@ export type ServerEvent = {
     type: "subagent.event";
     run: SubagentRun;
 }
+/**
+ * The current SNAPSHOT of one orchestrated plan, sent on every step transition and nothing else.
+ *
+ * WHOLE SNAPSHOT, like `subagent.event`, for the same reason: a timeline assembled from missed events
+ * is a timeline that can be wrong, and this one has to survive a reload and a reconnect race.
+ *
+ * ON TRANSITIONS ONLY, never on a stream delta, and that asymmetry is deliberate rather than an
+ * oversight. A step's own progress already arrives as `subagent.event` for the run it is executing, so
+ * a workflow event on every delta would broadcast the whole plan - every step's output, accumulated -
+ * once per TOKEN of one child. That is the one way this feature could make the app feel broken. Two
+ * events per step (begin, settle) is what a timeline actually needs; the rest is the run card's job.
+ */
+ | {
+    type: "workflow.event";
+    workflow: WorkflowRun;
+}
 /**
  * Pi's own queue snapshot, forwarded the moment `queue_update` arrives on the child's stdout.
  *

package/dist/server/workflow-engine.d.ts

@@ -0,0 +1,129 @@
+import type { SubagentRunRecorder } from "./subagent-runs.js";
+import type { Store } from "./store.js";
+import type { ModelSelection, ServerEvent } from "./types.js";
+import { type WorkflowPlan, type WorkflowRun } from "./workflow.js";
+/**
+ * Walking an orchestrated plan: the half of the feature that DECIDES anything.
+ *
+ * WHY THIS FILE HOLDS NO SPAWNING, NO STREAMING AND NO PROCESS TEARDOWN. Every one of those already
+ * exists and is already proved - `subagents.ts` spawns and drains, `subagent-runs.ts` records and
+ * publishes. The engine's whole job is to call `dispatch` in the right ORDER and decide what to do when
+ * a step does not succeed, and `SubagentRunRecorder.dispatch` is the seam that makes that possible: it
+ * ALWAYS RESOLVES with a settled record, including for a dispatch that never started (`subagent-runs.ts:159`).
+ * So an engine step is `await` one call, read `status` off the record, and move on. There is no error
+ * parsing here, no exception handling around a spawn, and no way for a child to be left running because
+ * the thing above it threw - which is the entire reason this feature is small.
+ *
+ * WHAT THE ENGINE IS NOT ALLOWED TO DO, stated as the two rules it is built around:
+ *
+ * 1. IT DOES NOT DECIDE WHAT A STEP MEANS. `role` is written through to the run record and read by
+ *    nobody in this process. A step that says "verify" and a step that says "look at it" execute the same
+ *    way. The rules about who does what live in `agents/*.md` and in the model that wrote the plan, not
+ *    in a dispatcher holding a table of role names.
+ * 2. IT DOES NOT JUDGE RESULTS. A `verifier` step that completes with 结论：失败 has SUCCEEDED, as far as
+ *    this loop is concerned, and the plan advances. The verdict lives in the text, and the component that
+ *    can read the text - the primary agent - is what decides whether to run another round. A server that
+ *    parsed 通过/失败 would be guessing at a convention `verifier.md` states in prose and `scout.md` and
+ *    `critic.md` do not have at all, and would have no correct answer when the text said neither.
+ */
+/** What the engine needs from the server around it. Injected, so this file holds no globals. */
+export type WorkflowEngineHooks = {
+    store: Store;
+    /** Publishes one event to whoever is listening. A plain function, so a test can pass an array. */
+    broadcast: (event: ServerEvent) => void;
+};
+/** Everything one plan needs to run. The plan itself arrives already validated and normalized. */
+export type WorkflowRunInput = {
+    conversationId: string;
+    /** The dispatching conversation's workspace, resolved by the caller. Never defaulted to the server's own directory. */
+    cwd: string;
+    plan: WorkflowPlan;
+    model?: ModelSelection;
+    /** Tools the primary agent denied, inherited by every step, exactly as a single dispatch inherits them. */
+    denyTools?: readonly string[];
+    /** Cancels the whole plan. Each step is dispatched under it, so one signal reaches the loop and the child. */
+    signal?: AbortSignal;
+};
+/** The outcome of a plan, as the endpoint reports it. Always produced, never thrown. */
+export type WorkflowOutcome = {
+    workflow: WorkflowRun;
+};
+export declare class WorkflowEngine {
+    private readonly recorder;
+    private readonly hooks;
+    /**
+     * One controller per in-flight plan.
+     *
+     * NEEDED SEPARATELY FROM THE RECORDER'S, and the difference is what stops a plan between steps. The
+     * recorder's map only holds runs that are executing right now, so a plan halted by a signal while no
+     * child is out would have nothing to abort and would happily start the next one. This map holds the
+     * PLAN, which exists for its whole length, so `stop` reaches it in every phase.
+     */
+    private readonly controllers;
+    constructor(recorder: SubagentRunRecorder, hooks: WorkflowEngineHooks);
+    /**
+     * Stops ONE plan, and says whether there was anything to stop.
+     *
+     * `false` for an unknown or already-finished id is deliberate and matches `SubagentRunRecorder.stop`:
+     * the click that produces it raced the plan's own terminal event, and an error reply would put a
+     * failure banner on a timeline that says it finished normally.
+     *
+     * The abort reaches the child too, because every step is dispatched under this controller's signal and
+     * `dispatch` turns it into the same abort-then-killTree the recorder uses. Stopping a plan really does
+     * stop the process it is on.
+     */
+    stop(workflowId: string): boolean;
+    /** Stops every plan in flight for one conversation, and returns how many were signalled. */
+    stopConversation(conversationId: string): number;
+    /** Aborts every plan in flight. Called on shutdown, so no child outlives the server that owns it. */
+    abortAll(): void;
+    /** The conversation a plan belongs to, which only this map knows while the plan is running. */
+    private conversationOf;
+    /**
+     * Which conversation each in-flight plan belongs to.
+     *
+     * Held beside the controllers rather than read back from the store, because the store is the right
+     * place for what a person may read later and the wrong place for a synchronous lookup in a stop
+     * handler - it clones the entire state, and this runs on a click.
+     */
+    private readonly owners;
+    /**
+     * Executes one plan to a terminal state, and returns the record as it ended.
+     *
+     * ALWAYS RESOLVES, like `dispatch` does and for the same reason: by the time the first await runs, the
+     * whole plan is already on disk, so the honest account of a plan that cannot proceed is a record that
+     * says why, rather than a rejection that leaves it claiming to be running until the next restart.
+     */
+    run(input: WorkflowRunInput): Promise<WorkflowOutcome>;
+    /**
+     * Runs one step until it succeeds, is skipped, or stops the plan. Returns whether the PLAN should halt.
+     *
+     * The retry is a loop rather than a recursive call so the bound in the policy is the loop's own
+     * condition and cannot be exceeded by a bug in the call structure - the one property a retry policy has
+     * to have absolutely.
+     */
+    private runStep;
+    /**
+     * Marks every step from `from` onward as stopped, because none of them will run.
+     *
+     * LEAVING THEM `pending` WOULD BE A LIE IN THE SPECIFIC DIRECTION THAT MATTERS: a browser renders
+     * "未开始" for a pending step, so a plan that died after step one of three would show three steps with
+     * two still waiting, and a person would reasonably expect the rest to happen. They will not.
+     */
+    private haltRemaining;
+    /**
+     * Persists a plan, THEN announces it.
+     *
+     * PERSIST FIRST, ANNOUNCE SECOND, and the order is load-bearing here for exactly the reason it is in
+     * `SubagentRunRecorder.settle`: a browser that is told a step finished while `state.json` still says it
+     * is running will show a timeline a reload immediately contradicts, and the startup reconciliation that
+     * would fix it runs on a SERVER restart, not a page refresh.
+     *
+     * Unlike the recorder, this AWAITS both halves rather than writing fire-and-forget, and that is not an
+     * inconsistency. The recorder cannot await: it publishes on every text delta, and a drain loop that
+     * flushed to disk per token would throttle the child it is streaming. This publishes twice per step -
+     * at most sixteen times for a whole plan - so awaiting costs nothing measurable and buys the strong
+     * version of the guarantee.
+     */
+    private commit;
+}

package/dist/server/workflow-engine.js

@@ -0,0 +1,253 @@
+import { attemptFromRun, composeStepPrompt, newWorkflowRunId, retriesFor, } from "./workflow.js";
+const now = () => new Date().toISOString();
+export class WorkflowEngine {
+    recorder;
+    hooks;
+    /**
+     * One controller per in-flight plan.
+     *
+     * NEEDED SEPARATELY FROM THE RECORDER'S, and the difference is what stops a plan between steps. The
+     * recorder's map only holds runs that are executing right now, so a plan halted by a signal while no
+     * child is out would have nothing to abort and would happily start the next one. This map holds the
+     * PLAN, which exists for its whole length, so `stop` reaches it in every phase.
+     */
+    controllers = new Map();
+    constructor(recorder, hooks) {
+        this.recorder = recorder;
+        this.hooks = hooks;
+    }
+    /**
+     * Stops ONE plan, and says whether there was anything to stop.
+     *
+     * `false` for an unknown or already-finished id is deliberate and matches `SubagentRunRecorder.stop`:
+     * the click that produces it raced the plan's own terminal event, and an error reply would put a
+     * failure banner on a timeline that says it finished normally.
+     *
+     * The abort reaches the child too, because every step is dispatched under this controller's signal and
+     * `dispatch` turns it into the same abort-then-killTree the recorder uses. Stopping a plan really does
+     * stop the process it is on.
+     */
+    stop(workflowId) {
+        const controller = this.controllers.get(workflowId);
+        if (!controller)
+            return false;
+        controller.abort();
+        return true;
+    }
+    /** Stops every plan in flight for one conversation, and returns how many were signalled. */
+    stopConversation(conversationId) {
+        let stopped = 0;
+        for (const [id, controller] of this.controllers) {
+            if (this.conversationOf(id) === conversationId) {
+                controller.abort();
+                stopped += 1;
+            }
+        }
+        return stopped;
+    }
+    /** Aborts every plan in flight. Called on shutdown, so no child outlives the server that owns it. */
+    abortAll() {
+        for (const controller of this.controllers.values())
+            controller.abort();
+    }
+    /** The conversation a plan belongs to, which only this map knows while the plan is running. */
+    conversationOf(workflowId) {
+        return this.owners.get(workflowId);
+    }
+    /**
+     * Which conversation each in-flight plan belongs to.
+     *
+     * Held beside the controllers rather than read back from the store, because the store is the right
+     * place for what a person may read later and the wrong place for a synchronous lookup in a stop
+     * handler - it clones the entire state, and this runs on a click.
+     */
+    owners = new Map();
+    /**
+     * Executes one plan to a terminal state, and returns the record as it ended.
+     *
+     * ALWAYS RESOLVES, like `dispatch` does and for the same reason: by the time the first await runs, the
+     * whole plan is already on disk, so the honest account of a plan that cannot proceed is a record that
+     * says why, rather than a rejection that leaves it claiming to be running until the next restart.
+     */
+    async run(input) {
+        const id = newWorkflowRunId();
+        const controller = new AbortController();
+        const onCallerAbort = () => controller.abort();
+        input.signal?.addEventListener("abort", onCallerAbort, { once: true });
+        this.controllers.set(id, controller);
+        this.owners.set(id, input.conversationId);
+        // THE WHOLE PLAN, IN FULL, BEFORE STEP ONE RUNS. See `Store.beginWorkflow`: this is the write that
+        // makes the record a claim the loop makes good rather than a log that fills in after the fact.
+        const plan = {
+            id,
+            conversationId: input.conversationId,
+            summary: input.plan.summary,
+            onFailure: input.plan.onFailure,
+            status: "running",
+            steps: input.plan.steps.map((step, index) => ({
+                index,
+                agentId: step.agentId,
+                ...(step.label ? { label: step.label } : {}),
+                prompt: step.prompt,
+                attempts: [],
+                status: "pending",
+            })),
+            currentIndex: 0,
+            startedAt: now(),
+        };
+        try {
+            // The INSERT, distinct from every later `commit`: this is the one write that makes the plan exist,
+            // and it happens before the loop rather than inside it. Separate from `commit` rather than folded
+            // into it because "insert if absent" is a different store operation with a different failure mode -
+            // a `commit` that upserted would let a plan start executing without ever having been written down.
+            const created = await this.hooks.store.beginWorkflow(plan);
+            this.hooks.broadcast({ type: "workflow.event", workflow: created });
+            for (let index = 0; index < plan.steps.length; index += 1) {
+                // Checked BEFORE each step, not only after one: a plan stopped between two children must not
+                // start the second one, and the signal that stopped it may have arrived while no child was out.
+                if (controller.signal.aborted)
+                    break;
+                const halted = await this.runStep(plan, plan.steps[index], input, controller.signal);
+                if (halted)
+                    break;
+                plan.currentIndex = index + 1;
+                await this.commit(plan);
+            }
+            // The terminal status is DERIVED, not set optimistically as the loop goes. A plan that finished all
+            // its steps including deliberate skips is `completed` - skips are the plan's own declared intent,
+            // not a shortfall. A plan that ran out of steps because one failed under a `stop` policy is `failed`.
+            //
+            // BEING HALTED OUTRANKS ALL OF IT, and it is keyed on a STEP that ended `stopped` rather than only
+            // on this engine's own signal - because a plan can be halted by a button that never touches the
+            // engine at all. Pressing stop on a step's OWN run card aborts the child through the recorder, which
+            // settles that run as `stopped`; the engine's controller is still perfectly un-aborted at that point.
+            // Keying only on the signal reported that plan as `failed`, which is a verdict nothing established:
+            // the work was not broken, a person stopped it. So the test is whether anything in the plan ended
+            // `stopped`, whoever did the stopping.
+            if (controller.signal.aborted || plan.steps.some((step) => step.status === "stopped")) {
+                this.haltRemaining(plan, plan.currentIndex);
+                plan.status = "stopped";
+            }
+            else if (plan.steps.every((step) => step.status === "completed" || step.status === "skipped")) {
+                plan.status = "completed";
+            }
+            else {
+                this.haltRemaining(plan, plan.currentIndex);
+                plan.status = "failed";
+            }
+            plan.finishedAt = now();
+            await this.commit(plan);
+            return { workflow: structuredClone(plan) };
+        }
+        finally {
+            input.signal?.removeEventListener("abort", onCallerAbort);
+            this.controllers.delete(id);
+            this.owners.delete(id);
+        }
+    }
+    /**
+     * Runs one step until it succeeds, is skipped, or stops the plan. Returns whether the PLAN should halt.
+     *
+     * The retry is a loop rather than a recursive call so the bound in the policy is the loop's own
+     * condition and cannot be exceeded by a bug in the call structure - the one property a retry policy has
+     * to have absolutely.
+     */
+    async runStep(plan, step, input, signal) {
+        const retries = retriesFor(plan.onFailure);
+        let attempt = 0;
+        while (attempt <= retries) {
+            if (signal.aborted) {
+                step.status = "stopped";
+                await this.commit(plan);
+                return true;
+            }
+            attempt += 1;
+            step.status = "running";
+            plan.currentIndex = step.index;
+            // Recomposed EVERY attempt, not once before the loop. A retry exists because the first answer was
+            // not acceptable, so handing the second attempt the same inputs would make the policy a no-op that
+            // burns the same sub-agent's answer twice and reports it as progress.
+            const composed = composeStepPrompt(step.prompt, plan.steps.slice(0, step.index));
+            await this.commit(plan);
+            const run = await this.recorder.dispatch({
+                conversationId: input.conversationId,
+                cwd: input.cwd,
+                agentId: step.agentId,
+                task: composed.prompt,
+                dispatchedBy: "model",
+                // The two fields that were carried in every run record from the start and read by nothing until
+                // now. A step's run therefore names the plan it belongs to and the label the model gave it, which
+                // is what lets the timeline link a card back to its step without any new field on `SubagentRun`.
+                loopId: plan.id,
+                role: step.label,
+                model: input.model,
+                denyTools: input.denyTools,
+                signal,
+            });
+            // Appended, never assigned over: the attempt that failed is exactly what makes the retry legible,
+            // and it is the record a person reads when a verifier failed twice.
+            step.attempts.push(attemptFromRun(run, attempt));
+            if (run.status === "completed") {
+                step.status = "completed";
+                await this.commit(plan);
+                return false;
+            }
+            if (run.status === "stopped") {
+                step.status = "stopped";
+                await this.commit(plan);
+                return true;
+            }
+            // Failed. The policy decides whether this step is tried again, walked past, or ends the plan.
+            if (attempt <= retries) {
+                await this.commit(plan);
+                continue;
+            }
+            if (plan.onFailure === "skip") {
+                // Marked `skipped` rather than `failed`, because the two mean different things to what comes
+                // after: a skipped step contributed no output and says so in the next step's handoff block, while
+                // a failed one contributed output that failed. Both are visible; conflating them would lose which.
+                step.status = "skipped";
+                await this.commit(plan);
+                return false;
+            }
+            step.status = "failed";
+            await this.commit(plan);
+            return true;
+        }
+        // Unreachable: the loop returns on every path that sets a terminal step status, and the bound is
+        // checked on entry. Present so a future edit that adds a path fails to compile rather than silently
+        // leaving a step `running` with no plan status to match it.
+        step.status = "failed";
+        return true;
+    }
+    /**
+     * Marks every step from `from` onward as stopped, because none of them will run.
+     *
+     * LEAVING THEM `pending` WOULD BE A LIE IN THE SPECIFIC DIRECTION THAT MATTERS: a browser renders
+     * "未开始" for a pending step, so a plan that died after step one of three would show three steps with
+     * two still waiting, and a person would reasonably expect the rest to happen. They will not.
+     */
+    haltRemaining(plan, from) {
+        for (const step of plan.steps.slice(from))
+            if (step.status === "pending" || step.status === "running")
+                step.status = "stopped";
+    }
+    /**
+     * Persists a plan, THEN announces it.
+     *
+     * PERSIST FIRST, ANNOUNCE SECOND, and the order is load-bearing here for exactly the reason it is in
+     * `SubagentRunRecorder.settle`: a browser that is told a step finished while `state.json` still says it
+     * is running will show a timeline a reload immediately contradicts, and the startup reconciliation that
+     * would fix it runs on a SERVER restart, not a page refresh.
+     *
+     * Unlike the recorder, this AWAITS both halves rather than writing fire-and-forget, and that is not an
+     * inconsistency. The recorder cannot await: it publishes on every text delta, and a drain loop that
+     * flushed to disk per token would throttle the child it is streaming. This publishes twice per step -
+     * at most sixteen times for a whole plan - so awaiting costs nothing measurable and buys the strong
+     * version of the guarantee.
+     */
+    async commit(plan) {
+        const persisted = await this.hooks.store.setWorkflow(plan);
+        this.hooks.broadcast({ type: "workflow.event", workflow: persisted });
+    }
+}