@sema-ai/core 1.275.1

package/dist/orchestration/workflow-observe.js

@@ -0,0 +1,177 @@
+import { PushQueue } from "../core/push-queue.js";
+/**
+ * design/97 S1c — the `/workflows` query + live-progress seam over the S1b {@link WorkflowRunStore} and the
+ * S1a {@link import("./workflow.js").runWorkflow} event stream. CLI (design/92) and the supervisor client
+ * (design/90) consume THIS to render the `/workflows` list / detail / live view — core gives the seam, the
+ * UI lives in the consumer.
+ *
+ * Two halves:
+ *  - **Historical / list** ({@link listWorkflowRuns} / {@link getWorkflowRun}) — thin pass-throughs to the
+ *    persisted store (history included, the "看之前的" query). Require a store; with no store wired there is
+ *    no durable history to query.
+ *  - **Live progress** ({@link subscribeWorkflow}) — an in-process pub/sub registry that fans a running
+ *    workflow's {@link WorkflowEvent}s to any subscriber. **OPT-IN, process-local, store-independent**: it
+ *    works whether or not a store is wired (a zero-config L0 run is still subscribable for live progress).
+ *    `runWorkflow` publishes EVERY emitted event to this registry (best-effort — a bad subscriber can never
+ *    break the workflow) via {@link publishWorkflowEvent}, and closes the channel at `run_end` via
+ *    {@link closeWorkflowChannel}.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Live-progress registry (in-process, opt-in)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * runId → the set of live subscriber queues for that run. A run has an entry ONLY while it has ≥1 subscriber
+ * (created lazily by {@link subscribeWorkflow}, pruned when the last subscriber leaves or the run closes), so
+ * an un-subscribed workflow costs nothing here. Module-level (process-local) — the registry is the seam for
+ * the SAME-process consumer (CLI/client in-proc); a cross-replica live feed is a deployment concern (it tails
+ * the durable store / its own event bus), out of core's scope.
+ */
+const channels = new Map();
+/**
+ * runIds currently RUNNING in this process (marked at `run_start` by {@link markWorkflowActive}, cleared at
+ * `run_end` by {@link closeWorkflowChannel}). {@link subscribeWorkflow} uses it to refuse subscribing to a
+ * run that already ended or never ran here — otherwise such a subscriber would block forever (no producer
+ * would ever close its channel). Both functions are synchronous, so there is no check-then-act race.
+ */
+const activeRuns = new Set();
+/** design/97 S1c: mark a run RUNNING (called by `runWorkflow` before it emits `run_start`). */
+export function markWorkflowActive(runId) {
+    activeRuns.add(runId);
+}
+/** T2A-9 (2026-07-05 soak): is this runId currently ACTIVE in-process? Used by `startWorkflow` to reject an
+ *  explicit duplicate `opts.runId` up front — two runs sharing one observation channel let the first finisher
+ *  close the second's event stream (and best-effort-swallow its store writes). Synchronous, race-free with
+ *  markWorkflowActive/closeWorkflowChannel (same tick). */
+export function isWorkflowRunActive(runId) {
+    return activeRuns.has(runId);
+}
+/**
+ * design/97 S1c: fan one {@link WorkflowEvent} to every live subscriber of `runId`. Called by `runWorkflow`
+ * for EVERY emitted event. BEST-EFFORT — a `push` never throws (the {@link PushQueue} just buffers), and a
+ * missing channel (no subscriber) is a no-op; nothing here can break the workflow. A subscriber that
+ * registered AFTER the run started receives only events from that point on (live progress, not a replay).
+ */
+export function publishWorkflowEvent(runId, event) {
+    const subs = channels.get(runId);
+    if (!subs)
+        return;
+    for (const q of subs)
+        q.push(event);
+}
+/**
+ * design/97 S1c: close the live channel for `runId` (called by `runWorkflow` at `run_end`). Closes every
+ * subscriber's queue so their `for await` loops END cleanly, and drops the channel entry (no leak). A
+ * subscriber's queue is also pruned individually if it stops iterating before the run ends (see
+ * {@link subscribeWorkflow}). Idempotent — closing a missing/already-closed channel is a no-op.
+ */
+export function closeWorkflowChannel(runId) {
+    activeRuns.delete(runId); // the run is no longer running — future subscribers get an empty stream, not a hang
+    const subs = channels.get(runId);
+    if (!subs)
+        return;
+    for (const q of subs)
+        q.close();
+    channels.delete(runId);
+}
+/**
+ * design/97 S1c: subscribe to a RUNNING workflow's live {@link WorkflowEvent} progress (the `/workflows` live
+ * view). Returns an `AsyncIterable<WorkflowEvent>` that yields every event emitted AFTER subscription and ends
+ * when the run finishes (its channel closes at `run_end`). **In-process + opt-in**: subscribing registers a
+ * queue in the module registry; `runWorkflow` only fans events to a runId that HAS a subscriber, so this is
+ * pay-for-what-you-use.
+ *
+ * Subscribe BEFORE or DURING the run: a queue registered before `run_start` catches the whole stream; one
+ * registered mid-run catches the rest (no replay of past events — the historical view is {@link getWorkflowRun}).
+ * If the run already ended (or never ran in this process), the returned iterable simply yields nothing and ends.
+ *
+ * The queue is pruned from the registry when the consumer's iteration ENDS (loop completes, `break`, or throw)
+ * — so a consumer that stops early does not leak a buffer (the `finally` removes it).
+ */
+export function subscribeWorkflow(runId) {
+    // The run already ended (or never ran in this process) → no producer will ever close a channel, so a live
+    // subscription would block forever. Return an immediately-exhausted stream instead (history via
+    // getWorkflowRun). Safe to check synchronously: markWorkflowActive/closeWorkflowChannel are synchronous.
+    if (!activeRuns.has(runId)) {
+        return {
+            // eslint-disable-next-line require-yield
+            async *[Symbol.asyncIterator]() {
+                /* no events: the run is not live in this process */
+            },
+        };
+    }
+    const queue = new PushQueue();
+    let subs = channels.get(runId);
+    if (!subs) {
+        subs = new Set();
+        channels.set(runId, subs);
+    }
+    subs.add(queue);
+    // Wrap the queue's iterator so leaving the loop (return/break/throw) deregisters this subscriber.
+    return {
+        async *[Symbol.asyncIterator]() {
+            try {
+                for await (const ev of queue)
+                    yield ev;
+            }
+            finally {
+                const live = channels.get(runId);
+                if (live) {
+                    live.delete(queue);
+                    if (live.size === 0)
+                        channels.delete(runId); // prune an empty channel (no leak)
+                }
+            }
+        },
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Historical / list queries (over the durable store)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * design/97 S1c: list a scope's workflow runs (newest first) as lightweight {@link WorkflowRunSummary}
+ * projections — **history included** (completed / failed, not just running), the "看之前的" query. A thin
+ * pass-through to {@link WorkflowRunStore.listByScope}; `opts.status` filters to one lifecycle state and
+ * `opts.limit` caps the count (newest N).
+ */
+export function listWorkflowRuns(store, scope, opts) {
+    return store.listByScope(scope, opts);
+}
+/**
+ * design/97 S1c: fetch ONE full {@link WorkflowRun} (phases / agents / stats) by id — the `/workflows` detail
+ * view. 🔐 SCOPED (CORE-1~9 audit BLOCKER): returns the run ONLY when its `scope` equals the caller's `scope`
+ * (the tenant) — else `null`, just like {@link listWorkflowRuns}/the journal load. A run id is unguessable, but
+ * without this check a cross-tenant id leaks the run's metadata / groups / redacted prompts+outputs / stats; the
+ * store's lower-level `get(id)` carries no scope, so the isolation MUST be enforced here at the observe layer.
+ */
+export async function getWorkflowRun(store, id, scope) {
+    const run = await store.get(id);
+    return run && run.scope === scope ? run : null;
+}
+/**
+ * design/99 MF-W (design-review DoR ⑤+⑥): the SHARED, anti-drift projection of a workflow agent's record-level
+ * status → a CC-style display status, derived PURELY from the persisted record (the agent's `status` + `startedAt`
+ * + the run's status), so the shell + service render IDENTICALLY (no per-shell drift — the WPe port lives once,
+ * here, not copied N times). Covers 5 of the 8 contract states from the durable record:
+ *   - `completed` → `done`; `failed` → `failed`.
+ *   - `running` but `startedAt` ABSENT → `queued` (enqueued, still waiting for a concurrency slot — the DoR ⑥ fix:
+ *     a queued agent no longer lies as `running`).
+ *   - `running` + started, while the RUN still runs → `running`; started but the RUN terminated (the agent never
+ *     finished) → `interrupted`.
+ * The other contract states are intentionally NOT here: `idle` (last-activity age) is a SERVICE live aggregation
+ * (core's `ToolActivity` has no timestamp); `skipped`/`paused`/`stopped` are not core states (no engine producer —
+ * see the DoR "don't model an enum arm the engine never emits").
+ */
+export function deriveAgentDisplayStatus(agent, runStatus) {
+    if (agent.status === "completed")
+        return "done";
+    if (agent.status === "failed")
+        return "failed";
+    // status === "running": if the RUN already terminated, this agent was abandoned (the producer normally closes it
+    // to `failed` at finalize — codex council; this ordering also guards a pre-fix persisted zombie / a live
+    // transient so it never reads `queued` forever). Otherwise the run is LIVE: `queued` if it never acquired a slot
+    // (no `startedAt`), else `running`.
+    if (runStatus !== "running")
+        return "interrupted";
+    return agent.startedAt === undefined ? "queued" : "running";
+}
+//# sourceMappingURL=workflow-observe.js.map

package/dist/orchestration/workflow-observe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-observe.js","sourceRoot":"","sources":["../../src/orchestration/workflow-observe.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAIlD;;;;;;;;;;;;;;;;GAgBG;AAEH,gFAAgF;AAChF,8CAA8C;AAC9C,gFAAgF;AAEhF;;;;;;GAMG;AACH,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAyC,CAAC;AAElE;;;;;GAKG;AACH,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;AAErC,+FAA+F;AAC/F,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AACxB,CAAC;AAED;;;2DAG2D;AAC3D,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,OAAO,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAa,EAAE,KAAoB;IACtE,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACjC,IAAI,CAAC,IAAI;QAAE,OAAO;IAClB,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACtC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,oFAAoF;IAC9G,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACjC,IAAI,CAAC,IAAI;QAAE,OAAO;IAClB,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,CAAC,CAAC,KAAK,EAAE,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,0GAA0G;IAC1G,gGAAgG;IAChG,yGAAyG;IACzG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO;YACL,yCAAyC;YACzC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;gBAC3B,oDAAoD;YACtD,CAAC;SACF,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,SAAS,EAAiB,CAAC;IAC7C,IAAI,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC/B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,IAAI,GAAG,IAAI,GAAG,EAAE,CAAC;QACjB,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC5B,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAChB,kGAAkG;IAClG,OAAO;QACL,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;YAC3B,IAAI,CAAC;gBACH,IAAI,KAAK,EAAE,MAAM,EAAE,IAAI,KAAK;oBAAE,MAAM,EAAE,CAAC;YACzC,CAAC;oBAAS,CAAC;gBACT,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;gBACjC,IAAI,IAAI,EAAE,CAAC;oBACT,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;oBACnB,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC;wBAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,mCAAmC;gBAClF,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,qDAAqD;AACrD,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAuB,EACvB,KAAa,EACb,IAAqD;IAErD,OAAO,KAAK,CAAC,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,KAAuB,EAAE,EAAU,EAAE,KAAa;IACrF,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAChC,OAAO,GAAG,IAAI,GAAG,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AACjD,CAAC;AAKD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAyD,EAAE,SAA4B;IAC9H,IAAI,KAAK,CAAC,MAAM,KAAK,WAAW;QAAE,OAAO,MAAM,CAAC;IAChD,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC/C,iHAAiH;IACjH,yGAAyG;IACzG,iHAAiH;IACjH,oCAAoC;IACpC,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,aAAa,CAAC;IAClD,OAAO,KAAK,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9D,CAAC"}

package/dist/orchestration/workflow-primitives.d.ts

@@ -0,0 +1,31 @@
+/**
+ * design/98 §E.1 (S8b) — the MEMBRANE adapter: extract the bound primitive functions FROM a trusted
+ * {@link WorkflowRunContext} and assemble a flat, sterile {@link WorkflowPrimitives} record. A
+ * {@link WorkflowScriptRunner} receives ONLY this record — the host `ctx` object (with its prototype chain
+ * into the host realm) structurally never enters the runner, so a script cannot walk
+ * `ctx.constructor.constructor(...)` to escape (the chain is unreachable: there is no `ctx`).
+ *
+ * Two modes:
+ *  - **governed** (`governance` set) — for an LLM-AUTHORED script: the `agent` primitive runs the untrusted
+ *    spec through {@link buildGovernedChildSpec} (default-deny whitelist + baseline + model allowlist + clamp)
+ *    BEFORE `ctx.agent`. The script can ONLY tighten the deployment governance, never escape it.
+ *  - **trusted-dev** (no `governance`) — for a developer-authored script: the `agent` primitive passes the
+ *    full `TaskSpec` straight through (the author IS the deployment).
+ */
+import type { Model } from "../internal/llm.js";
+import type { TaskSpec, WorkflowGovernanceBaseline } from "../core/types.js";
+import type { WorkflowAgentHandle, WorkflowRunContext } from "./workflow.js";
+import type { WorkflowPrimitives } from "./workflow-script-runner.js";
+import { type WorkflowChildCaps } from "./workflow-governance.js";
+/** What an LLM-authored workflow needs to GOVERN each spawned sub-agent (design/98 §2.5). */
+export interface WorkflowGovernance {
+    baseline: WorkflowGovernanceBaseline;
+    models?: Record<string, Model>;
+    caps?: WorkflowChildCaps;
+}
+/**
+ * Build the flat {@link WorkflowPrimitives} a {@link WorkflowScriptRunner} runs the script against. The
+ * `agent` primitive is GOVERNED when `governance` is set (LLM-authored), else a trusted pass-through.
+ */
+export declare function buildWorkflowPrimitives(ctx: WorkflowRunContext, governance?: WorkflowGovernance, onAgentSpawn?: (handle: WorkflowAgentHandle) => void, parentThinking?: () => TaskSpec["thinking"], parentPrincipal?: string): WorkflowPrimitives;
+//# sourceMappingURL=workflow-primitives.d.ts.map

package/dist/orchestration/workflow-primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-primitives.d.ts","sourceRoot":"","sources":["../../src/orchestration/workflow-primitives.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAwB,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,EAA0B,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE1F,6FAA6F;AAC7F,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,0BAA0B,CAAC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC/B,IAAI,CAAC,EAAE,iBAAiB,CAAC;CAC1B;AAsBD;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,kBAAkB,EACvB,UAAU,CAAC,EAAE,kBAAkB,EAC/B,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,mBAAmB,KAAK,IAAI,EACpD,cAAc,CAAC,EAAE,MAAM,QAAQ,CAAC,UAAU,CAAC,EAC3C,eAAe,CAAC,EAAE,MAAM,GACvB,kBAAkB,CAyDpB"}

package/dist/orchestration/workflow-primitives.js

@@ -0,0 +1,104 @@
+/**
+ * design/98 §E.1 (S8b) — the MEMBRANE adapter: extract the bound primitive functions FROM a trusted
+ * {@link WorkflowRunContext} and assemble a flat, sterile {@link WorkflowPrimitives} record. A
+ * {@link WorkflowScriptRunner} receives ONLY this record — the host `ctx` object (with its prototype chain
+ * into the host realm) structurally never enters the runner, so a script cannot walk
+ * `ctx.constructor.constructor(...)` to escape (the chain is unreachable: there is no `ctx`).
+ *
+ * Two modes:
+ *  - **governed** (`governance` set) — for an LLM-AUTHORED script: the `agent` primitive runs the untrusted
+ *    spec through {@link buildGovernedChildSpec} (default-deny whitelist + baseline + model allowlist + clamp)
+ *    BEFORE `ctx.agent`. The script can ONLY tighten the deployment governance, never escape it.
+ *  - **trusted-dev** (no `governance`) — for a developer-authored script: the `agent` primitive passes the
+ *    full `TaskSpec` straight through (the author IS the deployment).
+ */
+import { buildGovernedChildSpec } from "./workflow-governance.js";
+/** Sanitize the script-supplied agent options down to the SAFE subset (label / phase / schema). A script may
+ *  not reach into host cancellation (`signal`) or any other field. */
+function safeAgentOptions(opts) {
+    if (typeof opts !== "object" || opts === null)
+        return {};
+    const o = opts;
+    const out = {};
+    if (typeof o.label === "string")
+        out.label = o.label;
+    if (typeof o.phase === "string")
+        out.phase = o.phase;
+    if (o.schema !== undefined)
+        out.schema = o.schema;
+    // F4 (CC 198 parity): a script may pick a REGISTERED agent type by NAME — safe to pass through (the
+    // registry is deployment-supplied and resolution + the unknown-name teaching error live in the spawn
+    // lane; a name can select among deployment-declared definitions but can never inject one).
+    if (typeof o.agentType === "string")
+        out.agentType = o.agentType;
+    // design/97 CORE-6: an LLM-authored script MAY request worktree isolation (only the literal "worktree") — it
+    // is a PROTECTIVE mode (a clean per-agent worktree, no escape) and a no-op when the factory isn't
+    // worktree-capable. NOT a TaskSpec field, so the governed-spec whitelist is untouched.
+    if (o.isolation === "worktree")
+        out.isolation = "worktree";
+    return out;
+}
+/**
+ * Build the flat {@link WorkflowPrimitives} a {@link WorkflowScriptRunner} runs the script against. The
+ * `agent` primitive is GOVERNED when `governance` is set (LLM-authored), else a trusted pass-through.
+ */
+export function buildWorkflowPrimitives(ctx, governance, onAgentSpawn, parentThinking, parentPrincipal) {
+    const agent = (spec, opts) => {
+        // 黑板 [420]② (CC-parity, [406] bare-phase 的姊妹): CC-ecosystem scripts write `agent('prompt', opts)`.
+        // Coerce a bare string to `{ objective }` instead of the runtime throw that left whole runs at 0 agents
+        // (the LLM-visible error taught avoidance, not the object form). Everything downstream (governance
+        // whitelist, thinking/principal inheritance) sees a normal spec object.
+        if (typeof spec === "string")
+            spec = { objective: spec };
+        const agentOpts = safeAgentOptions(opts);
+        // UNTRUSTED spec → default-deny construction (whitelist + baseline + allowlist + clamp) BEFORE runTask; a
+        // trusted-dev author (no governance) passes the full TaskSpec through — SHALLOW-COPIED (fable
+        // impl-review F2): mutating the caller's object broke frozen specs and pinned the first call's
+        // inherited thinking across reuses.
+        const childSpec = governance
+            ? buildGovernedChildSpec(spec, governance.baseline, governance.models, governance.caps)
+            : { ...spec };
+        // Thinking inheritance (the subagent-childThinking companion): explicit script `thinking` (whitelisted)
+        // wins, then a deployment-baseline `thinking` (both already landed on childSpec), then the HOST task's
+        // current level (call-time getter — a mid-run degrade/boost carries into new children).
+        if (childSpec.thinking === undefined && parentThinking) {
+            const inherited = parentThinking();
+            if (inherited !== undefined)
+                childSpec.thinking = inherited;
+        }
+        // Principal inheritance (fable impl-review F1, design/62: the principal inherits verbatim down the
+        // delegation tree — Task delegation already does via ctx.principal; the workflow lane was the gap).
+        // ENGINE-injected AFTER the governed build (principal is control-plane, deliberately not on the
+        // script whitelist; the baseline's own principal, when a deployment pins one, wins). Without this,
+        // a principal-scoped host task's workflow children offloaded tool results under the WRONG
+        // tool-result-store scope ("default") — the parent's ReadToolResult could never deref them, and
+        // two tenants' workflow children shared one scope (the codex-B1 isolation gap, workflow lane).
+        if (childSpec.principal === undefined && parentPrincipal !== undefined) {
+            childSpec.principal = parentPrincipal;
+        }
+        // design/97 CORE-9 (Part B): when the deployment wants STEERABLE tool-launched agents, run each via
+        // agentStream + emit its handle to the trusted sink (the SCRIPT never receives the handle — no host-context
+        // leak into the runner) while still returning the RESULT to the script. Unset ⇒ plain non-steerable agent.
+        if (onAgentSpawn) {
+            return ctx.agentStream(childSpec, agentOpts).then((handle) => {
+                onAgentSpawn(handle);
+                return handle.result();
+            });
+        }
+        return ctx.agent(childSpec, agentOpts);
+    };
+    return {
+        agent,
+        parallel: (thunks) => ctx.parallel(thunks),
+        pipeline: (items, ...stages) => ctx.pipeline(items, ...stages),
+        phase: (title, body) => ctx.phase(title, body),
+        log: (message) => ctx.log(message),
+        // LIVE accessors (NOT a snapshot) — re-read on every call so a budget-scaled loop sees the current spend.
+        budget: {
+            total: ctx.budget.total,
+            spent: () => ctx.budget.spent(),
+            remaining: () => ctx.budget.remaining(),
+        },
+    };
+}
+//# sourceMappingURL=workflow-primitives.js.map

package/dist/orchestration/workflow-primitives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-primitives.js","sourceRoot":"","sources":["../../src/orchestration/workflow-primitives.ts"],"names":[],"mappings":"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"}

package/dist/orchestration/workflow-sandbox-conformance.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 type { WorkflowScriptRunner } from "./workflow-script-runner.js";
+/**
+ * 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 declare function assertWorkflowPrimitivesWiring(runner: WorkflowScriptRunner): Promise<void>;
+export declare function assertWorkflowSandboxConformance(runner: WorkflowScriptRunner): Promise<void>;
+/**
+ * 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 declare function assertWorkflowDeterminism(runner: WorkflowScriptRunner): Promise<void>;
+//# sourceMappingURL=workflow-sandbox-conformance.d.ts.map

package/dist/orchestration/workflow-sandbox-conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-sandbox-conformance.d.ts","sourceRoot":"","sources":["../../src/orchestration/workflow-sandbox-conformance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAsB,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAmI5F;;;GAGG;AACH;;;;;;;GAOG;AACH,wBAAsB,8BAA8B,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuEhG;AAED,wBAAsB,gCAAgC,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgElG;AAUD;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe3F"}