@intx/workflow-host 0.3.0 → 0.4.0

package/README.md

@@ -26,9 +26,14 @@ The package is organized along the abstract pieces it implements:
   startup recovery walk and a live `subscribeKind` loop so a
   `TimerSet` committed by an active workflow process fires without
   waiting for a process restart. `signal-channel.ts` funnels live
-  `SignalReceived` commits into the matching awaiter, with resume
-  rehydration consulting `unconsumedSignals` so a signal that
-  arrived while offline replays before live subscription begins.
+  `SignalReceived` commits into the matching awaiter. The channel
+  reads `unconsumedSignals` through its injected `readState`
+  reader, but every production call site passes an `emptyState`
+  reader, so that queue is always empty in production: a pre-await
+  signal resolves through the live `subscribeKind` tail, and
+  resume rehydration of a signal that arrived while the run was
+  offline is not wired. Plumbing the runtime body's own `RunState`
+  reader into the child is what that capability waits on.
 - `ipc/` — control and event channel implementations the
   supervisor wraps. Threat model lives at the top of
   `ipc/index.ts`; the supervisor uses these primitives directly.
@@ -287,7 +292,19 @@ The contract is intentionally narrow:
    factory returns `RunWorkflowChildBindings`: substrate `RepoStore`,
    principal, per-deployment repo ids, scheduler, step invoker, child
    spawner, grant evaluator. The factory consumes the typed struct,
-   never `NodeJS.ProcessEnv` directly.
+   never `NodeJS.ProcessEnv` directly. Each spawner declares
+   `hasUpstreamSignalResolver` on the runtime env it builds: `true`
+   for a run an answer can reach -- the deployment's own addressable
+   run, or a suspendable body whose container relays a decision back
+   down -- and `false` for a terminal `childWorkflow` child, which
+   carries no address and is run to its terminal rather than driven
+   across parks. The field is required, so an omission is a compile
+   error; a wrong `true` is not. Declared on a terminal-child seam it
+   type-checks and reinstates the hang the flag exists to remove. The
+   in-tree seams show both answers: `buildRuntimeEnv` declares `true`
+   for the deployment's own run, while in the sidecar's substrate
+   factory `createSidecarRunChild` declares `false` and
+   `createSidecarSpawnSuspendableChild` declares `true`.
 3. **The helper fails loudly.** A missing or malformed spawn-time
    env throws via `parseSpawnTimeEnv`; a substrate-config key the
    host listed but the supervisor did not populate throws before the

package/dist/adapters/mail-part-store.d.ts

@@ -0,0 +1,46 @@
+import type { Principal, RepoId, RepoStore as SubstrateRepoStore } from "@intx/hub-sessions/substrate";
+import type { Mail, MailPartReader, MessageHeaders, MessagePart } from "@intx/types/runtime";
+/**
+ * Thrown for a DETERMINISTIC, input-shaped rejection of an inbound mail -- a
+ * messageId that cannot form a usable path segment. Distinct from a transient
+ * substrate write failure so the caller drops the offending mail (replaying it
+ * would fail identically) rather than treating it as a retryable fault.
+ */
+export declare class InvalidMailError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export type MailPartStoreOpts = {
+    substrate: SubstrateRepoStore;
+    repoId: RepoId;
+    principal: Principal;
+    runId: string;
+    ref: string;
+};
+/**
+ * Commit a decoded message's parts and assemble the JSON-safe `Mail`. Every
+ * part's bytes are written in ONE prefix-preserving commit under the message's
+ * directory (write-once, atomic), and each part becomes a `MailPart` descriptor
+ * carrying its metadata, an opaque `ref`, and -- for a small UTF-8 text part --
+ * its decoded `text` inline.
+ */
+export declare function commitMail(opts: MailPartStoreOpts, messageId: string, decoded: {
+    headers: MessageHeaders;
+    rawHeaders: Record<string, string[]>;
+    parts: MessagePart[];
+}): Promise<Mail>;
+export type MailPartReaderOpts = {
+    substrate: SubstrateRepoStore;
+    repoId: RepoId;
+    principal: Principal;
+    ref: string;
+};
+/**
+ * Construct the single mail-part reader for a deployment's workflow-run repo.
+ * `read` resolves any run's `MailPart.ref` to the committed bytes through a
+ * committed read pinned to the object store, so a cross-run read (a childflow
+ * or body step resolving a parent's part) never observes the lagging working
+ * tree.
+ */
+export declare function createMailPartReader(opts: MailPartReaderOpts): MailPartReader;

