@sema-ai/core 1.275.1

package/dist/orchestration/workflow-sandbox-conformance.js

@@ -0,0 +1,301 @@
+/**
+ * design/98 §2.3 (S8b) — the reusable CONFORMANCE CONTRACT a HARD {@link WorkflowScriptRunner}
+ * (`safeForUntrustedScripts:true`) MUST pass. Core ships the contract (zero deps beyond `node:assert`); a
+ * deployment's isolated-vm / separate-process runner imports it and runs it in its OWN test suite to prove
+ * its membrane does not leak. It runs a battery of sandbox-escape scripts against the runner and asserts each
+ * FAILS to reach a host capability (`process` / `require` / a host `Function`).
+ *
+ * The dev `vm` runner deliberately does NOT pass this (it is not a boundary) — see
+ * `test/workflow-vm-escape.test.ts`, which PROVES that and asserts `safeForUntrustedScripts === false`.
+ */
+import assert from "node:assert/strict";
+const META = "export const meta = { name: 'conformance', description: 'sandbox escape probes' }\n";
+/** Escape bodies — each tries to climb a prototype chain or reach a global to grab a host capability. A hard
+ *  runner must make every one return null/undefined (or throw): the injected primitives/args are isolate-local,
+ *  so their `.constructor.constructor` is the ISOLATE's `Function` (no host `process`/`require`). */
+const ESCAPE_BODIES = [
+    // via the injected `agent` function's constructor chain
+    `return agent.constructor.constructor("return typeof process !== 'undefined' ? process : null")()`,
+    // via the injected `log` function
+    `return log.constructor.constructor("return typeof process !== 'undefined' ? process : null")()`,
+    // via the `budget` object's prototype
+    `return budget.constructor.constructor("return typeof process !== 'undefined' ? process : null")()`,
+    // via a fresh object literal's prototype (the classic vm escape vector)
+    `return ({}).constructor.constructor("return typeof process !== 'undefined' ? process : null")()`,
+    // via the ExternalCopy'd `args` prototype
+    `return args.constructor.constructor("return typeof require !== 'undefined' ? require : null")()`,
+    // via a returned task result's prototype
+    `const r = await agent({ objective: 'x' }); return (r ?? {}).constructor.constructor("return typeof require !== 'undefined' ? require : null")()`,
+    // direct global reach
+    `return (typeof process !== 'undefined' ? process : null)`,
+    `return (typeof require !== 'undefined' ? require : null)`,
+    `return (typeof globalThis !== 'undefined' && globalThis.process) ? globalThis.process : null`,
+];
+/**
+ * Error-path probes (service [211] red-team — a vector the result-path battery alone misses). The script
+ * triggers a HOST-side error from a bridged primitive, catches it INSIDE the isolate, and climbs THAT error's
+ * constructor chain. A hard runner MUST sterilize errors crossing INTO the isolate (re-wrap rejections as
+ * isolate-side values) — otherwise the script catches a host `Error` whose `.constructor.constructor` is the
+ * HOST `Function`, reaching `process`/`require` through the failure path instead of the return path. Run
+ * against {@link throwingPrimitives}; the returned climb result is checked by {@link looksLikeHostCapability}.
+ */
+const ERROR_PATH_BODIES = [
+    `try { await agent({ objective: 'x' }); return null } catch (e) { return e.constructor.constructor("return typeof process !== 'undefined' ? process : null")() }`,
+    `try { await parallel([]); return null } catch (e) { return e.constructor.constructor("return typeof require !== 'undefined' ? require : null")() }`,
+    `try { await agent({}); return null } catch (e) { return (e && e.constructor && e.constructor.constructor) ? e.constructor.constructor("return (typeof globalThis !== 'undefined' && globalThis.process) ? globalThis.process : null")() : null }`,
+];
+/**
+ * Prototype-pollution probes (service [211] red-team — the marshalling-bridge vector). The script returns a
+ * value carrying an INJECTED own `__proto__` / `constructor` / `prototype` key (via `JSON.parse` of a crafted
+ * literal or `Reflect.defineProperty`). A hard runner MUST scrub these at the marshalling boundary — else the
+ * key survives into the host result graph and a downstream deep-merge sink writes through it to the host
+ * `Object.prototype`, polluting every tenant. We assert the MARSHALLED result graph carries no such own key
+ * (a plain JSON value never has `__proto__`/`constructor`/`prototype` as an OWN property — only inherited).
+ */
+const POLLUTION_BODIES = [
+    `return JSON.parse('{"__proto__":{"polluted":1}}')`,
+    `const o = {}; Reflect.defineProperty(o, "__proto__", { value: { polluted: 1 }, enumerable: true, configurable: true }); return o`,
+    `return { nested: JSON.parse('{"__proto__":{"polluted":1}}') }`,
+    `return { constructor: { prototype: { polluted: 1 } } }`,
+    `return [JSON.parse('{"__proto__":{"polluted":1}}')]`,
+];
+/**
+ * Signal-path probes (CORE-1~9 audit MAJOR). The production `run_workflow` tool passes a HOST `AbortSignal` to
+ * `run({ signal })`. That signal is for ABORT CONTROL — the runner must NOT hand the RAW host object to the
+ * script (a host object's `.constructor.constructor` is the HOST `Function`, a classic climb to `process`). If a
+ * runner exposes abort-awareness at all it must be an isolate-side wrapper. These probes reach for the signal
+ * under either common name (`signal` global / `input.signal`); if the runner exposes neither, the reference is
+ * undefined and the probe harmlessly returns null (PASS) — only a leaked HOST signal fails.
+ */
+const SIGNAL_BODIES = [
+    `return (typeof signal !== 'undefined' && signal) ? signal.constructor.constructor("return typeof process !== 'undefined' ? process : null")() : null`,
+    `return (typeof input !== 'undefined' && input && input.signal) ? input.signal.constructor.constructor("return typeof process !== 'undefined' ? process : null")() : null`,
+    `try { return (typeof signal !== 'undefined' && signal) ? (signal.addEventListener ? signal.addEventListener.constructor("return typeof process !== 'undefined' ? process : null")() : null) : null } catch (e) { return null }`,
+];
+function benignPrimitives() {
+    return {
+        agent: async () => ({ status: "completed", result: "ok" }),
+        parallel: async (thunks) => Promise.all(thunks.map((t) => t())),
+        pipeline: async (items) => items,
+        phase: async (_title, body) => (body === undefined ? undefined : body()), // [406] bare marker form
+        log: () => { },
+        budget: { total: null, spent: () => 0, remaining: () => Infinity },
+    };
+}
+/** Primitives whose bridged calls reject with a HOST `Error` — for the {@link ERROR_PATH_BODIES} probes. A
+ *  hard runner must sterilize this rejection before the script's `catch` sees it. */
+function throwingPrimitives() {
+    const boom = () => {
+        throw new Error("host-side primitive failure");
+    };
+    return {
+        agent: async () => boom(),
+        parallel: async () => boom(),
+        pipeline: async () => boom(),
+        phase: async () => boom(),
+        log: () => { },
+        budget: { total: null, spent: () => 0, remaining: () => Infinity },
+    };
+}
+const DANGEROUS_OWN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+/** Walk a marshalled result graph: does any node carry an INJECTED own `__proto__`/`constructor`/`prototype`
+ *  key whose value is an object? Plain JSON values never do — its presence means the runner's marshalling did
+ *  not scrub the pollution payload. Uses own-descriptor values (never the inherited slot) and guards cycles. */
+function graphHasInjectedProtoKey(v, seen = new Set()) {
+    if (v == null || typeof v !== "object")
+        return false;
+    if (seen.has(v))
+        return false;
+    seen.add(v);
+    for (const k of Object.getOwnPropertyNames(v)) {
+        if (DANGEROUS_OWN_KEYS.has(k)) {
+            const val = Object.getOwnPropertyDescriptor(v, k)?.value;
+            if (val != null && typeof val === "object")
+                return true;
+        }
+    }
+    for (const k of Object.getOwnPropertyNames(v)) {
+        if (DANGEROUS_OWN_KEYS.has(k))
+            continue;
+        if (graphHasInjectedProtoKey(v[k], seen))
+            return true;
+    }
+    return false;
+}
+/** Does `v` look like a host capability the script should never reach? A host `Function` (`require`), or an
+ *  object exposing `process`-like keys, means the membrane leaked. */
+function looksLikeHostCapability(v) {
+    if (v == null)
+        return false;
+    if (typeof v === "function")
+        return true; // reached `require` (a function) — a host capability
+    if (typeof v === "object") {
+        const o = v;
+        return "pid" in o || "env" in o || "version" in o || "mainModule" in o || "binding" in o;
+    }
+    return false;
+}
+/**
+ * Assert a HARD runner passes the sandbox-escape battery. Throws an `AssertionError` on the first escape that
+ * reaches a host capability. A probe that THROWS counts as blocked (PASS).
+ */
+/**
+ * 黑板 [427] — the PRIMITIVES-WIRING battery. The [420]①/[423] production incident was a hard runner whose
+ * injection table wired only `agent` (+ return): `phase`/`log` were silently absent in the isolate, so whole
+ * runs recorded `phases: []` with no error anywhere. Sandbox tightness alone doesn't catch that — a runner can
+ * be perfectly escape-proof AND miss half the API. This battery proves EVERY {@link WorkflowPrimitives} member
+ * is present in-isolate, callable, and actually bridged back to the HOST primitives (recorded on the host
+ * side, not just observed in-script). Run it in the same suite as the escape battery.
+ */
+export async function assertWorkflowPrimitivesWiring(runner) {
+    assert.equal(runner.safeForUntrustedScripts, true, "wiring conformance targets a HARD runner (safeForUntrustedScripts must be true)");
+    const hostSeen = { phaseCalls: [], scopedBodyRan: false, logs: [] };
+    const primitives = {
+        agent: async () => ({ status: "completed", result: "ok" }),
+        parallel: async (thunks) => Promise.all(thunks.map((t) => t())),
+        pipeline: async (items, ...stages) => {
+            let out = items;
+            for (const st of stages) {
+                out = await Promise.all(out.map((x, i) => st(x, x, i)));
+            }
+            return out;
+        },
+        phase: async (title, body) => {
+            hostSeen.phaseCalls.push({ title, hasBody: body !== undefined });
+            if (body === undefined)
+                return undefined;
+            const out = await body();
+            if (title === "wiring-scoped")
+                hostSeen.scopedBodyRan = true;
+            return out;
+        },
+        log: (message) => void hostSeen.logs.push(message),
+        budget: { total: 1000, spent: () => 25, remaining: () => 975 },
+    };
+    const scriptSource = META +
+        [
+            `const report = { typeofs: { agent: typeof agent, parallel: typeof parallel, pipeline: typeof pipeline, phase: typeof phase, log: typeof log, budgetRemaining: budget && typeof budget.remaining }, calls: {} }`,
+            `log('wiring-probe-log')`,
+            `report.calls.bareUndefined = (await phase('wiring-marker')) === undefined`,
+            `let scopedRan = false`,
+            `await phase('wiring-scoped', async () => { scopedRan = true })`,
+            `report.calls.scopedRan = scopedRan`,
+            `report.calls.budgetRemaining = budget.remaining()`,
+            `const par = await parallel([async () => 1, async () => 2])`,
+            `report.calls.parallelOk = Array.isArray(par) && par.length === 2`,
+            `const pipe = await pipeline([1, 2], async (x) => x)`,
+            `report.calls.pipelineOk = Array.isArray(pipe) && pipe.length === 2`,
+            `const a = await agent({ objective: 'wiring' })`,
+            `report.calls.agentOk = a && a.status === 'completed'`,
+            `return report`,
+        ].join("\n");
+    const out = await runner.run({ scriptSource, primitives, scriptArgs: {} });
+    const report = out.result;
+    assert.ok(report && report.typeofs && report.calls, "wiring probe returned no report — script body did not run");
+    // In-isolate presence: every primitive must be a function (budget.remaining included).
+    for (const k of ["agent", "parallel", "pipeline", "phase", "log", "budgetRemaining"]) {
+        assert.equal(report.typeofs[k], "function", `primitive "${k}" is not a function INSIDE the isolate — injection table incomplete (the [423] failure mode)`);
+    }
+    // In-isolate behaviour observed by the script.
+    assert.equal(report.calls.bareUndefined, true, "bare phase(title) must return undefined in-isolate");
+    assert.equal(report.calls.scopedRan, true, "scoped phase body did not run in-isolate");
+    assert.equal(report.calls.budgetRemaining, 975, "budget.remaining() is not bridged to the live host accessor");
+    assert.equal(report.calls.parallelOk, true, "parallel() thunks not executed");
+    assert.equal(report.calls.pipelineOk, true, "pipeline() stages not executed");
+    assert.equal(report.calls.agentOk, true, "agent() result not bridged back");
+    // HOST-side receipts: the bridge must actually reach the host primitives (a stubbed isolate-local fake
+    // would pass the in-isolate checks — these prove the crossing).
+    assert.deepEqual(hostSeen.phaseCalls.map((c) => `${c.title}:${c.hasBody ? "scoped" : "bare"}`), ["wiring-marker:bare", "wiring-scoped:scoped"], "phase() calls did not reach the HOST primitive (bridge severed — phases would record [])");
+    assert.equal(hostSeen.scopedBodyRan, true, "the scoped body's completion did not round-trip through the host phase()");
+    assert.deepEqual(hostSeen.logs, ["wiring-probe-log"], "log() did not reach the HOST primitive");
+}
+export async function assertWorkflowSandboxConformance(runner) {
+    assert.equal(runner.safeForUntrustedScripts, true, "conformance is only meaningful for a HARD runner (safeForUntrustedScripts must be true)");
+    for (const escBody of ESCAPE_BODIES) {
+        const scriptSource = META + escBody;
+        let result;
+        try {
+            const out = await runner.run({ scriptSource, primitives: benignPrimitives(), scriptArgs: { probe: true } });
+            result = out.result;
+        }
+        catch {
+            continue; // a throw = the escape was blocked → PASS for this probe
+        }
+        assert.equal(looksLikeHostCapability(result), false, `sandbox escape REACHED a host capability via: ${escBody}`);
+    }
+    // Error-path probes (service [211]): a host-side primitive rejection, caught inside the isolate, must not
+    // expose a host capability through the caught error's constructor chain.
+    for (const errBody of ERROR_PATH_BODIES) {
+        const scriptSource = META + errBody;
+        let result;
+        try {
+            const out = await runner.run({ scriptSource, primitives: throwingPrimitives(), scriptArgs: { probe: true } });
+            result = out.result;
+        }
+        catch {
+            continue; // the runner re-threw without surfacing a climbable host error → PASS for this probe
+        }
+        assert.equal(looksLikeHostCapability(result), false, `error-path: a host-side primitive error leaked a host capability via: ${errBody}`);
+    }
+    // Prototype-pollution probes (service [211]): an injected __proto__/constructor/prototype own key must be
+    // scrubbed at the marshalling boundary, so a downstream host deep-merge can't pollute Object.prototype.
+    for (const polBody of POLLUTION_BODIES) {
+        const scriptSource = META + polBody;
+        let result;
+        try {
+            const out = await runner.run({ scriptSource, primitives: benignPrimitives(), scriptArgs: { probe: true } });
+            result = out.result;
+        }
+        catch {
+            continue; // a throw = the pollution attempt was blocked → PASS for this probe
+        }
+        assert.equal(graphHasInjectedProtoKey(result), false, `prototype pollution: the marshalled result carries an injected __proto__/constructor/prototype own key via: ${polBody}`);
+    }
+    // Signal-path probes (CORE-1~9 audit MAJOR): supply a HOST AbortSignal the way the production tool does, and
+    // assert the script cannot climb it to a host capability. A runner that exposes the raw host signal fails here.
+    const hostSignal = new AbortController().signal;
+    for (const sigBody of SIGNAL_BODIES) {
+        const scriptSource = META + sigBody;
+        let result;
+        try {
+            const out = await runner.run({ scriptSource, primitives: benignPrimitives(), scriptArgs: { probe: true }, signal: hostSignal });
+            result = out.result;
+        }
+        catch {
+            continue; // a throw = the climb was blocked (or signal not exposed) → PASS for this probe
+        }
+        assert.equal(looksLikeHostCapability(result), false, `signal-path: the host AbortSignal leaked a host capability via: ${sigBody}`);
+    }
+}
+/** B2/F3: each body must throw in a conformant runner (or return the literal "threw" from its own catch). */
+const DETERMINISM_FORBIDDEN_BODIES = [
+    `try { return Date.now() } catch { return "threw" }`,
+    `try { return Math.random() } catch { return "threw" }`,
+    `try { return new Date().getTime() } catch { return "threw" }`,
+    `try { return new Date(0).constructor.now() } catch { return "threw" }`, // the .constructor backdoor must be closed
+];
+/**
+ * PARITY-SPOT-WORKFLOW B2/F3 (CC `S0m` parity) — assert a runner ENFORCES determinism: Date.now() /
+ * Math.random() / argless new Date() throw (a clock/randomness read silently busts the resume prefix cache),
+ * while DATED construction (`new Date(0)`) stays available. SEPARATE from the sandbox/wiring batteries — those
+ * accept a minimal stub runner (they test the assertion's own leak/bridge logic); determinism requires a
+ * runner that actually executes the body against shimmed intrinsics (the dev vm runner + any hard runner).
+ */
+export async function assertWorkflowDeterminism(runner) {
+    for (const detBody of DETERMINISM_FORBIDDEN_BODIES) {
+        const scriptSource = META + detBody;
+        let threw = false;
+        let result;
+        try {
+            const out = await runner.run({ scriptSource, primitives: benignPrimitives(), scriptArgs: { probe: true } });
+            result = out.result;
+        }
+        catch {
+            threw = true; // the forbidden read threw → PASS
+        }
+        assert.equal(threw || result === "threw", true, `determinism: ${detBody.trim().split("\n")[0]} did NOT throw — a clock/randomness read would silently bust resume`);
+    }
+    const out = await runner.run({ scriptSource: META + `return new Date(0).getTime()`, primitives: benignPrimitives(), scriptArgs: { probe: true } });
+    assert.equal(out.result, 0, "determinism: DATED construction new Date(0) must stay available");
+}
+//# sourceMappingURL=workflow-sandbox-conformance.js.map

