@intx/workflow-host 0.3.0 → 0.4.0

package/dist/adapters/substrate-mailbox-store.js

@@ -0,0 +1,404 @@
+// Workflow-run-substrate backing for the `@intx/mailbox` `MailboxStore`.
+//
+// The `MailboxStore` mutation surface is SYNCHRONOUS, but the workflow-run
+// substrate is an async git store. This backing follows the shape of an IMAP
+// client with a local cache: the async `createSubstrateMailboxStore` factory
+// loads the committed `mailbox/INBOX/` METADATA (`index.json`) into an
+// in-memory mirror on open, exposes the synchronous mutation surface over that
+// mirror, and persists the current state back to the substrate through
+// `flush`. Callers mutate synchronously (append / addFlags / removeFlags /
+// remove) and `await flush()` at a boundary.
+//
+// The per-message raw RFC 2822 bytes are NOT loaded on open and are NOT held
+// resident: `readRaw(uid)` reads a message's `<uid>.eml` blob on demand from
+// the committed-read snapshot the open pinned. The only raw this backing keeps
+// in memory is that of a message appended-but-not-yet-flushed; a successful
+// `flush` drops it. So the resident footprint of a long-lived warm mailbox is
+// bounded to metadata regardless of how much mail it has accumulated.
+//
+// On-disk layout, a top-level subtree of the workflow-run repo (one mailbox per
+// deployment repo):
+//
+//   mailbox/INBOX/index.json      committed metadata: uidValidity, the
+//                                 uid/modseq counters, one entry per live
+//                                 message (uid, modseq, flags, pre-parsed
+//                                 envelope), and the expunged-uid tombstones
+//                                 QRESYNC answers `vanished` from.
+//   mailbox/INBOX/<uid>.eml       the verbatim raw RFC 2822 bytes of each live
+//                                 message, so `fetchFull` verifies signatures
+//                                 byte-exactly. Write-once per uid.
+//
+// Reads resolve from the committed substrate (`openCommittedReads`), never the
+// lagging working tree, matching the sibling `mail-part-store` reader. Writes
+// go through `writeTreeDelta`: `index.json` changes on every mutation and is
+// always put; each `<uid>.eml` is immutable, so a flush puts only the blobs
+// appended since the last successful flush and deletes only those whose
+// message was removed since then, and the substrate carries every untouched
+// `.eml` forward by object id. This keeps a flush O(delta) rather than
+// O(mailbox), so a long-lived warm conversational mailbox does not re-hash its
+// whole history on each append or flag change. The committed subtree the delta
+// leaves behind is byte-identical in shape to a full rewrite of the same live
+// set. The kind handler's push-time validation of this subtree is owned
+// separately by the hub replication layer; this module owns the on-disk shape
+// it validates.
+import { type } from "arktype";
+/** Top-level subtree of the workflow-run repo that holds the mailbox. */
+export const MAILBOX_PREFIX = "mailbox";
+/** The single mailbox this backing persists, an IMAP INBOX. */
+export const MAILBOX_INBOX_DIR = "INBOX";
+/** Committed metadata blob name directly under `mailbox/INBOX/`. */
+export const MAILBOX_INDEX_FILE = "index.json";
+/** Suffix of a per-message raw-bytes blob (`<uid>.eml`). */
+export const MAILBOX_EML_SUFFIX = ".eml";
+/**
+ * The `mailbox/INBOX/` prefix, ending in `/` as
+ * `writeTreePreservingPrefix` requires. Every blob this backing writes is a
+ * direct child of it.
+ */
+export const MAILBOX_INBOX_PREFIX = `${MAILBOX_PREFIX}/${MAILBOX_INBOX_DIR}/`;
+/** Relative directory path of the INBOX, for `CommittedReads.listDir`. */
+const MAILBOX_INBOX_DIR_PATH = `${MAILBOX_PREFIX}/${MAILBOX_INBOX_DIR}`;
+/** Current on-disk schema version of `index.json`. */
+const INDEX_VERSION = 1;
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+/**
+ * On-disk envelope shape. Mirrors `StoredEnvelope` but serializes `date` as an
+ * ISO string and the three nullable header fields as `string | null` (JSON has
+ * no `undefined`); the loader maps `null` back to `undefined`.
+ */
+const StoredEnvelopeJson = type({
+    messageId: "string",
+    from: "string",
+    to: "string[]",
+    subject: "string",
+    date: "string",
+    inReplyTo: "string | null",
+    references: "string[]",
+    interchangeType: "string | null",
+    interchangeCorrelationId: "string | null",
+});
+/**
+ * On-disk `index.json` shape. Validated on every open: the committed tree is
+ * durable but external to this process, so it is parsed at the boundary rather
+ * than trusted. `expunged` records the uid and the modseq at which each
+ * message vanished so a QRESYNC `sync` can answer `vanished` since a client's
+ * known modseq.
+ */
+const MailboxIndexJson = type({
+    version: `${INDEX_VERSION}`,
+    uidValidity: "number >= 0",
+    uidNext: "number >= 1",
+    highestModSeq: "number >= 0",
+    messages: type({
+        uid: "number >= 1",
+        modseq: "number >= 1",
+        flags: "string[]",
+        envelope: StoredEnvelopeJson,
+    }).array(),
+    expunged: type({
+        uid: "number >= 1",
+        modseq: "number >= 1",
+    }).array(),
+});
+function serializeEnvelope(envelope) {
+    return {
+        messageId: envelope.messageId,
+        from: envelope.from,
+        to: envelope.to,
+        subject: envelope.subject,
+        date: envelope.date.toISOString(),
+        inReplyTo: envelope.inReplyTo ?? null,
+        references: envelope.references,
+        interchangeType: envelope.interchangeType ?? null,
+        interchangeCorrelationId: envelope.interchangeCorrelationId ?? null,
+    };
+}
+function deserializeEnvelope(raw) {
+    return {
+        messageId: raw.messageId,
+        from: raw.from,
+        to: raw.to,
+        subject: raw.subject,
+        date: new Date(raw.date),
+        inReplyTo: raw.inReplyTo === null ? undefined : raw.inReplyTo,
+        references: raw.references,
+        interchangeType: raw.interchangeType === null ? undefined : raw.interchangeType,
+        interchangeCorrelationId: raw.interchangeCorrelationId === null
+            ? undefined
+            : raw.interchangeCorrelationId,
+    };
+}
+/** The `<uid>.eml` blob name for a message. */
+function emlName(uid) {
+    return `${String(uid)}${MAILBOX_EML_SUFFIX}`;
+}
+/**
+ * Load the committed `mailbox/INBOX/` METADATA into an in-memory state, or the
+ * empty state (a fresh `uidValidity`) when the repo, the ref, or the subtree
+ * does not yet exist. Only `index.json` is read; the per-message `<uid>.eml`
+ * blobs stay on disk and are read lazily by `readRaw`, so an open's resident
+ * footprint is bounded to metadata regardless of mailbox size. The committed
+ * read snapshot and the uid->oid map are retained so `readRaw` resolves a
+ * blob against the same pinned commit the open observed. Every read resolves
+ * against the committed object store, so an open observes committed state even
+ * when the working tree lags.
+ */
+async function loadCommittedState(opts) {
+    const empty = (reads) => ({
+        uidValidity: Date.now(),
+        uidNext: 1,
+        highestModSeq: 0,
+        messages: [],
+        expunged: [],
+        reads,
+        oidByUid: new Map(),
+    });
+    const reads = await opts.substrate.openCommittedReads(opts.principal, opts.repoId, opts.ref);
+    if (reads === null)
+        return empty(reads);
+    const entries = await reads.listDir(MAILBOX_INBOX_DIR_PATH);
+    const indexEntry = entries.find((e) => e.name === MAILBOX_INDEX_FILE && e.type === "blob");
+    if (indexEntry === undefined)
+        return empty(reads);
+    const indexBytes = await reads.readBlobByOid(indexEntry.oid);
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(decoder.decode(indexBytes));
+    }
+    catch (cause) {
+        throw new Error(`substrate mailbox store: ${MAILBOX_INBOX_PREFIX}${MAILBOX_INDEX_FILE} is not valid JSON`, { cause });
+    }
+    const index = MailboxIndexJson(parsedJson);
+    if (index instanceof type.errors) {
+        throw new Error(`substrate mailbox store: invalid ${MAILBOX_INBOX_PREFIX}${MAILBOX_INDEX_FILE}: ${index.summary}`);
+    }
+    const emlByName = new Map(entries
+        .filter((e) => e.type === "blob" && e.name.endsWith(MAILBOX_EML_SUFFIX))
+        .map((e) => [e.name, e.oid]));
+    const messages = [];
+    const oidByUid = new Map();
+    for (const entry of index.messages) {
+        const oid = emlByName.get(emlName(entry.uid));
+        if (oid === undefined) {
+            throw new Error(`substrate mailbox store: index references message uid ${String(entry.uid)} but ${MAILBOX_INBOX_PREFIX}${emlName(entry.uid)} is absent`);
+        }
+        // The blob's presence is asserted by its object id; its bytes are not read
+        // here -- `readRaw` reads them on demand.
+        oidByUid.set(entry.uid, oid);
+        messages.push({
+            uid: entry.uid,
+            modseq: entry.modseq,
+            flags: new Set(entry.flags),
+            envelope: deserializeEnvelope(entry.envelope),
+        });
+    }
+    return {
+        uidValidity: index.uidValidity,
+        uidNext: index.uidNext,
+        highestModSeq: index.highestModSeq,
+        messages,
+        expunged: index.expunged.map((e) => ({ uid: e.uid, modseq: e.modseq })),
+        reads,
+        oidByUid,
+    };
+}
+/**
+ * Create a workflow-run-substrate-backed `MailboxStore`. Loads the committed
+ * `mailbox/INBOX/` subtree into an in-memory mirror, then serves the
+ * synchronous `MailboxStore` surface over that mirror. Mutations stay in
+ * memory until `flush` persists them.
+ */
+export async function createSubstrateMailboxStore(opts) {
+    const state = await loadCommittedState(opts);
+    const messages = state.messages;
+    const expunged = state.expunged;
+    const uidValidity = state.uidValidity;
+    const reads = state.reads;
+    const oidByUid = state.oidByUid;
+    let uidCounter = state.uidNext;
+    // The next modseq to assign. `highestModSeq` is the largest assigned, so the
+    // next is one past it; a fresh mailbox (highestModSeq 0) starts at 1.
+    let modseqCounter = state.highestModSeq + 1;
+    let dirty = false;
+    // Delta tracking for `flush`. `index.json` changes on every mutation, so it
+    // is put unconditionally; each `<uid>.eml` is immutable and written once, so
+    // a flush need only put the blobs appended since the last successful flush
+    // and delete the blobs whose message was removed since then. The removed set
+    // clears on a successful flush; a flush that throws leaves it intact so the
+    // next flush re-attempts the same delta.
+    //
+    // `pendingRawByUid` holds the raw bytes of appended-but-not-yet-flushed
+    // messages -- the only raw this backing keeps resident. It doubles as the
+    // "appended since flush" set: `flush` puts each entry's blob, then drops it
+    // so a flushed message's bytes leave memory and are read from disk on demand.
+    const pendingRawByUid = new Map();
+    const removedSinceFlush = new Set();
+    function find(uid) {
+        return messages.find((m) => m.uid === uid);
+    }
+    function require(uid) {
+        const msg = find(uid);
+        if (msg === undefined) {
+            throw new Error(`Message UID ${String(uid)} not found`);
+        }
+        return msg;
+    }
+    async function flush() {
+        if (!dirty)
+            return;
+        const index = {
+            version: INDEX_VERSION,
+            uidValidity,
+            uidNext: uidCounter,
+            highestModSeq: modseqCounter - 1,
+            messages: messages.map((m) => ({
+                uid: m.uid,
+                modseq: m.modseq,
+                flags: Array.from(m.flags),
+                envelope: serializeEnvelope(m.envelope),
+            })),
+            expunged: expunged.map((e) => ({ uid: e.uid, modseq: e.modseq })),
+        };
+        // `index.json` is put on every flush. Each `<uid>.eml` is immutable, so
+        // only the blobs appended since the last successful flush are put and only
+        // those whose message was removed are deleted; every other `.eml` is
+        // carried forward by object id, so the flush never re-hashes the mailbox's
+        // whole history.
+        const puts = {
+            [`${MAILBOX_INBOX_PREFIX}${MAILBOX_INDEX_FILE}`]: encoder.encode(JSON.stringify(index)),
+        };
+        const flushedUids = [];
+        for (const [uid, raw] of pendingRawByUid) {
+            puts[`${MAILBOX_INBOX_PREFIX}${emlName(uid)}`] = raw;
+            flushedUids.push(uid);
+        }
+        const deletes = Array.from(removedSinceFlush, (uid) => `${MAILBOX_INBOX_PREFIX}${emlName(uid)}`);
+        await opts.substrate.writeTreeDelta(opts.principal, opts.repoId, opts.ref, {
+            computeDelta: async () => ({ puts, deletes }),
+            changedPathPrefixes: new Set([MAILBOX_INBOX_PREFIX]),
+            message: `persist mailbox INBOX (${String(messages.length)} message(s))`,
+        });
+        // The appended blobs are now committed, so their raw leaves memory: a later
+        // `readRaw` reads them from disk. Their object ids are not recorded here
+        // (the pinned committed-read snapshot predates this commit), so `readRaw`
+        // resolves a post-open append only while its raw is still pending; the
+        // long-lived writer never reads its own appends back, and every reader
+        // opens a fresh snapshot that sees the committed blob.
+        for (const uid of flushedUids) {
+            pendingRawByUid.delete(uid);
+        }
+        removedSinceFlush.clear();
+        dirty = false;
+    }
+    function sync(known) {
+        const highestModSeq = modseqCounter - 1;
+        if (known.uidValidity !== uidValidity) {
+            return {
+                resync: true,
+                uidValidity,
+                uidNext: uidCounter,
+                highestModSeq,
+                messages: messages.slice(),
+            };
+        }
+        const changed = messages
+            .filter((m) => m.modseq > known.highestModSeq)
+            .sort((a, b) => a.uid - b.uid);
+        const vanished = expunged
+            .filter((e) => e.modseq > known.highestModSeq)
+            .map((e) => e.uid)
+            .sort((a, b) => a - b);
+        return {
+            resync: false,
+            uidValidity,
+            uidNext: uidCounter,
+            highestModSeq,
+            changed,
+            vanished,
+        };
+    }
+    return {
+        uidValidity,
+        get uidNext() {
+            return uidCounter;
+        },
+        get highestModSeq() {
+            return modseqCounter - 1;
+        },
+        get messages() {
+            return messages;
+        },
+        get pendingWrites() {
+            return dirty;
+        },
+        append(raw, envelope, flags) {
+            const uid = uidCounter++;
+            const modseq = modseqCounter++;
+            messages.push({ uid, modseq, flags: new Set(flags), envelope });
+            pendingRawByUid.set(uid, raw);
+            dirty = true;
+            return uid;
+        },
+        async readRaw(uid) {
+            if (find(uid) === undefined) {
+                throw new Error(`Message UID ${String(uid)} not found`);
+            }
+            // An appended-but-not-yet-flushed message keeps its raw in memory; a
+            // flushed or previously-committed message reads its blob from the pinned
+            // committed-read snapshot on demand.
+            const pending = pendingRawByUid.get(uid);
+            if (pending !== undefined)
+                return pending;
+            const oid = oidByUid.get(uid);
+            if (oid === undefined || reads === null) {
+                throw new Error(`substrate mailbox store: no committed blob for message uid ${String(uid)}; its raw bytes are not resolvable from this snapshot`);
+            }
+            return reads.readBlobByOid(oid);
+        },
+        find,
+        addFlags(uid, flags) {
+            const msg = require(uid);
+            for (const flag of flags) {
+                msg.flags.add(flag);
+            }
+            msg.modseq = modseqCounter++;
+            dirty = true;
+            return msg;
+        },
+        removeFlags(uid, flags) {
+            const msg = require(uid);
+            for (const flag of flags) {
+                msg.flags.delete(flag);
+            }
+            msg.modseq = modseqCounter++;
+            dirty = true;
+            return msg;
+        },
+        remove(uid) {
+            const idx = messages.findIndex((m) => m.uid === uid);
+            if (idx === -1) {
+                throw new Error(`Message UID ${String(uid)} not found`);
+            }
+            messages.splice(idx, 1);
+            // Record the expunge with a fresh modseq so a QRESYNC `sync` can report
+            // this uid as `vanished` to a client whose known modseq predates it. The
+            // in-memory reference backing does not advance modseq on remove; this
+            // backing does, because it must answer QRESYNC across reopens.
+            expunged.push({ uid, modseq: modseqCounter++ });
+            // A message appended and removed within the same flush window was never
+            // committed, so its `.eml` must be neither put nor deleted: drop its
+            // pending raw. Otherwise the blob is already committed and the next flush
+            // deletes it.
+            if (pendingRawByUid.has(uid)) {
+                pendingRawByUid.delete(uid);
+            }
+            else {
+                removedSinceFlush.add(uid);
+            }
+            dirty = true;
+        },
+        flush,
+        sync,
+    };
+}

