@sema-ai/core 1.275.1

package/dist/orchestration/run-workflow-tool.js

@@ -0,0 +1,612 @@
+/**
+ * design/98 §3.1 (S8c) — the `run_workflow` TOOL an LLM calls to author + run its own workflow. Mounted ONLY
+ * when self-orchestration is active (design/98 §1.2: opt-in + a HARD `WorkflowScriptRunner` + a governance
+ * baseline). Params are ONLY `{ script, args }` — it NEVER accepts `depth` (the nesting depth is a trusted
+ * internal channel, design/98 §0.1). `effect: "write"` (spawning agents is an irreversible side effect → it
+ * passes the design/37 policy gate; each spawned agent then passes its OWN governed gate).
+ *
+ * Flow: size-cap the script → statically validate `meta` (no eval) → `startWorkflow` with the GOVERNED
+ * primitives + hard caps → return `{ runId }` IMMEDIATELY → on completion, notify the originator via the
+ * {@link WorkflowCompletionNotifier} seam.
+ */
+import { Type } from "typebox";
+import { defineTool } from "../core/tools.js";
+import { redactHostLeaks, boundedRedactedSummary } from "../core/untrusted-egress.js";
+import { startWorkflow } from "./workflow.js";
+import { buildWorkflowPrimitives } from "./workflow-primitives.js";
+import { parseWorkflowMeta, splitWorkflowMeta, workflowScriptReadsClockOrRandom } from "./workflow-meta.js";
+import { mergeWorkflowArgs, normalizeStringArg } from "./workflow-script-store.js";
+import { builtinWorkflowListings, resolveBuiltinWorkflow } from "./builtin-workflows.js";
+import { workflowSizeGuidelineSection } from "./workflow-size-guideline.js";
+/** Reserved name of the injected self-orchestration tool. Audit [485]④ (2026-07-07): CC's primary
+ *  name is `Workflow` with `RunWorkflow` as the alias — CC-trained prompts address "Workflow", so the
+ *  primary flips to match; `RunWorkflow`/`run_workflow` remain callable via tool-name-aliases. */
+export const RUN_WORKFLOW_TOOL_NAME = "Workflow";
+/** Strip the surrounding markdown code fence a model commonly wraps a script in (```js … ```). Conservative:
+ *  only when the WHOLE trimmed string is one fenced block; leaves an unfenced script untouched. */
+function stripCodeFences(s) {
+    const t = s.trim();
+    const m = /^```[A-Za-z]*\r?\n([\s\S]*?)\r?\n?```$/.exec(t);
+    return m ? m[1] : s;
+}
+const DEFAULTS = {
+    maxScriptChars: 100_000,
+    maxAgents: 50,
+    totalTimeoutMs: 600_000,
+    perAgentTimeoutSec: 300,
+    maxResultChars: 100_000,
+    maxLogChars: 10_000,
+};
+// The summary handed to the notifier is REDACTED + bounded — never the raw result/host internals
+// (design/98 §D.5 / IMPLEMENTER-SPEC §5). boundedSummary / redactSummary live in
+// ../core/untrusted-egress.ts (design/97 CORE-2 — the single untrusted-text→human egress home).
+/**
+ * 黑板 [405][S]: the COMPLETED-path `summary` is a bounded HUMAN-READABLE line (name + agent counts +
+ * elapsed), never the return value's escaped-JSON blob — clay 截图里模型收到一坨 `\n` blob 原样复述。
+ * The (bounded, redacted) return value still travels in `result`, and the full one via TaskOutput.
+ */
+function completionSummary(name, run) {
+    // codex 复审 m: meta.name is MODEL-authored and flows to the raw notifier seam — neutralize to a
+    // conservative charset (no quotes/backticks/control chars can alter the summary line's framing).
+    const cleanName = name?.replace(/[^\p{L}\p{N} _.:/-]/gu, "").replace(/\s+/g, " ").trim().slice(0, 60);
+    const done = run.agents.filter((a) => a.status === "completed").length;
+    const failed = run.agents.filter((a) => a.status === "failed").length;
+    const secs = run.endedAt !== undefined ? Math.max(0, Math.round((run.endedAt - run.startedAt) / 1000)) : undefined;
+    const elapsed = secs === undefined ? "" : secs >= 60 ? ` in ${Math.floor(secs / 60)}m${secs % 60}s` : ` in ${secs}s`;
+    return (`workflow${cleanName ? ` "${cleanName}"` : ""} completed${elapsed} — agents ${done}/${run.agents.length} done` +
+        `${failed > 0 ? ` (${failed} failed)` : ""}; result via TaskOutput("${run.id}")`);
+}
+/** Codes for errors that are about the LLM's OWN SCRIPT (its fault, safe + actionable to surface so it can
+ *  self-correct) — as opposed to a HOST runtime error (kept generic, may carry paths/tokens). */
+const SCRIPT_ERROR_CODES = new Set([
+    "workflow.script_error",
+    "workflow.nesting",
+    "workflow.model_not_allowed",
+    "workflow.agent_schema",
+    "workflow.max_agents",
+    "workflow.result_too_large",
+    "workflow.budget_exceeded",
+]);
+/** The FAILED-path summary. For a SCRIPT-level typed error (the model's own script — e.g. a compile error or
+ *  a disallowed model) surface the bounded+redacted message so the model can FIX + retry. For a HOST runtime
+ *  error (no `workflow.*` code, or one not in the script set) stay generic — NEVER the raw host message (it
+ *  originates from `runner.runTask` etc. and can carry paths/tokens). The full error is always in the run
+ *  store, queryable. */
+function failureSummary(err) {
+    const e = err;
+    const code = typeof e?.code === "string" ? e.code : undefined;
+    if (code && SCRIPT_ERROR_CODES.has(code) && typeof e?.message === "string") {
+        const msg = redactHostLeaks(e.message);
+        return `workflow failed (${code}): ${msg.length > 200 ? `${msg.slice(0, 200)}…` : msg}`;
+    }
+    return code && code.startsWith("workflow.") ? `workflow failed (${code})` : "workflow failed";
+}
+/**
+ * design/140 §6 1b — pick the LLM-facing guidance text for one named workflow: `whenToUse` when declared,
+ * else the description (the agents-side `agentWhenToUseText`/CC `tIl` selection shape, workflows arm —
+ * workflows have no lean variant, so the fallback chain is just whenToUse → description).
+ */
+export function workflowWhenToUseText(m) {
+    return (m.whenToUse || m.description) || undefined;
+}
+/**
+ * design/140 §6 1b — render the named-workflow roster block appended to the Workflow tool card (the
+ * consumption face `meta.whenToUse` previously lacked). Line shape mirrors the agent roster (CC `tIl`,
+ * subagent.ts precedent): `- name: whenToUse-or-description`. Returns undefined when nothing is registered
+ * (the card stays byte-identical to the pre-140 form).
+ */
+export function renderNamedWorkflowListing(entries) {
+    if (entries.length === 0)
+        return undefined;
+    const lines = entries.map((e) => {
+        const w = workflowWhenToUseText(e);
+        return `- ${e.name}${w ? `: ${w}` : ""}`;
+    });
+    return ("Named workflows available via {name} (registered defaults merge UNDER your `args`; a top-level key you pass wins wholesale):\n" +
+        lines.join("\n"));
+}
+/** Collect the card's named-workflow roster with the SAME shadowing truth as the execute path (codex F3):
+ *  a built-in name that the deployment registry RESOLVES is shadowed at execution — so the card must not
+ *  advertise the built-in's metadata for it. Each built-in name is probed via `resolveName()` (the execute
+ *  path's own source); a shadowed name keeps a line (the workflow exists) but with an honest deployment
+ *  marker unless `list()` supplies the deployment's real metadata, which then overlays BY NAME. `list()` is
+ *  awaited (async stores reach the card too); any probe/listing failure degrades to the advisory default —
+ *  it must never block mounting the tool. */
+async function collectNamedWorkflowListings(store, builtinsEnabled) {
+    const byName = new Map();
+    if (builtinsEnabled) {
+        for (const b of builtinWorkflowListings()) {
+            let shadowed = false;
+            if (store?.resolveName) {
+                try {
+                    shadowed = (await store.resolveName(b.name)) !== undefined;
+                }
+                catch {
+                    shadowed = false; // probe failure → card shows the built-in; execute-path errors surface on call
+                }
+            }
+            byName.set(b.name, shadowed ? { name: b.name, description: "deployment-registered workflow (shadows the built-in of the same name)" } : b);
+        }
+    }
+    try {
+        const listed = await store?.list?.();
+        if (Array.isArray(listed)) {
+            for (const e of listed) {
+                if (e && typeof e.name === "string" && e.name.length > 0)
+                    byName.set(e.name, e);
+            }
+        }
+    }
+    catch {
+        /* a listing hiccup must never block mounting the tool — the roster block is advisory */
+    }
+    return [...byName.values()];
+}
+/**
+ * Build the `run_workflow` tool. ASSERTS the runner is a hard sandbox (defense in depth — prepare-task only
+ * mounts it under the same gate). Returns a structured error (not a throw) for an LLM-correctable problem
+ * (oversized / malformed-meta / nesting), so the model can fix and retry.
+ *
+ * Async since codex F3: the card's named-workflow roster is derived from the SAME sources the execute path
+ * resolves against (built-ins probed through `resolveName` shadowing + awaited `list()`), so the card can
+ * never advertise a workflow the call would resolve differently.
+ */
+export async function createRunWorkflowTool(d) {
+    if (d.scriptRunner.safeForUntrustedScripts !== true) {
+        throw new Error("createRunWorkflowTool: refusing to mount run_workflow on a runner that is not safeForUntrustedScripts (design/98 fail-closed)");
+    }
+    const lim = d.limits ?? {};
+    const maxScriptChars = lim.maxScriptChars ?? DEFAULTS.maxScriptChars;
+    const childCaps = {
+        perAgentTimeoutSec: lim.perAgentTimeoutSec ?? DEFAULTS.perAgentTimeoutSec,
+        childMaxCostUsd: lim.childMaxCostUsd,
+        childMaxTokens: lim.childMaxTokens,
+        childMaxTurns: lim.childMaxTurns,
+    };
+    const governance = { baseline: d.governanceBaseline, models: d.models, caps: childCaps };
+    // design/140 §6 1b/1c: the named-workflow roster on the card (built-ins + sync deployment listing) and the
+    // execute-path built-in fallback share ONE flag (default ON — the builtinAgents GA-default-on posture).
+    const builtinsEnabled = d.builtinWorkflows !== false;
+    const namedWorkflowSection = renderNamedWorkflowListing(await collectNamedWorkflowListings(d.scriptStore, builtinsEnabled));
+    // 黑板 [663]③ (CC 2.1.206 :17593321 — `Bvs + Wvs(Tt().workflowSizeGuideline)` on both prompt() and
+    // description()): the advisory size-guideline section, appended to the card. "unrestricted"/unset ⇒ ""
+    // (byte-identical card). Snapshot at mount time = CC's session-start `pbd` snapshot semantics; the
+    // mid-session change reminder lane is a TODO (see workflow-size-guideline.ts module doc).
+    const sizeGuidelineSection = workflowSizeGuidelineSection(d.sizeGuideline ?? lim.sizeGuideline);
+    const structuredError = (message) => ({ content: JSON.stringify({ error: message }) });
+    return defineTool({
+        name: RUN_WORKFLOW_TOOL_NAME,
+        // Pre-[485]④ primary + snake_case stay callable (old model calls / resumed sessions).
+        aliases: ["RunWorkflow", "run_workflow"],
+        description: "Author and run your own deterministic JS WORKFLOW that spawns and coordinates sub-agents. Pass `script` " +
+            "(begins with `export const meta = {...}`, then an async body) and optional `args` (a JSON value). Returns a " +
+            "runId immediately; the workflow runs asynchronously and you are notified on completion. Use for a " +
+            "SUBSTANTIAL task that genuinely decomposes.\n" +
+            // CC 198 semantic port (deep-diff HIGH-1): CC gates this tool on EXPLICIT opt-in — scale must be
+            // requested, never inferred. sema has no ultracode keyword, so the opt-in list is translated to
+            // deployment-neutral equivalents; the negative fallback is the load-bearing line (a merely
+            // parallelizable task is NOT authorization — that inference is exactly what burns tokens unasked).
+            "ONLY call this tool when multi-agent orchestration was explicitly opted into: the user/operator asked " +
+            "for a workflow or fan-out in their own words, a skill or task directive requests it, or your standing " +
+            "instructions authorize self-orchestration. For any other task — even one that would clearly benefit " +
+            "from parallelism — do NOT call this tool: delegate individual sub-agents instead, or briefly describe " +
+            "what a workflow could do and ask first. A task merely LOOKING decomposable does not count.\n" +
+            "Pick the MINIMAL primitive that fits — do NOT reach for parallel by default:\n" +
+            "• agent(spec): ONE sub-agent (sequential when awaited). The DEFAULT — use it for any single coherent task. " +
+            "Both forms work: agent({ objective: '…', label: '…' }) and agent('prompt string', opts?). " +
+            "Do NOT split a task into parallel agents unless its parts are GENUINELY INDEPENDENT.\n" +
+            "• parallel(thunks): run agents concurrently with a BARRIER (await ALL). ONLY for INDEPENDENT fan-out whose " +
+            "results you need together. If the parts share state, depend on each other, or just 'feel like multiple " +
+            "things', it is NOT parallel. A flat independent fan-out IS parallel — not workflow (and if those agents " +
+            "WRITE the same repo, it is isolation, below).\n" +
+            "• pipeline(items, ...stages): each item flows through the stages on its own chain (no barrier). Use for " +
+            "per-item STAGED processing of many items (e.g. for each file: lint → test → report).\n" +
+            // PARITY-SPOT-WORKFLOW F1 (design/98 §6.3): the card previously claimed `workflow(body)` nesting and an
+            // `agentStream(spec)` handle — neither hook exists in the script isolate (WorkflowPrimitives is exactly
+            // agent/parallel/pipeline/phase/log/budget + args). A card must never promise a capability the task does
+            // not have; both claims are removed until the corresponding primitive actually ships.
+            "• agent(spec, { isolation: \"worktree\" }): run the agent in an ISOLATED git worktree. Use specifically when " +
+            "concurrent agents WRITE THE SAME FILES/REPO and must not clobber each other — even as a parallel fan-out " +
+            "(plain parallel would clobber); this takes precedence over plain parallel. A separate-working-copy need, " +
+            "NOT merely 'several agents'.\n" +
+            "• resumeFromRunId (this tool's arg): RESUME a prior/crashed run — replay its completed agents, run only new work.\n" +
+            // B5/F2 (CC card): the iterate-by-file calling surface (needs a deployment script store; the runtime
+            // error is honest when none is wired).
+            "• scriptPath / name (this tool's args): when a script store is wired, every run persists its script and " +
+            "returns its scriptPath — to iterate, EDIT that file and re-invoke with {scriptPath} instead of resending " +
+            "the full script; {name} runs a saved workflow.\n" +
+            // F9/B6: the Infinity trap (CC card + D0m teaching) — the single most common runaway-loop cause.
+            "• budget: SCALE the number/depth of agents to a token/cost CEILING — use whenever the task names a budget. " +
+            "Guard budget-driven loops on budget.total: with no budget set, budget.remaining() returns Infinity and a " +
+            "while-loop runs straight into the agent cap — add a hard iteration cap or pass a budget.\n" +
+            // Environment facts (blackboard 2026-07-03, clay dogfood: a five-round trial-and-error chain
+            // happened ONLY because the tool never stated these boundaries — say them up front):
+            "\n" +
+            "Environment facts (read before writing the script):\n" +
+            "• Sub-agents may run in an isolated working directory — when a task concerns specific files/repos, put " +
+            "ABSOLUTE paths in the agent's objective; never assume it sees your cwd.\n" +
+            "• The script itself has NO host APIs: no require/import, no process/fs/fetch, no setTimeout (schedule " +
+            "time-based work outside the workflow). Only agent/parallel/pipeline/phase/log/budget/args exist.\n" +
+            // B2/F3 (CC card :448059 verbatim, adapted list form): the determinism ban is ENFORCED (static check at
+            // submit + runtime shim), not advisory — say it before the model writes a timestamped script.
+            "• Scripts must be DETERMINISTIC: `Date.now()`/`Math.random()`/argless `new Date()` throw (they would " +
+            "break resume) — pass timestamps in via `args`, stamp results after the workflow returns, and for " +
+            "randomness vary the agent prompt/label by index.\n" +
+            // 黑板 [406]: LLMs with the CC mental model wrote bare phase() (which used to throw), then dropped
+            // phase() entirely → whole runs rendered unphased in the monitor. State BOTH forms with examples.
+            "• schema: if an agent's result is consumed by CODE or a downstream stage (a scorer, a file writer, the " +
+            "next pipeline stage, your own JSON.parse), pass opts.schema to FORCE structured output — prose transfer " +
+            "silently loses fields. Only results a human/LLM reads as narrative may omit schema.\n" +
+            "• phase (two forms, both fine): bare marker — phase('Scan'); groups every later agent() under 'Scan' " +
+            "until the next phase() call. Scoped — await phase('Fix', async () => { ...agents... }); groups just the " +
+            "body. Give each stage a phase so progress renders as stage groups.\n" +
+            "• spec.modelName works only when the deployment configured a workflow model allowlist; if unsure, omit " +
+            "modelName and the agent runs on the deployment's default role.\n" +
+            // design/116 W4: CC AgentTool/prompt.ts:94 "Don't race" verbatim (adapted fork→workflow) — guards the
+            // observed failure of narrating/fabricating a still-running workflow's results (the sema-async symptom).
+            "\n" +
+            "Don't race. After launching, you know nothing about what the workflow found. Never fabricate or predict its " +
+            "results in any format — not as prose, summary, or structured output. When a completion notifier is wired " +
+            "(the launch note will say so) END YOUR TURN and wait — the notification carries the result; poll " +
+            "TaskOutput(task_id) only when the user asks for progress. If the user asks a follow-up before it lands, " +
+            "give status, not a guess." +
+            // design/140 §6 1b: the named-workflow roster (whenToUse projection) — appended ONLY when something is
+            // registered, so a roster-less deployment's card is byte-identical to the pre-140 form.
+            (namedWorkflowSection !== undefined ? `\n\n${namedWorkflowSection}` : "") +
+            // [663]③ CC parity: the advisory size-guideline section last (CC appends Wvs to the whole card).
+            sizeGuidelineSection,
+        parameters: Type.Object({
+            // B5/F2 (CC pretty.js:449105 strictObject): `script` is now one of THREE calling surfaces —
+            // script ∨ name ∨ scriptPath (validated in execute; typebox has no refine).
+            script: Type.Optional(Type.String({
+                description: "Self-contained workflow script. Must begin with `export const meta = { name, description, phases }` " +
+                    "(pure literal, no computed values) followed by the script body using agent()/parallel()/pipeline()/phase().",
+            })),
+            name: Type.Optional(Type.String({
+                description: "Name of a predefined workflow (a saved script in the deployment's workflow store, or a built-in — " +
+                    "see the named-workflow list in this tool's description). Resolves to a self-contained script; the " +
+                    "registration's default args merge under your `args`.",
+            })),
+            scriptPath: Type.Optional(Type.String({
+                description: "Path to a workflow script file persisted by a prior invocation (each run's tool result carries its " +
+                    "scriptPath when the deployment wires a script store). To iterate, edit that file and re-invoke with the " +
+                    "same `scriptPath` instead of re-sending the full script. Takes precedence over `script` and `name`.",
+            })),
+            args: Type.Optional(Type.Unknown()),
+            resumeFromRunId: Type.Optional(Type.String({
+                description: "design/97 CORE-9: resume a PRIOR run of the SAME script — replays the longest unchanged prefix of " +
+                    "its agent results from the journal and runs only the first changed/new call + everything after live. " +
+                    "Requires a journal-backed deployment; omit for a fresh run.",
+            })),
+        }),
+        effect: "write",
+        execute: async (rawArgs, ctx) => {
+            const rawScript = rawArgs.script;
+            const rawName = rawArgs.name;
+            const rawScriptPath = rawArgs.scriptPath;
+            const scriptArgs = rawArgs.args;
+            const rawResume = rawArgs.resumeFromRunId;
+            const resumeFromRunId = typeof rawResume === "string" && rawResume.length > 0 ? rawResume : undefined;
+            const sourceTaskId = ctx.taskId ?? d.sourceTaskId;
+            const principal = ctx.principal ?? d.principal;
+            const taskScope = ctx.principal ?? d.scope;
+            // 0. B5/F2 — resolve the script from the three-way calling surface (CC refine: "Must provide script,
+            // name, or scriptPath"; scriptPath > script > name). scriptPath needs the deployment's store; name
+            // resolves deployment store FIRST (SHADOW), then the built-in registry (design/140 §6 1c).
+            let script;
+            // design/140 §6 1a — the registration's defaultArgs layer (only the `name` surface has a registry entry).
+            let registeredDefaultArgs;
+            // 团队通道 [426] CORE-1 — the registration's declared bare-string key (default "topic"): when a `{name}`
+            // call passes a raw string args AND the registry carries object defaultArgs, the string is normalized to
+            // `{ [key]: string }` BEFORE the merge, so the ergonomic "裸 string = topic" entry composes with the
+            // registered defaults instead of wiping them wholesale.
+            let registeredStringArgKey;
+            if (typeof rawScriptPath === "string" && rawScriptPath.length > 0) {
+                if (!d.scriptStore)
+                    return structuredError("scriptPath requires a deployment workflow script store — none is wired; pass `script` inline");
+                try {
+                    script = await d.scriptStore.load(rawScriptPath);
+                }
+                catch (err) {
+                    return structuredError(`failed to read workflow script at scriptPath: ${redactHostLeaks(err instanceof Error ? err.message : String(err)).slice(0, 300)}`);
+                }
+            }
+            else if (typeof rawScript === "string" && rawScript.length > 0) {
+                // Normalize a common model habit: a whole-script markdown code fence (```js … ```).
+                script = stripCodeFences(rawScript);
+            }
+            else if (typeof rawName === "string" && rawName.length > 0) {
+                if (!d.scriptStore?.resolveName && !builtinsEnabled) {
+                    return structuredError("named workflows require a deployment workflow script store — none is wired (and built-in workflows are disabled); pass `script` inline");
+                }
+                let resolved;
+                if (d.scriptStore?.resolveName) {
+                    try {
+                        resolved = await d.scriptStore.resolveName(rawName);
+                    }
+                    catch (err) {
+                        return structuredError(`failed to resolve workflow name: ${redactHostLeaks(err instanceof Error ? err.message : String(err)).slice(0, 300)}`);
+                    }
+                }
+                // Built-in fallback (design/140 §6 1c): consulted ONLY when the deployment registry does not resolve
+                // the name — a same-name deployment entry shadows the built-in; `builtinWorkflows:false` removes it.
+                if (resolved === undefined && builtinsEnabled) {
+                    resolved = resolveBuiltinWorkflow(rawName); // built-ins carry no registry defaultArgs layer
+                }
+                if (resolved === undefined)
+                    return structuredError(`unknown workflow name: ${JSON.stringify(rawName)}`);
+                script = typeof resolved === "string" ? resolved : resolved.script;
+                if (typeof resolved !== "string" && "defaultArgs" in resolved)
+                    registeredDefaultArgs = resolved.defaultArgs;
+                // [426] CORE-1: honor a registry-declared bare-string key (缺省 "topic"); only the `name` surface has
+                // a registry entry, so a `{script}`/`{scriptPath}` call never normalizes (registeredDefaultArgs stays
+                // undefined there → normalizeStringArg is a no-op regardless).
+                if (typeof resolved !== "string" && typeof resolved.stringArgKey === "string" && resolved.stringArgKey.length > 0) {
+                    registeredStringArgKey = resolved.stringArgKey;
+                }
+            }
+            else {
+                return structuredError("Must provide script, name, or scriptPath");
+            }
+            // design/140 §6 1a — the merge chain, resolved ONCE here (parse-time snapshot discipline, design/140 §2):
+            // call-time args > registered defaultArgs > script-internal fallbacks (the script's own job). The run —
+            // including a `resumeFromRunId` replay — receives the merged VALUE and never re-queries the registry;
+            // a post-launch registry change reaches only FUTURE invocations (a changed default on a resume
+            // re-invocation diverges via the journal's callKey identity, exactly like a changed script).
+            // 团队通道 [426] CORE-1 — normalization happens BEFORE the merge: a bare-string call arg + object
+            // defaultArgs would otherwise hit mergeWorkflowArgs' non-object branch and wipe the registered defaults
+            // wholesale (the published "裸 string = topic" ergonomic entry colliding with center-配的 defaults —
+            // the collab template silently degrading to generic advocate/skeptic). Normalizing the string to
+            // `{ [stringArgKey ?? "topic"]: <string> }` first lets both conventions compose; with no object
+            // defaults the string passes through untouched. The effectiveArgs snapshot below (and the value handed
+            // to the script runner) is therefore the NORMALIZED+MERGED final value.
+            const effectiveArgs = mergeWorkflowArgs(normalizeStringArg(scriptArgs, registeredDefaultArgs, registeredStringArgKey), registeredDefaultArgs);
+            // 1. size cap — fail fast before any parse.
+            if (script.length > maxScriptChars) {
+                return structuredError(`script too large: ${script.length} chars > max ${maxScriptChars}`);
+            }
+            // 2. STATIC meta validation (no eval) — early, structured feedback the model can fix. Capture the meta so
+            // the run records its name/description for the MF-W /workflows monitor header (design/99).
+            let meta;
+            try {
+                meta = parseWorkflowMeta(script);
+            }
+            catch (err) {
+                return structuredError(err instanceof Error ? err.message : String(err));
+            }
+            // 2b. SYNC precompile fail-fast (CC 198 `Ubt` parity, pretty.js:449293-449307): a BODY syntax error
+            // returns a structured error THIS turn — the model fixes it immediately — instead of surfacing only
+            // through the async completion notification (PARITY-SPOT-WORKFLOW F8/B3). Compile-only: the same
+            // wrapper shape the script runners use, built via the Function constructor and NEVER invoked, so
+            // error line offsets match the real execution and no script code runs here.
+            try {
+                const { body } = splitWorkflowMeta(script);
+                new Function(`return (async function(agent, parallel, pipeline, phase, log, budget, args) {\n${body}\n})`);
+                // 2c. STATIC determinism check (CC `wxl` → errorCode 4, pretty.js:446005/:449214, B2/F3): a clock or
+                // randomness read busts the resume prefix cache SILENTLY — teach at authoring time, this turn. The
+                // runtime shim in the runner is the backstop (strings/comments are lexed out here, so a prompt that
+                // merely mentions Date.now() does not trip).
+                if (workflowScriptReadsClockOrRandom(body)) {
+                    return structuredError("Workflow scripts must be deterministic: Date.now()/Math.random()/new Date() are unavailable (breaks resume). " +
+                        "Stamp results after the workflow returns, or pass timestamps via args.");
+                }
+            }
+            catch (err) {
+                return structuredError(`workflow script failed to compile: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            // 3. start — GOVERNED primitives + hard caps. A sync nesting throw becomes a structured error.
+            const scriptFn = (wfCtx) => {
+                // `principal` (resolved above: ctx.principal ?? d.principal) also threads into every spawned
+                // agent (fable impl-review F1 — design/62 verbatim inheritance; the notify/registry scope and
+                // the children now agree on the SAME principal, so tool-result-store scoping lines up).
+                const primitives = buildWorkflowPrimitives(wfCtx, governance, d.onAgentSpawn, d.parentThinking, principal); // CORE-9 Part B steer sink + thinking/principal inheritance
+                // Pass the WORKFLOW signal (caller + cancel + totalTimeout), not the tool-context signal, so a
+                // cancel/timeout aborts the script body itself — not just the agents it spawns (workflow review).
+                // design/140 §6 1a: the script receives the MERGED effective args (call-time > registered defaults).
+                return d.scriptRunner.run({ scriptSource: script, primitives, scriptArgs: effectiveArgs, signal: wfCtx.signal }).then((r) => r.result);
+            };
+            let handle;
+            const workflowTaskId = d.taskRegistry?.mintTaskId("workflow");
+            try {
+                handle = startWorkflow(d.runner, scriptFn, {
+                    store: d.store,
+                    // F4 agentType: thread the deployment registry into the run's spawn lanes.
+                    ...(d.agents !== undefined ? { agents: d.agents } : {}),
+                    ...(d.builtinAgents !== undefined ? { builtinAgents: d.builtinAgents } : {}),
+                    // design/99 MF-W: record the script's meta name/description on the run for the /workflows header.
+                    name: meta.name,
+                    ...(meta.description !== undefined ? { description: meta.description } : {}),
+                    // B7/F7 (CC :446478): pre-register the plan's phases as pending progress groups.
+                    ...(meta.phases !== undefined ? { phases: meta.phases } : {}),
+                    // design/140 §6 1a: snapshot the MERGED effective args onto the run (parse-time discipline,
+                    // design/140 §2 — observability/recovery read the value the script actually received; nothing
+                    // downstream ever re-queries the registry).
+                    ...(effectiveArgs !== undefined ? { effectiveArgs } : {}),
+                    // design/114 #3: thread the host task id onto the WorkflowRun (was only on the notify path) so a
+                    // crash-recovered consumer rebuilding from getWorkflowRun can re-associate the run with its initiator.
+                    ...(sourceTaskId !== undefined ? { sourceTaskId } : {}),
+                    ...(d.originatingSessionId !== undefined ? { originatingSessionId: d.originatingSessionId } : {}), // service [371]②: recovery 与 live 对称
+                    ...(workflowTaskId !== undefined ? { runId: workflowTaskId } : {}),
+                    // CORE-9 Part A: durable resume for tool-launched workflows. journalStore records; resumeFromRunId
+                    // (a tool arg) replays the prior run's unchanged prefix. startWorkflow throws (→ structured error) if
+                    // resumeFromRunId is set without a journalStore.
+                    journalStore: d.journalStore,
+                    ...(resumeFromRunId !== undefined ? { resumeFromRunId } : {}),
+                    scope: d.scope,
+                    signal: ctx.signal,
+                    budget: lim.budget,
+                    maxAgents: lim.maxAgents ?? DEFAULTS.maxAgents,
+                    totalTimeoutMs: lim.totalTimeoutMs ?? DEFAULTS.totalTimeoutMs,
+                    maxResultChars: lim.maxResultChars ?? DEFAULTS.maxResultChars,
+                    maxLogChars: lim.maxLogChars ?? DEFAULTS.maxLogChars,
+                    ...(d.parentCwd !== undefined ? { parentCwd: d.parentCwd } : {}),
+                }, { workflowDepth: d.workflowDepth });
+            }
+            catch (err) {
+                // design/98 §0.1: a workflow started INSIDE a workflow (nesting) throws here → structured error.
+                return structuredError(err instanceof Error ? err.message : String(err));
+            }
+            const runId = handle.runId;
+            // B5/F2 (CC `Pqi` :449309): persist THIS invocation's resolved script (best-effort — a store hiccup must
+            // never block the launch) and report the path so the model iterates via {scriptPath} instead of resending.
+            let persistedScriptPath;
+            if (d.scriptStore) {
+                try {
+                    persistedScriptPath = await d.scriptStore.persist(runId, script);
+                }
+                catch {
+                    /* best-effort persistence — the run itself is unaffected */
+                }
+            }
+            if (d.taskRegistry) {
+                const taskOwner = ctx.taskId ?? d.taskOwner ?? d.sourceTaskId;
+                d.taskRegistry.registerWorkflow({
+                    runId,
+                    handle,
+                    store: d.store,
+                    description: meta.name ?? meta.description,
+                    toolUseId: ctx.toolCallId,
+                    ...(taskOwner !== undefined ? { owner: taskOwner } : {}),
+                    ...(taskScope !== undefined ? { scope: taskScope } : {}),
+                    // 黑板 [405]: the originating session polled this run to TERMINAL in-band → tell the deployment
+                    // to drop the (session, runId) completion-inbox entry (durable half; the shell's same-process
+                    // seed Set is the belt). Fire-and-forget, swallow-guarded.
+                    onServedTerminal: () => {
+                        void Promise.resolve()
+                            .then(() => d.notifier?.ackServed?.({
+                            runId,
+                            ...(d.originatingSessionId !== undefined ? { originatingSessionId: d.originatingSessionId } : {}),
+                            ...(sourceTaskId !== undefined ? { sourceTaskId } : {}),
+                            ...(principal !== undefined ? { principal } : {}),
+                        }))
+                            .catch(() => { });
+                    },
+                });
+            }
+            // 4. fire-and-forget completion notify (at most once per runId; notifier errors swallowed).
+            if (d.notifier) {
+                let notified = false;
+                const fire = (notification) => {
+                    if (notified)
+                        return;
+                    notified = true;
+                    try {
+                        d.taskNotification?.(notification);
+                    }
+                    catch {
+                        /* best-effort live notification; deployment notifier below is still attempted */
+                    }
+                    // Funnel notify() THROUGH a then() so a SYNCHRONOUS throw (the seam allows `void` returns) is caught
+                    // by the `.catch` rather than escaping as an unhandled rejection (workflow review, tool-flow).
+                    void Promise.resolve()
+                        .then(() => d.notifier.notify({
+                        runId,
+                        task_id: notification.task_id,
+                        task_type: "workflow",
+                        ...(notification.toolUseId !== undefined ? { toolUseId: notification.toolUseId } : {}),
+                        sourceTaskId,
+                        ...(d.originatingSessionId !== undefined ? { originatingSessionId: d.originatingSessionId } : {}),
+                        principal,
+                        status: notification.status === "completed" ? "completed" : "failed",
+                        summary: notification.summary,
+                        ...(notification.result !== undefined ? { result: notification.result } : {}),
+                        ...(notification.usage !== undefined ? { usage: notification.usage } : {}),
+                    }))
+                        .catch(() => { });
+                };
+                handle.done
+                    .then((res) => fire({
+                    task_id: runId,
+                    task_type: "workflow",
+                    ...(ctx.toolCallId !== undefined ? { toolUseId: ctx.toolCallId } : {}),
+                    status: "completed",
+                    summary: completionSummary(meta.name, res.run),
+                    result: boundedRedactedSummary(res.result, 4000),
+                    usage: res.run.stats,
+                }), (err) => fire({
+                    task_id: runId,
+                    task_type: "workflow",
+                    ...(ctx.toolCallId !== undefined ? { toolUseId: ctx.toolCallId } : {}),
+                    status: "failed",
+                    summary: failureSummary(err),
+                }))
+                    // Belt: a throw inside either callback (e.g. summary building) must not become an unhandled rejection.
+                    .catch(() => { });
+            }
+            else {
+                let notified = false;
+                const fire = (notification) => {
+                    if (notified)
+                        return;
+                    notified = true;
+                    try {
+                        d.taskNotification?.(notification);
+                    }
+                    catch {
+                        /* best-effort live notification */
+                    }
+                };
+                handle.done
+                    .then((res) => fire({
+                    task_id: runId,
+                    task_type: "workflow",
+                    ...(ctx.toolCallId !== undefined ? { toolUseId: ctx.toolCallId } : {}),
+                    status: "completed",
+                    summary: completionSummary(meta.name, res.run),
+                    result: boundedRedactedSummary(res.result, 4000),
+                    usage: res.run.stats,
+                }), (err) => fire({
+                    task_id: runId,
+                    task_type: "workflow",
+                    ...(ctx.toolCallId !== undefined ? { toolUseId: ctx.toolCallId } : {}),
+                    status: "failed",
+                    summary: failureSummary(err),
+                }))
+                    .catch(() => { });
+            }
+            // 5. return the runId IMMEDIATELY (the workflow runs asynchronously). The `note` is HONEST about how to
+            // learn the outcome: when a task registry is wired (the Runner mount path always passes one) point at
+            // the reliable TaskOutput POLL path; the push completion-notify is a deployment-optional seam
+            // (`workflowCompletionNotifier`), so we say
+            // "may also be notified … if the deployment wires it" rather than the old unconditional over-promise (a
+            // deployment whose notify sink only logs would leave the model waiting forever — the observed sema symptom).
+            // [378] flywheel ask (monitor #5): a machine-checkable "backgrounded" marker so the shell renders
+            // the CC-shaped "Running in background · /workflows to monitor" line without parsing free text.
+            return {
+                details: { type: "workflow-run", status: "backgrounded", workflowRunId: runId },
+                content: JSON.stringify({
+                    runId,
+                    task_id: runId,
+                    status: "started",
+                    // B5/F2: where this invocation's script was persisted — edit it + re-invoke with {scriptPath} to iterate.
+                    ...(persistedScriptPath !== undefined ? { scriptPath: persistedScriptPath } : {}),
+                    // 黑板 [409]② + 复审 r2: honest note by capability tier (clay 截图: 旧文案主动教轮询 →
+                    // TaskOutput×5 连刷). The poll tool named must ACTUALLY be mounted (registry→TaskOutput, else
+                    // none — design/136 §2.3: WorkflowStatus retired; a directly-constructed SDK consumer that wants
+                    // a poll path must pass `taskRegistry`). Only a DURABLE `notifier` earns "end your turn and
+                    // wait"; a bare SDK `taskNotification` may not reach an idle session → hedge, don't over-promise.
+                    note: (() => {
+                        const pollExpr = d.taskRegistry ? `TaskOutput({ task_id: "${runId}" })` : undefined;
+                        const carries = pollExpr ? ` A terminal ${pollExpr} reply carries its result.` : "";
+                        if (d.notifier) {
+                            return `The workflow runs asynchronously. You will be NOTIFIED when it completes (the notification carries the result). End your turn and wait — do not poll unless the user asks for progress.${carries}`;
+                        }
+                        if (d.taskNotification) {
+                            return `The workflow runs asynchronously. Its completion is injected into THIS session if it is still active; if you have ended your turn and hear nothing, ${pollExpr ? `poll ${pollExpr}` : "there is no poll path wired"}.${carries}`;
+                        }
+                        return pollExpr
+                            ? `The workflow runs asynchronously and no completion notifier is wired. Poll ${pollExpr}.${carries}`
+                            : "The workflow runs asynchronously; no completion notifier is wired and no status/poll path is available.";
+                    })(),
+                }),
+            };
+        },
+    });
+}
+// design/136 §2.3 (BREAKING 去超集批): the standalone `WorkflowStatus` poll tool was retired — poll capability
+// is fully carried by `TaskOutput` (field superset via formatWorkflowRun + delimitUntrusted fencing + the
+// cross-replica `workflowStore` fallback; the legacy `runId` argument was already accepted). "WorkflowStatus"
+// remains a live alias of TaskOutput (old calls run verbatim) and an OLD_TO_NEW entry (durable-state
+// normalization). CC shape: a single Workflow tool, status via /workflows + task notifications — no status
+// query tool.
+//# sourceMappingURL=run-workflow-tool.js.map