package/dist/adapters/mail-part-store.js

@@ -0,0 +1,251 @@
+// Durable store for a run's inbound-mail parts.
+//
+// The supervisor decodes an inbound MIME message into parts (via `decodeMail`)
+// and commits each part's decoded bytes here as a real file under
+// `runs/<runId>/parts/<urlEncoded(messageId)>/<index>-<name>`, returning the
+// JSON-safe `MailPart[]` descriptors that ride in the run's trigger/signal
+// payload. A `MailPartReader` resolves a descriptor's opaque `ref` back to the
+// committed bytes for any consumer -- an agent's content-block projection, a
+// workflow tool, a child run -- through the single, environment-agnostic
+// `MailPartReader` interface.
+//
+// Modeled on the sibling `blob-substrate` adapter: same per-run handles, same
+// substrate primitives (`writeTreePreservingPrefix` to write raw bytes;
+// `openCommittedReads` to read them back from a coherent object-store snapshot
+// rather than the lagging working tree). The write happens in one commit per
+// message (write-once, atomic). The kind handler validates the subtree shape;
+// this module sanitizes untrusted names to satisfy it and reuses the handler's
+// path-component byte cap.
+import { MAX_MAIL_PART_PATH_COMPONENT_BYTES, WORKFLOW_RUN_PARTS_DIR, WORKFLOW_RUN_RUNS_PREFIX, } from "@intx/hub-sessions/substrate";
+const REF_SCHEME = "mail-part:///";
+// Content types whose bytes are UTF-8 text and small enough to also inline as
+// `MailPart.text`, so a selector can read them without resolving the ref.
+const INLINE_TEXT_MAX_BYTES = 1024 * 1024;
+const CONTROL_CHAR_MAX = 0x1f;
+const DEL_CHAR = 0x7f;
+// Unicode line/paragraph separators. JavaScript's regex `.` does NOT match
+// these, so the kind handler's `<index>-<name>` check (whose name group is
+// `.+`) rejects a filename containing them. The sanitizer must strip them to
+// keep its "satisfies the handler by construction" contract.
+const LINE_SEPARATOR = 0x2028;
+const PARAGRAPH_SEPARATOR = 0x2029;
+const encoder = new TextEncoder();
+function byteLength(value) {
+    return encoder.encode(value).length;
+}
+/**
+ * Thrown for a DETERMINISTIC, input-shaped rejection of an inbound mail -- a
+ * messageId that cannot form a usable path segment. Distinct from a transient
+ * substrate write failure so the caller drops the offending mail (replaying it
+ * would fail identically) rather than treating it as a retryable fault.
+ */
+export class InvalidMailError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "InvalidMailError";
+    }
+}
+function encodeMessageSegment(messageId) {
+    const encoded = encodeURIComponent(messageId);
+    if (byteLength(encoded) > MAX_MAIL_PART_PATH_COMPONENT_BYTES) {
+        throw new InvalidMailError(`mail part store: messageId ${JSON.stringify(messageId)} url-encodes to ${String(byteLength(encoded))} bytes, over the ${String(MAX_MAIL_PART_PATH_COMPONENT_BYTES)}-byte path-component limit`);
+    }
+    // `encodeURIComponent` leaves `.` unescaped, so "." or ".." would form a
+    // traversal segment; reject it where the messageId -> segment constraint is
+    // owned. An empty segment is unreachable for a non-empty messageId but is
+    // refused for the same reason.
+    if (encoded.length === 0 || encoded === "." || encoded === "..") {
+        throw new InvalidMailError(`mail part store: messageId ${JSON.stringify(messageId)} url-encodes to ${JSON.stringify(encoded)}, which is not a usable path segment`);
+    }
+    return encoded;
+}
+/**
+ * Reduce an untrusted part name (a MIME filename, or a fallback) to one safe
+ * path segment: path separators, NUL, and control characters become `_`. The
+ * `<index>-` prefix guarantees per-message uniqueness, so a sanitization
+ * collision between two parts of one message is harmless.
+ */
+function sanitizePartName(name) {
+    let out = "";
+    for (const ch of name) {
+        const code = ch.codePointAt(0) ?? 0;
+        out +=
+            ch === "/" ||
+                ch === "\\" ||
+                code <= CONTROL_CHAR_MAX ||
+                code === DEL_CHAR ||
+                code === LINE_SEPARATOR ||
+                code === PARAGRAPH_SEPARATOR
+                ? "_"
+                : ch;
+    }
+    return out.length > 0 ? out : "part";
+}
+/** Truncate to at most `maxBytes` UTF-8 bytes on a codepoint boundary. */
+function truncateToBytes(value, maxBytes) {
+    if (byteLength(value) <= maxBytes)
+        return value;
+    let out = "";
+    let used = 0;
+    for (const ch of value) {
+        const chBytes = byteLength(ch);
+        if (used + chBytes > maxBytes)
+            break;
+        out += ch;
+        used += chBytes;
+    }
+    return out;
+}
+/**
+ * The on-disk filename for one part: `<index>-<name>`, sanitized and truncated
+ * to the handler's byte cap. Satisfies the handler's `<index>-<name>` shape by
+ * construction.
+ */
+function partFilename(index, part) {
+    const prefix = `${String(index)}-`;
+    const budget = MAX_MAIL_PART_PATH_COMPONENT_BYTES - byteLength(prefix);
+    const rawName = part.filename ?? defaultPartName(part.contentType);
+    const safeName = truncateToBytes(sanitizePartName(rawName), budget);
+    return `${prefix}${safeName.length > 0 ? safeName : "part"}`;
+}
+/** A stable fallback name for a part with no filename, derived from its type. */
+function defaultPartName(contentType) {
+    const slash = contentType.indexOf("/");
+    const subtype = slash === -1 ? contentType : contentType.slice(slash + 1);
+    const safeSubtype = subtype.replace(/[^a-z0-9]+/gi, "") || "bin";
+    return `part.${safeSubtype}`;
+}
+function isTextType(contentType) {
+    return (contentType.startsWith("text/") ||
+        contentType === "application/json" ||
+        contentType === "application/vnd.interchange+json");
+}
+function mailPartRef(runId, messageSegment, filename) {
+    return `${REF_SCHEME}${encodeURIComponent(runId)}/${messageSegment}/${encodeURIComponent(filename)}`;
+}
+/**
+ * Parse a `mail-part:///` ref into its run id, message segment, and filename.
+ * The ref is persisted in the event log and re-read on resume, so it is
+ * treated as untrusted: the scheme must match, it must be exactly three
+ * non-empty segments, and no segment may traverse.
+ */
+function parseMailPartRef(ref) {
+    if (!ref.startsWith(REF_SCHEME)) {
+        throw new Error(`mail part reader: unrecognized ref ${JSON.stringify(ref)}`);
+    }
+    const rest = ref.slice(REF_SCHEME.length);
+    const segments = rest.split("/");
+    const malformed = `mail part reader: malformed ref ${JSON.stringify(ref)}`;
+    if (segments.length !== 3 ||
+        segments.some((s) => s.length === 0) ||
+        rest.includes("\\")) {
+        throw new Error(malformed);
+    }
+    // `runId` and `filename` were percent-encoded into the ref; `messageSegment`
+    // is stored encoded and matches the on-disk directory name verbatim.
+    let runId;
+    let filename;
+    try {
+        runId = decodeURIComponent(segments[0] ?? "");
+        filename = decodeURIComponent(segments[2] ?? "");
+    }
+    catch (cause) {
+        throw new Error(malformed, { cause });
+    }
+    const messageSegment = segments[1] ?? "";
+    // Reject traversal on the DECODED values too: a ref could encode `..`
+    // (`%2e%2e`) or a path separator (`%2f`, `%5c`) that only reveals itself
+    // after decoding, forming a compound traversal segment like `../..`.
+    const traverses = (s) => s === "." || s === ".." || s.includes("/") || s.includes("\\");
+    if ([runId, messageSegment, filename].some(traverses)) {
+        throw new Error(malformed);
+    }
+    return { runId, messageSegment, filename };
+}
+/**
+ * Commit a decoded message's parts and assemble the JSON-safe `Mail`. Every
+ * part's bytes are written in ONE prefix-preserving commit under the message's
+ * directory (write-once, atomic), and each part becomes a `MailPart` descriptor
+ * carrying its metadata, an opaque `ref`, and -- for a small UTF-8 text part --
+ * its decoded `text` inline.
+ */
+export async function commitMail(opts, messageId, decoded) {
+    const messageSegment = encodeMessageSegment(messageId);
+    const messagePrefix = `${WORKFLOW_RUN_RUNS_PREFIX}/${opts.runId}/${WORKFLOW_RUN_PARTS_DIR}/${messageSegment}/`;
+    const fresh = {};
+    const mailParts = decoded.parts.map((part, index) => {
+        const filename = partFilename(index, part);
+        fresh[`${messagePrefix}${filename}`] = part.content;
+        const descriptor = {
+            contentType: part.contentType,
+            ref: mailPartRef(opts.runId, messageSegment, filename),
+        };
+        if (part.filename !== undefined)
+            descriptor.filename = part.filename;
+        if (part.disposition !== undefined)
+            descriptor.disposition = part.disposition;
+        if (isTextType(part.contentType) &&
+            part.content.byteLength <= INLINE_TEXT_MAX_BYTES) {
+            descriptor.text = new TextDecoder("utf-8", { fatal: false }).decode(part.content);
+        }
+        return descriptor;
+    });
+    if (Object.keys(fresh).length > 0) {
+        try {
+            await opts.substrate.writeTreePreservingPrefix(opts.principal, opts.repoId, opts.ref, {
+                preservePrefix: messagePrefix,
+                merge: async (existing) => {
+                    const files = {};
+                    for (const [k, v] of existing)
+                        files[k] = v;
+                    for (const [k, v] of Object.entries(fresh))
+                        files[k] = v;
+                    return files;
+                },
+                message: `commit ${String(decoded.parts.length)} mail part(s) for message ${messageId} of run ${opts.runId}`,
+            });
+        }
+        catch (cause) {
+            const message = cause instanceof Error ? cause.message : String(cause);
+            // A path_violation is a shape rejection of this message's own (already
+            // sanitized) content: it is deterministic, so replaying the same bytes
+            // fails identically. Surface it as InvalidMailError so the caller drops
+            // the mail rather than retrying it forever as a transient fault.
+            if (message.startsWith("path_violation: ")) {
+                throw new InvalidMailError(message.slice("path_violation: ".length), {
+                    cause,
+                });
+            }
+            throw cause;
+        }
+    }
+    return {
+        headers: decoded.headers,
+        rawHeaders: decoded.rawHeaders,
+        parts: mailParts,
+    };
+}
+/**
+ * Construct the single mail-part reader for a deployment's workflow-run repo.
+ * `read` resolves any run's `MailPart.ref` to the committed bytes through a
+ * committed read pinned to the object store, so a cross-run read (a childflow
+ * or body step resolving a parent's part) never observes the lagging working
+ * tree.
+ */
+export function createMailPartReader(opts) {
+    return {
+        async read(ref) {
+            const { runId, messageSegment, filename } = parseMailPartRef(ref);
+            const dir = `${WORKFLOW_RUN_RUNS_PREFIX}/${runId}/${WORKFLOW_RUN_PARTS_DIR}/${messageSegment}`;
+            const reads = await opts.substrate.openCommittedReads(opts.principal, opts.repoId, opts.ref);
+            if (reads === null) {
+                throw new Error(`mail part reader: repo ${opts.repoId.id} ref ${opts.ref} has no committed tree; cannot resolve ${ref}`);
+            }
+            const entry = (await reads.listDir(dir)).find((e) => e.name === filename && e.type === "blob");
+            if (entry === undefined) {
+                throw new Error(`mail part reader: no committed part at ${dir}/${filename}`);
+            }
+            return reads.readBlobByOid(entry.oid);
+        },
+    };
+}

