@intx/workflow-host 0.2.2

package/dist/child/env-bootstrap.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The required spawn-time env keys, named once so the supervisor-side
+ * producer (`buildChildSpawnEnv`) and this child-side parser share a
+ * single required-key contract. `WARM_KEEP` is optional and lives only in
+ * the shape below. The producer types its output against this list
+ * (`Record<RequiredSpawnEnvKey, string>`), so omitting a listed key is a
+ * compile error. That this list stays in step with the validator shape
+ * below -- a hand-maintained arktype object -- is covered by the recycle
+ * env-contract regression test, which drives the real producer through
+ * this parser. This is the contract whose drift once omitted `STEP_COUNT`
+ * from the recycle env and broke every recycle.
+ */
+export declare const REQUIRED_SPAWN_ENV_KEYS: readonly ["IPC_CHANNEL_ID", "IPC_HMAC_KEY", "HOST_PUBKEY", "DEPLOYMENT_ID", "DEFINITION_HASH", "MAILBOX_ADDRESS", "STEP_COUNT"];
+export type RequiredSpawnEnvKey = (typeof REQUIRED_SPAWN_ENV_KEYS)[number];
+/**
+ * Parsed and validated spawn-time env. The hex-encoded trust anchors
+ * decode to their raw byte representations so the IPC channel
+ * constructors can consume them without re-validating the hex shape.
+ */
+export interface SpawnTimeEnv {
+    /** Channel identifier minted by the supervisor for this spawn. */
+    channelId: string;
+    /** 32-byte shared HMAC key for the event channel. */
+    hmacKey: Uint8Array;
+    /** Supervisor's 32-byte Ed25519 public key for control-frame verification. */
+    hostPublicKey: Uint8Array;
+    /** Deployment identity the supervisor manages. */
+    deploymentId: string;
+    /** Content hash of the deployed `WorkflowDefinition`. */
+    definitionHash: string;
+    /** Mail address the deployment registered on the bus. */
+    mailboxAddress: string;
+    /**
+     * Number of steps in the deployed `WorkflowDefinition`
+     * (`stepOrder.length`). Selects the head/step collapse in the sidecar's
+     * `resolveStepAddress`: a single-step deployment reads its deploy tree
+     * at the head, a multi-step deployment at the per-step address.
+     */
+    stepCount: number;
+    /**
+     * Whether this deployment's agent is warm-kept across messages (design
+     * §3b). True only for the single-step long-lived deployment the deploy
+     * projection marked a warm candidate; the run-loop builds a warm-agent
+     * cache when set and keeps cold instantiate-send-teardown otherwise.
+     */
+    warmKeep: boolean;
+}
+/**
+ * Parse and validate `process.env`-shaped input into the typed
+ * `SpawnTimeEnv` struct. Any missing key, malformed hex, or off-size
+ * byte payload throws so the binary aborts before opening IPC.
+ *
+ * The validator runs at the boundary; downstream consumers trust the
+ * parsed struct without re-checking.
+ */
+export declare function parseSpawnTimeEnv(rawEnv: Record<string, string | undefined>): SpawnTimeEnv;

package/dist/child/env-bootstrap.js

