@op1/threads 0.1.8 → 0.2.0

package/src/workflow-rpc.ts

@@ -0,0 +1,39 @@
+import { Rpc } from "@opencode/plugin/rpc";
+import { z } from "zod";
+import { Json, WorkflowRun, WorkflowSummary } from "./workflow-types";
+
+export const WorkflowControl = z.object({
+  runID: z.string().min(1),
+  action: z.enum(["pause", "resume", "stop"]),
+  checkpointKey: z.string().optional(),
+  response: Json.optional(),
+}).strict();
+
+export const WorkflowsRpc = Rpc.define({
+  id: "workflows",
+  methods: {
+    snapshot: {
+      input: z.object({ ownerID: z.string() }).strict(),
+      output: z.object({ runs: z.array(WorkflowSummary) }),
+      errors: {},
+    },
+    inspect: {
+      input: z.object({ ownerID: z.string(), runID: z.string() }).strict(),
+      output: WorkflowRun,
+      errors: {},
+    },
+    control: {
+      input: WorkflowControl.extend({ ownerID: z.string() }).strict(),
+      output: WorkflowRun,
+      errors: {},
+    },
+    save: {
+      input: z.object({ ownerID: z.string(), runID: z.string(), name: z.string(), scope: z.enum(["project", "user"]) }).strict(),
+      output: z.object({ path: z.string() }),
+      errors: {},
+    },
+  },
+  events: {
+    updated: { schema: z.object({ ownerID: z.string(), runID: z.string() }) },
+  },
+});

package/src/workflow-runtime-interpreter.ts

