@evandu/super-pi 0.1.142 → 0.1.144

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

@@ -3,129 +3,45 @@ 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.
+ * Recursive descent over the primary's plan. This engine owns execution order and the mechanical `until`
+ * comparison; it does not infer tasks, discover foreach items, or ask a child whether another round should
+ * run. Spawning, streaming and teardown remain behind `SubagentRunRecorder.dispatch`, which always resolves
+ * with a settled record.
  */
-/** 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;
+    private readonly owners;
     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;
-    /** Waits until aborted plans have committed their terminal state. */
     waitForIdle(): Promise<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.
-     */
+    /** Allocates execution rows once per statically known occurrence; loop occurrences are allocated per round. */
+    private materializeNodes;
+    private runNodes;
+    private runLoop;
+    private runForeach;
     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.
-     */
+    /** Persist first, announce second, so a reload never contradicts an event already shown. */
     private commit;
 }

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 });