@automatalabs/acp-agents 0.1.0

package/dist/backends/claude.js

@@ -0,0 +1,48 @@
+// ClaudeBackend — drives @agentclientprotocol/claude-agent-acp@0.53.0 (over the Claude
+// Agent SDK). Structured output rides the vendor `_meta.claudeCode` channel at session/new:
+//   options.outputFormat = { type:"json_schema", schema }   // the SDK's native constraint
+//   emitRawSDKMessages = true                                // MANDATORY to READ the result
+// The parsed object lands on SDKResultSuccess.structured_output, observable ONLY off the raw
+// `_claude/sdkMessage` extension notification (the runner's ACP client captures it).
+import { createRequire } from "node:module";
+import { splitArgs } from "../backend.js";
+import { toJsonSchema } from "../schema-strict.js";
+const require = createRequire(import.meta.url);
+export class ClaudeBackend {
+    id = "claude";
+    spawnConfig() {
+        const env = process.env;
+        const override = env.AGENTPRISM_CLAUDE_ACP_CMD;
+        if (override) {
+            return { command: override, args: splitArgs(env.AGENTPRISM_CLAUDE_ACP_ARGS), env };
+        }
+        // Prefer the installed package's bin script run under the current node; fall back to npx
+        // when it is not resolvable from this install.
+        try {
+            const bin = require.resolve("@agentclientprotocol/claude-agent-acp/dist/index.js");
+            return { command: process.execPath, args: [bin], env };
+        }
+        catch {
+            return { command: "npx", args: ["-y", "@agentclientprotocol/claude-agent-acp"], env };
+        }
+    }
+    sessionMeta(schema) {
+        if (!schema)
+            return undefined;
+        return {
+            claudeCode: {
+                options: {
+                    outputFormat: { type: "json_schema", schema: toJsonSchema(schema) },
+                },
+                emitRawSDKMessages: true,
+            },
+        };
+    }
+    promptMeta() {
+        // Claude's schema is session-scoped (read at session/new); nothing on the turn.
+        return undefined;
+    }
+    nativeStructured(source) {
+        return source.rawStructuredOutput();
+    }
+}

package/dist/backends/codex.d.ts

@@ -0,0 +1,10 @@
+import type { TSchema } from "typebox";
+import type { Backend, SpawnConfig, StructuredSource } from "../backend.js";
+export declare class CodexBackend implements Backend {
+    readonly id: "codex";
+    spawnConfig(): SpawnConfig;
+    sessionMeta(): Record<string, unknown> | undefined;
+    promptMeta(schema: TSchema | undefined): Record<string, unknown> | undefined;
+    nativeStructured(source: StructuredSource): unknown;
+}
+//# sourceMappingURL=codex.d.ts.map

package/dist/backends/codex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/backends/codex.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAO5E,qBAAa,YAAa,YAAW,OAAO;IAC1C,QAAQ,CAAC,EAAE,EAAG,OAAO,CAAU;IAE/B,WAAW,IAAI,WAAW;IAe1B,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAKlD,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAK5E,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO;CAoBpD"}

package/dist/backends/codex.js