@@ -0,0 +1,368 @@
+import { CodeMode, Tool, toolError } from "@opencode/codemode";
+import { parse } from "acorn";
+import { Effect } from "effect";
+
+export type WorkflowHost = {
+  agent(input: unknown): Promise<unknown>;
+  phase(title: string): Promise<void>;
+  log(message: string): Promise<void>;
+  checkpoint(input: unknown): Promise<unknown>;
+  workflow(input: { name: string; args?: unknown }): Promise<unknown>;
+};
+
+export type WorkflowMeta = {
+  name: string;
+  description: string;
+  phases?: { title: string }[];
+};
+
+type Node = { type: string; start: number; end: number; [key: string]: unknown };
+
+const injected = new Set([
+  "args",
+  "agent",
+  "phase",
+  "log",
+  "checkpoint",
+  "workflow",
+  "parallel",
+  "pipeline",
+  "retry",
+  "gate",
+  "loopUntilDry",
+]);
+
+const safeGlobals = new Set([
+  "undefined", "NaN", "Infinity", "Object", "Array", "Math", "JSON", "Promise",
+  "Symbol", "Number", "String", "Boolean", "parseInt", "parseFloat", "isFinite",
+  "isNaN", "RegExp", "Map", "Set", "URL", "URLSearchParams", "Headers", "Uint8Array",
+  "TextEncoder", "TextDecoder", "encodeURI", "encodeURIComponent", "decodeURI",
+  "decodeURIComponent", "atob", "btoa", "Error", "TypeError", "RangeError",
+  "SyntaxError", "ReferenceError", "AggregateError",
+]);
+
+const deterministicMathProperties = new Set([
+  "PI", "E", "LN2", "LN10", "LOG2E", "LOG10E", "SQRT2", "SQRT1_2",
+  "max", "min", "hypot", "abs", "acos", "acosh", "asin", "asinh", "atan",
+  "atan2", "atanh", "floor", "ceil", "round", "trunc", "sign", "sqrt", "cbrt",
+  "pow", "cos", "cosh", "sin", "sinh", "tan", "tanh", "log", "log2", "log10",
+  "log1p", "exp", "expm1", "f16round", "fround", "clz32", "imul", "sumPrecise",
+]);
+
+const prototypeEscapeProperties = new Set([
+  "constructor", "prototype", "__proto__", "getPrototypeOf", "setPrototypeOf",
+]);
+
+const forbiddenGlobals = new Set([
+  "Date", "performance", "crypto", "process", "fetch", "require", "globalThis",
+  "window", "self", "eval", "Function", "WebAssembly", "tools", "search", "console",
+]);
+
+function ast(source: string, sourceType: "script" | "module"): Node {
+  return parse(source, {
+    ecmaVersion: "latest",
+    sourceType,
+    allowReturnOutsideFunction: true,
+    allowAwaitOutsideFunction: true,
+  }) as unknown as Node;
+}
+
+function children(node: Node): Node[] {
+  const result: Node[] = [];
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "start" || key === "end" || key === "loc") continue;
+    if (value && typeof value === "object" && "type" in value)
+      result.push(value as Node);
+    else if (Array.isArray(value))
+      for (const item of value)
+        if (item && typeof item === "object" && "type" in item) result.push(item as Node);
+  }
+  return result;
+}
+
+function literal(node: Node): unknown {
+  if (node.type === "Literal") return node.value;
+  if (node.type === "UnaryExpression" && (node.operator === "-" || node.operator === "+")) {
+    const value = literal(node.argument as Node);
+    if (typeof value === "number") return node.operator === "-" ? -value : value;
+  }
+  if (node.type === "ArrayExpression")
+    return (node.elements as (Node | null)[]).map((item) => {
+      if (!item) throw new Error("Workflow metadata cannot contain array holes");
+      return literal(item);
+    });
+  if (node.type === "ObjectExpression") {
+    const value: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+    for (const property of node.properties as Node[]) {
+      if (property.type !== "Property" || property.computed || property.kind !== "init" || property.method || property.shorthand)
+        throw new Error("Workflow metadata must be a literal object");
+      const keyNode = property.key as Node;
+      const key = keyNode.type === "Identifier" ? keyNode.name : literal(keyNode);
+      if (typeof key !== "string") throw new Error("Workflow metadata keys must be strings");
+      if (Object.hasOwn(value, key)) throw new Error(`Duplicate workflow metadata key: ${key}`);
+      value[key] = literal(property.value as Node);
+    }
+    return value;
+  }
+  throw new Error("Workflow metadata must contain only literal values");
+}
+
+function validateMeta(value: unknown): WorkflowMeta {
+  if (!isRecord(value) || typeof value.name !== "string" || !value.name.trim() ||
+      typeof value.description !== "string" || !value.description.trim())
+    throw new Error("Workflow metadata requires non-empty name and description strings");
+  const keys = Object.keys(value);
+  if (keys.some((key) => !["name", "description", "phases"].includes(key)))
+    throw new Error("Workflow metadata contains an unknown field");
+  if (value.phases !== undefined && (!Array.isArray(value.phases) || value.phases.some((phase) =>
+    !isRecord(phase) || Object.keys(phase).length !== 1 || typeof phase.title !== "string" || !phase.title.trim())))
+    throw new Error("Workflow metadata phases must contain only non-empty titles");
+  return {
+    name: value.name,
+    description: value.description,
+    ...(value.phases === undefined ? {} : { phases: value.phases as { title: string }[] }),
+  };
+}
+
+export function parseWorkflow(script: string): { meta: WorkflowMeta; body: string } {
+  const program = ast(script, "module");
+  const statements = program.body as Node[];
+  const first = statements[0];
+  if (!first || first.type !== "ExportNamedDeclaration")
+    throw new Error("The first statement must be `export const meta =` with a literal object");
+  const declaration = first.declaration as Node | null;
+  const declarations = declaration?.declarations as Node[] | undefined;
+  const item = declarations?.[0];
+  if (declaration?.type !== "VariableDeclaration" || declaration.kind !== "const" || declarations?.length !== 1 ||
+      item?.id && ((item.id as Node).type !== "Identifier" || (item.id as Node).name !== "meta") ||
+      (item?.init as Node | undefined)?.type !== "ObjectExpression")
+    throw new Error("The first statement must be `export const meta =` with a literal object");
+  const meta = validateMeta(literal((item as Node).init as Node));
+  return { meta, body: script.slice(first.end).trim() };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function patternNames(node: Node | null | undefined, names: Set<string>): void {
+  if (!node) return;
+  if (node.type === "Identifier") names.add(node.name as string);
+  else if (node.type === "RestElement") patternNames(node.argument as Node, names);
+  else if (node.type === "AssignmentPattern") patternNames(node.left as Node, names);
+  else if (node.type === "ArrayPattern") for (const item of node.elements as (Node | null)[]) patternNames(item, names);
+  else if (node.type === "ObjectPattern") for (const property of node.properties as Node[])
+    patternNames((property.type === "RestElement" ? property.argument : property.value) as Node, names);
+}
+
+function isReference(node: Node, parent?: Node): boolean {
+  if (!parent) return true;
+  if ((parent.type === "VariableDeclarator" && parent.id === node) ||
+      ((parent.type === "FunctionDeclaration" || parent.type === "FunctionExpression" || parent.type === "ArrowFunctionExpression") &&
+       (parent.id === node || (parent.params as Node[]).includes(node))) ||
+      ((parent.type === "Property" || parent.type === "MethodDefinition") && parent.key === node && !parent.computed &&
+       !(parent.type === "Property" && parent.shorthand && parent.value === node)) ||
+      (parent.type === "MemberExpression" && parent.property === node && !parent.computed) ||
+      (parent.type === "LabeledStatement" || parent.type === "BreakStatement" || parent.type === "ContinueStatement") ||
+      (parent.type === "CatchClause" && parent.param === node)) return false;
+  return true;
+}
+
+function validateBody(body: string): void {
+  const program = ast(body, "script");
+  const declared = new Set<string>();
+  const nodes: { node: Node; parent?: Node }[] = [];
+  const visit = (node: Node, parent?: Node) => {
+    nodes.push({ node, parent });
+    if (node.type === "VariableDeclarator") patternNames(node.id as Node, declared);
+    if ((node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ClassDeclaration" || node.type === "ClassExpression") && node.id)
+      patternNames(node.id as Node, declared);
+    if (node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression")
+      for (const param of node.params as Node[]) patternNames(param, declared);
+    if (node.type === "CatchClause") patternNames(node.param as Node | null, declared);
+    for (const child of children(node)) visit(child, node);
+  };
+  visit(program);
+  for (const name of declared)
+    if (injected.has(name) || name === "tools" || name === "search") throw new Error(`Workflow cannot shadow injected binding ${name}`);
+
+  for (const { node, parent } of nodes) {
+    if (node.type === "ImportDeclaration" || node.type === "ImportExpression" || node.type.startsWith("Export"))
+      throw new Error("Imports and exports are not supported in workflow bodies");
+    if (node.type === "Identifier" && isReference(node, parent)) {
+      const name = node.name as string;
+      if (forbiddenGlobals.has(name)) throw new Error(`Workflow cannot access ${name}`);
+      if (name === "Math") {
+        if (parent?.type !== "MemberExpression" || parent.object !== node)
+          throw new Error("Workflow may only use Math through a deterministic static property");
+        const property = parent.property as Node;
+        const propertyName = parent.computed ? (property.type === "Literal" ? property.value : undefined) : property.name;
+        if (typeof propertyName !== "string" || !deterministicMathProperties.has(propertyName))
+          throw new Error(`Workflow cannot access nondeterministic or unknown Math property ${String(propertyName)}`);
+      }
+      if (!declared.has(name) && !safeGlobals.has(name) && !injected.has(name)) throw new Error(`Unknown workflow global: ${name}`);
+    }
+    if (node.type === "MemberExpression") {
+      const property = node.property as Node;
+      const name = node.computed ? (property.type === "Literal" ? property.value : undefined) : property.name;
+      if (typeof name === "string" && prototypeEscapeProperties.has(name))
+        throw new Error(`Workflow cannot access prototype escape property ${name}`);
+    }
+  }
+}
+
+const anySchema = {};
+const objectSchema = (properties: Record<string, unknown>, required: string[] = []) => ({
+  type: "object", properties, required, additionalProperties: true,
+});
+
+const prelude = `
+const args = await tools.runtime.args({});
+const agent = async (prompt, options = {}) => tools.runtime.agent({ ...options, prompt });
+const phase = async (title) => tools.runtime.phase({ title });
+const log = async (message) => tools.runtime.log({ message });
+const checkpoint = async (prompt, options = {}) => tools.runtime.checkpoint({ ...options, prompt });
+const workflow = async (name, workflowArgs) => workflowArgs === undefined
+  ? tools.runtime.workflow({ name })
+  : tools.runtime.workflow({ name, args: workflowArgs });
+const MAX_HELPER_ITERATIONS = 1000;
+const positiveInteger = (value, name) => {
+  if (!Number.isSafeInteger(value) || value < 1 || value > MAX_HELPER_ITERATIONS)
+    throw new RangeError(name + " must be a safe positive integer no greater than " + MAX_HELPER_ITERATIONS);
+  return value;
+};
+const parallel = async (thunks) => Promise.all(thunks.map((thunk) => thunk()));
+const pipeline = async (items, ...stages) => Promise.all(items.map(async (item) => {
+  let value = item;
+  for (const stage of stages) value = await stage(value);
+  return value;
+}));
+const retry = async (thunk, options = {}) => {
+  const attempts = positiveInteger(options.attempts === undefined ? 3 : options.attempts, "attempts");
+  let lastError;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try { return await thunk(attempt); } catch (error) { lastError = error; }
+  }
+  throw lastError;
+};
+const gate = async (thunk, validator, options = {}) => retry(async (attempt) => {
+  const value = await thunk(attempt);
+  const verdict = await validator(value, attempt);
+  const accepted = verdict === true || (verdict !== null && typeof verdict === "object" && verdict.ok === true);
+  if (verdict !== true && verdict !== false && (verdict === null || typeof verdict !== "object" || typeof verdict.ok !== "boolean"))
+    throw new TypeError("Workflow gate validator must return a boolean or { ok, feedback? }");
+  if (!accepted) {
+    const feedback = verdict !== null && typeof verdict === "object" && typeof verdict.feedback === "string" ? ": " + verdict.feedback : "";
+    throw new Error("Workflow gate rejected the result" + feedback);
+  }
+  return value;
+}, options);
+const loopUntilDry = async ({ round, key, consecutiveEmpty = 2, maxRounds = 10 }) => {
+  positiveInteger(consecutiveEmpty, "consecutiveEmpty");
+  positiveInteger(maxRounds, "maxRounds");
+  if (typeof round !== "function") throw new TypeError("loopUntilDry round must be a function");
+  if (typeof key !== "function" && typeof key !== "string") throw new TypeError("loopUntilDry key must be a function or property name");
+  const seen = new Set();
+  const values = [];
+  let empty = 0;
+  for (let index = 1; index <= maxRounds && empty < consecutiveEmpty; index++) {
+    const batch = await round(index);
+    if (!Array.isArray(batch)) throw new TypeError("loopUntilDry round must return an array");
+    let added = 0;
+    for (const item of batch) {
+      const identity = typeof key === "function" ? await key(item) : item[key];
+      if (!seen.has(identity)) { seen.add(identity); values.push(item); added++; }
+    }
+    empty = added === 0 ? empty + 1 : 0;
+  }
+  return values;
+};
+`;
+
+function positiveOption(value: number | undefined, name: string): number | undefined {
+  if (value !== undefined && (!Number.isSafeInteger(value) || value < 1)) throw new RangeError(`${name} must be a positive integer`);
+  return value;
+}
+
+export async function executeWorkflowInterpreter(input: {
+  script: string;
+  args: unknown;
+  signal: AbortSignal;
+  host: WorkflowHost;
+  maxCalls?: number;
+  timeoutMs?: number;
+}): Promise<unknown> {
+  const { body } = parseWorkflow(input.script);
+  validateBody(body);
+  const maxCalls = positiveOption(input.maxCalls, "maxCalls");
+  const timeoutMs = positiveOption(input.timeoutMs, "timeoutMs");
+  if (input.signal.aborted) throw input.signal.reason ?? new DOMException("Aborted", "AbortError");
+  let calls = 0;
+  const pending = new Set<Promise<void>>();
+  const safeMessage = (error: unknown) => error instanceof Error ? error.message : String(error);
+  const effect = <T>(operation: () => Promise<T>) => Effect.flatMap(
+    Effect.promise(() => {
+      const settled = operation().then(
+      (value) => ({ ok: true as const, value }),
+      (error) => ({ ok: false as const, error }),
+      );
+      const completion = settled.then(() => {});
+      pending.add(completion);
+      void completion.then(() => pending.delete(completion));
+      return settled;
+    }),
+    (settled) => settled.ok ? Effect.succeed(settled.value) : Effect.fail(toolError(safeMessage(settled.error))),
+  );
+  const call = <T>(operation: () => Promise<T>) => effect(async () => {
+      calls++;
+      if (maxCalls !== undefined && calls > maxCalls) throw new Error(`Workflow call limit exceeded (${maxCalls})`);
+      return operation();
+  });
+  const tool = (description: string, schema: object, execute: (value: unknown) => Promise<unknown>, counted = true) =>
+    Tool.make({
+      description,
+      input: schema,
+      output: anySchema,
+      execute: (value) => counted ? call(() => execute(value)) : effect(() => execute(value)),
+    });
+  const runtime = CodeMode.make({
+    limits: { timeoutMs, maxOutputBytes: 1024 * 1024 },
+    tools: { runtime: {
+      args: tool("Return the workflow arguments", objectSchema({}), () => Promise.resolve(input.args), false),
+      agent: tool("Run an agent", objectSchema({ prompt: { type: "string" } }, ["prompt"]), async (value) => {
+        if (!isRecord(value) || typeof value.prompt !== "string") throw new TypeError("agent prompt must be a string");
+        return input.host.agent(value);
+      }),
+      phase: tool("Enter a workflow phase", objectSchema({ title: { type: "string" } }, ["title"]), async (value) => {
+        if (!isRecord(value) || typeof value.title !== "string") throw new TypeError("phase title must be a string");
+        await input.host.phase(value.title); return null;
+      }),
+      log: tool("Write a workflow log message", objectSchema({ message: { type: "string" } }, ["message"]), async (value) => {
+        if (!isRecord(value) || typeof value.message !== "string") throw new TypeError("log message must be a string");
+        await input.host.log(value.message); return null;
+      }),
+      checkpoint: tool("Request a checkpoint", objectSchema({ prompt: { type: "string" }, key: { type: "string" } }, ["prompt", "key"]), async (value) => {
+        if (!isRecord(value) || typeof value.prompt !== "string" || typeof value.key !== "string" || !value.key)
+          throw new TypeError("checkpoint requires string prompt and key");
+        return input.host.checkpoint(value);
+      }),
+      workflow: tool("Run a named workflow", objectSchema({ name: { type: "string" }, args: {} }, ["name"]), async (value) => {
+        if (!isRecord(value) || typeof value.name !== "string" || !value.name) throw new TypeError("workflow name must be a non-empty string");
+        return input.host.workflow({ name: value.name, ...(Object.hasOwn(value, "args") ? { args: value.args } : {}) });
+      }),
+    } },
+  });
+  let result: CodeMode.Result;
+  try {
+    result = await Effect.runPromise(runtime.execute(`${prelude}\n${body}`), { signal: input.signal });
+  } catch (error) {
+    throw error;
+  }
+  if (!result.ok) throw new Error(`${result.error.kind}: ${result.error.message}`);
+  if (pending.size > 0) throw new Error("Workflow returned with unawaited host operations; await every agent and helper call");
+  if (result.truncated || result.warnings?.some((warning) => warning.kind === "Truncated" || warning.kind === "TimeoutExceeded"))
+    throw new Error("Workflow execution was truncated or timed out");
+  const failedBackgroundWork = result.warnings?.find((warning) => warning.kind === "ToolFailure" || warning.kind === "ExecutionFailure");
+  if (failedBackgroundWork) throw new Error(`${failedBackgroundWork.kind}: ${failedBackgroundWork.message}`);
+  return result.value;
+}

package/src/workflow-runtime-protocol.ts

@@ -0,0 +1,36 @@
+export const WORKFLOW_MESSAGE_LIMIT_BYTES = 1024 * 1024;
+export const WORKFLOW_DIAGNOSTIC_LIMIT = 8_192;
+
+export type HostMethod = "agent" | "phase" | "log" | "checkpoint" | "workflow";
+
+export type ParentToWorker =
+  | { type: "start"; script: string; args: unknown; maxCalls?: number; timeoutMs?: number }
+  | { type: "hostResult"; id: number; ok: true; value: unknown }
+  | { type: "hostResult"; id: number; ok: false; error: string };
+
+export type WorkerToParent =
+  | { type: "hostCall"; id: number; method: HostMethod; input: unknown }
+  | { type: "result"; ok: true; value: unknown }
+  | { type: "result"; ok: false; error: string };
+
+export function boundedDiagnostic(value: unknown): string {
+  const message = value instanceof Error ? value.message : String(value);
+  if (Buffer.byteLength(message) <= WORKFLOW_DIAGNOSTIC_LIMIT) return message;
+  const suffix = "… [truncated]";
+  const prefixBytes = WORKFLOW_DIAGNOSTIC_LIMIT - Buffer.byteLength(suffix);
+  let prefix = Buffer.from(message).subarray(0, prefixBytes).toString("utf8");
+  while (Buffer.byteLength(prefix + suffix) > WORKFLOW_DIAGNOSTIC_LIMIT) prefix = prefix.slice(0, -1);
+  return prefix + suffix;
+}
+
+export function assertBoundedMessage(value: unknown, label: string): void {
+  let encoded: string;
+  try {
+    encoded = JSON.stringify(value);
+  } catch {
+    throw new Error(`${label} must be JSON serializable`);
+  }
+  if (encoded === undefined) encoded = "null";
+  if (Buffer.byteLength(encoded) > WORKFLOW_MESSAGE_LIMIT_BYTES)
+    throw new Error(`${label} exceeds ${WORKFLOW_MESSAGE_LIMIT_BYTES} bytes`);
+}

package/src/workflow-runtime-worker.ts

@@ -0,0 +1,64 @@
+import { executeWorkflowInterpreter, type WorkflowHost } from "./workflow-runtime-interpreter";
+import { assertBoundedMessage, boundedDiagnostic, type HostMethod, type ParentToWorker, type WorkerToParent } from "./workflow-runtime-protocol";
+
+declare const self: {
+  onmessage: ((event: MessageEvent<ParentToWorker>) => void) | null;
+  postMessage(message: WorkerToParent): void;
+};
+
+const controller = new AbortController();
+const pending = new Map<number, { resolve(value: unknown): void; reject(error: unknown): void }>();
+let nextID = 1;
+let started = false;
+
+function send(message: WorkerToParent): void {
+  self.postMessage(message);
+}
+
+function hostCall(method: HostMethod, input: unknown): Promise<unknown> {
+  assertBoundedMessage(input, `Workflow ${method} request`);
+  const id = nextID++;
+  return new Promise((resolve, reject) => {
+    pending.set(id, { resolve, reject });
+    send({ type: "hostCall", id, method, input });
+  });
+}
+
+const host: WorkflowHost = {
+  agent: (input) => hostCall("agent", input),
+  phase: async (input) => { await hostCall("phase", input); },
+  log: async (input) => { await hostCall("log", input); },
+  checkpoint: (input) => hostCall("checkpoint", input),
+  workflow: (input) => hostCall("workflow", input),
+};
+
+self.onmessage = (event) => {
+  const message = event.data;
+  if (message.type === "hostResult") {
+    const operation = pending.get(message.id);
+    if (!operation) return;
+    pending.delete(message.id);
+    if (message.ok) operation.resolve(message.value);
+    else operation.reject(new Error(message.error));
+    return;
+  }
+  if (message.type !== "start" || started) return;
+  started = true;
+  void (async () => {
+    try {
+      assertBoundedMessage(message.args, "Workflow arguments");
+      const value = await executeWorkflowInterpreter({
+        script: message.script,
+        args: message.args,
+        signal: controller.signal,
+        host,
+        maxCalls: message.maxCalls,
+        timeoutMs: message.timeoutMs,
+      });
+      assertBoundedMessage(value, "Workflow result");
+      send({ type: "result", ok: true, value });
+    } catch (error) {
+      send({ type: "result", ok: false, error: boundedDiagnostic(error) });
+    }
+  })();
+};

package/src/workflow-runtime.ts

@@ -0,0 +1,144 @@
+export { parseWorkflow } from "./workflow-runtime-interpreter";
+export type { WorkflowMeta } from "./workflow-runtime-interpreter";
+
+import {
+  assertBoundedMessage,
+  boundedDiagnostic,
+  type HostMethod,
+  type ParentToWorker,
+  type WorkerToParent,
+} from "./workflow-runtime-protocol";
+
+export type WorkflowHost = {
+  agent(input: unknown, signal?: AbortSignal): Promise<unknown>;
+  phase(title: string, signal?: AbortSignal): Promise<void>;
+  log(message: string, signal?: AbortSignal): Promise<void>;
+  checkpoint(input: unknown, signal?: AbortSignal): Promise<unknown>;
+  workflow(input: { name: string; args?: unknown }, signal?: AbortSignal): Promise<unknown>;
+};
+
+type ExecuteInput = {
+  script: string;
+  args: unknown;
+  signal: AbortSignal;
+  host: WorkflowHost;
+  maxCalls?: number;
+  timeoutMs?: number;
+};
+
+const MAX_RUNTIME_WORKERS = 64;
+const HOST_DRAIN_GRACE_MS = 100;
+let liveWorkers = 0;
+
+function positiveOption(value: number | undefined, name: string): number | undefined {
+  if (value !== undefined && (!Number.isSafeInteger(value) || value < 1))
+    throw new RangeError(`${name} must be a positive integer`);
+  return value;
+}
+
+function abortError(signal: AbortSignal): unknown {
+  return signal.reason ?? new DOMException("Aborted", "AbortError");
+}
+
+async function boundedDrain(operations: Set<Promise<void>>): Promise<void> {
+  if (operations.size === 0) return;
+  await Promise.race([
+    Promise.allSettled([...operations]).then(() => undefined),
+    Bun.sleep(HOST_DRAIN_GRACE_MS),
+  ]);
+}
+
+/**
+ * Runs parsing and CodeMode execution in a terminable worker. Host effects remain
+ * in this process and receive an internal cancellation signal as an optional
+ * second argument. At most 64 interpreter calls may coexist; excess fan-out fails
+ * rather than waiting and deadlocking nested workflows.
+ */
+export async function executeWorkflow(input: ExecuteInput): Promise<unknown> {
+  const maxCalls = positiveOption(input.maxCalls, "maxCalls");
+  const timeoutMs = positiveOption(input.timeoutMs, "timeoutMs");
+  if (input.signal.aborted) throw abortError(input.signal);
+  if (liveWorkers >= MAX_RUNTIME_WORKERS) throw new Error(`Workflow runtime worker limit reached (${MAX_RUNTIME_WORKERS})`);
+  const worker = new Worker(new URL("./workflow-runtime-worker.ts", import.meta.url), { type: "module" });
+  liveWorkers++;
+  const hostController = new AbortController();
+  const operations = new Set<Promise<void>>();
+  let acceptingCalls = true;
+  let settled = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let resolveResult!: (value: unknown) => void;
+  let rejectResult!: (error: unknown) => void;
+  const result = new Promise<unknown>((resolve, reject) => { resolveResult = resolve; rejectResult = reject; });
+
+  const stop = (reason: unknown) => {
+    if (settled) return;
+    settled = true;
+    acceptingCalls = false;
+    hostController.abort(reason);
+    void worker.terminate();
+    rejectResult(reason);
+  };
+  const onAbort = () => stop(abortError(input.signal));
+  input.signal.addEventListener("abort", onAbort, { once: true });
+  if (timeoutMs !== undefined) {
+    timer = setTimeout(() => stop(new Error(`Workflow execution timed out after ${timeoutMs}ms`)), timeoutMs);
+  }
+
+  const invokeHost = (method: HostMethod, value: unknown): Promise<unknown> => {
+    switch (method) {
+      case "agent": return input.host.agent(value, hostController.signal);
+      case "phase": return input.host.phase(value as string, hostController.signal);
+      case "log": return input.host.log(value as string, hostController.signal);
+      case "checkpoint": return input.host.checkpoint(value, hostController.signal);
+      case "workflow": return input.host.workflow(value as { name: string; args?: unknown }, hostController.signal);
+    }
+  };
+
+  worker.onmessage = (event: MessageEvent<WorkerToParent>) => {
+    const message = event.data;
+    if (message.type === "hostCall") {
+      if (!acceptingCalls) return;
+      const operation = Promise.resolve().then(() => invokeHost(message.method, message.input)).then(
+        (value) => {
+          if (!acceptingCalls) return;
+          try {
+            assertBoundedMessage(value, `Workflow ${message.method} response`);
+            worker.postMessage({ type: "hostResult", id: message.id, ok: true, value } satisfies ParentToWorker);
+          } catch (error) {
+            worker.postMessage({ type: "hostResult", id: message.id, ok: false, error: `truncated: ${boundedDiagnostic(error)}` } satisfies ParentToWorker);
+          }
+        },
+        (error) => {
+          if (!acceptingCalls) return;
+          worker.postMessage({ type: "hostResult", id: message.id, ok: false, error: boundedDiagnostic(error) } satisfies ParentToWorker);
+        },
+      );
+      const tracked = operation.then(() => {}, () => {});
+      operations.add(tracked);
+      void tracked.finally(() => operations.delete(tracked));
+      return;
+    }
+    if (message.type !== "result" || settled) return;
+    settled = true;
+    acceptingCalls = false;
+    if (message.ok) resolveResult(message.value);
+    else {
+      hostController.abort(new Error(message.error));
+      rejectResult(new Error(message.error));
+    }
+  };
+  worker.onerror = (event: ErrorEvent) => stop(new Error(boundedDiagnostic(event.error ?? event.message)));
+
+  try {
+    worker.postMessage({ type: "start", script: input.script, args: input.args, maxCalls, timeoutMs } satisfies ParentToWorker);
+    return await result;
+  } finally {
+    acceptingCalls = false;
+    input.signal.removeEventListener("abort", onAbort);
+    if (timer !== undefined) clearTimeout(timer);
+    if (!hostController.signal.aborted) hostController.abort(new Error("Workflow runtime finished"));
+    void worker.terminate();
+    await boundedDrain(operations);
+    liveWorkers--;
+  }
+}