@herbertgao/pi-subagents 0.17.1 → 0.18.1

package/src/workflow/runtime.ts

@@ -0,0 +1,1399 @@
+/**
+ * runtime.ts — the host half of a workflow run.
+ *
+ * Owns the worker lifecycle, the RPC bridge, the concurrency semaphore, the
+ * per-run caps, and the progress log. The script's only route to an agent is a
+ * `call` message landing here, which is what makes the caps and the abort story
+ * enforceable at all: a script cannot go around them because it has nothing to
+ * go around them *with*.
+ *
+ * Spawning is injected rather than imported. `AgentManager` is a large, stateful
+ * dependency and wiring it in directly would make every test here an integration
+ * test; a {@link WorkflowHost} stub is a dozen lines. The adapter that binds this
+ * to the real manager lives at the call site.
+ */
+
+import { cpus } from "node:os"
+import { Worker } from "node:worker_threads"
+import {
+  type JournalKeyInput,
+  journalKey,
+  type WorkflowJournalEntry,
+} from "./journal.js"
+import { type CompiledSchema, compileJsonSchema } from "./json-schema.js"
+import { extractMeta, type WorkflowMeta } from "./meta.js"
+import type { WorkflowAgentEntry, WorkflowEntry } from "./progress.js"
+import { WORKER_SOURCE } from "./worker-source.js"
+
+/** Matches the `script` field's `maxLength` in the tool schema. */
+export const MAX_SCRIPT_LENGTH = 524_288
+
+/** Agents one run may schedule, in total. */
+export const WORKFLOW_AGENT_CAP = 1000
+
+/** Items one `parallel()` or `pipeline()` call may take. */
+export const WORKFLOW_ITEM_CAP = 4096
+
+/** Nested `workflow()` invocations allowed per run. */
+export const WORKFLOW_NESTED_CAP = 256
+
+/** How much of a prompt or result is kept for the UI. */
+const PREVIEW_LENGTH = 200
+
+export class WorkflowRuntimeError extends Error {}
+
+/**
+ * Concurrent agents allowed, leaving two cores for the host and the TUI.
+ *
+ * `Math.max(1, …)` is not decoration: the raw `min(16, cpus - 2)` is 0 on a one-
+ * or two-core machine, and a semaphore with zero permits never hands out a slot,
+ * so the run would hang before its first agent rather than fail.
+ */
+export function workflowConcurrency(cpuCount: number = cpus().length): number {
+  return Math.max(1, Math.min(16, cpuCount - 2))
+}
+
+/** One agent the script asked for. `agentId` is the handle for {@link WorkflowHost.abortAgent}. */
+export interface WorkflowSpawnRequest {
+  agentId: string
+  /** Position in the run, and the progress entry's stable identity. */
+  index: number
+  prompt: string
+  label: string
+  agentType: string
+  model?: string
+  /**
+   * Reasoning effort for this child, as one of pi's thinking levels.
+   *
+   * Typed as a plain string because this interface is the host boundary and
+   * deliberately knows nothing about pi — `host.ts` is where it becomes a
+   * `ThinkingLevel`. The worker has already rejected anything off the list.
+   */
+  effort?: string
+  isolation?: "worktree"
+  /**
+   * Called by the host once the child's EFFECTIVE configuration is known —
+   * which is when its session exists, not when the spawn resolves.
+   *
+   * Without it a row could only ever show what the script asked for: a fuzzy
+   * `model: "haiku"` stays `haiku` instead of the id it resolved to, an
+   * `agent()` that named no model shows nothing at all, and a level pi clamped
+   * is presented as the level that was requested (#168, #182).
+   *
+   * Plain strings, like `effort` above: this interface is the host boundary and
+   * deliberately knows nothing about pi's `AgentInvocation`. Optional, so a host
+   * that cannot report any of this simply does not, and the row keeps the
+   * requested values it started with.
+   */
+  onResolved?(info: {
+    /**
+     * The host's own id for the child — the manager's `AgentRecord` id here.
+     *
+     * Reported as soon as the host has one, which is earlier than the rest of
+     * this: the model is knowable only once a session exists, but the id is
+     * what lets a reader open that child's conversation, and a child that
+     * never got a model is exactly the one worth opening.
+     */
+    recordId?: string
+    modelName?: string
+    modelId?: string
+    thinking?: string
+    requestedThinking?: string
+    requestedModel?: string
+  }): void
+  /**
+   * Compiled from the script's `agent({ schema })`.
+   *
+   * The host must give the child a `StructuredOutput` tool built from it and
+   * return the validated payload as JSON text. Compiled rather than raw so the
+   * runtime can re-check the answer without re-parsing the schema per call.
+   */
+  schema?: CompiledSchema
+  phaseIndex?: number
+  phaseTitle?: string
+  /**
+   * The `gate` command this agent is being spawned under, when it has one.
+   *
+   * Passed down rather than run purely from here because an isolated child's
+   * worktree is destroyed as part of its own settle: a host that can reach
+   * inside that settle runs the gate there, against the tree the child wrote,
+   * and reports the outcome back as {@link WorkflowSpawnResult.gate}. A host
+   * that ignores this leaves the gate to {@link applyGate}, which then runs it
+   * itself — so exactly one execution either way.
+   */
+  gate?: string
+}
+
+export interface WorkflowSpawnResult {
+  ok: boolean
+  /** The agent's answer. Present when `ok`. */
+  text?: string
+  /** Why it failed. Present when not `ok`. */
+  error?: string
+  /** The user dismissed it rather than it failing; renders as skipped. */
+  skipped?: boolean
+  tokens?: number
+  /**
+   * Output tokens only, for the script's `budget.spent()`.
+   *
+   * Separate from {@link tokens}, which is the lifetime total. Claude Code's
+   * budget counts output, and a fan-out's re-sent input would swamp it.
+   */
+  outputTokens?: number
+  /** Whether the child needed an extra prompt to produce its structured answer. */
+  structuredRetried?: boolean
+  toolCalls?: number
+  /**
+   * Where the child actually ran.
+   *
+   * Only meaningful for `isolation: "worktree"`, and the whole reason it exists:
+   * a gate has to run against the tree the child edited, not the main one, or it
+   * verifies the wrong working copy. Left unset, a gate runs wherever the host
+   * runs commands by default.
+   *
+   * Usually unset for a worktree child even so: the copy is removed during the
+   * child's own settle, so it no longer exists by the time this is read. That
+   * is what {@link gate} is for.
+   */
+  cwd?: string
+  /**
+   * The outcome of this agent's `gate`, when the host already ran it.
+   *
+   * Set only by a host that ran the command itself — inside the child's
+   * worktree, while that directory still existed. Its presence is what tells
+   * {@link applyGate} the command has already been executed; the pass/fail
+   * decision and the error shaping still happen there, in one place.
+   */
+  gate?: WorkflowGateResult
+}
+
+/** Outcome of a `gate` command. `output` is what the user is shown when it fails. */
+export interface WorkflowGateResult {
+  ok: boolean
+  /** Combined stdout/stderr, or whatever the host wants surfaced as the failure. */
+  output: string
+}
+
+/** The one seam between a workflow and the rest of the extension. */
+/** How a script names another workflow: a saved name, or a path to a file. */
+export interface WorkflowScriptRef {
+  name?: string
+  scriptPath?: string
+}
+
+export type WorkflowScriptSource =
+  | { ok: true; script: string; path?: string }
+  | { ok: false; message: string }
+
+export interface WorkflowHost {
+  spawnAgent(request: WorkflowSpawnRequest): Promise<WorkflowSpawnResult>
+  /** Called for every in-flight agent when the run aborts. */
+  abortAgent(agentId: string): void
+  /**
+   * Continue a child that already ran in this run, keeping its context.
+   *
+   * `agentId` is one previously handed out in a {@link WorkflowSpawnRequest};
+   * the child keeps the agent type, model and tool contract it started with, so
+   * only the follow-up prompt crosses.
+   *
+   * Optional: a host without it rejects `resume` rather than quietly starting a
+   * fresh child that has none of the context the script is counting on.
+   */
+  resumeAgent?(
+    agentId: string,
+    prompt: string,
+    /**
+     * Same reporter {@link WorkflowSpawnRequest.onResolved} carries, for the
+     * same reason: a resumed row is rebuilt from scratch, so without it the
+     * continuation of a child would show the model the script *asked* for while
+     * the row above it shows the one that ran.
+     */
+    onResolved?: WorkflowSpawnRequest["onResolved"],
+  ): Promise<WorkflowSpawnResult>
+  /**
+   * Run a `gate` command and report whether it passed.
+   *
+   * `cwd` is the child's worktree when it had one. Optional for the same reason
+   * as {@link resumeAgent}, and more sharply: a gate that silently does not run
+   * would mark unverified work as verified, so the runtime fails the call
+   * instead of skipping it.
+   */
+  runGate?(
+    command: string,
+    options: { agentId: string; cwd?: string },
+  ): Promise<WorkflowGateResult>
+  /**
+   * Resolve a nested `workflow()` reference to source.
+   *
+   * The runtime knows nothing about the filesystem or about pi, so it asks. It
+   * still decides whether what comes back *is* a workflow — see
+   * {@link validateScript} — because those rules belong with the runtime that
+   * enforces them everywhere else.
+   *
+   * Optional for the same reason as {@link resumeAgent}: a host without it
+   * rejects `workflow()` outright rather than silently running nothing.
+   */
+  loadWorkflow?(
+    ref: WorkflowScriptRef,
+  ): Promise<WorkflowScriptSource> | WorkflowScriptSource
+}
+
+/**
+ * What a run can be told to do while it is going, from the workflows dialog.
+ *
+ * Every method is best-effort and idempotent: the dialog renders off a progress
+ * log that lags the runtime slightly, so it will sometimes ask for something
+ * that has just stopped being possible. `false` means "there was nothing to do
+ * that to" — a caller can say so, but it is never an error.
+ */
+export interface WorkflowControl {
+  /**
+   * Stop *starting* agents. Ones already running are left to finish, because
+   * killing model work mid-turn throws away everything it has spent and there
+   * is no way to hand it back its context.
+   */
+  pause(): void
+  resume(): void
+  isPaused(): boolean
+  /**
+   * Give up on the agent at `index`: its `agent()` call returns `null`, exactly
+   * as a terminal failure does, and the row renders skipped.
+   *
+   * Immediate for a running agent and for one held at a pause. An agent parked
+   * behind the concurrency limit takes its skip when it reaches the front —
+   * the alternative is a cancellable semaphore for a case that resolves itself
+   * as soon as any sibling finishes.
+   */
+  skip(index: number): boolean
+  /**
+   * Start the agent at `index` over: the child is stopped and the same call is
+   * re-run, so the script's `agent()` promise is still the one waiting and it
+   * gets the new answer.
+   *
+   * Only while it is running — that is the whole window. Once the call has
+   * settled its value is already the script's, and re-running would produce a
+   * result with nowhere to go.
+   */
+  retry(index: number): boolean
+}
+
+export interface RunWorkflowOptions {
+  /** Full script source, starting with `export const meta = { … }`. */
+  script: string
+  args?: unknown
+  host: WorkflowHost
+  signal?: AbortSignal
+  /** Fired per batch, not per entry — see the worker's progress batching. */
+  onProgress?(entries: readonly WorkflowEntry[]): void
+  concurrency?: number
+  agentCap?: number
+  itemCap?: number
+  /**
+   * Hands the caller the run's control surface, once per run.
+   *
+   * A callback rather than a return value because `runWorkflow` resolves when
+   * the run is *over*, which is the one moment there is nothing left to
+   * control. Fired before the first agent starts.
+   */
+  onControl?(control: WorkflowControl): void
+  /**
+   * How many nested `workflow()` invocations one run may make in total.
+   *
+   * Each costs a compile and a scope rather than a thread, so the ceiling is
+   * generous — but unbounded is worse than capped, on the same reasoning as
+   * {@link agentCap}.
+   */
+  nestedCap?: number
+  /**
+   * Replay and record, for `resumeFromRunId`.
+   *
+   * The runtime does no file IO — `entries` come in already read and `append`
+   * goes back out — so its tests stay free of a filesystem, the same reason
+   * spawning is behind {@link WorkflowHost}.
+   */
+  journal?: {
+    /** A previous run's settled calls, in position order. Empty replays nothing. */
+    entries?: readonly WorkflowJournalEntry[]
+    /** Called as each call of *this* run settles, so it can be resumed in turn. */
+    append?(entry: WorkflowJournalEntry): void
+  }
+}
+
+export interface WorkflowRunResult {
+  status: "completed" | "failed" | "killed"
+  meta: WorkflowMeta
+  /** The script's return value, JSON-checked at the boundary. */
+  value?: unknown
+  error?: string
+  /** The append-only log, in emission order. */
+  progress: WorkflowEntry[]
+  /** Agents scheduled, including those that failed. */
+  agentCount: number
+  /** How many of those came back from the journal instead of being spawned. */
+  replayedCount: number
+}
+
+/* ------------------------------------------------------------------------- *
+ * JSON boundary — host side
+ * ------------------------------------------------------------------------- */
+
+function boundaryError(what: string, path: string): WorkflowRuntimeError {
+  return new WorkflowRuntimeError(
+    `Cannot pass ${what} across the workflow VM boundary (at ${path}).`,
+  )
+}
+
+function walk(value: unknown, path: string, seen: Set<object>): void {
+  if (value === null) return
+  const kind = typeof value
+  if (kind === "string" || kind === "boolean") return
+  if (kind === "number") {
+    if (!Number.isFinite(value))
+      throw boundaryError("a non-finite number", path)
+    return
+  }
+  if (kind === "undefined") {
+    if (path === "args") return
+    throw boundaryError("undefined", path)
+  }
+  if (kind === "bigint") throw boundaryError("a BigInt", path)
+  if (kind === "symbol") throw boundaryError("a symbol", path)
+  if (kind === "function") throw boundaryError("a function", path)
+  if (kind !== "object") throw boundaryError(`a ${kind}`, path)
+
+  const object = value as object
+  if (seen.has(object)) throw boundaryError("a circular structure", path)
+  seen.add(object)
+
+  if (Object.getOwnPropertySymbols(object).length > 0) {
+    throw boundaryError("an object with symbol keys", path)
+  }
+
+  if (Array.isArray(object)) {
+    for (let i = 0; i < object.length; i++) {
+      if (!Object.hasOwn(object, i))
+        throw boundaryError("a sparse array", `${path}[${i}]`)
+      walk(object[i], `${path}[${i}]`, seen)
+    }
+    seen.delete(object)
+    return
+  }
+
+  const prototype = Object.getPrototypeOf(object)
+  if (prototype !== null && prototype !== Object.prototype) {
+    throw boundaryError("a non-plain object", path)
+  }
+  for (const [key, entry] of Object.entries(object)) {
+    walk(entry, `${path}.${key}`, seen)
+  }
+  seen.delete(object)
+}
+
+/**
+ * Reject anything that cannot survive the round trip to the worker and into a
+ * resume journal. Structured clone would happily carry a `Map` or a cycle that
+ * the journal then cannot represent, so the check is stricter than the transport.
+ */
+export function assertBoundarySafe(value: unknown, path: string): void {
+  walk(value, path, new Set())
+}
+
+/* ------------------------------------------------------------------------- *
+ * Semaphore
+ * ------------------------------------------------------------------------- */
+
+class Semaphore {
+  private active = 0
+  private readonly waiters: (() => void)[] = []
+
+  constructor(private readonly limit: number) {}
+
+  acquire(): Promise<void> {
+    if (this.active < this.limit) {
+      this.active++
+      return Promise.resolve()
+    }
+    return new Promise<void>((resolve) => {
+      this.waiters.push(resolve)
+    })
+  }
+
+  release(): void {
+    const next = this.waiters.shift()
+    // Hand the permit straight over rather than decrementing and re-acquiring;
+    // otherwise a burst of releases can let more than `limit` through.
+    if (next) next()
+    else this.active--
+  }
+
+  /** Wake everyone so aborted callers can observe the abort and bail. */
+  drain(): void {
+    while (this.waiters.length > 0) {
+      const next = this.waiters.shift()
+      next?.()
+    }
+  }
+}
+
+/* ------------------------------------------------------------------------- *
+ * Messages
+ * ------------------------------------------------------------------------- */
+
+interface AgentCallPayload {
+  prompt: string
+  label?: string
+  model?: string
+  agentType?: string
+  isolation?: "worktree"
+  phaseIndex?: number
+  phaseTitle?: string
+  /** Shell command that has to pass before the agent counts as done. */
+  gate?: string
+  /** Label of an earlier child in this run to continue instead of starting one. */
+  resume?: string
+  /** Reasoning effort, already validated against pi's thinking levels worker-side. */
+  effort?: string
+  /** Raw JSON Schema from `agent({ schema })`, compiled before anything spawns. */
+  schema?: unknown
+}
+
+type WorkerMessage =
+  | { type: "call"; callId: number; method: string; payload: AgentCallPayload }
+  | { type: "progress"; entries: WorkflowEntry[] }
+  | { type: "complete"; resultJson?: string }
+  | { type: "error"; message: string; stack?: string }
+
+/** Everything below 0x20 except tab, newline and carriage return, plus DEL. */
+const CONTROL_CHARACTERS = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/
+
+const preview = (text: string) =>
+  text.length <= PREVIEW_LENGTH ? text : `${text.slice(0, PREVIEW_LENGTH - 1)}…`
+
+/** First line of the prompt, trimmed — the fallback display name for an agent. */
+function derivedLabel(prompt: string): string {
+  const line = prompt.split("\n", 1)[0].trim()
+  return line.length <= 60 ? line || "agent" : `${line.slice(0, 59)}…`
+}
+
+/**
+ * A child `resume` can revive, remembered under its label.
+ *
+ * The spawn options travel with it because `resume` deliberately takes none: the
+ * revived child keeps the agent type, model and isolation it was started with,
+ * and the progress entry has to show the same thing the first entry showed.
+ */
+interface CompletedChild {
+  agentId: string
+  label: string
+  agentType: string
+  model?: string
+  isolation?: "worktree"
+}
+
+/**
+ * Turn a failing gate into a failing agent.
+ *
+ * Deliberately no new state, no new entry type: a gated agent whose command
+ * fails is *a failed agent*, so the card, the dialog and `agent()`'s `null`
+ * return all handle it with the code they already have. The command output
+ * becomes the error, because that is the thing worth reading.
+ *
+ * The single place that decides whether a gate passed. The command may have
+ * been run by the host instead (inside a worktree that no longer exists by
+ * now), but only ever by one of the two: a host that ran it says so with
+ * `result.gate`, and this then shapes that outcome rather than running it
+ * again.
+ */
+/**
+ * Hold a schema'd result to its schema, host-side.
+ *
+ * The child's own tool already validated whatever it passed, so this normally
+ * agrees. It exists for the cases where nothing did: a host that ignores
+ * `schema` entirely, a replayed journal entry from before the schema changed,
+ * or a payload that reached us some other way. The script asked for a shape;
+ * exactly one place should be able to promise it.
+ */
+function applySchema(
+  result: WorkflowSpawnResult,
+  compiled: CompiledSchema,
+): WorkflowSpawnResult {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(result.text ?? "")
+  } catch {
+    return {
+      ...result,
+      ok: false,
+      error:
+        "The agent did not return structured output: its answer was not JSON.",
+    }
+  }
+  const verdict = compiled.check(parsed)
+  if (verdict === true) return result
+  return {
+    ...result,
+    ok: false,
+    error: `The agent's answer did not match the requested schema: ${verdict}`,
+  }
+}
+
+async function applyGate(
+  result: WorkflowSpawnResult,
+  command: string,
+  agentId: string,
+  runGate: NonNullable<WorkflowHost["runGate"]>,
+): Promise<WorkflowSpawnResult> {
+  const outcome =
+    result.gate ??
+    (await runGate(command, {
+      agentId,
+      // Where the child worked, when it had a worktree of its own. Gating the
+      // main tree instead would verify code the child never touched.
+      ...(result.cwd !== undefined ? { cwd: result.cwd } : {}),
+    }))
+  const { gate: _ran, ...kept } = result
+  if (outcome.ok) return kept
+  const { text: _discarded, ...rest } = kept
+  const output = outcome.output.trim()
+  return {
+    ...rest,
+    ok: false,
+    error: output === "" ? `Gate command failed: ${command}` : output,
+  }
+}
+
+/**
+ * Nico's wording, kept verbatim — this is the one borrowed check whose message a
+ * user is likely to search for.
+ */
+function unawaitedLaunchMessage(labels: readonly string[]): string {
+  const list = labels.map((label) => `'${label}'`).join(", ")
+  return `workflow script completed with unawaited agent launch(es): ${list}. Await or return each launch.`
+}
+
+/**
+ * Run one workflow script to completion.
+ *
+ * Rejects before starting for a script that cannot run at all (bad `meta`, over
+ * the size limit, control characters, non-JSON `args`). Everything after the
+ * worker is live resolves instead, carrying the failure in `status` — by then
+ * there is a progress log worth handing back.
+ */
+/**
+ * Everything a script must satisfy before it is compiled.
+ *
+ * Extracted so a nested `workflow()` is held to exactly the same standard as a
+ * top-level run: same size limit, same character rules, same `meta` contract.
+ * The host resolves a reference to source; deciding whether that source is a
+ * workflow stays here, where the rules live.
+ */
+export function validateScript(script: string): {
+  meta: WorkflowMeta
+  body: string
+} {
+  if (script.length > MAX_SCRIPT_LENGTH) {
+    throw new WorkflowRuntimeError(
+      `Workflow script is ${script.length} characters, over the limit of ${MAX_SCRIPT_LENGTH}.`,
+    )
+  }
+  if (CONTROL_CHARACTERS.test(script)) {
+    throw new WorkflowRuntimeError(
+      "Workflow script contains control characters. Only tab, carriage return and newline are allowed.",
+    )
+  }
+  return extractMeta(script)
+}
+
+export async function runWorkflow(
+  options: RunWorkflowOptions,
+): Promise<WorkflowRunResult> {
+  const { script, host } = options
+
+  assertBoundarySafe(options.args, "args")
+
+  const { meta, body } = validateScript(script)
+  const agentCap = options.agentCap ?? WORKFLOW_AGENT_CAP
+  const itemCap = options.itemCap ?? WORKFLOW_ITEM_CAP
+  const semaphore = new Semaphore(options.concurrency ?? workflowConcurrency())
+
+  const progress: WorkflowEntry[] = []
+  const inflight = new Set<string>()
+  /** Label → the child that ran under it, last one wins. The `resume` handle. */
+  const completedByLabel = new Map<string, CompletedChild>()
+  /**
+   * Launches the host has accepted and not yet answered, in call order.
+   *
+   * This is the whole unawaited-launch mechanism: a script that drops an
+   * `agent()` promise still gets its call answered eventually, but it returns
+   * first — so anything left here when `complete` arrives is a result nobody is
+   * waiting for. Tracking it host-side avoids proxying `Promise` inside the
+   * realm, which §2.4 rules out, and reading stack traces, which is brittle.
+   */
+  const openLaunches = new Map<number, string>()
+  let agentCount = 0
+  let aborted = false
+  let settled = false
+
+  /* --- resume state ---------------------------------------------------- */
+
+  const journalEntries = options.journal?.entries ?? []
+  const recordJournal = options.journal?.append
+  /**
+   * Whether the replayable prefix is still intact.
+   *
+   * Once a position misses — different key, a journaled failure, or nothing
+   * recorded there — every later call runs live, however well it matches.
+   * See the header of journal.ts for why this is a prefix and not a lookup.
+   */
+  // A journal from a run that used `agent({ resume })` is declined whole: see
+  // journal.ts on why a replayed agent leaves nothing for a later resume to
+  // continue. Declining up front beats stranding the first `resume` call
+  // partway through a run that has already spent its cheap half.
+  const journalResumes = journalEntries.some((entry) => entry.resumed)
+  let prefixIntact = journalEntries.length > 0 && !journalResumes
+  let replayedCount = 0
+
+  /* --- live control ---------------------------------------------------- */
+
+  /**
+   * Agents that still have an unanswered `agent()` call, by index.
+   *
+   * The window in which skip and retry mean anything: before the entry appears
+   * there is nothing to act on, and after it is gone the script already has its
+   * value. `started` is what separates the two — a retry needs a child to stop.
+   */
+  interface LiveAgent {
+    agentId: string
+    started: boolean
+    intent?: "skip" | "retry"
+    /** Wakes it out of a pause hold, so a skip does not wait for a resume. */
+    wake?: () => void
+  }
+  const liveAgents = new Map<number, LiveAgent>()
+
+  /**
+   * Output tokens this run has spent, mirrored to the script as
+   * `budget.spent()`.
+   *
+   * The host owns the number and every response carries it, rather than the
+   * worker accumulating its own: two counters would drift, and there is nothing
+   * to gain from the second one. Nor is there observable staleness — tokens
+   * only accrue through agents, and the script only learns anything through
+   * agent responses.
+   */
+  let spentOutputTokens = 0
+
+  let paused = false
+  /** Read through a call for the same reason `intent()` is — see below. */
+  const isPaused = () => paused
+  const pauseWaiters = new Set<() => void>()
+  /** Release everyone held at a pause — on resume, and on the way out. */
+  function releasePause(): void {
+    for (const wake of [...pauseWaiters]) wake()
+    pauseWaiters.clear()
+  }
+  /** Park here while the run is paused, so no new agent is started. */
+  function pauseGate(live: LiveAgent): Promise<void> {
+    if (!paused || aborted || settled) return Promise.resolve()
+    return new Promise<void>((resolve) => {
+      const wake = () => {
+        pauseWaiters.delete(wake)
+        live.wake = undefined
+        resolve()
+      }
+      live.wake = wake
+      pauseWaiters.add(wake)
+    })
+  }
+
+  options.onControl?.({
+    pause: () => {
+      paused = true
+    },
+    resume: () => {
+      paused = false
+      releasePause()
+    },
+    isPaused: () => paused,
+    skip: (index) => {
+      const live = liveAgents.get(index)
+      if (live === undefined || live.intent !== undefined) return false
+      live.intent = "skip"
+      // A running child is stopped, which comes back as a skipped result; a
+      // held one is woken so it can bail at the gate it is parked on.
+      if (live.started) host.abortAgent(live.agentId)
+      else live.wake?.()
+      return true
+    },
+    retry: (index) => {
+      const live = liveAgents.get(index)
+      if (live === undefined || !live.started || live.intent !== undefined)
+        return false
+      live.intent = "retry"
+      host.abortAgent(live.agentId)
+      return true
+    },
+  })
+
+  /** The journal entry to reuse at `index`, or undefined to run it live. */
+  function replayAt(
+    index: number,
+    key: string,
+  ): WorkflowJournalEntry | undefined {
+    if (!prefixIntact) return undefined
+    const entry = journalEntries[index]
+    if (
+      entry === undefined ||
+      entry.index !== index ||
+      entry.key !== key ||
+      !entry.ok
+    ) {
+      prefixIntact = false
+      return undefined
+    }
+    return entry
+  }
+
+  const worker = new Worker(WORKER_SOURCE, {
+    eval: true,
+    workerData: {
+      body,
+      metaJson: JSON.stringify(meta),
+      argsJson:
+        options.args === undefined ? undefined : JSON.stringify(options.args),
+      itemCap,
+      nestedCap: options.nestedCap ?? WORKFLOW_NESTED_CAP,
+    },
+  })
+
+  return await new Promise<WorkflowRunResult>((resolve) => {
+    const emit = (entries: WorkflowEntry[]) => {
+      if (entries.length === 0) return
+      progress.push(...entries)
+      options.onProgress?.(entries)
+    }
+
+    const respond = (
+      callId: number,
+      ok: boolean,
+      value?: unknown,
+      error?: string,
+      fatal?: boolean,
+    ) => {
+      // Cleared before the settled check: a launch answered by a run that is
+      // already finishing is not an unawaited launch either.
+      openLaunches.delete(callId)
+      if (settled) return
+      // `spent` rides on every response, so the worker's `budget.spent()` is a
+      // mirror of this number rather than a second tally of its own.
+      worker.postMessage({
+        type: "response",
+        callId,
+        ok,
+        value,
+        error,
+        fatal,
+        spent: spentOutputTokens,
+      })
+    }
+
+    const finish = (
+      result: Omit<
+        WorkflowRunResult,
+        "meta" | "progress" | "agentCount" | "replayedCount"
+      >,
+    ) => {
+      if (settled) return
+      settled = true
+      options.signal?.removeEventListener("abort", onAbort)
+      // Symmetric with `semaphore.drain()` below: everything parked is woken so
+      // it observes the settle and unwinds. Nothing depends on it — the run's
+      // promise resolves either way — it just does not leave live-agent
+      // bookkeeping behind for a run that is over.
+      releasePause()
+      for (const agentId of inflight) host.abortAgent(agentId)
+      inflight.clear()
+      semaphore.drain()
+      // Resolve only once the thread is actually down, so a caller that awaits
+      // runWorkflow() is guaranteed not to be leaking one.
+      const settle = () =>
+        resolve({ ...result, meta, progress, agentCount, replayedCount })
+      void worker.terminate().then(settle, settle)
+    }
+
+    function onAbort() {
+      aborted = true
+      // terminate() is why this runs in a worker at all: it stops a script that
+      // is spinning or wedged mid-await, which an in-process vm cannot do.
+      finish({ status: "killed", error: "Workflow aborted." })
+    }
+
+    if (options.signal) {
+      if (options.signal.aborted) {
+        onAbort()
+        return
+      }
+      options.signal.addEventListener("abort", onAbort, { once: true })
+    }
+
+    async function handleAgent(
+      callId: number,
+      payload: AgentCallPayload,
+    ): Promise<void> {
+      // Bound now: the optional methods are checked once, up front, so a
+      // capability the host lacks fails before an agent is spawned rather than
+      // after — a gate that never ran must not be mistaken for a gate that
+      // passed.
+      const runGate = host.runGate?.bind(host)
+      const resumeAgent = host.resumeAgent?.bind(host)
+      if (payload.gate !== undefined && runGate === undefined) {
+        respond(
+          callId,
+          false,
+          undefined,
+          "This workflow host cannot run gate commands.",
+          true,
+        )
+        return
+      }
+      if (payload.resume !== undefined && resumeAgent === undefined) {
+        respond(
+          callId,
+          false,
+          undefined,
+          "This workflow host cannot resume agents.",
+          true,
+        )
+        return
+      }
+
+      let resumed: CompletedChild | undefined
+      if (payload.resume !== undefined) {
+        resumed = completedByLabel.get(payload.resume)
+        if (resumed === undefined) {
+          const known = [...completedByLabel.keys()]
+          // Fatal: a typo'd label is a script bug, and folding it into a null
+          // would show up as an agent that mysteriously returned nothing.
+          //
+          // Unless agents were replayed, in which case it is not a script bug
+          // at all — the label's child came back from the journal and has no
+          // conversation here to continue. Saying "no agent has completed"
+          // would send the reader hunting for a typo that is not there.
+          respond(
+            callId,
+            false,
+            undefined,
+            replayedCount > 0
+              ? `agent() opts.resume: "${payload.resume}" was replayed from the resume journal, not run, so there is ` +
+                  "no conversation in this run to continue. Re-run without resumeFromRunId."
+              : `agent() opts.resume: no agent has completed under the label "${payload.resume}" in this run. ${
+                  known.length === 0
+                    ? "No agent has completed yet."
+                    : `Known labels: ${known.map((label) => `"${label}"`).join(", ")}.`
+                }`,
+            true,
+          )
+          return
+        }
+      }
+
+      // Compiled before anything is scheduled. A schema the runtime cannot use
+      // is a script bug, so it is fatal like a typo'd resume label — folding it
+      // into a null would surface as an agent that mysteriously returned
+      // nothing, and it costs no model call to say so here.
+      let compiledSchema: CompiledSchema | undefined
+      if (payload.schema !== undefined) {
+        const compilation = compileJsonSchema(payload.schema)
+        if (!compilation.ok) {
+          respond(callId, false, undefined, compilation.message, true)
+          return
+        }
+        compiledSchema = compilation.compiled
+      }
+
+      if (agentCount >= agentCap) {
+        // Fatal, so parallel()/pipeline() rethrow instead of folding it into a
+        // null. A cap that silently drops work is worse than no cap.
+        respond(
+          callId,
+          false,
+          undefined,
+          `Workflow exceeded its cap of ${agentCap} agents.`,
+          true,
+        )
+        return
+      }
+      const index = agentCount++
+      // A resumed call is the same child again: it keeps the agent id, so an
+      // abort still reaches it, and it keeps its spawn contract, so the row
+      // reads the same as the row it continues.
+      const agentId = resumed?.agentId ?? `wf-agent-${index}`
+      const label =
+        payload.label ?? resumed?.label ?? derivedLabel(payload.prompt)
+      const agentType =
+        resumed?.agentType ?? payload.agentType ?? "general-purpose"
+      const model = resumed !== undefined ? resumed.model : payload.model
+      const isolation =
+        resumed !== undefined ? resumed.isolation : payload.isolation
+      openLaunches.set(callId, label)
+
+      const base: WorkflowAgentEntry = {
+        type: "workflow_agent",
+        index,
+        label,
+        state: "start",
+        agentId,
+        agentType,
+        promptPreview: preview(payload.prompt),
+        ...(model !== undefined ? { model } : {}),
+        ...(isolation !== undefined ? { isolation } : {}),
+        ...(payload.phaseIndex !== undefined
+          ? { phaseIndex: payload.phaseIndex }
+          : {}),
+        ...(payload.phaseTitle !== undefined
+          ? { phaseTitle: payload.phaseTitle }
+          : {}),
+      }
+
+      const queuedAt = Date.now()
+      emit([{ ...base, queuedAt }])
+
+      // Replay before the semaphore, not after: a cached answer is not model
+      // running, so it must not hold a concurrency slot that a live agent
+      // could use. The row still appears in the tree — the run reads as the
+      // same shape it had the first time, just faster.
+      // The payload's `schema` is the raw object; the key wants it serialized,
+      // so the spread is narrowed rather than passed through.
+      const keyInput: JournalKeyInput = {
+        ...payload,
+        schema:
+          payload.schema !== undefined
+            ? JSON.stringify(payload.schema)
+            : undefined,
+      }
+      let replayed = replayAt(index, journalKey(keyInput))
+      // A replayed answer still has to satisfy the schema. The key covers a
+      // schema that *changed*, but not a journal that was hand-edited, and not
+      // the empty text a torn entry leaves behind — either would hand the
+      // script a null from an entry the journal claims succeeded.
+      if (replayed !== undefined && compiledSchema !== undefined) {
+        const recheck = applySchema(
+          { ok: true, text: replayed.text ?? "" },
+          compiledSchema,
+        )
+        if (!recheck.ok) {
+          prefixIntact = false
+          replayed = undefined
+        }
+      }
+      if (replayed !== undefined) {
+        replayedCount++
+        const replayedText = replayed.text ?? ""
+        const at = Date.now()
+        emit([
+          {
+            ...base,
+            queuedAt,
+            startedAt: at,
+            lastProgressAt: at,
+            durationMs: 0,
+            state: "done",
+            // The row reads as done, because it is — `cached` is what tells the
+            // dialog to annotate it "from resume journal" rather than letting a
+            // 0ms agent look like one that did the work impossibly fast.
+            cached: true,
+            resultPreview: preview(replayedText),
+          },
+        ])
+        openLaunches.delete(callId)
+        // Re-recorded so this run's journal is complete on its own terms: a
+        // resume of a resume must not have to walk back through a chain of
+        // earlier files to find the prefix.
+        recordJournal?.({
+          index,
+          key: replayed.key,
+          ok: true,
+          text: replayedText,
+        })
+        respond(callId, true, replayedText)
+        return
+      }
+
+      const key = journalKey(keyInput)
+      const resumeMark =
+        payload.resume !== undefined ? ({ resumed: true } as const) : {}
+
+      /** A skip the user asked for, before the child ever started. */
+      const settleSkipped = (extra: Partial<WorkflowAgentEntry>) => {
+        recordJournal?.({ index, key, ok: false, ...resumeMark })
+        emit([
+          {
+            ...base,
+            queuedAt,
+            ...extra,
+            state: "error",
+            skipped: true,
+            error: "Skipped by user.",
+          },
+        ])
+        // `null`, exactly as a terminal failure gives — a skipped agent is one
+        // the script's `.filter(Boolean)` was already written to survive.
+        respond(callId, true, null)
+      }
+
+      // Registered for exactly as long as the call is unanswered, which is the
+      // window in which skip and retry mean anything.
+      const live: LiveAgent = { agentId, started: false }
+      liveAgents.set(index, live)
+      // Read through a call, not off the field: `intent` is set from outside
+      // this function while it is suspended at an await, so control-flow
+      // narrowing across the awaits would be reasoning about a value that has
+      // since changed.
+      const intent = (): LiveAgent["intent"] => live.intent
+      let attempt = 1
+      try {
+        for (;;) {
+          // Held before the slot, not after: a paused run must not sit on
+          // concurrency it is not using while its running agents drain.
+          await pauseGate(live)
+          if (intent() === "skip") return settleSkipped({})
+
+          // A resumed agent waits its turn like any other: it is the same amount of
+          // model running at once.
+          await semaphore.acquire()
+          if (aborted || settled) {
+            semaphore.release()
+            respond(callId, false, undefined, "Workflow aborted.", true)
+            return
+          }
+          // Paused while parked behind the limit: this agent was waiting for a
+          // permit when the pause landed, so it never passed the gate above.
+          // Hand the permit back and go wait at the gate like everything else,
+          // or a pause would leak exactly as many agents as were queued.
+          if (isPaused() && !aborted && !settled) {
+            semaphore.release()
+            continue
+          }
+          // Skipped while parked behind the limit: the permit arrived, and the
+          // only thing left to do with it is give it back.
+          if (intent() === "skip") {
+            semaphore.release()
+            return settleSkipped({})
+          }
+
+          // Carried on every emit from here on, so a retried row keeps saying
+          // why it is on its second attempt instead of losing it to the next
+          // progress update.
+          const attemptMark =
+            attempt > 1
+              ? { attempt, lastAttemptReason: "user-retry" as const }
+              : {}
+
+          const startedAt = Date.now()
+          emit([{ ...base, queuedAt, startedAt, ...attemptMark }])
+
+          // Mutates `base` rather than emitting a standalone patch: every later
+          // emit spreads it, so the settle path carries the effective values
+          // without knowing they were ever corrected. Re-emitting under the
+          // same `index` is what the append-only, last-write-wins progress log
+          // is for — the row updates in place while the agent is still running.
+          const onResolved = (info: {
+            recordId?: string
+            modelName?: string
+            modelId?: string
+            thinking?: string
+            requestedThinking?: string
+            requestedModel?: string
+          }) => {
+            if (info.recordId !== undefined) base.recordId = info.recordId
+            if (info.modelName !== undefined) base.model = info.modelName
+            if (info.modelId !== undefined) base.modelId = info.modelId
+            if (info.thinking !== undefined) base.thinking = info.thinking
+            if (info.requestedThinking !== undefined)
+              base.requestedThinking = info.requestedThinking
+            if (info.requestedModel !== undefined)
+              base.requestedModel = info.requestedModel
+            // `base.state` is still "start", so emitting after the row reached a
+            // terminal state would revert it to running under last-write-wins.
+            // Not reachable from this repo's host, which reports during startup
+            // — but this is the host boundary, and every other promise it makes
+            // is checked rather than trusted.
+            if (!inflight.has(agentId)) return
+            emit([
+              {
+                ...base,
+                queuedAt,
+                startedAt,
+                ...attemptMark,
+                lastProgressAt: Date.now(),
+              },
+            ])
+          }
+          live.started = true
+          inflight.add(agentId)
+
+          let result: WorkflowSpawnResult
+          try {
+            result =
+              resumed !== undefined && resumeAgent !== undefined
+                ? await resumeAgent(resumed.agentId, payload.prompt, onResolved)
+                : await host.spawnAgent({
+                    agentId,
+                    index,
+                    prompt: payload.prompt,
+                    label,
+                    agentType,
+                    ...(model !== undefined ? { model } : {}),
+                    ...(payload.effort !== undefined
+                      ? { effort: payload.effort }
+                      : {}),
+                    ...(compiledSchema !== undefined
+                      ? { schema: compiledSchema }
+                      : {}),
+                    ...(isolation !== undefined ? { isolation } : {}),
+                    ...(payload.phaseIndex !== undefined
+                      ? { phaseIndex: payload.phaseIndex }
+                      : {}),
+                    ...(payload.phaseTitle !== undefined
+                      ? { phaseTitle: payload.phaseTitle }
+                      : {}),
+                    // Offered, not delegated: a host that can run it inside the
+                    // child's worktree does, and hands back `result.gate`.
+                    ...(payload.gate !== undefined
+                      ? { gate: payload.gate }
+                      : {}),
+                    onResolved,
+                  })
+            if (result.ok) {
+              // Recorded before the gate runs: the child itself finished, so it is
+              // resumable even when its gate rejects the work — "here is what the
+              // gate said, fix it" is the loop this exists for.
+              completedByLabel.set(label, {
+                agentId,
+                label,
+                agentType,
+                ...(model !== undefined ? { model } : {}),
+                ...(isolation !== undefined ? { isolation } : {}),
+              })
+              // Re-checked here, not just in the child's tool: this is the one
+              // place that decides the script's value matches the schema it
+              // asked for, so a host that ignored `schema` fails loudly instead
+              // of handing the script prose. Before the gate, because a gate
+              // verifies work and there is no work to verify if the shape is
+              // wrong — and the reader should see the schema error, not a gate
+              // error standing in front of it.
+              if (compiledSchema !== undefined && result.ok) {
+                result = applySchema(result, compiledSchema)
+              }
+              if (
+                result.ok &&
+                payload.gate !== undefined &&
+                runGate !== undefined
+              ) {
+                result = await applyGate(result, payload.gate, agentId, runGate)
+              }
+            }
+          } catch (error) {
+            result = {
+              ok: false,
+              error: error instanceof Error ? error.message : String(error),
+            }
+          } finally {
+            inflight.delete(agentId)
+            live.started = false
+            semaphore.release()
+          }
+
+          if (settled) return
+
+          // The stop that produced this result was ours, so run the same call
+          // again rather than reporting it. The script is still awaiting this
+          // `agent()`, which is the only reason a retry can mean anything.
+          if (intent() === "retry" && !aborted) {
+            live.intent = undefined
+            attempt++
+            emit([
+              { ...base, queuedAt, attempt, lastAttemptReason: "user-retry" },
+            ])
+            continue
+          }
+
+          // Counted before the response is sent, so the very call that spent
+          // them already sees them in `budget.spent()`. Failed and skipped
+          // agents count too — they burned the tokens either way.
+          spentOutputTokens += result.outputTokens ?? 0
+
+          const finishedAt = Date.now()
+          const common = {
+            ...base,
+            queuedAt,
+            startedAt,
+            ...attemptMark,
+            lastProgressAt: finishedAt,
+            durationMs: finishedAt - startedAt,
+            ...(result.tokens !== undefined ? { tokens: result.tokens } : {}),
+            ...(result.toolCalls !== undefined
+              ? { toolCalls: result.toolCalls }
+              : {}),
+          }
+
+          if (result.ok) {
+            const text = result.text ?? ""
+            emit([{ ...common, state: "done", resultPreview: preview(text) }])
+            recordJournal?.({ index, key, ok: true, text, ...resumeMark })
+            respond(callId, true, text)
+            return
+          }
+          // Recorded as a failure rather than left out: a gap would be read as an
+          // unchanged prefix on the next resume, silently skipping the retry this
+          // whole mechanism exists to make cheap.
+          recordJournal?.({ index, key, ok: false, ...resumeMark })
+          // A dead agent is a null in the script, not a thrown error: Claude Code
+          // scripts .filter(Boolean) rather than try/catch around every call.
+          emit([
+            {
+              ...common,
+              state: "error",
+              // A user skip reaches here as a stopped child, which the host
+              // already reports as skipped — the flag is taken from the result
+              // rather than from the intent so an abort mid-skip still reads
+              // as whatever actually happened to the child.
+              error: result.error ?? "Agent failed.",
+              ...(result.skipped ? { skipped: true } : {}),
+            },
+          ])
+          respond(callId, true, null)
+          return
+        }
+      } finally {
+        liveAgents.delete(index)
+      }
+    }
+
+    /**
+     * Resolve one `workflow(ref)` and hand the child's source back compiled.
+     *
+     * Resolution failures are non-fatal — Claude Code documents `workflow()` as
+     * throwing on an unknown name so a script can catch it and carry on. A host
+     * with no `loadWorkflow` at all is fatal, matching how a missing `runGate`
+     * or `resumeAgent` is treated: a capability the script asked for and this
+     * host cannot provide is a wiring error, not a runtime condition.
+     */
+    async function handleLoadWorkflow(
+      callId: number,
+      ref: WorkflowScriptRef,
+    ): Promise<void> {
+      const loadWorkflow = host.loadWorkflow?.bind(host)
+      if (loadWorkflow === undefined) {
+        respond(
+          callId,
+          false,
+          undefined,
+          "This workflow host cannot run nested workflows.",
+          true,
+        )
+        return
+      }
+      let source: WorkflowScriptSource
+      try {
+        source = await loadWorkflow(ref)
+      } catch (error) {
+        respond(
+          callId,
+          false,
+          undefined,
+          error instanceof Error ? error.message : String(error),
+        )
+        return
+      }
+      if (!source.ok) {
+        respond(callId, false, undefined, source.message)
+        return
+      }
+      try {
+        const child = validateScript(source.script)
+        respond(callId, true, {
+          name: child.meta.name,
+          metaJson: JSON.stringify(child.meta),
+          body: child.body,
+        })
+      } catch (error) {
+        respond(
+          callId,
+          false,
+          undefined,
+          error instanceof Error ? error.message : String(error),
+        )
+      }
+    }
+
+    worker.on("message", (message: WorkerMessage) => {
+      if (settled) return
+      switch (message.type) {
+        case "progress":
+          emit(message.entries)
+          break
+        case "call":
+          if (message.method === "workflow") {
+            void handleLoadWorkflow(
+              message.callId,
+              message.payload as WorkflowScriptRef,
+            )
+            break
+          }
+          if (message.method !== "agent") {
+            respond(
+              message.callId,
+              false,
+              undefined,
+              `Unknown workflow host method "${message.method}".`,
+              true,
+            )
+            break
+          }
+          void handleAgent(message.callId, message.payload as AgentCallPayload)
+          break
+        case "complete": {
+          // The script is done, so every launch it made should have been
+          // answered by now — a response is sent before the worker can post
+          // this, so anything still open was never awaited. finish() aborts
+          // those children on the way out.
+          const unawaited = [...openLaunches.values()]
+          if (unawaited.length > 0) {
+            finish({
+              status: "failed",
+              error: unawaitedLaunchMessage(unawaited),
+            })
+            break
+          }
+          finish({
+            status: "completed",
+            ...(message.resultJson === undefined
+              ? {}
+              : { value: JSON.parse(message.resultJson) }),
+          })
+          break
+        }
+        case "error":
+          finish({ status: "failed", error: message.message })
+          break
+      }
+    })
+
+    worker.on("error", (error) => {
+      finish({
+        status: "failed",
+        error: error instanceof Error ? error.message : String(error),
+      })
+    })
+
+    worker.on("exit", () => {
+      // Only reachable when the worker dies without reporting — a terminate()
+      // we did not initiate, or a hard crash.
+      finish({
+        status: "failed",
+        error: "Workflow worker exited before completing.",
+      })
+    })
+  })
+}