@intx/workflow-host 0.2.2 → 0.4.0

package/dist/child/verified-definition-loader.js

@@ -0,0 +1,43 @@
+// Source-ref definition load + re-verify barrier for the workflow-process child.
+//
+// A source-ref deployment's runnable definition is the evaluated pinned code
+// closure, not an on-disk `workflow.json`. `loadVerifiedWorkflowDefinitionFromClosure`
+// evaluates that closure to a live `WorkflowDefinition` and re-verifies it by
+// project-then-hash: it projects the live definition back to its inert form,
+// hashes it (`computeLiveDefinitionHash`), and refuses to return a definition
+// whose recompute does not match the hub-approved hash. A mismatch throws --
+// fail closed, no fallback and no coercion.
+//
+// The re-verify barrier is load-bearing because the approved hash arrives
+// OUT-OF-BAND from the bytes being checked (a signed spawn env the closure
+// materializer cannot forge). It lives at the LOAD boundary, not at run start:
+// a resumed run reuses the definition this loader returned at child boot, so
+// gating the load covers fresh runs, resumed runs, and referenced onTrigger
+// bodies (which the child extracts from the same re-verified closure) with a
+// single check. `RunStarted.definitionHash` is deliberately NOT the barrier: it
+// hashes a different projection and never fires when the run log already carries
+// a `RunStarted`, so it is skipped on resume.
+import { computeLiveDefinitionHash } from "@intx/workflow";
+import { loadWorkflowDefinitionFromClosure } from "../workflow-definition-loader.js";
+/**
+ * Evaluate a source-ref deployment's pinned code closure to a live
+ * `WorkflowDefinition` and re-verify it by project-then-hash before returning
+ * it. The inert projection is a non-executable approval surface, so the runtime
+ * needs the live definition the closure evaluates to. The re-verify projects
+ * that live definition back to its inert form and hashes it
+ * (`computeLiveDefinitionHash`), matching the hub-approved wire hash by byte
+ * equality; a divergent closure fails closed here and never runs.
+ */
+export async function loadVerifiedWorkflowDefinitionFromClosure(opts) {
+    const definition = await loadWorkflowDefinitionFromClosure({
+        packageDir: opts.packageDir,
+        ...(opts.importModule !== undefined
+            ? { importModule: opts.importModule }
+            : {}),
+    });
+    const recomputed = await computeLiveDefinitionHash(definition);
+    if (recomputed !== opts.approvedHash) {
+        throw new Error(`workflow-host verified-definition loader: recomputed wire hash ${recomputed} for the source-ref closure at ${opts.packageDir} does not match the approved hash ${opts.approvedHash}; refusing to run a definition that no longer projects to the hub-approved content`);
+    }
+    return definition;
+}

package/dist/child/warm-agent-cache.d.ts

@@ -11,6 +11,35 @@ import type { InferenceEvent, InferenceSource } from "@intx/types/runtime";
 export interface WarmEventSinkRef {
     current: ((event: InferenceEvent) => void) | null;
 }