package/dist/orchestration/workflow-sandbox-conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-sandbox-conformance.js","sourceRoot":"","sources":["../../src/orchestration/workflow-sandbox-conformance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,MAAM,MAAM,oBAAoB,CAAC;AAGxC,MAAM,IAAI,GAAG,qFAAqF,CAAC;AAEnG;;qGAEqG;AACrG,MAAM,aAAa,GAAa;IAC9B,wDAAwD;IACxD,kGAAkG;IAClG,kCAAkC;IAClC,gGAAgG;IAChG,sCAAsC;IACtC,mGAAmG;IACnG,wEAAwE;IACxE,iGAAiG;IACjG,0CAA0C;IAC1C,iGAAiG;IACjG,yCAAyC;IACzC,iJAAiJ;IACjJ,sBAAsB;IACtB,0DAA0D;IAC1D,0DAA0D;IAC1D,8FAA8F;CAC/F,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,iBAAiB,GAAa;IAClC,iKAAiK;IACjK,oJAAoJ;IACpJ,kPAAkP;CACnP,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,gBAAgB,GAAa;IACjC,mDAAmD;IACnD,kIAAkI;IAClI,+DAA+D;IAC/D,wDAAwD;IACxD,qDAAqD;CACtD,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,aAAa,GAAa;IAC9B,sJAAsJ;IACtJ,0KAA0K;IAC1K,gOAAgO;CACjO,CAAC;AAEF,SAAS,gBAAgB;IACvB,OAAO;QACL,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;QAC1D,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAE,MAAwC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QAClG,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK;QAChC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAE,IAA+B,EAAE,CAAC,EAAE,yBAAyB;QAC/H,GAAG,EAAE,GAAG,EAAE,GAAE,CAAC;QACb,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,QAAQ,EAAE;KACnE,CAAC;AACJ,CAAC;AAED;qFACqF;AACrF,SAAS,kBAAkB;IACzB,MAAM,IAAI,GAAG,GAAU,EAAE;QACvB,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACjD,CAAC,CAAC;IACF,OAAO;QACL,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,IAAI,EAAE;QACzB,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAC,IAAI,EAAE;QAC5B,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAC,IAAI,EAAE;QAC5B,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,IAAI,EAAE;QACzB,GAAG,EAAE,GAAG,EAAE,GAAE,CAAC;QACb,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,QAAQ,EAAE;KACnE,CAAC;AACJ,CAAC;AAED,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,aAAa,EAAE,WAAW,CAAC,CAAC,CAAC;AAE9E;;gHAEgH;AAChH,SAAS,wBAAwB,CAAC,CAAU,EAAE,OAAO,IAAI,GAAG,EAAW;IACrE,IAAI,CAAC,IAAI,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACrD,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9B,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACZ,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,IAAI,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9B,MAAM,GAAG,GAAG,MAAM,CAAC,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC;YACzD,IAAI,GAAG,IAAI,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;QAC1D,CAAC;IACH,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,IAAI,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,SAAS;QACxC,IAAI,wBAAwB,CAAE,CAA6B,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;IACrF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;sEACsE;AACtE,SAAS,uBAAuB,CAAC,CAAU;IACzC,IAAI,CAAC,IAAI,IAAI;QAAE,OAAO,KAAK,CAAC;IAC5B,IAAI,OAAO,CAAC,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC,CAAC,qDAAqD;IAC/F,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC1B,MAAM,CAAC,GAAG,CAA4B,CAAC;QACvC,OAAO,KAAK,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,SAAS,IAAI,CAAC,IAAI,YAAY,IAAI,CAAC,IAAI,SAAS,IAAI,CAAC,CAAC;IAC3F,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,8BAA8B,CAAC,MAA4B;IAC/E,MAAM,CAAC,KAAK,CACV,MAAM,CAAC,uBAAuB,EAC9B,IAAI,EACJ,iFAAiF,CAClF,CAAC;IACF,MAAM,QAAQ,GAAG,EAAE,UAAU,EAAE,EAAgD,EAAE,aAAa,EAAE,KAAK,EAAE,IAAI,EAAE,EAAc,EAAE,CAAC;IAC9H,MAAM,UAAU,GAAuB;QACrC,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;QAC1D,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAE,MAAwC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QAClG,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,MAAM,EAAE,EAAE;YACnC,IAAI,GAAG,GAAG,KAAkB,CAAC;YAC7B,KAAK,MAAM,EAAE,IAAI,MAA2E,EAAE,CAAC;gBAC7F,GAAG,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YAC1D,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC;QACD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YAC3B,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,KAAK,SAAS,EAAE,CAAC,CAAC;YACjE,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YACzC,MAAM,GAAG,GAAG,MAAO,IAA+B,EAAE,CAAC;YACrD,IAAI,KAAK,KAAK,eAAe;gBAAE,QAAQ,CAAC,aAAa,GAAG,IAAI,CAAC;YAC7D,OAAO,GAAG,CAAC;QACb,CAAC;QACD,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;QAClD,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE;KAC/D,CAAC;IACF,MAAM,YAAY,GAChB,IAAI;QACJ;YACE,gNAAgN;YAChN,yBAAyB;YACzB,2EAA2E;YAC3E,uBAAuB;YACvB,gEAAgE;YAChE,oCAAoC;YACpC,mDAAmD;YACnD,4DAA4D;YAC5D,kEAAkE;YAClE,qDAAqD;YACrD,oEAAoE;YACpE,gDAAgD;YAChD,sDAAsD;YACtD,eAAe;SAChB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC;IAC3E,MAAM,MAAM,GAAG,GAAG,CAAC,MAGlB,CAAC;IACF,MAAM,CAAC,EAAE,CAAC,MAAM,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,KAAK,EAAE,2DAA2D,CAAC,CAAC;IACjH,uFAAuF;IACvF,KAAK,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,iBAAiB,CAAC,EAAE,CAAC;QACrF,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,cAAc,CAAC,8FAA8F,CAAC,CAAC;IAC7J,CAAC;IACD,+CAA+C;IAC/C,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,EAAE,IAAI,EAAE,oDAAoD,CAAC,CAAC;IACrG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,0CAA0C,CAAC,CAAC;IACvF,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,EAAE,GAAG,EAAE,6DAA6D,CAAC,CAAC;IAC/G,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,EAAE,IAAI,EAAE,gCAAgC,CAAC,CAAC;IAC9E,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,EAAE,IAAI,EAAE,gCAAgC,CAAC,CAAC;IAC9E,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,iCAAiC,CAAC,CAAC;IAC5E,uGAAuG;IACvG,gEAAgE;IAChE,MAAM,CAAC,SAAS,CACd,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,EAC7E,CAAC,oBAAoB,EAAE,sBAAsB,CAAC,EAC9C,0FAA0F,CAC3F,CAAC;IACF,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,aAAa,EAAE,IAAI,EAAE,0EAA0E,CAAC,CAAC;IACvH,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,kBAAkB,CAAC,EAAE,wCAAwC,CAAC,CAAC;AAClG,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gCAAgC,CAAC,MAA4B;IACjF,MAAM,CAAC,KAAK,CACV,MAAM,CAAC,uBAAuB,EAC9B,IAAI,EACJ,yFAAyF,CAC1F,CAAC;IACF,KAAK,MAAM,OAAO,IAAI,aAAa,EAAE,CAAC;QACpC,MAAM,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC;QACpC,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,EAAE,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;YAC5G,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;QACtB,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,CAAC,yDAAyD;QACrE,CAAC;QACD,MAAM,CAAC,KAAK,CAAC,uBAAuB,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,iDAAiD,OAAO,EAAE,CAAC,CAAC;IACnH,CAAC;IAED,0GAA0G;IAC1G,yEAAyE;IACzE,KAAK,MAAM,OAAO,IAAI,iBAAiB,EAAE,CAAC;QACxC,MAAM,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC;QACpC,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,EAAE,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;YAC9G,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;QACtB,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,CAAC,qFAAqF;QACjG,CAAC;QACD,MAAM,CAAC,KAAK,CAAC,uBAAuB,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,yEAAyE,OAAO,EAAE,CAAC,CAAC;IAC3I,CAAC;IAED,0GAA0G;IAC1G,wGAAwG;IACxG,KAAK,MAAM,OAAO,IAAI,gBAAgB,EAAE,CAAC;QACvC,MAAM,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC;QACpC,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,EAAE,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;YAC5G,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;QACtB,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,CAAC,oEAAoE;QAChF,CAAC;QACD,MAAM,CAAC,KAAK,CACV,wBAAwB,CAAC,MAAM,CAAC,EAChC,KAAK,EACL,+GAA+G,OAAO,EAAE,CACzH,CAAC;IACJ,CAAC;IAED,6GAA6G;IAC7G,gHAAgH;IAChH,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC,MAAM,CAAC;IAChD,KAAK,MAAM,OAAO,IAAI,aAAa,EAAE,CAAC;QACpC,MAAM,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC;QACpC,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,EAAE,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;YAChI,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;QACtB,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,CAAC,gFAAgF;QAC5F,CAAC;QACD,MAAM,CAAC,KAAK,CAAC,uBAAuB,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,mEAAmE,OAAO,EAAE,CAAC,CAAC;IACrI,CAAC;AACH,CAAC;AAED,6GAA6G;AAC7G,MAAM,4BAA4B,GAAG;IACnC,oDAAoD;IACpD,uDAAuD;IACvD,8DAA8D;IAC9D,uEAAuE,EAAE,2CAA2C;CACrH,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,MAA4B;IAC1E,KAAK,MAAM,OAAO,IAAI,4BAA4B,EAAE,CAAC;QACnD,MAAM,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC;QACpC,IAAI,KAAK,GAAG,KAAK,CAAC;QAClB,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,EAAE,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;YAC5G,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;QACtB,CAAC;QAAC,MAAM,CAAC;YACP,KAAK,GAAG,IAAI,CAAC,CAAC,kCAAkC;QAClD,CAAC;QACD,MAAM,CAAC,KAAK,CAAC,KAAK,IAAI,MAAM,KAAK,OAAO,EAAE,IAAI,EAAE,gBAAgB,OAAO,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,qEAAqE,CAAC,CAAC;IACtK,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,EAAE,YAAY,EAAE,IAAI,GAAG,8BAA8B,EAAE,UAAU,EAAE,gBAAgB,EAAE,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;IACnJ,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,iEAAiE,CAAC,CAAC;AACjG,CAAC"}

