@intx/workflow-host 0.2.2

package/dist/child/outbound-mail-bridge.js

@@ -0,0 +1,143 @@
+// Child-side outbound-mail bridge (OUTBOUND half of mailbox ownership,
+// §3a).
+//
+// The workflow-process child holds no signing key for the agent's
+// identity. The supervisor is the sole mail owner: it holds the host
+// transport against which the agent's address is registered with its
+// `CryptoProvider`, and it is the only process that can emit signed mail
+// on the agent's behalf. So a step agent never calls `transport.send`
+// directly; its mail tools are backed by a transport whose outbound side
+// routes through this bridge, which forwards the structured
+// `OutboundMessage` plus the sender (agent) address up over the control
+// IPC. The supervisor performs the actual signed send and replies with
+// the `SendReceipt`.
+//
+// Lifecycle of one outbound send:
+//
+//   1. The agent's mail tool (or the step reply path) calls the
+//      supervisor-backed transport's `send`. The transport calls
+//      `bridge.submit(senderAddress, message)`.
+//   2. `submit` mints a `requestId`, registers a pending awaiter, and
+//      emits `outbound.message` upstream carrying the JSON-projected
+//      message (attachment bytes base64-encoded).
+//   3. The supervisor receives the request, performs the signed send
+//      through the host transport (`MailBusBindings.sendOutbound`), and
+//      replies with `outbound.result` carrying the `SendReceipt` (or a
+//      structured failure).
+//   4. The bridge resolves / rejects the pending awaiter; the
+//      transport's `send` returns the receipt to the mail tool. A
+//      supervisor-side failure (unregistered sender, signing failure,
+//      transport rejection) surfaces as a rejection so the agent's
+//      mail-tool call fails loudly rather than silently dropping the
+//      send.
+import { getLogger } from "@intx/log";
+import { base64Encode } from "@intx/types";
+const logger = getLogger(["workflow-host", "child", "outbound-mail-bridge"]);
+/**
+ * Construct the child-side outbound-mail bridge. Pending sends live in
+ * a map keyed by `requestId`; the bridge resolves the awaiter when the
+ * supervisor's matching `outbound.result` lands.
+ */
+export function createChildOutboundMailBridge(opts) {
+    const pending = new Map();
+    const allocate = opts.allocateRequestId ?? defaultRequestIdAllocator();
+    return {
+        get pendingCount() {
+            return pending.size;
+        },
+        async submit(senderAddress, message) {
+            const requestId = allocate();
+            const resultPromise = new Promise((resolve, reject) => {
+                pending.set(requestId, { resolve, reject });
+            });
+            try {
+                await opts.upstreamSender.send({
+                    type: "outbound.message",
+                    data: {
+                        requestId,
+                        senderAddress,
+                        message: projectOutboundMessage(message),
+                    },
+                });
+            }
+            catch (cause) {
+                pending.delete(requestId);
+                const reason = cause instanceof Error ? cause.message : String(cause);
+                throw new Error(`workflow-child outbound mail: upstream send failed for requestId ${requestId}: ${reason}`, { cause });
+            }
+            return resultPromise;
+        },
+        handleResult(data) {
+            const entry = pending.get(data.requestId);
+            if (entry === undefined) {
+                logger.warn `outbound.result landed with no pending entry; requestId=${data.requestId} dropped`;
+                return;
+            }
+            pending.delete(data.requestId);
+            if (data.result.ok) {
+                entry.resolve({
+                    messageId: data.result.messageId,
+                    status: data.result.status,
+                });
+                return;
+            }
+            entry.reject(new Error(`workflow-child outbound mail (requestId=${data.requestId}) rejected by supervisor: ${data.result.reason}`));
+        },
+        cancelAll(reason) {
+            for (const [requestId, entry] of pending) {
+                entry.reject(new Error(`workflow-child outbound mail (requestId=${requestId}) cancelled: ${reason}`));
+            }
+            pending.clear();
+        },
+    };
+}
+/**
+ * Project a runtime `OutboundMessage` into the IPC wire shape. Optional
+ * fields are omitted when absent (the wire validator spells them
+ * optional), and attachment bytes ride base64-encoded so the NDJSON
+ * control channel stays text-safe.
+ */
+function projectOutboundMessage(message) {
+    const payload = {
+        to: message.to,
+        type: message.type,
+    };
+    if (message.cc !== undefined)
+        payload.cc = message.cc;
+    if (message.subject !== undefined)
+        payload.subject = message.subject;
+    if (message.content !== undefined)
+        payload.content = message.content;
+    if (message.payload !== undefined)
+        payload.payload = message.payload;
+    if (message.summary !== undefined)
+        payload.summary = message.summary;
+    if (message.inReplyTo !== undefined)
+        payload.inReplyTo = message.inReplyTo;
+    if (message.correlationId !== undefined) {
+        payload.correlationId = message.correlationId;
+    }
+    if (message.sessionId !== undefined)
+        payload.sessionId = message.sessionId;
+    if (message.tenantId !== undefined)
+        payload.tenantId = message.tenantId;
+    if (message.attachments !== undefined) {
+        payload.attachments = message.attachments.map((a) => ({
+            name: a.name,
+            contentType: a.contentType,
+            dataBase64: bytesToBase64(a.data),
+        }));
+    }
+    return payload;
+}
+function bytesToBase64(bytes) {
+    return base64Encode(bytes);
+}
+function defaultRequestIdAllocator() {
+    let counter = 0;
+    return () => {
+        counter += 1;
+        const rand = Math.random().toString(36).slice(2, 10);
+        return `om-${String(counter)}-${rand}`;
+    };
+}