@@ -0,0 +1,120 @@
+// Spawn-time env parser for the workflow-process child.
+//
+// The supervisor's spawn path constructs a fresh env object carrying
+// only the IPC trust anchors plus a tightly-scoped set of deployment
+// identifiers. The binary parses `process.env` once at start and hands
+// the validated struct to `runWorkflowChild`. The struct shape is the
+// only env-shaped surface the runtime body sees; everything else flows
+// through IPC frames.
+//
+// The IPC trust anchors carried here are public-half values: the
+// supervisor's Ed25519 PUBLIC key (`HOST_PUBKEY`) plus the shared HMAC
+// key (`IPC_HMAC_KEY`) the supervisor minted at spawn time. The
+// supervisor's Ed25519 PRIVATE key never appears in env per the IPC
+// threat model; the child verifies but never signs control frames.
+import { type } from "arktype";
+import { hexDecode } from "@intx/types";
+import { IPC_CRYPTO } from "../ipc/index.js";
+/**
+ * The required spawn-time env keys, named once so the supervisor-side
+ * producer (`buildChildSpawnEnv`) and this child-side parser share a
+ * single required-key contract. `WARM_KEEP` is optional and lives only in
+ * the shape below. The producer types its output against this list
+ * (`Record<RequiredSpawnEnvKey, string>`), so omitting a listed key is a
+ * compile error. That this list stays in step with the validator shape
+ * below -- a hand-maintained arktype object -- is covered by the recycle
+ * env-contract regression test, which drives the real producer through
+ * this parser. This is the contract whose drift once omitted `STEP_COUNT`
+ * from the recycle env and broke every recycle.
+ */
+export const REQUIRED_SPAWN_ENV_KEYS = [
+    "IPC_CHANNEL_ID",
+    "IPC_HMAC_KEY",
+    "HOST_PUBKEY",
+    "DEPLOYMENT_ID",
+    "DEFINITION_HASH",
+    "MAILBOX_ADDRESS",
+    "STEP_COUNT",
+];
+/**
+ * Required env keys carried by the supervisor at spawn time. The
+ * validator surface is intentionally narrow: every key documented at
+ * the supervisor's `spawn(opts)` method is represented here, and
+ * anything the supervisor did not place in the env causes a targeted
+ * failure rather than a silent fallback.
+ */
+const SpawnTimeEnvShape = type({
+    IPC_CHANNEL_ID: "string > 0",
+    IPC_HMAC_KEY: "string > 0",
+    HOST_PUBKEY: "string > 0",
+    DEPLOYMENT_ID: "string > 0",
+    DEFINITION_HASH: "string > 0",
+    MAILBOX_ADDRESS: "string > 0",
+    // Step count of the deployed `WorkflowDefinition` (`stepOrder.length`),
+    // stringified by the supervisor. The child's deploy-tree read collapses
+    // onto the head for a single-step deployment (`resolveStepAddress`), so
+    // producer and consumer never derive divergent step addresses. Parsed to
+    // a positive integer below; a non-integer or non-positive value throws.
+    STEP_COUNT: "string > 0",
+    // Warm-keep signal (design §3b). The supervisor sets this to the
+    // string `"true"` only for the single-step long-lived deployment the
+    // deploy projection marked a warm candidate; any other value (or the
+    // key's absence) means cold instantiate-send-teardown per message.
+    // Carried explicitly rather than re-derived heuristically in the child
+    // so the warm-keep decision is deterministic and a multi-step agent is
+    // never warm-kept by a silent default.
+    "WARM_KEEP?": "string",
+}).onUndeclaredKey("ignore");
+/**
+ * Parse and validate `process.env`-shaped input into the typed
+ * `SpawnTimeEnv` struct. Any missing key, malformed hex, or off-size
+ * byte payload throws so the binary aborts before opening IPC.
+ *
+ * The validator runs at the boundary; downstream consumers trust the
+ * parsed struct without re-checking.
+ */
+export function parseSpawnTimeEnv(rawEnv) {
+    const present = {};
+    for (const [key, value] of Object.entries(rawEnv)) {
+        if (value !== undefined)
+            present[key] = value;
+    }
+    const validated = SpawnTimeEnvShape(present);
+    if (validated instanceof type.errors) {
+        throw new Error(`workflow-child spawn-time env failed validation: ${validated.summary}`);
+    }
+    const hmacKey = hexDecode(validated.IPC_HMAC_KEY);
+    if (hmacKey.length !== IPC_CRYPTO.HMAC_KEY_BYTES) {
+        throw new Error(`workflow-child IPC_HMAC_KEY must decode to ${String(IPC_CRYPTO.HMAC_KEY_BYTES)} bytes; got ${String(hmacKey.length)}`);
+    }
+    const hostPublicKey = hexDecode(validated.HOST_PUBKEY);
+    if (hostPublicKey.length !== IPC_CRYPTO.ED25519_KEY_BYTES) {
+        throw new Error(`workflow-child HOST_PUBKEY must decode to ${String(IPC_CRYPTO.ED25519_KEY_BYTES)} bytes; got ${String(hostPublicKey.length)}`);
+    }
+    // The channelId is supervisor-minted and the receiver compares it
+    // byte-for-byte against incoming frames. Hex-decoding here would
+    // surface a malformed value but the IPC primitives expect the
+    // hex-encoded string form, so we only verify the encoded length
+    // matches the documented channelId byte width.
+    const expectedChannelIdHex = IPC_CRYPTO.CHANNEL_ID_BYTES * 2;
+    if (validated.IPC_CHANNEL_ID.length !== expectedChannelIdHex) {
+        throw new Error(`workflow-child IPC_CHANNEL_ID must be ${String(expectedChannelIdHex)} hex chars; got ${String(validated.IPC_CHANNEL_ID.length)}`);
+    }
+    const stepCount = Number(validated.STEP_COUNT);
+    if (!Number.isInteger(stepCount) || stepCount <= 0) {
+        throw new Error(`workflow-child STEP_COUNT must be a positive integer; got ${JSON.stringify(validated.STEP_COUNT)}`);
+    }
+    return {
+        channelId: validated.IPC_CHANNEL_ID,
+        hmacKey,
+        hostPublicKey,
+        deploymentId: validated.DEPLOYMENT_ID,
+        definitionHash: validated.DEFINITION_HASH,
+        mailboxAddress: validated.MAILBOX_ADDRESS,
+        stepCount,
+        // Strict `=== "true"` so any other value (including the key's
+        // absence) reads false. Warm-keep is opt-in and deterministic; a
+        // typo'd or partial value must not silently enable it.
+        warmKeep: validated.WARM_KEEP === "true",
+    };
+}

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