package/dist/orchestration/workflow-script-runner.d.ts

@@ -0,0 +1,127 @@
+import type { RunnerDeps, TaskSpec } from "../core/types.js";
+/**
+ * design/98 §1.2 / §C — is LLM self-orchestration ACTIVE for this task? `true` ONLY when the task opted in
+ * AND the deployment provides BOTH a hard sandbox (`workflowScriptRunner.safeForUntrustedScripts`) AND a
+ * governance baseline (`workflowGovernanceBaseline`). This is the SINGLE gate that drives BOTH the
+ * orchestration-prompt injection (S8a) and the `run_workflow` tool mount (S8c) — kept in lockstep so the
+ * prompt never claims a capability the task lacks (§6.3). FAIL-CLOSED: any missing piece ⇒ off.
+ */
+export declare function isSelfOrchestrationActive(spec: TaskSpec, deps: RunnerDeps): boolean;
+/**
+ * design/98 §C — the DEPLOYMENT-level capability: does this deployment SUPPORT self-orchestration / workflows
+ * AT ALL? `true` ⟺ it provides BOTH a hard sandbox (`workflowScriptRunner.safeForUntrustedScripts`) AND a
+ * governance baseline (`workflowGovernanceBaseline`). This is the deps half of {@link isSelfOrchestrationActive}
+ * with NO per-task `selfOrchestration` opt-in — the canonical predicate a control plane projects onto a
+ * capability surface (e.g. service `GET /v1/capabilities`.`workflows`) so a shell can HONESTLY gate `/workflows`
+ * + ultracode affordances: dark when `false` (the deployment can never run a workflow), available when `true`.
+ *
+ * SINGLE SOURCE so the surfaced capability can never drift from the gate that actually mounts `run_workflow`
+ * (a shell that shows `/workflows` as available while the engine fail-closes the tool = the exact mismatch
+ * design/98 §6.3 forbids). Per-principal/tier gating does NOT exist today — this is deployment-wide.
+ */
+export declare function workflowsCapability(deps: RunnerDeps): boolean;
+/**
+ * design/98 §1.2 — the task OPTED IN (`selfOrchestration:true`) but the deployment did not meet the bar (a
+ * hard sandbox + a governance baseline), so self-orchestration is FAIL-CLOSED. Returns a human-readable
+ * reason for an operator warning, or `null` when not in this state (off, or fully active). The runner emits
+ * ONE operator-visible warning so a misconfigured opt-in is never silent.
+ */
+export declare function selfOrchestrationFailClosedReason(spec: TaskSpec, deps: RunnerDeps): string | null;
+/**
+ * design/98 §D.3/§E.1 — the `WorkflowScriptRunner` SEAM for running an LLM-AUTHORED workflow script
+ * (S8 self-orchestration). A deployment provides the runner; **core does NOT ship a hard sandbox** (the
+ * isolated-vm / separate-process implementation is a deployment concern or a separate
+ * `@ai-only/workflow-sandbox` package). Core defines this contract + a TRUSTED-DEV vm runner
+ * ({@link import("./dev-vm-script-runner.js").devWorkflowScriptRunner}, S8b) that is explicitly NOT a
+ * security boundary, plus a conformance contract a hard runner must pass.
+ *
+ * 🔴 **Membrane = STRUCTURAL constraint, not a behavioral promise (codex v3/v4 BLOCKER).** The seam's
+ * `run()` accepts ONLY {@link WorkflowPrimitives} — a flat, sterile record of bound callbacks + a budget
+ * DATA snapshot. It does NOT accept a `WorkflowRunContext` (a host object whose prototype chain the script
+ * could walk via `ctx.constructor.constructor("return process")()` to escape). The engine extracts the bound
+ * functions FROM the context and constructs the primitives; the host context object structurally never
+ * enters the runner — there is no prototype chain into the host reachable from the script. A hard runner
+ * bridges each primitive as an isolated-vm `Reference`/`Callback` and copies `scriptArgs` via `ExternalCopy`.
+ */
+/** The `export const meta = {...}` a workflow script declares (a PURE literal — parsed by the meta-AST,
+ *  never `eval`'d; design/98 §2.4). Only `name`/`description` are required; the rest is observability. */
+export interface WorkflowMeta {
+    name: string;
+    description: string;
+    /** PARITY-SPOT-WORKFLOW B7 (CC card pretty.js:448042): `model` on a phase entry documents that phase's
+     *  model override — parsed + stored + displayed on the pre-registered run phase (no behavior yet). */
+    phases?: Array<{
+        title: string;
+        detail?: string;
+        model?: string;
+    }>;
+    whenToUse?: string;
+}
+/**
+ * The FLAT, STERILE primitives a workflow script may call — bound functions + a budget DATA snapshot, and
+ * NOTHING else from the host (design/98 §2.1). NO `ctx` object, NO host prototype chain. The HARD runner
+ * bridges each function as an isolated-vm `Reference`/`Callback` (the script `await`s them, round-tripping
+ * back to the main isolate where the real {@link import("./workflow.js").WorkflowRunContext} executes them).
+ *
+ * The `spec`/`opts`/stage/thunk shapes are `unknown` at this boundary on purpose: an LLM-authored `spec` is
+ * UNTRUSTED input that the engine's `agent` primitive validates + governs (whitelist construction +
+ * `tightenTaskSpec`, design/98 §2.5) BEFORE it ever reaches `runner.runTask`. The seam must not promise a
+ * trusted `TaskSpec` here.
+ */
+export interface WorkflowPrimitives {
+    /** Spawn one governed sub-agent. `spec` is an UNTRUSTED `WorkflowAgentSpec` (whitelist-constructed by the
+     *  engine, design/98 §2.5); `opts` carries `label`/`phase`/`schema`. Resolves to the task result. */
+    agent(spec: unknown, opts?: unknown): Promise<unknown>;
+    /** Run thunks concurrently (BARRIER); a thrown thunk resolves to `null`. */
+    parallel(thunks: unknown[]): Promise<unknown[]>;
+    /** Run each item through all stages independently (no barrier between stages). */
+    pipeline(items: unknown[], ...stages: unknown[]): Promise<unknown[]>;
+    /** Group work under a named phase (observability). */
+    phase(title: string, body: unknown): Promise<unknown>;
+    /** Emit a narrator log line. */
+    log(message: string): void;
+    /** LIVE budget accessors, mirroring {@link import("./workflow.js").WorkflowBudget} (NOT a one-shot data
+     *  snapshot — a static snapshot would break the `while (budget.remaining() > N)` budget-scaled-depth loop
+     *  the orchestration guidance promotes). `total` is a stable number/null; `spent()`/`remaining()` are bound
+     *  functions the hard runner bridges (an isolated-vm `Reference`/`Callback`, like the other primitives) so
+     *  each call re-reads the current spend. */
+    budget: {
+        total: number | null;
+        spent(): number;
+        remaining(): number;
+    };
+}
+/**
+ * The seam a deployment implements to execute an LLM-authored workflow script. The engine calls `run()` with
+ * the sterile {@link WorkflowPrimitives} + the script source + (copied) args; the runner compiles/executes
+ * the script in its isolation domain and returns the script's value + parsed {@link WorkflowMeta}.
+ */
+export interface WorkflowScriptRunner {
+    /**
+     * Whether this runner can SAFELY execute UNTRUSTED (LLM-authored) scripts. `true` = a hard sandbox
+     * (isolated-vm / separate process + container/seccomp). `false` = trusted-DEV authors only (the Node `vm`
+     * runner — NOT a security boundary, see {@link import("./dev-vm-script-runner.js").devWorkflowScriptRunner}).
+     *
+     * 🔴 The S8 gate (design/98 §C / §1.2) mounts the `run_workflow` tool + injects the orchestration prompt
+     * ONLY when this is `true`. `selfOrchestration:true` with no hard runner ⇒ FAIL-CLOSED (tool not mounted,
+     * prompt not injected, operator warning). Core NEVER runs an LLM script in the dev `vm`.
+     */
+    readonly safeForUntrustedScripts: boolean;
+    run(input: {
+        scriptSource: string;
+        primitives: WorkflowPrimitives;
+        scriptArgs: unknown;
+        /**
+         * A HOST `AbortSignal` for ABORT CONTROL (the workflow aborting cancels the script run). 🔐 The runner MUST
+         * NOT expose this raw host object to the untrusted script — a host object's `.constructor.constructor` climbs
+         * to the host `Function`/`process`. Use it to abort isolate execution; if you surface abort-awareness to the
+         * script at all, wrap it isolate-side. {@link assertWorkflowSandboxConformance} supplies a host signal and
+         * probes for this leak (CORE-1~9 audit MAJOR).
+         */
+        signal?: AbortSignal;
+    }): Promise<{
+        result: unknown;
+        meta: WorkflowMeta;
+    }>;
+}
+//# sourceMappingURL=workflow-script-runner.d.ts.map

