@automatalabs/acp-agents 1.2.6 → 1.3.0

package/dist/agent/errors.d.ts

@@ -0,0 +1,17 @@
+import { WorkflowError } from "@automatalabs/shared-types";
+import { type ErrorMapContext } from "../errors-map.js";
+import type { TypedSessionFailure } from "../typed-failures.js";
+import type { AcpAgentTurn, AcpAgentTurnError } from "./types.js";
+/** A deterministic caller error (bad option, misuse): SCRIPT_VALIDATION_ERROR, non-recoverable. */
+export declare function agentValidationError(message: string, label?: string): WorkflowError;
+/** Every method except `close()`/`cancel()`/getters after the agent closed, aborted, or its process died. */
+export declare function agentClosedError(label: string | undefined, backendId: string, detail?: string): WorkflowError;
+/** Map a thrown wire/lifecycle error onto the seam contract — unless `signal` aborted, in which
+ *  case the error is returned untouched so the caller can rethrow `signal.reason` itself. */
+export declare function mapAgentError(error: unknown, ctx: ErrorMapContext, signal?: AbortSignal): unknown;
+/** The `prompt()` rejection for a walled turn: `mapTypedSessionFailure` (codes/recoverable/details
+ *  unchanged) with the complete `AcpAgentTurn` attached as `error.turn`. */
+export declare function agentTurnError(failure: TypedSessionFailure, turn: AcpAgentTurn, ctx: ErrorMapContext): AcpAgentTurnError;
+/** Narrow a `prompt()` rejection to the typed-session-failure shape that carries the turn. */
+export declare function isAcpAgentTurnError(error: unknown): error is AcpAgentTurnError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/agent/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/agent/errors.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAsC,MAAM,4BAA4B,CAAC;AAC/F,OAAO,EAA0C,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAChG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAElE,mGAAmG;AACnG,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,aAAa,CAKnF;AAED,6GAA6G;AAC7G,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,CAM7G;AAED;6FAC6F;AAC7F,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAGjG;AAED;4EAC4E;AAC5E,wBAAgB,cAAc,CAC5B,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,YAAY,EAClB,GAAG,EAAE,eAAe,GACnB,iBAAiB,CAInB;AAED,8FAA8F;AAC9F,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAM9E"}

package/dist/agent/errors.js

@@ -0,0 +1,37 @@
+// AcpAgent error helpers: SDK misuse is uniformly a WorkflowError(SCRIPT_VALIDATION_ERROR); wire
+// failures go through the same `mapThrownError` ladder the runner uses; an abort is never mapped
+// (the affected promise rejects with `signal.reason` untouched); a typed session failure rejects
+// with the runner's mapped error carrying the complete turn.
+import { WorkflowError, WorkflowErrorCode, isWorkflowError } from "@automatalabs/shared-types";
+import { mapThrownError, mapTypedSessionFailure } from "../errors-map.js";
+/** A deterministic caller error (bad option, misuse): SCRIPT_VALIDATION_ERROR, non-recoverable. */
+export function agentValidationError(message, label) {
+    return new WorkflowError(message, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, {
+        recoverable: false,
+        agentLabel: label,
+    });
+}
+/** Every method except `close()`/`cancel()`/getters after the agent closed, aborted, or its process died. */
+export function agentClosedError(label, backendId, detail) {
+    return new WorkflowError(`AcpAgent (${backendId}) is closed${detail ? `: ${detail}` : ""}`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: label });
+}
+/** Map a thrown wire/lifecycle error onto the seam contract — unless `signal` aborted, in which
+ *  case the error is returned untouched so the caller can rethrow `signal.reason` itself. */
+export function mapAgentError(error, ctx, signal) {
+    if (signal?.aborted)
+        return error;
+    return mapThrownError(error, ctx);
+}
+/** The `prompt()` rejection for a walled turn: `mapTypedSessionFailure` (codes/recoverable/details
+ *  unchanged) with the complete `AcpAgentTurn` attached as `error.turn`. */
+export function agentTurnError(failure, turn, ctx) {
+    const mapped = mapTypedSessionFailure(failure, ctx);
+    Object.defineProperty(mapped, "turn", { value: turn, enumerable: false, writable: false, configurable: false });
+    return mapped;
+}
+/** Narrow a `prompt()` rejection to the typed-session-failure shape that carries the turn. */
+export function isAcpAgentTurnError(error) {
+    return (isWorkflowError(error) &&
+        typeof error.turn === "object" &&
+        error.turn !== null);
+}