@@ -0,0 +1,127 @@
+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 FrameWriter, type NdjsonReader, type NdjsonWriter } from "../ipc/index.js";
+/**
+ * File descriptor the supervisor's `Bun.spawn` wires the
+ * event-channel socketpair onto. The supervisor's spawn convention
+ * inherits stdio 0/1/2 for stdin/stdout/stderr and the
+ * event-channel write side at fd 3 in the child's address space.
+ * The wrapper opens fd 3 as the child's `FrameWriter`.
+ */
+export declare const EVENT_CHANNEL_FD = 3;
+/**
+ * Substrate-config env keys the host promises to its factory. The
+ * supervisor's spawn-time env always carries the IPC trust anchors
+ * plus the deployment identifiers (parsed via `parseSpawnTimeEnv`).
+ * `substrateConfig` carries every key the host placed in
+ * `WorkflowSupervisorBindings.substrateEnv` -- the host's own narrow
+ * struct (data-dir, signing-key paths, definition-repo identifiers)
+ * lives there, and the factory narrows it again on the way in.
+ *
+ * The factory does NOT receive `NodeJS.ProcessEnv` directly. The
+ * surface is intentionally narrow so a future env-shaped surface
+ * (a CLI launcher that prepends keys, a test harness that injects
+ * extra knobs) crosses this contract explicitly rather than via
+ * an opaque process-shaped slot.
+ */
+export interface SubstrateFactoryEnv {
+    /** Parsed spawn-time env (IPC trust anchors + deployment ids). */
+    readonly spawn: SpawnTimeEnv;
+    /**
+     * Substrate-config keys the host placed in
+     * `WorkflowSupervisorBindings.substrateEnv`. The factory narrows
+     * its own required-key shape against this record at the boundary.
+     */
+    readonly substrateConfig: Readonly<Record<string, string>>;
+    /**
+     * Child-side IPC bridge over the upstream control channel for the
+     * workflow-run substrate-write surface. The substrate factory uses
+     * this to construct its proxy `RepoStore`, whose
+     * `writeTreePreservingPrefix` forwards over IPC into the
+     * supervisor's substrate. The bridge's `submit` sends a
+     * `substrate.write.request` upstream control frame; the supervisor
+     * runs its own underlying `writeTreePreservingPrefix` (which fires
+     * the boot-edge pack-push wrap on success) and replies with a
+     * matching `substrate.write.response` the bridge resolves the
+     * awaiter against. The supervisor's merge callback runs as a
+     * `substrate.merge.request` / `substrate.merge.response` pair so
+     * the child's per-write merge closure stays in the child's address
+     * space.
+     */
+    readonly substrateWriteBridge: ChildSubstrateWriteBridge;
+    /**
+     * Child-side IPC bridge over the upstream control channel for the
+     * OUTBOUND half of mailbox ownership (§3a). The substrate factory uses
+     * this to construct the supervisor-backed `MessageTransport` it
+     * supplies as the step agent's `env.transport`: the transport's
+     * `send` calls `bridge.submit`, which emits an `outbound.message`
+     * upstream frame and resolves once the supervisor's matching
+     * `outbound.result` lands. The supervisor performs the actual signed
+     * send through the host transport, so outbound mail carries the
+     * agent's signature without the child ever holding the agent's key.
+     */
+    readonly outboundMailBridge: ChildOutboundMailBridge;
+}
+/**
+ * Substrate-factory callback the host supplies to
+ * `runWorkflowChildFromProcessEnv`. The factory constructs the
+ * `RunWorkflowChildBindings` the runtime body consumes:
+ * substrate-shaped `RepoStore`, principal, per-deployment repo ids,
+ * scheduler, step invoker, child spawner, grant evaluator. The
+ * factory owns every concrete dependency the runtime body needs to
+ * see; the wrapper itself depends on nothing host-specific.
+ */
+export type SubstrateFactory = (env: SubstrateFactoryEnv) => Promise<RunWorkflowChildBindings>;
+/**
+ * Optional overrides for the process-shaped surfaces the wrapper
+ * crosses. Production hosts use the defaults; tests can inject
+ * in-memory streams. The fields exist so a host that wants to
+ * compose the wrapper around its own logging layer or telemetry
+ * surface can pass through, without exposing `process.env` to the
+ * factory.
+ */
+export interface RunWorkflowChildFromProcessEnvOpts {
+    /** Override the raw env record (defaults to `process.env`). */
+    rawEnv?: Readonly<Record<string, string | undefined>>;
+    /** Override the control-channel reader (defaults to `process.stdin`). */
+    controlReader?: NdjsonReader;
+    /** Override the control-channel writer (defaults to `process.stdout`). */
+    controlWriter?: NdjsonWriter;
+    /** Override the event-channel writer (defaults to a wrap of fd 3). */
+    eventWriter?: FrameWriter;
+    /**
+     * Override which env keys are forwarded to the factory's
+     * `substrateConfig`. Keys not in this allowlist are filtered out.
+     * Production hosts list their own substrate-config keys here so the
+     * factory never sees spawn-time IPC keys (those flow through the
+     * typed `spawn` slot) or unrelated process env. The default is the
+     * empty allowlist -- a host that wants its factory to receive
+     * substrate-config keys MUST name them here.
+     */
+    substrateConfigKeys?: readonly string[];
+}
+/**
+ * Process-boundary wrapper around `runWorkflowChild`. The wrapper
+ * parses `process.env` into the typed `SpawnTimeEnv` plus a narrow
+ * substrate-config record, opens stdin/stdout for the control
+ * channel, wraps the inherited event-channel fd into a
+ * `FrameWriter`, hands the typed env to the host's substrate
+ * factory to mint the runtime body's bindings, and invokes
+ * `runWorkflowChild`.
+ *
+ * Failures surface loudly:
+ *   - missing or malformed spawn-time env throws via
+ *     `parseSpawnTimeEnv`;
+ *   - a substrate-config key listed in `substrateConfigKeys` whose
+ *     value is missing or empty throws;
+ *   - factory rejection propagates;
+ *   - `runWorkflowChild` rejection propagates.
+ *
+ * The wrapper does not catch or coerce failures. The host's binary
+ * is the layer that decides what to do with a thrown error; the
+ * convention shown in the documentation is `process.exit(1)` with
+ * a stderr message.
+ */
+export declare function runWorkflowChildFromProcessEnv(factory: SubstrateFactory, opts?: RunWorkflowChildFromProcessEnvOpts): Promise<RunWorkflowChildResult>;

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

