@intx/workflow-host 0.2.2

package/dist/child/self-discovery.d.ts

@@ -0,0 +1,29 @@
+import type { RepoId, RepoStore as SubstrateRepoStore } from "@intx/hub-sessions/substrate";
+import { type RunState, type WorkflowEvent } from "@intx/workflow";
+import type { RepoStore as RuntimeRepoStore } from "@intx/workflow";
+/**
+ * Per-run discovery entry. The runtime body re-applies `seedEvents`
+ * via its `resumeFromEvents` path and resumes the run from
+ * `resumedState`. The caller hands both into `runtimeRun`.
+ */
+export interface DiscoveredRun {
+    runId: string;
+    seedEvents: readonly WorkflowEvent[];
+    resumedState: RunState;
+}
+export interface DiscoverRunsOpts {
+    /** Workflow-run substrate repo store. */
+    substrate: SubstrateRepoStore;
+    /** Workflow-run repo identity. */
+    repoId: RepoId;
+    /** Runtime-env `RepoStore` adapter the runs are read through. */
+    runtimeRepoStore: RuntimeRepoStore;
+}
+/**
+ * Enumerate `runs/<runId>/` subdirectories and return one
+ * `DiscoveredRun` entry per run whose log does not already end with a
+ * terminal event. Runs that already terminated are skipped because
+ * resume against a terminal log would still settle without progress
+ * but would generate spurious "resume seed" reads for no benefit.
+ */
+export declare function discoverInFlightRuns(opts: DiscoverRunsOpts): Promise<readonly DiscoveredRun[]>;

package/dist/child/self-discovery.js

@@ -0,0 +1,57 @@
+// Self-discovery: enumerate in-flight runs from the workflow-run repo
+// at startup and surface their event logs so the child can resume
+// each one in place.
+//
+// The supervisor does not pass an explicit list of runs; the
+// workflow-run repo's `runs/<runId>/` subtree is the authoritative
+// ledger. A run is in-flight if its log lacks a terminal event
+// (`RunCompleted`, `RunFailed`, `RunCancelled`). Resume seeds the
+// runtime body via the seed-events path on `runtimeRun`.
+//
+// Working-tree-read pattern: the substrate's `getRepoDir(repoId)` is a
+// pure path computation; sibling production adapters
+// (`adapters/repo-store.ts`, `adapters/blob-substrate.ts`,
+// `adapters/spawn-child.ts`) read working-tree contents directly via
+// `node:fs/promises`. Self-discovery follows the same path so a
+// startup scan does not need to consult the git object database.
+import { isTerminalRunPhase, resumeFromLog, } from "@intx/workflow";
+const RUNS_PREFIX = "runs";
+/**
+ * Enumerate `runs/<runId>/` subdirectories and return one
+ * `DiscoveredRun` entry per run whose log does not already end with a
+ * terminal event. Runs that already terminated are skipped because
+ * resume against a terminal log would still settle without progress
+ * but would generate spurious "resume seed" reads for no benefit.
+ */
+export async function discoverInFlightRuns(opts) {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    const dir = opts.substrate.getRepoDir(opts.repoId);
+    const runsDir = path.join(dir, RUNS_PREFIX);
+    let runDirs;
+    try {
+        runDirs = await fs.readdir(runsDir);
+    }
+    catch (cause) {
+        if (isErrnoNotFound(cause))
+            return [];
+        throw cause;
+    }
+    const out = [];
+    for (const runId of runDirs) {
+        const events = await opts.runtimeRepoStore.read(runId);
+        if (events.length === 0)
+            continue;
+        const resumed = resumeFromLog(runId, events);
+        if (isTerminalRunPhase(resumed.phase))
+            continue;
+        out.push({ runId, seedEvents: events, resumedState: resumed });
+    }
+    return out;
+}
+function isErrnoNotFound(cause) {
+    if (cause === null || typeof cause !== "object")
+        return false;
+    const code = cause.code;
+    return code === "ENOENT";
+}

package/dist/child/substrate-write-bridge.d.ts

