@evandu/super-pi 0.1.1 → 0.1.3

package/dist/server/store.js

@@ -205,6 +205,96 @@ function trimSubagentRuns(runs, conversations) {
     }
     runs.splice(0, runs.length, ...runs.filter((run) => !doomed.has(run.id)));
 }
+/**
+ * How many orchestrated plans are kept.
+ *
+ * SMALLER THAN THE RUN RETENTION, and deliberately so. A plan does not duplicate the runs it executed -
+ * it holds one row per STEP - so fifty plans point at runs that are themselves evicted at 100. Keeping
+ * more plans than runs would leave timelines whose cards have all been trimmed away, which is a worse
+ * outcome than forgetting the plan: an empty timeline reads as "nothing ran" rather than as "the details
+ * aged out". Fifty is also well past what one working day of orchestration produces, since a plan is a
+ * request that needed several specialists rather than a unit of work.
+ */
+export const WORKFLOW_RETENTION = 50;
+/**
+ * Evicts settled plans down to `WORKFLOW_RETENTION`, newest first.
+ *
+ * A `running` plan is NEVER evicted, for the reason runs are not: that row is the claim startup
+ * reconciliation looks for, and forgetting it would leave a plan that claims to be executing with nothing
+ * executing it - the one state that is unreconcilable rather than merely stale.
+ *
+ * Unlike `trimSubagentRuns` this makes no attempt to favour live conversations. A plan's own steps name
+ * the runs they dispatched, so an evicted plan is the one thing that must survive as long as the cards it
+ * explains; the flat newest-N bound keeps that simple and keeps the bound honest.
+ */
+function trimWorkflows(workflows) {
+    const settled = workflows.filter((plan) => plan?.status !== "running");
+    const excess = settled.length - WORKFLOW_RETENTION;
+    if (excess <= 0)
+        return;
+    const doomed = new Set();
+    for (const plan of [...settled].reverse()) {
+        if (doomed.size >= excess)
+            break;
+        doomed.add(plan.id);
+    }
+    workflows.splice(0, workflows.length, ...workflows.filter((plan) => !doomed.has(plan.id)));
+}
+/**
+ * Why a plan the previous process left `running` is stopped rather than resumed, in the same spirit and
+ * for the same audience as `ORPHANED_RUN_ERROR`.
+ *
+ * It says the work was NOT finished, not that it failed. The distinction matters to the person reading
+ * it: a verifier that never reported is a question left open, while a patcher that reported and was then
+ * interrupted is a question already answered. The plan keeps every attempt it made, so what is actually
+ * known is still on the timeline underneath this line.
+ */
+const ORPHANED_WORKFLOW_ERROR = "服务器上次退出时这个编排仍在运行；它的步骤已经随进程消失，本次编排被标记为停止，没有自动续跑。";
+/**
+ * Startup reconciliation: every plan the previous process left `running` is an orphan.
+ *
+ * THE SAME ARGUMENT AS `reconcileSubagentRuns`, applied one level up. A plan marked `running` is a claim
+ * that a loop is walking it, and no such loop can survive the process that owned it.
+ *
+ * WHY `stopped` AND NOT `failed`, which is the one place this deliberately differs from a run. A failed
+ * step is a verdict the sub-agent reached; nothing here was reached, so calling it failed would report a
+ * conclusion that does not exist. `stopped` is the status this project already uses for work that was
+ * cut short rather than completed, and it is what the timeline's own stop button produces, so a plan
+ * abandoned by a crash looks like the thing it actually is: halted, with its steps' work intact.
+ *
+ * Steps are NOT rewritten. A step left `running` keeps that status - it is the true account of the child
+ * process that is gone - while every step still `pending` becomes `stopped`, because those never started
+ * and leaving them `pending` would show a plan as still having work ahead of it that nothing will do.
+ */
+function reconcileWorkflows(state) {
+    // LEFT ABSENT WHEN IT WAS ABSENT, which is the opposite of `reconcileSubagentRuns` and deliberate. That
+    // one assigns unconditionally because `subagentRuns` is a required field that must be an array. This one
+    // is optional, and the project rule for optional lists is the one `setTodos` states: absence and an
+    // empty list mean the same thing to every reader, so the key is DELETED rather than stored as `[]`. A
+    // server that has never run an orchestration should not leave behind a `workflows: []` claiming it has
+    // considered plans and found none - and writing one would mean this sweep marked the file changed and
+    // persisted it, for a key that did not need to exist.
+    if (!Array.isArray(state.workflows)) {
+        // A present-but-not-an-array value is still normalized, because `state.json` is read blind and a
+        // hand edit or an older build can leave anything here; ignoring it would let it reach every reader.
+        if (state.workflows !== undefined)
+            state.workflows = [];
+        return [];
+    }
+    const orphaned = [];
+    for (const plan of state.workflows) {
+        if (!plan || plan.status !== "running")
+            continue;
+        for (const step of plan.steps ?? []) {
+            if (step?.status === "pending")
+                step.status = "stopped";
+        }
+        plan.status = "stopped";
+        plan.finishedAt = now();
+        orphaned.push(plan);
+    }
+    return orphaned;
+}
 /**
  * Startup reconciliation for the follow-up queue: an entry the previous process left `sending` goes
  * back to `queued`.
@@ -350,6 +440,7 @@ export class Store {
             // Reconciling them in separate writes would put a file on disk in which one kind of orphan was fixed
             // and the other was not - a half-repaired state that still needs a second restart to finish.
             const orphaned = reconcileSubagentRuns(state);
+            const orphanedWorkflows = reconcileWorkflows(state);
             const interrupted = reconcileConversations(state);
             const requeued = reconcileQueuedMessages(state);
             const todos = reconcileTodos(state);
@@ -357,9 +448,11 @@ export class Store {
             // Persisted here, in `open`, rather than left for the first unrelated write: a reconciled record that
             // is only rewritten by a later mutation would still read `running` to anything that opened the file
             // in the meantime, and would be reconciled a SECOND time on the next restart.
-            if (orphaned.length || interrupted.length || requeued.recovered.length || requeued.changed || todos.changed) {
+            if (orphaned.length || orphanedWorkflows.length || interrupted.length || requeued.recovered.length || requeued.changed || todos.changed) {
                 for (const run of orphaned)
                     console.warn(`Super Pi: sub-agent run ${run.id} was still marked running when the last server stopped - it is now failed, because no child process survived it.`);
+                for (const plan of orphanedWorkflows)
+                    console.warn(`Super Pi: workflow ${plan.id} was still marked running when the last server stopped - it is now stopped, because no step can still be executing.`);
                 // Announced for the same reason: a conversation that failed while nobody was watching is invisible
                 // otherwise, and the user who was watching a spinner when the server died deserves to learn that
                 // their run is over rather than guessing from the fact that it stopped moving.
@@ -988,6 +1081,56 @@ export class Store {
         // store mutates in place on the next delta, or a run's "snapshot" would change under it.
         return structuredClone(run);
     }
+    /**
+     * Writes a whole plan BEFORE step one runs, and persists it.
+     *
+     * THE ORDER THIS EXISTS TO ENFORCE. A plan recorded only as it executes leaves a reload showing
+     * nothing recoverable - which steps were intended, in what order, under which failure policy - because
+     * a transcript of the model asking for a plan is not the plan. Writing it whole first makes the record
+     * a CLAIM the engine then makes good, exactly the relationship a run has to its child process, and it
+     * means an engine that dies mid-plan leaves a document a person can read instead of a gap.
+     *
+     * Steps arrive already in their pending form with empty `attempts`, rather than being built as the
+     * engine reaches them, so what lands on disk before anything runs is the whole intention.
+     *
+     * `structuredClone` on the way out, like `beginSubagentRun`: the engine mutates its own copy on every
+     * transition, and a caller holding a live reference would watch the record change under itself.
+     */
+    async beginWorkflow(plan) {
+        if (!this.state.workflows)
+            this.state.workflows = [];
+        if (this.state.workflows.some((item) => item?.id === plan.id))
+            throw new Error(`Workflow already recorded: ${plan.id}`);
+        this.state.workflows.unshift(plan);
+        trimWorkflows(this.state.workflows);
+        await this.persist();
+        return structuredClone(plan);
+    }
+    /**
+     * Replaces a plan wholesale, and persists it.
+     *
+     * THE WHOLE PLAN RATHER THAN A FIELD PATCH, and the reason is that a plan's live state is three moving
+     * parts at once - `currentIndex`, the status of one step, and an appended attempt - so a patch type
+     * narrow enough to be safe for all three is a shape nothing could be typechecked against. Writing the
+     * plan also cannot forget a field, which is the failure a hand-maintained patch list invites as the
+     * plan grows new parts.
+     *
+     * The whole array is cloned before the write, for the same reason the recorder keeps its own copy of a
+     * run (`subagent-runs.ts:170`): the caller mutates the object it is about to hand back here, and a store
+     * that persisted by reference would write out those edits before they were ever announced.
+     */
+    async setWorkflow(plan) {
+        if (!this.state.workflows)
+            this.state.workflows = [];
+        const stored = structuredClone(plan);
+        const index = this.state.workflows.findIndex((item) => item?.id === stored.id);
+        if (index < 0)
+            throw new Error(`Workflow not found: ${stored.id}`);
+        this.state.workflows[index] = stored;
+        trimWorkflows(this.state.workflows);
+        await this.persist();
+        return structuredClone(stored);
+    }
     async setBackgroundTask(summary) {
         const existing = this.state.backgroundTasks.find((item) => item.id === summary.id);
         if (existing)
@@ -1051,6 +1194,22 @@ export class Store {
         await this.persist();
         return { todos: structuredClone(todos), dropped };
     }
+    /**
+     * Updates user-configured custom agent discovery directories.
+     * Empty/whitespace paths are ignored, and if no valid paths remain, the key is deleted
+     * to keep state.json clean.
+     */
+    async setCustomAgentDirs(dirs) {
+        const cleaned = Array.from(new Set(dirs.map((d) => d.trim()).filter(Boolean)));
+        if (cleaned.length) {
+            this.state.customAgentDirs = cleaned;
+        }
+        else {
+            delete this.state.customAgentDirs;
+        }
+        await this.persist();
+        return structuredClone(cleaned);
+    }
     /**
      * Writes the whole state atomically: a temp file, then a rename over the real one.
      *

package/dist/server/subagent-runs.d.ts

@@ -89,6 +89,8 @@ export declare class SubagentRunRecorder {
      */
     private readonly controllers;
     constructor(supervisor: SubagentSupervisor, hooks: SubagentRunHooks);
+    /** Updates agent discovery directories on the underlying supervisor. */
+    setAgentsDir(dir: string | string[]): void;
     /** Every child still running, optionally narrowed to one conversation. The supervisor owns the pids. */
     liveRuns(conversationId?: string): {
         id: string;

package/dist/server/subagent-runs.js

@@ -44,6 +44,10 @@ export class SubagentRunRecorder {
         this.supervisor = supervisor;
         this.hooks = hooks;
     }
+    /** Updates agent discovery directories on the underlying supervisor. */
+    setAgentsDir(dir) {
+        this.supervisor.setAgentsDir?.(dir);
+    }
     /** Every child still running, optionally narrowed to one conversation. The supervisor owns the pids. */
     liveRuns(conversationId) {
         return this.supervisor.liveRuns(conversationId);

package/dist/server/subagents.d.ts

@@ -136,7 +136,7 @@ export declare class SubagentCancelled extends Error {
 /** Spawns sub-agent children Pi and drains their JSONL RPC streams. */
 export declare class SubagentSupervisor {
     private readonly sessionDir;
-    private readonly agents;
+    private agents;
     private readonly pi;
     /** Live children by run id, so a caller can name the process it means. Cleared in the run's `finally`. */
     private readonly children;
@@ -147,7 +147,7 @@ export declare class SubagentSupervisor {
      * child's spawn line depend on when it was started.
      */
     constructor(sessionDir: string, command?: string, agents?: {
-        dir: string;
+        dir: string | string[];
         promptDir: string;
     });
     /**
@@ -163,6 +163,7 @@ export declare class SubagentSupervisor {
         conversationId: string;
         pid: number | undefined;
     }[];
+    setAgentsDir(dir: string | string[]): void;
     /**
      * Runs one sub-agent to completion and returns what it said.
      *

package/dist/server/subagents.js

@@ -195,6 +195,9 @@ export class SubagentSupervisor {
     liveRuns(conversationId) {
         return [...this.children].map(([id, run]) => ({ id, conversationId: run.conversationId, pid: run.child.pid }));
     }
+    setAgentsDir(dir) {
+        this.agents.dir = dir;
+    }
     /**
      * Runs one sub-agent to completion and returns what it said.
      *
@@ -537,6 +540,7 @@ export class SubagentSupervisor {
         const agent = agents.find((item) => item.id === agentId);
         if (agent)
             return agent;
-        throw new Error(`sub-agent ${JSON.stringify(agentId)} is not a subagent definition in ${this.agents.dir}${problems.length ? ` (${problems.length} file(s) there are not usable agents)` : ""}. A sub-agent is an agents/*.md file with \`mode: subagent\`; a primary agent is chosen by a human and is deliberately not dispatchable as one.`);
+        const dirLabel = Array.isArray(this.agents.dir) ? this.agents.dir.join(", ") : this.agents.dir;
+        throw new Error(`sub-agent ${JSON.stringify(agentId)} is not a subagent definition in ${dirLabel}${problems.length ? ` (${problems.length} file(s) there are not usable agents)` : ""}. A sub-agent is an agents/*.md file with \`mode: subagent\`; a primary agent is chosen by a human and is deliberately not dispatchable as one.`);
     }
 }

package/dist/server/task-tool.d.ts

@@ -62,6 +62,27 @@ export declare const TASK_ROSTER_ENV = "SUPER_PI_TASK_ROSTER";
 export declare const TASK_CONVERSATION_ENV = "SUPER_PI_TASK_CONVERSATION";
 /** How many task hops deep this process already is. A primary is `0`. See `DEFAULT_SUBAGENT_DEPTH`. */
 export declare const TASK_DEPTH_ENV = "SUPER_PI_TASK_DEPTH";
+/**
+ * The name the model calls to hand an ordered plan of sub-agent steps to the server.
+ *
+ * A THIRD tool rather than an extra parameter on `task`, and the reason is what the server does with the
+ * two. `task` is one delegation whose result the model reads back and acts on itself; `workflow` is a
+ * plan the server walks, carrying each step's output into the next without the model in the middle. One
+ * tool with a `steps` array would make every single delegation carry a shape it cannot use, and would make
+ * "dispatch one agent" and "run this pipeline" indistinguishable in the transcript - which is the opposite
+ * of what the model needs to choose between them.
+ */
+export declare const WORKFLOW_TOOL_NAME = "workflow";
+/**
+ * The endpoint the `workflow` tool dials. A FIFTH name in the same wire as the four above, written out on
+ * both sides for the same reason.
+ *
+ * A SEPARATE variable rather than a path derived from `TASK_ENDPOINT_ENV`, for the reason
+ * `TODO_ENDPOINT_ENV` already states: a Pi can legitimately be started with a dispatch endpoint and no
+ * workflow endpoint, and a derived path could not tell that apart from a misconfiguration. The tool then
+ * refuses in words instead of posting somewhere that does not exist.
+ */
+export declare const WORKFLOW_ENDPOINT_ENV = "SUPER_PI_WORKFLOW_ENDPOINT";
 /**
  * One entry of the roster the model is shown: what it types into `subagent_type`, and when to pick it.
  *

package/dist/server/task-tool.js

@@ -61,6 +61,27 @@ export const TASK_ROSTER_ENV = "SUPER_PI_TASK_ROSTER";
 export const TASK_CONVERSATION_ENV = "SUPER_PI_TASK_CONVERSATION";
 /** How many task hops deep this process already is. A primary is `0`. See `DEFAULT_SUBAGENT_DEPTH`. */
 export const TASK_DEPTH_ENV = "SUPER_PI_TASK_DEPTH";
+/**
+ * The name the model calls to hand an ordered plan of sub-agent steps to the server.
+ *
+ * A THIRD tool rather than an extra parameter on `task`, and the reason is what the server does with the
+ * two. `task` is one delegation whose result the model reads back and acts on itself; `workflow` is a
+ * plan the server walks, carrying each step's output into the next without the model in the middle. One
+ * tool with a `steps` array would make every single delegation carry a shape it cannot use, and would make
+ * "dispatch one agent" and "run this pipeline" indistinguishable in the transcript - which is the opposite
+ * of what the model needs to choose between them.
+ */
+export const WORKFLOW_TOOL_NAME = "workflow";
+/**
+ * The endpoint the `workflow` tool dials. A FIFTH name in the same wire as the four above, written out on
+ * both sides for the same reason.
+ *
+ * A SEPARATE variable rather than a path derived from `TASK_ENDPOINT_ENV`, for the reason
+ * `TODO_ENDPOINT_ENV` already states: a Pi can legitimately be started with a dispatch endpoint and no
+ * workflow endpoint, and a derived path could not tell that apart from a misconfiguration. The tool then
+ * refuses in words instead of posting somewhere that does not exist.
+ */
+export const WORKFLOW_ENDPOINT_ENV = "SUPER_PI_WORKFLOW_ENDPOINT";
 /**
  * The dispatchable roster, in the order it will be injected.
  *

package/dist/server/types.d.ts

@@ -1,3 +1,4 @@
+import type { WorkflowRun } from "./workflow.js";
 export type RunStatus = "idle" | "running" | "completed" | "stopped" | "failed";
 export type MessageRole = "user" | "assistant" | "tool" | "system";
 /**
@@ -253,6 +254,8 @@ export type AgentDefinition = {
      */
     tools?: Record<string, unknown>;
     prompt: string;
+    /** The directory this agent definition was discovered from. */
+    sourceDir?: string;
 };
 /**
  * What the picker receives. The prompt body is deliberately NOT sent: it is a whole system prompt,
@@ -260,6 +263,7 @@ export type AgentDefinition = {
  */
 export type AgentSummary = Omit<AgentDefinition, "prompt" | "toolFlags" | "tools"> & {
     toolSummary: string;
+    sourceDir?: string;
 };
 export type AgentCatalog = {
     source: "directory" | "unavailable";
@@ -270,6 +274,8 @@ export type AgentCatalog = {
         message: string;
     }[];
     directory: string;
+    /** All searched agent directories in priority order. */
+    directories?: string[];
     fetchedAt: string;
     error?: string;
 };
@@ -477,6 +483,16 @@ export type BackgroundTaskSummary = {
     startedAt: string;
     resultBlockId: string;
 };
+/**
+ * Orchestrated plans, optional for the same reason `todos` is: a `state.json` written before this
+ * feature existed has no `workflows` key, and must read correctly rather than looking like an install
+ * that has considered a plan and found none. Absence and an empty list mean the same thing to every
+ * reader, so the store deletes the key rather than storing `[]`.
+ *
+ * The workflow's own types live in `workflow.ts` next to the rules that build them. This is a type-only
+ * import and is erased at compile time, so it does not close a runtime cycle with the rules that
+ * construct them - the same relationship `SubagentRun` already has with `subagent-runs.ts`.
+ */
 export type AppState = {
     workspaces: Workspace[];
     conversations: Conversation[];
@@ -484,6 +500,8 @@ export type AppState = {
     queuedMessages: QueuedMessage[];
     backgroundTasks: BackgroundTaskSummary[];
     todos?: TodoItem[];
+    workflows?: WorkflowRun[];
+    customAgentDirs?: string[];
 };
 export type TodoItem = {
     id?: string;
@@ -790,9 +808,20 @@ export type ClientCommand = {
     type: "subagent.stop";
     runId: string;
 }
+/** Stops one orchestrated plan. Distinct from `subagent.stop` because the engine holds the loop and
+ *  the signal, and stopping only the run would leave the plan marching on to the next step. */
+ | {
+    type: "workflow.stop";
+    workflowId: string;
+}
 /** Asks for the `mode: subagent` half of the agent directory. Answered by `subagent.catalog`. */
  | {
     type: "subagent.catalog.fetch";
+} | {
+    type: "agents.setCustomDirs";
+    dirs: string[];
+} | {
+    type: "agents.rescan";
 } | ({
     type: "extension.ui.answer";
     conversationId: string;
@@ -905,6 +934,22 @@ export type ServerEvent = {
     type: "subagent.event";
     run: SubagentRun;
 }
+/**
+ * The current SNAPSHOT of one orchestrated plan, sent on every step transition and nothing else.
+ *
+ * WHOLE SNAPSHOT, like `subagent.event`, for the same reason: a timeline assembled from missed events
+ * is a timeline that can be wrong, and this one has to survive a reload and a reconnect race.
+ *
+ * ON TRANSITIONS ONLY, never on a stream delta, and that asymmetry is deliberate rather than an
+ * oversight. A step's own progress already arrives as `subagent.event` for the run it is executing, so
+ * a workflow event on every delta would broadcast the whole plan - every step's output, accumulated -
+ * once per TOKEN of one child. That is the one way this feature could make the app feel broken. Two
+ * events per step (begin, settle) is what a timeline actually needs; the rest is the run card's job.
+ */
+ | {
+    type: "workflow.event";
+    workflow: WorkflowRun;
+}
 /**
  * Pi's own queue snapshot, forwarded the moment `queue_update` arrives on the child's stdout.
  *

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

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