@@ -0,0 +1,62 @@
+// CodexBackend — drives the installed npm dep @automatalabs/codex-acp, a published fork of
+// @agentclientprotocol/codex-acp that bakes in the outputSchema patch. The patch forwards
+// request._meta["agentprism/outputSchema"] into the Codex App Server's turn/start.outputSchema,
+// which the shipped @openai/codex binary honors end-to-end as an OpenAI Responses-API STRICT
+// constraint on the final assistant message. So the schema rides per-PROMPT `_meta` (not
+// session/new), normalized to OpenAI strict rules first. Output needs no special channel: the
+// constrained final message flows back over the normal agent-message stream, so the backend
+// reads the final text and JSON.parses it.
+import { createRequire } from "node:module";
+import { META_KEYS } from "@automatalabs/shared-types";
+import { splitArgs } from "../backend.js";
+import { toStrictJsonSchema } from "../schema-strict.js";
+import { findJsonBlock } from "../structured-output.js";
+const require = createRequire(import.meta.url);
+export class CodexBackend {
+    id = "codex";
+    spawnConfig() {
+        const env = process.env;
+        const override = env.AGENTPRISM_CODEX_ACP_CMD;
+        if (override) {
+            return { command: override, args: splitArgs(env.AGENTPRISM_CODEX_ACP_ARGS), env };
+        }
+        // Run the installed codex-acp under the current node. AGENTPRISM_CODEX_ACP_BIN overrides the
+        // resolved path; otherwise resolve the package's main (dist/index.js) from node_modules so it
+        // ships on a clean `git clone && pnpm install` (the @automatalabs/codex-acp fork already bakes
+        // in the outputSchema patch). Works from both src/ and the compiled dist/.
+        const bin = env.AGENTPRISM_CODEX_ACP_BIN ?? require.resolve("@automatalabs/codex-acp");
+        return { command: process.execPath, args: [bin], env };
+    }
+    sessionMeta() {
+        // Codex carries the schema on the turn, not session/new.
+        return undefined;
+    }
+    promptMeta(schema) {
+        if (!schema)
+            return undefined;
+        return { [META_KEYS.outputSchema]: toStrictJsonSchema(schema) };
+    }
+    nativeStructured(source) {
+        const text = source.currentTurnText().trim();
+        if (!text)
+            return undefined;
+        // The constrained final message is pure JSON; parse it directly, then fall back to a
+        // balanced-block extraction if the turn also emitted leading prose.
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            // fall through to block extraction
+        }
+        const block = findJsonBlock(text);
+        if (block !== undefined) {
+            try {
+                return JSON.parse(block);
+            }
+            catch {
+                // give up; the runner's ladder will re-prompt / extract.
+            }
+        }
+        return undefined;
+    }
+}

package/dist/errors-map.d.ts

@@ -0,0 +1,5 @@
+import { WorkflowError } from "@automatalabs/shared-types";
+export declare function errorText(error: unknown): string;
+/** Map any thrown error from the run path onto a seam-level WorkflowError. */
+export declare function mapThrownError(error: unknown, label?: string): WorkflowError;
+//# sourceMappingURL=errors-map.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors-map.d.ts","sourceRoot":"","sources":["../src/errors-map.ts"],"names":[],"mappings":"AAYA,OAAO,EAA0C,aAAa,EAAqB,MAAM,4BAA4B,CAAC;AAEtH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAahD;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,aAAa,CAmB5E"}

package/dist/errors-map.js