@@ -0,0 +1,183 @@
+// Process-shaped convenience wrapper around `runWorkflowChild`.
+//
+// The wrapper crosses the only boundary that touches `process.env`,
+// `process.stdin`/`process.stdout`, and the inherited event-channel
+// file descriptor. Each host ships a ~5-line entry script
+// (`#!/usr/bin/env bun` + an `import` + an `await` of this function)
+// against a substrate-factory of its own; the factory consumes a
+// narrow typed env struct rather than `NodeJS.ProcessEnv`, and the
+// runtime body never sees the process boundary.
+//
+// The factory's typed env carries the spawn-time keys the supervisor
+// promises plus the substrate-config keys the host injected on top.
+// The supervisor's `WorkflowSupervisorBindings.substrateEnv` is the
+// only documented surface for the substrate-config slot; the host
+// places its own data-dir / signing-key / definition-repo keys there
+// at supervisor-construction time and reads them back here.
+import fs from "node:fs";
+import { type } from "arktype";
+import { generateKeyPair } from "@intx/crypto";
+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 { createControlChannelSender, } from "../ipc/index.js";
+/**
+ * File descriptor the supervisor's `Bun.spawn` wires the
+ * event-channel socketpair onto. The supervisor's spawn convention
+ * inherits stdio 0/1/2 for stdin/stdout/stderr and the
+ * event-channel write side at fd 3 in the child's address space.
+ * The wrapper opens fd 3 as the child's `FrameWriter`.
+ */
+export const EVENT_CHANNEL_FD = 3;
+/**
+ * Process-boundary wrapper around `runWorkflowChild`. The wrapper
+ * parses `process.env` into the typed `SpawnTimeEnv` plus a narrow
+ * substrate-config record, opens stdin/stdout for the control
+ * channel, wraps the inherited event-channel fd into a
+ * `FrameWriter`, hands the typed env to the host's substrate
+ * factory to mint the runtime body's bindings, and invokes
+ * `runWorkflowChild`.
+ *
+ * Failures surface loudly:
+ *   - missing or malformed spawn-time env throws via
+ *     `parseSpawnTimeEnv`;
+ *   - a substrate-config key listed in `substrateConfigKeys` whose
+ *     value is missing or empty throws;
+ *   - factory rejection propagates;
+ *   - `runWorkflowChild` rejection propagates.
+ *
+ * The wrapper does not catch or coerce failures. The host's binary
+ * is the layer that decides what to do with a thrown error; the
+ * convention shown in the documentation is `process.exit(1)` with
+ * a stderr message.
+ */
+export async function runWorkflowChildFromProcessEnv(factory, opts = {}) {
+    const rawEnv = opts.rawEnv ?? process.env;
+    const spawn = parseSpawnTimeEnv(rawEnv);
+    const substrateConfig = filterSubstrateConfig(rawEnv, opts.substrateConfigKeys ?? []);
+    const controlReader = opts.controlReader ?? defaultControlReader();
+    const controlWriter = opts.controlWriter ?? defaultControlWriter();
+    const eventWriter = opts.eventWriter ?? defaultEventWriter();
+    // Mint the child's upstream-signing keypair here so the wrapper can
+    // construct the upstream sender before invoking the substrate
+    // factory: the factory consumes the sender via the pack-push bridge
+    // to build its `ChildHubPackSink`, and the same sender carries the
+    // `ready` frame `runWorkflowChild` emits.
+    const childKeyPair = await generateKeyPair();
+    const upstreamSender = createControlChannelSender({
+        privateKeySeed: childKeyPair.privateKey,
+        channelId: spawn.channelId,
+        writer: controlWriter,
+    });
+    const substrateWriteBridge = createChildSubstrateWriteBridge({
+        upstreamSender,
+    });
+    const outboundMailBridge = createChildOutboundMailBridge({
+        upstreamSender,
+    });
+    const bindings = await factory({
+        spawn,
+        substrateConfig,
+        substrateWriteBridge,
+        outboundMailBridge,
+    });
+    return runWorkflowChild({
+        env: spawn,
+        controlReader,
+        controlWriter,
+        eventWriter,
+        bindings: {
+            ...bindings,
+            // The child key pair is minted at this layer so the upstream
+            // sender and the `ready` frame's `childPublicKey` come from one
+            // keypair. Override the factory's path so `runWorkflowChild`
+            // does not re-mint a different key and break verification.
+            ipcChildKeyPairFactory: () => Promise.resolve(childKeyPair),
+        },
+        upstreamSender,
+        substrateWriteBridge,
+        outboundMailBridge,
+    });
+}
+const SubstrateConfigValue = type("string > 0");
+function filterSubstrateConfig(rawEnv, keys) {
+    const out = {};
+    for (const key of keys) {
+        const value = rawEnv[key];
+        if (value === undefined) {
+            throw new Error(`workflow-child substrate-config env: required key ${key} is unset`);
+        }
+        const validated = SubstrateConfigValue(value);
+        if (validated instanceof type.errors) {
+            throw new Error(`workflow-child substrate-config env: ${key} failed validation: ${validated.summary}`);
+        }
+        out[key] = validated;
+    }
+    return out;
+}
+function defaultControlReader() {
+    return {
+        read() {
+            return readNdjsonLines(process.stdin);
+        },
+    };
+}
+function defaultControlWriter() {
+    return {
+        write(line) {
+            return new Promise((resolve, reject) => {
+                process.stdout.write(line, (err) => {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
+            });
+        },
+    };
+}
+function defaultEventWriter() {
+    // The supervisor inherits the event-channel write side on fd 3 in
+    // the child's address space. Wrap it as a Node writable so the
+    // wire matches the supervisor's `FrameReader` half. Failing to
+    // open fd 3 surfaces loudly: the child cannot publish
+    // InferenceEvents without it.
+    const stream = fs.createWriteStream("", { fd: EVENT_CHANNEL_FD });
+    return {
+        write(bytes) {
+            return new Promise((resolve, reject) => {
+                stream.write(bytes, (err) => {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
+            });
+        },
+    };
+}
+async function* readNdjsonLines(source) {
+    // Buffered line splitter over the source stream. Yields one JSON
+    // line per iteration; trailing newlines are stripped so callers
+    // see exactly what the sender wrote without a wire-shape
+    // re-decode.
+    const decoder = new TextDecoder("utf-8");
+    let pending = "";
+    for await (const chunk of source) {
+        const text = typeof chunk === "string"
+            ? chunk
+            : decoder.decode(chunk, { stream: true });
+        pending += text;
+        let nl = pending.indexOf("\n");
+        while (nl >= 0) {
+            const line = pending.slice(0, nl).replace(/\r$/, "");
+            pending = pending.slice(nl + 1);
+            if (line.length > 0)
+                yield line;
+            nl = pending.indexOf("\n");
+        }
+    }
+    if (pending.length > 0)
+        yield pending;
+}

package/dist/child/index.d.ts

@@ -0,0 +1,9 @@
+export { createCredentialsBackedAuthorize, hashGrants, runWorkflowChild, type ChildStepInvoker, type CredentialsSnapshotRef, 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 { 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";
+export { createWarmAgentCache, type WarmAgentCache, type WarmEventSinkRef, } from "./warm-agent-cache.js";
+export { EVENT_CHANNEL_FD, runWorkflowChildFromProcessEnv, type RunWorkflowChildFromProcessEnvOpts, type SubstrateFactory, type SubstrateFactoryEnv, } from "./from-process-env.js";

package/dist/child/index.js

@@ -0,0 +1,9 @@
+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 { createProxyWorkflowRunRepoStore, } from "./proxy-repo-store.js";
+export { parseSpawnTimeEnv } from "./env-bootstrap.js";
+export { discoverInFlightRuns, } from "./self-discovery.js";
+export { createWarmAgentCache, } from "./warm-agent-cache.js";
+export { EVENT_CHANNEL_FD, runWorkflowChildFromProcessEnv, } from "./from-process-env.js";

package/dist/child/outbound-mail-bridge.d.ts

@@ -0,0 +1,36 @@
+import type { OutboundMessage, SendReceipt } from "@intx/types/runtime";
+import type { ControlChannelSender, ControlPayload } from "../ipc/control-channel.js";
+/**
+ * Bridge surface the child's supervisor-backed transport reaches into.
+ * `submit` sends an `outbound.message` upstream and resolves once the
+ * supervisor's matching `outbound.result` lands. `handleResult` is the
+ * receiver-side entry point the child's control loop invokes when the
+ * downstream `outbound.result` frame arrives. `cancelAll` is the
+ * cleanup hook the control loop invokes on any exit path so a pending
+ * send does not leak an awaiter when the supervisor has torn the IPC
+ * down.
+ */
+export interface ChildOutboundMailBridge {
+    submit(senderAddress: string, message: OutboundMessage): Promise<SendReceipt>;
+    handleResult(data: Extract<ControlPayload, {
+        type: "outbound.result";
+    }>["data"]): void;
+    cancelAll(reason: string): void;
+    readonly pendingCount: number;
+}
+export interface CreateChildOutboundMailBridgeOpts {
+    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 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 declare function createChildOutboundMailBridge(opts: CreateChildOutboundMailBridgeOpts): ChildOutboundMailBridge;