@sema-agent/core 5.20.0 → 5.21.0

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

@@ -1,16 +1,40 @@
+/**
+ * design/98 §2.5 / §E.2 (S8b, security core) — the DEFAULT-DENY governance for a sub-agent an LLM-authored
+ * workflow script spawns. The child spec is BUILT (complete-by-construction) from the deployment's trusted
+ * {@link WorkflowGovernanceBaseline} + a strict WHITELIST of safe work-fields the script may set — NEVER by
+ * stripping a denylist off the untrusted spec (codex BLOCKER2: a missed control-plane field would leak).
+ *
+ * The script's spec is UNTRUSTED. Only {@link WHITELIST_KEYS} are ever read from it; every other field
+ * (toolPolicy / onAsk / hooks / principal / tools / mcp / skills / lspManager / checkpointStore /
+ * getApiKeyAndHeaders / promptProvider / sessionId / signal / …) is structurally never copied. The model is
+ * chosen by NAME ONLY (resolved against an allowlist to a deploy-configured `Model` — the script never sees a
+ * `Model` object, which carries `baseUrl`/`headers` = an exfil surface, codex v3 BLOCKER). Resource limits
+ * are CLAMPED to the baseline + workflow ceilings (`tightenTaskSpec` only covers the safety knobs, not
+ * cost/token caps — codex Q4).
+ */
 import type { Model } from "../internal/llm.js";
 import type { ImageInput, TaskSpec, ThinkingLevel, WorkflowGovernanceBaseline } from "../core/types.js";
+/** Thrown when an LLM-authored script picks a `modelName` not in the workflow model allowlist (or no
+ *  allowlist is configured). FAIL-CLOSED: a script can only ever name a model the deployment pre-approved. */
 export declare class WorkflowModelNotAllowedError extends Error {
     readonly modelName: string;
     readonly code = "workflow.model_not_allowed";
     constructor(modelName: string, reason: string);
 }
