@intx/workflow-host 0.2.2 → 0.3.0

package/dist/supervisor/terminal-commit.d.ts

@@ -0,0 +1,36 @@
+import type { RepoId, RepoStore as SubstrateRepoStore } from "@intx/hub-sessions/substrate";
+export type CommitRunFailedOpts = {
+    /** Substrate handle the supervisor writes through. */
+    substrate: SubstrateRepoStore;
+    /** Workflow-run repo for this deployment. */
+    repoId: RepoId;
+    /** Events ref the workflow-run repo writes to. */
+    ref: string;
+    /** Anchor run id used to construct the supervisor principal. */
+    anchorRunId: string;
+    /** Run id whose event log receives the RunFailed entry. */
+    runId: string;
+    /** ISO-8601 commit timestamp the event carries. */
+    at: string;
+    /** Operator-facing failure reason on `RunFailed.error.message`. */
+    message: string;
+};
+export type CommitRunFailedResult = {
+    /** Substrate-assigned commit SHA the write produced. */
+    commitSha: string;
+    /**
+     * True when a `RunFailed` was appended; false when the run was already
+     * terminal and the write was a no-op (terminal-lock respected).
+     */
+    appended: boolean;
+};
+/**
+ * Append a supervisor-authored `RunFailed` to a run's event log, unless the
+ * run is already terminal. The next seq is computed inside the substrate
+ * merge (atomic against any concurrent writer under the per-repo lock): the
+ * first event on an empty tree lands at seq 1 (the runtime's convention),
+ * otherwise at `maxSeq + 1` so the log stays seq-contiguous. If the run's
+ * highest-seq event is already terminal, the write is a no-op so push
+ * validation's terminal-lock is never tripped.
+ */
+export declare function commitRunFailed(opts: CommitRunFailedOpts): Promise<CommitRunFailedResult>;

package/dist/supervisor/terminal-commit.js