package/dist/adapters/repo-store.js

@@ -27,10 +27,9 @@
 //     prospective tree via `validatePush`. Translated into a thrown
 //     Error carrying the handler's `reason` text. No retries.
 import { type } from "arktype";
-import { subscribeKind, WORKFLOW_RUN_EVENTS_FILE, splitCombinedEventLog, } from "@intx/hub-sessions/substrate";
+import { parseEventSeq, subscribeKind, WORKFLOW_RUN_EVENTS_FILE, splitCombinedEventLog, } from "@intx/hub-sessions/substrate";
 const RUNS_PREFIX = "runs";
 const EVENTS_DIR = "events";
-const EVENT_FILENAME_RE = /^(0|[1-9][0-9]*)\.json$/;
 /**
  * On-disk envelope shape committed under
  * `runs/<runId>/events/<seq>.json`. Carries the seq cross-check the
@@ -141,13 +140,9 @@ async function readAllEventsForRun(opts, runId) {
     for (const child of eventBlobs) {
         if (child.type !== "blob")
             continue;
-        const match = EVENT_FILENAME_RE.exec(child.name);
-        if (match === null)
+        const seqFromName = parseEventSeq(child.name);
+        if (seqFromName === null)
             continue;
-        const seqStr = match[1];
-        if (seqStr === undefined)
-            continue;
-        const seqFromName = Number.parseInt(seqStr, 10);
         const raw = decoder.decode(await reads.readBlobByOid(child.oid));
         const source = `${opts.repoId.id}/${runId}/${EVENTS_DIR}/${child.name}`;
         const entry = parseEventEnvelope(raw, source);
@@ -262,13 +257,9 @@ async function appendBatchEvents(opts, runId, events) {
                 let priorLastSeq = 0;
                 for (const filepath of existing.keys()) {
                     const name = filepath.slice(prefix.length);
-                    const match = EVENT_FILENAME_RE.exec(name);
-                    if (match === null)
-                        continue;
-                    const seqStr = match[1];
-                    if (seqStr === undefined)
+                    const seq = parseEventSeq(name);
+                    if (seq === null)
                         continue;
-                    const seq = Number.parseInt(seqStr, 10);
                     if (seq > priorLastSeq)
                         priorLastSeq = seq;
                 }

package/dist/adapters/spawn-child.d.ts

@@ -1,5 +1,6 @@
 import type { InferenceEvent } from "@intx/types/runtime";
 import type { SpawnChildWorkflow, SpawnSuspendableChild, SuspendableChildHandle, WorkflowDefinition, WorkflowEvent } from "@intx/workflow";
+import type { CredentialMaterialRef } from "../child/run-child.js";
 /**
  * The terminal-status shape the runtime body expects back from a
  * spawn. Mirrored from `SpawnChildWorkflow`'s return type so the
@@ -16,7 +17,18 @@ export type ChildTerminalStatus = "completed" | "failed" | "cancelled";
  *
  * The callback receives the same `AbortSignal` the parent runtime
  * passed into the adapter so a parent-initiated cancellation
- * propagates to the child without an intermediate wrapper.
+ * propagates to the child without an intermediate wrapper. It also
+ * receives the parent run's live `onEvent` sink so the child's agent
+ * steps emit inference events up the same channel (mirroring
+ * {@link RunSuspendableChild}), and the spawn `depth` / ceiling so the
+ * child run's own spawns keep counting against the tree-wide bound.
+ *
+ * The callback also receives the parent run's live credential-material cell
+ * (the same reference the top-level step invoker reads live), so the child's
+ * inference resolves its source secret by `credentialId` against the run's
+ * current delivery -- a rotation the parent applies reaches the child through
+ * the shared reference. A non-sidecar executor that carries no credential
+ * material omits it.
  */
 export type RunChildWorkflow = (input: {
     definition: WorkflowDefinition;
@@ -26,7 +38,9 @@ export type RunChildWorkflow = (input: {
     parentRunId: string;
     parentStepId: string;
     signal: AbortSignal;
-}) => Promise<{
+    depth: number;
+    maxChildSpawnDepth: number;
+}, onEvent: (event: InferenceEvent) => void, credentialMaterial?: CredentialMaterialRef) => Promise<{
     terminalStatus: ChildTerminalStatus;
 }>;
 /**
@@ -43,10 +57,21 @@ export type RunChildWorkflow = (input: {
  * {@link createInMemorySpawnSuspendableChild} but drives the child terminal-only
  * (await its terminal status) rather than across approval parks.
  */
+/**
+ * Host-side widening of the runtime {@link SpawnChildWorkflow} contract: the
+ * same input plus the per-run `onEvent` sink the host injects. The runtime env
+ * carries the narrow `SpawnChildWorkflow` (no event slot); the caller wraps this
+ * with its run's `onEvent`, mirroring {@link HostSpawnSuspendableChild}. The
+ * sink is a call argument (not closed over at construction) because the resolver
+ * is selected once per deployment while `onEvent` is built per run. The run's
+ * live credential-material cell rides the same seam, so the child's inference
+ * reads the parent's current credential delivery.
+ */
+export type HostSpawnChild = (input: Parameters<SpawnChildWorkflow>[0], onEvent: (event: InferenceEvent) => void, credentialMaterial?: CredentialMaterialRef) => ReturnType<SpawnChildWorkflow>;
 export declare function createInMemorySpawnChild(opts: {
     bodies: ReadonlyMap<string, WorkflowDefinition>;
     runChild: RunChildWorkflow;
-}): SpawnChildWorkflow;
+}): HostSpawnChild;
 /**
  * Runtime-supplied suspendable child execution callback. The park-aware
  * analog of {@link RunChildWorkflow}: the supervisor owns the child
@@ -65,6 +90,8 @@ export type RunSuspendableChild = (input: {
     parentRunId: string;
     parentStepId: string;
     signal: AbortSignal;
+    depth: number;
+    maxChildSpawnDepth: number;
     resumeFromEvents?: readonly WorkflowEvent[];
 }, 
 /**
@@ -74,16 +101,25 @@ export type RunSuspendableChild = (input: {
  * silently dropped. Per-run durable attribution is unaffected -- the child
  * runtime commits its events under `runs/<childRunId>/events/` regardless.
  */