@@ -0,0 +1,47 @@
+// ACP failure -> WorkflowError{code, recoverable, resetHint}.
+//
+// Every hard backend failure REJECTS the ACP request (claude-agent-acp `failActive(...)`,
+// codex-acp request errors), so the runner catches one thrown error and classifies it HERE.
+// Provider usage/quota/rate walls are detected by running the thrown error's MESSAGE through
+// classifyProviderLimit (shared-types) — this is the "gate on the error channel, never task
+// text" rule: we only ever classify text that arrived via an error/reject, never the
+// assistant's normal output. A matched wall becomes PROVIDER_USAGE_LIMIT (non-recoverable +
+// resetHint -> the engine PAUSES and resumes instead of retrying into the same wall).
+// Everything else is a recoverable AGENT_EXECUTION_ERROR (transient process/ACP faults that
+// the engine retries). WorkflowErrors raised inside the ladder (SCHEMA_NONCOMPLIANCE,
+// AGENT_EMPTY_OUTPUT) pass through unchanged.
+import { classifyProviderLimit, isWorkflowError, WorkflowError, WorkflowErrorCode } from "@automatalabs/shared-types";
+export function errorText(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "string")
+        return error;
+    if (error && typeof error === "object") {
+        const message = error.message;
+        if (typeof message === "string")
+            return message;
+        try {
+            return JSON.stringify(error);
+        }
+        catch {
+            return String(error);
+        }
+    }
+    return String(error);
+}
+/** Map any thrown error from the run path onto a seam-level WorkflowError. */
+export function mapThrownError(error, label) {
+    // Already a seam error (e.g. SCHEMA_NONCOMPLIANCE / AGENT_EMPTY_OUTPUT raised in-band).
+    if (isWorkflowError(error))
+        return error;
+    const message = errorText(error);
+    const { matched, resetHint } = classifyProviderLimit(message);
+    if (matched) {
+        return new WorkflowError(message || "Provider usage/quota limit reached", WorkflowErrorCode.PROVIDER_USAGE_LIMIT, { recoverable: false, agentLabel: label, resetHint, details: error });
+    }
+    return new WorkflowError(message || "Subagent execution failed", WorkflowErrorCode.AGENT_EXECUTION_ERROR, {
+        recoverable: true,
+        agentLabel: label,
+        details: error,
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { AcpAgentRunner, createAcpRunner, selectBackend } from "./runner.js";
+export { PooledConnection, SessionHandle } from "./acp-client.js";
+export type { AcpSessionOptions, PooledConnectionDeps } from "./acp-client.js";
+export { AcpAgentPool, resolvePoolSize } from "./pool.js";
+export type { AcpPoolOptions } from "./pool.js";
+export type { Backend, BackendId, SpawnConfig, StructuredSource } from "./backend.js";
+export { ClaudeBackend } from "./backends/claude.js";
+export { CodexBackend } from "./backends/codex.js";
+export { decidePermission } from "./permissions.js";
+export type { ToolPolicy } from "./permissions.js";
+export { UsageAccumulator } from "./usage.js";
+export { toJsonSchema, toStrictJsonSchema } from "./schema-strict.js";
+export { extractValidated, findJsonBlock, resolveStructuredOutput, validateValue, } from "./structured-output.js";
+export type { ResolveOptions, StructuredSession } from "./structured-output.js";
+export { errorText, mapThrownError } from "./errors-map.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE7E,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAClE,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC1D,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEtE,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,uBAAuB,EACvB,aAAa,GACd,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+// @automatalabs/acp-agents — implements the AgentRunner seam from @automatalabs/shared-types over
+// the Agent Client Protocol. It spawns claude-agent-acp / the installed npm dep codex-acp
+// (patched via pnpm patchedDependencies) as child processes and drives one subagent run to
+// completion. It NEVER imports
+// @automatalabs/workflow-engine; the two siblings meet ONLY at AgentRunner, injected by
+// mcp-server (the composition root) via createAcpRunner().
+export { AcpAgentRunner, createAcpRunner, selectBackend } from "./runner.js";
+export { PooledConnection, SessionHandle } from "./acp-client.js";
+export { AcpAgentPool, resolvePoolSize } from "./pool.js";
+export { ClaudeBackend } from "./backends/claude.js";
+export { CodexBackend } from "./backends/codex.js";
+export { decidePermission } from "./permissions.js";
+export { UsageAccumulator } from "./usage.js";
+export { toJsonSchema, toStrictJsonSchema } from "./schema-strict.js";
+export { extractValidated, findJsonBlock, resolveStructuredOutput, validateValue, } from "./structured-output.js";
+export { errorText, mapThrownError } from "./errors-map.js";

package/dist/permissions.d.ts

@@ -0,0 +1,10 @@
+import type { RequestPermissionRequest, RequestPermissionResponse } from "@agentclientprotocol/sdk";
+export interface ToolPolicy {
+    /** Allow-list (agentType `tools`). When non-empty, a tool that matches NOTHING is denied. */
+    allow?: string[];
+    /** Deny-list (agentType `disallowedTools`), applied after the allow-list. */
+    deny?: string[];
+}
+/** Decide the auto-response for one permission request given the tool policy. */
+export declare function decidePermission(request: RequestPermissionRequest, policy: ToolPolicy): RequestPermissionResponse;
+//# sourceMappingURL=permissions.d.ts.map

package/dist/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAGV,wBAAwB,EACxB,yBAAyB,EAC1B,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,UAAU;IACzB,6FAA6F;IAC7F,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAKD,iFAAiF;AACjF,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,wBAAwB,EACjC,MAAM,EAAE,UAAU,GACjB,yBAAyB,CAqC3B"}

package/dist/permissions.js

@@ -0,0 +1,86 @@
+const ALLOW_KIND_ORDER = ["allow_once", "allow_always"];
+const REJECT_KIND_ORDER = ["reject_once", "reject_always"];
+/** Decide the auto-response for one permission request given the tool policy. */
+export function decidePermission(request, policy) {
+    const { toolNames, decoration } = candidateNames(request);
+    // (a) EXACT pool: the authoritative tool id (vendor _meta.toolName) when present, else
+    //     the human title/kind. The substring pool is everything, used only as a fallback.
+    const exactPool = toolNames.length > 0 ? toolNames : decoration;
+    const allPool = [...toolNames, ...decoration];
+    const denyList = policy.deny ?? [];
+    const allowList = policy.allow ?? [];
+    const hasDeny = denyList.length > 0;
+    const hasAllowList = allowList.length > 0;
+    const denyExact = hasDeny && exactMatchesAny(exactPool, denyList);
+    const allowExact = hasAllowList && exactMatchesAny(exactPool, allowList);
+    let denied;
+    let allowedByList;
+    if (denyExact || allowExact) {
+        // The tool is EXACTLY named by some policy entry -> decide on exact matches alone.
+        // (Suppresses loose substring matches: a deny `read` no longer catches an exactly
+        // allow-listed `thread-reader`.)
+        denied = denyExact;
+        allowedByList = !hasAllowList || allowExact;
+    }
+    else {
+        // (b) No exact match in either list -> best-effort bidirectional substring fallback.
+        denied = hasDeny && substringMatchesAny(allPool, denyList);
+        allowedByList = !hasAllowList || substringMatchesAny(allPool, allowList);
+    }
+    const wantAllow = !denied && allowedByList;
+    const option = pickOption(request.options, wantAllow);
+    if (!option) {
+        // No option of the desired polarity exists. Cancelling the permission is the only
+        // remaining way to refuse a tool the server offers no reject option for.
+        return { outcome: { outcome: "cancelled" } };
+    }
+    return { outcome: { outcome: "selected", optionId: option.optionId } };
+}
+function candidateNames(request) {
+    const decoration = [];
+    const toolCall = request.toolCall;
+    if (toolCall.title)
+        decoration.push(toolCall.title);
+    if (toolCall.kind)
+        decoration.push(toolCall.kind);
+    const toolNames = [];
+    collectMetaToolNames(toolCall._meta, toolNames);
+    return { toolNames, decoration };
+}
+function collectMetaToolNames(meta, out) {
+    if (!meta || typeof meta !== "object")
+        return;
+    for (const [key, value] of Object.entries(meta)) {
+        if (key === "toolName" && typeof value === "string")
+            out.push(value);
+        else if (value && typeof value === "object")
+            collectMetaToolNames(value, out);
+    }
+}
+/** (a) Does any pattern EXACTLY equal (case-insensitive) any candidate name? */
+function exactMatchesAny(names, patterns) {
+    const lowered = new Set(names.map((n) => n.toLowerCase()).filter(Boolean));
+    return patterns.some((pattern) => {
+        const p = pattern.toLowerCase();
+        return p.length > 0 && lowered.has(p);
+    });
+}
+/** (b) Best-effort bidirectional substring fallback (the prior, looser semantics). */
+function substringMatchesAny(names, patterns) {
+    const lowered = names.map((n) => n.toLowerCase()).filter(Boolean);
+    return patterns.some((pattern) => {
+        const p = pattern.toLowerCase();
+        if (!p)
+            return false;
+        return lowered.some((n) => n === p || n.includes(p) || p.includes(n));
+    });
+}
+function pickOption(options, wantAllow) {
+    const order = wantAllow ? ALLOW_KIND_ORDER : REJECT_KIND_ORDER;
+    for (const kind of order) {
+        const found = options.find((option) => option.kind === kind);
+        if (found)
+            return found;
+    }
+    return undefined;
+}

package/dist/pool.d.ts

@@ -0,0 +1,35 @@
+import type { Backend } from "./backend.js";
+import { SessionHandle, type AcpSessionOptions } from "./acp-client.js";
+export interface AcpPoolOptions {
+    /** Long-lived processes to keep PER backend. Default 1; falls back to AGENTPRISM_ACP_POOL_SIZE. */
+    size?: number;
+}
+/** Resolve the per-backend pool size: explicit option wins, else env, else 1. Clamped to >= 1. */
+export declare function resolvePoolSize(option?: number): number;
+export declare class AcpAgentPool {
+    private readonly size;
+    private readonly byBackend;
+    private readonly onProcessExit;
+    private exitHookInstalled;
+    private disposed;
+    constructor(options?: AcpPoolOptions);
+    /** Acquire a session for one agent() run: get/grow a pooled connection and open a session. */
+    acquire(backend: Backend, opts: AcpSessionOptions): Promise<SessionHandle>;
+    /**
+     * Pick the connection to host the next session. Runs SYNCHRONOUSLY (no await) through to the
+     * synchronous load-reservation in openSession(), so concurrent acquires never over-spawn or
+     * double-book a connection.
+     */
+    private selectConnection;
+    private connectionsFor;
+    /** Evict a dead connection so it is never handed out again. */
+    private drop;
+    /** Close every pooled process and clear the pool. Idempotent. */
+    dispose(): Promise<void>;
+    private allConnections;
+    private installExitHook;
+    private removeExitHook;
+    /** Synchronous best-effort child kill for the process-exit hook (no async work is possible). */
+    private killAllSync;
+}
+//# sourceMappingURL=pool.d.ts.map

package/dist/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,OAAO,EAAa,MAAM,cAAc,CAAC;AACvD,OAAO,EAAoB,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAK1F,MAAM,WAAW,cAAc;IAC7B,mGAAmG;IACnG,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAUvD;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4C;IACtE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4B;IAC1D,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,GAAE,cAAmB;IAIxC,8FAA8F;IACxF,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC;IAMhF;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAoBxB,OAAO,CAAC,cAAc;IAStB,+DAA+D;IAC/D,OAAO,CAAC,IAAI;IAOZ,iEAAiE;IAC3D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,cAAc;IAMtB,gGAAgG;IAChG,OAAO,CAAC,WAAW;CAGpB"}

package/dist/pool.js

@@ -0,0 +1,103 @@
+import { PooledConnection } from "./acp-client.js";
+const DEFAULT_POOL_SIZE = 1;
+const POOL_SIZE_ENV = "AGENTPRISM_ACP_POOL_SIZE";
+/** Resolve the per-backend pool size: explicit option wins, else env, else 1. Clamped to >= 1. */
+export function resolvePoolSize(option) {
+    if (typeof option === "number" && Number.isFinite(option) && option >= 1) {
+        return Math.floor(option);
+    }
+    const env = process.env[POOL_SIZE_ENV];
+    if (env !== undefined) {
+        const parsed = Number.parseInt(env, 10);
+        if (Number.isFinite(parsed) && parsed >= 1)
+            return parsed;
+    }
+    return DEFAULT_POOL_SIZE;
+}
+export class AcpAgentPool {
+    size;
+    byBackend = new Map();
+    onProcessExit = () => this.killAllSync();
+    exitHookInstalled = false;
+    disposed = false;
+    constructor(options = {}) {
+        this.size = resolvePoolSize(options.size);
+    }
+    /** Acquire a session for one agent() run: get/grow a pooled connection and open a session. */
+    async acquire(backend, opts) {
+        if (this.disposed)
+            throw new Error("ACP agent pool is disposed");
+        const connection = this.selectConnection(backend);
+        return connection.openSession(opts);
+    }
+    /**
+     * Pick the connection to host the next session. Runs SYNCHRONOUSLY (no await) through to the
+     * synchronous load-reservation in openSession(), so concurrent acquires never over-spawn or
+     * double-book a connection.
+     */
+    selectConnection(backend) {
+        const connections = this.connectionsFor(backend.id);
+        const live = connections.filter((c) => c.alive);
+        const idle = live.find((c) => c.activeSessions === 0);
+        if (idle)
+            return idle;
+        if (live.length < this.size) {
+            this.installExitHook();
+            const connection = PooledConnection.create(backend, {
+                onDead: (dead) => this.drop(backend.id, dead),
+            });
+            connections.push(connection);
+            return connection;
+        }
+        // At capacity with every connection busy: multiplex onto the least-loaded one.
+        return live.reduce((least, c) => (c.activeSessions < least.activeSessions ? c : least));
+    }
+    connectionsFor(id) {
+        let arr = this.byBackend.get(id);
+        if (!arr) {
+            arr = [];
+            this.byBackend.set(id, arr);
+        }
+        return arr;
+    }
+    /** Evict a dead connection so it is never handed out again. */
+    drop(id, connection) {
+        const arr = this.byBackend.get(id);
+        if (!arr)
+            return;
+        const index = arr.indexOf(connection);
+        if (index >= 0)
+            arr.splice(index, 1);
+    }
+    /** Close every pooled process and clear the pool. Idempotent. */
+    async dispose() {
+        this.disposed = true;
+        this.removeExitHook();
+        const all = this.allConnections();
+        this.byBackend.clear();
+        await Promise.all(all.map((c) => c.dispose()));
+    }
+    allConnections() {
+        const all = [];
+        for (const arr of this.byBackend.values())
+            all.push(...arr);
+        return all;
+    }
+    installExitHook() {
+        if (this.exitHookInstalled)
+            return;
+        this.exitHookInstalled = true;
+        process.once("exit", this.onProcessExit);
+    }
+    removeExitHook() {
+        if (!this.exitHookInstalled)
+            return;
+        this.exitHookInstalled = false;
+        process.removeListener("exit", this.onProcessExit);
+    }
+    /** Synchronous best-effort child kill for the process-exit hook (no async work is possible). */
+    killAllSync() {
+        for (const connection of this.allConnections())
+            connection.killNow();
+    }
+}

package/dist/runner.d.ts

@@ -0,0 +1,22 @@
+import { type AgentResult, type AgentRunner, type RunOptions } from "@automatalabs/shared-types";
+import type { TSchema } from "typebox";
+import { type AcpPoolOptions } from "./pool.js";
+import type { Backend } from "./backend.js";
+export declare class AcpAgentRunner implements AgentRunner {
+    private readonly pool;
+    constructor(options?: AcpPoolOptions);
+    run<S extends TSchema | undefined = undefined>(prompt: string, options?: RunOptions<S>): Promise<AgentResult<S>>;
+    /** Tear down the whole pool (close every long-lived process). Call when the run ends / the
+     *  runner is disposed. Beyond the AgentRunner seam (additive) — never enters the resume hash. */
+    dispose(): Promise<void>;
+}
+/** Factory the mcp-server composition root calls to inject the runner into the engine. The pool
+ *  size is a runner-level option (default 1, else AGENTPRISM_ACP_POOL_SIZE) — NOT a RunOptions
+ *  field, so it never enters hashAgentCall / the resume identity. */
+export declare function createAcpRunner(options?: AcpPoolOptions): AcpAgentRunner;
+/** Pick the backend by model/tier. Cross-provider routing = which ACP server to spawn. */
+export declare function selectBackend(opts: {
+    model?: string;
+    tier?: string;
+}): Backend;
+//# sourceMappingURL=runner.d.ts.map

package/dist/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAkBA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,UAAU,EAChB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAS5C,qBAAa,cAAe,YAAW,WAAW;IAChD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;gBAExB,OAAO,GAAE,cAAmB;IAIlC,GAAG,CAAC,CAAC,SAAS,OAAO,GAAG,SAAS,GAAG,SAAS,EACjD,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,UAAU,CAAC,CAAC,CAAM,GAC1B,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAiF1B;qGACiG;IAC3F,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B;AAED;;qEAEqE;AACrE,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,cAAc,CAExE;AAoED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAG9E"}