package/dist/orchestration/workflow-script-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-script-runner.d.ts","sourceRoot":"","sources":["../../src/orchestration/workflow-script-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE7D;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAEnF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAK7D;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAcjG;AAED;;;;;;;;;;;;;;;GAeG;AAEH;0GAC0G;AAC1G,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB;0GACsG;IACtG,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IACjC;yGACqG;IACrG,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvD,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAChD,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IACrE,sDAAsD;IACtD,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtD,gCAAgC;IAChC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;;;gDAI4C;IAC5C,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,IAAI,MAAM,CAAC;QAAC,SAAS,IAAI,MAAM,CAAA;KAAE,CAAC;CACxE;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;OAQG;IACH,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;IAC1C,GAAG,CAAC,KAAK,EAAE;QACT,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,kBAAkB,CAAC;QAC/B,UAAU,EAAE,OAAO,CAAC;QACpB;;;;;;WAMG;QACH,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,YAAY,CAAA;KAAE,CAAC,CAAC;CACtD"}

package/dist/orchestration/workflow-script-runner.js

@@ -0,0 +1,48 @@
+/**
+ * design/98 §1.2 / §C — is LLM self-orchestration ACTIVE for this task? `true` ONLY when the task opted in
+ * AND the deployment provides BOTH a hard sandbox (`workflowScriptRunner.safeForUntrustedScripts`) AND a
+ * governance baseline (`workflowGovernanceBaseline`). This is the SINGLE gate that drives BOTH the
+ * orchestration-prompt injection (S8a) and the `run_workflow` tool mount (S8c) — kept in lockstep so the
+ * prompt never claims a capability the task lacks (§6.3). FAIL-CLOSED: any missing piece ⇒ off.
+ */
+export function isSelfOrchestrationActive(spec, deps) {
+    return spec.selfOrchestration === true && workflowsCapability(deps);
+}
+/**
+ * design/98 §C — the DEPLOYMENT-level capability: does this deployment SUPPORT self-orchestration / workflows
+ * AT ALL? `true` ⟺ it provides BOTH a hard sandbox (`workflowScriptRunner.safeForUntrustedScripts`) AND a
+ * governance baseline (`workflowGovernanceBaseline`). This is the deps half of {@link isSelfOrchestrationActive}
+ * with NO per-task `selfOrchestration` opt-in — the canonical predicate a control plane projects onto a
+ * capability surface (e.g. service `GET /v1/capabilities`.`workflows`) so a shell can HONESTLY gate `/workflows`
+ * + ultracode affordances: dark when `false` (the deployment can never run a workflow), available when `true`.
+ *
+ * SINGLE SOURCE so the surfaced capability can never drift from the gate that actually mounts `run_workflow`
+ * (a shell that shows `/workflows` as available while the engine fail-closes the tool = the exact mismatch
+ * design/98 §6.3 forbids). Per-principal/tier gating does NOT exist today — this is deployment-wide.
+ */
+export function workflowsCapability(deps) {
+    return (deps.workflowScriptRunner?.safeForUntrustedScripts === true &&
+        deps.workflowGovernanceBaseline !== undefined);
+}
+/**
+ * design/98 §1.2 — the task OPTED IN (`selfOrchestration:true`) but the deployment did not meet the bar (a
+ * hard sandbox + a governance baseline), so self-orchestration is FAIL-CLOSED. Returns a human-readable
+ * reason for an operator warning, or `null` when not in this state (off, or fully active). The runner emits
+ * ONE operator-visible warning so a misconfigured opt-in is never silent.
+ */
+export function selfOrchestrationFailClosedReason(spec, deps) {
+    if (spec.selfOrchestration !== true)
+        return null;
+    if (isSelfOrchestrationActive(spec, deps))
+        return null;
+    const missing = [];
+    if (deps.workflowScriptRunner?.safeForUntrustedScripts !== true) {
+        missing.push("a hard WorkflowScriptRunner (RunnerDeps.workflowScriptRunner.safeForUntrustedScripts === true)");
+    }
+    if (deps.workflowGovernanceBaseline === undefined) {
+        missing.push("a governance baseline (RunnerDeps.workflowGovernanceBaseline)");
+    }
+    return (`self-orchestration (TaskSpec.selfOrchestration) requires ${missing.join(" and ")}; it is DISABLED for ` +
+        `this task (fail-closed — the run_workflow tool is not mounted and the orchestration prompt is not injected).`);
+}
+//# sourceMappingURL=workflow-script-runner.js.map

