@evandu/super-pi 0.1.141 → 0.1.143

package/dist/server/workflow-engine.js

@@ -1,32 +1,14 @@
-import { attemptFromRun, composeStepPrompt, newWorkflowRunId, retriesFor, } from "./workflow.js";
+import { attemptFromRun, composeStepPrompt, newWorkflowRunId, retriesFor, substituteWorkflowVariables, workflowUntilMet, WORKFLOW_DEFAULT_LOOP_MAX, } 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();
+    owners = 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)
@@ -34,7 +16,6 @@ export class WorkflowEngine {
         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) {
@@ -45,36 +26,17 @@ export class WorkflowEngine {
         }
         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();
     }
-    /** Waits until aborted plans have committed their terminal state. */
     async waitForIdle() {
-        while (this.controllers.size > 0) {
+        while (this.controllers.size > 0)
             await new Promise((resolve) => setTimeout(resolve, 10));
-        }
     }
-    /** 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();
@@ -84,63 +46,34 @@ export class WorkflowEngine {
             controller.abort();
         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 definitions = input.plan.nodes ?? input.plan.steps.map((step) => ({ kind: "step", ...step }));
         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",
-            })),
+            steps: [],
             currentIndex: 0,
             startedAt: now(),
         };
+        // The complete definition and every statically known iteration are persisted before the first dispatch.
+        // Loop rounds are materialized as they begin because their number depends on prior conclusion lines.
+        plan.nodes = this.materializeNodes(definitions, plan);
         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.
+            const history = [];
+            await this.runNodes(plan.nodes, plan, input, controller.signal, {}, history);
             if (controller.signal.aborted || plan.steps.some((step) => step.status === "stopped")) {
-                this.haltRemaining(plan, plan.currentIndex);
+                this.haltRemaining(plan);
                 plan.status = "stopped";
             }
             else if (plan.steps.every((step) => step.status === "completed" || step.status === "skipped")) {
                 plan.status = "completed";
             }
             else {
-                this.haltRemaining(plan, plan.currentIndex);
+                this.haltRemaining(plan);
                 plan.status = "failed";
             }
             plan.finishedAt = now();
@@ -153,30 +86,116 @@ export class WorkflowEngine {
             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) {
+    /** Allocates execution rows once per statically known occurrence; loop occurrences are allocated per round. */
+    materializeNodes(definitions, plan) {
+        return definitions.map((definition) => {
+            if (definition.kind === "step") {
+                const stepIndex = plan.steps.length;
+                plan.steps.push({
+                    index: stepIndex,
+                    agentId: definition.agentId,
+                    ...(definition.label ? { label: definition.label } : {}),
+                    prompt: definition.prompt,
+                    attempts: [],
+                    status: "pending",
+                });
+                return { kind: "step", stepIndex };
+            }
+            if (definition.kind === "foreach") {
+                return {
+                    kind: "foreach",
+                    items: [...definition.items],
+                    iterations: definition.items.map((item) => ({ item, nodes: this.materializeNodes(definition.do, plan) })),
+                };
+            }
+            return {
+                kind: "loop",
+                until: definition.until,
+                max: definition.max ?? WORKFLOW_DEFAULT_LOOP_MAX,
+                do: structuredClone(definition.do),
+                rounds: [],
+            };
+        });
+    }
+    async runNodes(nodes, plan, input, signal, variables, history) {
+        let output;
+        for (const node of nodes) {
+            if (signal.aborted)
+                return { halted: true, output };
+            let result;
+            if (node.kind === "step") {
+                const step = plan.steps[node.stepIndex];
+                result = await this.runStep(plan, step, input, signal, variables, history);
+                if (!result.halted) {
+                    history.push(step);
+                    plan.currentIndex = history.length;
+                    await this.commit(plan);
+                }
+            }
+            else if (node.kind === "loop") {
+                result = await this.runLoop(node, plan, input, signal, variables, history);
+            }
+            else {
+                result = await this.runForeach(node, plan, input, signal, variables, history);
+            }
+            // The last node's output replaces the earlier one even when it is absent; an empty final node must
+            // not accidentally satisfy `until` by exposing an older sibling's conclusion.
+            output = result.output;
+            if (result.halted)
+                return { halted: true, output };
+        }
+        return { halted: false, output };
+    }
+    async runLoop(node, plan, input, signal, variables, history) {
+        let last = "";
+        let output;
+        for (let n = 1; n <= node.max; n += 1) {
+            if (signal.aborted)
+                return { halted: true, output };
+            const round = { n, nodes: this.materializeNodes(node.do, plan), untilMet: false };
+            node.rounds.push(round);
+            await this.commit(plan);
+            const result = await this.runNodes(round.nodes, plan, input, signal, { ...variables, last }, history);
+            output = result.output;
+            if (output !== undefined)
+                round.output = output;
+            round.untilMet = !result.halted && workflowUntilMet(output, node.until);
+            await this.commit(plan);
+            if (result.halted)
+                return { halted: true, output };
+            if (round.untilMet)
+                return { halted: false, output };
+            last = output ?? "";
+        }
+        // Exhausting the declared bound is a completed bounded plan, with every round's untilMet=false visible.
+        return { halted: false, output };
+    }
+    async runForeach(node, plan, input, signal, variables, history) {
+        let output;
+        for (const iteration of node.iterations) {
+            if (signal.aborted)
+                return { halted: true, output };
+            const result = await this.runNodes(iteration.nodes, plan, input, signal, { ...variables, item: iteration.item }, history);
+            output = result.output;
+            if (result.halted)
+                return { halted: true, output };
+        }
+        return { halted: false, output };
+    }
+    async runStep(plan, step, input, signal, variables, history) {
         const retries = retriesFor(plan.onFailure);
         let attempt = 0;
         while (attempt <= retries) {
             if (signal.aborted) {
                 step.status = "stopped";
                 await this.commit(plan);
-                return true;
+                return { halted: 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));
-            // A retry receives the failed attempt's evidence, rather than repeating a blind prompt.
+            plan.currentIndex = history.length;
+            const prompt = substituteWorkflowVariables(step.prompt, variables);
+            const composed = composeStepPrompt(prompt, history);
             const previousAttempt = step.attempts.at(-1);
             if (previousAttempt) {
                 const evidence = [previousAttempt.error, previousAttempt.output].filter(Boolean).join("\n").slice(-8000);
@@ -189,77 +208,46 @@ export class WorkflowEngine {
                 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));
+            const output = step.attempts.at(-1)?.output;
             if (run.status === "completed") {
                 step.status = "completed";
                 await this.commit(plan);
-                return false;
+                return { halted: false, output };
             }
             if (run.status === "stopped") {
                 step.status = "stopped";
                 await this.commit(plan);
-                return true;
+                return { halted: true, output };
             }
-            // 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;
+                return { halted: false, output };
             }
             step.status = "failed";
             await this.commit(plan);
-            return true;
+            return { halted: true, output };
         }
