surf-cli 2.10.0 → 2.12.0

package/native/oracle-jobs.cjs

@@ -0,0 +1,253 @@
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+const {
+  assertNotSymlink,
+  atomicWriteFile,
+  atomicWriteJson,
+  ensurePrivateDir,
+  getPrivateStateRoot,
+  readPrivateFile,
+  readPrivateJson,
+} = require("./private-state.cjs");
+
+const JOB_ID_PATTERN = /^\d{8}-\d{6}-[0-9a-f]{4}$/;
+const TERMINAL_STATES = new Set(["captured", "failed"]);
+const TRANSITIONS = {
+  created: new Set(["dispatched", "failed"]),
+  dispatched: new Set(["awaiting", "failed"]),
+  awaiting: new Set(["captured", "failed"]),
+};
+
+function oracleRoot(root = getPrivateStateRoot()) {
+  return path.join(root, "oracle");
+}
+
+function jobDirectory(id, root = getPrivateStateRoot()) {
+  if (!JOB_ID_PATTERN.test(id)) throw codedError("not_found", `oracle job not found: ${id}`);
+  return path.join(oracleRoot(root), id);
+}
+
+function codedError(code, message, details = {}) {
+  const error = new Error(message);
+  error.code = code;
+  Object.assign(error, details);
+  return error;
+}
+
+function readJobs(root = getPrivateStateRoot()) {
+  const base = oracleRoot(root);
+  if (!fs.existsSync(base)) return [];
+  const stat = assertNotSymlink(base, false);
+  if (!stat.isDirectory()) throw new Error(`oracle state path is not a directory: ${base}`);
+  return fs.readdirSync(base)
+    .filter((id) => JOB_ID_PATTERN.test(id))
+    .sort((a, b) => b.localeCompare(a))
+    .map((id) => readPrivateJson(path.join(base, id, "job.json"), null, { root }))
+    .filter(Boolean);
+}
+
+function createJob({ prompt, contextManifest = {}, model = null, effortRequested = null, follow = null }) {
+  const root = getPrivateStateRoot();
+  const base = oracleRoot(root);
+  ensurePrivateDir(base, root);
+  const inFlight = readJobs(root).find((job) => !TERMINAL_STATES.has(job.state));
+  if (inFlight) {
+    throw codedError(
+      "capacity",
+      `oracle job capacity reached; in-flight job: ${inFlight.id}`,
+      { jobId: inFlight.id },
+    );
+  }
+
+  const now = new Date();
+  const compactTimestamp = now.toISOString().replace(/\D/g, "").slice(0, 14);
+  const timestamp = `${compactTimestamp.slice(0, 8)}-${compactTimestamp.slice(8)}`;
+  let id;
+  let directory;
+  for (;;) {
+    id = `${timestamp}-${crypto.randomBytes(2).toString("hex")}`;
+    directory = path.join(base, id);
+    try {
+      fs.mkdirSync(directory, { mode: 0o700 });
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+    }
+  }
+
+  try {
+    ensurePrivateDir(path.join(directory, "turns"), root);
+    atomicWriteFile(path.join(directory, "request.md"), prompt, { root, encoding: "utf8" });
+    atomicWriteJson(path.join(directory, "context-manifest.json"), contextManifest, { root });
+    const job = {
+      id,
+      state: "created",
+      model,
+      effortRequested,
+      effortVerified: null,
+      createdAt: now.toISOString(),
+      dispatchedAt: null,
+      awaitingAt: null,
+      capturedAt: null,
+      failedAt: null,
+      tabId: null,
+      conversationUrl: null,
+      promptEcho: null,
+      error: null,
+      turns: [],
+      ...(follow ? { follow } : {}),
+    };
+    atomicWriteJson(path.join(directory, "job.json"), job, { root });
+    return job;
+  } catch (error) {
+    fs.rmSync(directory, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+function getJob(id) {
+  const root = getPrivateStateRoot();
+  const job = readPrivateJson(path.join(jobDirectory(id, root), "job.json"), null, { root });
+  if (!job) throw codedError("not_found", `oracle job not found: ${id}`);
+  return job;
+}
+
+function getResponse(id) {
+  const root = getPrivateStateRoot();
+  getJob(id);
+  return readPrivateFile(path.join(jobDirectory(id, root), "response.md"), {
+    root,
+    encoding: "utf8",
+  });
+}
+
+function transition(id, state, updates) {
+  const job = getJob(id);
+  if (!TRANSITIONS[job.state]?.has(state)) {
+    throw codedError(
+      "invalid_transition",
+      `oracle job ${id} cannot transition from ${job.state} to ${state}`,
+    );
+  }
+  const updated = { ...job, state, ...updates };
+  const root = getPrivateStateRoot();
+  atomicWriteJson(path.join(jobDirectory(id, root), "job.json"), updated, { root });
+  return updated;
+}
+
+function markDispatched(id, { tabId, promptEcho, modelVerified, effortVerified }) {
+  return transition(id, "dispatched", {
+    dispatchedAt: new Date().toISOString(),
+    tabId,
+    ...(promptEcho ? { promptEcho } : {}),
+    ...(modelVerified ? { model: modelVerified } : {}),
+    ...(effortVerified ? { effortVerified } : {}),
+  });
+}
+
+function markAwaiting(id, { conversationUrl, promptEcho }) {
+  return transition(id, "awaiting", {
+    awaitingAt: new Date().toISOString(),
+    conversationUrl,
+    promptEcho,
+  });
+}
+
+function markCaptured(id, { response }) {
+  const job = getJob(id);
+  if (!TRANSITIONS[job.state]?.has("captured")) {
+    throw codedError(
+      "invalid_transition",
+      `oracle job ${id} cannot transition from ${job.state} to captured`,
+    );
+  }
+  const root = getPrivateStateRoot();
+  atomicWriteFile(path.join(jobDirectory(id, root), "response.md"), response, {
+    root,
+    encoding: "utf8",
+  });
+  return transition(id, "captured", { capturedAt: new Date().toISOString() });
+}
+
+function markFailed(id, { code, message }) {
+  return transition(id, "failed", {
+    failedAt: new Date().toISOString(),
+    error: { code, message },
+  });
+}
+
+function updateTabId(id, tabId) {
+  const job = getJob(id);
+  if (TERMINAL_STATES.has(job.state)) {
+    throw codedError(
+      "invalid_transition",
+      `oracle job ${id} cannot transition from ${job.state} to update tab`,
+    );
+  }
+  const updated = { ...job, tabId };
+  const root = getPrivateStateRoot();
+  atomicWriteJson(path.join(jobDirectory(id, root), "job.json"), updated, { root });
+  return updated;
+}
+
+function appendTurn(id, turn) {
+  const job = getJob(id);
+  const storedTurn = {
+    prompt: turn.prompt,
+    dispatchedAt: turn.dispatchedAt ?? null,
+    capturedAt: turn.capturedAt ?? null,
+  };
+  const root = getPrivateStateRoot();
+  const directory = jobDirectory(id, root);
+  const turnName = `${String(job.turns.length + 1).padStart(4, "0")}.json`;
+  atomicWriteJson(path.join(directory, "turns", turnName), storedTurn, { root });
+  const updated = { ...job, turns: [...job.turns, storedTurn] };
+  atomicWriteJson(path.join(directory, "job.json"), updated, { root });
+  return updated;
+}
+
+function markTurnCaptured(id, { dispatchedAt, capturedAt }) {
+  const job = getJob(id);
+  const turnIndex = job.turns.findIndex((turn) => turn.dispatchedAt === dispatchedAt);
+  if (turnIndex === -1) {
+    throw codedError(
+      "invalid_transition",
+      `oracle job ${id} has no follow turn dispatched at ${dispatchedAt}`,
+    );
+  }
+  const turns = [...job.turns];
+  turns[turnIndex] = { ...turns[turnIndex], capturedAt };
+  const root = getPrivateStateRoot();
+  const directory = jobDirectory(id, root);
+  const turnName = `${String(turnIndex + 1).padStart(4, "0")}.json`;
+  atomicWriteJson(path.join(directory, "turns", turnName), turns[turnIndex], { root });
+  const updated = { ...job, turns };
+  atomicWriteJson(path.join(directory, "job.json"), updated, { root });
+  return updated;
+}
+
+function listJobs({ limit } = {}) {
+  const jobs = readJobs();
+  return limit === undefined ? jobs : jobs.slice(0, Math.max(0, limit));
+}
+
+function adoptOrphans() {
+  return listJobs({}).filter((job) => !TERMINAL_STATES.has(job.state));
+}
+
+module.exports = {
+  adoptOrphans,
+  appendTurn,
+  createJob,
+  getJob,
+  getResponse,
+  listJobs,
+  markAwaiting,
+  markCaptured,
+  markDispatched,
+  markFailed,
+  markTurnCaptured,
+  oracleRoot,
+  updateTabId,
+};

package/native/playbook-cli.cjs

@@ -48,7 +48,7 @@ function runSpec(argv) {
   const parsed = parseCommandArgs(argv.slice(offset));
   const [playbook, op] = parsed.positional;
   if (!playbook || !op) throw new Error(direct ? "Usage: surf use <playbook> <op> [--arg value]" : "Usage: surf pb run <playbook> <op> [--arg value]");
-  const reserved = new Set(["json", "no-lock", "tab-id", "write", "repeat", "retry-attempt", "override-in-doubt", "pin-built-in"]);
+  const reserved = new Set(["json", "no-lock", "tab-id", "write", "repeat", "retry-attempt", "override-in-doubt", "pin-built-in", "allow-script"]);
   const args = Object.fromEntries(Object.entries(parsed.options).filter(([name]) => !reserved.has(name)));
   return { playbook, op, args, options: parsed.options };
 }
@@ -89,6 +89,7 @@ async function handlePlaybookCli(argv, { endpoint, cwd = process.cwd() }) {
       retryAttempt: spec.options["retry-attempt"],
       overrideInDoubt: spec.options["override-in-doubt"] === true,
       pinBuiltIn: spec.options["pin-built-in"] === true,
+      allowScript: spec.options["allow-script"] === true,
     };
     const value = await requestHost(endpoint, "playbook.run", args, {
       tabId: spec.options["tab-id"],
@@ -98,7 +99,7 @@ async function handlePlaybookCli(argv, { endpoint, cwd = process.cwd() }) {
   }
   const command = argv[1];
   const parsed = parseCommandArgs(argv.slice(2));
-  if (!command || command === "help") return { handled: true, value: "Usage: surf playbook|pb <list|show|ops|run|record|suggest|save|client|trace|export|import>" };
+  if (!command || command === "help") return { handled: true, value: "Usage: surf playbook|pb <list|show|ops|run|record|suggest|save|client|trace|export|import>\nRun trusted script strategies with: surf use <playbook> <op> --allow-script" };
   if (endpoint?.kind === "remote" && ["list", "show", "ops"].includes(command)) throw new Error(`playbook ${command} is local-only with --remote because runs resolve on the browser host`);
   if (command === "list") return { handled: true, value: listPlaybooks({ cwd }), json: parsed.options.json === true };
   if (command === "show") {

package/native/playbook-runtime.cjs

@@ -1,4 +1,5 @@
-const { executeWorkflow } = require("./workflow-runtime.cjs");
+const { executeSingleStep, executeWorkflow } = require("./workflow-runtime.cjs");
+const { runWorkflowScript } = require("./workflow-script-runtime.cjs");
 
 function applyTemplate(value, args) {
   if (typeof value === "string") {
@@ -93,6 +94,31 @@ return { status: response.status, ok: response.ok, url: response.url, headers: O
 }
 
 async function runStrategy(strategy, context) {
+  if (strategy.using === "script") {
+    if (context.allowScript !== true) throw new Error("script strategy requires --allow-script");
+    const vars = { ...context.args };
+    const result = await runWorkflowScript({
+      script: strategy.script,
+      input: context.args,
+      timeoutMs: strategy.timeoutMs ?? 10 * 60 * 1000,
+      signal: context.signal,
+      onEvent: context.onEvent,
+      executeTool: async (tool, args, options = {}) => {
+        await context.markDispatched?.();
+        const step = await executeSingleStep({ cmd: tool, args, as: "value" }, vars, {
+          autoWait: strategy.autoWait !== false,
+          executeTool: context.executeTool,
+          onEvent: context.onEvent,
+          signal: options.signal || context.signal,
+          sleep: context.sleep,
+          stepDelay: strategy.stepDelay ?? 100,
+        });
+        if (!step.success) throw new Error(step.error || `tool ${tool} failed`);
+        return step.output;
+      },
+    });
+    return result.value;
+  }
   if (strategy.using === "workflow") {
     const result = await executeWorkflow(applyTemplate(strategy.steps, context.args), {
       autoWait: strategy.autoWait !== false,
@@ -130,7 +156,7 @@ async function runStrategy(strategy, context) {
   throw new Error(`unsupported strategy: ${strategy.using}`);
 }
 
-async function runPlaybookOp({ playbook, op, args: providedArgs = {}, attemptId, executeTool, executeNative, signal, sleep, onEvent = () => {}, beforeDispatch = async () => {}, afterDispatch = async () => {} }) {
+async function runPlaybookOp({ playbook, op, args: providedArgs = {}, attemptId, executeTool, executeNative, signal, sleep, onEvent = () => {}, beforeDispatch = async () => {}, afterDispatch = async () => {}, allowScript = false }) {
   const args = resolveArgs(op, providedArgs);
   const attempts = [];
   for (let index = 0; index < op.run.length; index++) {
@@ -154,6 +180,7 @@ async function runPlaybookOp({ playbook, op, args: providedArgs = {}, attemptId,
         allowedOrigins: op.origins || playbook.origins || [],
         markDispatched: op.effect === "write" ? markDispatched : undefined,
         serverIdempotency: op.effect === "write" ? op.safety?.serverIdempotency : undefined,
+        allowScript,
       });
       const value = extractResult(raw, strategy.extract);
       verifyResult(value, strategy.verify || strategy.expect || op.on?.success?.expect, raw);

package/native/playbooks.cjs

@@ -75,8 +75,21 @@ function validateWriteWorkflowSteps(steps, opId) {
   }
 }
 
+function normalizeScript(value) {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value) && value.every((line) => typeof line === "string")) return value.join("\n");
+  return null;
+}
+
 function validateStrategy(strategy, effect, opId) {
   if (!strategy || typeof strategy !== "object" || Array.isArray(strategy)) throw new Error("playbook strategy must be an object");
+  if (strategy.using === "script") {
+    if (effect === "write") throw new Error(`write op ${opId} script strategy is not supported`);
+    const script = normalizeScript(strategy.script);
+    if (!script?.trim()) throw new Error("script strategy requires script");
+    if (strategy.timeoutMs !== undefined && (!Number.isInteger(strategy.timeoutMs) || strategy.timeoutMs < 1)) throw new Error("script strategy timeoutMs must be a positive integer");
+    return { ...strategy, script };
+  }
   if (strategy.using === "workflow") {
     if (!Array.isArray(strategy.steps) || strategy.steps.length === 0) throw new Error("workflow strategy requires steps");
     const steps = strategy.steps.map(normalizeStep);

package/native/workflow-definition.cjs

@@ -7,6 +7,7 @@ const COMMANDS = {
   ai: { primaryArg: "query", effect: "read", argKinds: { query: "user-input" }, sensitiveArgs: ["query"] },
   gemini: { primaryArg: "query", effect: "page-write", argKinds: { query: "user-input" }, sensitiveArgs: ["query"] },
   chatgpt: { primaryArg: "query", effect: "page-write", argKinds: { query: "user-input" }, sensitiveArgs: ["query"] },
+  "oracle.ask": { primaryArg: "prompt", effect: "page-write", argKinds: { prompt: "user-input" }, sensitiveArgs: ["prompt"] },
   perplexity: { primaryArg: "query", effect: "page-write", argKinds: { query: "user-input" }, sensitiveArgs: ["query"] },
   grok: { primaryArg: "query", effect: "page-write", argKinds: { query: "user-input" }, sensitiveArgs: ["query"] },
   navigate: { primaryArg: "url", effect: "navigation", argKinds: { url: "url" } },

package/native/workflow-script-runtime.cjs

@@ -0,0 +1,294 @@
+const { Worker } = require("node:worker_threads");
+
+const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+const WORKER_SOURCE = String.raw`
+const { parentPort } = require("node:worker_threads");
+const vm = require("node:vm");
+const { inspect } = require("node:util");
+
+let nextCallId = 0;
+const pending = new Map();
+const keyPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const fingerprints = new Map();
+let contextObjectPrototype;
+
+function stableJson(value) {
+  if (Array.isArray(value)) return "[" + value.map(stableJson).join(",") + "]";
+  if (value && typeof value === "object") return "{" + Object.keys(value).sort().map((key) => JSON.stringify(key) + ":" + stableJson(value[key])).join(",") + "}";
+  return JSON.stringify(value) ?? "undefined";
+}
+
+function assertJsonValue(value, path = "value", seen = new Set()) {
+  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.prototype.hasOwnProperty.call(value, index)) throw new Error(path + " must not contain sparse array entries.");
+      assertJsonValue(value[index], path + "[" + index + "]", seen);
+    }
+  } else {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== null && prototype !== Object.prototype && prototype !== contextObjectPrototype) 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)) assertJsonValue(entry, path + "." + key, seen);
+  }
+  seen.delete(value);
+}
+
+function hostCall(method, args) {
+  return new Promise((resolve, reject) => {
+    const callId = ++nextCallId;
+    pending.set(callId, { resolve, reject });
+    parentPort.postMessage({ type: "call", callId, method, args });
+  });
+}
+
+function validateRunCall(key, params, label, nextFingerprints = fingerprints) {
+  if (typeof key !== "string" || !keyPattern.test(key)) throw new Error(label + " has an invalid key.");
+  if (!params || typeof params !== "object" || Array.isArray(params)) throw new Error(label + " requires a params object.");
+  const tool = params.tool ?? params.cmd;
+  if (typeof tool !== "string" || !tool) throw new Error(label + " requires a tool string.");
+  if (params.args !== undefined && (!params.args || typeof params.args !== "object" || Array.isArray(params.args))) throw new Error(label + " args must be an object.");
+  assertJsonValue(params, label + " params");
+  const fingerprint = stableJson(params);
+  const existing = nextFingerprints.get(key);
+  if (existing !== undefined && existing !== fingerprint) throw new Error("Duplicate script key '" + key + "' used with incompatible tool params.");
+  nextFingerprints.set(key, fingerprint);
+}
+
+const tools = Object.freeze({
+  run(key, params) {
+    validateRunCall(key, params, "tools.run");
+    return hostCall("run", { key, params });
+  },
+  all(items) {
+    if (!Array.isArray(items)) throw new Error("tools.all(items) requires an array.");
+    const nextFingerprints = new Map(fingerprints);
+    const calls = [];
+    for (let index = 0; index < items.length; index++) {
+      if (!Object.prototype.hasOwnProperty.call(items, index)) throw new Error("tools.all items must not contain sparse entries.");
+      const item = items[index];
+      if (!item || typeof item !== "object" || Array.isArray(item)) throw new Error("tools.all item " + index + " must be an object.");
+      const { key, ...params } = item;
+      validateRunCall(key, params, "tools.all item " + index, nextFingerprints);
+      calls.push({ key, params });
+    }
+    for (const { key, params } of calls) fingerprints.set(key, stableJson(params));
+    return Promise.all(calls.map(({ key, params }) => hostCall("run", { key, params, collectFailure: true })));
+  },
+  ref(result) {
+    if (!result || typeof result !== "object") throw new Error("tools.ref(result) requires a tool result object.");
+    return "[tool " + (result.key || "unknown") + "]";
+  },
+  refs(results) {
+    if (!Array.isArray(results)) throw new Error("tools.refs(results) requires an array.");
+    return results.map(tools.ref).join("\n");
+  },
+});
+
+const capturedConsole = Object.freeze(Object.fromEntries(
+  ["log", "info", "warn", "error"].map((level) => [level, (...args) => {
+    parentPort.postMessage({ type: "console", level, text: args.map((value) => typeof value === "string" ? value : inspect(value, { depth: 4, breakLength: 120 })).join(" ") });
+  }]),
+));
+
+parentPort.on("message", async (message) => {
+  if (message.type === "response") {
+    const entry = pending.get(message.callId);
+    if (!entry) return;
+    pending.delete(message.callId);
+    if (message.ok) entry.resolve(message.value);
+    else entry.reject(new Error(message.error));
+    return;
+  }
+  if (message.type !== "start") return;
+  try {
+    const sandbox = {
+      input: Object.freeze(message.input ?? {}),
+      tools,
+      surf: tools,
+      emit(value) { assertJsonValue(value, "emit"); parentPort.postMessage({ type: "emit", value }); },
+      console: capturedConsole,
+    };
+    const context = vm.createContext(sandbox, { codeGeneration: { strings: false, wasm: false } });
+    contextObjectPrototype = vm.runInContext("Object.prototype", context);
+    const compiled = new vm.Script("(async () => {\n" + message.script + "\n})()", { filename: "surf-workflow-script.js" });
+    const value = await compiled.runInContext(context);
+    const persistedValue = value === undefined ? null : value;
+    assertJsonValue(persistedValue, "return");
+    parentPort.postMessage({ type: "complete", value: persistedValue });
+  } catch (error) {
+    parentPort.postMessage({ type: "error", error: error && error.stack ? error.stack : String(error) });
+  }
+});
+`;
+
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function assertJsonValue(value, path = "value", seen = new Set()) {
+  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.`);
+      assertJsonValue(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)) assertJsonValue(entry, `${path}.${key}`, seen);
+  }
+  seen.delete(value);
+}
+
+function omitUndefined(value, seen = new Set()) {
+  if (value === null || typeof value !== "object") return value;
+  if (seen.has(value)) return value;
+  seen.add(value);
+  const next = Array.isArray(value)
+    ? value.map((entry) => entry === undefined ? null : omitUndefined(entry, seen))
+    : Object.fromEntries(Object.entries(value).flatMap(([key, entry]) => entry === undefined ? [] : [[key, omitUndefined(entry, seen)]]));
+  seen.delete(value);
+  return next;
+}
+
+function validateKey(value) {
+  if (typeof value !== "string" || !KEY_PATTERN.test(value)) {
+    throw new Error("tool key must be 1-128 characters using letters, numbers, '.', '_' or '-', and start with a letter or number.");
+  }
+  return value;
+}
+
+async function runWorkflowScript({ script, input = {}, timeoutMs = 10 * 60 * 1000, signal, executeTool, onEvent = () => {}, onEmit = () => {}, onConsole = () => {} }) {
+  if (typeof script !== "string" || !script.trim()) throw new Error("script strategy requires a non-empty script string");
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1) throw new Error("script timeoutMs must be a positive integer");
+  if (typeof executeTool !== "function") throw new Error("script strategy requires executeTool");
+  assertJsonValue(input, "input");
+
+  const worker = new Worker(WORKER_SOURCE, { eval: true });
+  const emits = [];
+  const consoleEntries = [];
+  const trace = [];
+  const childController = new AbortController();
+  let settled = false;
+
+  return await new Promise((resolve, reject) => {
+    const finish = (outcome) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      void worker.terminate();
+      childController.abort(outcome.error || new Error("Script strategy completed."));
+      if (outcome.error) reject(outcome.error);
+      else resolve({ value: outcome.value, emits, console: consoleEntries, trace });
+    };
+    const onAbort = () => finish({ error: new Error(signal.reason instanceof Error ? signal.reason.message : String(signal.reason || "Script strategy aborted")) });
+    const timer = setTimeout(() => finish({ error: new Error(`Script strategy timed out after ${timeoutMs}ms.`) }), timeoutMs);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted) return onAbort();
+
+    const respond = (callId, promise) => {
+      void promise.then(
+        (value) => {
+          try {
+            const clean = omitUndefined(value);
+            assertJsonValue(clean, "tool result");
+            worker.postMessage({ type: "response", callId, ok: true, value: clean });
+          } catch (error) {
+            worker.postMessage({ type: "response", callId, ok: false, error: error instanceof Error ? error.message : String(error) });
+          }
+        },
+        (error) => worker.postMessage({ type: "response", callId, ok: false, error: error instanceof Error ? error.message : String(error) }),
+      );
+    };
+
+    worker.on("error", (error) => finish({ error: new Error(`Script worker failed: ${error.message}`) }));
+    worker.on("exit", (code) => {
+      if (!settled && code !== 0) finish({ error: new Error(`Script worker exited with code ${code}.`) });
+    });
+    worker.on("message", (message) => {
+      if (message.type === "emit") {
+        try {
+          assertJsonValue(message.value, "emit");
+          emits.push(message.value);
+          onEmit([...emits]);
+        } catch (error) {
+          finish({ error: new Error(`Script emit could not be persisted: ${error.message}`) });
+        }
+        return;
+      }
+      if (message.type === "console") {
+        if (["log", "info", "warn", "error"].includes(message.level) && typeof message.text === "string") {
+          const entry = { level: message.level, text: message.text };
+          consoleEntries.push(entry);
+          onConsole(entry);
+        }
+        return;
+      }
+      if (message.type === "complete") {
+        try {
+          assertJsonValue(message.value, "return");
+          finish({ value: message.value });
+        } catch (error) {
+          finish({ error: new Error(`Script return could not be persisted: ${error.message}`) });
+        }
+        return;
+      }
+      if (message.type === "error") return finish({ error: new Error(typeof message.error === "string" ? message.error : "Script strategy failed.") });
+      if (message.type !== "call" || typeof message.callId !== "number" || message.method !== "run" || !isRecord(message.args)) return;
+      let key;
+      try {
+        key = validateKey(message.args.key);
+      } catch (error) {
+        return respond(message.callId, Promise.reject(error));
+      }
+      const params = message.args.params;
+      if (!isRecord(params)) return respond(message.callId, Promise.reject(new Error(`tools.run('${key}', params) requires a params object.`)));
+      const tool = params.tool ?? params.cmd;
+      if (typeof tool !== "string" || !tool) return respond(message.callId, Promise.reject(new Error(`tools.run('${key}') requires a tool string.`)));
+      const args = params.args === undefined ? {} : params.args;
+      if (!isRecord(args)) return respond(message.callId, Promise.reject(new Error(`tools.run('${key}') args must be an object.`)));
+      const collectFailure = message.args.collectFailure === true;
+      const startedAt = Date.now();
+      trace.push({ key, tool, state: "started" });
+      onEvent({ type: "script.tool.started", key, tool, startedAt: new Date().toISOString() });
+      respond(message.callId, Promise.resolve().then(async () => {
+        try {
+          const output = await executeTool(tool, args, { signal: childController.signal });
+          const result = { key, tool, ok: true, output };
+          trace.push({ key, tool, state: "completed", durationMs: Date.now() - startedAt });
+          onEvent({ type: "script.tool.completed", key, tool, endedAt: new Date().toISOString() });
+          return result;
+        } catch (error) {
+          const text = error instanceof Error ? error.message : String(error);
+          const result = { key, tool, ok: false, error: text };
+          trace.push({ key, tool, state: "failed", durationMs: Date.now() - startedAt, error: text });
+          onEvent({ type: "script.tool.failed", key, tool, error: text, endedAt: new Date().toISOString() });
+          if (!collectFailure) throw new Error(`Tool '${key}' failed: ${text}`);
+          return result;
+        }
+      }));
+    });
+
+    worker.postMessage({ type: "start", script, input });
+  });
+}
+
+module.exports = { runWorkflowScript };