package/dist/child/child-mailbox-reader.d.ts

@@ -0,0 +1,10 @@
+import { type SubstrateMailboxStore, type SubstrateMailboxStoreOpts } from "../adapters/substrate-mailbox-store.js";
+export interface ChildMailboxReader {
+    /**
+     * Open a fresh committed snapshot of the deployment's substrate INBOX. Each
+     * call re-reads the committed `mailbox/INBOX/` subtree, so a snapshot opened
+     * after a `mailbox.notify` observes the newly committed message.
+     */
+    open(): Promise<SubstrateMailboxStore>;
+}
+export declare function createChildMailboxReader(opts: SubstrateMailboxStoreOpts): ChildMailboxReader;

package/dist/child/child-mailbox-reader.js

@@ -0,0 +1,23 @@
+// Child-side substrate mailbox reader (INBOUND half of mailbox ownership,
+// design §3b).
+//
+// The supervisor commits an arrived message to the deployment's workflow-run
+// substrate mailbox (`mailbox/INBOX/`), then fires a `mailbox.notify` control
+// frame. A step agent's supervisor-backed transport answers the IMAP read
+// surface (`search`, `fetchHeaders`, `fetchFull`, ...) by opening a fresh
+// committed snapshot of that mailbox through this reader. `open` re-reads the
+// committed subtree on every call, so a snapshot taken after a `mailbox.notify`
+// observes the message the supervisor just committed.
+//
+// Modeled on the sibling `createMailPartReader` wiring: the same per-deployment
+// substrate handles (substrate, repoId, principal, workflow-run ref), bound
+// once so the transport reads without re-threading them. `createSubstrateMailboxStore`
+// loads committed state on open and is async, so `open` returns a promise.
+import { createSubstrateMailboxStore, } from "../adapters/substrate-mailbox-store.js";
+export function createChildMailboxReader(opts) {
+    return {
+        open() {
+            return createSubstrateMailboxStore(opts);
+        },
+    };
+}