-onEvent: (event: InferenceEvent) => void) => Promise<SuspendableChildHandle>;
+onEvent: (event: InferenceEvent) => void, 
+/**
+ * The parent run's live credential-material cell. Threaded so the body's
+ * inference resolves its source secret by `credentialId` against the run's
+ * current delivery, reached live through the shared reference on a rotation.
+ * A non-sidecar executor that carries no credential material omits it.
+ */
+credentialMaterial?: CredentialMaterialRef) => Promise<SuspendableChildHandle>;
 /**
  * Host-side widening of the runtime {@link SpawnSuspendableChild} contract: the
  * same input plus the per-run `onEvent` sink the host injects. The runtime
  * calls the narrow `SpawnSuspendableChild` (no event slot); the host binding
  * wired into the runtime env closes over the run's funnel and forwards it here,
  * mirroring how `ChildStepInvoker` widens the runtime `StepInvoker` with
- * `onEvent`. The runtime contract in `@intx/workflow` stays untouched.
+ * `onEvent`. The runtime contract in `@intx/workflow` stays untouched. The
+ * run's live credential-material cell rides the same seam, so the body's
+ * inference reads the parent's current credential delivery.
  */
-export type HostSpawnSuspendableChild = (input: Parameters<SpawnSuspendableChild>[0], onEvent: (event: InferenceEvent) => void) => ReturnType<SpawnSuspendableChild>;
+export type HostSpawnSuspendableChild = (input: Parameters<SpawnSuspendableChild>[0], onEvent: (event: InferenceEvent) => void, credentialMaterial?: CredentialMaterialRef) => ReturnType<SpawnSuspendableChild>;
 /**
  * Construct the `WorkflowRuntimeEnv.SpawnSuspendableChild` adapter for the
  * source-ref (code-sourced) path -- the only deploy lineage. The parent child

package/dist/adapters/spawn-child.js

@@ -59,22 +59,8 @@
 // `runChild` does -- but the callback's input shape (`{ definition,
 // childRunId, ... }`) is the seam that makes the scoping unambiguous
 // at the boundary.
-/**
- * Construct the terminal `WorkflowRuntimeEnv.SpawnChildWorkflow` adapter for an
- * owned childWorkflow import. The child re-evaluated the whole pinned closure
- * and lifted every inline child to an internal `{ ref }`, so the child
- * definitions are in hand and already covered by the parent's re-verify.
- * Resolve each `definitionRef`
- * from the in-memory `bodies` map and delegate to the runtime-supplied
- * `runChild`, with NO on-disk round-trip and NO separate per-child re-verify:
- * materializing the child back out and re-fingerprinting it would round-trip
- * trusted-in-hand data for no gain, and the closure re-eval on restart
- * re-derives the same bodies durably. Mirrors
- * {@link createInMemorySpawnSuspendableChild} but drives the child terminal-only
- * (await its terminal status) rather than across approval parks.
- */
 export function createInMemorySpawnChild(opts) {
-    return async ({ definitionRef, childRunId, input, parentRunId, parentStepId, signal, }) => {
+    return async ({ definitionRef, childRunId, input, parentRunId, parentStepId, signal, depth, maxChildSpawnDepth, }, onEvent, credentialMaterial) => {
         if (signal.aborted) {
             throw abortError(signal);
         }
@@ -101,7 +87,9 @@ export function createInMemorySpawnChild(opts) {
             parentRunId,
             parentStepId,
             signal,
-        });
+            depth,
+            maxChildSpawnDepth,
+        }, onEvent, credentialMaterial);
         return { terminalStatus: result.terminalStatus };
     };
 }
