@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/engine/workflow/notifications.mjs

@@ -0,0 +1,52 @@
+/**
+ * lib/engine/workflow/notifications.mjs — one notification source for the loop
+ * from several (the agent runtime's background tasks, workflow runs).
+ *
+ * The loop takes one `drainNotifications` and one `awaitNotifications`
+ * (loop.mjs). This merges sources that each have those plus `hasRunning`:
+ *
+ *   drain   every source's ready notifications, in source order
+ *   await   ready ones now; otherwise wait until any running source produces
+ *           one (a source that wakes with nothing — its work was read early —
+ *           waits again), or nothing is running, or the signal fires
+ *
+ * The other sources' waits are released when one wins, and whatever they
+ * drained on release is kept, so no notification is lost to the race.
+ *
+ * @module lib/engine/workflow/notifications
+ */
+
+/**
+ * @typedef {{drainNotifications:() => string[], awaitNotifications:(signal?:AbortSignal) => Promise<string[]>, hasRunning:() => boolean}} NotificationSource
+ */
+
+/** @param {Array<NotificationSource|null|undefined>} sources */
+export function mergeNotificationSources(sources) {
+  const list = /** @type {NotificationSource[]} */ (sources.filter(Boolean));
+  const drainNotifications = () => list.flatMap((s) => s.drainNotifications());
+  return {
+    drainNotifications,
+    hasRunning: () => list.some((s) => s.hasRunning()),
+    /** @param {AbortSignal} [signal] */
+    async awaitNotifications(signal) {
+      for (;;) {
+        const ready = drainNotifications();
+        if (ready.length > 0) return ready;
+        const running = list.filter((s) => s.hasRunning());
+        if (running.length === 0 || signal?.aborted) return [];
+        const inner = new AbortController();
+        const onOuter = () => inner.abort();
+        signal?.addEventListener("abort", onOuter, { once: true });
+        try {
+          const waits = running.map((s) => s.awaitNotifications(inner.signal));
+          await Promise.race(waits);
+          inner.abort();
+          const got = (await Promise.all(waits)).flat();
+          if (got.length > 0) return [...got, ...drainNotifications()];
+        } finally {
+          signal?.removeEventListener("abort", onOuter);
+        }
+      }
+    },
+  };
+}

package/lib/engine/workflow/runtime.mjs