package/dist/child/credential-cell.d.ts

@@ -0,0 +1,8 @@
+import type { CredentialDelivery } from "@intx/types/sidecar";
+/**
+ * Apply a `credentials-updated` frame to the current cell and return the next
+ * cell. Pure: it reads neither argument's identity back out, so the caller can
+ * assign the result to the live ref in one atomic whole-object swap and a
+ * concurrent reader never observes a torn cell.
+ */
+export declare function mergeCredentialDelivery(current: CredentialDelivery | null, delivery: CredentialDelivery, revoke: readonly string[] | undefined): CredentialDelivery;

package/dist/child/credential-cell.js

@@ -0,0 +1,66 @@
+// Merge semantics for the child's in-memory credential-material cell.
+//
+// The cell is fed by several INDEPENDENTLY-SCOPED producers: the deploy frame
+// (tool bindings plus the run's inference materials, frozen at deploy time and
+// re-asserted on every spawn and pre-trigger barrier), an inference rotation
+// (materials only, no binding), and a tool-grant push (tool bindings plus their
+// materials). Each producer carries only its own slice of the cell. A wholesale
+// swap would therefore let one producer evict another's credentials -- an
+// inference rotation would drop every tool binding, a barrier re-push would drop
+// a live-pushed tool credential. So a `credentials-updated` frame MERGES:
+// materials upsert by `credentialId`, bindings upsert by `(consumer, handle)`.
+//
+// Because omission no longer means "gone", revocation is EXPLICIT: a frame's
+// `revoke` list names the credentialIds to drop, and dropping one also drops
+// every binding that references it. Revocation is applied before the upsert, so
+// a frame that both revokes and re-adds the same credentialId resolves to the
+// re-add. A material an upsert leaves unreferenced (a rebind of a handle to a
+// different credential) is not garbage-collected -- inference materials never
+// carry a binding, so "unreferenced" is not a drop signal; only an explicit
+// `revoke` removes a material.
+// A binding's identity is the (consumer, handle) pair: a handle string is only
+// unique within a consumer, so two consumers can each bind their own handle of
+// the same name. The U+0000 joiner keeps the pair injective where a printable
+// joiner would not -- a handle is an arbitrary string that may contain a space
+// or a colon, but by convention never a NUL.
+function bindingKey(binding) {
+    return `${binding.consumer}\u0000${binding.handle}`;
+}
+/**
+ * Apply a `credentials-updated` frame to the current cell and return the next
+ * cell. Pure: it reads neither argument's identity back out, so the caller can
+ * assign the result to the live ref in one atomic whole-object swap and a
+ * concurrent reader never observes a torn cell.
+ */
+export function mergeCredentialDelivery(current, delivery, revoke) {
+    const materials = new Map();
+    const bindings = new Map();
+    if (current !== null) {
+        for (const material of current.materials) {
+            materials.set(material.credentialId, material);
+        }
+        for (const binding of current.bindings) {
+            bindings.set(bindingKey(binding), binding);
+        }
+    }
+    if (revoke !== undefined) {
+        for (const credentialId of revoke) {
+            materials.delete(credentialId);
+            for (const [key, binding] of bindings) {
+                if (binding.credentialId === credentialId) {
+                    bindings.delete(key);
+                }
+            }
+        }
+    }
+    for (const material of delivery.materials) {
+        materials.set(material.credentialId, material);
+    }
+    for (const binding of delivery.bindings) {
+        bindings.set(bindingKey(binding), binding);
+    }
+    return {
+        bindings: [...bindings.values()],
+        materials: [...materials.values()],
+    };
+}