package/dist/orchestration/workflow-script-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-script-runner.js","sourceRoot":"","sources":["../../src/orchestration/workflow-script-runner.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAAc,EAAE,IAAgB;IACxE,OAAO,IAAI,CAAC,iBAAiB,KAAK,IAAI,IAAI,mBAAmB,CAAC,IAAI,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAgB;IAClD,OAAO,CACL,IAAI,CAAC,oBAAoB,EAAE,uBAAuB,KAAK,IAAI;QAC3D,IAAI,CAAC,0BAA0B,KAAK,SAAS,CAC9C,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iCAAiC,CAAC,IAAc,EAAE,IAAgB;IAChF,IAAI,IAAI,CAAC,iBAAiB,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACjD,IAAI,yBAAyB,CAAC,IAAI,EAAE,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACvD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,IAAI,CAAC,oBAAoB,EAAE,uBAAuB,KAAK,IAAI,EAAE,CAAC;QAChE,OAAO,CAAC,IAAI,CAAC,gGAAgG,CAAC,CAAC;IACjH,CAAC;IACD,IAAI,IAAI,CAAC,0BAA0B,KAAK,SAAS,EAAE,CAAC;QAClD,OAAO,CAAC,IAAI,CAAC,+DAA+D,CAAC,CAAC;IAChF,CAAC;IACD,OAAO,CACL,4DAA4D,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,uBAAuB;QACxG,8GAA8G,CAC/G,CAAC;AACJ,CAAC"}