@@ -0,0 +1,134 @@
+// Supervisor-authored terminal-event commit for the crash-loop guard.
+//
+// When the crash-loop guard latches, the workflow-process child is dead
+// and cannot commit its own terminal event, yet the deployment's run must
+// reach a terminal state so its external `workflow_run.status` flips to
+// `failed` -- the sole durable, queryable signal of a crash-loop. The
+// supervisor's `crash-looping` phase is in-memory and per-process; no
+// external reader observes it. The supervisor, as the sole writer of the
+// workflow-run repo, authors a `RunFailed` for the deployment's stable
+// run so the crash-loop leaves a durable tombstone.
+//
+// Unlike `commitCancelRequested`, a terminal workflow event carries no
+// signature: only `CancelRequested` is signed (for its origin<->principal
+// cross-check at push validation), so this writer is unsigned. It writes
+// under the `supervisor` principal, which the workflow-run kind handler
+// authorizes for the deployment's own event log (`repoId.id ===
+// anchorRunId`); terminal events have no per-type authorship check.
+import { type } from "arktype";
+import { getLogger } from "@intx/log";
+import { workflowEventToOnDisk } from "../adapters/repo-store.js";
+const logger = getLogger(["workflow-host", "supervisor", "terminal-commit"]);
+/** Path layout inside the workflow-run repo: `runs/<runId>/events/<seq>.json`. */
+const RUNS_PREFIX = "runs";
+const EVENTS_DIR = "events";
+const EVENT_FILENAME_RE = /^(0|[1-9][0-9]*)\.json$/;
+/**
+ * Terminal run-event kinds, mirroring the runtime's terminal vocabulary
+ * (`RunCompleted`/`RunFailed`/`RunCancelled`). Inlined because the workflow
+ * package exports only the phase-level `isTerminalRunPhase`, not an
+ * event-kind set; the child runtime (`run-child`) and the substrate adapter
+ * (`repo-store`) inline the same three kinds. Reducing the log to a phase to
+ * reuse `isTerminalRunPhase` would be strictly heavier for a last-event
+ * type check.
+ */
+const TERMINAL_EVENT_KINDS = new Set([
+    "RunCompleted",
+    "RunFailed",
+    "RunCancelled",
+]);
+const SUPERVISOR_PRINCIPAL_KIND = "supervisor";
+/**
+ * On-disk event envelope, validated at the substrate read boundary. Only
+ * `seq` and `type` are load-bearing here (max-seq computation and the
+ * terminal-lock check); the rest of the event body is ignored.
+ */
+const OnDiskEventEnvelope = type({
+    seq: "number >= 0",
+    type: "string",
+    "+": "ignore",
+});
+/**
+ * Append a supervisor-authored `RunFailed` to a run's event log, unless the
+ * run is already terminal. The next seq is computed inside the substrate
+ * merge (atomic against any concurrent writer under the per-repo lock): the
+ * first event on an empty tree lands at seq 1 (the runtime's convention),
+ * otherwise at `maxSeq + 1` so the log stays seq-contiguous. If the run's
+ * highest-seq event is already terminal, the write is a no-op so push
+ * validation's terminal-lock is never tripped.
+ */
+export async function commitRunFailed(opts) {
+    const prefix = `${RUNS_PREFIX}/${opts.runId}/${EVENTS_DIR}/`;
+    const principal = {
+        kind: SUPERVISOR_PRINCIPAL_KIND,
+        anchorRunId: opts.anchorRunId,
+    };
+    const decoder = new TextDecoder();
+    let appended = false;
+    const { commitSha } = await opts.substrate.writeTreePreservingPrefix(principal, opts.repoId, opts.ref, {
+        preservePrefix: prefix,
+        merge: async (existing) => {
+            let maxSeq = -1;
+            let maxPath = null;
+            for (const filepath of existing.keys()) {
+                const name = filepath.slice(prefix.length);
+                const match = EVENT_FILENAME_RE.exec(name);
+                if (match === null)
+                    continue;
+                const seqStr = match[1];
+                if (seqStr === undefined)
+                    continue;
+                const seq = Number.parseInt(seqStr, 10);
+                if (seq > maxSeq) {
+                    maxSeq = seq;
+                    maxPath = filepath;
+                }
+            }
+            const carried = {};
+            for (const [k, v] of existing)
+                carried[k] = v;
+            // Terminal-lock: appending a terminal event after an existing one
+            // is rejected at push validation. If the run already ended, its
+            // `workflow_run.status` is already terminal, so the crash-loop
+            // tombstone is redundant -- no-op rather than push a rejected write.
+            //
+            // This detects the per-event (`events/<seq>.json`) form only, not
+            // the sealed combined-log (`events.jsonl`) form, which lives outside
+            // `preservePrefix`. That is sufficient here because the anchor run
+            // this commit targets is sealed only when the DEPLOYMENT itself is
+            // terminal, and the crash-loop latch fires only while the deployment
+            // is running -- so the run is never in the sealed form at this call.
+            // If a sealed run ever reached here, the append would produce a tree
+            // carrying both forms, which push validation rejects, and the caller
+            // logs the failure (best-effort tombstone) rather than corrupting.
+            if (maxPath !== null) {
+                const raw = existing.get(maxPath);
+                if (raw !== undefined) {
+                    const parsed = OnDiskEventEnvelope(JSON.parse(decoder.decode(raw)));
+                    if (parsed instanceof type.errors) {
+                        throw new Error(`commitRunFailed: event blob ${maxPath} failed validation: ${parsed.summary}`);
+                    }
+                    if (TERMINAL_EVENT_KINDS.has(parsed.type)) {
+                        return carried;
+                    }
+                }
+            }
+            const nextSeq = maxSeq < 0 ? 1 : maxSeq + 1;
+            const event = {
+                kind: "RunFailed",
+                seq: nextSeq,
+                at: opts.at,
+                error: { message: opts.message },
+            };
+            const onDisk = workflowEventToOnDisk(event, nextSeq);
+            carried[`${prefix}${String(nextSeq)}.json`] = JSON.stringify(onDisk);
+            appended = true;
+            return carried;
+        },
+        message: `append RunFailed (crash-loop) for run ${opts.runId}`,
+    });
+    if (!appended) {
+        logger.info `commitRunFailed: run ${opts.runId} already terminal; no RunFailed appended`;
+    }
+    return { commitSha, appended };
+}