@@ -0,0 +1,447 @@
+/**
+ * lib/engine/workflow/runtime.mjs — the session's workflow runs: starting one
+ * in the background, resuming from a journal, progress, completion
+ * notifications, stopping.
+ *
+ * A run starts from an inline `script`, a `scriptPath`, or (with
+ * `resumeFromRunId` alone) the script the earlier run persisted. Everything
+ * that can be refused is refused BEFORE the run exists and is the Workflow
+ * call's error: the size cap, the meta literal, `import`, a syntax error,
+ * args that are not JSON, a script file the session's Read rules refuse, an
+ * unknown run (or another project's) to resume, and a run that may still be
+ * running (in this process, or in another live process that has not written its
+ * `end` record).
+ *
+ * The call returns {runId, scriptPath} at once. The run executes in this
+ * process (host.mjs), and when it ends a notification — the script's return
+ * value, cut at `RESULT_INLINE_CHARS` with the path of the full `result.json`
+ * — is queued and delivered by the loop as a user message, exactly like a
+ * background subagent's report (agents/runtime.mjs; merged with it by
+ * notifications.mjs). A run read to its end with WorkflowStatus is not
+ * notified again. Runs still going when the conversation's turn ends are
+ * stopped, as background subagents are.
+ *
+ * @module lib/engine/workflow/runtime
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { writeFileAtomic } from "../../fs-atomic.mjs";
+import { LIFETIME_AGENT_CAP, createRunState, createSemaphore, defaultConcurrency, executeRun } from "./host.mjs";
+import { createJournal, createReplay, findRunDir, isRunId, newRunId, readJournal, runDirFor, runSummary } from "./journal.mjs";
+import { MAX_SCRIPT_BYTES, parseWorkflowSource } from "./meta.mjs";
+import { compileWorkflow } from "./sandbox.mjs";
+import { PROCESS_NONCE, judgeOwner, processAlive, processStartToken } from "../process-identity.mjs";
+
+export const RESULT_INLINE_CHARS = 20_000;
+export const MAX_ARGS_CHARS = 1_000_000;
+const STOP_WAIT_MS = 10_000;
+const STATUS_LOG_LINES = 20;
+
+/**
+ * @typedef {Object} WorkflowRuntimeDeps
+ * @property {string} sessionId
+ * @property {string} sessionsDir
+ * @property {string} cwd
+ * @property {import('../agents/definitions.mjs').AgentDefinition[]} agents
+ * @property {(p:any) => Promise<any>} runChild            agents/runtime.mjs runChild
+ * @property {(o:{agentType:string}) => {behavior:'allow'|'deny'|'ask', reason:string}} [checkAgent]
+ * @property {() => number} [now]
+ * @property {number} [maxConcurrency]    default min(16, cpus − 2), at least 1
+ * @property {number} [lifetimeCap]       agent() calls per run, default 1000
+ * @property {number} [maxItems]          items per parallel()/pipeline(), default 4096
+ * @property {number|null} [budgetTokens] the budget's total; null = unlimited
+ * @property {number} [syncTimeoutMs]
+ * @property {number} [busyTimeoutMs]     CF-90: how long a script may go without yielding (sandbox.mjs BUSY_TIMEOUT_MS)
+ * @property {number|null} [runTimeoutMs] CF-90: a run's time limit; null = none
+ * @property {number} [budgetGraceMs]     CF-90: once a run's budget is spent, how long its script may go on (host.mjs BUDGET_GRACE_MS)
+ * @property {HostWorktrees} [worktrees]
+ * @property {(o:{path:string}) => {behavior:'allow'|'deny'|'ask', reason:string}} [checkRead]
+ *           the session's Read evaluation for a script file named by scriptPath or workflow(ref)
+ * @property {number} [pid]                          this process (default process.pid)
+ * @property {string} [nonce]                        this process's nonce (default process-identity.mjs PROCESS_NONCE)
+ * @property {(pid:number) => boolean} [isProcessAlive]
+ * @property {(pid:number) => string|null} [processStartToken]  the OS start time of a PID (process-identity.mjs)
+ * @property {number} [settleWaitMs]
+ * @property {() => void} [onNotify]  a run's notification was queued (wakes an idle `cohort session`)
+ */
+/** @typedef {NonNullable<import('./host.mjs').HostDeps['worktrees']>} HostWorktrees */
+
+/** Run ids executing in THIS process, whichever runtime started them (a host may build several). */
+const PROCESS_RUNNING_RUNS = new Set();
+
+/**
+ * Workflow timing knobs from the environment (W4-E2 review: a canary can loosen them without a code
+ * change). Unset or invalid: the defaults (sandbox.mjs BUSY_TIMEOUT_MS, host.mjs BUDGET_GRACE_MS, no run
+ * time limit). Pure.
+ *   COHORT_ENGINE_WORKFLOW_TIMEOUT_MS          a run's time limit
+ *   COHORT_ENGINE_WORKFLOW_BUSY_TIMEOUT_MS     how long a script may go without its event loop turning
+ *   COHORT_ENGINE_WORKFLOW_BUDGET_GRACE_MS     how long a script may go on once its token budget is spent
+ * @param {Record<string, string|undefined>} env
+ * @returns {{runTimeoutMs:number|null, busyTimeoutMs?:number, budgetGraceMs?:number}}
+ */
+export function workflowTimingFromEnv(env) {
+  const ms = (/** @type {string|undefined} */ v) => {
+    const n = Number(v);
+    return v !== undefined && v !== "" && Number.isInteger(n) && n > 0 ? n : null;
+  };
+  const busy = ms(env.COHORT_ENGINE_WORKFLOW_BUSY_TIMEOUT_MS);
+  const grace = ms(env.COHORT_ENGINE_WORKFLOW_BUDGET_GRACE_MS);
+  return { runTimeoutMs: ms(env.COHORT_ENGINE_WORKFLOW_TIMEOUT_MS), ...(busy !== null ? { busyTimeoutMs: busy } : {}), ...(grace !== null ? { budgetGraceMs: grace } : {}) };
+}
+
+/** @param {WorkflowRuntimeDeps} d */
+export function createWorkflowRuntime(d) {
+  const now = d.now ?? Date.now;
+  const pid = d.pid ?? process.pid;
+  const nonce = d.nonce ?? PROCESS_NONCE;
+  const isAlive = d.isProcessAlive ?? processAlive;
+  const startTokenOf = d.processStartToken ?? processStartToken;
+  /**
+   * Is a run whose journal has no `end` still running somewhere (W4-E2 review: not by bare PID)?
+   * @param {string} runId @param {{pid:number|null, nonce:string|null, startToken:string|null}} summary
+   */
+  const stillRunning = (runId, summary) => {
+    if (summary.pid === null) return false;
+    const owner = judgeOwner({ pid: summary.pid, nonce: summary.nonce, startToken: summary.startToken }, { pid, nonce }, { isAlive, startToken: startTokenOf });
+    return owner === "alive" || (owner === "self" && PROCESS_RUNNING_RUNS.has(runId));
+  };
+  const semaphore = createSemaphore(d.maxConcurrency ?? defaultConcurrency());
+  /** @type {Map<string, any>} */
+  const runs = new Map();
+  /** @type {Array<{runId:string, text:string}>} */
+  const queue = [];
+  /** @type {Set<() => void>} */
+  const waiters = new Set();
+  const wake = () => {
+    for (const w of [...waiters]) w();
+    waiters.clear();
+  };
+
+  /**
+   * @param {string} file
+   * @param {boolean} [named]  a path the model named (scriptPath, workflow(ref)): the session's Read rules apply
+   * @returns {{ok:true, source:string, path:string}|{ok:false, error:string}}
+   */
+  const readScript = (file, named = false) => {
+    if (named && d.checkRead) {
+      const verdict = d.checkRead({ path: file });
+      if (verdict.behavior !== "allow") return { ok: false, error: `reading ${file} is not allowed for this session (${verdict.reason})` };
+    }
+    try {
+      const st = statSync(file);
+      if (!st.isFile()) return { ok: false, error: `${file} is not a file` };
+      if (st.size > MAX_SCRIPT_BYTES) return { ok: false, error: `${file} is ${st.size} bytes; a workflow script may be at most ${MAX_SCRIPT_BYTES}` };
+      return { ok: true, source: readFileSync(file, "utf8"), path: file };
+    } catch (e) {
+      return { ok: false, error: `cannot read ${file} (${e instanceof Error ? e.message : String(e)})` };
+    }
+  };
+
+  /**
+   * workflow(ref): an earlier run's id, a path (relative to the project), or a
+   * name under <project>/.cohort/workflows or <project>/.claude/workflows.
+   * @param {string} ref
+   */
+  const resolveRef = (ref) => {
+    if (isRunId(ref)) {
+      const dir = findRunDir(d.sessionsDir, d.sessionId, ref, { cwd: d.cwd });
+      return dir ? readScript(path.join(dir, "script.js")) : { ok: false, error: `there is no workflow run ${ref} in this session or this project` };
+    }
+    if (ref.includes("/") || /\.m?js$/.test(ref)) return readScript(path.resolve(d.cwd, ref), true);
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(ref)) return { ok: false, error: `workflow(${JSON.stringify(ref)}): not a path, a run id or a workflow name` };
+    for (const dir of [".cohort", ".claude"]) {
+      for (const ext of [".js", ".mjs"]) {
+        const file = path.join(d.cwd, dir, "workflows", `${ref}${ext}`);
+        if (existsSync(file)) return readScript(file, true);
+      }
+    }
+    return { ok: false, error: `there is no workflow named "${ref}" in .cohort/workflows or .claude/workflows` };
+  };
+
+  /** @param {any} run */
+  const view = (run) => {
+    const s = run.state;
+    return {
+      runId: run.id,
+      name: run.meta.name,
+      status: run.status,
+      scriptPath: run.scriptPath,
+      resumedFrom: run.resumedFrom,
+      agents: { ...s.agents },
+      phases: s.phases.map((/** @type any */ p) => ({ ...p })),
+      currentPhase: s.currentPhase,
+      budget: { total: s.budgetTotal, spent: s.spent },
+      worktreesKept: s.worktreesKept.map((/** @type any */ w) => ({ ...w })),
+      recentLogs: s.logs.slice(-STATUS_LOG_LINES),
+      ...(run.error ? { error: run.error } : {}),
+    };
+  };
+
+  /** @param {any} run */
+  const resultText = (run) => {
+    const json = run.resultJson ?? "null";
+    if (json.length <= RESULT_INLINE_CHARS) return json;
+    return `${json.slice(0, RESULT_INLINE_CHARS)}\n… [the result is ${json.length} characters; the whole value is in ${run.resultPath}]`;
+  };
+
+  /** @param {any} run */
+  const notificationText = (run) => {
+    const a = run.state.agents;
+    const counts = `${a.done} agent${a.done === 1 ? "" : "s"} done${a.replayed ? ` (${a.replayed} replayed from ${run.resumedFrom})` : ""}, ${a.failed} failed`;
+    if (run.status === "completed") return `[Workflow ${run.id} finished] "${run.meta.name}" completed: ${counts}. Its result:\n\n${resultText(run)}`;
+    return `[Workflow ${run.id} ended] "${run.meta.name}" did not finish: ${run.error ?? "unknown error"} (${counts}). The journal is kept: Workflow {"resumeFromRunId":"${run.id}"} runs it again, replaying the agent calls that completed.`;
+  };
+
+  /** @param {any} run */
+  const consume = (run) => {
+    run.notified = true;
+    const i = queue.findIndex((q) => q.runId === run.id);
+    if (i !== -1) queue.splice(i, 1);
+  };
+
+  /**
+   * Start a run. Synchronous up to the point the run exists.
+   * @param {{script?:string, scriptPath?:string, args?:unknown, resumeFromRunId?:string}} input
+   * @param {{toolUseId?:string|null, signal?:AbortSignal}} [ctx]
+   * @returns {{ok:true, runId:string, scriptPath:string, name:string, resumedFrom:string|null, replayable:number}|{ok:false, error:string}}
+   */
+  function start(input, ctx = {}) {
+    const hasScript = typeof input.script === "string";
+    const hasPath = typeof input.scriptPath === "string" && input.scriptPath.trim() !== "";
+    if (hasScript && hasPath) return { ok: false, error: "pass either script or scriptPath, not both" };
+
+    let replay = null;
+    let resumedFrom = null;
+    /** @type {{ok:true, source:string, path:string|null}|{ok:false, error:string}|null} */
+    let src = null;
+    if (input.resumeFromRunId !== undefined) {
+      const prev = input.resumeFromRunId;
+      if (!isRunId(prev)) return { ok: false, error: `resumeFromRunId "${prev}" is not a workflow run id (wf_ and 12 hex digits)` };
+      if (runs.get(prev)?.status === "running") return { ok: false, error: `workflow run ${prev} is still running; wait for it or stop it before resuming` };
+      const dir = findRunDir(d.sessionsDir, d.sessionId, prev, { cwd: d.cwd });
+      if (!dir) return { ok: false, error: `there is no workflow run ${prev} to resume (in this session, or started in this project directory)` };
+      const records = readJournal(path.join(dir, "journal.jsonl")).records;
+      // A journal with no `end` is a run that is still going, or one whose process died.
+      // Another live process may still be writing it: refuse rather than race it.
+      const summary = runSummary(records);
+      if (!summary.ended && stillRunning(prev, summary)) {
+        return { ok: false, error: `workflow run ${prev} has not ended and may still be running in ${summary.pid === pid ? "another runtime of this engine process" : "another process"} (pid ${summary.pid}); wait for it or stop that process before resuming` };
+      }
+      replay = createReplay(records);
+      resumedFrom = prev;
+      if (!hasScript && !hasPath) src = readScript(path.join(dir, "script.js"));
+    }
+    if (!src) {
+      if (hasScript) src = { ok: true, source: /** @type string */ (input.script), path: null };
+      else if (hasPath) src = readScript(path.resolve(d.cwd, /** @type string */ (input.scriptPath)), true);
+      else return { ok: false, error: "pass script (the JavaScript source), scriptPath, or resumeFromRunId" };
+    }
+    if (!src.ok) return src;
+
+    const parsed = parseWorkflowSource(src.source);
+    if (!parsed.ok) return parsed;
+    const compiled = compileWorkflow(parsed.body, `workflow:${parsed.meta.name}`);
+    if (!compiled.ok) return compiled;
+    const args = input.args === undefined ? null : input.args;
+    let argsJson;
+    try {
+      argsJson = JSON.stringify(args);
+    } catch {
+      return { ok: false, error: "args must be JSON" };
+    }
+    if (argsJson.length > MAX_ARGS_CHARS) return { ok: false, error: `args are ${argsJson.length} characters of JSON; the limit is ${MAX_ARGS_CHARS}` };
+
+    const runId = newRunId();
+    const dir = runDirFor(d.sessionsDir, d.sessionId, runId);
+    const journal = createJournal({ dir, now });
+    const scriptPath = path.join(dir, "script.js");
+    writeFileAtomic(scriptPath, src.source);
+    journal.append({ type: "run", runId, sessionId: d.sessionId, cwd: d.cwd, pid, nonce, startToken: startTokenOf(pid), name: parsed.meta.name, scriptPath, source: src.path, resumedFrom, args });
+    PROCESS_RUNNING_RUNS.add(runId);
+
+    const state = createRunState({ runId, meta: parsed.meta, budgetTotal: d.budgetTokens ?? null });
+    const controller = new AbortController();
+    const outer = ctx.signal;
+    const onOuter = () => controller.abort();
+    if (outer?.aborted) controller.abort();
+    else outer?.addEventListener("abort", onOuter, { once: true });
+
+    const run = { id: runId, meta: parsed.meta, dir, scriptPath, resultPath: path.join(dir, "result.json"), status: "running", state, resultJson: /** @type {string|null} */ (null), error: /** @type {string|null} */ (null), notified: false, stopRequested: false, controller, resumedFrom, done: Promise.resolve() };
+    runs.set(runId, run);
+    run.done = executeRun({
+      script: compiled.script,
+      meta: parsed.meta,
+      args,
+      state,
+      journal,
+      replay,
+      signal: controller.signal,
+      deps: {
+        cwd: d.cwd,
+        runDir: dir,
+        agents: d.agents,
+        runChild: d.runChild,
+        checkAgent: d.checkAgent,
+        semaphore,
+        lifetimeCap: d.lifetimeCap ?? LIFETIME_AGENT_CAP,
+        maxItems: d.maxItems,
+        resolveRef,
+        worktrees: d.worktrees,
+        parentToolUseId: ctx.toolUseId ?? null,
+        syncTimeoutMs: d.syncTimeoutMs,
+        busyTimeoutMs: d.busyTimeoutMs,
+        runTimeoutMs: d.runTimeoutMs ?? null,
+        budgetGraceMs: d.budgetGraceMs,
+        settleWaitMs: d.settleWaitMs,
+      },
+    })
+      .then(
+        (r) => {
+          if (r.ok) {
+            run.status = "completed";
+            run.resultJson = r.json;
+            writeFileAtomic(run.resultPath, r.json);
+          } else {
+            run.status = run.stopRequested || r.stopped ? "stopped" : "failed";
+            run.error = r.error;
+          }
+        },
+        (e) => {
+          run.status = run.stopRequested ? "stopped" : "failed";
+          run.error = `the workflow runtime failed unexpectedly (${e instanceof Error ? e.message : String(e)})`;
+        },
+      )
+      .finally(() => {
+        outer?.removeEventListener("abort", onOuter);
+        // executeRun settles only after every child it started has (host.mjs), so `end` is the last record.
+        journal.append({ type: "end", status: run.status, error: run.error, resultPath: run.status === "completed" ? run.resultPath : null, worktrees: state.worktreesKept });
+        PROCESS_RUNNING_RUNS.delete(runId);
+        if (!run.notified && run.status !== "stopped") {
+          queue.push({ runId, text: notificationText(run) });
+          d.onNotify?.();
+        }
+        wake();
+      });
+    return { ok: true, runId, scriptPath, name: parsed.meta.name, resumedFrom, replayable: replay?.size ?? 0 };
+  }
+
+  const drainNotifications = () => {
+    const out = queue.splice(0);
+    for (const n of out) {
+      const r = runs.get(n.runId);
+      if (r) r.notified = true;
+    }
+    return out.map((n) => n.text);
+  };
+
+  return {
+    start,
+    resolveRef,
+    /**
+     * Progress of a run; with `block`, wait up to `timeoutMs` for it to end. A
+     * finished run read here is not notified later.
+     * @param {string} runId @param {{block?:boolean, timeoutMs?:number, signal?:AbortSignal}} [o]
+     */
+    async status(runId, { block = false, timeoutMs = 30_000, signal } = {}) {
+      const run = runs.get(runId);
+      if (!run) return { ok: false, error: `There is no workflow run "${runId}" in this session. Known: ${[...runs.keys()].join(", ") || "none"}.` };
+      if (run.status === "running" && block) await waitFor(run.done, timeoutMs, signal);
+      const v = view(run);
+      if (run.status === "running") return { ok: true, view: v, result: null };
+      consume(run);
+      return { ok: true, view: v, result: run.status === "completed" ? resultText(run) : null };
+    },
+    list: () => [...runs.values()].map(view),
+    /** W4-E2: is this run one of this runtime's (TaskOutput / TaskStop take run ids)? @param {string} runId */
+    has: (runId) => runs.has(runId),
+    /**
+     * W4-E2: a run this process does not hold, read from its journal — one started before an engine
+     * restart (this session, or this project). Ended: its status and result; not ended and its
+     * process gone: interrupted, with the way to resume it.
+     * @param {string} runId
+     * @returns {{ok:true, running:boolean, content:string}|{ok:false, error:string}}
+     */
+    diskStatus(runId) {
+      const dir = findRunDir(d.sessionsDir, d.sessionId, runId, { cwd: d.cwd });
+      if (!dir) return { ok: false, error: `There is no workflow run "${runId}" in this session or this project.` };
+      const records = readJournal(path.join(dir, "journal.jsonl")).records;
+      const summary = runSummary(records);
+      const header = records.find((r) => r?.type === "run");
+      const name = typeof header?.name === "string" ? header.name : runId;
+      const end = [...records].reverse().find((r) => r?.type === "end");
+      if (end) {
+        let result = "";
+        if (end.status === "completed") {
+          const file = path.join(dir, "result.json"); // never a path the journal names
+          try {
+            const json = readFileSync(file, "utf8");
+            result = json.length <= RESULT_INLINE_CHARS ? json : `${json.slice(0, RESULT_INLINE_CHARS)}\n… [the result is ${json.length} characters; the whole value is in ${file}]`;
+          } catch {
+            result = `(the result could not be read from ${file})`;
+          }
+        }
+        return { ok: true, running: false, content: `Workflow ${runId} ("${name}") ${end.status === "completed" ? "completed" : end.status === "stopped" ? "was stopped" : "failed"} in an earlier engine process${typeof end.error === "string" && end.error ? `: ${end.error}` : ""}.${result ? `\n\nResult:\n${result}` : ""}` };
+      }
+      if (stillRunning(runId, summary)) {
+        return { ok: true, running: true, content: `Workflow ${runId} ("${name}") has not ended and may still be running in ${summary.pid === pid ? "another runtime of this engine process" : "another engine process"} (pid ${summary.pid}).` };
+      }
+      return { ok: true, running: false, content: `Workflow ${runId} ("${name}") was interrupted: its engine process stopped before the run ended. Workflow {"resumeFromRunId":"${runId}"} runs it again, replaying the agent calls that completed.` };
+    },
+    drainNotifications,
+    /** @param {AbortSignal} [signal] */
+    async awaitNotifications(signal) {
+      if (queue.length) return drainNotifications();
+      if (![...runs.values()].some((r) => r.status === "running")) return [];
+      await new Promise((resolve) => {
+        const done = () => {
+          signal?.removeEventListener("abort", done);
+          waiters.delete(done);
+          resolve(undefined);
+        };
+        waiters.add(done);
+        if (signal?.aborted) done();
+        else signal?.addEventListener("abort", done, { once: true });
+      });
+      return drainNotifications();
+    },
+    hasRunning: () => [...runs.values()].some((r) => r.status === "running"),
+    /** Stop every running run and wait for it (bounded). */
+    async stopAll() {
+      const running = [...runs.values()].filter((r) => r.status === "running");
+      for (const r of running) {
+        r.stopRequested = true;
+        r.notified = true;
+        r.controller.abort();
+      }
+      await Promise.all(running.map((r) => waitFor(r.done, STOP_WAIT_MS)));
+    },
+    /** @param {string} runId */
+    async stop(runId) {
+      const run = runs.get(runId);
+      if (!run) return { ok: false, error: `There is no workflow run "${runId}".` };
+      if (run.status !== "running") return { ok: true, content: `Workflow ${runId} had already ${run.status === "completed" ? "completed" : "ended"}.` };
+      run.stopRequested = true;
+      consume(run);
+      run.controller.abort();
+      await waitFor(run.done, STOP_WAIT_MS);
+      return { ok: true, content: `Stopped workflow ${runId} ("${run.meta.name}").` };
+    },
+    semaphore,
+  };
+}
+
+/** @param {Promise<unknown>} p @param {number} ms @param {AbortSignal} [signal] */
+function waitFor(p, ms, signal) {
+  return new Promise((resolve) => {
+    const t = setTimeout(done, ms);
+    const onAbort = () => done();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    p.then(done, done);
+    function done() {
+      clearTimeout(t);
+      signal?.removeEventListener("abort", onAbort);
+      resolve(undefined);
+    }
+  });
+}