-        // 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;
+        return { halted: 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))
+    haltRemaining(plan) {
+        for (const step of plan.steps)
             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.
-     */
+    /** Persist first, announce second, so a reload never contradicts an event already shown. */
     async commit(plan) {
         const persisted = await this.hooks.store.setWorkflow(plan);
         this.hooks.broadcast({ type: "workflow.event", workflow: persisted });

package/dist/server/workflow.d.ts

@@ -1,37 +1,14 @@
 import type { SubagentRosterEntry } from "./task-tool.js";
 import type { SubagentRun } from "./types.js";
 /**
- * The workflow PLAN: an ordered list of sub-agent steps the server will execute on the primary agent's
- * behalf, carrying each step's output into the next one.
+ * The workflow PLAN: a tree of steps, bounded loops and primary-supplied foreach iterations. The server
+ * executes the tree; it never asks a sub-agent to choose the control flow. Step outputs are still carried
+ * into later prompts, and every rule in this file remains pure so validation and conclusion matching can
+ * be tested without spawning a process.
  *
- * WHY THIS FILE EXISTS, and why it holds no I/O at all.
- *
- * The dispatch pipe was already built and already proved: `task-tool.ts` is the policy half of the mouth,
- * `subagent-runs.ts` records and publishes a run, `subagents.ts` spawns and drains a child. What was
- * missing was that a MODEL, given a request that needs three different specialists in a row, had to
- * remember the order itself and hand-copy each result into the next prompt by hand. That is the
- * orchestration gap - and the reason the seam here is pure is the same reason `task-tool.ts` is: every
- * rule in this file can then be proved without spawning a process, which is the only layer where a
- * plan's shape, its refusals and its truncation budgets are cheap to test exhaustively.
- *
- * WHAT IS BORROWED FROM OPENCODE, and what is not: nothing. That is a deliberate departure from the
- * sibling files, which each cite upstream lines they ported. OpenCode has no multi-sub-agent pipeline
- * primitive to port - it composes `task` calls the same way this project did, by model convention, which
- * is the gap. What this file reuses instead is local: the roster filter from `task-tool.ts` (the same one
- * that decides who may be dispatched), and the `SubagentRunRecorder.dispatch` seam, which always resolves
- * with a settled record and therefore needs no error parsing here.
- *
- * WHAT THIS FILE DELIBERATELY DOES NOT MODEL, because `docs/AGENT_LOOP_DESIGN.md` proposed all of it and
- * each one is a second orchestration authority rather than a capability:
- *
- * - BRANCHES AND EDGES. A declared graph makes the model learn a language to express sequencing it can
- *   already express by dispatching twice. It also cannot be expressive enough, and a model that finds it
- *   too rigid bypasses it, leaving two ways to orchestrate that behave differently.
- * - LOOP-BACK. `verifier.md` already ends its report with `通过`/`失败`, so the model can read a failed
- *   step and decide whether to run another round. That judgement is the thing worth keeping on the side
- *   that can read the output; encoding it as an edge would move it to a component that never sees the text.
- * - A SEPARATE ARTIFACT STORE. `WorkflowAttempt` below IS the versioned artefact: one attempt's output is
- *   written once and never edited, and the next attempt appends beside it rather than replacing it.
+ * The dispatch and persistence seams are the existing ones: `task-tool.ts` supplies the roster,
+ * `SubagentRunRecorder.dispatch` settles every child, and `WorkflowAttempt` is the append-only artefact.
+ * There is deliberately no graph, expression language, server-side item discovery, or second artefact store.
  */
 /**
  * The id an orchestrated plan answers to.
@@ -54,6 +31,9 @@ export declare const WORKFLOW_ID_PATTERN: RegExp;
  * one it would hit by accident.
  */
 export declare const WORKFLOW_MAX_STEPS = 8;
+/** A loop always has a finite bound. The primary may lower it or explicitly raise it to this hard cap. */
+export declare const WORKFLOW_DEFAULT_LOOP_MAX = 8;
+export declare const WORKFLOW_MAX_LOOP_ROUNDS = 100;
 /**
  * What happens to a step that failed.
  *
@@ -130,12 +110,44 @@ export type WorkflowRun = {
     summary: string;
     onFailure: WorkflowFailurePolicy;
     status: WorkflowStatus;
+    /** Execution rows. The tree below references these by index rather than duplicating attempts and output. */
     steps: WorkflowStep[];
-    /** Which step is executing or next. `steps.length` means the plan is past its last step. */
+    /** Optional only for records written before recursive plans existed. */
+    nodes?: WorkflowRunNode[];
+    /** Number of settled execution rows; while running, the row currently executing or next. */
     currentIndex: number;
     startedAt: string;
     finishedAt?: string;
 };
+export type WorkflowStepRef = {
+    kind: "step";
+    stepIndex: number;
+};
+export type WorkflowLoopRound = {
+    n: number;
+    nodes: WorkflowRunNode[];
+    /** The round's last node output. Missing output can never satisfy `until`. */
+    output?: string;
+    untilMet: boolean;
+};
+export type WorkflowLoopRun = {
+    kind: "loop";
+    until: string;
+    max: number;
+    /** The primary's body definition, retained so future rounds survive a reload with the whole plan. */
+    do: WorkflowPlanNode[];
+    rounds: WorkflowLoopRound[];
+};
+export type WorkflowForeachIteration = {
+    item: string;
+    nodes: WorkflowRunNode[];
+};
+export type WorkflowForeachRun = {
+    kind: "foreach";
+    items: string[];
+    iterations: WorkflowForeachIteration[];
+};
+export type WorkflowRunNode = WorkflowStepRef | WorkflowLoopRun | WorkflowForeachRun;
 /** One step as the primary agent is told about it: the last attempt, not the whole history. */
 export type WorkflowStepSummary = {
     n: number;
@@ -165,15 +177,36 @@ export type WorkflowSummary = {
     steps: WorkflowStepSummary[];
     finishedAt?: string;
 };
+export type WorkflowStepPlan = {
+    kind: "step";
+    agentId: string;
+    label?: string;
+    prompt: string;
+};
+export type WorkflowLoopPlan = {
+    kind: "loop";
+    until: string;
+    max?: number;
+    do: WorkflowPlanNode[];
+};
+export type WorkflowForeachPlan = {
+    kind: "foreach";
+    items: string[];
+    do: WorkflowPlanNode[];
+};
+export type WorkflowPlanNode = WorkflowStepPlan | WorkflowLoopPlan | WorkflowForeachPlan;
 /** The plan shape the engine executes, after validation. What `validateWorkflowPlan` returns on success. */
 export type WorkflowPlan = {
     summary: string;
     onFailure: WorkflowFailurePolicy;
+    /** Legacy input, and a flat declaration index for recursive input. Runtime executions live on WorkflowRun. */
     steps: {
         agentId: string;
         label?: string;
         prompt: string;
     }[];
+    /** Present when the primary used the recursive spelling. Legacy steps are normalized by the engine. */
+    nodes?: WorkflowPlanNode[];
 };
 /**
  * Text that had to lose its front, plus what it lost and why.
@@ -219,6 +252,15 @@ export declare const WORKFLOW_CONTEXT_BUDGET = 32000;
 export declare const PREVIOUS_TOKEN = "{{previous}}";
 /** The token that hands a step every prior step's output, with nothing prepended. */
 export declare const HISTORY_TOKEN = "{{history}}";
+export declare const ITEM_TOKEN = "{{item}}";
+export declare const LAST_TOKEN = "{{last}}";
+/** Single-pass replacement: token-looking text inside an item or prior output is data, not another expression. */
+export declare function substituteWorkflowVariables(prompt: string, variables: {
+    item?: string;
+    last?: string;
+}): string;
+/** Exact whole-line matching against the final line. Empty or missing output is false, never an error. */
+export declare function workflowUntilMet(output: string | undefined, until: string): boolean;
 /** What a composed prompt ended up carrying, so a caller can report it without re-parsing the string. */
 export type ComposedPrompt = {
     prompt: string;