package/dist/agent/events.d.ts

@@ -0,0 +1,26 @@
+import type { AcpEventSink } from "../events.js";
+import type { AcpAgentEventListener, AcpAgentEventMap, AcpAgentEventName } from "./types.js";
+/** An internal listener that runs BEFORE public listeners for every dispatched event. */
+export type AgentEventTap = <K extends AcpAgentEventName>(name: K, event: AcpAgentEventMap[K]) => void;
+export declare class AgentEventBus {
+    #private;
+    /** Passed to `PooledConnection.create({ onEvent })`. */
+    readonly sink: AcpEventSink;
+    constructor();
+    on<K extends AcpAgentEventName>(name: K, listener: AcpAgentEventListener<K>): () => void;
+    once<K extends AcpAgentEventName>(name: K, listener: AcpAgentEventListener<K>): () => void;
+    off<K extends AcpAgentEventName>(name: K, listener: AcpAgentEventListener<K>): void;
+    /** Internal observer; runs before public listeners, exception-isolated. Returns the untap thunk. */
+    tap(listener: AgentEventTap): () => void;
+    /** Buffer events for ids not yet known (a session is being opened/forked/reattached). */
+    beginAcquisition(): void;
+    /** Adopt `sessionId`: mark it known, replay the buffered entries for it (taps first, then public
+     *  listeners) with the acquisition still flagged pending so the hand-off drops stay armed, then
+     *  drop everything else. */
+    endAcquisition(sessionId: string): void;
+    /** Drop the buffer (the open failed). */
+    abortAcquisition(): void;
+    /** After teardown: listeners cleared; `on`/`once` become no-ops returning `() => {}`. */
+    close(): void;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/agent/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/agent/events.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAmB,YAAY,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE7F,yFAAyF;AACzF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,SAAS,iBAAiB,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;AAoBvG,qBAAa,aAAa;;IACxB,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;;IAe5B,EAAE,CAAC,CAAC,SAAS,iBAAiB,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAIxF,IAAI,CAAC,CAAC,SAAS,iBAAiB,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAI1F,GAAG,CAAC,CAAC,SAAS,iBAAiB,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,IAAI;IAKnF,oGAAoG;IACpG,GAAG,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,IAAI;IAOxC,yFAAyF;IACzF,gBAAgB,IAAI,IAAI;IAIxB;;gCAE4B;IAC5B,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAWvC,yCAAyC;IACzC,gBAAgB,IAAI,IAAI;IAMxB,yFAAyF;IACzF,KAAK,IAAI,IAAI;CA2Fd"}

package/dist/agent/events.js

@@ -0,0 +1,165 @@
+function sessionIdOf(event) {
+    const sid = event?.sessionId;
+    return typeof sid === "string" ? sid : undefined;
+}
+export class AgentEventBus {
+    /** Passed to `PooledConnection.create({ onEvent })`. */
+    sink;
+    #entries = [];
+    #taps = new Set();
+    #known = new Set();
+    #acquiring = false;
+    #buffer = [];
+    #bufferedOpenIds = new Set();
+    #sawSessionOpen = false;
+    #sticky;
+    #closed = false;
+    constructor() {
+        this.sink = (name, event) => this.#route(name, event);
+    }
+    on(name, listener) {
+        return this.#subscribe(name, listener, false);
+    }
+    once(name, listener) {
+        return this.#subscribe(name, listener, true);
+    }
+    off(name, listener) {
+        const index = this.#entries.findIndex((entry) => entry.name === name && entry.listener === listener);
+        if (index >= 0)
+            this.#entries.splice(index, 1);
+    }
+    /** Internal observer; runs before public listeners, exception-isolated. Returns the untap thunk. */
+    tap(listener) {
+        this.#taps.add(listener);
+        return () => {
+            this.#taps.delete(listener);
+        };
+    }
+    /** Buffer events for ids not yet known (a session is being opened/forked/reattached). */
+    beginAcquisition() {
+        this.#acquiring = true;
+    }
+    /** Adopt `sessionId`: mark it known, replay the buffered entries for it (taps first, then public
+     *  listeners) with the acquisition still flagged pending so the hand-off drops stay armed, then
+     *  drop everything else. */
+    endAcquisition(sessionId) {
+        this.#known.add(sessionId);
+        const buffered = this.#buffer;
+        this.#buffer = [];
+        this.#bufferedOpenIds.clear();
+        for (const { name, event } of buffered) {
+            if (sessionIdOf(event) === sessionId)
+                this.#route(name, event);
+        }
+        this.#acquiring = false;
+    }
+    /** Drop the buffer (the open failed). */
+    abortAcquisition() {
+        this.#acquiring = false;
+        this.#buffer = [];
+        this.#bufferedOpenIds.clear();
+    }
+    /** After teardown: listeners cleared; `on`/`once` become no-ops returning `() => {}`. */
+    close() {
+        this.#closed = true;
+        this.#entries.length = 0;
+        this.#taps.clear();
+    }
+    #subscribe(name, listener, once) {
+        if (this.#closed)
+            return () => { };
+        const entry = {
+            name,
+            listener: listener,
+            once,
+            sawSessionOpen: false,
+        };
+        this.#entries.push(entry);
+        const off = () => {
+            const index = this.#entries.indexOf(entry);
+            if (index >= 0)
+                this.#entries.splice(index, 1);
+        };
+        if (name === "session_open" && this.#sticky) {
+            // Late subscriber: deliver the retained open once, on the next tick, only if still
+            // subscribed and not already served live in the meantime.
+            const sticky = this.#sticky;
+            queueMicrotask(() => {
+                if (entry.sawSessionOpen || !this.#entries.includes(entry))
+                    return;
+                this.#deliver(entry, "session_open", sticky);
+            });
+        }
+        return off;
+    }
+    #route(name, event) {
+        if (this.#closed)
+            return;
+        const sid = sessionIdOf(event);
+        // Only `backend_error` carries no session id; the connection is dedicated, so it is ours.
+        if (sid === undefined) {
+            this.#dispatch(name, event);
+            return;
+        }
+        if (this.#known.has(sid)) {
+            // The id-only fork registers the same id twice (fork, then reattach) — one open per agent.
+            if (name === "session_open" && this.#sawSessionOpen)
+                return;
+            // The hand-off release unregisters the id while the reattach is pending — not our close.
+            if (name === "session_close" && this.#acquiring)
+                return;
+            this.#dispatch(name, event);
+            return;
+        }
+        if (!this.#acquiring)
+            return;
+        // Unknown id while acquiring: never buffer a close (it is the hand-off release or a
+        // stranger's), buffer at most one open per id (the reattach registers before its wire call),
+        // buffer everything else for adoption.
+        if (name === "session_close")
+            return;
+        if (name === "session_open") {
+            if (this.#bufferedOpenIds.has(sid))
+                return;
+            this.#bufferedOpenIds.add(sid);
+        }
+        this.#buffer.push({ name, event });
+    }
+    #dispatch(name, event) {
+        if (name === "session_open") {
+            this.#sawSessionOpen = true;
+            this.#sticky ??= event;
+        }
+        for (const tap of [...this.#taps]) {
+            try {
+                tap(name, event);
+            }
+            catch {
+                // Taps are internal observers; a throwing one never breaks delivery.
+            }
+        }
+        // Snapshot so a listener that (un)subscribes during dispatch cannot perturb this emit.
+        for (const entry of [...this.#entries]) {
+            if (entry.name !== name)
+                continue;
+            this.#deliver(entry, name, event);
+        }
+    }
+    #deliver(entry, name, event) {
+        if (!this.#entries.includes(entry))
+            return;
+        if (entry.once) {
+            const index = this.#entries.indexOf(entry);
+            if (index >= 0)
+                this.#entries.splice(index, 1);
+        }
+        if (name === "session_open")
+            entry.sawSessionOpen = true;
+        try {
+            entry.listener(event);
+        }
+        catch {
+            // Listeners are observers — never let one break the turn or sibling listeners.
+        }
+    }
+}

package/dist/agent/fork.d.ts

@@ -0,0 +1,27 @@
+import type { AcpSessionOptions, PooledConnection, SessionHandle } from "../acp-client.js";
+import type { Backend } from "../backend.js";
+import { type ForkSessionTraitRow } from "../protocol-coverage.js";
+import type { BackendRegistry } from "../registry.js";
+/** A registered custom backend uses its declared `fork` trait (or the live default); a built-in
+ *  uses its `FORK_SESSION_TRAITS` row. A registry lookup, never an identity branch: a custom entry
+ *  named like a built-in is a different program and never inherits the built-in's row. */
+export declare function forkTraitFor(backend: Backend, registry: BackendRegistry): ForkSessionTraitRow;
+export interface AcquiredFork {
+    /** The LIVE session: the fork handle itself (`live`), or the reattached handle (`id-only`). */
+    readonly handle: SessionHandle;
+    /** How the live handle was obtained. `load` means the agent replayed the transcript. */
+    readonly method: "fork" | "resume" | "load";
+}
+/**
+ * Fork `sourceSessionId` on `connection` (a dedicated process; the source's own process is not
+ * involved on the wire) and hand back the live handle per `trait`:
+ *   - `live`: the fork response IS the session.
+ *   - `id-only`: the response names a persisted copy that is not live; release the fork handle
+ *     with `keepOpen` (unregister only — no `session/close`, so the reattach's `register()` never
+ *     replaces a live state and the slot count stays at one), then reattach it (resume preferred,
+ *     load fallback). The catalog/modes come from the reattach response; the bare fork response is
+ *     never read for them.
+ * `prepare` is re-evaluated for the reattach so it sees the same options the fork carried.
+ */
+export declare function acquireForkedSession(connection: PooledConnection, sourceSessionId: string, opts: AcpSessionOptions, trait: ForkSessionTraitRow): Promise<AcquiredFork>;
+//# sourceMappingURL=fork.d.ts.map

package/dist/agent/fork.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fork.d.ts","sourceRoot":"","sources":["../../src/agent/fork.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC3F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAoB,KAAK,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACrF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD;;0FAE0F;AAC1F,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,GAAG,mBAAmB,CAG7F;AAED,MAAM,WAAW,YAAY;IAC3B,+FAA+F;IAC/F,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;CAC7C;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,gBAAgB,EAC5B,eAAe,EAAE,MAAM,EACvB,IAAI,EAAE,iBAAiB,EACvB,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,YAAY,CAAC,CAOvB"}

package/dist/agent/fork.js

@@ -0,0 +1,28 @@
+import { forkSessionTrait } from "../protocol-coverage.js";
+/** A registered custom backend uses its declared `fork` trait (or the live default); a built-in
+ *  uses its `FORK_SESSION_TRAITS` row. A registry lookup, never an identity branch: a custom entry
+ *  named like a built-in is a different program and never inherits the built-in's row. */
+export function forkTraitFor(backend, registry) {
+    const custom = registry.get(backend.id);
+    return custom ? forkSessionTrait(backend.id, custom.fork ?? { disposition: "live" }) : forkSessionTrait(backend.id);
+}
+/**
+ * Fork `sourceSessionId` on `connection` (a dedicated process; the source's own process is not
+ * involved on the wire) and hand back the live handle per `trait`:
+ *   - `live`: the fork response IS the session.
+ *   - `id-only`: the response names a persisted copy that is not live; release the fork handle
+ *     with `keepOpen` (unregister only — no `session/close`, so the reattach's `register()` never
+ *     replaces a live state and the slot count stays at one), then reattach it (resume preferred,
+ *     load fallback). The catalog/modes come from the reattach response; the bare fork response is
+ *     never read for them.
+ * `prepare` is re-evaluated for the reattach so it sees the same options the fork carried.
+ */
+export async function acquireForkedSession(connection, sourceSessionId, opts, trait) {
+    const forkHandle = await connection.forkSession(sourceSessionId, opts);
+    if (trait.disposition !== "id-only")
+        return { handle: forkHandle, method: "fork" };
+    const forkedId = forkHandle.sessionId;
+    await forkHandle.release({ keepOpen: true });
+    const { handle, method } = await connection.openPreparedReattachedSession(forkedId, () => opts);
+    return { handle, method };
+}

package/dist/agent/probe.d.ts

@@ -0,0 +1,14 @@
+import { type ValidateProbeRunner } from "../config-catalog.js";
+import { type CustomBackendConfig } from "../registry.js";
+import type { AcpAgentCatalog, AcpAgentProbeOptions } from "./types.js";
+/** A `ValidateProbeRunner` over a dedicated connection per probe: spawn, initialize, one no-prompt
+ *  session/new (+ model selection for exact specs), read the catalog, release, dispose. No
+ *  `listBackends`/`defaultBackendId`/`dispose`: `probeHarnessConfig` derives the default targets
+ *  from the registry itself and never owns a caller-supplied runner. */
+export declare function createAgentProbeRunner(backends: Record<string, CustomBackendConfig> | undefined): ValidateProbeRunner;
+/** The catalog behind `AcpAgent.probe` (see the file header). Per-target failures never throw
+ *  (`probed: false` with a redacted `error`); a bad `modelFilter`, `probeTimeoutMs`, or
+ *  `probeConcurrency` throws a TypeError and a malformed registry a SCRIPT_VALIDATION_ERROR — all
+ *  before any process spawns. */
+export declare function probeCatalog(options?: AcpAgentProbeOptions): Promise<AcpAgentCatalog>;
+//# sourceMappingURL=probe.d.ts.map

package/dist/agent/probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.d.ts","sourceRoot":"","sources":["../../src/agent/probe.ts"],"names":[],"mappings":"AAMA,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAA2B,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAInF,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAExE;;;wEAGwE;AACxE,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,GAAG,SAAS,GAAG,mBAAmB,CAuCrH;AAED;;;iCAGiC;AACjC,wBAAsB,YAAY,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,eAAe,CAAC,CA8B/F"}

package/dist/agent/probe.js

@@ -0,0 +1,87 @@
+import { PooledConnection, isChildCleanupError } from "../acp-client.js";
+import { buildHarnessModelsView, buildModelFilter, probeHarnessConfig, } from "../config-catalog.js";
+import { mapThrownError } from "../errors-map.js";
+import { registryWithRunBackends } from "../registry.js";
+import { resolveModelRoute } from "../routing.js";
+import { releaseOnExit, retainOnExit } from "./process-registry.js";
+import { resolveAgentRegistry } from "./routing.js";
+/** A `ValidateProbeRunner` over a dedicated connection per probe: spawn, initialize, one no-prompt
+ *  session/new (+ model selection for exact specs), read the catalog, release, dispose. No
+ *  `listBackends`/`defaultBackendId`/`dispose`: `probeHarnessConfig` derives the default targets
+ *  from the registry itself and never owns a caller-supplied runner. */
+export function createAgentProbeRunner(backends) {
+    return {
+        async probeConfigOptions(spec, opts = {}) {
+            opts.signal?.throwIfAborted();
+            const registry = registryWithRunBackends(resolveAgentRegistry(backends), opts.backends);
+            const route = resolveModelRoute(spec, registry);
+            const cwd = opts.cwd ?? process.cwd();
+            const connection = PooledConnection.create(route.backend, { onDead: () => undefined });
+            retainOnExit(connection);
+            // Unsticks a hung initialize/session-new: the raced wire call rejects with the death error.
+            const onAbort = () => {
+                void connection.dispose();
+            };
+            opts.signal?.addEventListener("abort", onAbort, { once: true });
+            let handle;
+            try {
+                handle = await connection.openSession({ cwd, schema: undefined, policy: {} });
+                opts.signal?.throwIfAborted();
+                if (opts.selectModel && route.modelSpec !== undefined)
+                    await handle.selectModel(route.modelSpec);
+                return {
+                    backendId: route.backend.id,
+                    ...(route.backend.defaultModeId === undefined ? {} : { defaultModeId: route.backend.defaultModeId }),
+                    options: handle.advertisedConfigOptions,
+                    modes: handle.modes ?? null,
+                };
+            }
+            finally {
+                opts.signal?.removeEventListener("abort", onAbort);
+                try {
+                    await handle?.release();
+                }
+                catch (error) {
+                    if (isChildCleanupError(error)) {
+                        throw mapThrownError(error, { backendId: route.backend.id, backend: route.backend });
+                    }
+                }
+                await connection.dispose().catch(() => undefined);
+                releaseOnExit(connection);
+            }
+        },
+    };
+}
+/** The catalog behind `AcpAgent.probe` (see the file header). Per-target failures never throw
+ *  (`probed: false` with a redacted `error`); a bad `modelFilter`, `probeTimeoutMs`, or
+ *  `probeConcurrency` throws a TypeError and a malformed registry a SCRIPT_VALIDATION_ERROR — all
+ *  before any process spawns. */
+export async function probeCatalog(options = {}) {
+    // Validation only: a bad regex must surface BEFORE any spawn (the MCP handler does the same).
+    if (options.modelFilter !== undefined)
+        buildModelFilter(options.modelFilter);
+    // The SDK surfaces a malformed registry as a WorkflowError; probeHarnessConfig re-reads it.
+    resolveAgentRegistry(options.backends);
+    const modelSpecs = [...(options.model === undefined ? [] : [options.model]), ...(options.models ?? [])];
+    const probeRunner = createAgentProbeRunner(options.backends);
+    const common = {
+        backends: options.backends,
+        cwd: options.cwd,
+        probeTimeoutMs: options.probeTimeoutMs,
+        probeConcurrency: options.probeConcurrency,
+        signal: options.signal,
+        probeRunner,
+    };
+    let report = await probeHarnessConfig({ harnesses: options.harnesses, modelSpecs, ...common });
+    // Mirror the MCP `action:"config"` fallback: when an exact model probe fails, still return the
+    // bare harness catalog next to the failure so the caller can pick a valid id.
+    const missingCatalogBackends = [...new Set(report.harnessOptions
+            .filter((harness) => !harness.probed && harness.model !== undefined)
+            .map((harness) => harness.backendId)
+            .filter((backendId) => !report.harnessOptions.some((harness) => harness.probed && harness.backendId === backendId && harness.model === undefined)))];
+    if (missingCatalogBackends.length > 0) {
+        const catalogs = await probeHarnessConfig({ harnesses: missingCatalogBackends, ...common });
+        report = { ok: false, exitCode: 1, harnessOptions: [...report.harnessOptions, ...catalogs.harnessOptions] };
+    }
+    return { ...report, models: buildHarnessModelsView(report, options.modelFilter) };
+}

package/dist/agent/process-registry.d.ts

@@ -0,0 +1,9 @@
+import type { PooledConnection } from "../acp-client.js";
+/** Register a connection for the exit hook; call right after `PooledConnection.create`. */
+export declare function retainOnExit(connection: PooledConnection): void;
+/** Forget a connection; call in the `finally` of every teardown path. Removes the listener with
+ *  the last connection so the process never accumulates dead hooks. */
+export declare function releaseOnExit(connection: PooledConnection): void;
+/** Test seam: how many connections the hook currently guards. */
+export declare function liveConnectionCount(): number;
+//# sourceMappingURL=process-registry.d.ts.map

package/dist/agent/process-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-registry.d.ts","sourceRoot":"","sources":["../../src/agent/process-registry.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAUzD,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAM/D;AAED;uEACuE;AACvE,wBAAgB,aAAa,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAMhE;AAED,iEAAiE;AACjE,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C"}

package/dist/agent/process-registry.js

@@ -0,0 +1,28 @@
+const live = new Set();
+let installed = false;
+/** `killNow()` is synchronous and idempotent — the only thing an `exit` handler may call. */
+const onExit = () => {
+    for (const connection of live)
+        connection.killNow();
+};
+/** Register a connection for the exit hook; call right after `PooledConnection.create`. */
+export function retainOnExit(connection) {
+    live.add(connection);
+    if (!installed) {
+        installed = true;
+        process.once("exit", onExit);
+    }
+}
+/** Forget a connection; call in the `finally` of every teardown path. Removes the listener with
+ *  the last connection so the process never accumulates dead hooks. */
+export function releaseOnExit(connection) {
+    live.delete(connection);
+    if (installed && live.size === 0) {
+        installed = false;
+        process.removeListener("exit", onExit);
+    }
+}
+/** Test seam: how many connections the hook currently guards. */
+export function liveConnectionCount() {
+    return live.size;
+}

package/dist/agent/queue.d.ts

@@ -0,0 +1,19 @@
+export declare class SerialQueue {
+    #private;
+    /** Queued + running. */
+    get depth(): number;
+    /** Whether an op is executing right now. */
+    get running(): boolean;
+    /** Resolves once the currently running op (if any) has settled and nothing else is queued. */
+    whenIdle(): Promise<void>;
+    /**
+     * Append `op`; it starts strictly after every earlier entry settled. A `signal` that is already
+     * aborted rejects with `signal.reason` without calling `op`; an abort while the entry is still
+     * queued removes it and rejects it (the listener is dropped the moment the entry starts — an
+     * in-flight abort is the op's own concern).
+     */
+    run<T>(op: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+    /** Reject every NOT-YET-STARTED entry with `reason`; the running op is untouched. */
+    drain(reason: unknown): void;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/agent/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/agent/queue.ts"],"names":[],"mappings":"AAaA,qBAAa,WAAW;;IAMtB,wBAAwB;IACxB,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,4CAA4C;IAC5C,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,8FAA8F;IAC9F,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAIzB;;;;;OAKG;IACH,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;IA0B9D,qFAAqF;IACrF,KAAK,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;CAiC7B"}

package/dist/agent/queue.js

@@ -0,0 +1,90 @@
+// The per-agent FIFO. `prompt`, `fork`, `setMode`, `setConfigOptions`, `close` and the implicit
+// open all run through one SerialQueue so no two of them ever overlap (a second concurrent
+// `SessionHandle.prompt` would clobber the handle's active turn; pi rejects a fork while the
+// source has a turn in flight; Claude would copy a partial transcript). Pure: no ACP imports.
+export class SerialQueue {
+    #entries = [];
+    #running = false;
+    #idle = Promise.resolve();
+    #resolveIdle;
+    /** Queued + running. */
+    get depth() {
+        return this.#entries.length + (this.#running ? 1 : 0);
+    }
+    /** Whether an op is executing right now. */
+    get running() {
+        return this.#running;
+    }
+    /** Resolves once the currently running op (if any) has settled and nothing else is queued. */
+    whenIdle() {
+        return this.#idle;
+    }
+    /**
+     * Append `op`; it starts strictly after every earlier entry settled. A `signal` that is already
+     * aborted rejects with `signal.reason` without calling `op`; an abort while the entry is still
+     * queued removes it and rejects it (the listener is dropped the moment the entry starts — an
+     * in-flight abort is the op's own concern).
+     */
+    run(op, signal) {
+        return new Promise((resolve, reject) => {
+            if (signal?.aborted) {
+                reject(signal.reason);
+                return;
+            }
+            const entry = {
+                op,
+                signal,
+                resolve: resolve,
+                reject,
+            };
+            if (signal) {
+                const onAbort = () => {
+                    const index = this.#entries.indexOf(entry);
+                    if (index >= 0)
+                        this.#entries.splice(index, 1);
+                    reject(signal.reason);
+                };
+                signal.addEventListener("abort", onAbort, { once: true });
+                entry.removeAbort = () => signal.removeEventListener("abort", onAbort);
+            }
+            this.#entries.push(entry);
+            void this.#pump();
+        });
+    }
+    /** Reject every NOT-YET-STARTED entry with `reason`; the running op is untouched. */
+    drain(reason) {
+        for (const entry of this.#entries.splice(0)) {
+            entry.removeAbort?.();
+            entry.reject(reason);
+        }
+    }
+    async #pump() {
+        if (this.#running)
+            return;
+        this.#running = true;
+        this.#idle = new Promise((resolve) => {
+            this.#resolveIdle = resolve;
+        });
+        try {
+            while (this.#entries.length > 0) {
+                const entry = this.#entries.shift();
+                entry.removeAbort?.();
+                if (entry.signal?.aborted) {
+                    entry.reject(entry.signal.reason);
+                    continue;
+                }
+                try {
+                    entry.resolve(await entry.op());
+                }
+                catch (error) {
+                    entry.reject(error);
+                }
+            }
+        }
+        finally {
+            this.#running = false;
+            this.#resolveIdle?.();
+            this.#resolveIdle = undefined;
+        }
+    }
+}

package/dist/agent/routing.d.ts

@@ -0,0 +1,27 @@
+import type { AgentSessionRef } from "@automatalabs/shared-types";
+import type { Backend } from "../backend.js";
+import { type BackendRegistry, type CustomBackendConfig } from "../registry.js";
+import { type ModelRoute } from "../routing.js";
+import type { AcpAgentOptions } from "./types.js";
+/** The custom-backend registry for an agent: `backends` merged over `AGENTPRISM_BACKENDS`. A
+ *  malformed registry is a caller error (SCRIPT_VALIDATION_ERROR), mirroring the runner's wrap. */
+export declare function resolveAgentRegistry(backends: Record<string, CustomBackendConfig> | undefined, label?: string): BackendRegistry;
+/** The runner's routing grammar applied to `new AcpAgent({ model })`. */
+export declare function resolveAgentRoute(options: Pick<AcpAgentOptions, "model">, registry: BackendRegistry): ModelRoute;
+/**
+ * Route a cold reopen from a session ref. `ref.backendId` must name a registered custom backend
+ * (wins, like `resolveModelRoute`) or a built-in — NEVER the default backend; the ref's `poolKey`
+ * must match the currently resolved `poolKey ?? id` (the runner's silent `backend-mismatch` skip,
+ * made loud); an optional `model` must stay on the ref's backend: `<ref.backendId>/<inner>` strips
+ * the prefix, a spec routing to another known backend is rejected, and an unrouted spec goes
+ * VERBATIM to the ref's backend (the same unrouted rule as the runner, applied to this backend).
+ */
+export declare function resolveRefRoute(ref: AgentSessionRef, model: string | undefined, registry: BackendRegistry, label?: string): ModelRoute;
+/** A fresh `Backend` instance with the same identity as `backend` (a registered name wins, as in
+ *  routing; else the built-in of that id). A fork child must own its own instance — pooling identity
+ *  is `poolKey ?? id`, never the object. */
+export declare function freshBackendFor(backend: Backend, registry: BackendRegistry): Backend;
+/** Stricter than the runner's interactive check and equal to the Claude adapter's own: absolute,
+ *  existing, and a directory — so the failure happens before a process spawns. */
+export declare function validateAgentCwd(cwd: unknown, label: string | undefined, method: string): asserts cwd is string;
+//# sourceMappingURL=routing.d.ts.map

package/dist/agent/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/agent/routing.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG7C,OAAO,EAA0B,KAAK,eAAe,EAAE,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACxG,OAAO,EAAqC,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAEnF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;mGACmG;AACnG,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,GAAG,SAAS,EACzD,KAAK,CAAC,EAAE,MAAM,GACb,eAAe,CAMjB;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,eAAe,GAAG,UAAU,CAEhH;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,eAAe,EACpB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,QAAQ,EAAE,eAAe,EACzB,KAAK,CAAC,EAAE,MAAM,GACb,UAAU,CA4BZ;AAED;;4CAE4C;AAC5C,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,CAEpF;AAQD;kFACkF;AAClF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,MAAM,CAiB/G"}