package/dist/child/proxy-repo-store.d.ts

@@ -0,0 +1,27 @@
+import type { RepoId, RepoStore } from "@intx/hub-sessions/substrate";
+import type { ChildSubstrateWriteBridge } from "./substrate-write-bridge.js";
+export interface CreateProxyWorkflowRunRepoStoreOpts {
+    /**
+     * Bare substrate handle the child opens against the shared on-disk
+     * data dir. Used for the read-only methods that consult the
+     * substrate's local state -- `getRepoDir` (path computation, no
+     * I/O), `resolveRef`, `listRefs`, `resolveHead`, `createPack`. The
+     * bare store is never used as a writer here; its
+     * `writeTreePreservingPrefix` / `writeTree` / `receivePack` are not
+     * reachable through this proxy.
+     */
+    bareStore: RepoStore;
+    /**
+     * Substrate-write bridge that forwards proxied writes over the
+     * control IPC into the supervisor.
+     */
+    bridge: ChildSubstrateWriteBridge;
+    /**
+     * Workflow-run repo id this proxy services. Used as a guard: writes
+     * targeting any other repo id surface a structured failure so a
+     * stray call against a non-workflow-run repo does not silently land
+     * in the wrong substrate.
+     */
+    workflowRunRepoId: RepoId;
+}
+export declare function createProxyWorkflowRunRepoStore(opts: CreateProxyWorkflowRunRepoStoreOpts): RepoStore;

package/dist/child/proxy-repo-store.js

