@intx/workflow-host 0.3.0 → 0.4.0

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,11 +1,12 @@
-export { loadWorkflowDefinitionFromClosure, loadWorkflowDirectorRegistryFromClosure, loadWorkflowPluginFactoriesFromClosure, loadWorkflowPluginToolDefinitionsFromClosure, type LoadWorkflowDefinitionFromClosureArgs, type LoadWorkflowDirectorRegistryFromClosureArgs, type LoadWorkflowPluginsFromClosureArgs, } from "./workflow-definition-loader.js";
+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 { 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 CredentialWiring, type DiscoverRunsOpts, type DiscoveredRun, type DrainController, type GrantEvaluator, type LoadParkedApproval, 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,11 +1,12 @@
-export { loadWorkflowDefinitionFromClosure, loadWorkflowDirectorRegistryFromClosure, loadWorkflowPluginFactoriesFromClosure, loadWorkflowPluginToolDefinitionsFromClosure, } from "./workflow-definition-loader.js";
+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 { 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,7 +44,7 @@ export declare const SourcesUpdatedData: import("arktype/internal/variants/objec
         id: string;
         provider: string;
         baseURL: string;
-        apiKey: string;
+        credentialId: string;
         model: string;
         defaults?: {
             maxTokens?: number;
@@ -95,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
@@ -113,6 +147,7 @@ export declare const ControlPayload: import("arktype/internal/variants/object.ts
         runId: string;
         messageId: string;
         receivedAt: number;
+        payload: unknown;
     };
 } | {
     type: "signal.deliver";
@@ -152,7 +187,7 @@ 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;
@@ -179,6 +214,7 @@ export declare const ControlPayload: import("arktype/internal/variants/object.ts
                 secret: string;
             }[];
         };
+        revoke?: string[];
     };
 } | {
     type: "ready";
@@ -258,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;
@@ -327,6 +364,60 @@ export declare const ControlPayload: import("arktype/internal/variants/object.ts
     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 {

package/dist/ipc/control-channel.js

@@ -127,10 +127,43 @@ export const OutboundMessagePayload = type({
     "summary?": "string",
     "attachments?": OutboundAttachmentPayload.array(),
     "inReplyTo?": "string",
+    "references?": "string[]",
     "correlationId?": "string",
     "sessionId?": "string",
     "tenantId?": "string",
 });
+/**
+ * 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 const MailboxNotifyHeaders = type({
+    from: "string",
+    to: "string[]",
+    "cc?": "string[]",
+    date: "string",
+    messageId: "string",
+    "inReplyTo?": "string",
+    "references?": "string[]",
+    "subject?": "string",
+    "listId?": "string",
+    "interchangeType?": InterchangeType,
+    "interchangeCorrelationId?": "string",
+    "interchangeTenantId?": "string",
+    "interchangeAgentId?": "string",
+    "interchangeSessionId?": "string",
+    "interchangeOfferingId?": "string",
+    "interchangeSchemaVersion?": "string",
+    "traceparent?": "string",
+    "tracestate?": "string",
+});
 /**
  * Discriminated union of every control-channel payload kind. The
  * `type` discriminator namespaces the control-plane vocabulary so a
@@ -138,14 +171,22 @@ export const OutboundMessagePayload = type({
  * union and not by widening the envelope shape. Inference events
  * NEVER appear here; they ride the event channel.
  */
-export const ControlPayload = type({
+export const ControlPayload = type.or({
     type: "'trigger.fire'",
     data: {
         runId: "string",
         messageId: "string",
         receivedAt: "number",
+        // The run's inbound-mail input, resolved by the supervisor (the sole
+        // mail owner) before the frame: a decoded `Mail` (headers plus part
+        // descriptors that reference the part bytes committed to the workflow-run
+        // substrate). The child hands this straight to the runtime as the trigger
+        // payload. Refs, not raw mail bytes, ride here; the committed part files
+        // stay in the substrate. Typed `unknown` -- `Mail` is a nested structural
+        // type validated at the consumption boundary by `isMail`.
+        payload: "unknown",
     },
-}, "|", {
+}, {
     type: "'signal.deliver'",
     data: {
         runId: "string",
@@ -154,25 +195,23 @@ export const ControlPayload = type({
         // The resume decision in FINAL form -- the child commits it as the
         // SignalReceived payload verbatim. Each sender owns any
         // provenance-specific preparation BEFORE this frame: the dispatch loop
-        // resolves an inbound mail to conversation text (like the turn-1
-        // trigger), while `deliverSignal` ships a structured signal payload
-        // unchanged. Do NOT ship raw inbound mail bytes through here.
+        // resolves an inbound mail to a decoded `Mail` (headers plus part
+        // references, like the turn-1 trigger), while `deliverSignal` ships a
+        // structured signal payload unchanged -- so this field stays
+        // polymorphic. Do NOT ship raw inbound mail bytes through here.
         payload: "unknown",
     },
-})
-    .or({
+}, {
     type: "'drain'",
     data: {
         deadlineMs: "number",
     },
-})
-    .or({
+}, {
     type: "'shutdown'",
     data: {
         reason: "string",
     },
-})
-    .or({
+}, {
     type: "'grants-updated'",
     data: {
         /**
@@ -194,24 +233,28 @@ export const ControlPayload = type({
          */
         "stepHashes?": "Record<string, string>",
     },
-})
-    .or({
+}, {
     type: "'sources-updated'",
     data: SourcesUpdatedData,
-})
-    .or({
-    // Refreshed credential material for the deployment's tools. The child
-    // replaces its in-memory material cell wholesale on receive; a revoked
-    // credential arrives by omission (its material entry is absent) so the
-    // swap evicts it. Carried inline like the grants and sources snapshots --
-    // single-producer supervisor, single-consumer child. The secret rides
-    // this frame and the in-memory cell only; it is never persisted.
+}, {
+    // Refreshed credential material for the deployment's inference sources and
+    // tools. The child MERGES this into its in-memory cell (see
+    // `mergeCredentialDelivery`): `delivery.materials` upsert by credentialId
+    // and `delivery.bindings` upsert by (consumer, handle); `revoke` names
+    // credentialIds to drop, and dropping one drops every binding referencing
+    // it. Merge rather than wholesale-replace because the cell has several
+    // independently-scoped producers (the deploy frame, an inference rotation,
+    // a tool-grant push), each carrying only its own slice -- a swap would let
+    // one evict another's credentials. Revocation is therefore explicit, never
+    // by omission. Carried inline like the grants and sources snapshots. The
+    // secret rides this frame and the in-memory cell only; it is never
+    // persisted.
     type: "'credentials-updated'",
     data: {
         delivery: CredentialDelivery,
+        "revoke?": "string[]",
     },
-})
-    .or({
+}, {
     type: "'ready'",
     data: {
         childPid: "number",
@@ -223,8 +266,7 @@ export const ControlPayload = type({
          */
         childPublicKey: "string",
     },
-})
-    .or({
+}, {
     // Child-initiated request to recycle the workflow-process. The
     // child emits this when its own self-check decides it needs to be
     // recycled (an internal consistency error it can't recover from,
@@ -238,8 +280,7 @@ export const ControlPayload = type({
     data: {
         reason: "string",
     },
-})
-    .or({
+}, {
     // Child-initiated `writeTreePreservingPrefix` request. The child
     // does not hold a substrate write authority for the workflow-run
     // repo (single-writer at the ref tip belongs to the supervisor);
@@ -262,8 +303,7 @@ export const ControlPayload = type({
         preservePrefix: "string > 0",
         message: "string > 0",
     },
-})
-    .or({
+}, {
     // Supervisor-initiated request for the child's merge bytes. Fired
     // from inside the supervisor's `writeTreePreservingPrefix` merge
     // callback while the per-repo lock is held; the child receives the
@@ -280,8 +320,7 @@ export const ControlPayload = type({
             contentBase64: "string",
         }).array(),
     },
-})
-    .or({
+}, {
     // Child's merge result. `requestId` correlates with the
     // `substrate.write.request` that started the write; the supervisor
     // resumes its merge callback with the supplied entries (or
@@ -300,8 +339,7 @@ export const ControlPayload = type({
             reason: "string > 0",
         }),
     },
-})
-    .or({
+}, {
     // Supervisor's terminal reply to a child's `substrate.write.request`.
     // The `requestId` echoes the child's allocated correlation id so
     // the child's pending-id map resolves the awaiter. A successful
@@ -321,8 +359,7 @@ export const ControlPayload = type({
             reason: "string > 0",
         }),
     },
-})
-    .or({
+}, {
     // Child-initiated outbound-mail request (OUTBOUND half of mailbox
     // ownership, §3a). The workflow-process child never holds the
     // agent's signing key and never calls `transport.send` itself. When
@@ -348,8 +385,7 @@ export const ControlPayload = type({
         "mailbox?": "string",
         message: OutboundMessagePayload,
     },
-})
-    .or({
+}, {
     // Supervisor's terminal reply to a child's `outbound.message`. The
     // `requestId` echoes the child's correlation id so the child's
     // pending mail-tool awaiter resolves. A successful send surfaces the
@@ -369,8 +405,7 @@ export const ControlPayload = type({
             reason: "string > 0",
         }),
     },
-})
-    .or({
+}, {
     // Child-initiated terminal-run notification. The workflow-process
     // child emits this when one of its runs reaches a terminal phase
     // (`RunCompleted`, `RunFailed`, `RunCancelled`) so the supervisor's
@@ -396,8 +431,7 @@ export const ControlPayload = type({
             message: "string",
         },
     },
-})
-    .or({
+}, {
     // Child-initiated control-plane suspension notification. The
     // workflow-process child emits this when a workflow agent step parks
     // on a reserved `signalName(correlationId)` channel (`env.onPark`),
@@ -421,8 +455,7 @@ export const ControlPayload = type({
         // process boundary. Optional: only an ask-rail suspension carries one.
         "snapshot?": BoundedApprovalSnapshot,
     },
-})
-    .or({
+}, {
     // Supervisor-initiated request: enumerate the child's currently-parked
     // approval correlations. The supervisor fires this after a
     // re-establishment (child respawn, or hub-link reconnect fanned out to
@@ -437,8 +470,7 @@ export const ControlPayload = type({
     data: {
         requestId: "string > 0",
     },
-})
-    .or({
+}, {
     // Child's reply to `parked-correlations.request`. Each entry mirrors
     // `park.notify`'s data -- the child-supplied half of a
     // `SuspensionRegistration` the supervisor stamps its deployment identity
@@ -460,8 +492,7 @@ export const ControlPayload = type({
             "snapshot?": BoundedApprovalSnapshot,
         }).array(),
     },
-})
-    .or({
+}, {
     // Child reports self-discovered runs after reconnect or recycle.
     // The supervisor seeds its cohort tracking from these runIds so
     // drain accumulators and dispatch routing account for runs the
@@ -470,6 +501,75 @@ export const ControlPayload = type({
     data: {
         runIds: type("string > 0").array(),
     },
+}, {
+    // Supervisor-to-child one-way notification that new mail landed in a
+    // deployment mailbox (INBOUND half of mailbox ownership, §3b). One-way
+    // like `grants-updated`/`sources-updated`: no correlation id, no response.
+    // The supervisor -- the sole mail owner -- commits the arrived message to
+    // the workflow-run substrate mailbox, then fires this frame so the child's
+    // warm-agent `watch`/`mail_wait` observes the arrival decoupled from the
+    // FIFO trigger dispatch that resolves a run's first input. `headers` rides
+    // inline so a watcher gets the `exists` `MailboxEvent`'s envelope without a
+    // substrate round-trip. The child reads the latest committed mailbox state
+    // regardless, so the frame carries no commit pin.
+    type: "'mailbox.notify'",
+    data: {
+        runId: "string > 0",
+        mailbox: "string > 0",
+        uid: "number >= 1",
+        headers: MailboxNotifyHeaders,
+    },
+}, {
+    // Child-initiated mailbox-mutation request (INBOUND half of mailbox
+    // ownership, §3b). The supervisor is the sole writer to the
+    // workflow-run mailbox: a step agent reads its INBOX locally but
+    // every mutation -- flag writes and `expunge` -- routes up here so
+    // the supervisor applies it to its owned store. A child flushing the
+    // same ref would race the supervisor's in-memory mirror and break
+    // uid / modseq monotonicity.
+    //
+    // `data` is discriminated on `op`: an `addFlags` / `removeFlags`
+    // carries the target `uid` and the `flags` to change, so the wire
+    // boundary rejects a flag frame that omits them; an `expunge` sweeps
+    // every `\Deleted` message in the mailbox and the child constructs it
+    // with neither. `requestId` correlates the supervisor's
+    // `mailbox.mutate.response` reply.
+    type: "'mailbox.mutate.request'",
+    data: type({
+        requestId: "string > 0",
+        runId: "string > 0",
+        mailbox: "string > 0",
+        op: "'addFlags' | 'removeFlags'",
+        uid: "number >= 1",
+        flags: "string[]",
+    }, "|", {
+        requestId: "string > 0",
+        runId: "string > 0",
+        mailbox: "string > 0",
+        op: "'expunge'",
+    }),
+}, {
+    // Supervisor's terminal reply to a child's `mailbox.mutate.request`.
+    // The `requestId` echoes the child's correlation id so the child's
+    // pending mail-tool awaiter resolves. The reply is sent only after
+    // the supervisor flushes the mutation, so the child's next committed
+    // read observes it -- the same flush-before-signal ordering
+    // `mailbox.notify` relies on. A successful `expunge` carries the
+    // `expungedUids` it swept so the agent tool can report the count; a
+    // flag write carries no operand echo. A failed mutation (unknown
+    // uid, substrate fault) surfaces a structured `{ ok: false, reason }`
+    // the child's bridge rethrows so the mail-tool call fails loudly.
+    type: "'mailbox.mutate.response'",
+    data: {
+        requestId: "string > 0",
+        result: type({
+            ok: "true",
+            "expungedUids?": "number[]",
+        }, "|", {
+            ok: "false",
+            reason: "string > 0",
+        }),
+    },
 });
 /**
  * Construct the supervisor-side control-channel sender. The

package/dist/ipc/index.d.ts

@@ -1,4 +1,4 @@
-export { ControlPayload, OutboundAttachmentPayload, OutboundMessagePayload, SourcesUpdatedData, createControlChannelSender, receiveControlChannel, type ControlChannelSender, type ControlChannelSenderOpts, type ControlChannelReceiverOpts, type NdjsonReader, type NdjsonWriter, } from "./control-channel.js";
+export { ControlPayload, MailboxNotifyHeaders, OutboundAttachmentPayload, OutboundMessagePayload, SourcesUpdatedData, createControlChannelSender, receiveControlChannel, type ControlChannelSender, type ControlChannelSenderOpts, type ControlChannelReceiverOpts, type NdjsonReader, type NdjsonWriter, } from "./control-channel.js";
 export { DEFAULT_EVENT_BUFFER_LIMIT, EventPayload, createEventChannelSender, receiveEventChannel, type EventChannelSender, type EventChannelSenderOpts, type EventChannelReceiverOpts, type FrameReader, type FrameWriter, } from "./event-channel.js";
 export { FrameEnvelope, MacedEnvelope, SignedEnvelope, decodeEnvelope, encodeEnvelope, } from "./envelope.js";
 export { IPC_CRYPTO, generateChannelId, generateHmacKey, signEd25519, signHmac, verifyEd25519, verifyHmac, } from "./crypto.js";

package/dist/ipc/index.js

@@ -137,7 +137,7 @@
 //    from env, the supervisor enforces.
 //
 // =============================================================
-export { ControlPayload, OutboundAttachmentPayload, OutboundMessagePayload, SourcesUpdatedData, createControlChannelSender, receiveControlChannel, } from "./control-channel.js";
+export { ControlPayload, MailboxNotifyHeaders, OutboundAttachmentPayload, OutboundMessagePayload, SourcesUpdatedData, createControlChannelSender, receiveControlChannel, } from "./control-channel.js";
 export { DEFAULT_EVENT_BUFFER_LIMIT, EventPayload, createEventChannelSender, receiveEventChannel, } from "./event-channel.js";
 export { FrameEnvelope, MacedEnvelope, SignedEnvelope, decodeEnvelope, encodeEnvelope, } from "./envelope.js";
 export { IPC_CRYPTO, generateChannelId, generateHmacKey, signEd25519, signHmac, verifyEd25519, verifyHmac, } from "./crypto.js";