package/dist/supervisor/types.d.ts

@@ -1,5 +1,6 @@
-import type { DequeueToProcessingResult, EnqueueInboxArgs, EnqueueInboxResult, MarkConsumedArgs, MarkConsumedResult, Principal, RepoId, RepoStore as SubstrateRepoStore, ReplayProcessingToInboxOpts, ReplayProcessingToInboxResult } from "@intx/hub-sessions/substrate";
-import type { OutboundMessage, SendReceipt } from "@intx/types/runtime";
+import type { DequeueToProcessingResult, EnqueueInboxArgs, EnqueueInboxOutcome, MarkConsumedArgs, MarkConsumedResult, Principal, RepoId, RepoStore as SubstrateRepoStore, ReplayProcessingToInboxOpts, ReplayProcessingToInboxResult } from "@intx/hub-sessions/substrate";
+import type { SignalKind } from "@intx/types";
+import type { ApprovalSnapshot, OutboundMessage, SendReceipt } from "@intx/types/runtime";
 import type { RunCancelled, RunCompleted, RunFailed } from "@intx/workflow";
 import type { FrameReader, NdjsonReader, NdjsonWriter } from "../ipc/index.js";
 /**
@@ -69,7 +70,13 @@ export type PrincipalSigner = (kind: WorkflowSupervisorPrincipalKind, payload: U
  *
  * `subscribeMailForAddress` returns a disposer the supervisor calls
  * during teardown. The supplied handler is invoked with the raw RFC
- * 2822 message bytes of each inbound message at the address.
+ * 2822 message bytes of each inbound message at the address, and returns
+ * a promise that resolves once the message is durably accepted (its inbox
+ * write landed, or the message was already durably present) and rejects
+ * when it was not (a transient failure, a stale refusal, or a phase where
+ * the deployment is tearing down). The host propagates that settlement to
+ * the wire so a durable-receipt ack is sent only on resolution -- resolve
+ * is the ack signal, reject is the withhold signal.
  *
  * `sendOutbound` is the OUTBOUND half of mailbox ownership (§3a). The
  * supervisor is the sole mail owner: the workflow-process child never
@@ -92,7 +99,7 @@ export type PrincipalSigner = (kind: WorkflowSupervisorPrincipalKind, payload: U
 export interface MailBusBindings {
     registerAddress(address: string): void;
     unregisterAddress(address: string): void;
-    subscribeMailForAddress(address: string, handler: (rawMessage: Uint8Array) => void): () => void;
+    subscribeMailForAddress(address: string, handler: (rawMessage: Uint8Array) => Promise<void>): () => void;
     sendOutbound(senderAddress: string, message: OutboundMessage): Promise<SendReceipt>;
 }
 /**
@@ -181,11 +188,33 @@ export type DeriveMailAuditRef = (messageId: string, rawMessage: Uint8Array) =>
  * surprise.
  */
 export interface InboxPrimitives {
-    enqueueInbox(store: SubstrateRepoStore, principal: Principal, repoId: RepoId, args: EnqueueInboxArgs): Promise<EnqueueInboxResult>;
+    enqueueInbox(store: SubstrateRepoStore, principal: Principal, repoId: RepoId, args: EnqueueInboxArgs): Promise<EnqueueInboxOutcome>;
     dequeueToProcessing(store: SubstrateRepoStore, principal: Principal, repoId: RepoId, address: string): Promise<DequeueToProcessingResult>;
     markConsumed(store: SubstrateRepoStore, principal: Principal, repoId: RepoId, args: MarkConsumedArgs): Promise<MarkConsumedResult>;
     replayProcessingToInbox(store: SubstrateRepoStore, principal: Principal, repoId: RepoId, address: string, opts?: ReplayProcessingToInboxOpts): Promise<ReplayProcessingToInboxResult>;
 }
