@intx/workflow-host 0.3.0 → 0.4.0

package/dist/child/substrate-write-bridge.js

@@ -35,11 +35,13 @@
 // the closure produces, both base64-encoded.
 import { getLogger } from "@intx/log";
 import { base64Decode, base64Encode } from "@intx/types";
+import { createPendingRequestCore } from "./pending-request.js";
 const logger = getLogger(["workflow-host", "child", "substrate-write-bridge"]);
 /**
  * Construct the child-side substrate-write bridge. Pending writes
- * live in a map keyed by `requestId`; the bridge resolves the awaiter
- * when the supervisor's matching `substrate.write.response` lands.
+ * live in the shared pending-request core keyed by `requestId`; the
+ * bridge resolves the awaiter when the supervisor's matching
+ * `substrate.write.response` lands.
  *
  * The supervisor may emit zero or more `substrate.merge.request`
  * frames per pending write (the supervisor's merge callback may run
@@ -49,17 +51,17 @@ const logger = getLogger(["workflow-host", "child", "substrate-write-bridge"]);
  * pending entry stays alive until the terminal write response lands.
  */
 export function createChildSubstrateWriteBridge(opts) {
-    const pending = new Map();
-    const allocate = opts.allocateRequestId ?? defaultRequestIdAllocator();
+    const pending = createPendingRequestCore({
+        label: "workflow-child substrate write",
+        allocatorPrefix: "sw",
+        allocateRequestId: opts.allocateRequestId,
+    });
     return {
         get pendingCount() {
-            return pending.size;
+            return pending.pendingCount;
         },
         async submit(req) {
-            const requestId = allocate();
-            const resultPromise = new Promise((resolve, reject) => {
-                pending.set(requestId, { req, resolve, reject });
-            });
+            const { requestId, promise } = pending.register(req);
             try {
                 await opts.upstreamSender.send({
                     type: "substrate.write.request",
@@ -73,11 +75,10 @@ export function createChildSubstrateWriteBridge(opts) {
                 });
             }
             catch (cause) {
-                pending.delete(requestId);
-                const message = cause instanceof Error ? cause.message : String(cause);
-                throw new Error(`workflow-child substrate write: upstream send failed for requestId ${requestId}: ${message}`, { cause });
+                pending.discard(requestId);
+                throw pending.sendFailedError(requestId, cause);
             }
-            return resultPromise;
+            return promise;
         },
         handleMergeRequest(data) {
             const entry = pending.get(data.requestId);
@@ -93,7 +94,7 @@ export function createChildSubstrateWriteBridge(opts) {
                         requestId: data.requestId,
                         result: {
                             ok: false,
-                            reason: `workflow-child substrate write: no pending entry for requestId ${data.requestId}`,
+                            reason: pending.noPendingError(data.requestId).message,
                         },
                     },
                 })
@@ -106,7 +107,7 @@ export function createChildSubstrateWriteBridge(opts) {
             void (async () => {
                 try {
                     const existing = decodeMergeRequest(data.existing);
-                    const merged = await entry.req.merge(existing);
+                    const merged = await entry.meta.merge(existing);
                     const files = encodeFiles(merged);
                     await opts.upstreamSender.send({
                         type: "substrate.merge.response",
@@ -137,30 +138,26 @@ export function createChildSubstrateWriteBridge(opts) {
             })();
         },
         handleWriteResponse(data) {
-            const entry = pending.get(data.requestId);
+            const entry = pending.settle(data.requestId);
             if (entry === undefined) {
                 logger.warn `substrate.write.response landed with no pending entry; requestId=${data.requestId} dropped`;
                 return;
             }
-            pending.delete(data.requestId);
             if (data.result.ok) {
                 entry.resolve({ commitSha: data.result.commitSha });
                 return;
             }
-            entry.reject(new Error(`workflow-child substrate write (requestId=${data.requestId}) rejected by supervisor: ${data.result.reason}`));
+            entry.reject(pending.rejectedError(data.requestId, data.result.reason));
         },
         cancelAll(reason) {
-            for (const [requestId, entry] of pending) {
-                entry.reject(new Error(`workflow-child substrate write (requestId=${requestId}) cancelled: ${reason}`));
-            }
-            pending.clear();
+            pending.cancelAll(reason);
         },
     };
 }
 function decodeMergeRequest(existing) {
     const out = new Map();
     for (const entry of existing) {
-        out.set(entry.path, base64ToBytes(entry.contentBase64));
+        out.set(entry.path, base64Decode(entry.contentBase64));
     }
     return out;
 }
@@ -168,21 +165,7 @@ function encodeFiles(files) {
     const out = [];
     for (const [path, content] of Object.entries(files)) {
         const bytes = typeof content === "string" ? new TextEncoder().encode(content) : content;
-        out.push({ path, contentBase64: bytesToBase64(bytes) });
+        out.push({ path, contentBase64: base64Encode(bytes) });
     }
     return out;
 }
-function bytesToBase64(bytes) {
-    return base64Encode(bytes);
-}
-function base64ToBytes(value) {
-    return base64Decode(value);
-}
-function defaultRequestIdAllocator() {
-    let counter = 0;
-    return () => {
-        counter += 1;
-        const rand = Math.random().toString(36).slice(2, 10);
-        return `sw-${String(counter)}-${rand}`;
-    };
-}

package/dist/child/supervisor-backed-transport.d.ts

@@ -1,10 +1,56 @@
-import type { MessageTransport } from "@intx/types/runtime";
+import type { CryptoProvider, MessageTransport } from "@intx/types/runtime";
+import type { ChildMailboxReader } from "./child-mailbox-reader.js";
+import type { ChildMailboxMutationBridge } from "./mailbox-mutation-bridge.js";
+import type { MailboxWatchRegistry } from "./mailbox-watch-registry.js";
 import type { ChildOutboundMailBridge } from "./outbound-mail-bridge.js";
+/**
+ * The dependencies backing the transport's whole inbox capability: the local
+ * IMAP READ surface (`reader` / `watchRegistry` / `getCrypto`) that resolves
+ * against the deployment's substrate mailbox, plus the routed-WRITE channel
+ * (`mutationBridge`) that carries flag writes and expunge up to the supervisor.
+ * The sidecar wires the bundle only for a build that owns an inbound mailbox
+ * (the warm agent); a build without it has no inbox and every inbound method
+ * throws a clear "not wired" error. Reads are local; writes route upstream --
+ * the child never flushes the run ref, so it never races the supervisor.
+ */
+export interface SupervisorBackedTransportInbound {
+    /**
+     * Opens a fresh committed snapshot of the deployment's substrate `INBOX`.
+     * Every inbound read opens a new snapshot, so a read taken after a
+     * `mailbox.notify` -- or after a routed write the supervisor flushed before
+     * replying -- observes the committed state.
+     */
+    reader: ChildMailboxReader;
+    /**
+     * The registry the child's control loop fires `mailbox.notify` into. It must
+     * be the same instance `runWorkflowChild` routes the frame to, so a `watch`
+     * installed here observes the supervisor's notification.
+     */
+    watchRegistry: MailboxWatchRegistry;
+    /**
+     * Resolve a sender address to its `CryptoProvider` so `fetchFull` can verify
+     * the message signature. Returns `undefined` when no key is known for the
+     * sender, in which case the signature status is reported as `unknown`.
+     */
+    getCrypto: (fromAddress: string) => CryptoProvider | undefined;
+    /**
+     * The upstream channel the write methods route through. `setFlags` /
+     * `clearFlags` / `expunge` call `mutationBridge.submit`, which emits a
+     * `mailbox.mutate.request` and resolves once the supervisor applies the
+     * mutation to its owned store and replies. Bundled with the read surface
+     * because the write methods and the reads share one presence condition:
+     * this agent owns an inbox, or it owns none.
+     */
+    mutationBridge: ChildMailboxMutationBridge;
+}
 /**
  * Construct a `MessageTransport` whose outbound side routes through the
- * supervisor (via `bridge`) and whose inbound side is inert. `address`
- * is the agent's mail address; the supervisor signs the outbound mail as
- * this address through the host transport, so it must be the address the
- * host registered the agent's `CryptoProvider` against.
+ * supervisor (via `bridge`) and whose inbound side is a local IMAP read
+ * surface over `inbound`. `address` is the agent's mail address; the
+ * supervisor signs the outbound mail as this address through the host
+ * transport, so it must be the address the host registered the agent's
+ * `CryptoProvider` against. When `inbound` is omitted, the inbound methods
+ * throw a clear "not wired" error; the sidecar supplies it once the child's
+ * mailbox reader and watch registry are threaded through.
  */
-export declare function createSupervisorBackedTransport(bridge: ChildOutboundMailBridge, address: string): MessageTransport;
+export declare function createSupervisorBackedTransport(bridge: ChildOutboundMailBridge, address: string, inbound?: SupervisorBackedTransportInbound): MessageTransport;

package/dist/child/supervisor-backed-transport.js

@@ -1,35 +1,80 @@
 // Supervisor-backed `MessageTransport` for a unified-host step agent
-// (OUTBOUND half of mailbox ownership, §3a).
+// (both halves of mailbox ownership, §3a OUTBOUND and §3b INBOUND).
 //
 // Under the unified host the supervisor is the sole mail owner: it holds
 // the durable inbox and the host transport against which the agent's
 // address is registered with its signing key. The step agent therefore
-// does NOT subscribe its own transport for inbound mail (the supervisor
-// delivers inputs via the step path) and does NOT hold a signing key to
-// send outbound mail. Its mail tools are backed by this transport:
+// does NOT hold a signing key to send outbound mail, and it does NOT own
+// the host-side inbox directly. Its mail tools are backed by this
+// transport:
 //
-//   - INBOUND is a no-op. `watch` returns a no-op unsubscribe and never
-//     fires; the supervisor delivers the agent's input as the step
-//     input, not through the agent's own mailbox. The IMAP read surface
-//     (`search`, `fetchFull`, `fetchHeaders`, ...) throws: the agent
-//     owns no mailbox in the unified host, so a read against one is a
-//     programming error, surfaced loudly rather than returning a
-//     silently-empty result that would hide the missing inbound surface.
-//   - OUTBOUND (`send` / `append`) routes through the supervisor over
-//     the control IPC via the outbound-mail bridge. The supervisor
-//     performs the actual signed send through the host transport, so the
-//     outbound mail carries the agent's signature with full parity to
-//     the in-process path. The agent never holds the key.
+//   - INBOUND is a functional local IMAP read surface once the sidecar
+//     wires it (the `inbound` constructor argument). The supervisor
+//     commits an arrived message to the deployment's workflow-run
+//     substrate mailbox (`mailbox/INBOX/`) and fires a `mailbox.notify`
+//     control frame. The read surface (`search`, `thread`,
+//     `fetchHeaders`, `fetchStructure`, `fetchPart`, `fetchFull`, `sync`,
+//     `getMailboxStatus`) answers by opening a fresh committed snapshot of
+//     that mailbox through the child mailbox reader and running the
+//     `@intx/mailbox` pure query functions over it -- local, no hub or
+//     IPC round-trip. `watch` registers into the child watch registry, so
+//     `mail_wait` unblocks when the routed `mailbox.notify` fires. The
+//     WRITE methods (`setFlags` / `clearFlags` / `expunge`) do NOT touch
+//     the local read surface: they route up to the supervisor through the
+//     mailbox-mutation bridge (a `mailbox.mutate.request` frame), which
+//     applies the mutation to the supervisor's owned store and replies.
+//     The child never flushes the run ref, so it never races the
+//     supervisor's mirror. The agent owns only the `INBOX`, so every
+//     inbound method rejects a request for any other mailbox rather than
+//     silently serving `INBOX` under the wrong name. When the sidecar
+//     constructs the transport without the `inbound` argument, the inbound
+//     methods throw a clear "not wired" error rather than answer against a
+//     missing surface.
+//   - OUTBOUND (`send`) routes through the supervisor over the control
+//     IPC via the outbound-mail bridge. The supervisor performs the
+//     actual signed send through the host transport, so the outbound mail
+//     carries the agent's signature with full parity to the in-process
+//     path. The agent never holds the key.
+//
+// A handful of methods stay unsupported and throw: they act on a resource
+// the unified-host agent does not own. `append` and the mailbox-management
+// methods (`listMailboxes` / `createMailbox` / `deleteMailbox`) target a
+// mailbox the agent does not own; `move` / `copy` need a second mailbox it
+// does not own; and the distribution-list methods are unimplemented across
+// every transport.
+import { executeSearch, executeThread, fetchFull as doFetchFull, fetchHeaders as doFetchHeaders, fetchPart as doFetchPart, fetchStructure as doFetchStructure, } from "@intx/mailbox";
+import { deriveWorkflowRunId } from "@intx/types";
+import { MAILBOX_INBOX_DIR } from "../adapters/substrate-mailbox-store.js";
 /**
  * Construct a `MessageTransport` whose outbound side routes through the
- * supervisor (via `bridge`) and whose inbound side is inert. `address`
- * is the agent's mail address; the supervisor signs the outbound mail as
- * this address through the host transport, so it must be the address the
- * host registered the agent's `CryptoProvider` against.
+ * supervisor (via `bridge`) and whose inbound side is a local IMAP read
+ * surface over `inbound`. `address` is the agent's mail address; the
+ * supervisor signs the outbound mail as this address through the host
+ * transport, so it must be the address the host registered the agent's
+ * `CryptoProvider` against. When `inbound` is omitted, the inbound methods
+ * throw a clear "not wired" error; the sidecar supplies it once the child's
+ * mailbox reader and watch registry are threaded through.
  */
-export function createSupervisorBackedTransport(bridge, address) {
-    function inboundUnsupported(method) {
-        throw new Error(`supervisor-backed transport: ${method} is not supported for unified-host step agent ${address}; the supervisor owns the mailbox and delivers inbound mail as the step input`);
+export function createSupervisorBackedTransport(bridge, address, inbound) {
+    function unsupported(method) {
+        throw new Error(`supervisor-backed transport: ${method} is not supported for unified-host step agent ${address}; the supervisor owns the mailbox and the agent owns only its own ${MAILBOX_INBOX_DIR}`);
+    }
+    // Return the wired inbound surface, or fail loud when the sidecar
+    // constructed the transport without it -- an inbound read against a missing
+    // surface is a wiring error, not a silently-empty result.
+    function requireInbound(method) {
+        if (inbound === undefined) {
+            throw new Error(`supervisor-backed transport: ${method} needs the inbound surface, but it is not wired for unified-host step agent ${address}; the sidecar must construct the transport with its mailbox reader, watch registry, and crypto`);
+        }
+        return inbound;
+    }
+    // The unified-host agent owns exactly one mailbox, the substrate `INBOX`
+    // the reader opens. Reject any other name rather than serve `INBOX` under
+    // it, which would return the wrong mailbox's messages mislabeled.
+    function requireInbox(mailbox) {
+        if (mailbox !== MAILBOX_INBOX_DIR) {
+            throw new Error(`supervisor-backed transport: unified-host step agent ${address} owns only the "${MAILBOX_INBOX_DIR}" mailbox; "${mailbox}" is not available`);
+        }
     }
     return {
         async send(message, _signal) {
@@ -39,75 +84,173 @@ export function createSupervisorBackedTransport(bridge, address) {
             // `append` writes into a mailbox the agent owns; in the unified
             // host the agent owns none. The mail tools do not append (they
             // `send`), so a reachable `append` is a programming error.
-            return inboundUnsupported("append");
+            return unsupported("append");
         },
         async listMailboxes(_signal) {
-            return inboundUnsupported("listMailboxes");
+            return unsupported("listMailboxes");
         },
         async createMailbox(_name, _signal) {
-            return inboundUnsupported("createMailbox");
+            return unsupported("createMailbox");
         },
         async deleteMailbox(_name, _signal) {
-            return inboundUnsupported("deleteMailbox");
+            return unsupported("deleteMailbox");
         },
-        async getMailboxStatus(_name, _signal) {
-            return inboundUnsupported("getMailboxStatus");
+        async getMailboxStatus(name, _signal) {
+            const { reader } = requireInbound("getMailboxStatus");
+            requireInbox(name);
+            const store = await reader.open();
+            const unseen = store.messages.filter((m) => !m.flags.has("\\Seen")).length;
+            return {
+                total: store.messages.length,
+                unseen,
+                recent: 0,
+                uidNext: store.uidNext,
+                uidValidity: store.uidValidity,
+                highestModSeq: store.highestModSeq,
+            };
         },
-        async search(_mailbox, _query, _signal) {
-            return inboundUnsupported("search");
+        async search(mailbox, query, _signal) {
+            const { reader } = requireInbound("search");
+            requireInbox(mailbox);
+            const store = await reader.open();
+            return await executeSearch(mailbox, store, query);
         },
-        async thread(_mailbox, _algorithm, _query, _signal) {
-            return inboundUnsupported("thread");
+        async thread(mailbox, algorithm, query, _signal) {
+            const { reader } = requireInbound("thread");
+            requireInbox(mailbox);
+            const store = await reader.open();
+            return await executeThread(mailbox, store, algorithm, query);
         },
-        async fetchHeaders(_ref, _signal) {
-            return inboundUnsupported("fetchHeaders");
+        async fetchHeaders(ref, _signal) {
+            const { reader } = requireInbound("fetchHeaders");
+            requireInbox(ref.mailbox);
+            const store = await reader.open();
+            return await doFetchHeaders(ref, store);
         },
-        async fetchStructure(_ref, _signal) {
-            return inboundUnsupported("fetchStructure");
+        async fetchStructure(ref, _signal) {
+            const { reader } = requireInbound("fetchStructure");
+            requireInbox(ref.mailbox);
+            const store = await reader.open();
+            return await doFetchStructure(ref, store);
         },
-        async fetchPart(_ref, _partPath, _signal) {
-            return inboundUnsupported("fetchPart");
+        async fetchPart(ref, partPath, _signal) {
+            const { reader } = requireInbound("fetchPart");
+            requireInbox(ref.mailbox);
+            const store = await reader.open();
+            return await doFetchPart(ref, partPath, store);
         },
-        async fetchFull(_ref, _signal) {
-            return inboundUnsupported("fetchFull");
+        async fetchFull(ref, _signal) {
+            const { reader, getCrypto } = requireInbound("fetchFull");
+            requireInbox(ref.mailbox);
+            const store = await reader.open();
+            return await doFetchFull(ref, store, getCrypto);
         },
-        async setFlags(_ref, _flags, _signal) {
-            return inboundUnsupported("setFlags");
+        async setFlags(ref, flags, _signal) {
+            const { mutationBridge } = requireInbound("setFlags");
+            requireInbox(ref.mailbox);
+            // Route the flag write to the supervisor -- the sole mailbox writer --
+            // rather than flushing a second store against the run ref. `submit`
+            // resolves only after the supervisor flushes, so a subsequent read
+            // observes the flag.
+            await mutationBridge.submit({
+                runId: deriveWorkflowRunId(address),
+                mailbox: ref.mailbox,
+                op: "addFlags",
+                uid: ref.uid,
+                flags,
+            });
         },
-        async clearFlags(_ref, _flags, _signal) {
-            return inboundUnsupported("clearFlags");
+        async clearFlags(ref, flags, _signal) {
+            const { mutationBridge } = requireInbound("clearFlags");
+            requireInbox(ref.mailbox);
+            await mutationBridge.submit({
+                runId: deriveWorkflowRunId(address),
+                mailbox: ref.mailbox,
+                op: "removeFlags",
+                uid: ref.uid,
+                flags,
+            });
         },
         async move(_ref, _toMailbox, _signal) {
-            return inboundUnsupported("move");
+            return unsupported("move");
         },
         async copy(_ref, _toMailbox, _signal) {
-            return inboundUnsupported("copy");
+            return unsupported("copy");
         },
-        async expunge(_mailbox, _signal) {
-            return inboundUnsupported("expunge");
+        async expunge(mailbox, _signal) {
+            const { mutationBridge } = requireInbound("expunge");
+            requireInbox(mailbox);
+            // Route to the supervisor, which sweeps every `\Deleted` message out of
+            // its owned INBOX and returns the swept uids. The expunged bytes survive
+            // in git history (a workflow-run repo's objects are never GC'd), so the
+            // replication check permits the deletion. A caller expunging after a
+            // `setFlags(\Deleted)` MUST await the two in sequence -- the supervisor
+            // applies mutations in arrival order, so an unawaited (concurrent) pair
+            // could let the sweep run before the flag is set and miss the message.
+            const result = await mutationBridge.submit({
+                runId: deriveWorkflowRunId(address),
+                mailbox,
+                op: "expunge",
+            });
+            return { expungedUids: result.expungedUids ?? [] };
         },
-        watch(_mailbox, _callback) {
-            // Inbound delivery is a no-op: the supervisor delivers the agent's
-            // input as the step input, not through the agent's mailbox. The
-            // watch never fires; return a no-op unsubscribe so a mail tool that
-            // installs a watch (mail_wait) does not throw at install time but
-            // also never observes a spurious event.
-            return () => undefined;
+        watch(mailbox, callback) {
+            const { watchRegistry } = requireInbound("watch");
+            requireInbox(mailbox);
+            // The supervisor -- the sole mail owner -- fires `mailbox.notify` into
+            // the registry when new mail lands; the registry delivers the typed
+            // event to this callback. `mail_wait` installs the watch and unblocks on
+            // the first delivery.
+            return watchRegistry.watch(mailbox, callback);
         },
-        async sync(_mailbox, _knownState, _signal) {
-            return inboundUnsupported("sync");
+        async sync(mailbox, knownState, _signal) {
+            const { reader } = requireInbound("sync");
+            requireInbox(mailbox);
+            const store = await reader.open();
+            const result = store.sync({
+                uidValidity: knownState.uidValidity,
+                highestModSeq: knownState.highestModSeq,
+            });
+            if (result.resync) {
+                return {
+                    vanished: [],
+                    changed: [],
+                    newMessages: result.messages.map((m) => ({ uid: m.uid, mailbox })),
+                    fullResyncRequired: true,
+                };
+            }
+            // The backing reports every message whose modseq advanced past the
+            // client's known state as `changed`. Split it against the client's known
+            // `uidNext`: a uid at or beyond it is a new arrival, one below it is a
+            // flag change on a message the client already held.
+            const newMessages = [];
+            const changed = [];
+            for (const m of result.changed) {
+                if (m.uid >= knownState.uidNext) {
+                    newMessages.push({ uid: m.uid, mailbox });
+                }
+                else {
+                    changed.push({ uid: m.uid, flags: Array.from(m.flags) });
+                }
+            }
+            return {
+                vanished: [...result.vanished],
+                changed,
+                newMessages,
+                fullResyncRequired: false,
+            };
         },
         async createList(_address, _name, _signal) {
-            return inboundUnsupported("createList");
+            return unsupported("createList");
         },
         async listMembers(_address, _signal) {
-            return inboundUnsupported("listMembers");
+            return unsupported("listMembers");
         },
         async subscribe(_listAddress, _subscriberAddress, _signal) {
-            return inboundUnsupported("subscribe");
+            return unsupported("subscribe");
         },
         async unsubscribe(_listAddress, _subscriberAddress, _signal) {
-            return inboundUnsupported("unsubscribe");
+            return unsupported("unsubscribe");
         },
     };
 }

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