+/**
+ * The SAFE fields an LLM-authored workflow script may set per sub-agent — the WORK, never the control plane.
+ * `model` is a NAME (string), NOT a `ModelRef`/`Model` object (codex v3 BLOCKER: a `Model` carries
+ * `baseUrl`/`headers`/`extraBody` = endpoint + auth-header injection). No `modelRole`/`roles` (a `roles.select`
+ * conditional selector is its own vector). The engine resolves `modelName` against the allowlist.
+ */
 export interface WorkflowAgentSpec {
     objective: string;
     modelName?: string;
     thinking?: ThinkingLevel;
     systemPrompt?: string;
     images?: ImageInput[];
+    /** Every sub-field must be a POSITIVE number — a non-positive value is a DISABLE sentinel downstream
+     *  (or an exhausted budget), never a tighter ceiling, and is refused (see {@link NON_POSITIVE_LIMIT_MSG}). */
     limits?: {
         maxTurns?: number;
         maxWalltimeMs?: number;
@@ -18,17 +42,54 @@ export interface WorkflowAgentSpec {
         maxCostUsd?: number;
     };
 }
+/**
+ * The SINGLE source of truth for the whitelist (a test pins that it contains no control-plane key). `objective`
+ * + `modelName` are handled explicitly in {@link buildGovernedChildSpec}; the rest map 1:1 onto `TaskSpec`.
+ */
 export declare const WHITELIST_KEYS: readonly ["objective", "modelName", "thinking", "systemPrompt", "images", "limits"];
+/** Per-child workflow ceilings the engine forces onto every spawned agent (design/98 §D.6), independent of
+ *  what the script asks for. The child's effective limits = min(script, baseline, these). */
 export interface WorkflowChildCaps {
+    /** design/164 — per-child wall-clock ceiling in MILLISECONDS (was `perAgentTimeoutSec`, seconds).
+     *  No default: a deployment that wants a ceiling states it. */
     perAgentMaxWalltimeMs?: number;
     childMaxCostUsd?: number;
     childMaxTokens?: number;
     childMaxTurns?: number;
 }
+/**
+ * RB-378 disclosure — one resource field whose EFFECTIVE (applied) value differs from what the script's spec
+ * literally carried. `requested` is `undefined` when the script omitted the field entirely (a baseline/cap
+ * ceiling was FORCED onto an unset field, not just a script value pushed down). Emitted so a caller can tell
+ * "the script asked for/omitted X" apart from "the child actually ran under Y" — see
+ * {@link buildGovernedChildSpec}'s `onResourceClamp` param.
+ */
 export interface ResourceClampNote {
     field: "maxCostUsd" | "maxTokens" | "maxWalltimeMs" | "maxTurns";
+    /** What the script's spec literally set for this field, or `undefined` if it never set it. */
     requested: number | undefined;
+    /** The effective value the child actually runs under (min of script/baseline/caps, or a forced ceiling). */
     applied: number;
 }
+/** Resolve an LLM-supplied model NAME to a deploy-configured `Model`, FAIL-CLOSED against the allowlist.
+ *  Throws (never falls open to the whole catalog) when no allowlist is configured or the name is not on it. */
 export declare function resolveModelName(name: string, allowlist: string[] | undefined, models: Record<string, Model> | undefined): Model;
+/**
+ * Build a TRUSTED child `TaskSpec` for an LLM-authored sub-agent (design/98 §2.5). Complete-by-construction:
+ *   1. read ONLY the whitelist work-fields off the untrusted script spec (type-checked);
+ *   2. resolve `modelName` → a deploy `Model` against the allowlist (fail-closed);
+ *   3. clamp resource limits to the baseline + workflow ceilings;
+ *   4. `tightenTaskSpec(baseline.base, safe)` → the child spec (baseline governance FIRST, safe work-fields
+ *      overlay; safety fields can only equal-or-tighten — belt-and-suspenders over the whitelist).
+ * Every governance/control-plane field of the result comes from `baseline.base` (the deployment's trusted
+ * config), never from the script.
+ *
+ * RB-378: `onResourceClamp`, when given, receives the non-empty list of {@link ResourceClampNote}s produced by
+ * step 3 — i.e. it fires exactly when the child's effective maxCostUsd/maxTokens/maxWalltimeMs/maxTurns diverges
+ * from what the script's spec literally asked for (never called when nothing was clamped/forced). The clamp
+ * VALUES and the fact that it is always-tighten-never-raise are UNCHANGED by this param — it is a pure
+ * disclosure hook the caller can wire to a log/event channel (see `buildWorkflowPrimitives`, which logs it
+ * onto the run's log stream so the LLM-authored script's caller can see requested→applied per field instead
+ * of the child silently running under different limits than the script wrote).
+ */
 export declare function buildGovernedChildSpec(scriptSpec: unknown, baseline: WorkflowGovernanceBaseline, models: Record<string, Model> | undefined, caps?: WorkflowChildCaps, onResourceClamp?: (notes: ResourceClampNote[]) => void): TaskSpec;

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

@@ -1,11 +1,39 @@
+/**
+ * design/98 §2.4 (S8b) — STATIC, NON-EVAL extraction of a workflow script's `export const meta = {...}`.
+ *
+ * 🔴 The meta block is parsed as PURE DATA by a small recursive-descent reader that NEVER executes the
+ * script (no `vm`, no `eval`, no `Function`) — evaluating untrusted source to read its metadata would itself
+ * be the injection surface. The reader accepts ONLY literal values (string / number / boolean / null / array
+ * / plain object) and REJECTS anything that could carry behavior or pollute a prototype:
+ *   - identifier values (a variable reference), function calls, template literals, spreads, computed keys,
+ *     method shorthand, getters/setters;
+ *   - the dangerous keys `__proto__` / `constructor` / `prototype` (prototype-pollution guard).
+ * Any violation throws {@link WorkflowScriptError} so the `run_workflow` tool can hand the LLM a structured
+ * "fix your meta" error BEFORE the (hard) sandbox ever runs the body.
+ */
 import type { WorkflowMeta } from "./workflow-script-runner.js";
+/** Thrown when an LLM-authored workflow script is malformed at the static layer (bad meta, oversized source,
+ *  a forbidden construct). Carries a `code` so the tool can return a structured error the model can act on. */
 export declare class WorkflowScriptError extends Error {
     readonly code = "workflow.script_error";
     constructor(message: string);
 }
+/**
+ * Statically extract + validate a workflow script's `export const meta`. Returns a typed {@link WorkflowMeta}
+ * (name + description required, both strings; `phases`/`whenToUse` optional). NEVER executes the script.
+ * @throws {WorkflowScriptError} on a missing/malformed/non-literal meta.
+ */
 export declare function parseWorkflowMeta(source: string): WorkflowMeta;
+/** Replace every string literal (incl. template text, recursing into `${…}` code) and comment with spaces. */
 export declare function stripStringsAndComments(src: string): string;
+/** CC `wxl` semantics: a `Date.now` / `Math.random` member access, or an ARGLESS `new Date()`, anywhere in the
+ *  body's CODE (strings/comments stripped) — each silently busts the resume prefix cache. */
 export declare function workflowScriptReadsClockOrRandom(body: string): boolean;
+/**
+ * Parse the meta AND return the script BODY with the `export const meta = {...}` declaration removed — for a
+ * runner that compiles the remaining body as an async function (the meta is DATA, parsed statically; only the
+ * body is ever executed). An optional trailing `;` after the declaration is trimmed.
+ */
 export declare function splitWorkflowMeta(source: string): {
     meta: WorkflowMeta;
     body: string;

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

@@ -1,16 +1,76 @@
 import type { WorkflowRunStore, WorkflowRunSummary } from "../core/workflow-run-store.js";
 import type { WorkflowEvent, WorkflowItemStatus, WorkflowRun, WorkflowRunStatus } from "./workflow.js";
+/** design/97 S1c: mark a run RUNNING (called by `runWorkflow` before it emits `run_start`).
+ *  γ 批 B-3 (BREAKING): carries the run's SCOPE — {@link subscribeWorkflow} gates on it. */
 export declare function markWorkflowActive(runId: string, scope: string): void;
+/** 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 declare function isWorkflowRunActive(runId: string): boolean;
+/**
+ * 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 declare function publishWorkflowEvent(runId: string, event: WorkflowEvent): void;
+/**
+ * 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 declare function closeWorkflowChannel(runId: string): void;
+/**
+ * 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 declare function subscribeWorkflow(runId: string, scope: string): AsyncIterable<WorkflowEvent>;
+/**
+ * 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 declare function listWorkflowRuns(store: WorkflowRunStore, scope: string, opts?: {
     status?: WorkflowRunStatus;
     limit?: number;
 }): Promise<WorkflowRunSummary[]>;
+/**
+ * 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 declare function getWorkflowRun(store: WorkflowRunStore, id: string, scope: string): Promise<WorkflowRun | null>;
+/** design/99 MF-W display status. */
 export type AgentDisplayStatus = "queued" | "running" | "done" | "failed" | "interrupted";
+/**
+ * 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 declare function deriveAgentDisplayStatus(agent: {
     status: WorkflowItemStatus;
     startedAt?: number;

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

@@ -1,11 +1,33 @@
+/**
+ * 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;
 }
-export declare function buildWorkflowPrimitives(ctx: WorkflowRunContext, governance?: WorkflowGovernance, onAgentSpawn?: (handle: WorkflowAgentHandle) => void, parentThinking?: () => TaskSpec["thinking"], parentPrincipal?: string, parentCheckpointStoreDisabled?: boolean): WorkflowPrimitives;
+/**
+ * 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, 
+/** ruled 2026-08-04 — the host run set `TaskSpec.checkpointStore: null` (the per-run durable off
+ *  switch). Every agent this workflow spawns inherits it; see the injection below. */
+parentCheckpointStoreDisabled?: boolean): WorkflowPrimitives;

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

@@ -1,4 +1,42 @@
+/**
+ * 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.
+ *
+ * Structure, in the order it must hold:
+ *  1. a POSITIVE CONTROL ({@link runLivenessCanary}) — the runner executes a body, sees `scriptArgs`, and
+ *     returns the value. Without this the battery is vacuous.
+ *  2. four probe families, each judging the MARSHALLED result. The capability families return an in-isolate
+ *     WITNESS ({@link WITNESS_PRELUDE}) rather than the capability object, so a leak whose value cannot cross
+ *     the marshalling boundary is no longer swallowed as "blocked".
+ *  3. a probe that THROWS is re-tested for liveness before its throw is read as "blocked"
+ *     ({@link runProbeBody}) — the two meanings of a throw are separated by evidence, not by assumption.
+ */
+/**
+ * The PRIMITIVES-WIRING battery. A 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>;

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

@@ -1,10 +1,55 @@
 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;
@@ -12,24 +57,67 @@ export interface WorkflowMeta {
     }>;
     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;

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

@@ -1,20 +1,118 @@
+/**
+ * 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). ONE return shape: a registry that carries no defaults returns `{ script }`
+ * — the bare-string return is RETIRED (RB-482 #9, ruled 2026-08-03), matching {@link
+ * WorkflowScriptStore.resolveName}'s contract. A plain-JS store still returning a bare string is refused
+ * with a structured migration error at the tool boundary, not read as a resolution.
+ */
 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 {
+    /** γ 批 B-4 (codex γ-G3) — the CONFORMANCE MARKER for the scope-partitioned contract. Structural
+     *  typing would otherwise let a pre-partition adapter (`load(path)`, `persist(runId, script)`)
+     *  remain assignable — fewer-parameter functions are compatible in TypeScript — and silently
+     *  ignore the scope argument, serving cross-tenant reads while the tool presents the operation as
+     *  scope-bounded. A REQUIRED literal field breaks that assignability at compile time; the
+     *  run-workflow tool also refuses at runtime when it is absent (plain-JS adapters). */
     readonly scopePartitioned: true;
+    /** 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.
+     *  γ 批 B-4 (BREAKING): `scope` PARTITIONS per-run scripts — the CC anchor is a per-session directory,
+     *  and the port had dropped the axis (one flat directory let a model-supplied scriptPath read another
+     *  scope's script). Implementations key storage by scope (the file store uses per-scope subdirs). */
     persist(runId: string, script: string, scope: 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).
+     *  γ 批 B-4 (BREAKING): `scope` bounds the read to the CALLER's partition — a path pointing into
+     *  another scope's partition must be refused exactly like a path outside the store. */
     load(scriptPath: string, scope: string): Promise<string> | string;
+    /** Resolve a SAVED workflow name to its registration (undefined = unknown name). Optional — a deployment
+     *  without a named registry simply omits it. RB-482 #9 (ruled 2026-08-03): ONE return form — a
+     *  {@link NamedWorkflowResolution} ({ script, defaultArgs? }); the legacy bare-string return is retired. A
+     *  deployment entry of the SAME NAME as a built-in workflow SHADOWS the built-in (design/140 §6 1c).
+     *  γ 批 RULING: deliberately NO scope axis here — saved names are a DEPLOYMENT-level registry (the
+     *  built-ins' tier), shared across scopes like agent definitions; a multi-tenant deployment that wants
+     *  per-tenant registries mounts per-tenant store instances. */
     resolveName?(name: string): Promise<NamedWorkflowResolution | undefined> | 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}: per-run scripts land as `<dir>/<scopeDir>/<runId>.js`
+ * (γ 批 B-4: per-scope partition — the CC per-session-dir posture restored on the tenant axis);
+ * `resolveName` reads `<dir>/<name>.js` at the ROOT (the deployment-level saved-name tier, see the
+ * interface RULING — deliberately outside every scope partition).
+ */
 export declare function createFileWorkflowScriptStore(dir: string): WorkflowScriptStore;

package/dist/orchestration/workflow-size-guideline.d.ts

@@ -1,14 +1,81 @@
+/**
+ * CC config key `workflowSizeGuideline`: an ADVISORY size guideline for LLM-authored workflows
+ * (small/medium/large/unrestricted), injected into the Workflow tool's prompt/description. It is
+ * guidance, NOT a cap — the hard ceiling stays `WorkflowLimits.maxAgents`.
+ *
+ * RB-339 (2026-07-30, clay A 案) — REBASELINED on CC 2.1.220 (语料 ../cc-decoded/pretty220.js). The
+ * module was anchored to 2.1.206 and had drifted on four points; all four are corrected here and the
+ * old "verbatim" claims (which were not true of the two sentence builders) are replaced with what
+ * each function actually is:
+ *  1. DEFAULT. CC's `_Td = "medium"` (:455529) with `Oft` (:455538) returning `{ size: "medium",
+ *     isDefault: true }` whenever the setting is absent or not a member of the enum. sema defaulted
+ *     to "unrestricted" (= inject nothing), so an unconfigured deployment got NO guideline at all.
+ *     Behavior narrowing, declared: an unconfigured task now carries the medium section.
+ *  2. TWO-ARM SECTION. CC's `TTd(size, isDefault)` (:455514) has a DEFAULT arm ("This session has the
+ *     default …" + the "/config" escape sentence) and an EXPLICIT arm ("A workflow size guideline is
+ *     configured for this session:" with no escape sentence). sema had a single hand-written form.
+ *  3. CHANGE NOTICE. CC's `ETd` (:455523) — both arms differed from sema's wording.
+ *  4. Normalization. CC's `Msn` (:455494) is a MEMBERSHIP test returning `undefined` for a non-member
+ *     (which then falls to the medium default); sema mapped every unknown value to "unrestricted",
+ *     i.e. a typo in the setting silently disabled the guideline. Now `undefined`, per CC.
+ *
+ * Still-current 220 anchors: `rLs` enum (:455532) / `oko` caps (:455533) / `bTd` describe (:455507) /
+ * `STd` not-a-hard-limit sentence (:455511) / `Sj_` display label (:455497). Those five ARE verbatim.
+ *
+ * Injection site: CC appends the section to BOTH `prompt()` and `description()` of the Workflow tool
+ * (`oLs`, :455548 — returns "" for "unrestricted", else "\n\n" + the sentence). Snapshot semantics:
+ * CC memoizes the SESSION-START value (`Nsn`) so the card is stable within a session; a mid-session
+ * /config change reaches the model via a `workflow_size_guideline_change` attachment (`vTd`, :455555)
+ * rendered with `ETd`. sema equivalence: the card is built once per mount (`createRunWorkflowTool`) =
+ * per-task snapshot — same stability property.
+ *
+ * Mid-session change lane (SHIPPED — the module no longer ships static injection only): CC's `vTd`
+ * (:455555) recomputes the RESOLVED guideline each turn, recovers the last announced one (its own
+ * previous attachment, falling back to the session-start snapshot) and emits a
+ * `workflow_size_guideline_change` attachment rendered with `ETd` on inequality. sema's equivalent
+ * lives at the run loop's turn-boundary steerer (`runtask.ts`, alongside the structurally identical
+ * date_change / instructions_change lanes): the leg's resolved guideline is the baseline, the live
+ * `RunnerDeps.workflowLimits` read is the current value, and {@link workflowSizeGuidelineChangeNotice}
+ * is the copy. Comparison is on the RESOLVED coordinate on both sides, CC-exact — `vTd` compares
+ * `Oft(...).size` against `Nsn(...).size`, so a deployment writing down the value already in force by
+ * default is not a change. Two lane properties are sema's own and deliberate: the frame is
+ * continuation-gated (an advisory retune must never revive a finished run), and only the
+ * `WorkflowLimits` channel is watched — the direct-construction `RunWorkflowToolDeps.sizeGuideline` is
+ * a per-mount pin the runner never sets.
+ */
+/** CC `rLs` member type — the config value space. */
 export type WorkflowSizeGuideline = "small" | "medium" | "large" | "unrestricted";
+/** CC `rLs` (:455532) — the enum options, in CC's settings-face order. */
 export declare const WORKFLOW_SIZE_GUIDELINES: readonly WorkflowSizeGuideline[];
+/** CC `_Td` (:455529) — the guideline in force when the deployment configured none. */
 export declare const WORKFLOW_SIZE_GUIDELINE_DEFAULT: WorkflowSizeGuideline;
+/** CC `oko` (:455533) — the advisory agent count each tier aims under. */
 export declare const WORKFLOW_SIZE_GUIDELINE_AGENT_CAPS: Readonly<Record<"small" | "medium" | "large", number>>;
+/** CC `Msn` (:455494) — a MEMBERSHIP test: the value when it is one of the four options, otherwise
+ *  `undefined` (an unknown/absent value is "unconfigured", NOT "unrestricted" — see
+ *  {@link resolveWorkflowSizeGuideline}, which is where the default is applied). */
 export declare function normalizeWorkflowSizeGuideline(value: unknown): WorkflowSizeGuideline | undefined;
+/** CC `Oft` (:455538) — resolve the guideline in force plus whether it came from the default.
+ *  `isDefault` drives the two arms of {@link workflowSizeGuidelineSection}. */
 export declare function resolveWorkflowSizeGuideline(value: unknown): {
     size: WorkflowSizeGuideline;
     isDefault: boolean;
 };
+/** CC `ubd`/`yTd` — the tier's advisory agent count (undefined for "unrestricted"). CC feeds this into
+ *  its workflow-size warning thresholds; exported for the same future lane + deployments. */
 export declare function workflowSizeGuidelineAgentCap(g: WorkflowSizeGuideline): number | undefined;
+/** CC `bTd` (:455507) — the tier description embedded in the injected sentences. Verbatim. */
 export declare function describeWorkflowSizeGuideline(g: WorkflowSizeGuideline): string;
+/** CC `Sj_` (:455497) — the settings-face display label ("Dynamic workflow size" enum row). Verbatim.
+ *  Exported for a shell's settings 透传 (the shell only surfaces the key; the engine hosts it). */
 export declare function formatWorkflowSizeGuidelineLabel(g: WorkflowSizeGuideline): string;
+/**
+ * CC `oLs` (:455548) — the section appended to the Workflow tool's prompt AND description, including
+ * the leading blank line. An EXPLICIT "unrestricted" injects nothing; an absent/unknown value resolves
+ * to the medium DEFAULT and injects the default arm (RB-339 — this is the behavior narrowing).
+ */
 export declare function workflowSizeGuidelineSection(value: unknown): string;
+/** CC `ETd` (:455523) — the mid-session change notice. Verbatim. Emitted by the run loop's
+ *  `workflow_size_guideline_change` turn-boundary lane (see the module header); this is that frame's
+ *  ONLY copy — the lane renders through here rather than restating the sentences. */
 export declare function workflowSizeGuidelineChangeNotice(g: WorkflowSizeGuideline): string;