+/**
+ * A control-plane suspension the supervisor forwards to the host after a
+ * workflow-process child reports a park. The child supplies `runId`,
+ * `correlationId`, and `kind`; the supervisor stamps `anchorRunId` and
+ * `agentAddress` from its own bindings before invoking the host's
+ * `onSuspensionRegister`. The host (production: the sidecar) turns this into
+ * a `signal.correlation.register` frame the hub co-writes the run's routing +
+ * approval rows from.
+ */
+export interface SuspensionRegistration {
+    runId: string;
+    correlationId: string;
+    kind: SignalKind;
+    anchorRunId: string;
+    agentAddress: string;
+    /**
+     * Approver-facing snapshot of the parked tool call, forwarded from the
+     * child's `park.notify`. Present only for an ask-rail suspension; the host
+     * turns it into the register frame's snapshot.
+     */
+    approvalSnapshot?: ApprovalSnapshot;
+}
 /**
  * Constructor arguments for `createWorkflowSupervisor`. One
  * `RepoStore` handle plus a `signAsPrincipal` callback that mints
@@ -201,6 +230,49 @@ export interface WorkflowSupervisorBindings {
     signAsPrincipal: PrincipalSigner;
     /** Mail-bus surface for address registration and inbound subscription. */
     mailBus: MailBusBindings;
+    /**
+     * Optional control-plane suspension sink. Two callers invoke it, both
+     * stamping `anchorRunId` and `deploymentMailAddress` (as `agentAddress`)
+     * onto the child-supplied `runId`/`correlationId`/`kind`: the upstream-control
+     * pump's `park.notify` arm (the happy-path emit at suspend), and
+     * `reEmitParkedCorrelations` (the re-establishment re-emit that recovers a
+     * register the hub missed while it was down). Production wires this to the
+     * sidecar's hub link so a `signal.correlation.register` frame reaches the hub;
+     * a host that does not wire it does not register suspensions (today, the
+     * tests). Best-effort: a throwing sink is logged and
+     * both callers keep going, so one bad register cannot wedge the control pump
+     * or abort a re-emit partway through the parked set.
+     */
+    onSuspensionRegister?: (registration: SuspensionRegistration) => void;
+    /**
+     * Per-run grants source the dispatch loop consults before it forwards a
+     * `trigger.fire`. Unlike `onSuspensionRegister` (best-effort, fire-and-
+     * forget), this is a request/response contract: the supervisor awaits the
+     * returned `CredentialsSnapshot` and pushes it to the child over the
+     * control channel BEFORE firing the run's trigger, so the child's
+     * authorize closure binds to the run's grants rather than a stale
+     * spawn-time snapshot. A throwing sink is NOT swallowed -- the dispatch
+     * loop fails that run (a synthesized `RunFailed`) rather than firing the
+     * trigger against absent grants.
+     *
+     * When this binding is wired, it is the SOLE grants push: `spawn` does not
+     * push a spawn-time snapshot, so the per-run push is the only thing that
+     * satisfies the child's throw-on-null authorize guard. A caller that
+     * injects no per-run sink -- today, the supervisor's own tests -- keeps the
+     * spawn-time push instead. Production (the sidecar) wires it to the
+     * walk-derived per-step credentials assembly.
+     */
+    onRunStart?: (args: {
+        runId: string;
+        anchorRunId: string;
+    }) => Promise<import("./credentials.js").CredentialsSnapshot>;
+    /**
+     * Decrypted credential material for the deployment's tools, delivered to the
+     * child on the pre-trigger barrier alongside the grants. Absent when the
+     * deployment binds no credentials. A rotation flows through
+     * `deliverCredentials`, not this static binding.
+     */
+    credentialDelivery?: import("@intx/types/sidecar").CredentialDelivery;
     /** Subprocess spawner the supervisor invokes per spawn. */
     subprocessSpawner: SubprocessSpawner;
     /**
@@ -235,8 +307,8 @@ export interface WorkflowSupervisorBindings {
     workflowRunRepoId: import("@intx/hub-sessions").RepoId;
     /** Workflow-run repo ref the supervisor commits events to. */
     workflowRunRef: string;