package/dist/child/from-process-env.d.ts

@@ -2,6 +2,7 @@ import { type SpawnTimeEnv } from "./env-bootstrap.js";
 import { type RunWorkflowChildBindings, type RunWorkflowChildResult } from "./run-child.js";
 import { type ChildSubstrateWriteBridge } from "./substrate-write-bridge.js";
 import { type ChildOutboundMailBridge } from "./outbound-mail-bridge.js";
+import { type ChildMailboxMutationBridge } from "./mailbox-mutation-bridge.js";
 import { type FrameWriter, type NdjsonReader, type NdjsonWriter } from "../ipc/index.js";
 /**
  * File descriptor the supervisor's `Bun.spawn` wires the
@@ -63,6 +64,17 @@ export interface SubstrateFactoryEnv {
      * agent's signature without the child ever holding the agent's key.
      */
     readonly outboundMailBridge: ChildOutboundMailBridge;
+    /**
+     * Child-side IPC bridge over the upstream control channel for the
+     * INBOUND half of mailbox ownership (§3b). The substrate factory uses
+     * this to construct the supervisor-backed `MessageTransport`'s write
+     * surface: `setFlags` / `clearFlags` / `expunge` call `bridge.submit`,
+     * which emits a `mailbox.mutate.request` upstream frame and resolves
+     * once the supervisor's matching `mailbox.mutate.response` lands. The
+     * supervisor -- the sole mailbox writer -- applies the mutation to its
+     * owned store, so the child never flushes the run ref itself.
+     */
+    readonly mailboxMutationBridge: ChildMailboxMutationBridge;
 }
 /**
  * Substrate-factory callback the host supplies to

package/dist/child/from-process-env.js

@@ -21,6 +21,7 @@ import { parseSpawnTimeEnv } from "./env-bootstrap.js";
 import { runWorkflowChild, } from "./run-child.js";
 import { createChildSubstrateWriteBridge, } from "./substrate-write-bridge.js";
 import { createChildOutboundMailBridge, } from "./outbound-mail-bridge.js";
+import { createChildMailboxMutationBridge, } from "./mailbox-mutation-bridge.js";
 import { createControlChannelSender, } from "../ipc/index.js";
 /**
  * File descriptor the supervisor's `Bun.spawn` wires the
@@ -76,11 +77,15 @@ export async function runWorkflowChildFromProcessEnv(factory, opts = {}) {
     const outboundMailBridge = createChildOutboundMailBridge({
         upstreamSender,
     });
+    const mailboxMutationBridge = createChildMailboxMutationBridge({
+        upstreamSender,
+    });
     const bindings = await factory({
         spawn,
         substrateConfig,
         substrateWriteBridge,
         outboundMailBridge,
+        mailboxMutationBridge,
     });
     return runWorkflowChild({
         env: spawn,
@@ -98,6 +103,7 @@ export async function runWorkflowChildFromProcessEnv(factory, opts = {}) {
         upstreamSender,
         substrateWriteBridge,
         outboundMailBridge,
+        mailboxMutationBridge,
     });
 }
 const SubstrateConfigValue = type("string > 0");

package/dist/child/index.d.ts

@@ -1,7 +1,10 @@
 export { createCredentialsBackedAuthorize, hashGrants, runWorkflowChild, type ChildStepInvoker, type CredentialsSnapshotRef, type CredentialWiring, type DrainController, type GrantEvaluator, type RunWorkflowChildBindings, type RunWorkflowChildOpts, type RunWorkflowChildResult, type SourcesSnapshotRef, type SubstrateWriteResponseSink, } from "./run-child.js";
 export { createChildSubstrateWriteBridge, type ChildSubstrateWriteBridge, type CreateChildSubstrateWriteBridgeOpts, type SubstrateWriteRequest, } from "./substrate-write-bridge.js";
 export { createChildOutboundMailBridge, type ChildOutboundMailBridge, type CreateChildOutboundMailBridgeOpts, } from "./outbound-mail-bridge.js";
-export { createSupervisorBackedTransport } from "./supervisor-backed-transport.js";
+export { createChildMailboxMutationBridge, type ChildMailboxMutationBridge, type CreateChildMailboxMutationBridgeOpts, type MailboxMutation, type MailboxMutationResult, } from "./mailbox-mutation-bridge.js";
+export { createSupervisorBackedTransport, type SupervisorBackedTransportInbound, } from "./supervisor-backed-transport.js";
+export { createMailboxWatchRegistry, type MailboxWatchRegistry, } from "./mailbox-watch-registry.js";
+export { createChildMailboxReader, type ChildMailboxReader, } from "./child-mailbox-reader.js";
 export { createProxyWorkflowRunRepoStore, type CreateProxyWorkflowRunRepoStoreOpts, } from "./proxy-repo-store.js";
 export { parseSpawnTimeEnv, type SpawnTimeEnv } from "./env-bootstrap.js";
 export { discoverInFlightRuns, type DiscoverRunsOpts, type DiscoveredRun, } from "./self-discovery.js";

package/dist/child/index.js

@@ -1,7 +1,10 @@
 export { createCredentialsBackedAuthorize, hashGrants, runWorkflowChild, } from "./run-child.js";
 export { createChildSubstrateWriteBridge, } from "./substrate-write-bridge.js";
 export { createChildOutboundMailBridge, } from "./outbound-mail-bridge.js";
-export { createSupervisorBackedTransport } from "./supervisor-backed-transport.js";
+export { createChildMailboxMutationBridge, } from "./mailbox-mutation-bridge.js";
+export { createSupervisorBackedTransport, } from "./supervisor-backed-transport.js";
+export { createMailboxWatchRegistry, } from "./mailbox-watch-registry.js";
+export { createChildMailboxReader, } from "./child-mailbox-reader.js";
 export { createProxyWorkflowRunRepoStore, } from "./proxy-repo-store.js";
 export { parseSpawnTimeEnv } from "./env-bootstrap.js";
 export { discoverInFlightRuns, } from "./self-discovery.js";

package/dist/child/mailbox-mutation-bridge.d.ts

@@ -0,0 +1,61 @@
+import type { ControlChannelSender, ControlPayload } from "../ipc/control-channel.js";
+/**
+ * A mailbox mutation the child asks the supervisor to apply. A flag
+ * mutation carries the target `uid` and the `flags` to add or remove; an
+ * `expunge` sweeps every `\Deleted` message in the mailbox and so carries
+ * neither.
+ */
+export type MailboxMutation = {
+    runId: string;
+    mailbox: string;
+    op: "addFlags" | "removeFlags";
+    uid: number;
+    flags: string[];
+} | {
+    runId: string;
+    mailbox: string;
+    op: "expunge";
+};
+/**
+ * The supervisor's applied-mutation result. `expungedUids` is present
+ * only for an `expunge` and lists the uids the sweep removed, so the
+ * agent tool can report how many messages it consumed.
+ */
+export type MailboxMutationResult = {
+    expungedUids?: number[];
+};
+/**
+ * Bridge surface the child's supervisor-backed transport reaches into.
+ * `submit` sends a `mailbox.mutate.request` upstream and resolves once
+ * the supervisor's matching `mailbox.mutate.response` lands.
+ * `handleResult` is the receiver-side entry point the child's control
+ * loop invokes when the downstream `mailbox.mutate.response` frame
+ * arrives. `cancelAll` is the cleanup hook the control loop invokes on
+ * any exit path so a pending mutation does not leak an awaiter when the
+ * supervisor has torn the IPC down.
+ */
+export interface ChildMailboxMutationBridge {
+    submit(mutation: MailboxMutation): Promise<MailboxMutationResult>;
+    handleResult(data: Extract<ControlPayload, {
+        type: "mailbox.mutate.response";
+    }>["data"]): void;
+    cancelAll(reason: string): void;
+    readonly pendingCount: number;
+}
+export interface CreateChildMailboxMutationBridgeOpts {
+    upstreamSender: ControlChannelSender;
+    /**
+     * Optional `requestId` allocator. Production wires a per-instance
+     * monotonic counter plus a random suffix; tests inject a
+     * deterministic factory so the upstream frame's `requestId` is
+     * predictable.
+     */
+    allocateRequestId?: () => string;
+}
+/**
+ * Construct the child-side mailbox-mutation bridge. Pending mutations
+ * live in the shared pending-request core keyed by `requestId`; the
+ * bridge resolves the awaiter when the supervisor's matching
+ * `mailbox.mutate.response` lands.
+ */
+export declare function createChildMailboxMutationBridge(opts: CreateChildMailboxMutationBridgeOpts): ChildMailboxMutationBridge;