@@ -119,7 +107,7 @@ export function createInMemorySpawnChild(opts) {
  * per-body boundary is the deferred, opt-in SandboxBoundary case).
  */
 export function createInMemorySpawnSuspendableChild(opts) {
-    return async ({ definitionRef, childRunId, input, parentRunId, parentStepId, signal, resumeFromEvents, }, onEvent) => {
+    return async ({ definitionRef, childRunId, input, parentRunId, parentStepId, signal, depth, maxChildSpawnDepth, resumeFromEvents, }, onEvent, credentialMaterial) => {
         if (signal.aborted) {
             throw abortError(signal);
         }
@@ -140,8 +128,10 @@ export function createInMemorySpawnSuspendableChild(opts) {
             parentRunId,
             parentStepId,
             signal,
+            depth,
+            maxChildSpawnDepth,
             ...(resumeFromEvents !== undefined ? { resumeFromEvents } : {}),
-        }, onEvent);
+        }, onEvent, credentialMaterial);
     };
 }
 /**

package/dist/adapters/step-invoker.d.ts

@@ -1,7 +1,7 @@
 import { type Agent, type AgentDefinition, type BaseEnv } from "@intx/agent";
-import type { InferenceEvent, InferenceSource } from "@intx/types/runtime";
+import type { InboundMessage, InferenceEvent, InferenceSource, MailPartReader } from "@intx/types/runtime";
 import type { StepInvokeRequest, StepInvoker, WorkflowAuthorizeFn } from "@intx/workflow";
-import type { WarmAgentCache } from "../child/warm-agent-cache.js";
+import type { WarmAgentCache, WarmReplyDrive } from "../child/warm-agent-cache.js";
 /**
  * Per-step env contributions the caller of the adapter owns.
  *
@@ -104,6 +104,56 @@ export interface WorkflowStepInvokerOpts {
      * has no cross-run conversation to mirror.
      */
     onRunBoundary?: (key: string) => Promise<void>;