-    /** Deployment id baked into the supervisor's principal claims. */
-    deploymentId: string;
+    /** Anchor run id baked into the supervisor's principal claims. */
+    anchorRunId: string;
     /**
      * Number of steps in the deployed `WorkflowDefinition`
      * (`stepOrder.length`). The supervisor threads this into the child's
@@ -268,7 +340,7 @@ export interface WorkflowSupervisorBindings {
     deriveStepAddress: import("./credentials.js").DeriveStepAddress;
     /**
      * Optional override for the step's agent-state repo identity. The
-     * default convention is `<deploymentId>-<stepId>`.
+     * default convention is `<anchorRunId>-<stepId>`.
      */
     deriveStepRepoId?: import("./credentials.js").DeriveStepRepoId;
     /**
@@ -377,11 +449,11 @@ export interface WorkflowSupervisorBindings {
     /**
      * Workflow-run substrate principal the supervisor uses to author
      * inbox/processing/consumed writes. The substrate's workflow-run
-     * kind handler accepts a `{ kind: "supervisor", deploymentId }`
+     * kind handler accepts a `{ kind: "supervisor", anchorRunId }`
      * principal for claim-check writes; the supervisor constructs this
      * value once at bindings construction and reuses it for every
      * claim-check operation. Defaults to `{ kind: "supervisor",
-     * deploymentId }` derived from `bindings.deploymentId`; tests
+     * anchorRunId }` derived from `bindings.anchorRunId`; tests
      * override it when they need to assert on a structurally distinct
      * principal shape.
      */