@@ -0,0 +1,72 @@
+import type { ControlChannelSender, ControlPayload } from "../ipc/control-channel.js";
+/**
+ * Arguments the bridge takes per `writeTreePreservingPrefix` call. The
+ * shape mirrors the substrate's `WriteTreePreservingPrefixArgs` plus
+ * the repoId/ref the supervisor needs to route the write to the right
+ * underlying substrate.
+ */
+export interface SubstrateWriteRequest {
+    repoId: {
+        kind: string;
+        id: string;
+    };
+    ref: string;
+    preservePrefix: string;
+    message: string;
+    /**
+     * Caller's merge closure. The bridge invokes it locally inside the
+     * supervisor-driven merge round-trip; the closure receives the
+     * existing prefix entries the supervisor decoded from
+     * `substrate.merge.request`'s payload and returns the prospective
+     * tree the bridge encodes back into `substrate.merge.response`.
+     */
+    merge: (existing: ReadonlyMap<string, Uint8Array>) => Promise<Record<string, string | Uint8Array>>;
+}
+/**
+ * Bridge surface the child's substrate proxy reaches into. `submit`
+ * sends a `substrate.write.request` upstream and resolves once the
+ * supervisor's matching `substrate.write.response` lands. The
+ * `handleMergeRequest` and `handleWriteResponse` hooks are the
+ * receiver-side entry points the child's control loop invokes when
+ * the corresponding downstream frames arrive.
+ *
+ * `cancelAll` is the cleanup hook the control loop invokes on any
+ * exit path so a pending write does not leak an awaiter when the
+ * supervisor has torn the IPC down.
+ */
+export interface ChildSubstrateWriteBridge {
+    submit(req: SubstrateWriteRequest): Promise<{
+        commitSha: string;
+    }>;
+    handleMergeRequest(data: Extract<ControlPayload, {
+        type: "substrate.merge.request";
+    }>["data"]): void;
+    handleWriteResponse(data: Extract<ControlPayload, {
+        type: "substrate.write.response";
+    }>["data"]): void;
+    cancelAll(reason: string): void;
+    readonly pendingCount: number;
+}
+export interface CreateChildSubstrateWriteBridgeOpts {
+    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 substrate-write bridge. Pending writes
+ * live in a map keyed by `requestId`; the bridge resolves the awaiter
+ * when the supervisor's matching `substrate.write.response` lands.
+ *
+ * The supervisor may emit zero or more `substrate.merge.request`
+ * frames per pending write (the supervisor's merge callback may run
+ * once per attempt; the substrate retries on conflict). The bridge
+ * resolves each merge request synchronously through the pending
+ * entry's `merge` closure and emits `substrate.merge.response`. The
+ * pending entry stays alive until the terminal write response lands.
+ */
+export declare function createChildSubstrateWriteBridge(opts: CreateChildSubstrateWriteBridgeOpts): ChildSubstrateWriteBridge;

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

@@ -0,0 +1,188 @@
+// Child-side substrate-write bridge.
+//
+// The workflow-process child holds no write authority over the
+// workflow-run repo's ref. The hub linearizes writes at the ref tip;
+// a child that opened its own substrate would race the supervisor's
+// inbox / processing / consumed writes at the same ref. The supervisor
+// owns the write contract; the child proxies its
+// `writeTreePreservingPrefix` calls over the control IPC into the
+// supervisor's substrate.
+//
+// Lifecycle of one proxied write:
+//
+//   1. The child's proxy `RepoStore.writeTreePreservingPrefix` mints a
+//      `requestId`, registers a pending entry holding the caller's
+//      original merge closure plus resolve/reject hooks, and emits
+//      `substrate.write.request` upstream.
+//   2. The supervisor receives the request and invokes its own wrapped
+//      `writeTreePreservingPrefix` against the supervisor's repoStore.
+//      Inside the supervisor's merge callback, the supervisor sends
+//      `substrate.merge.request` back to the child carrying the
+//      existing prefix entries.
+//   3. The bridge resolves the existing entries through the pending
+//      entry's merge closure, encodes the resulting tree as
+//      base64-coded files, and replies with `substrate.merge.response`.
+//   4. The supervisor's merge callback returns the decoded files; the
+//      substrate commits the prospective tree under the per-repo lock.
+//   5. The supervisor sends `substrate.write.response` with the
+//      resulting `commitSha` (or the structured failure). The bridge
+//      resolves / rejects the pending awaiter; the child's substrate
+//      proxy returns the result to its caller.
+//
+// The bridge does NOT serialize the merge closure: the closure lives
+// in the child's address space, so the merge invocation always runs
+// here. The IPC carries the bytes the closure consumes and the bytes
+// the closure produces, both base64-encoded.
+import { getLogger } from "@intx/log";
+import { base64Decode, base64Encode } from "@intx/types";
+const logger = getLogger(["workflow-host", "child", "substrate-write-bridge"]);
+/**
+ * Construct the child-side substrate-write bridge. Pending writes
+ * live in a map keyed by `requestId`; the bridge resolves the awaiter
+ * when the supervisor's matching `substrate.write.response` lands.
+ *
+ * The supervisor may emit zero or more `substrate.merge.request`
+ * frames per pending write (the supervisor's merge callback may run
+ * once per attempt; the substrate retries on conflict). The bridge
+ * resolves each merge request synchronously through the pending
+ * entry's `merge` closure and emits `substrate.merge.response`. The
+ * pending entry stays alive until the terminal write response lands.
+ */
+export function createChildSubstrateWriteBridge(opts) {
+    const pending = new Map();
+    const allocate = opts.allocateRequestId ?? defaultRequestIdAllocator();
+    return {
+        get pendingCount() {
+            return pending.size;
+        },
+        async submit(req) {
+            const requestId = allocate();
+            const resultPromise = new Promise((resolve, reject) => {
+                pending.set(requestId, { req, resolve, reject });
+            });
+            try {
+                await opts.upstreamSender.send({
+                    type: "substrate.write.request",
+                    data: {
+                        requestId,
+                        repoId: { kind: req.repoId.kind, id: req.repoId.id },
+                        ref: req.ref,
+                        preservePrefix: req.preservePrefix,
+                        message: req.message,
+                    },
+                });
+            }
+            catch (cause) {
+                pending.delete(requestId);
+                const message = cause instanceof Error ? cause.message : String(cause);
+                throw new Error(`workflow-child substrate write: upstream send failed for requestId ${requestId}: ${message}`, { cause });
+            }
+            return resultPromise;
+        },
+        handleMergeRequest(data) {
+            const entry = pending.get(data.requestId);
+            if (entry === undefined) {
+                logger.warn `substrate.merge.request landed with no pending entry; requestId=${data.requestId} dropped`;
+                // Reply with a structured failure so the supervisor's merge
+                // callback can short-circuit rather than wedge waiting on a
+                // response that will never come.
+                void opts.upstreamSender
+                    .send({
+                    type: "substrate.merge.response",
+                    data: {
+                        requestId: data.requestId,
+                        result: {
+                            ok: false,
+                            reason: `workflow-child substrate write: no pending entry for requestId ${data.requestId}`,
+                        },
+                    },
+                })
+                    .catch((cause) => {
+                    const msg = cause instanceof Error ? cause.message : String(cause);
+                    logger.error `substrate.merge.response upstream send (no-pending) failed: ${msg}`;
+                });
+                return;
+            }
+            void (async () => {
+                try {
+                    const existing = decodeMergeRequest(data.existing);
+                    const merged = await entry.req.merge(existing);
+                    const files = encodeFiles(merged);
+                    await opts.upstreamSender.send({
+                        type: "substrate.merge.response",
+                        data: {
+                            requestId: data.requestId,
+                            result: { ok: true, files },
+                        },
+                    });
+                }
+                catch (cause) {
+                    const reason = cause instanceof Error ? cause.message : String(cause);
+                    try {
+                        await opts.upstreamSender.send({
+                            type: "substrate.merge.response",
+                            data: {
+                                requestId: data.requestId,
+                                result: { ok: false, reason },
+                            },
+                        });
+                    }
+                    catch (sendCause) {
+                        const msg = sendCause instanceof Error
+                            ? sendCause.message
+                            : String(sendCause);
+                        logger.error `substrate.merge.response upstream send (failure path) failed: ${msg}`;
+                    }
+                }
+            })();
+        },
+        handleWriteResponse(data) {
+            const entry = pending.get(data.requestId);
+            if (entry === undefined) {
+                logger.warn `substrate.write.response landed with no pending entry; requestId=${data.requestId} dropped`;
+                return;
+            }
+            pending.delete(data.requestId);
+            if (data.result.ok) {
+                entry.resolve({ commitSha: data.result.commitSha });
+                return;
+            }
+            entry.reject(new Error(`workflow-child substrate write (requestId=${data.requestId}) rejected by supervisor: ${data.result.reason}`));
+        },
+        cancelAll(reason) {
+            for (const [requestId, entry] of pending) {
+                entry.reject(new Error(`workflow-child substrate write (requestId=${requestId}) cancelled: ${reason}`));
+            }
+            pending.clear();
+        },
+    };
+}
+function decodeMergeRequest(existing) {
+    const out = new Map();
+    for (const entry of existing) {
+        out.set(entry.path, base64ToBytes(entry.contentBase64));
+    }
+    return out;
+}
+function encodeFiles(files) {
+    const out = [];
+    for (const [path, content] of Object.entries(files)) {
+        const bytes = typeof content === "string" ? new TextEncoder().encode(content) : content;
+        out.push({ path, contentBase64: bytesToBase64(bytes) });
+    }
+    return out;
+}
+function bytesToBase64(bytes) {
+    return base64Encode(bytes);
+}
+function base64ToBytes(value) {
+    return base64Decode(value);
+}
+function defaultRequestIdAllocator() {
+    let counter = 0;
+    return () => {
+        counter += 1;
+        const rand = Math.random().toString(36).slice(2, 10);
+        return `sw-${String(counter)}-${rand}`;
+    };
+}

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

@@ -0,0 +1,10 @@
+import type { MessageTransport } from "@intx/types/runtime";
+import type { ChildOutboundMailBridge } from "./outbound-mail-bridge.js";
+/**
+ * Construct a `MessageTransport` whose outbound side routes through the
+ * supervisor (via `bridge`) and whose inbound side is inert. `address`
+ * is the agent's mail address; the supervisor signs the outbound mail as
+ * this address through the host transport, so it must be the address the
+ * host registered the agent's `CryptoProvider` against.
+ */
+export declare function createSupervisorBackedTransport(bridge: ChildOutboundMailBridge, address: string): MessageTransport;

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

@@ -0,0 +1,113 @@
+// Supervisor-backed `MessageTransport` for a unified-host step agent
+// (OUTBOUND half of mailbox ownership, §3a).
+//
+// Under the unified host the supervisor is the sole mail owner: it holds
+// the durable inbox and the host transport against which the agent's
+// address is registered with its signing key. The step agent therefore
+// does NOT subscribe its own transport for inbound mail (the supervisor
+// delivers inputs via the step path) and does NOT hold a signing key to
+// send outbound mail. Its mail tools are backed by this transport:
+//
+//   - INBOUND is a no-op. `watch` returns a no-op unsubscribe and never
+//     fires; the supervisor delivers the agent's input as the step
+//     input, not through the agent's own mailbox. The IMAP read surface
+//     (`search`, `fetchFull`, `fetchHeaders`, ...) throws: the agent
+//     owns no mailbox in the unified host, so a read against one is a
+//     programming error, surfaced loudly rather than returning a
+//     silently-empty result that would hide the missing inbound surface.
+//   - OUTBOUND (`send` / `append`) routes through the supervisor over
+//     the control IPC via the outbound-mail bridge. The supervisor
+//     performs the actual signed send through the host transport, so the
+//     outbound mail carries the agent's signature with full parity to
+//     the in-process path. The agent never holds the key.
+/**
+ * Construct a `MessageTransport` whose outbound side routes through the
+ * supervisor (via `bridge`) and whose inbound side is inert. `address`
+ * is the agent's mail address; the supervisor signs the outbound mail as
+ * this address through the host transport, so it must be the address the
+ * host registered the agent's `CryptoProvider` against.
+ */
+export function createSupervisorBackedTransport(bridge, address) {
+    function inboundUnsupported(method) {
+        throw new Error(`supervisor-backed transport: ${method} is not supported for unified-host step agent ${address}; the supervisor owns the mailbox and delivers inbound mail as the step input`);
+    }
+    return {
+        async send(message, _signal) {
+            return bridge.submit(address, message);
+        },
+        async append(_mailbox, _message, _flags, _signal) {
+            // `append` writes into a mailbox the agent owns; in the unified
+            // host the agent owns none. The mail tools do not append (they
+            // `send`), so a reachable `append` is a programming error.
+            return inboundUnsupported("append");
+        },
+        async listMailboxes(_signal) {
+            return inboundUnsupported("listMailboxes");
+        },
+        async createMailbox(_name, _signal) {
+            return inboundUnsupported("createMailbox");
+        },
+        async deleteMailbox(_name, _signal) {
+            return inboundUnsupported("deleteMailbox");
+        },
+        async getMailboxStatus(_name, _signal) {
+            return inboundUnsupported("getMailboxStatus");
+        },
+        async search(_mailbox, _query, _signal) {
+            return inboundUnsupported("search");
+        },
+        async thread(_mailbox, _algorithm, _query, _signal) {
+            return inboundUnsupported("thread");
+        },
+        async fetchHeaders(_ref, _signal) {
+            return inboundUnsupported("fetchHeaders");
+        },
+        async fetchStructure(_ref, _signal) {
+            return inboundUnsupported("fetchStructure");
+        },
+        async fetchPart(_ref, _partPath, _signal) {
+            return inboundUnsupported("fetchPart");
+        },
+        async fetchFull(_ref, _signal) {
+            return inboundUnsupported("fetchFull");
+        },
+        async setFlags(_ref, _flags, _signal) {
+            return inboundUnsupported("setFlags");
+        },
+        async clearFlags(_ref, _flags, _signal) {
+            return inboundUnsupported("clearFlags");
+        },
+        async move(_ref, _toMailbox, _signal) {
+            return inboundUnsupported("move");
+        },
+        async copy(_ref, _toMailbox, _signal) {
+            return inboundUnsupported("copy");
+        },
+        async expunge(_mailbox, _signal) {
+            return inboundUnsupported("expunge");
+        },
+        watch(_mailbox, _callback) {
+            // Inbound delivery is a no-op: the supervisor delivers the agent's
+            // input as the step input, not through the agent's mailbox. The
+            // watch never fires; return a no-op unsubscribe so a mail tool that
+            // installs a watch (mail_wait) does not throw at install time but
+            // also never observes a spurious event.
+            return () => undefined;
+        },
+        async sync(_mailbox, _knownState, _signal) {
+            return inboundUnsupported("sync");
+        },
+        async createList(_address, _name, _signal) {
+            return inboundUnsupported("createList");
+        },
+        async listMembers(_address, _signal) {
+            return inboundUnsupported("listMembers");
+        },
+        async subscribe(_listAddress, _subscriberAddress, _signal) {
+            return inboundUnsupported("subscribe");
+        },
+        async unsubscribe(_listAddress, _subscriberAddress, _signal) {
+            return inboundUnsupported("unsubscribe");
+        },
+    };
+}

package/dist/child/warm-agent-cache.d.ts

@@ -0,0 +1,78 @@
+import type { Agent } from "@intx/agent";
+import type { InferenceEvent, InferenceSource } from "@intx/types/runtime";
+/**
+ * Mutable per-entry event sink the warm agent's stream forwarder reads
+ * before forwarding each event. The step-invoker swaps `current` to the
+ * active step's `onEvent` before every `agent.send`, so events from the
+ * agent's single lifetime stream reach whichever run is in flight. A
+ * `null` `current` drops events (no run is driving the agent), which is
+ * the correct behaviour in the gap between sends.
+ */
+export interface WarmEventSinkRef {
+    current: ((event: InferenceEvent) => void) | null;
+}
+/**
+ * Per-address warm-agent cache. Keyed by the step's stable identity (the
+ * single step's id), so a long-lived agent resolves to the same entry on
+ * every inbound message. The cache is single-writer from the run-loop's
+ * perspective: the step-invoker builds-or-reuses inside one step
+ * invocation, and the run-loop evicts at teardown.
+ */
+export interface WarmAgentCache {
+    /**
+     * Return the warm agent cached for `key`, or `null` when none is
+     * built yet (the lazy first-message path). The caller builds the
+     * agent and calls `store` on a miss.
+     */
+    acquire(key: string): Agent | null;
+    /**
+     * Cache a freshly-built warm agent under `key`. The `eventSinkRef` is
+     * the mutable sink the agent's stream forwarder reads; `eventForward`
+     * is the forwarder loop's settle promise. Throws if an entry already
+     * exists for `key` -- a double-build is a step-invoker bug, not a
+     * silent overwrite that would leak the prior agent's LSP subprocess.
+     */
+    store(key: string, agent: Agent, eventSinkRef: WarmEventSinkRef, eventForward: Promise<void>): void;
+    /**
+     * Point the warm agent's stream forwarder at the active step's event
+     * sink before its `agent.send`. Throws when no entry exists for
+     * `key` -- the step-invoker must `store` before it rewrites the sink.
+     */
+    setEventSink(key: string, onEvent: (event: InferenceEvent) => void): void;
+    /**
+     * Clear the active event sink for `key` after a step's `agent.send`
+     * settles, so a stray event between messages is dropped rather than
+     * delivered to a torn-down per-run channel. A missing entry is a
+     * no-op: the agent may already have been evicted.
+     */
+    clearEventSink(key: string): void;
+    /**
+     * Apply a rotated inference-source list to every retained warm agent in
+     * place, via `Agent.setSources`. A single-step warm cache holds 0 or 1
+     * entry, so this rotates the one built agent -- or is a no-op when none
+     * is built yet (the pre-first-build window). The swap mutates the
+     * agent's shared active-source object in place and takes effect on the
+     * reactor's next inference call; the single-threaded control loop means
+     * there is no torn read against a concurrent send. `setSources` validates
+     * the list and throws on an invalid source (or a closed agent, if a
+     * rotation races eviction), so a bad rotation surfaces rather than being
+     * swallowed.
+     */
+    applySources(sources: InferenceSource[], defaultSource: string): void;
+    /**
+     * Tear down every cached warm agent: run the wrapped `agent.close()`
+     * (disposing plugins and killing the LSP subprocess) and drain the
+     * stream forwarder. Idempotent -- a second call after the cache is
+     * empty is a no-op, so the run-loop can evict on both the shutdown
+     * frame and the exit-path `finally` without double-closing. Resolves
+     * once every agent is closed and every forwarder has drained, so no
+     * LSP subprocess outlives the call.
+     */
+    evictAll(reason: string): Promise<void>;
+}
+/**
+ * Construct an empty warm-agent cache. The run-loop builds one per
+ * spawn when the deployment is a warm candidate and threads it into the
+ * step-invoker; multi-step deployments construct none.
+ */
+export declare function createWarmAgentCache(): WarmAgentCache;

package/dist/child/warm-agent-cache.js

@@ -0,0 +1,112 @@
+// Warm-agent cache for the workflow-process child (design §3b).
+//
+// A long-lived single-step agent is built once -- tools materialized,
+// plugins instantiated, the LSP subprocess spawned -- and reused across
+// every inbound message. Re-materializing tools and re-spawning the LSP
+// per message is the instantiate-send-teardown cost the warm cache
+// removes; keeping the agent alive across messages is also what
+// preserves in-memory conversation continuity (durability across child
+// respawns lands in §3c, a later sub-step).
+//
+// Ownership and lifetime. The cache lives in the child's address space,
+// owned by the run-loop (`run-child.ts`), NOT the supervisor. The
+// step-invoker consults it on every step invocation: a cache hit reuses
+// the warm agent, a miss builds and stores one lazily. The cached agent
+// is torn down -- the wrapped `agent.close()` runs, disposing plugins
+// and killing the LSP subprocess -- only at the run-loop's eviction
+// points (child shutdown, deployment undeploy, recycle, post-drain
+// teardown), never between messages. On recycle the child process dies,
+// killing the LSP grandchild regardless; the respawned child starts with
+// an empty cache and re-warms lazily.
+//
+// Per-message event sink. The agent's `stream()` is consumed once, for
+// the agent's whole life, by a single forwarder owned by the entry. The
+// per-step `onEvent` sink the runtime threads in differs per message
+// (it carries the run id in its error-log path), so the forwarder routes
+// through a mutable reference the step-invoker rewrites before each
+// `agent.send`. The forwarder loop ends only when the agent closes at an
+// eviction point.
+//
+// Warm-keep is gated explicitly: the cache is constructed only when the
+// deploy projection marks the deployment a warm candidate (the
+// single-step launched agent). Multi-step deployments pass no cache and
+// keep instantiate-send-teardown per step. The decision is never a
+// silent default -- a multi-step agent is never warm-kept.
+import { getLogger } from "@intx/log";
+const logger = getLogger(["workflow-host", "child", "warm-agent-cache"]);
+/**
+ * Construct an empty warm-agent cache. The run-loop builds one per
+ * spawn when the deployment is a warm candidate and threads it into the
+ * step-invoker; multi-step deployments construct none.
+ */
+export function createWarmAgentCache() {
+    const entries = new Map();
+    function acquire(key) {
+        const entry = entries.get(key);
+        return entry === undefined ? null : entry.agent;
+    }
+    function store(key, agent, eventSinkRef, eventForward) {
+        if (entries.has(key)) {
+            throw new Error(`warm-agent cache: an entry already exists for ${key}; the step-invoker must reuse the cached agent rather than rebuild it`);
+        }
+        entries.set(key, { agent, eventSinkRef, eventForward });
+    }
+    function setEventSink(key, onEvent) {
+        const entry = entries.get(key);
+        if (entry === undefined) {
+            throw new Error(`warm-agent cache: setEventSink for ${key} with no cached entry; the step-invoker must store the warm agent before wiring its per-message event sink`);
+        }
+        entry.eventSinkRef.current = onEvent;
+    }
+    function clearEventSink(key) {
+        const entry = entries.get(key);
+        if (entry === undefined)
+            return;
+        entry.eventSinkRef.current = null;
+    }
+    function applySources(sources, defaultSource) {
+        for (const entry of entries.values()) {
+            entry.agent.setSources(sources, defaultSource);
+        }
+    }
+    async function evictAll(reason) {
+        if (entries.size === 0)
+            return;
+        const toEvict = [...entries.values()];
+        entries.clear();
+        for (const entry of toEvict) {
+            // Clear the sink first so any event emitted during the agent's
+            // shutdown window is dropped rather than delivered to a per-run
+            // channel the run-loop is tearing down.
+            entry.eventSinkRef.current = null;
+            try {
+                // The wrapped close (see `createToolBearingAgentFactory`) runs
+                // the agent's own close and then the plugin + tool-bundle
+                // disposers, killing the LSP subprocess. A close failure must
+                // surface, not be swallowed -- a leaked LSP subprocess is
+                // exactly the failure warm-keep risks -- so it propagates after
+                // we have drained what we can.
+                await entry.agent.close();
+            }
+            catch (cause) {
+                const message = cause instanceof Error ? cause.message : String(cause);
+                logger.error `warm-agent eviction (${reason}): agent.close failed: ${message}`;
+                throw cause instanceof Error ? cause : new Error(message);
+            }
+            finally {
+                // `agent.close()` terminates the stream iterator, so the
+                // forwarder loop has ended (or is about to). Await it so no
+                // forwarder outlives the eviction.
+                await entry.eventForward;
+            }
+        }
+    }
+    return {
+        acquire,
+        store,
+        setEventSink,
+        clearEventSink,
+        applySources,
+        evictAll,
+    };
+}