+    /**
+     * Seed hook for the warm path (design §3c threading). When supplied, the
+     * adapter calls it before `agent.send` on every message whose delivered
+     * input is a mail-derived `InboundMessage`, passing the step identity
+     * (`authzContext.stepId`, the same key `onRunBoundary` and the warm cache
+     * use) and that message. The sidecar wires this to the warm agent's
+     * durable conversation store, which routes the message onto the connector
+     * thread (seeding threadRoot / lastMessageId / replyTo) so the reply path
+     * can compose a threaded reply. Awaited before the send so the thread
+     * state is committed and durably flushed before the reply is produced; a
+     * seed failure surfaces by rejecting the step.
+     *
+     * Only mail-derived inbound messages seed: an approval-resume inbound
+     * carries a synthetic sender and a correlation id, and a synthesized
+     * string input is not a message, so neither advances the connector
+     * thread. Omitted on the cold path, which has no durable connector state
+     * to seed.
+     */
+    seedInbound?: (key: string, message: InboundMessage) => Promise<void>;
+    /**
+     * Connector reply-drain hook for the warm path (design §3c). When supplied,
+     * the adapter invokes it ONCE -- at the warm agent's first-message build --
+     * with the step identity (`authzContext.stepId`, the same key the warm
+     * cache, seed, and run-boundary hooks use) and the agent's lifetime event
+     * stream. The sidecar wires this to the shared connector reply drain: on
+     * every `connector.reply` the agent emits, the drain composes a threaded
+     * reply from the durable store's connector thread and sends it through the
+     * supervisor-backed outbound bridge, then advances the thread from the send
+     * receipt.
+     *
+     * The returned drive handle exposes the drain's lifetime `done` promise --
+     * which settles when the agent's stream ends at eviction, folded into the
+     * warm entry's event-forward promise so the cache drains the reply loop
+     * alongside the observability forwarder -- plus the per-turn settle barrier
+     * (`replySeq` / `waitForReplyAfter`) the warm step gates each reply turn on,
+     * so the run parks only after the reply is durably sent.
+     *
+     * Omitted on the cold path (a torn-down per-step agent has no cross-message
+     * connector thread) and whenever the deployment is not warm-kept.
+     */
+    driveReplies?: (key: string, stream: ReturnType<Agent["stream"]>) => WarmReplyDrive;
+    /**
+     * Reader for the run's inbound-mail parts. When the step input is a decoded
+     * `Mail`, the adapter resolves each part's `ref` to its committed bytes
+     * through this reader and delivers a real `InboundMessage` (text and/or
+     * attachments) to `agent.send`. Supplied by the run child for the top-level
+     * run's steps; absent for body steps, where a part whose bytes must be read
+     * is refused loudly rather than silently flattened to text.
+     */
+    mailPartReader?: MailPartReader;
 }
 /**
  * Construct the production `WorkflowRuntimeEnv.StepInvoker` adapter.