@sema-agent/core/dist/orchestration/workflow-primitives.d.ts

Stateless, task-oriented AI agent core

/**
 * 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 { CheckpointStore } from "../core/checkpoint-store.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;
    /** The deployment's structured notice sink (`RunnerDeps.onNotice`), threaded here because the governed
     *  build is the only place that can report which spec fields did NOT reach the child (see
     *  `buildGovernedChildSpec`'s `onNotice` param). Only meaningful in governed mode — the trusted-dev lane
     *  strips nothing. Absent ⇒ the notice falls back to `console.warn`. */
    onNotice?: (n: import("../core/types.js").EngineNotice) => void;
}
/**
 * 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.
 * The host's model and thinking are NOT injected here: both are seats the launch site (`workflow.ts`,
 * `withWorkflowChildSeats`) fills AFTER the agentType fold, so a definition's own value is the explicit rung
 * — filling them here ran ahead of the fold and made the fold's "when unset" guard permanently false. The parent
 * SPEC seat (principal, oneShot, clientContext, the question face, the fs-fence widening, envFacts, the persistence
 * statement) is applied there for the same reason (`applyParentSpecSeat`).
 */
export declare function buildWorkflowPrimitives(ctx: WorkflowRunContext, governance?: WorkflowGovernance, onAgentSpawn?: (handle: WorkflowAgentHandle) => void, 
/** The host run's RESOLVED checkpoint seat — the store object it parks in, else the word `"disabled"`.
 *  Every agent this workflow spawns inherits it; see the injection below. */
parentCheckpointStore?: CheckpointStore | "disabled", 
/** 5.30 merge-rescan (design/199 parity gap) — the host run's RESOLVED read-face containment
 *  (post deps/org/mount resolution, not the raw spec value). `TaskSpec.readFace`'s own JSDoc
 *  promises "roots pins this task, and via the tighten-only clamp, its whole delegation subtree" —
 *  a workflow child is that subtree; the Task/SendMessage delegation lane already carries this,
 *  the workflow lane was the one gap. Lazy (read at spawn time, after prepare has resolved it). */
parentReadFace?: () => TaskSpec["readFace"], 
/** The WRITE seat's twin of the above — the host run's RESOLVED write-face containment, folded
 *  stricter-wins into every spawned child on its own seat (the two seats never read each other). */
parentWriteFace?: () => TaskSpec["writeFace"], 
/** Twin of the above for the deny-set additions (the extra entries the host's own deployment/task
 *  layers stacked on; the built-in rows the DEPLOYMENT's tier selection activates apply beside them). */
parentReadDenyPatterns?: () => TaskSpec["readDenyPatterns"], 
/** #345 ③ — the HOST task's write-hands clamp is ON (`spec.handsReadOnly === true`). Injected
 *  tighten-only into every spawned child, like the read-face clamp above; see the injection
 *  below for why it outranks even a `worktreeBase: { handsReadOnly: false }` overlay. */
parentHandsReadOnly?: boolean, 
/** #345 ③ — the HOST task's hard-headless clamp is ON (`spec.interactiveTools === false`).
 *  Same tighten-only injection; only the disabling value ever arrives here as `true`. */
parentInteractiveToolsOff?: boolean): WorkflowPrimitives;