@@ -413,14 +485,65 @@ export interface WorkflowSupervisorBindings {
      */
     readyTimeoutMs?: number;
     /**
-     * Watchdog timeout (ms) for the supervisor's substrate-write
-     * handler's wait on the dispatch loop's `markConsumed` when a
-     * terminal-event blob lands in a proxied write. Defaults to
-     * `DEFAULT_TERMINAL_WRITE_WATCHDOG_MS`. Tests inject a small value
-     * so the watchdog path is observable without holding a test loop
-     * for the production duration.
+     * Crash-loop guard: the maximum number of UNEXPECTED workflow-process
+     * child exits (crash, OOM, panic, signal) the supervisor tolerates
+     * within `crashLoopWindowMs` before it stops respawning and latches the
+     * deployment to a terminal state. The boot edge resolves the operator's
+     * config and supplies it; absent, `DEFAULT_CRASH_LOOP_MAX_COUNT` (3)
+     * applies. The operator owns this bound.
      */
-    terminalWriteWatchdogMs?: number;
+    crashLoopMaxCount?: number;
+    /**
+     * Sliding window (ms) over which `crashLoopMaxCount` unexpected exits
+     * latch the deployment. Absent, `DEFAULT_CRASH_LOOP_WINDOW_MS` (60s)
+     * applies.
+     */
+    crashLoopWindowMs?: number;
+    /**
+     * Stable-run duration (ms) after a respawn: once a respawned child has
+     * stayed up this long, the crash counter resets, so a burst of crashes
+     * followed by stability does not permanently latch. Absent,
+     * `DEFAULT_CRASH_LOOP_STABLE_RESET_MS` (60s) applies. Driven by the
+     * injectable `setTimer`/`clearTimer` pair so tests are deterministic.
+     */
+    crashLoopStableResetMs?: number;
+    /**
+     * Initial respawn backoff (ms): the wait before the FIRST respawn after
+     * an unexpected exit. Each subsequent respawn doubles the wait, capped at
+     * `respawnBackoffMaxMs`; a stable run resets it to this value. Absent,
+     * `DEFAULT_RESPAWN_BACKOFF_INITIAL_MS` (1s) applies.
+     */
+    respawnBackoffInitialMs?: number;
+    /**
+     * Maximum respawn backoff (ms) the exponential doubling is capped at, so
+     * a rapidly-flapping child does not saturate the host. Absent,
+     * `DEFAULT_RESPAWN_BACKOFF_MAX_MS` (30s) applies.
+     *
+     * Config invariant: keep this comfortably below `crashLoopWindowMs`.
+     * Crashes must fall within the window to accumulate toward the latch, and
+     * the backoff spaces them apart; a cap at or above the window guarantees a
+     * slow flapper's timestamps age out before the count reaches
+     * `crashLoopMaxCount`, so the guard never latches. This is necessary but
+     * not sufficient: the child's own lifetime also spaces crashes, so a child
+     * whose healthy lifetime approaches `crashLoopStableResetMs` can still
+     * out-space the window (and never earn a counter reset either), respawning
+     * indefinitely. Windowed crash detection cannot catch an arbitrarily slow
+     * flapper; the window/backoff/stable-reset trio bounds the FAST flap this
+     * guard targets.
+     */
+    respawnBackoffMaxMs?: number;
+    /**
+     * Watchdog timeout (ms) for `reEmitParkedCorrelations`' wait on the
+     * child's `parked-correlations.response`. Caps the wait so a
+     * wedged-but-alive child (whose cohort never tears down, so the
+     * cohort-abort rejection never fires) cannot hang the re-registration
+     * driver -- and therefore the reconnect/re-establishment caller that
+     * awaits it. On expiry the pending query is dropped and the driver
+     * returns; the next re-establishment re-drives it. Defaults to
+     * `DEFAULT_PARKED_QUERY_WATCHDOG_MS`. Tests inject a small value so the
+     * timeout path is observable.
+     */
+    parkedQueryWatchdogMs?: number;
     /**
      * Optional per-message dispatch-timing observer. When supplied, the
      * dispatch loop invokes it twice per dispatched inbox entry: once with
@@ -490,9 +613,8 @@ export type DispatchSubstrateLeg = "enqueue" | "dequeue" | "runevent" | "markcon
  * (design §10b). All are cheap filesystem reads against the workflow-run
  * repo's on-disk working tree, taken only when the observer is wired.
  *
- *   - `runsFanOut`     — entry count under `runs/` (one subdir per message;
- *                        never pruned). The candidate-(i) "collapse runs"
- *                        win is sized by this.
+ *   - `runsFanOut`     — entry count under `runs/` (the stable top-level run
+ *                        plus any internal body-child runs).
  *   - `consumedFanOut` — entry count under
  *                        `addresses/<addr>/consumed/` (one dedup entry per
  *                        message; never pruned). The candidate-(iv) "prune
@@ -512,8 +634,13 @@ export type DispatchStructuralCounters = {
 /**
  * One observation emitted by `WorkflowSupervisorBindings.onDispatchTiming`.
  *
+ * Both variants key on `messageId`, the per-message identifier (the mail's
+ * Message-ID). The top-level run id cannot serve as the key: one deployment
+ * keeps that stable id across all of its live trigger occurrences, so it does
+ * not distinguish one dispatched message from the next.
+ *
  * The `"roundtrip"` variant is the 4.7 latency-gate bracket: pair the
- * `"dispatch-start"` and `"reply-produced"` marks for the same `runId` to
+ * `"dispatch-start"` and `"reply-produced"` marks for the same `messageId` to
  * recover the per-message round-trip. `atMs` is a high-resolution
  * monotonic timestamp (`performance.now()`).
  *
@@ -528,12 +655,12 @@ export type DispatchStructuralCounters = {
  */
 export type DispatchTimingMark = {
     kind: "roundtrip";
-    runId: string;
+    messageId: string;
     marker: "dispatch-start" | "reply-produced";
     atMs: number;
 } | {
     kind: "leg";
-    runId: string;
+    messageId: string;
     leg: DispatchSubstrateLeg;
     phase: "start" | "end";
     atMs: number;

package/dist/workflow-definition-loader.d.ts

@@ -0,0 +1,131 @@
+import { type AnnotatedPluginFactory, type DirectorRegistry, type ToolDeclaration } from "@intx/agent";
+import type { WorkflowDefinition } from "@intx/workflow/definition";
+export interface LoadWorkflowDefinitionFromClosureArgs {
+    /**
+     * Directory of the materialized workflow package within the closure:
+     * the directory holding the package's `package.json`, with its
+     * `node_modules/` already laid out by the closure-materialization
+     * machinery so the entry module's bare-specifier imports resolve.
+     */
+    readonly packageDir: string;
+    /**
+     * Optional token mixed into the import URL's query string to bust
+     * Node's ESM module cache. Node keys the ESM cache by resolved
+     * URL/path, not by content: a process that imports the same package
+     * directory twice with different bytes underneath (a rare re-apply in
+     * a reused child) would otherwise resolve to the first-imported module
+     * instance. Passing a per-materialization token (the closure's
+     * integrity SRI is the natural choice) makes each materialization a
+     * distinct ESM cache entry. Omit it when the process imports a given
+     * package directory at most once.
+     */
+    readonly importCacheKey?: string;
+    /**
+     * Test seam for dynamic import. Production omits this and the loader
+     * uses the native dynamic-import expression. The argument is the
+     * `file://` URL the loader resolves for the `interchange.workflow`
+     * entry.
+     */
+    readonly importModule?: (importUrl: string) => Promise<unknown>;
+}
+/**
+ * Import the `interchange.workflow` entry from a materialized workflow
+ * package closure, evaluate it, and return the validated
+ * `WorkflowDefinition` its `defineWorkflow(...)` call produced.
+ *
+ * @param args - the materialized package directory plus optional import
+ *   seams
+ * @returns the validated `WorkflowDefinition`
+ * @throws if the package.json is missing/malformed, declares no
+ *   `interchange.workflow` entry, the entry path escapes the package
+ *   directory, the module cannot be imported, or its evaluation does not
+ *   produce exactly one value that validates as a `WorkflowDefinition`
+ */
+export declare function loadWorkflowDefinitionFromClosure(args: LoadWorkflowDefinitionFromClosureArgs): Promise<WorkflowDefinition>;
+export interface LoadWorkflowDirectorRegistryFromClosureArgs {
+    /**
+     * Directory of the materialized workflow package within the closure --
+     * the same directory `loadWorkflowDefinitionFromClosure` reads. Both the
+     * approval-time probe and the run-child call this over the SAME frozen
+     * closure, so the director set they compose cannot drift.
+     */
+    readonly packageDir: string;
+    /** See `LoadWorkflowDefinitionFromClosureArgs.importCacheKey`. */
+    readonly importCacheKey?: string;
+    /** Test seam for dynamic import; see the definition loader's variant. */
+    readonly importModule?: (importUrl: string) => Promise<unknown>;
+}
+/**
+ * Compose the `DirectorRegistry` for a workflow closure from the closure
+ * package's OWN `interchange.directors` module (if any), alongside the
+ * built-in default director. A package with no `interchange.directors`
+ * field composes to the built-ins-only registry -- absence is valid, a
+ * workflow need not ship a director. A present-but-empty directors module
+ * is malformed and throws, matching the tool-package loader.
+ *
+ * Only the workflow's OWN package directors are loaded here. Directors
+ * shipped by PINNED dependency packages are deliberately not resolved on
+ * the source-ref path yet: the airlocked probe does not materialize pinned
+ * packages, so loading them here would let the runtime resolve a director
+ * the probe never advertised for approval. A workflow referencing a
+ * pinned-package director fails closed (the capability walk reports it as
+ * unresolved).
+ *
+ * @throws if the directors entry path escapes the package, the module
+ *   cannot be imported, or it exports no `AnnotatedDirectorFactory` value
+ */
+export declare function loadWorkflowDirectorRegistryFromClosure(args: LoadWorkflowDirectorRegistryFromClosureArgs): Promise<DirectorRegistry>;
+export interface LoadWorkflowPluginsFromClosureArgs {
+    /**
+     * Directory of the materialized workflow package within the closure --
+     * the same directory `loadWorkflowDefinitionFromClosure` reads. Each
+     * declared plugin package is resolved from this package's laid-out
+     * `node_modules/`, exactly as the workflow entry's own bare-specifier
+     * imports resolve.
+     */
+    readonly packageDir: string;
+    /**
+     * Plugin-package names the workflow's agents declare via
+     * `AgentDefinition.plugins` (`["@intx/tools-lsp"]`). Each MUST be a
+     * direct dependency of the workflow package so it is laid out under the
+     * workflow package's `node_modules/`. Empty is valid (no plugins).
+     */
+    readonly plugins: readonly string[];
+    /** See `LoadWorkflowDefinitionFromClosureArgs.importCacheKey`. */
+    readonly importCacheKey?: string;
+    /** Test seam for dynamic import; see the definition loader's variant. */
+    readonly importModule?: (importUrl: string) => Promise<unknown>;
+}
+/**
+ * Import each declared plugin package's `interchange.tools` module from the
+ * materialized workflow closure and collect the `AnnotatedPluginFactory`
+ * values it exports. This is the run-child counterpart to the tool-package
+ * loader's plugin channel: a source-ref workflow contributes no plugin factory
+ * through its agent definition (a plugin has no agent slot), so the child
+ * materializes the declared plugins straight from the already-laid-out closure
+ * -- no re-download, no manifest -- and feeds them into the existing per-step
+ * plugin chain. The closure bytes were SRI-verified when the deploy applied the
+ * frozen closure, and resolution walks the same `node_modules/` graph the
+ * workflow entry's imports use.
+ *
+ * @throws if a declared plugin package cannot be resolved, declares no
+ *   `interchange.tools` entry, the entry escapes the package, cannot be
+ *   imported, or exports no `AnnotatedPluginFactory` value
+ */
+export declare function loadWorkflowPluginFactoriesFromClosure(args: LoadWorkflowPluginsFromClosureArgs): Promise<AnnotatedPluginFactory[]>;
+/**
+ * Read the static tool `definitions` each declared plugin package
+ * contributes, keyed by plugin-package name, WITHOUT retaining the plugin
+ * factory (so the caller never instantiates a plugin, which for LSP would
+ * start a subprocess). This is the probe/capability-walk counterpart to
+ * `loadWorkflowPluginFactoriesFromClosure`: it loads the SAME plugin module
+ * from the SAME frozen closure so the tool grant surface the walk approves
+ * matches the plugin the run-child materializes.
+ *
+ * A plugin package that exports plugin factories but declares no tool
+ * definitions (a middleware-only plugin) maps to an empty array -- valid,
+ * it contributes no tool grant.
+ *
+ * @throws under the same conditions as `loadWorkflowPluginFactoriesFromClosure`
+ */
+export declare function loadWorkflowPluginToolDefinitionsFromClosure(args: LoadWorkflowPluginsFromClosureArgs): Promise<Map<string, readonly ToolDeclaration[]>>;