@pi-unipi/unipi 3.0.0-alpha.2 → 3.0.0-alpha.21

package/packages/subagents/src/workflow-script.ts

@@ -1,737 +0,0 @@
-/**
- * @pi-unipi/subagents — workflowScript host runtime
- *
- * Ported from pi-subagents src/workflows/scripted-workflow.ts (host half).
- * Spawns the sandbox worker, routes RPC calls (run/all/steer/status/state) to
- * host callbacks, tracks children + trace, enforces the unawaited-launch
- * contract, and resolves with { value, emits, console, trace, children }.
- *
- * The launch callback is OURS: in-process AgentManager.spawn (foreground) —
- * Phase 3 swaps in the process-based runner for async workflows.
- */
-
-import { Worker } from "node:worker_threads";
-import { createRequire } from "node:module";
-import { readFileSync } from "node:fs";
-import { dirname, resolve as resolvePath } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const requireFromPackage = createRequire(import.meta.url);
-
-export interface WorkflowScriptTraceEntry {
-  operation: "run" | "steer" | "status";
-  key: string;
-  state: string;
-  durationMs?: number;
-  phase?: string;
-  label?: string;
-  agent?: string;
-  runId?: string;
-  error?: string;
-}
-
-export interface WorkflowScriptChildResult {
-  key: string;
-  ok: boolean;
-  output: string;
-  error?: string;
-  detached?: boolean;
-  runId?: string;
-  agent?: string;
-  artifactPaths?: string[];
-  [extra: string]: unknown;
-}
-
-export interface WorkflowSteerResult {
-  key: string;
-  state: "queued" | "delivered" | "missed" | "failed";
-  requestId?: string;
-  error?: string;
-}
-
-export interface WorkflowScriptResult {
-  value: unknown;
-  emits: unknown[];
-  console: Array<{ level: "log" | "info" | "warn" | "error"; text: string }>;
-  trace: WorkflowScriptTraceEntry[];
-  children: WorkflowScriptChildResult[];
-}
-
-export class WorkflowScriptError extends Error {
-  readonly partial: Omit<WorkflowScriptResult, "value">;
-
-  constructor(message: string, partial: Omit<WorkflowScriptResult, "value">) {
-    super(message);
-    this.name = "WorkflowScriptError";
-    this.partial = partial;
-  }
-}
-
-export interface RunWorkflowScriptOptions {
-  script: string;
-  timeoutMs?: number;
-  signal?: AbortSignal;
-  /** Spawn-budget admission hook (called before children start; may throw). */
-  admit?: (calls: Array<{ key: string; params: Record<string, unknown> }>) => void | Promise<void>;
-  /** OUR launch path: in-process foreground spawn (Phase 3: process runner). */
-  launch: (
-    key: string,
-    params: Record<string, unknown>,
-    signal: AbortSignal,
-    admission: { admitted: boolean },
-  ) => Promise<WorkflowScriptChildResult>;
-  status: (keyOrRunId: string, signal: AbortSignal) => Promise<WorkflowScriptChildResult>;
-  steer?: (
-    key: string,
-    message: string,
-    options: { mode?: string; index?: number; ackTimeoutMs?: number },
-    signal: AbortSignal,
-  ) => Promise<WorkflowSteerResult>;
-  state?: {
-    get: (key: string) => unknown | Promise<unknown>;
-    set: (key: string, value: unknown) => void | Promise<void>;
-  };
-  onTrace?: (trace: WorkflowScriptTraceEntry[]) => void;
-  onEmit?: (emits: unknown[]) => void;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return !!value && typeof value === "object" && !Array.isArray(value);
-}
-
-function isPlainJsonObject(value: unknown): value is Record<string, unknown> {
-  if (!isRecord(value)) return false;
-  const prototype = Object.getPrototypeOf(value);
-  return prototype === null || prototype === Object.prototype;
-}
-
-export function assertWorkflowJsonValue(value: unknown, path = "value", seen = new Set<object>()): void {
-  if (value === null || typeof value === "string" || typeof value === "boolean") return;
-  if (typeof value === "number") {
-    if (!Number.isFinite(value)) throw new Error(`${path} must contain only finite JSON numbers.`);
-    return;
-  }
-  if (typeof value !== "object") throw new Error(`${path} must be a JSON value; received ${typeof value}.`);
-  if (seen.has(value)) throw new Error(`${path} must not contain cycles.`);
-  seen.add(value);
-  if (Array.isArray(value)) {
-    for (let index = 0; index < value.length; index++) {
-      if (!Object.hasOwn(value, index)) throw new Error(`${path} must not contain sparse array entries.`);
-      assertWorkflowJsonValue(value[index], `${path}[${index}]`, seen);
-    }
-  } else {
-    const prototype = Object.getPrototypeOf(value);
-    if (prototype !== null && prototype !== Object.prototype) {
-      throw new Error(`${path} must contain only plain JSON objects.`);
-    }
-    if (Object.getOwnPropertySymbols(value).length > 0) {
-      throw new Error(`${path} must not contain symbol keys.`);
-    }
-    for (const [key, entry] of Object.entries(value)) {
-      assertWorkflowJsonValue(entry, `${path}.${key}`, seen);
-    }
-  }
-  seen.delete(value);
-}
-
-export function formatWorkflowJsonPreview(value: unknown, maxLength: number): string | undefined {
-  try {
-    assertWorkflowJsonValue(value);
-    const serialized = JSON.stringify(value);
-    return typeof serialized === "string" ? serialized.slice(0, maxLength) : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-export interface SimpleWorkflowRunPreview {
-  agent?: string;
-  task?: string;
-}
-
-/** Display-only preview for the exact simple `return runs.run(key, {...})` form. */
-export function previewSimpleWorkflowRun(script: string | undefined): SimpleWorkflowRunPreview | undefined {
-  const body = script
-    ?.match(/^\s*return\s+(?:await\s+)?runs\.run\s*\(\s*(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`[^`$\\]*`)\s*,\s*\{([\s\S]*)\}\s*\)\s*;?\s*$/)
-    ?.[1];
-  if (body === undefined) return undefined;
-  const readProperty = (name: "agent" | "task"): string | undefined => {
-    const match = body.match(
-      new RegExp(`(?:^|,)\\s*(?:${name}|["']${name}["'])\\s*:\\s*("(?:\\\\.|[^"\\\\])*"|'(?:\\\\.|[^'\\\\])*'|\u0060[^\u0060$\\\\]*\u0060)`),
-    );
-    if (!match?.[1]) return undefined;
-    const literal = match[1];
-    if (literal.startsWith('"')) {
-      try {
-        return JSON.parse(literal) as string;
-      } catch {
-        return undefined;
-      }
-    }
-    if (literal.slice(1, -1).includes("\\")) return undefined;
-    return literal.slice(1, -1);
-  };
-  const agent = readProperty("agent");
-  const task = readProperty("task");
-  return { ...(agent !== undefined ? { agent } : {}), ...(task !== undefined ? { task } : {}) };
-}
-
-function stableJson(value: unknown): string {
-  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
-  if (isRecord(value)) {
-    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
-  }
-  return JSON.stringify(value) ?? "undefined";
-}
-
-function omitUndefinedWorkflowValues(value: unknown, seen = new Set<object>()): unknown {
-  if (value === null || typeof value !== "object") return value;
-  if (seen.has(value)) return value;
-  seen.add(value);
-  const normalized = Array.isArray(value)
-    ? value.map((entry) => (entry === undefined ? null : omitUndefinedWorkflowValues(entry, seen)))
-    : isPlainJsonObject(value)
-      ? Object.fromEntries(
-          Object.entries(value).flatMap(([key, entry]) =>
-            entry === undefined ? [] : [[key, omitUndefinedWorkflowValues(entry, seen)]],
-          ),
-        )
-      : value;
-  seen.delete(value);
-  return normalized;
-}
-
-function omitNonJsonWorkflowResultMetadata(value: unknown): unknown {
-  const normalized = omitUndefinedWorkflowValues(value);
-  if (!isPlainJsonObject(normalized) || !Object.hasOwn(normalized, "results")) return normalized;
-  try {
-    assertWorkflowJsonValue(normalized.results, "runs.run result.results");
-    return normalized;
-  } catch {
-    const { results: _results, ...safeResult } = normalized;
-    return safeResult;
-  }
-}
-
-const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-
-function validateKey(value: unknown, owner = "runs.run"): string {
-  if (typeof value !== "string" || !KEY_PATTERN.test(value)) {
-    throw new Error(`${owner} key must be 1-128 characters using letters, numbers, '.', '_' or '-', and start with a letter or number.`);
-  }
-  return value;
-}
-
-function workflowStringMetadata(params: Record<string, unknown>): Pick<WorkflowScriptTraceEntry, "phase" | "label" | "agent"> {
-  return {
-    ...(typeof params.phase === "string" && params.phase.trim() ? { phase: params.phase.trim() } : {}),
-    ...(typeof params.label === "string" && params.label.trim() ? { label: params.label.trim() } : {}),
-    ...(typeof params.agent === "string" && params.agent.trim() ? { agent: params.agent.trim() } : {}),
-  };
-}
-
-/** Resolve acorn robustly (bare specifier, then package.json main). */
-function resolveWorkflowParserEntry(): string {
-  try {
-    return requireFromPackage.resolve("acorn");
-  } catch (primaryError) {
-    try {
-      const manifestPath = requireFromPackage.resolve("acorn/package.json");
-      const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as { main?: unknown };
-      const entry = typeof manifest.main === "string" && manifest.main ? manifest.main : "./dist/acorn.js";
-      return resolvePath(dirname(manifestPath), entry);
-    } catch {
-      throw primaryError;
-    }
-  }
-}
-
-/** Worker source: compiled .js in published installs, .ts under jiti/tsx (transpiled inline). */
-function loadWorkerSource(): string {
-  const base = resolvePath(dirname(fileURLToPath(import.meta.url)), "workflow-worker");
-  for (const candidate of [`${base}.js`, `${base}.ts`]) {
-    try {
-      return readFileSync(candidate, "utf8");
-    } catch {
-      // try next
-    }
-  }
-  throw new Error("workflow-worker source not found (expected workflow-worker.js or .ts)");
-}
-
-export async function runWorkflowScript(options: RunWorkflowScriptOptions): Promise<WorkflowScriptResult> {
-  if (!options.script.trim()) throw new Error("workflowScript must not be empty.");
-  if (options.timeoutMs !== undefined && (!Number.isInteger(options.timeoutMs) || options.timeoutMs < 1)) {
-    throw new Error("workflow script timeout must be a positive integer.");
-  }
-
-  let acornPath: string;
-  try {
-    acornPath = resolveWorkflowParserEntry();
-  } catch (error) {
-    throw new Error(
-      "Workflow parser dependency 'acorn' is unavailable from @pi-unipi/subagents. Reinstall dependencies before launching workflowScript.",
-      { cause: error },
-    );
-  }
-
-  const worker = new Worker(loadWorkerSource(), { eval: true, workerData: { acornPath } });
-  const emits: unknown[] = [];
-  const consoleEntries: WorkflowScriptResult["console"] = [];
-  const trace: WorkflowScriptTraceEntry[] = [];
-  const children = new Map<string, WorkflowScriptChildResult>();
-  const childOrder: string[] = [];
-  const launches = new Map<string, { fingerprint: string; promise: Promise<WorkflowScriptChildResult>; observed: boolean }>();
-  const steers = new Map<number, { key: string; promise: Promise<WorkflowSteerResult>; observed: boolean }>();
-  const stoppedLaunches = new Set<string>();
-  const batchAdmissions = new Map<string, Promise<void>>();
-  const childController = new AbortController();
-  let settled = false;
-  let finishing = false;
-
-  const partial = (): Omit<WorkflowScriptResult, "value"> => ({
-    emits,
-    console: consoleEntries,
-    trace,
-    children: childOrder.flatMap((key) => {
-      const child = children.get(key);
-      return child ? [child] : [];
-    }),
-  });
-
-  const traceChanged = () => {
-    try {
-      options.onTrace?.([...trace]);
-    } catch (error) {
-      console.error("Workflow onTrace callback failed:", error);
-    }
-  };
-
-  return await new Promise<WorkflowScriptResult>((resolve, reject) => {
-    const finish = (outcome: { value: unknown } | { error: Error }) => {
-      if (settled || finishing) return;
-      finishing = true;
-      childController.abort("error" in outcome ? outcome.error : new Error("Workflow script completed."));
-      void Promise.allSettled([...steers.values()].map(({ promise }) => promise)).then(() => {
-        if (settled) return;
-        settled = true;
-        if (timer) clearTimeout(timer);
-        options.signal?.removeEventListener("abort", onAbort);
-        void worker.terminate();
-        const unobservedKeys =
-          "value" in outcome ? [...launches].filter(([, launch]) => !launch.observed).map(([key]) => key) : [];
-        const completionError =
-          unobservedKeys.length > 0
-            ? new Error(
-                `workflowScript completed with unawaited runs.run launch(es): ${unobservedKeys.map((key) => `'${key}'`).join(", ")}. For ordinary parallel fanout use await runs.all([{key, agent, task}, ...]); do not read .output from unawaited launches.`,
-              )
-            : "value" in outcome
-              ? (() => {
-                  const unobservedSteers = [...steers.values()].filter((steer) => !steer.observed).map((steer) => steer.key);
-                  return unobservedSteers.length > 0
-                    ? new Error(`workflowScript completed with unawaited runs.steer call(s): ${unobservedSteers.map((key) => `'${key}'`).join(", ")}. Await or return each call.`)
-                    : undefined;
-                })()
-              : undefined;
-        if ("error" in outcome) reject(new WorkflowScriptError(outcome.error.message, partial()));
-        else if (completionError) reject(new WorkflowScriptError(completionError.message, partial()));
-        else resolve({ value: outcome.value, ...partial() });
-      });
-    };
-    const onAbort = () => {
-      const signalReason = options.signal?.reason;
-      const error =
-        signalReason instanceof Error
-          ? signalReason
-          : typeof signalReason === "string"
-            ? new Error(signalReason)
-            : new Error("Workflow script aborted.");
-      for (const key of launches.keys()) {
-        if (children.has(key)) continue;
-        stoppedLaunches.add(key);
-        const started = trace.findLast(
-          (entry) => entry.operation === "run" && entry.key === key && entry.state === "started",
-        );
-        trace.push({
-          operation: "run",
-          key,
-          state: "stopped",
-          ...(started?.agent ? { agent: started.agent } : {}),
-          ...(started?.phase ? { phase: started.phase } : {}),
-          ...(started?.label ? { label: started.label } : {}),
-          error: error.message,
-        });
-      }
-      traceChanged();
-      finish({ error });
-    };
-    const timer =
-      options.timeoutMs === undefined
-        ? undefined
-        : setTimeout(() => finish({ error: new Error(`Workflow script timed out after ${options.timeoutMs}ms.`) }), options.timeoutMs);
-    options.signal?.addEventListener("abort", onAbort, { once: true });
-    if (options.signal?.aborted) return onAbort();
-
-    worker.on("error", (error) =>
-      finish({ error: new Error(`Workflow worker failed: ${error instanceof Error ? error.message : String(error)}`) }),
-    );
-    worker.on("exit", (code) => {
-      if (!settled && code !== 0) finish({ error: new Error(`Workflow worker exited with code ${code}.`) });
-    });
-
-
-    worker.on("message", (msg: Record<string, unknown>) => {
-      if (settled) return;
-      if (msg.type === "emit") {
-        try {
-          assertWorkflowJsonValue(msg.value, "emit");
-        } catch (error) {
-          finish({ error: new Error(`Workflow emit could not be persisted: ${error instanceof Error ? error.message : String(error)}`) });
-          return;
-        }
-        emits.push(msg.value);
-        try {
-          options.onEmit?.([...emits]);
-        } catch (error) {
-          emits.pop();
-          finish({ error: new Error(`Workflow emit could not be persisted: ${error instanceof Error ? error.message : String(error)}`) });
-        }
-        return;
-      }
-      if (msg.type === "console") {
-        const level = msg.level;
-        if ((level === "log" || level === "info" || level === "warn" || level === "error") && typeof msg.text === "string") {
-          consoleEntries.push({ level, text: msg.text });
-        }
-        return;
-      }
-      if (msg.type === "complete") {
-        try {
-          assertWorkflowJsonValue(msg.value, "return");
-        } catch (error) {
-          return finish({ error: new Error(`Workflow return could not be persisted: ${error instanceof Error ? error.message : String(error)}`) });
-        }
-        return finish({ value: msg.value });
-      }
-      if (msg.type === "error") {
-        return finish({ error: new Error(typeof msg.error === "string" ? msg.error : "Workflow script failed.") });
-      }
-      if (msg.type === "callObserved" && typeof msg.callId === "number") {
-        if (msg.operation === "steer") {
-          const steer = steers.get(msg.callId);
-          if (steer) steer.observed = true;
-        }
-        // run/all observations are tracked via the launches map by key.
-        return;
-      }
-      if (msg.type !== "call" || typeof msg.callId !== "number" || typeof msg.method !== "string" || !isRecord(msg.args)) {
-        return;
-      }
-
-      const respond = (promise: Promise<unknown>, responsePath?: string) => {
-        void promise.then(
-          (value) => {
-            if (settled) return;
-            const normalized = responsePath ? omitNonJsonWorkflowResultMetadata(value) : omitUndefinedWorkflowValues(value);
-            if (!responsePath) {
-              worker.postMessage({ type: "response", callId: msg.callId, ok: true, value: normalized });
-              return;
-            }
-            try {
-              assertWorkflowJsonValue(normalized, responsePath);
-              worker.postMessage({ type: "response", callId: msg.callId, ok: true, value: normalized });
-            } catch (error) {
-              worker.postMessage({
-                type: "response",
-                callId: msg.callId,
-                ok: false,
-                error: `${responsePath} must contain only JSON data before it can be returned from workflowScript. Return a plain projection such as { runId, ok, output }. ${error instanceof Error ? error.message : String(error)}`,
-              });
-            }
-          },
-          (error: unknown) => {
-            if (!settled) {
-              worker.postMessage({
-                type: "response",
-                callId: msg.callId,
-                ok: false,
-                error: error instanceof Error ? error.message : String(error),
-              });
-            }
-          },
-        );
-      };
-
-      if (msg.method === "state.get" || msg.method === "state.set") {
-        if (!options.state) return respond(Promise.reject(new Error("Workflow state is unavailable without a mission.")));
-        let key: string;
-        try {
-          key = validateKey(msg.args.key, "state");
-        } catch (error) {
-          return respond(Promise.reject(error));
-        }
-        if (msg.method === "state.get") return respond(Promise.resolve().then(() => options.state!.get(key)));
-        const value = msg.args.value;
-        try {
-          assertWorkflowJsonValue(value, `state.set('${key}') value`);
-        } catch (error) {
-          return respond(Promise.reject(error));
-        }
-        return respond(Promise.resolve().then(() => options.state!.set(key, value)));
-      }
-
-      if (msg.method === "status") {
-        const keyOrRunId = msg.args.keyOrRunId;
-        if (typeof keyOrRunId !== "string" || !keyOrRunId.trim()) {
-          return respond(Promise.reject(new Error("runs.status(keyOrRunId) requires a non-empty string.")));
-        }
-        const known = children.get(keyOrRunId);
-        const target = known?.runId ?? keyOrRunId;
-        trace.push({ operation: "status", key: keyOrRunId, state: "started", ...(known?.runId ? { runId: known.runId } : {}) });
-        traceChanged();
-        if (settled || finishing) return;
-        respond(
-          options.status(target, childController.signal).then((result) => {
-            if (settled || finishing) return result;
-            trace.push({
-              operation: "status",
-              key: keyOrRunId,
-              state: result.ok ? "completed" : "failed",
-              ...(result.runId ? { runId: result.runId } : {}),
-              ...(!result.ok ? { error: result.output } : {}),
-            });
-            traceChanged();
-            if (!result.ok) throw new Error(`Status '${keyOrRunId}' failed: ${result.output}`);
-            return result;
-          }),
-        );
-        return;
-      }
-
-      if (msg.method === "steer") {
-        let key: string;
-        try {
-          key = validateKey(msg.args.key, "runs.steer");
-        } catch (error) {
-          return respond(Promise.reject(error));
-        }
-        const steerMessage = msg.args.message;
-        if (typeof steerMessage !== "string" || !steerMessage.trim()) {
-          return respond(Promise.reject(new Error(`runs.steer('${key}') requires a non-empty message.`)));
-        }
-        const steerOptions = isRecord(msg.args.options) ? (msg.args.options as { mode?: string; index?: number; ackTimeoutMs?: number }) : {};
-        const startedAt = Date.now();
-        trace.push({ operation: "steer", key, state: "started" });
-        traceChanged();
-        const promise = Promise.resolve()
-          .then(() => {
-            if (!launches.has(key)) throw new Error(`runs.steer('${key}') requires a prior runs.run/runs.all launch with that key.`);
-            if (!options.steer) throw new Error("Workflow steering is unavailable in this host.");
-            return options.steer(key, steerMessage.trim(), steerOptions, childController.signal);
-          })
-          .then(
-            (receipt) => {
-              trace.push({ operation: "steer", key, state: receipt.state, durationMs: Date.now() - startedAt, ...(receipt.error ? { error: receipt.error } : {}) });
-              traceChanged();
-              return receipt;
-            },
-            (error: unknown) => {
-              const text = error instanceof Error ? error.message : String(error);
-              trace.push({ operation: "steer", key, state: "failed", durationMs: Date.now() - startedAt, error: text });
-              traceChanged();
-              throw error;
-            },
-          );
-        steers.set(msg.callId, { key, promise, observed: false });
-        respond(promise);
-        return;
-      }
-
-      if (msg.method === "all") {
-        // runs.all(...) is itself the observation: every child is awaited by the batch.
-        // Batch launch: runs.all([...]) — admits the whole group atomically.
-        const calls = Array.isArray(msg.args.calls) ? msg.args.calls : [];
-        const valid = calls.filter(
-          (call): call is { key: string; params: Record<string, unknown> } =>
-            isRecord(call) && typeof call.key === "string" && isRecord(call.params),
-        );
-        const admission = Promise.resolve().then(() => {
-          if (settled || finishing) return;
-          return options.admit?.(valid);
-        }).catch((error: unknown) => {
-          // Admission failures (e.g. fanout budget) reject every child in the
-          // batch; runs.all collects them as ordinary failures (reference
-          // semantics: no partial starts, siblings report the rejection).
-          const text = error instanceof Error ? error.message : String(error);
-          for (const { key } of valid) {
-            const failure: WorkflowScriptChildResult = { key, ok: false, output: text, error: text, artifactPaths: [] };
-            children.set(key, failure);
-            if (!childOrder.includes(key)) childOrder.push(key);
-          }
-          throw error;
-        });
-        const promises = valid.map(({ key, params }) =>
-          admission.then(async () => {
-            if (settled || finishing || stoppedLaunches.has(key)) {
-              const reason = childController.signal.reason;
-              const text = reason instanceof Error ? reason.message : typeof reason === "string" ? reason : "Workflow script aborted.";
-              return { key, ok: false, output: text, error: text, artifactPaths: [] };
-            }
-            const startedAt = Date.now();
-            return options.launch(key, { ...params, async: params.async ?? false }, childController.signal, { admitted: true }).then(
-              (result) => {
-                const normalized = !result.ok && !result.error ? { ...result, error: result.output } : result;
-                children.set(key, normalized);
-                childOrder.push(key);
-                trace.push({
-                  operation: "run",
-                  key,
-                  state: normalized.ok ? "completed" : "failed",
-                  durationMs: Date.now() - startedAt,
-                  ...workflowStringMetadata(params),
-                  ...(normalized.agent ? { agent: normalized.agent } : {}),
-                  ...(normalized.runId ? { runId: normalized.runId } : {}),
-                  ...(!normalized.ok ? { error: normalized.error ?? normalized.output } : {}),
-                });
-                traceChanged();
-                return normalized;
-              },
-              (error: unknown) => {
-                const text = error instanceof Error ? error.message : String(error);
-                const failure: WorkflowScriptChildResult = { key, ok: false, output: text, error: text, artifactPaths: [] };
-                children.set(key, failure);
-                childOrder.push(key);
-                trace.push({ operation: "run", key, state: "failed", durationMs: Date.now() - startedAt, ...workflowStringMetadata(params), error: text });
-                traceChanged();
-                return failure;
-              },
-            );
-          }, (error: unknown) => {
-            // Admission rejection already recorded the failure per child; map
-            // this arm to the same failure so Promise.all collects it.
-            const text = error instanceof Error ? error.message : String(error);
-            return { key, ok: false, output: text, error: text, artifactPaths: [] } satisfies WorkflowScriptChildResult;
-          }),
-        );
-        // Mark all keys observed (runs.all is itself the observation).
-        for (const { key } of valid) {
-          const existing = launches.get(key);
-          if (existing) existing.observed = true;
-        }
-        const batchPromise = Promise.all(promises).then((results) => {
-          for (const result of results) {
-            const entry = launches.get(result.key);
-            if (entry) entry.observed = true;
-          }
-          return results;
-        });
-        for (const { key, params } of valid) {
-          const fingerprint = stableJson(params);
-          launches.set(key, { fingerprint, promise: batchPromise.then((rs) => rs.find((r) => r.key === key)!) , observed: true });
-        }
-        respond(batchPromise, "runs.all(...) results");
-        return;
-      }
-
-      if (msg.method !== "run") return respond(Promise.reject(new Error(`Unknown runs API method '${msg.method}'.`)));
-
-      let key: string;
-      try {
-        key = validateKey(msg.args.key);
-      } catch (error) {
-        return respond(Promise.reject(error));
-      }
-      const params = msg.args.params;
-      if (!isRecord(params)) return respond(Promise.reject(new Error(`runs.run('${key}', params) requires a params object.`)));
-      if (params.action !== undefined) return respond(Promise.reject(new Error(`runs.run('${key}') accepts execution params only; management action is not allowed.`)));
-      if (params.workflowScript !== undefined) return respond(Promise.reject(new Error(`runs.run('${key}') cannot start a nested workflow script.`)));
-      if (params.tasks !== undefined || params.chain !== undefined || params.parallel !== undefined || params.concurrency !== undefined) {
-        return respond(Promise.reject(new Error(`runs.run('${key}') accepts one child via { agent, task }; use runs.all(...) and JavaScript control flow for orchestration.`)));
-      }
-      if (params.resume !== undefined && params.agent !== undefined) {
-        return respond(Promise.reject(new Error(`runs.run('${key}') resume and agent are mutually exclusive.`)));
-      }
-      if (typeof params.resume === "string" && !params.resume.trim()) {
-        return respond(Promise.reject(new Error(`runs.run('${key}') resume must be a non-empty retained run id.`)));
-      }
-      if (params.resume !== undefined && (typeof params.task !== "string" || !params.task.trim())) {
-        return respond(Promise.reject(new Error(`runs.run('${key}') resume requires a non-empty task follow-up.`)));
-      }
-
-      const fingerprint = stableJson(params);
-      const existing = launches.get(key);
-      if (existing) {
-        if (existing.fingerprint !== fingerprint) {
-          return respond(Promise.reject(new Error(`Duplicate workflow key '${key}' used with incompatible launch params.`)));
-        }
-        existing.observed = true;
-        trace.push({ operation: "run", key, state: "reused", ...workflowStringMetadata(params) });
-        traceChanged();
-        return respond(
-          existing.promise.then((result) => {
-            if (result.ok) return result;
-            throw new Error(`Run '${key}' failed: ${result.error ?? result.output}`);
-          }),
-          `runs.run('${key}') result`,
-        );
-      }
-
-      const startedAt = Date.now();
-      const admission = Promise.resolve().then(() => {
-        if (settled || finishing) return;
-        return options.admit?.([{ key, params }]);
-      });
-      const promise = admission
-        .then(async () => {
-          if (settled || finishing || stoppedLaunches.has(key)) {
-            const reason = childController.signal.reason;
-            const text = reason instanceof Error ? reason.message : typeof reason === "string" ? reason : "Workflow script aborted.";
-            return { key, ok: false, output: text, error: text, artifactPaths: [] };
-          }
-          return options.launch(key, { ...params, async: params.async ?? false }, childController.signal, { admitted: true });
-        })
-        .then(
-          (result) => {
-            const normalized = !result.ok && !result.error ? { ...result, error: result.output } : result;
-            if (stoppedLaunches.has(key)) return normalized;
-            children.set(key, normalized);
-            const state = normalized.ok ? "completed" : "failed";
-            trace.push({
-              operation: "run",
-              key,
-              state,
-              durationMs: Date.now() - startedAt,
-              ...workflowStringMetadata(params),
-              ...(normalized.agent ? { agent: normalized.agent } : {}),
-              ...(normalized.runId ? { runId: normalized.runId } : {}),
-              ...(!normalized.ok ? { error: normalized.error ?? normalized.output } : {}),
-            });
-            traceChanged();
-            return normalized;
-          },
-          (error: unknown) => {
-            const text = error instanceof Error ? error.message : String(error);
-            const failure: WorkflowScriptChildResult = { key, ok: false, output: text, error: text, artifactPaths: [] };
-            if (stoppedLaunches.has(key)) return failure;
-            children.set(key, failure);
-            trace.push({ operation: "run", key, state: "failed", durationMs: Date.now() - startedAt, ...workflowStringMetadata(params), error: text });
-            traceChanged();
-            return failure;
-          },
-        );
-      launches.set(key, { fingerprint, promise, observed: true });
-      if (!childOrder.includes(key)) childOrder.push(key);
-      trace.push({ operation: "run", key, state: "started", ...workflowStringMetadata(params) });
-      traceChanged();
-      respond(
-        promise.then((result) => {
-          if (result.ok) return result;
-          throw new Error(`Run '${key}' failed: ${result.error ?? result.output}`);
-        }),
-        `runs.run('${key}') result`,
-      );
-    });
-
-    worker.postMessage({ type: "start", script: options.script, stateEnabled: options.state !== undefined });
-  });
-}