package/dist/orchestration/workflow-script-store.d.ts

@@ -0,0 +1,99 @@
+/**
+ * PARITY-SPOT-WORKFLOW B5/F2 (CC pretty.js:449105-449141 + `Pqi` :149631) — the script-persistence seam behind
+ * the Workflow tool's `scriptPath`/`name` calling surface. CC persists EVERY invocation's script under the
+ * session directory and returns the path in the tool result, so the model iterates by EDITING THE FILE and
+ * re-invoking with `{scriptPath}` instead of resending the whole script; `{name}` resolves a saved workflow.
+ *
+ * Core is deployment-neutral: the tool takes this seam via `RunWorkflowToolDeps.scriptStore` (optional — when
+ * absent, `scriptPath`/`name` calls get an honest structured error and inline `script` works as before). The
+ * file-backed implementation below is the TOC default (mirrors CC's session-dir posture: dir 0o700 / file
+ * 0o600, best-effort persist that never blocks a launch).
+ */
+/**
+ * design/140 §6 1a — a named-registry entry's RESOLVED form: the script source plus the registration's
+ * `defaultArgs` layer (the middle tier of the merge chain: call-time args > registered defaultArgs >
+ * script-internal fallbacks). A registry that carries no defaults may keep returning a bare string.
+ */
+export interface NamedWorkflowResolution {
+    script: string;
+    /** Registration-time default args (a JSON value — this is where a control-plane/center下发的默认 lands).
+     *  Merged UNDER the call-time args by {@link mergeWorkflowArgs} at tool-resolve time (parse-time snapshot:
+     *  the run receives the merged VALUE; nothing re-queries the registry after launch). */
+    defaultArgs?: unknown;
+    /**
+     * 团队通道 [426] CORE-1 — the top-level key a BARE STRING call-time arg normalizes into, so the "裸 string =
+     * <key>" ergonomic entry (published by the built-in `team-discussion` script: a bare string args IS the
+     * topic) composes with a registered object `defaultArgs` instead of colliding with it. When a `{name}` call
+     * passes a raw string AND this resolution carries an object `defaultArgs`, the tool wraps the string as
+     * `{ [stringArgKey]: <string> }` BEFORE the object merge (see {@link normalizeStringArg} / the run-workflow
+     * tool's resolve path). Defaults to `"topic"` (the built-in ergonomic contract). Ignored when `defaultArgs`
+     * is not a plain object (a bare string then reaches the script verbatim — pre-[426] behavior preserved). */
+    stringArgKey?: string;
+}
+/**
+ * design/140 §6 1b — one row of the named-workflow LISTING projection (the LLM-facing consumption face of
+ * `meta.whenToUse`). Mirrors the agents-side roster entry (subagent.ts `agentWhenToUseText`/CC `tIl`):
+ * `whenToUse` is shown when present, else `description`.
+ */
+export interface NamedWorkflowListing {
+    name: string;
+    description?: string;
+    whenToUse?: string;
+}
+export interface WorkflowScriptStore {
+    /** Persist THIS invocation's resolved script, keyed by its runId. Returns the persisted path (what the tool
+     *  reports back to the model). Failures should throw — the tool treats persistence as best-effort. */
+    persist(runId: string, script: string): Promise<string> | string;
+    /** Read a previously persisted script back. MUST refuse paths outside the store (the argument is
+     *  model-supplied — containment is the store's contract, not the tool's). */
+    load(scriptPath: string): Promise<string> | string;
+    /** Resolve a SAVED workflow name to its script source (undefined = unknown name). Optional — a deployment
+     *  without a named registry simply omits it. May return either the bare script source (legacy/simple form)
+     *  or a {@link NamedWorkflowResolution} carrying the registration's `defaultArgs` (design/140 §6 1a). A
+     *  deployment entry of the SAME NAME as a built-in workflow SHADOWS the built-in (design/140 §6 1c). */
+    resolveName?(name: string): Promise<string | NamedWorkflowResolution | undefined> | string | NamedWorkflowResolution | undefined;
+    /**
+     * design/140 §6 1b — enumerate the registry's SAVED workflows for the listing projection (tool card /
+     * roster faces). Optional: a store without a stable name registry omits it (the file store below does —
+     * its directory mixes per-run persisted scripts with saved names, so enumeration would advertise every
+     * past run as a "named workflow"). NOTE: only a SYNCHRONOUS return reaches the statically-built Workflow
+     * tool card; an async store should precompute if it wants card visibility.
+     */
+    list?(): NamedWorkflowListing[] | Promise<NamedWorkflowListing[]>;
+}
+/**
+ * design/140 §6 1a — the default-args merge: **call-time args > registered defaultArgs** (the script's own
+ * internal fallbacks remain the third tier, applied by the script itself). Semantics (locked by test):
+ * - both sides plain objects → SHALLOW top-level merge (`{...defaults, ...call}`): a top-level key present in
+ *   the call args wins WHOLESALE — nested objects/arrays/scalars are replaced, never deep-merged;
+ * - call args absent (`undefined`) → the registered defaults verbatim;
+ * - call args a non-object (array / scalar / null) → the call args win wholesale (no structural mixing).
+ * Pure value-in/value-out: the caller snapshots the RESULT into the run (parse-time discipline, design/140 §2 —
+ * a resume replay never re-queries the registry; a post-launch registry change cannot reach an in-flight run).
+ */
+export declare function mergeWorkflowArgs(callArgs: unknown, defaultArgs: unknown): unknown;
+/**
+ * 团队通道 [426] CORE-1 — NORMALIZE a bare-string call-time arg into `{ [key]: <string> }` so the published
+ * "裸 string = <key>" ergonomic entry (built-in `team-discussion`: bare string args IS the topic) COMPOSES
+ * with a registered object `defaultArgs` instead of colliding with it.
+ *
+ * The bug it fixes: {@link mergeWorkflowArgs}'s non-object branch lets a bare string win WHOLESALE — so a
+ * named workflow whose registration carries object `defaultArgs` (center 配的 members/rounds/finalizer) had
+ * its whole defaults block silently wiped the moment a caller used the ergonomic `{name, args: "<topic>"}`
+ * form, and the collab template quietly ran as a generic advocate/skeptic. Wrapping the string here lets the
+ * subsequent object merge preserve the defaults AND honor the topic.
+ *
+ * Applied ONLY when BOTH hold (otherwise return `callArgs` untouched — pre-[426] behavior byte-preserved):
+ *  - `callArgs` is a string (the ergonomic form), AND
+ *  - `defaultArgs` is a PLAIN OBJECT (there ARE object defaults to merge under; with no/scalar defaults a bare
+ *    string must still reach the script verbatim — the built-in's own `raw === "string"` fallback handles it).
+ * `key` is the resolution's `stringArgKey` (a registry may declare which key its bare string maps to); the
+ * caller passes the built-in default `"topic"` when the resolution omits it.
+ */
+export declare function normalizeStringArg(callArgs: unknown, defaultArgs: unknown, key?: string): unknown;
+/**
+ * File-backed {@link WorkflowScriptStore}: scripts land as `<dir>/<runId>.js`; `resolveName` reads
+ * `<dir>/<name>.js` (same directory — a saved workflow is just a script file someone/some run left there).
+ */
+export declare function createFileWorkflowScriptStore(dir: string): WorkflowScriptStore;
+//# sourceMappingURL=workflow-script-store.d.ts.map

package/dist/orchestration/workflow-script-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-script-store.d.ts","sourceRoot":"","sources":["../../src/orchestration/workflow-script-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf;;4FAEwF;IACxF,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;gHAO4G;IAC5G,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC;0GACsG;IACtG,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IACjE;iFAC6E;IAC7E,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IACnD;;;4GAGwG;IACxG,WAAW,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,uBAAuB,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,uBAAuB,GAAG,SAAS,CAAC;IACjI;;;;;;OAMG;IACH,IAAI,CAAC,IAAI,oBAAoB,EAAE,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAAC;CACnE;AAOD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,GAAG,OAAO,CAsBlF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,SAAU,GAAG,OAAO,CAGlG;AAQD;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAyC9E"}