@evandu/super-pi 0.1.142 → 0.1.143

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;

package/dist/server/workflow.js

@@ -1,36 +1,13 @@
 import { randomUUID } from "node:crypto";
 /**
- * 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.
@@ -53,6 +30,9 @@ export const WORKFLOW_ID_PATTERN = /^wf_[A-Za-z0-9_-]{1,120}$/;
  * one it would hit by accident.
  */
 export 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 const WORKFLOW_DEFAULT_LOOP_MAX = 8;
+export const WORKFLOW_MAX_LOOP_ROUNDS = 100;
 /** Every accepted policy, in the order the refusal message lists them for a model that guesses wrong. */
 export const WORKFLOW_FAILURE_POLICIES = ["stop", "skip", "retry:1", "retry:2", "retry:3"];
 /**
@@ -135,6 +115,19 @@ export const WORKFLOW_CONTEXT_BUDGET = 32_000;
 export const PREVIOUS_TOKEN = "{{previous}}";
 /** The token that hands a step every prior step's output, with nothing prepended. */
 export const HISTORY_TOKEN = "{{history}}";
+export const ITEM_TOKEN = "{{item}}";
+export const LAST_TOKEN = "{{last}}";
+/** Single-pass replacement: token-looking text inside an item or prior output is data, not another expression. */
+export function substituteWorkflowVariables(prompt, variables) {
+    return prompt.replace(/\{\{(item|last)\}\}/g, (_token, name) => variables[name] ?? "");
+}
+/** Exact whole-line matching against the final line. Empty or missing output is false, never an error. */
+export function workflowUntilMet(output, until) {
+    const text = output?.trim();
+    if (!text)
+        return false;
+    return (text.split(/\r?\n/).at(-1)?.trim() ?? "") === until;
+}
 /**
  * Renders one prior step as a block, or as a sentence when it has no output to hand on.
  *
@@ -288,6 +281,90 @@ function fillHistoryToken(prompt, ran) {
     const replacement = blocks.join("\n\n");
     return { text: replacement ? prompt.split(HISTORY_TOKEN).join(replacement) : prompt.split(HISTORY_TOKEN).join("（这是编排的第一步，前面还没有任何产出。）"), used, truncated };
 }
+/** Validates the complete tree before the engine can allocate even its first pending execution row. */
+function validateRecursivePlan(body, roster) {
+    const ids = roster.map((entry) => entry.id);
+    const available = ids.length ? ids.join(", ") : "(none)";
+    const onFailure = body.onFailure === undefined ? "stop" : parseFailurePolicy(body.onFailure);
+    if (!onFailure)
+        return { refusal: `workflow.onFailure must be one of ${WORKFLOW_FAILURE_POLICIES.join(", ")}, or "retry" on its own for a single retry. Got ${JSON.stringify(body.onFailure)}. "stop" is used when you leave it out.` };
+    if (!Array.isArray(body.nodes))
+        return { refusal: `workflow.nodes must be an array of at least one step, loop or foreach node. Got ${body.nodes === undefined ? "nothing" : typeof body.nodes}.` };
+    if (!body.nodes.length)
+        return { refusal: "workflow.nodes was empty. A workflow needs at least one node; for a single sub-agent, call the task tool instead." };
+    const steps = [];
+    const visit = (raw, where) => {
+        if (typeof raw !== "object" || raw === null)
+            return { refusal: `${where} must be a step, loop or foreach object. Got ${raw === null ? "null" : typeof raw}.` };
+        const entry = raw;
+        if (entry.kind === "step") {
+            const agentId = typeof entry.agentId === "string" ? entry.agentId.trim() : "";
+            if (!agentId)
+                return { refusal: `${where}.agentId is required. Dispatchable sub-agents: ${available}.` };
+            if (!ids.includes(agentId))
+                return { refusal: `${JSON.stringify(agentId)} is not a dispatchable sub-agent (${where}.agentId). Dispatchable sub-agents: ${available}. Pick one of those, or call the task tool directly for a single delegation.` };
+            const prompt = typeof entry.prompt === "string" ? entry.prompt.trim() : "";
+            if (!prompt)
+                return { refusal: `${where}.prompt is required and must not be empty: the sub-agent starts with a fresh context, so this is everything it will know about the work.` };
+            const label = typeof entry.label === "string" ? entry.label.trim() : "";
+            steps.push({ agentId, prompt, ...(label ? { label } : {}) });
+            return { node: { kind: "step", agentId, prompt, ...(label ? { label } : {}) } };
+        }
+        if (entry.kind === "loop") {
+            const until = typeof entry.until === "string" ? entry.until.trim() : "";
+            if (!until)
+                return { refusal: `${where}.until is required: write the exact conclusion line the server should match, for example "通过".` };
+            const max = entry.max === undefined ? WORKFLOW_DEFAULT_LOOP_MAX : entry.max;
+            if (typeof max !== "number" || !Number.isInteger(max) || max < 1 || max > WORKFLOW_MAX_LOOP_ROUNDS) {
+                return { refusal: `${where}.max must be an integer from 1 to ${WORKFLOW_MAX_LOOP_ROUNDS}. Leave it out for the default of ${WORKFLOW_DEFAULT_LOOP_MAX}.` };
+            }
+            if (!Array.isArray(entry.do) || !entry.do.length)
+                return { refusal: `${where}.do must be a non-empty array of nodes; a loop body may contain several steps, loops or foreaches.` };
+            const children = [];
+            for (let index = 0; index < entry.do.length; index += 1) {
+                const child = visit(entry.do[index], `${where}.do[${index}]`);
+                if (!child.node)
+                    return { refusal: child.refusal ?? `${where} is invalid.` };
+                children.push(child.node);
+            }
+            return { node: { kind: "loop", until, max, do: children } };
+        }
+        if (entry.kind === "foreach") {
+            if (!Array.isArray(entry.items) || !entry.items.length) {
+                return { refusal: `${where}.items must be a non-empty string array supplied by the primary agent. The server never discovers a foreach list; a foreach without items is refused.` };
+            }
+            const items = [];
+            for (let index = 0; index < entry.items.length; index += 1) {
+                const item = entry.items[index];
+                if (typeof item !== "string" || !item.trim())
+                    return { refusal: `${where}.items[${index}] must be a non-empty string explicitly supplied by the primary agent.` };
+                items.push(item);
+            }
+            if (!Array.isArray(entry.do) || !entry.do.length)
+                return { refusal: `${where}.do must be a non-empty array of nodes to run once for each primary-supplied item.` };
+            const children = [];
+            for (let index = 0; index < entry.do.length; index += 1) {
+                const child = visit(entry.do[index], `${where}.do[${index}]`);
+                if (!child.node)
+                    return { refusal: child.refusal ?? `${where} is invalid.` };
+                children.push(child.node);
+            }
+            return { node: { kind: "foreach", items, do: children } };
+        }
+        return { refusal: `${where}.kind must be exactly "step", "loop" or "foreach". Got ${JSON.stringify(entry.kind)}.` };
+    };
+    const nodes = [];
+    for (let index = 0; index < body.nodes.length; index += 1) {
+        const result = visit(body.nodes[index], `workflow.nodes[${index}]`);
+        if (!result.node)
+            return { refusal: result.refusal ?? `workflow.nodes[${index}] is invalid.` };
+        nodes.push(result.node);
+        if (steps.length > WORKFLOW_MAX_STEPS)
+            return { refusal: `workflow.nodes declares more than ${WORKFLOW_MAX_STEPS} step nodes and the limit is ${WORKFLOW_MAX_STEPS}. Shorten the plan, or split it into two workflows.` };
+    }
+    const summary = typeof body.summary === "string" && body.summary.trim() ? body.summary.trim().slice(0, 200) : `${steps.length} 步编排`;
+    return { plan: { summary, onFailure, steps, nodes } };
+}
 /**
  * Checks an untrusted plan body against the roster that may actually be dispatched.
  *
@@ -304,6 +381,11 @@ export function validateWorkflowPlan(raw, roster) {
     if (typeof raw !== "object" || raw === null)
         return { refusal: `A workflow must be an object with "summary", "onFailure" and "steps". Got ${raw === null ? "null" : typeof raw}.` };
     const body = raw;
+    if (body.nodes !== undefined) {
+        if (body.steps !== undefined)
+            return { refusal: "workflow accepts either legacy `steps` or recursive `nodes`, not both. Send one plan shape so there is only one execution order." };
+        return validateRecursivePlan(body, roster);
+    }
     const rawSteps = body.steps;
     if (!Array.isArray(rawSteps))
         return { refusal: `workflow.steps must be an array of at least 1 and at most ${WORKFLOW_MAX_STEPS} steps. Got ${rawSteps === undefined ? "nothing" : typeof rawSteps}.` };