+/**
+ * Per-turn settle barrier the connector reply drain exposes to the warm
+ * step (design §3c durability). The step snapshots `replySeq()` before its
+ * `agent.send` and, for a turn that produced a reply, awaits
+ * `waitForReplyAfter(snapshot)` so the run parks -- and the supervisor
+ * consumes the inbound mail -- only after the reply is durably sent. This is
+ * the structural subset of the harness `ConnectorReplyDrain` the warm path
+ * needs; declaring it here keeps the workflow-host package independent of
+ * `@intx/harness`, while the drain the sidecar builds satisfies it.
+ */
+export type WarmReplySettlement = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly cause: unknown;
+};
+export interface WarmReplyDrive {
+    /** Settles when the drain loop exits at eviction. Folded into `eventForward`. */
+    readonly done: Promise<void>;
+    /** Monotonic count of replies that have settled (sent-and-acked or failed). */
+    replySeq(): number;
+    /**
+     * Resolve once the reply at index `n` has settled, with its outcome. A
+     * failure outcome (or a drain that tears down before reply `n` arrives)
+     * carries `ok: false` so the caller fails the turn rather than treating the
+     * reply as sent.
+     */
+    waitForReplyAfter(n: number): Promise<WarmReplySettlement>;
+}
 /**
  * Per-address warm-agent cache. Keyed by the step's stable identity (the
  * single step's id), so a long-lived agent resolves to the same entry on
@@ -28,11 +57,22 @@ export interface WarmAgentCache {
     /**
      * Cache a freshly-built warm agent under `key`. The `eventSinkRef` is
      * the mutable sink the agent's stream forwarder reads; `eventForward`
-     * is the forwarder loop's settle promise. Throws if an entry already
-     * exists for `key` -- a double-build is a step-invoker bug, not a
-     * silent overwrite that would leak the prior agent's LSP subprocess.
+     * is the forwarder loop's settle promise. `replyDrive` is the connector
+     * reply drain's per-turn barrier, or `null` when the deployment drives no
+     * threaded replies. Throws if an entry already exists for `key` -- a
+     * double-build is a step-invoker bug, not a silent overwrite that would
+     * leak the prior agent's LSP subprocess.
+     */
+    store(key: string, agent: Agent, eventSinkRef: WarmEventSinkRef, eventForward: Promise<void>, replyDrive: WarmReplyDrive | null): void;
+    /**
+     * Return the connector reply drain's per-turn barrier cached for `key`, or
+     * `null` when the deployment drives no threaded replies. The step-invoker
+     * fetches it on every message -- the drain is established once at the
+     * first-message build but each message's send must snapshot and await it.
+     * Throws when no entry exists for `key`: a barrier fetch before the warm
+     * agent is stored is a step-invoker sequencing bug.
      */