@@ -0,0 +1,200 @@
+// Child-side proxy `RepoStore` for the workflow-run repo.
+//
+// Wraps a bare read-only substrate handle (the child constructs one
+// against the shared on-disk data dir for `getRepoDir` + other read
+// paths) and intercepts `writeTreePreservingPrefix` so the write is
+// proxied over the control IPC into the supervisor's substrate. The
+// supervisor is the sole writer of the workflow-run repo's ref; the
+// child has no write authority and would race the supervisor's
+// claim-check writes if it opened its own.
+//
+// Subscription fan-out: `RepoStore.subscribe` is a local-process
+// in-memory subscriber pattern; the bare-store's `subscribe` only
+// fires when a write lands on THAT particular substrate instance. The
+// supervisor's writes against its own substrate do not reach the
+// child's bare-store subscribers. The proxy therefore maintains its
+// own per-ref subscriber list and synthesizes a `ref.updated` event to
+// every subscriber after each successful proxied write -- the on-disk
+// repo already carries the new commit (the supervisor's substrate
+// commits before responding to the IPC), so subscribers that follow
+// up with a tree read (via `subscribeKind`'s `getRepoDir` +
+// `readBlobAtCommit` path) see the prospective tree's bytes.
+//
+// Methods that mutate state via paths other than
+// `writeTreePreservingPrefix` (`initRepo`, `writeTree`, `receivePack`)
+// throw on call. The workflow-host runtime body and adapters do not
+// invoke these against the workflow-run repo proxy today; a future
+// caller that tries to surfaces a structured failure rather than a
+// silent disk write that would corrupt the single-writer invariant.
+export function createProxyWorkflowRunRepoStore(opts) {
+    const { bareStore, bridge, workflowRunRepoId } = opts;
+    // Per-ref subscriber lists. The proxy fans `ref.updated` events to
+    // every subscriber on the ref after a successful proxied write so
+    // a `subscribeKind` loop watching this ref (the signal channel's
+    // `awaitNext` is the canonical consumer) wakes up.
+    const subscribers = new Map();
+    // Per-ref last-seen sha so the synthesized `ref.updated` carries the
+    // matching `oldSha`. Subscriber semantics in `subscribeKind` use the
+    // oldSha to enumerate commits added on top of the prior tip.
+    const lastSha = new Map();
+    function refKey(repoId, ref) {
+        return `${repoId.kind}/${repoId.id}/${ref}`;
+    }
+    function notifyRefUpdate(repoId, ref, oldSha, newSha) {
+        const key = refKey(repoId, ref);
+        const set = subscribers.get(key);
+        if (set === undefined)
+            return;
+        const event = {
+            type: "ref.updated",
+            ref,
+            oldSha,
+            newSha,
+        };
+        // The substrate's subscribe contract emits one entry per commit
+        // with the seq value derived at commit time. The proxy does not
+        // know the canonical seq the substrate assigned (the substrate
+        // computes it from the ref's history); the field is informational
+        // for the subscribe iterator's consumers. `subscribeKind` does
+        // not consult the value -- it walks the commit tree from `oldSha`
+        // to `newSha` itself -- so any monotonic value preserves the
+        // downstream contract. Use a per-ref monotonic counter.
+        const seq = (lastRefSeq.get(key) ?? 0) + 1;
+        lastRefSeq.set(key, seq);
+        for (const sub of set) {
+            if (sub.closed)
+                continue;
+            const entry = { seq, event };
+            if (sub.waiter !== null) {
+                const w = sub.waiter;
+                sub.waiter = null;
+                w({ value: entry, done: false });
+                continue;
+            }
+            sub.buffer.push(entry);
+        }
+    }
+    const lastRefSeq = new Map();
+    return {
+        initRepo: (_repoId, _initOpts) => {
+            throw new Error("workflow-child proxy substrate: initRepo is not supported (writes are proxied to the supervisor)");
+        },
+        writeTree: (_principal, _repoId, _ref, _content) => {
+            throw new Error("workflow-child proxy substrate: writeTree is not supported (writes are proxied to the supervisor)");
+        },
+        receivePack: (_principal, _repoId, _ref, _pack, _commitSha, _expectedOldSha) => {
+            throw new Error("workflow-child proxy substrate: receivePack is not supported (writes are proxied to the supervisor)");
+        },
+        writeTreeDelta: (_principal, _repoId, _ref, _args) => {
+            throw new Error("workflow-child proxy substrate: writeTreeDelta is not supported (claim-check writes run supervisor-side)");
+        },
+        async writeTreePreservingPrefix(_principal, repoId, ref, args) {
+            if (repoId.kind !== workflowRunRepoId.kind ||
+                repoId.id !== workflowRunRepoId.id) {
+                throw new Error(`workflow-child proxy substrate: writeTreePreservingPrefix targeting ${repoId.kind}/${repoId.id} is not supported (proxy services ${workflowRunRepoId.kind}/${workflowRunRepoId.id})`);
+            }
+            const key = refKey(repoId, ref);
+            const priorSha = lastSha.has(key)
+                ? (lastSha.get(key) ?? null)
+                : await bareStore.resolveRef(_principal, repoId, ref);
+            const result = await bridge.submit({
+                repoId: { kind: repoId.kind, id: repoId.id },
+                ref,
+                preservePrefix: args.preservePrefix,
+                message: args.message,
+                merge: args.merge,
+            });
+            lastSha.set(key, result.commitSha);
+            notifyRefUpdate(repoId, ref, priorSha, result.commitSha);
+            // The terminal signal is consumed supervisor-side (where the real
+            // substrate write happens); the child-proxied result carries only
+            // the commit, so report no terminal runs to the runtime body.
+            return { commitSha: result.commitSha, newlyTerminalRuns: [] };
+        },
+        createPack: bareStore.createPack.bind(bareStore),
+        commitPackedTip: bareStore.commitPackedTip.bind(bareStore),
+        resolveRef: bareStore.resolveRef.bind(bareStore),
+        listRefs: bareStore.listRefs.bind(bareStore),
+        resolveHead: bareStore.resolveHead.bind(bareStore),
+        getRepoDir: bareStore.getRepoDir.bind(bareStore),
+        subscribe(_principal, repoId, ref, subOpts) {
+            // Synthesizing the subscribe surface in the proxy: the bare
+            // store's `subscribe` would only fire from its own writes, but
+            // the writes for this ref happen in the supervisor's address
+            // space. Subscribers attached here receive events whenever the
+            // proxy's `writeTreePreservingPrefix` returns successfully.
+            //
+            // `from: { seq }` replay against historical commits is not
+            // emitted here today: the runtime body's signal-channel and
+            // similar consumers attach with `from: "head"` so only events
+            // committed after subscription fire. A `from: { seq }` caller
+            // (a resume path that wants to replay) would currently miss
+            // historical commits -- the bare store's `subscribe` is the
+            // path that supports replay today, and resume code can call it
+            // directly if needed.
+            const key = refKey(repoId, ref);
+            let set = subscribers.get(key);
+            if (set === undefined) {
+                set = new Set();
+                subscribers.set(key, set);
+            }
+            const sub = {
+                buffer: [],
+                waiter: null,
+                closed: false,
+                signal: subOpts.signal,
+            };
+            set.add(sub);
+            const cleanup = () => {
+                sub.closed = true;
+                const current = subscribers.get(key);
+                if (current !== undefined) {
+                    current.delete(sub);
+                    if (current.size === 0)
+                        subscribers.delete(key);
+                }
+                if (sub.waiter !== null) {
+                    const w = sub.waiter;
+                    sub.waiter = null;
+                    w({ value: undefined, done: true });
+                }
+            };
+            const onAbort = () => {
+                cleanup();
+            };
+            if (subOpts.signal.aborted) {
+                cleanup();
+            }
+            else {
+                subOpts.signal.addEventListener("abort", onAbort, { once: true });
+            }
+            return {
+                [Symbol.asyncIterator]() {
+                    return this;
+                },
+                next() {
+                    if (sub.closed) {
+                        return Promise.resolve({ value: undefined, done: true });
+                    }
+                    if (sub.buffer.length > 0) {
+                        const next = sub.buffer.shift();
+                        if (next === undefined) {
+                            return Promise.resolve({ value: undefined, done: true });
+                        }
+                        return Promise.resolve({ value: next, done: false });
+                    }
+                    return new Promise((resolve) => {
+                        sub.waiter = resolve;
+                    });
+                },
+                return() {
+                    cleanup();
+                    return Promise.resolve({
+                        value: undefined,
+                        done: true,
+                    });
+                },
+            };
+        },
+    };
+}