@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/engine/workflow/host.mjs

@@ -0,0 +1,524 @@
+/**
+ * lib/engine/workflow/host.mjs — executing one workflow run: the engine side of
+ * agent(), workflow(), phase(), log() and budget.
+ *
+ * An agent() call:
+ *   1. is checked (`checkAgentCall`, pure): prompt, known options, a schema this
+ *      validator enforces (json-schema.mjs), effort, isolation;
+ *   2. counts against the run's lifetime cap (`LIFETIME_AGENT_CAP`, nested runs
+ *      included) and is refused once the token budget is spent;
+ *   3. gets its key and occurrence (journal.mjs) and is answered from the
+ *      journal when a resume's replay plan has it;
+ *   4. otherwise waits for a slot (the session's semaphore: at most
+ *      min(16, cpus − 2) children at once), is checked against `Task(<type>)`
+ *      rules for its agent type (so a workflow cannot start a type the session
+ *      refuses), and runs as a subagent through the agents runtime
+ *      (`runChild`): the session's permission ceiling, attribution headers,
+ *      a sidechain transcript, and a usage record that joins the parent's
+ *      result;
+ *   5. with `schema`, the child is given a `StructuredOutput` tool whose input
+ *      is validated against the schema; a child that ends without a valid
+ *      call is run again (`SCHEMA_RETRIES`) with the reason and its last message;
+ *   6. with `isolation: "worktree"`, runs in a new git worktree (worktree.mjs);
+ *      outside a repository the call REJECTS (a usage error, not a child failure);
+ *   7. resolves to the child's final text, the validated object, or null when
+ *      the child failed — and is journaled either way.
+ *
+ * When the script settles (returns, throws, or is stopped), every call still
+ * running or queued is aborted and awaited (bounded, `SETTLE_WAIT_MS`) before
+ * the run resolves, so no child outlives its run.
+ *
+ * @module lib/engine/workflow/host
+ */
+
+import os from "node:os";
+import path from "node:path";
+import { findAgent } from "../agents/definitions.mjs";
+import { totalTokens } from "../wire/usage.mjs";
+import { callKey, nestedKey } from "./journal.mjs";
+import { schemaProblems, validateJsonSchema } from "./json-schema.mjs";
+import { parseWorkflowSource } from "./meta.mjs";
+import { MAX_ITEMS, compileWorkflow, runInSandbox } from "./sandbox.mjs";
+import { createWorktree, finishWorktree } from "./worktree.mjs";
+
+export const LIFETIME_AGENT_CAP = 1000;
+export const SCHEMA_RETRIES = 2;
+export const EFFORTS = Object.freeze(["low", "medium", "high", "xhigh", "max"]);
+const MAX_PROMPT_CHARS = 1_000_000;
+const MAX_LOGS = 500;
+const RETRY_TEXT_CHARS = 4_000;
+/** How long a settled script waits for its aborted, still-running calls to wind down. */
+export const SETTLE_WAIT_MS = 10_000;
+/** CF-90: how long a script may keep running once its token budget is spent before its worker is terminated. */
+export const BUDGET_GRACE_MS = 30_000;
+
+/** @param {number} [cpus] */
+export function defaultConcurrency(cpus = os.cpus().length) {
+  return Math.max(1, Math.min(16, cpus - 2));
+}
+
+/**
+ * A counting semaphore. `acquire` resolves to a release function, or null when
+ * the signal fired while waiting.
+ * @param {number} limit
+ */
+export function createSemaphore(limit) {
+  let active = 0;
+  /** @type {Array<() => void>} */
+  const waiting = [];
+  return {
+    limit,
+    get active() {
+      return active;
+    },
+    /** @param {AbortSignal} [signal] @returns {Promise<(() => void)|null>} */
+    acquire(signal) {
+      return new Promise((resolve) => {
+        if (signal?.aborted) return resolve(null);
+        const grant = () => {
+          active++;
+          let released = false;
+          resolve(() => {
+            if (released) return;
+            released = true;
+            active--;
+            waiting.shift()?.();
+          });
+        };
+        if (active < limit) return grant();
+        const onAbort = () => {
+          const i = waiting.indexOf(entry);
+          if (i !== -1) waiting.splice(i, 1);
+          resolve(null);
+        };
+        const entry = () => {
+          signal?.removeEventListener("abort", onAbort);
+          grant();
+        };
+        waiting.push(entry);
+        signal?.addEventListener("abort", onAbort, { once: true });
+      });
+    },
+  };
+}
+
+/**
+ * @typedef {Object} RunState  shared by a run and its nested workflows
+ * @property {string} runId
+ * @property {import('./meta.mjs').WorkflowMeta} meta
+ * @property {Array<{title:string, done:number, running:number, failed:number}>} phases
+ * @property {string|null} currentPhase
+ * @property {string[]} logs
+ * @property {{done:number, running:number, failed:number, replayed:number}} agents
+ * @property {number} lifetime
+ * @property {number} spent          tokens of finished (and replayed) agents
+ * @property {number|null} budgetTotal
+ * @property {number} maxRunning
+ * @property {number} seq
+ * @property {Map<string, number>} occurrences
+ * @property {Array<{seq:number, path:string, branch:string, reason:string}>} worktreesKept
+ */
+
+/** @param {{runId:string, meta:import('./meta.mjs').WorkflowMeta, budgetTotal:number|null}} o @returns {RunState} */
+export function createRunState({ runId, meta, budgetTotal }) {
+  return {
+    runId,
+    meta,
+    phases: meta.phases.map((p) => ({ title: p.title, done: 0, running: 0, failed: 0 })),
+    currentPhase: null,
+    logs: [],
+    agents: { done: 0, running: 0, failed: 0, replayed: 0 },
+    lifetime: 0,
+    spent: 0,
+    budgetTotal,
+    maxRunning: 0,
+    seq: 0,
+    occurrences: new Map(),
+    worktreesKept: [],
+  };
+}
+
+/**
+ * Check an agent() call's arguments. Pure.
+ * @param {any} data
+ * @returns {{ok:true, prompt:string, opts:Record<string, any>}|{ok:false, error:string}}
+ */
+export function checkAgentCall(data) {
+  const prompt = data?.prompt;
+  if (typeof prompt !== "string" || prompt.trim() === "") return { ok: false, error: "agent(prompt, opts): prompt must be a non-empty string" };
+  if (prompt.length > MAX_PROMPT_CHARS) return { ok: false, error: `agent(): the prompt is longer than ${MAX_PROMPT_CHARS} characters` };
+  const opts = data?.opts && typeof data.opts === "object" && !Array.isArray(data.opts) ? data.opts : {};
+  for (const k of ["label", "phase", "model", "agentType"]) {
+    if (opts[k] !== undefined && (typeof opts[k] !== "string" || opts[k].trim() === "")) return { ok: false, error: `agent(): ${k} must be a non-empty string` };
+  }
+  if (opts.effort !== undefined && !EFFORTS.includes(opts.effort)) return { ok: false, error: `agent(): effort must be one of ${EFFORTS.join(", ")}` };
+  if (opts.isolation !== undefined && opts.isolation !== "worktree") return { ok: false, error: 'agent(): isolation can only be "worktree"' };
+  if (opts.schema !== undefined) {
+    const problems = schemaProblems(opts.schema);
+    if (problems.length > 0) return { ok: false, error: `agent(): the schema cannot be enforced: ${problems.slice(0, 5).join("; ")}` };
+  }
+  return { ok: true, prompt, opts };
+}
+
+/**
+ * The tool a structured-output child returns its result with. The wire needs an
+ * object input, so a non-object schema is wrapped as {value}.
+ * Authorship: written for Cohort Engine by the Cohort team, 2026-09-14.
+ * @param {any} schema @param {(value:unknown) => void} onValid
+ */
+export function structuredOutputTool(schema, onValid) {
+  const wrapped = isObjectSchema(schema) ? schema : { type: "object", properties: { value: schema }, required: ["value"], additionalProperties: false };
+  return {
+    name: "StructuredOutput",
+    readOnly: true,
+    passthroughInput: true, // validated in full below, not by the loop's shallow check
+    description:
+      "Hand your result back to the workflow that started you. Call this once, when the work is done, with the result as the input. " +
+      "The input must match the schema of this tool; a call that does not is refused with the reasons and you can call it again.",
+    input_schema: wrapped,
+    /** @param {any} input */
+    async run(input) {
+      const v = validateJsonSchema(wrapped, input);
+      if (!v.ok) return { ok: false, error: `The result does not match the required schema: ${v.errors.join("; ")}. Call StructuredOutput again with a corrected result.` };
+      onValid(wrapped === schema ? input : input.value);
+      return { ok: true, content: "Result recorded. Reply with one short line and end your turn." };
+    },
+  };
+}
+
+/** @param {any} schema */
+function isObjectSchema(schema) {
+  return Boolean(schema && typeof schema === "object" && (schema.type === "object" || (schema.type === undefined && schema.properties)));
+}
+
+/** @param {any} schema */
+function schemaInstruction(schema) {
+  const input = isObjectSchema(schema) ? "the result itself" : 'an object {"value": <the result>}';
+  return `\n\nWhen the work is done, call the StructuredOutput tool with ${input} as its input. It must match this JSON Schema:\n${JSON.stringify(schema)}`;
+}
+
+/** @param {any} record */
+function recordTokens(record) {
+  try {
+    return record?.usage ? totalTokens(record.usage) : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/** @param {RunState} state @param {string} title */
+function phaseEntry(state, title) {
+  let e = state.phases.find((p) => p.title === title);
+  if (!e) {
+    e = { title, done: 0, running: 0, failed: 0 };
+    state.phases.push(e);
+  }
+  return e;
+}
+
+/**
+ * @typedef {Object} HostDeps
+ * @property {string} cwd
+ * @property {string} runDir
+ * @property {import('../agents/definitions.mjs').AgentDefinition[]} agents
+ * @property {(p:any) => Promise<{ok:boolean, agentId:string, text:string, error:string|null, stopKind:string, record?:any}>} runChild
+ * @property {(o:{agentType:string}) => {behavior:'allow'|'deny'|'ask', reason:string}} [checkAgent]
+ * @property {ReturnType<typeof createSemaphore>} semaphore
+ * @property {number} [lifetimeCap]
+ * @property {number} [maxItems]
+ * @property {(ref:string) => {ok:true, source:string, path:string}|{ok:false, error:string}} resolveRef
+ * @property {{create:(o:{runDir:string, runId:string, seq:number}) => Promise<any>, finish:(w:any) => Promise<{removed:boolean, reason:string}>}} [worktrees]
+ * @property {string|null} [parentToolUseId]
+ * @property {number} [syncTimeoutMs]
+ * @property {number} [busyTimeoutMs]   CF-90: the script's thread may go this long without yielding
+ * @property {number|null} [runTimeoutMs] CF-90: the top-level script's time limit (null: none)
+ * @property {number} [settleWaitMs]
+ * @property {number} [budgetGraceMs]   CF-90: once the budget is spent, how long before the script is stopped
+ */
+
+/**
+ * Execute a compiled workflow (a top-level run, or a nested one sharing its state).
+ * @param {object} p
+ * @param {import('./sandbox.mjs').CompiledWorkflow} p.script
+ * @param {import('./meta.mjs').WorkflowMeta} p.meta
+ * @param {unknown} p.args
+ * @param {RunState} p.state
+ * @param {ReturnType<typeof import('./journal.mjs').createJournal>} p.journal
+ * @param {ReturnType<typeof import('./journal.mjs').createReplay>|null} p.replay
+ * @param {HostDeps} p.deps
+ * @param {AbortSignal} p.signal
+ * @param {string} [p.scope]
+ * @param {number} [p.depth]
+ * @returns {Promise<{ok:true, json:string}|{ok:false, error:string, stack?:string|null, stopped?:boolean}>}
+ */
+export async function executeRun({ script, meta, args, state, journal, replay, deps, signal, scope = "", depth = 0 }) {
+  const lifetimeCap = deps.lifetimeCap ?? LIFETIME_AGENT_CAP;
+  // The run's own signal fires on a stop (the outer signal) OR when the script settles.
+  // Calls still running or queued when the script returns or throws (an un-awaited
+  // agent(), say) are aborted and settled before this resolves: none outlives its run,
+  // holds a concurrency slot, keeps spending, or journals after the `end` record.
+  const live = new AbortController();
+  const onOuterAbort = () => live.abort();
+  if (signal.aborted) live.abort();
+  else signal.addEventListener("abort", onOuterAbort, { once: true });
+  /** @type {Set<Promise<unknown>>} */
+  const inflight = new Set();
+  /** @template T @param {Promise<T>} p @returns {Promise<T>} */
+  const track = (p) => {
+    inflight.add(p);
+    const drop = () => inflight.delete(p);
+    p.then(drop, drop);
+    return p;
+  };
+  let scriptSettled = false;
+  // W4-E2 (CF-90): once the token budget is spent, the script has a grace period to wrap up
+  // (catch the refusal, return a partial result); after it the worker is terminated.
+  /** @type {(r:any)=>void} */
+  let budgetStop = () => {};
+  const budgetStopped = new Promise((resolve) => (budgetStop = resolve));
+  /** @type {ReturnType<typeof setTimeout>|null} */
+  let budgetTimer = null;
+  const armBudgetStop = () => {
+    if (budgetTimer !== null || scriptSettled || state.budgetTotal === null || state.spent < state.budgetTotal) return;
+    const graceMs = deps.budgetGraceMs ?? BUDGET_GRACE_MS;
+    budgetTimer = setTimeout(() => budgetStop({ ok: false, error: `the workflow's token budget (${state.budgetTotal}) is spent (${state.spent} used) and the script did not finish within ${graceMs} ms; it was stopped` }), graceMs);
+  };
+  const prefix = depth > 0 ? `${meta.name} › ` : "";
+  const worktrees = deps.worktrees ?? {
+    create: (/** @type any */ o) => createWorktree({ cwd: deps.cwd, dir: path.join(o.runDir, "worktrees", `agent-${o.seq}`), branch: `cohort-workflow/${o.runId}/agent-${o.seq}` }),
+    finish: finishWorktree,
+  };
+  /** @type {(id:number, json:string|null, error:string|null) => void} */
+  let deliver = () => {};
+  let closed = false;
+  const send = (/** @type number */ id, /** @type {string|null} */ json, /** @type {string|null} */ error) => {
+    if (!closed) deliver(id, json, error);
+  };
+  const addLog = (/** @type string */ message) => {
+    state.logs.push(message);
+    if (state.logs.length > MAX_LOGS) state.logs.splice(0, state.logs.length - MAX_LOGS);
+  };
+
+  /** @param {{prompt:string, opts:Record<string, any>, key:string, occurrence:number, id:number, phase:string|null}} c */
+  async function runLive({ prompt, opts, key, occurrence, id, phase }) {
+    const label = opts.label ?? null;
+    const release = await deps.semaphore.acquire(live.signal);
+    const entry = phase ? phaseEntry(state, phase) : null;
+    /** @type {{status:'ok'|'failed', result:unknown, error:string|null, agentId:string|null, tokens:number, reject:string|null}} */
+    const out = { status: "failed", result: null, error: null, agentId: null, tokens: 0, reject: null };
+    if (!release) {
+      out.error = scriptSettled && !signal.aborted ? "the workflow's script ended before this agent started" : "the workflow was stopped before this agent started";
+      state.agents.failed++;
+      if (entry) entry.failed++;
+      journal.append({ type: "agent", seq: id, key, occurrence, label, phase, status: "failed", replayed: false, result: null, tokens: 0, agentId: null, error: out.error });
+      return { value: null, reject: null };
+    }
+    state.agents.running++;
+    state.maxRunning = Math.max(state.maxRunning, state.agents.running);
+    if (entry) entry.running++;
+    /** @type {any} */
+    let worktree = null;
+    let note = "";
+    // The work fills `out`; the result is returned only after the worktree is settled,
+    // so a kept worktree's note reaches the script.
+    const work = async () => {
+      const found = findAgent(deps.agents, opts.agentType ?? "general-purpose");
+      if (!found.ok) {
+        out.error = found.error;
+        return;
+      }
+      const verdict = deps.checkAgent?.({ agentType: found.agent.name });
+      if (verdict && verdict.behavior !== "allow") {
+        out.error = `the ${found.agent.name} agent type is ${verdict.behavior === "deny" ? "refused" : "not allowed without approval"} for this session (${verdict.reason})`;
+        return;
+      }
+      const def = opts.model ? { ...found.agent, model: opts.model } : found.agent;
+      if (opts.isolation === "worktree") {
+        worktree = await worktrees.create({ runDir: deps.runDir, runId: state.runId, seq: id });
+        if (!worktree.ok) {
+          out.error = worktree.error;
+          // Asking for isolation where there is no repository is a usage error: the
+          // script's agent() rejects with it rather than resolving to null.
+          if (worktree.usage) out.reject = worktree.error;
+          worktree = null;
+          return;
+        }
+      }
+      const description = label ?? `${state.meta.name}: agent ${id}`;
+      const attempts = opts.schema !== undefined ? 1 + SCHEMA_RETRIES : 1;
+      const instruction = opts.schema !== undefined ? schemaInstruction(opts.schema) : "";
+      let childPrompt = prompt + instruction;
+      for (let attempt = 0; attempt < attempts && !live.signal.aborted; attempt++) {
+        /** @type {{value:unknown}|null} */
+        let captured = null;
+        const extraTools = opts.schema !== undefined ? [structuredOutputTool(opts.schema, (value) => (captured = { value }))] : [];
+        const r = await deps.runChild({ def, prompt: childPrompt, description, parentToolUseId: deps.parentToolUseId ?? null, signal: live.signal, background: true, extraTools, effort: opts.effort ?? null, cwd: worktree?.path ?? null });
+        out.agentId = r.agentId;
+        out.tokens += recordTokens(r.record);
+        if (!r.ok && scriptSettled && !signal.aborted) {
+          out.error = "the workflow's script ended while this agent was still running";
+          break;
+        }
+        if (opts.schema === undefined) {
+          if (r.ok) {
+            out.status = "ok";
+            out.result = r.text;
+          } else out.error = r.error;
+          break;
+        }
+        if (captured) {
+          out.status = "ok";
+          out.result = /** @type {{value:unknown}} */ (captured).value;
+          break;
+        }
+        out.error = r.ok ? "the agent ended without a valid StructuredOutput call" : r.error;
+        const last = r.text ? ` Its final message was:\n${r.text.slice(0, RETRY_TEXT_CHARS)}` : "";
+        childPrompt = `${prompt}${instruction}\n\nAn earlier attempt at this task ended without returning its result (${out.error}).${last}\nDo the task and call StructuredOutput with a result that matches the schema.`;
+      }
+    };
+    try {
+      await work();
+    } finally {
+      if (worktree) {
+        const fin = await worktrees.finish(worktree).catch((e) => ({ removed: false, reason: e instanceof Error ? e.message : String(e) }));
+        if (!fin.removed) {
+          note = `worktree kept at ${worktree.root} (branch ${worktree.branch}): ${fin.reason}`;
+          state.worktreesKept.push({ seq: id, path: worktree.root, branch: worktree.branch, reason: fin.reason });
+          addLog(`agent ${id}: ${note}`);
+          if (out.status === "ok" && typeof out.result === "string") out.result = `${out.result}\n\n[${note}]`;
+        }
+      }
+      release();
+      state.agents.running--;
+      if (entry) entry.running--;
+      if (out.status === "ok") {
+        state.agents.done++;
+        if (entry) entry.done++;
+      } else {
+        state.agents.failed++;
+        if (entry) entry.failed++;
+        if (out.error) addLog(`agent ${id}${label ? ` (${label})` : ""} failed: ${out.error}`);
+      }
+      state.spent += out.tokens;
+      armBudgetStop();
+      journal.append({ type: "agent", seq: id, key, occurrence, label, phase, status: out.status, replayed: false, result: out.status === "ok" ? out.result : null, tokens: out.tokens, agentId: out.agentId, error: out.error, worktree: note || null });
+    }
+    return { value: out.status === "ok" ? out.result : null, reject: out.reject };
+  }
+
+  /** @type {import('./sandbox.mjs').SandboxHandlers} */
+  const handlers = {
+    agent(data) {
+      const v = checkAgentCall(data);
+      if (!v.ok) return { error: v.error };
+      if (live.signal.aborted) return { error: "the workflow was stopped" };
+      if (state.lifetime >= lifetimeCap) return { error: `this workflow has made ${lifetimeCap} agent() calls, the most one run may make` };
+      if (state.budgetTotal !== null && state.spent >= state.budgetTotal) {
+        armBudgetStop();
+        return { error: `the workflow's token budget (${state.budgetTotal}) is spent (${state.spent} used)` };
+      }
+      state.lifetime++;
+      const id = ++state.seq;
+      const key = callKey({ scope, prompt: v.prompt, opts: v.opts });
+      const occurrence = state.occurrences.get(key) ?? 0;
+      state.occurrences.set(key, occurrence + 1);
+      const phase = v.opts.phase ? prefix + v.opts.phase : state.currentPhase;
+      const hit = replay?.take(key, occurrence);
+      if (hit) {
+        const tokens = Number.isFinite(hit.tokens) ? hit.tokens : 0;
+        state.agents.replayed++;
+        state.agents.done++;
+        state.spent += tokens;
+        armBudgetStop();
+        if (phase) phaseEntry(state, phase).done++;
+        journal.append({ type: "agent", seq: id, key, occurrence, label: v.opts.label ?? null, phase, status: "ok", replayed: true, result: hit.result ?? null, tokens, agentId: hit.agentId ?? null, error: null });
+        const json = JSON.stringify(hit.result ?? null);
+        queueMicrotask(() => send(id, json, null));
+        return { id };
+      }
+      track(runLive({ prompt: v.prompt, opts: v.opts, key, occurrence, id, phase })).then(
+        (r) => (r.reject !== null ? send(id, null, r.reject) : send(id, JSON.stringify(r.value ?? null), null)),
+        (e) => {
+          addLog(`agent ${id} failed unexpectedly: ${e instanceof Error ? e.message : String(e)}`);
+          send(id, "null", null);
+        },
+      );
+      return { id };
+    },
+    workflow(data) {
+      if (depth >= 1) return { error: "workflow(): a nested workflow cannot start another workflow (one level of nesting)" };
+      const ref = deps.resolveRef(String(data?.ref ?? ""));
+      if (!ref.ok) return { error: ref.error };
+      const parsed = parseWorkflowSource(ref.source);
+      if (!parsed.ok) return { error: `workflow(${JSON.stringify(data.ref)}): ${parsed.error}` };
+      const compiled = compileWorkflow(parsed.body, `workflow:${parsed.meta.name}`);
+      if (!compiled.ok) return { error: `workflow(${JSON.stringify(data.ref)}): ${compiled.error}` };
+      const nArgs = data?.args ?? null;
+      const nk = `wf:${nestedKey({ scope, source: ref.source, args: nArgs })}`;
+      const occurrence = state.occurrences.get(nk) ?? 0;
+      state.occurrences.set(nk, occurrence + 1);
+      const id = ++state.seq;
+      journal.append({ type: "workflow", seq: id, name: parsed.meta.name, path: ref.path, key: nk, occurrence });
+      track(executeRun({ script: compiled.script, meta: parsed.meta, args: nArgs, state, journal, replay, deps, signal: live.signal, scope: `${scope}${nk}#${occurrence}/`, depth: depth + 1 })).then(
+        (r) => (r.ok ? send(id, r.json, null) : send(id, null, `the nested workflow "${parsed.meta.name}" failed: ${r.error}`)),
+        (e) => send(id, null, `the nested workflow "${parsed.meta.name}" failed: ${e instanceof Error ? e.message : String(e)}`),
+      );
+      return { id };
+    },
+    phase(title) {
+      const t = prefix + title;
+      state.currentPhase = t;
+      phaseEntry(state, t);
+      journal.append({ type: "phase", title: t });
+    },
+    log(message) {
+      addLog(prefix + message);
+      journal.append({ type: "log", message: prefix + message });
+    },
+    spent: () => state.spent,
+  };
+
+  // W4-E2 (CF-90): the script runs in a worker thread; the run's time limit applies to the top-level script.
+  const sb = runInSandbox({ script, args, handlers, limits: { budgetTotal: state.budgetTotal, allowNested: depth === 0, maxItems: deps.maxItems ?? MAX_ITEMS }, syncTimeoutMs: deps.syncTimeoutMs, busyTimeoutMs: deps.busyTimeoutMs, runTimeoutMs: depth === 0 ? (deps.runTimeoutMs ?? null) : null });
+  deliver = sb.deliver;
+  /** @type {() => void} */
+  let unlisten = () => {};
+  const stopped = new Promise((resolve) => {
+    const onAbort = () => resolve({ ok: false, error: "the workflow was stopped", stopped: true });
+    if (signal.aborted) onAbort();
+    else {
+      signal.addEventListener("abort", onAbort, { once: true });
+      unlisten = () => signal.removeEventListener("abort", onAbort);
+    }
+  });
+  try {
+    return /** @type any */ (await Promise.race([sb.done, stopped, budgetStopped]));
+  } finally {
+    closed = true;
+    scriptSettled = true;
+    if (budgetTimer !== null) clearTimeout(budgetTimer);
+    // A stopped (or busy) script's worker is terminated before its calls are wound down.
+    await sb.terminate();
+    unlisten();
+    signal.removeEventListener("abort", onOuterAbort);
+    const left = inflight.size;
+    if (left > 0 && !signal.aborted) {
+      const message = `${prefix}the script ended with ${left} agent or workflow call${left === 1 ? "" : "s"} still running or queued; ${left === 1 ? "it was" : "they were"} stopped`;
+      addLog(message);
+      journal.append({ type: "log", message });
+    }
+    live.abort();
+    if (left > 0) await settleWithin([...inflight], deps.settleWaitMs ?? SETTLE_WAIT_MS);
+  }
+}
+
+/** Wait for every promise to settle, or `ms`, whichever comes first. @param {Promise<unknown>[]} promises @param {number} ms */
+function settleWithin(promises, ms) {
+  return new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    Promise.allSettled(promises).then(() => {
+      clearTimeout(t);
+      resolve(undefined);
+    });
+  });
+}