-    store(key: string, agent: Agent, eventSinkRef: WarmEventSinkRef, eventForward: Promise<void>): void;
+    getReplyDrive(key: string): WarmReplyDrive | null;
     /**
      * Point the warm agent's stream forwarder at the active step's event
      * sink before its `agent.send`. Throws when no entry exists for

package/dist/child/warm-agent-cache.js

@@ -45,11 +45,18 @@ export function createWarmAgentCache() {
         const entry = entries.get(key);
         return entry === undefined ? null : entry.agent;
     }
-    function store(key, agent, eventSinkRef, eventForward) {
+    function store(key, agent, eventSinkRef, eventForward, replyDrive) {
         if (entries.has(key)) {
             throw new Error(`warm-agent cache: an entry already exists for ${key}; the step-invoker must reuse the cached agent rather than rebuild it`);
         }
-        entries.set(key, { agent, eventSinkRef, eventForward });
+        entries.set(key, { agent, eventSinkRef, eventForward, replyDrive });
+    }
+    function getReplyDrive(key) {
+        const entry = entries.get(key);
+        if (entry === undefined) {
+            throw new Error(`warm-agent cache: getReplyDrive for ${key} with no cached entry; the step-invoker must store the warm agent before fetching its reply barrier`);
+        }
+        return entry.replyDrive;
     }
     function setEventSink(key, onEvent) {
         const entry = entries.get(key);
@@ -65,8 +72,24 @@ export function createWarmAgentCache() {
         entry.eventSinkRef.current = null;
     }
     function applySources(sources, defaultSource) {
+        // Rotate every retained agent before surfacing any failure: one agent
+        // rejecting the rotation (an invalid source, or a closed agent racing
+        // eviction) must not skip the rest. Collect failures and throw them
+        // together. (Warm-keep is single-step today, so the cache holds 0 or 1
+        // entry; this keeps the contract honest if warm-keep ever spans steps.)
+        const failures = [];
         for (const entry of entries.values()) {
-            entry.agent.setSources(sources, defaultSource);
+            try {
+                entry.agent.setSources(sources, defaultSource);
+            }
+            catch (cause) {
+                const message = cause instanceof Error ? cause.message : String(cause);
+                logger.error `warm-agent rotation: setSources failed: ${message}`;
+                failures.push(cause);
+            }
+        }
+        if (failures.length > 0) {
+            throw new AggregateError(failures, `warm-agent rotation: ${String(failures.length)} agent(s) rejected the source rotation`);
         }
     }
     async function evictAll(reason) {
@@ -74,24 +97,28 @@ export function createWarmAgentCache() {
             return;
         const toEvict = [...entries.values()];
         entries.clear();
+        // Close every entry before surfacing any failure. The wrapped close
+        // (see `createToolBearingAgentFactory`) runs the agent's own close and
+        // then the plugin + tool-bundle disposers, killing the LSP subprocess,
+        // and it rejects when a disposer fails. One entry's close rejecting
+        // must not strand the remaining entries' teardown -- that would leak
+        // exactly the LSP subprocesses warm-keep risks. Collect failures and
+        // throw them together once every agent has been closed and drained.
+        // (Warm-keep is single-step today, so the cache holds 0 or 1 entry;
+        // this keeps the contract honest if warm-keep ever spans steps.)
+        const failures = [];
         for (const entry of toEvict) {
             // Clear the sink first so any event emitted during the agent's
             // shutdown window is dropped rather than delivered to a per-run
             // channel the run-loop is tearing down.
             entry.eventSinkRef.current = null;
             try {
-                // The wrapped close (see `createToolBearingAgentFactory`) runs
-                // the agent's own close and then the plugin + tool-bundle
-                // disposers, killing the LSP subprocess. A close failure must
-                // surface, not be swallowed -- a leaked LSP subprocess is
-                // exactly the failure warm-keep risks -- so it propagates after
-                // we have drained what we can.
                 await entry.agent.close();
             }
             catch (cause) {
                 const message = cause instanceof Error ? cause.message : String(cause);
                 logger.error `warm-agent eviction (${reason}): agent.close failed: ${message}`;
-                throw cause instanceof Error ? cause : new Error(message);
+                failures.push(cause);
             }
             finally {
                 // `agent.close()` terminates the stream iterator, so the
@@ -100,10 +127,14 @@ export function createWarmAgentCache() {
                 await entry.eventForward;
             }
         }
+        if (failures.length > 0) {
+            throw new AggregateError(failures, `warm-agent eviction (${reason}): ${String(failures.length)} agent(s) failed to close; an LSP subprocess may be leaked`);
+        }
     }
     return {
         acquire,
         store,
+        getReplyDrive,
         setEventSink,
         clearEventSink,
         applySources,

package/dist/index.d.ts

@@ -1,10 +1,12 @@
+export { loadWorkflowDefinitionFromClosure, loadWorkflowDirectorRegistryFromClosure, loadWorkflowLoopFnsFromClosure, loadWorkflowPluginFactoriesFromClosure, loadWorkflowPluginToolDefinitionsFromClosure, type LoadWorkflowDefinitionFromClosureArgs, type LoadWorkflowDirectorRegistryFromClosureArgs, type LoadWorkflowLoopFnsFromClosureArgs, type LoadWorkflowPluginsFromClosureArgs, } from "./workflow-definition-loader.js";
 export { createWorkflowRunRepoStore, type WorkflowRunRepoStoreOpts, } from "./adapters/repo-store.js";
 export { createWorkflowRunBlobSubstrate, type WorkflowRunBlobSubstrateOpts, } from "./adapters/blob-substrate.js";
+export { createSubstrateMailboxStore, MAILBOX_PREFIX, MAILBOX_INBOX_DIR, MAILBOX_INDEX_FILE, MAILBOX_EML_SUFFIX, MAILBOX_INBOX_PREFIX, type SubstrateMailboxStore, type SubstrateMailboxStoreOpts, type MailboxSyncKnownState, type MailboxSyncResult, } from "./adapters/substrate-mailbox-store.js";
 export { createWorkflowStepInvoker, type StepEnvBase, type WorkflowStepInvokerOpts, } from "./adapters/step-invoker.js";
-export { createWorkflowSpawnChild, type ChildTerminalStatus, type RunChildWorkflow, type WorkflowSpawnChildOpts, } from "./adapters/spawn-child.js";
-export { createWorkflowSupervisor, assembleCredentialsSnapshot, commitCancelRequested, createDrainTimeoutAccumulator, createRecyclePolicy, defaultStepRepoId, hashGrants, triggerRecycle, DEFAULT_DRAIN_TIMEOUT_MS, DEFAULT_KILL_TIMEOUT_MS, DEFAULT_POLICY_INTERVAL_MS, DEFAULT_TERMINAL_WRITE_WATCHDOG_MS, MAX_BUFFERED_MAIL, STEP_GRANTS_PATH, STEP_GRANTS_REF, SUPERVISOR_PRINCIPAL_KIND, type AssembleCredentialsSnapshotOpts, type CancelCommitInfo, type CancelRequestOpts, type CommitCancelRequestedOpts, type CommitCancelRequestedResult, type CredentialsSnapshot, type CredentialsSnapshotStep, type DeliverSignalOpts, type DeliverSourcesOpts, type DeriveMailAuditRef, type DeriveStepAddress, type DeriveStepRepoId, type DrainOpts, type DrainTimeoutAccumulator, type DrainTimeoutAccumulatorFactory, type DrainTimeoutOpts, type InboxPrimitives, type MailAuditRef, type MailBusBindings, type PrincipalSigner, type RecycleAttempt, type RecycleContext, type RecycleOpts, type RecycleOrigin, type RecyclePolicy, type RecyclePolicyBounds, type RecyclePolicyOpts, type SignedPayload, type SpawnOpts, type SpawnResult, type SubprocessHandle, type SubprocessSpawner, type TerminalEventSource, type TerminalRunEvent, type TriggerRecycleOpts, type DispatchTimingMark, type DispatchStructuralCounters, type DispatchSubstrateLeg, type WorkflowSupervisor, type WorkflowSupervisorBindings, type WorkflowSupervisorPrincipalKind, } from "./supervisor/index.js";
+export { createInMemorySpawnChild, createInMemorySpawnSuspendableChild, type ChildTerminalStatus, type RunChildWorkflow, type RunSuspendableChild, } from "./adapters/spawn-child.js";
+export { createWorkflowSupervisor, assembleCredentialsSnapshot, isErrnoNotFound, commitCancelRequested, createDrainTimeoutAccumulator, createRecyclePolicy, defaultStepRepoId, hashGrants, triggerRecycle, DEFAULT_DRAIN_TIMEOUT_MS, DEFAULT_KILL_TIMEOUT_MS, DEFAULT_POLICY_INTERVAL_MS, MAX_BUFFERED_MAIL, STEP_GRANTS_PATH, STEP_GRANTS_REF, SUPERVISOR_PRINCIPAL_KIND, type AssembleCredentialsSnapshotOpts, type CancelCommitInfo, type CancelRequestOpts, type CommitCancelRequestedOpts, type CommitCancelRequestedResult, type CredentialsSnapshot, type CredentialsSnapshotStep, type DeliverSignalOpts, type DeliverSourcesOpts, type DeriveMailAuditRef, type DeriveStepAddress, type DeriveStepRepoId, type DrainOpts, type DrainTimeoutAccumulator, type DrainTimeoutAccumulatorFactory, type DrainTimeoutOpts, type InboxPrimitives, type MailAuditRef, type MailBusBindings, type PrincipalSigner, type RecycleAttempt, type RecycleContext, type RecycleOpts, type RecycleOrigin, type RecyclePolicy, type RecyclePolicyBounds, type RecyclePolicyOpts, type SignedPayload, type SpawnOpts, type SpawnResult, type SubprocessHandle, type SubprocessSpawner, type SuspensionRegistration, type TerminalEventSource, type TerminalRunEvent, type TriggerRecycleOpts, type DispatchTimingMark, type DispatchStructuralCounters, type DispatchSubstrateLeg, type WorkflowSupervisor, type WorkflowSupervisorBindings, type WorkflowSupervisorPrincipalKind, } from "./supervisor/index.js";
 export { createWorkflowHostDrainController, type WorkflowHostDrainController, type CreateWorkflowHostDrainControllerOpts, } from "./drain-controller.js";
 export { wrapHubTransportAsMailBus, type HubTransportMailBusAdapter, } from "./mail-bus/index.js";
-export { ControlPayload, DEFAULT_EVENT_BUFFER_LIMIT, EventPayload, FrameEnvelope, IPC_CRYPTO, SourcesUpdatedData, MacedEnvelope, OutboundAttachmentPayload, OutboundMessagePayload, SignedEnvelope, createControlChannelSender, createEventChannelSender, decodeEnvelope, encodeEnvelope, generateChannelId, generateHmacKey, receiveControlChannel, receiveEventChannel, signEd25519, signHmac, verifyEd25519, verifyHmac, type ControlChannelReceiverOpts, type ControlChannelSender, type ControlChannelSenderOpts, type EventChannelReceiverOpts, type EventChannelSender, type EventChannelSenderOpts, type FrameReader, type FrameWriter, type NdjsonReader, type NdjsonWriter, } from "./ipc/index.js";
-export { EVENT_CHANNEL_FD, createChildOutboundMailBridge, createChildSubstrateWriteBridge, createCredentialsBackedAuthorize, createProxyWorkflowRunRepoStore, createSupervisorBackedTransport, createWarmAgentCache, discoverInFlightRuns, parseSpawnTimeEnv, runWorkflowChild, runWorkflowChildFromProcessEnv, type ChildOutboundMailBridge, type ChildStepInvoker, type ChildSubstrateWriteBridge, type CreateChildOutboundMailBridgeOpts, type CreateChildSubstrateWriteBridgeOpts, type CreateProxyWorkflowRunRepoStoreOpts, type CredentialsSnapshotRef, type DiscoverRunsOpts, type DiscoveredRun, type DrainController, type GrantEvaluator, type RunWorkflowChildBindings, type RunWorkflowChildFromProcessEnvOpts, type RunWorkflowChildOpts, type RunWorkflowChildResult, type SourcesSnapshotRef, type SpawnTimeEnv, type SubstrateFactory, type SubstrateFactoryEnv, type SubstrateWriteRequest, type SubstrateWriteResponseSink, type WarmAgentCache, type WarmEventSinkRef, } from "./child/index.js";
+export { ControlPayload, DEFAULT_EVENT_BUFFER_LIMIT, EventPayload, FrameEnvelope, IPC_CRYPTO, MailboxNotifyHeaders, SourcesUpdatedData, MacedEnvelope, OutboundAttachmentPayload, OutboundMessagePayload, SignedEnvelope, createControlChannelSender, createEventChannelSender, decodeEnvelope, encodeEnvelope, generateChannelId, generateHmacKey, receiveControlChannel, receiveEventChannel, signEd25519, signHmac, verifyEd25519, verifyHmac, type ControlChannelReceiverOpts, type ControlChannelSender, type ControlChannelSenderOpts, type EventChannelReceiverOpts, type EventChannelSender, type EventChannelSenderOpts, type FrameReader, type FrameWriter, type NdjsonReader, type NdjsonWriter, } from "./ipc/index.js";
+export { EVENT_CHANNEL_FD, createChildMailboxReader, createChildMailboxMutationBridge, createChildOutboundMailBridge, createChildSubstrateWriteBridge, createCredentialsBackedAuthorize, createMailboxWatchRegistry, createProxyWorkflowRunRepoStore, createSupervisorBackedTransport, createWarmAgentCache, discoverInFlightRuns, parseSpawnTimeEnv, runWorkflowChild, runWorkflowChildFromProcessEnv, type ChildMailboxMutationBridge, type ChildMailboxReader, type ChildOutboundMailBridge, type ChildStepInvoker, type ChildSubstrateWriteBridge, type CreateChildMailboxMutationBridgeOpts, type CreateChildOutboundMailBridgeOpts, type CreateChildSubstrateWriteBridgeOpts, type CreateProxyWorkflowRunRepoStoreOpts, type CredentialsSnapshotRef, type CredentialWiring, type DiscoverRunsOpts, type DiscoveredRun, type DrainController, type GrantEvaluator, type LoadParkedApproval, type MailboxWatchRegistry, type RunWorkflowChildBindings, type RunWorkflowChildFromProcessEnvOpts, type RunWorkflowChildOpts, type RunWorkflowChildResult, type SourcesSnapshotRef, type SpawnTimeEnv, type SubstrateFactory, type SubstrateFactoryEnv, type SubstrateWriteRequest, type SubstrateWriteResponseSink, type SupervisorBackedTransportInbound, type WarmAgentCache, type WarmEventSinkRef, } from "./child/index.js";
 export { adaptHostScheduler, createWorkflowHostScheduler, createWorkflowHostSignalChannel, SignalReceivedEnvelope, type SchedulerHandle, type SchedulerOpts, type SignalChannelHandle, type SignalChannelOpts, } from "./seams/index.js";

package/dist/index.js

@@ -1,10 +1,12 @@
+export { loadWorkflowDefinitionFromClosure, loadWorkflowDirectorRegistryFromClosure, loadWorkflowLoopFnsFromClosure, loadWorkflowPluginFactoriesFromClosure, loadWorkflowPluginToolDefinitionsFromClosure, } from "./workflow-definition-loader.js";
 export { createWorkflowRunRepoStore, } from "./adapters/repo-store.js";
 export { createWorkflowRunBlobSubstrate, } from "./adapters/blob-substrate.js";
+export { createSubstrateMailboxStore, MAILBOX_PREFIX, MAILBOX_INBOX_DIR, MAILBOX_INDEX_FILE, MAILBOX_EML_SUFFIX, MAILBOX_INBOX_PREFIX, } from "./adapters/substrate-mailbox-store.js";
 export { createWorkflowStepInvoker, } from "./adapters/step-invoker.js";
-export { createWorkflowSpawnChild, } from "./adapters/spawn-child.js";
-export { createWorkflowSupervisor, assembleCredentialsSnapshot, commitCancelRequested, createDrainTimeoutAccumulator, createRecyclePolicy, defaultStepRepoId, hashGrants, triggerRecycle, DEFAULT_DRAIN_TIMEOUT_MS, DEFAULT_KILL_TIMEOUT_MS, DEFAULT_POLICY_INTERVAL_MS, DEFAULT_TERMINAL_WRITE_WATCHDOG_MS, MAX_BUFFERED_MAIL, STEP_GRANTS_PATH, STEP_GRANTS_REF, SUPERVISOR_PRINCIPAL_KIND, } from "./supervisor/index.js";
+export { createInMemorySpawnChild, createInMemorySpawnSuspendableChild, } from "./adapters/spawn-child.js";
+export { createWorkflowSupervisor, assembleCredentialsSnapshot, isErrnoNotFound, commitCancelRequested, createDrainTimeoutAccumulator, createRecyclePolicy, defaultStepRepoId, hashGrants, triggerRecycle, DEFAULT_DRAIN_TIMEOUT_MS, DEFAULT_KILL_TIMEOUT_MS, DEFAULT_POLICY_INTERVAL_MS, MAX_BUFFERED_MAIL, STEP_GRANTS_PATH, STEP_GRANTS_REF, SUPERVISOR_PRINCIPAL_KIND, } from "./supervisor/index.js";
 export { createWorkflowHostDrainController, } from "./drain-controller.js";
 export { wrapHubTransportAsMailBus, } from "./mail-bus/index.js";
-export { ControlPayload, DEFAULT_EVENT_BUFFER_LIMIT, EventPayload, FrameEnvelope, IPC_CRYPTO, SourcesUpdatedData, MacedEnvelope, OutboundAttachmentPayload, OutboundMessagePayload, SignedEnvelope, createControlChannelSender, createEventChannelSender, decodeEnvelope, encodeEnvelope, generateChannelId, generateHmacKey, receiveControlChannel, receiveEventChannel, signEd25519, signHmac, verifyEd25519, verifyHmac, } from "./ipc/index.js";
-export { EVENT_CHANNEL_FD, createChildOutboundMailBridge, createChildSubstrateWriteBridge, createCredentialsBackedAuthorize, createProxyWorkflowRunRepoStore, createSupervisorBackedTransport, createWarmAgentCache, discoverInFlightRuns, parseSpawnTimeEnv, runWorkflowChild, runWorkflowChildFromProcessEnv, } from "./child/index.js";
+export { ControlPayload, DEFAULT_EVENT_BUFFER_LIMIT, EventPayload, FrameEnvelope, IPC_CRYPTO, MailboxNotifyHeaders, SourcesUpdatedData, MacedEnvelope, OutboundAttachmentPayload, OutboundMessagePayload, SignedEnvelope, createControlChannelSender, createEventChannelSender, decodeEnvelope, encodeEnvelope, generateChannelId, generateHmacKey, receiveControlChannel, receiveEventChannel, signEd25519, signHmac, verifyEd25519, verifyHmac, } from "./ipc/index.js";
+export { EVENT_CHANNEL_FD, createChildMailboxReader, createChildMailboxMutationBridge, createChildOutboundMailBridge, createChildSubstrateWriteBridge, createCredentialsBackedAuthorize, createMailboxWatchRegistry, createProxyWorkflowRunRepoStore, createSupervisorBackedTransport, createWarmAgentCache, discoverInFlightRuns, parseSpawnTimeEnv, runWorkflowChild, runWorkflowChildFromProcessEnv, } from "./child/index.js";
 export { adaptHostScheduler, createWorkflowHostScheduler, createWorkflowHostSignalChannel, SignalReceivedEnvelope, } from "./seams/index.js";

package/dist/ipc/control-channel.d.ts

@@ -44,13 +44,14 @@ export declare const SourcesUpdatedData: import("arktype/internal/variants/objec
         id: string;
         provider: string;
         baseURL: string;
-        apiKey: string;
+        credentialId: string;
         model: string;
         defaults?: {
             maxTokens?: number;
             providerOptions?: Record<string, unknown>;
         };
         capabilities?: string[];
+        quirks?: Record<string, unknown>;
     }[];
     defaultSource: string;
 }, {}>;
@@ -94,11 +95,45 @@ export declare const OutboundMessagePayload: import("arktype/internal/variants/o
         dataBase64: string;
     }[];
     inReplyTo?: string;
+    references?: string[];
     correlationId?: string;
     sessionId?: string;
     tenantId?: string;
 }, {}>;
 export type OutboundMessagePayload = typeof OutboundMessagePayload.infer;
+/**
+ * Wire shape of the parsed `MessageHeaders` the supervisor rides inline on a
+ * `mailbox.notify` frame. Mirrors `@intx/types/runtime`'s `MessageHeaders`
+ * field-for-field so a child watcher gets the arrived message's envelope for
+ * its `exists` `MailboxEvent` without a substrate round-trip. The four
+ * unconditionally-dereferenced fields (`from`, `to`, `date`, `messageId`) are
+ * required; the rest are optional, matching the runtime type.
+ *
+ * Duplicated here as an arktype validator (rather than importing the TypeScript
+ * `MessageHeaders` type) so the IPC module validates the header block at the
+ * wire boundary, exactly as `OutboundMessagePayload` does for outbound mail.
+ */
+export declare const MailboxNotifyHeaders: import("arktype/internal/variants/object.ts").ObjectType<{
+    from: string;
+    to: string[];
+    date: string;
+    messageId: string;
+    cc?: string[];
+    inReplyTo?: string;
+    references?: string[];
+    subject?: string;
+    listId?: string;
+    interchangeType?: "conversation.message" | "conversation.join" | "conversation.leave" | "offering.request" | "offering.response" | "offering.error" | "offering.discover" | "offering.catalog" | "payment.required" | "payment.receipt" | "payment.verified" | "approval.request" | "approval.granted" | "approval.denied" | "system.health" | "system.register" | "system.deregister" | "system.credential.refresh";
+    interchangeCorrelationId?: string;
+    interchangeTenantId?: string;
+    interchangeAgentId?: string;
+    interchangeSessionId?: string;
+    interchangeOfferingId?: string;
+    interchangeSchemaVersion?: string;
+    traceparent?: string;
+    tracestate?: string;
+}, {}>;
+export type MailboxNotifyHeaders = typeof MailboxNotifyHeaders.infer;
 /**
  * Discriminated union of every control-channel payload kind. The
  * `type` discriminator namespaces the control-plane vocabulary so a
@@ -112,6 +147,7 @@ export declare const ControlPayload: import("arktype/internal/variants/object.ts
         runId: string;
         messageId: string;
         receivedAt: number;
+        payload: unknown;
     };
 } | {
     type: "signal.deliver";
@@ -151,16 +187,35 @@ export declare const ControlPayload: import("arktype/internal/variants/object.ts
             id: string;
             provider: string;
             baseURL: string;
-            apiKey: string;
+            credentialId: string;
             model: string;
             defaults?: {
                 maxTokens?: number;
                 providerOptions?: Record<string, unknown>;
             };
             capabilities?: string[];
+            quirks?: Record<string, unknown>;
         }[];
         defaultSource: string;
     };
+} | {
+    type: "credentials-updated";
+    data: {
+        delivery: {
+            bindings: {
+                handle: string;
+                credentialId: string;
+                consumer: string;
+            }[];
+            materials: {
+                credentialId: string;
+                providerKey: string;
+                origin: string;
+                secret: string;
+            }[];
+        };
+        revoke?: string[];
+    };
 } | {
     type: "ready";
     data: {
@@ -239,6 +294,7 @@ export declare const ControlPayload: import("arktype/internal/variants/object.ts
                 dataBase64: string;
             }[];
             inReplyTo?: string;
+            references?: string[];
             correlationId?: string;
             sessionId?: string;
             tenantId?: string;
@@ -269,6 +325,99 @@ export declare const ControlPayload: import("arktype/internal/variants/object.ts
             message: string;
         };
     };
+} | {
+    type: "park.notify";
+    data: {
+        runId: string;
+        correlationId: string;
+        parkKind: "approval" | "input" | "signal-relay";
+        snapshot?: {
+            name: string;
+            description: string;
+            inputSchema: Record<string, unknown>;
+            arguments: Record<string, unknown>;
+        };
+    };
+} | {
+    type: "parked-correlations.request";
+    data: {
+        requestId: string;
+    };
+} | {
+    type: "parked-correlations.response";
+    data: {
+        requestId: string;
+        parked: {
+            runId: string;
+            correlationId: string;
+            parkKind: "approval" | "input" | "signal-relay";
+            snapshot?: {
+                name: string;
+                description: string;
+                inputSchema: Record<string, unknown>;
+                arguments: Record<string, unknown>;
+            };
+        }[];
+    };
+} | {
+    type: "resumed.runs";
+    data: {
+        runIds: string[];
+    };
+} | {
+    type: "mailbox.notify";
+    data: {
+        runId: string;
+        mailbox: string;
+        uid: number;
+        headers: {
+            from: string;
+            to: string[];
+            date: string;
+            messageId: string;
+            cc?: string[];
+            inReplyTo?: string;
+            references?: string[];
+            subject?: string;
+            listId?: string;
+            interchangeType?: "conversation.message" | "conversation.join" | "conversation.leave" | "offering.request" | "offering.response" | "offering.error" | "offering.discover" | "offering.catalog" | "payment.required" | "payment.receipt" | "payment.verified" | "approval.request" | "approval.granted" | "approval.denied" | "system.health" | "system.register" | "system.deregister" | "system.credential.refresh";
+            interchangeCorrelationId?: string;
+            interchangeTenantId?: string;
+            interchangeAgentId?: string;
+            interchangeSessionId?: string;
+            interchangeOfferingId?: string;
+            interchangeSchemaVersion?: string;
+            traceparent?: string;
+            tracestate?: string;
+        };
+    };
+} | {
+    type: "mailbox.mutate.request";
+    data: {
+        requestId: string;
+        runId: string;
+        mailbox: string;
+        op: "addFlags" | "removeFlags";
+        uid: number;
+        flags: string[];
+    } | {
+        requestId: string;
+        runId: string;
+        mailbox: string;
+        op: "expunge";
+    };
+} | {
+    type: "mailbox.mutate.response";
+    data: {
+        requestId: string;
+        result: {
+            ok: true;
+            expungedUids?: number[];
+        } | {
+            ok: false;
+            reason: string;
+        };
+    };
 }, {}>;
 export type ControlPayload = typeof ControlPayload.infer;
 export interface NdjsonWriter {