@evandu/super-pi 0.1.1 → 0.1.3

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

package/dist/server/workflow.d.ts

@@ -0,0 +1,287 @@
+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.
+ *
+ * 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 id an orchestrated plan answers to.
+ *
+ * Prefixed and uuid-shaped for the same reason run ids are: the string is a lookup key in `state.json`
+ * and appears in `data-*` attributes in the browser, and a shape a person can recognise in a log is worth
+ * more than a bare uuid. `engine.ts` validates caller-supplied ids against this prefix the way
+ * `subagents.ts:358` validates run ids, because the same string becomes a reconciliation key at startup.
+ */
+export declare const newWorkflowRunId: () => string;
+/** Matches the shape `newWorkflowRunId` produces, for validating a caller-supplied id. */
+export declare const WORKFLOW_ID_PATTERN: RegExp;
+/**
+ * How many steps one plan may hold.
+ *
+ * A bound, because every step is a real Pi process that runs for minutes and every step's output is
+ * carried forward: the cost of a plan grows with both its length and the size of what it accumulates.
+ * Eight steps is more than the pipelines this install's four sub-agents are built for (`scout` to
+ * `patcher` to `verifier`, maybe twice), so the bound is one a real request would not reach rather than
+ * one it would hit by accident.
+ */
+export declare const WORKFLOW_MAX_STEPS = 8;
+/**
+ * What happens to a step that failed.
+ *
+ * `stop` is the DEFAULT and it is the honest one. `docs/AGENT_LOOP_DESIGN.md` named the failure this
+ * guards against in a sentence worth keeping: "A failed step never silently advances with missing input."
+ * Continuing past a failed step means the next sub-agent is handed a hole it cannot see, and the plan
+ * reports success. So a caller that says nothing about failure gets the behaviour that cannot lie.
+ */
+export type WorkflowFailurePolicy = "stop" | "skip" | "retry:1" | "retry:2" | "retry:3";
+/** Every accepted policy, in the order the refusal message lists them for a model that guesses wrong. */
+export declare const WORKFLOW_FAILURE_POLICIES: readonly WorkflowFailurePolicy[];
+/**
+ * Reads a failure policy, or `undefined` for anything that is not one.
+ *
+ * `retry` alone normalizes to `retry:1`: a model that reaches for retry almost always means "try it
+ * again once", and refusing over a missing count would cost a retry of the plan itself. Everything else
+ * is refused rather than coerced, because guessing `stop` for a model that asked for `parallel` would
+ * silently run a different plan than the one it wrote.
+ */
+export declare function parseFailurePolicy(raw: unknown): WorkflowFailurePolicy | undefined;
+/** How many times a policy re-runs a failing step. `stop` and `skip` both run it zero further times. */
+export declare function retriesFor(policy: WorkflowFailurePolicy): number;
+/** Where a whole plan ended. `running` is the only state from which it advances on its own. */
+export type WorkflowStatus = "running" | "completed" | "failed" | "stopped";
+/** Where one step ended. `skipped` means the policy chose to walk past it after a failure. */
+export type WorkflowStepStatus = "pending" | "running" | "completed" | "failed" | "skipped" | "stopped";
+/**
+ * One try at one step.
+ *
+ * THE ARTEFACT, AND THE REASON THERE IS NO ARTIFACT STORE. A failed `verifier` that is retried has two
+ * different answers - the first one found two failing assertions, the second found none - and the first
+ * is exactly what makes the second legible. So an attempt is written once and never edited, and a retry
+ * appends beside the attempt it replaced instead of overwriting it. `n` is the attempt number within its
+ * step, not a global counter, so one step's history reads 1, 2, 3 without knowing anything about its neighbours.
+ */
+export type WorkflowAttempt = {
+    /** 1-based within the step. Attempt 1 is the first try, not a zero-th. */
+    n: number;
+    /** The `SubagentRun` this attempt produced. Absent only when the dispatch was refused before a run row existed. */
+    runId?: string;
+    /** How the run settled. Never `running`: `dispatch` resolves only once the child is terminal. */
+    status: "completed" | "failed" | "stopped";
+    /** The child's final message. Carried forward to later steps, and read by the primary agent afterwards. */
+    output?: string;
+    outputTruncated?: boolean;
+    startedAt: string;
+    finishedAt?: string;
+    /** Why this attempt did not complete. Present only beside a `failed` or `stopped` status. */
+    error?: string;
+};
+/** One step of a plan. Its `attempts` array is append-only; `status` is the derived summary of it. */
+export type WorkflowStep = {
+    index: number;
+    agentId: string;
+    /** An opaque label for a person to read. The engine never branches on it. */
+    label?: string;
+    /** The prompt as the model wrote it, before any prior output is composed into it. */
+    prompt: string;
+    attempts: WorkflowAttempt[];
+    status: WorkflowStepStatus;
+};
+/**
+ * A whole orchestrated plan, as persisted.
+ *
+ * The plan is written in full BEFORE step one runs, and that is the point of the record: progression is
+ * controlled by the server walking this structure, not by conventions inside successive prompts, so a
+ * browser that reloads mid-plan reads an accurate account of what was intended and not merely what
+ * happened to be written in a transcript so far.
+ */
+export type WorkflowRun = {
+    id: string;
+    conversationId: string;
+    /** One line describing what the whole plan is for, shown to a person above the timeline. */
+    summary: string;
+    onFailure: WorkflowFailurePolicy;
+    status: WorkflowStatus;
+    steps: WorkflowStep[];
+    /** Which step is executing or next. `steps.length` means the plan is past its last step. */
+    currentIndex: number;
+    startedAt: string;
+    finishedAt?: string;
+};
+/** One step as the primary agent is told about it: the last attempt, not the whole history. */
+export type WorkflowStepSummary = {
+    n: number;
+    agentId: string;
+    label?: string;
+    status: WorkflowStepStatus;
+    /** How many tries this step took. Above one, the step failed before it passed, and that is visible. */
+    attempts: number;
+    output?: string;
+    outputTruncated?: boolean;
+    error?: string;
+};
+/**
+ * What the endpoint hands back so the extension can render one envelope.
+ *
+ * The last attempt's output rather than all of them, for the same reason the conversation transcript is
+ * not re-sent into every turn: the primary agent needs to know what the pipeline concluded, and the
+ * earlier attempts are already in the run records and the timeline. Rendering happens on the extension
+ * side because the envelope is the tool's return value, not the server's - the same split
+ * `task-tool.ts:17-19` states for `<task>`.
+ */
+export type WorkflowSummary = {
+    id: string;
+    summary: string;
+    status: WorkflowStatus;
+    onFailure: WorkflowFailurePolicy;
+    steps: WorkflowStepSummary[];
+    finishedAt?: string;
+};
+/** The plan shape the engine executes, after validation. What `validateWorkflowPlan` returns on success. */
+export type WorkflowPlan = {
+    summary: string;
+    onFailure: WorkflowFailurePolicy;
+    steps: {
+        agentId: string;
+        label?: string;
+        prompt: string;
+    }[];
+};
+/**
+ * Text that had to lose its front, plus what it lost and why.
+ *
+ * `truncated` is carried rather than inferred from length so a CALLER can announce the loss. The house
+ * rule here is the one `task-tool.ts:102-116` already follows for an over-long roster: a payload that
+ * quietly omits part of itself makes a reader act on a belief that is not true, with no way to notice.
+ */
+export type CappedText = {
+    text: string;
+    truncated: boolean;
+    droppedChars: number;
+};
+/**
+ * Caps a block of text from the FRONT, and says in the surviving text that something was dropped.
+ *
+ * THE TAIL IS WHAT SURVIVES, and that is not an arbitrary choice. Every sub-agent in `agents/` is written
+ * to put its conclusion last - `verifier.md` says its last line is `通过`/`失败`/`无法验证` and nothing
+ * else - so keeping the end of a report keeps the part the next step and the human both need. Cutting
+ * from the end would keep the preamble and discard the verdict, which is the one line that matters.
+ */
+export declare function capText(text: string, budget: number, what: string): CappedText;
+export declare const stepStatusWord: (status: WorkflowStepStatus) => string;
+export declare const workflowStatusWord: (status: WorkflowStatus) => string;
+/**
+ * Per-step cap on how much of one prior output is carried into the next step's prompt.
+ *
+ * Eight KB is roughly two thousand tokens of Chinese prose or a little more of code, which is enough for
+ * the conclusion-plus-evidence shape every sub-agent in `agents/` is instructed to produce, and small
+ * enough that eight of them plus the plan itself stay inside a normal model's working context.
+ */
+export declare const STEP_OUTPUT_BUDGET = 8000;
+/**
+ * Total cap across all carried-forward output in one step's prompt.
+ *
+ * Separate from the per-step cap because the per-step one alone does not bound anything: eight steps
+ * carrying 8 KB each is 64 KB, which is larger than the whole context most sub-agents run with. The
+ * budget is spent newest-first, so the immediately preceding step - the one whose conclusion the current
+ * step is most likely acting on - is never the one that loses characters.
+ */
+export declare const WORKFLOW_CONTEXT_BUDGET = 32000;
+/** The token that hands a step exactly the previous step's output, with nothing prepended. */
+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}}";
+/** What a composed prompt ended up carrying, so a caller can report it without re-parsing the string. */
+export type ComposedPrompt = {
+    prompt: string;
+    /** How many prior steps actually contributed output. */
+    handedOff: number;
+    /** Whether anything was dropped for space. */
+    truncated: boolean;
+};
+/**
+ * Composes the prompt one step actually runs with, carrying earlier results into it.
+ *
+ * THE DEFAULT IS THE HANDOFF BLOCK, and the two tokens are the opt-outs. A model that does nothing
+ * special gets every prior step's output prepended, because "did the model remember to copy the last
+ * result forward" is not a property worth trusting a multi-step plan to. A model that WANTS control -
+ * wants the last output and nothing else, or wants the whole history verbatim - says so with a token,
+ * and in exchange the automatic block is suppressed entirely rather than being added alongside. Both
+ * spellings keep one rule intact: whatever this returns is the complete prompt, never a prefix that
+ * hides some of the instruction.
+ *
+ * AN EMPTY FIRST STEP IS THE PROMPT, VERBATIM. Composing a handoff header onto step one would tell a
+ * sub-agent about previous steps that do not exist, and would spend its attention on the header.
+ */
+export declare function composeStepPrompt(prompt: string, prior: readonly WorkflowStep[]): ComposedPrompt;
+/**
+ * A plan that survived validation, or a sentence telling a MODEL what to fix.
+ *
+ * The refusal half exists because this value's first reader is a model about to retry: every message
+ * names what was wrong AND what an acceptable value looks like, following the rule `task-tool.ts:142`
+ * states for the depth refusal. `agents` is supplied in full even when the mistake is one member of it,
+ * because a model that guessed `scouter` has one correct answer and should not have to infer it.
+ */
+export type ValidatedPlan = {
+    plan: WorkflowPlan;
+    refusal?: undefined;
+} | {
+    plan?: undefined;
+    refusal: string;
+};
+/**
+ * Checks an untrusted plan body against the roster that may actually be dispatched.
+ *
+ * VALIDATES, NEVER REWRITES, THE AGENT LIST. `agentId` is matched against the roster rather than
+ * defaulted, because defaulting would run a different sub-agent than the model asked for - a plan that
+ * silently substituted `patcher` for a misspelled `patchre` would edit files on a read-only request.
+ * The roster arrives already filtered to `mode: subagent` and non-hidden (`task-tool.ts:88`), so a
+ * primary agent's id is refused here by the same rule that refuses it at dispatch time
+ * (`subagents.ts:368`) - one lock, consulted twice, rather than a second list that could drift.
+ */
+export declare function validateWorkflowPlan(raw: unknown, roster: readonly SubagentRosterEntry[]): ValidatedPlan;
+/**
+ * Reduces a persisted plan to what the primary agent is told when the workflow returns.
+ *
+ * ONE ATTEMPT PER STEP, THE LAST ONE. The earlier attempts stay in the run records and on the timeline,
+ * which is where a person debugging a retried plan looks; putting all of them in the envelope would make
+ * the model re-read a failure it has already acted on.
+ */
+export declare function workflowSummary(plan: WorkflowRun): WorkflowSummary;
+/**
+ * The step a settled run became, as an attempt record.
+ *
+ * The narrow seam between the run recorder and this engine: everything about spawning, streaming and
+ * process teardown is the recorder's, and the only thing that crosses here is the settled record it
+ * always resolves with (`subagent-runs.ts:159`). `output` is copied rather than referenced because the
+ * store hands out clones, and a plan that kept a live reference would read whatever the run wrote next.
+ */
+export declare function attemptFromRun(run: SubagentRun, n: number): WorkflowAttempt;