@automatalabs/acp-agents 0.5.1 → 0.7.0

package/README.md

@@ -99,6 +99,7 @@ Also exported: `AcpAgentPool` / `resolvePoolSize`, `PooledConnection` / `Session
 | --- | --- |
 | `AGENTPRISM_DEFAULT_BACKEND` | Backend when `model`/`tier` don't pick one (`codex` selects Codex; a registered custom name selects that backend; anything else is Claude). |
 | `AGENTPRISM_BACKENDS` | Custom ACP backends as JSON: `{"<name>": {"command": "…", "args": […], "env": {…}, "sessionMeta": {…}}}`. |
+| `AGENTPRISM_ACP_INIT_TIMEOUT_MS` | Deadline (default `60000`) for a backend's one-time ACP `initialize` handshake — a non-ACP command fails fast instead of hanging. |
 | `AGENTPRISM_ACP_POOL_SIZE` | Long-lived processes to keep per backend (default `1`). |
 | `AGENTPRISM_CLAUDE_ACP_CMD` / `AGENTPRISM_CLAUDE_ACP_ARGS` | Override the command (and args) used to spawn the Claude ACP server. |
 | `AGENTPRISM_CODEX_ACP_CMD` / `AGENTPRISM_CODEX_ACP_ARGS` | Override the command (and args) used to spawn the Codex ACP server. |

package/dist/acp-client.d.ts

@@ -2,6 +2,7 @@ import { ClientSideConnection, type PromptResponse, type SessionConfigOption, ty
 import type { TSchema } from "typebox";
 import { type AgentHistoryEntry, type McpServerConfig } from "@automatalabs/shared-types";
 import type { Backend, BackendId, StructuredSource } from "./backend.js";
+import { type NegotiatedCapabilities } from "./capabilities.js";
 import { type AcpEventSink } from "./events.js";
 import { type ToolPolicy } from "./permissions.js";
 import { UsageAccumulator } from "./usage.js";
@@ -83,7 +84,8 @@ export declare class PooledConnection {
     private readonly whenDead;
     private resolveDead;
     private deathError;
-    private supportsClose;
+    /** Set from the one-time initialize handshake; undefined until it completes (or if it failed). */
+    private negotiated;
     private _alive;
     private _activeSessions;
     private stderrTail;
@@ -93,6 +95,12 @@ export declare class PooledConnection {
     static create(backend: Backend, deps: PooledConnectionDeps): PooledConnection;
     get alive(): boolean;
     get activeSessions(): number;
+    /** The capabilities negotiated on this connection's one-time initialize handshake, or undefined
+     *  until it completes — derived-state-behind-a-getter, like `alive`/`activeSessions`. */
+    get capabilities(): NegotiatedCapabilities | undefined;
+    /** Drop the fork's custom bare `_meta` keys the connected agent did not advertise support for
+     *  (see gateCustomMeta). Applied to BOTH session/new and session/prompt `_meta`. */
+    gateCustomMeta(meta: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
     /** Mark this connection dead exactly once, then ask the pool to evict it. Idempotent. */
     private die;
     private stderrSuffix;

package/dist/acp-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"acp-client.d.ts","sourceRoot":"","sources":["../src/acp-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"acp-client.d.ts","sourceRoot":"","sources":["../src/acp-client.ts"],"names":[],"mappings":"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"}

package/dist/acp-client.js

@@ -23,7 +23,8 @@
 import { spawn } from "node:child_process";
 import { Readable, Writable } from "node:stream";
 import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION, } from "@agentclientprotocol/sdk";
-import { META_KEYS } from "@automatalabs/shared-types";
+import { META_KEYS, WorkflowError, WorkflowErrorCode, } from "@automatalabs/shared-types";
+import { gateCustomMeta, isSupportedProtocolVersion, negotiateCapabilities, unsupportedMcpServer, } from "./capabilities.js";
 import { emitSessionUpdate } from "./events.js";
 import { decidePermission } from "./permissions.js";
 import { UsageAccumulator } from "./usage.js";
@@ -171,6 +172,18 @@ class MultiplexClient {
         });
     }
 }
+const DEFAULT_INIT_TIMEOUT_MS = 60_000;
+/** Deadline for the one-time ACP `initialize` handshake per pooled process. Overridable via
+ *  AGENTPRISM_ACP_INIT_TIMEOUT_MS (e.g. for slow cold-start backends). Clamped to >= 1s. */
+function initializeTimeoutMs() {
+    const env = process.env.AGENTPRISM_ACP_INIT_TIMEOUT_MS;
+    if (env !== undefined) {
+        const parsed = Number.parseInt(env, 10);
+        if (Number.isFinite(parsed) && parsed >= 1000)
+            return parsed;
+    }
+    return DEFAULT_INIT_TIMEOUT_MS;
+}
 /** Shallow-merge `_meta` layers lowest-to-highest precedence, treating empty layers as absent
  *  so an unconfigured session keeps sending NO `_meta` at all. */
 function layerMeta(...layers) {
@@ -220,7 +233,8 @@ export class PooledConnection {
     whenDead;
     resolveDead;
     deathError;
-    supportsClose = false;
+    /** Set from the one-time initialize handshake; undefined until it completes (or if it failed). */
+    negotiated;
     _alive = true;
     _activeSessions = 0;
     stderrTail = "";
@@ -277,6 +291,16 @@ export class PooledConnection {
     get activeSessions() {
         return this._activeSessions;
     }
+    /** The capabilities negotiated on this connection's one-time initialize handshake, or undefined
+     *  until it completes — derived-state-behind-a-getter, like `alive`/`activeSessions`. */
+    get capabilities() {
+        return this.negotiated;
+    }
+    /** Drop the fork's custom bare `_meta` keys the connected agent did not advertise support for
+     *  (see gateCustomMeta). Applied to BOTH session/new and session/prompt `_meta`. */
+    gateCustomMeta(meta) {
+        return gateCustomMeta(meta, this.negotiated?.customMetaSupport);
+    }
     /** Mark this connection dead exactly once, then ask the pool to evict it. Idempotent. */
     die(error) {
         if (!this._alive)
@@ -307,12 +331,49 @@ export class PooledConnection {
         return Promise.race([op, dead]);
     }
     async initialize() {
-        const response = await this.race(this.rpc.initialize({
-            protocolVersion: PROTOCOL_VERSION,
-            clientCapabilities: {},
-            clientInfo: { ...CLIENT_INFO },
-        }));
-        this.supportsClose = Boolean(response.agentCapabilities?.sessionCapabilities?.close);
+        // Handshake deadline: a command that is NOT an ACP server never answers `initialize`, and
+        // without a deadline the first openSession() would hang forever. On timeout the process is
+        // killed and a legible error surfaces (fail-fast hygiene — this is NOT a security gate;
+        // the process has already been spawned by then). Tunable for slow cold starts.
+        const timeoutMs = initializeTimeoutMs();
+        let timer;
+        const deadline = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                reject(new Error(`ACP agent (${this.backendId}) did not complete the ACP initialize handshake within ${timeoutMs}ms — ` +
+                    `is the configured command an ACP server?${this.stderrSuffix()}`));
+                this.killNow();
+            }, timeoutMs);
+            timer.unref?.();
+        });
+        try {
+            const response = await Promise.race([
+                this.race(this.rpc.initialize({
+                    protocolVersion: PROTOCOL_VERSION,
+                    // Truthful advertisement: MultiplexClient implements NONE of the client-side
+                    // fs/terminal methods, so we advertise none (the ACP rule is "advertise only what you
+                    // implement"). Everything omitted here is treated as unsupported by the agent.
+                    clientCapabilities: {},
+                    clientInfo: { ...CLIENT_INFO },
+                })),
+                deadline,
+            ]);
+            const negotiated = negotiateCapabilities(response);
+            // Version negotiation: the agent replies with the version it chose (our requested version if
+            // it supports it, else its own latest). If this client cannot speak it, the ACP spec says
+            // CLOSE the connection and inform the user — kill the process (so the pool evicts it) and
+            // surface a legible error instead of proceeding on an unspoken protocol. Non-recoverable: a
+            // deterministic protocol incompatibility must fail fast, not be retried as a transient
+            // AGENT_EXECUTION_ERROR.
+            if (!isSupportedProtocolVersion(negotiated.protocolVersion)) {
+                this.killNow();
+                throw new WorkflowError(`ACP agent (${this.backendId}) selected protocol version ${negotiated.protocolVersion}, which ` +
+                    `this client (protocol v${PROTOCOL_VERSION}) does not support — closing the connection.${this.stderrSuffix()}`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false });
+            }
+            this.negotiated = negotiated;
+        }
+        finally {
+            clearTimeout(timer);
+        }
     }
     /**
      * Open a new per-agent session on this pooled connection: session/new { cwd }, register its
@@ -323,16 +384,28 @@ export class PooledConnection {
         this._activeSessions += 1;
         try {
             await this.ready;
+            // Capability gate: reject a client-provided MCP server whose transport the connected agent
+            // does not advertise (http/sse gated on mcpCapabilities; stdio is always serviceable).
+            // Fail-fast and non-recoverable — re-running the same incompatible transport can never
+            // succeed. Lenient for agents that advertise no mcpCapabilities (the legacy passthrough).
+            const unsupported = this.negotiated
+                ? unsupportedMcpServer(opts.mcpServers, this.negotiated.agent)
+                : undefined;
+            if (unsupported) {
+                throw new WorkflowError(`MCP server "${unsupported.name}" uses the "${unsupported.transport}" transport, which the ` +
+                    `${this.backendId} agent does not support`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: opts.label });
+            }
             const state = new SessionState(opts.policy, opts.label, opts.runId);
             // session/new `_meta`, layered lowest-to-highest precedence: the backend's static
             // defaults (a custom registry entry's `sessionMeta`), then the generic user passthrough
             // (opts.meta), then the backend's protocol-critical `_meta` (Claude schema channel;
-            // Codex base/developer instructions), then the engine runId correlation stamp. When no
-            // layer is present, no `_meta` is sent.
-            const meta = stampRunId(layerMeta(this.backend.sessionMetaDefaults?.(), opts.meta, this.backend.sessionMeta(opts.schema, {
+            // Codex base/developer instructions), then the engine runId correlation stamp. The result
+            // is gated against the agent's advertised custom capabilities (a Codex instruction key the
+            // agent said it does not honor is dropped). When no layer survives, no `_meta` is sent.
+            const meta = this.gateCustomMeta(stampRunId(layerMeta(this.backend.sessionMetaDefaults?.(), opts.meta, this.backend.sessionMeta(opts.schema, {
                 baseInstructions: opts.baseInstructions,
                 developerInstructions: opts.developerInstructions,
-            })), opts.runId);
+            })), opts.runId));
             const request = {
                 cwd: opts.cwd,
                 // Client-provided MCP servers (additive run input), else the default empty list.
@@ -368,7 +441,7 @@ export class PooledConnection {
         this.client.unregister(sessionId);
         if (this._activeSessions > 0)
             this._activeSessions -= 1;
-        if (!this.supportsClose || !this._alive)
+        if (!this.negotiated?.supportsClose || !this._alive)
             return;
         try {
             await this.race(withTimeout(this.rpc.closeSession({ sessionId }), CLOSE_SESSION_TIMEOUT_MS));
@@ -554,10 +627,13 @@ export class SessionHandle {
         this.opts.signal?.throwIfAborted();
         this.state.beginTurn();
         const prompt = [{ type: "text", text }];
+        // Gate the turn `_meta` against the agent's advertised custom capabilities: the Codex
+        // outputSchema forward is dropped when the connected agent said it does not honor it.
+        const gatedMeta = this.pooled.gateCustomMeta(promptMeta);
         const request = {
             sessionId: this.sessionId,
             prompt,
-            ...(promptMeta ? { _meta: promptMeta } : {}),
+            ...(gatedMeta ? { _meta: gatedMeta } : {}),
         };
         const response = await this.pooled.race(this.pooled.rpc.prompt(request));
         this.state.usage.recordPromptUsage(response.usage);

package/dist/backend.d.ts

@@ -26,6 +26,11 @@ export interface SessionMetaInputs {
 }
 export interface Backend {
     readonly id: BackendId;
+    /** Pool identity for this backend's long-lived processes. Defaults to `id` — but a CUSTOM
+     *  backend sets it to id + a spawn-config hash, because two runs may declare the SAME name
+     *  with DIFFERENT commands (script-declared `meta.backends`): keying the pool by name alone
+     *  would hand run B a pooled process spawned from run A's command. */
+    readonly poolKey?: string;
     /** When true, the runner EMBEDS the JSON Schema in the prompt text on schema runs. For the
      *  built-ins the native constraint channel is authoritative and this stays unset; a CUSTOM
      *  backend sets it because its agent may ignore the `_meta.outputSchema` forward entirely —

package/dist/backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,4FAA4F;AAC5F,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,OAAO,CAAC;AAClD;sFACsF;AACtF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AAED,8FAA8F;AAC9F,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,eAAe,IAAI,MAAM,CAAC;IAC1B,uGAAuG;IACvG,mBAAmB,IAAI,OAAO,CAAC;CAChC;AAED;+EAC+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,yFAAyF;IACzF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sFAAsF;IACtF,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB;;;;kGAI8F;IAC9F,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,0DAA0D;IAC1D,WAAW,IAAI,WAAW,CAAC;IAC3B;;sEAEkE;IAClE,mBAAmB,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC5D;;;mGAG+F;IAC/F,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,EAAE,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC1G,kGAAkG;IAClG,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC7E,oGAAoG;IACpG,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC;CACrD;AAED,6FAA6F;AAC7F,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAE7D"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,4FAA4F;AAC5F,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,OAAO,CAAC;AAClD;sFACsF;AACtF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AAED,8FAA8F;AAC9F,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,eAAe,IAAI,MAAM,CAAC;IAC1B,uGAAuG;IACvG,mBAAmB,IAAI,OAAO,CAAC;CAChC;AAED;+EAC+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,yFAAyF;IACzF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sFAAsF;IACtF,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB;;;0EAGsE;IACtE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;kGAI8F;IAC9F,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,0DAA0D;IAC1D,WAAW,IAAI,WAAW,CAAC;IAC3B;;sEAEkE;IAClE,mBAAmB,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC5D;;;mGAG+F;IAC/F,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,EAAE,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC1G,kGAAkG;IAClG,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC7E,oGAAoG;IACpG,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC;CACrD;AAED,6FAA6F;AAC7F,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAE7D"}

package/dist/backends/custom.d.ts

@@ -4,6 +4,9 @@ import type { RegisteredBackend } from "../registry.js";
 export declare class CustomAcpBackend implements Backend {
     private readonly config;
     readonly id: string;
+    /** id + spawn-config hash: two registries (e.g. two scripts' `meta.backends`) may declare
+     *  the SAME name with DIFFERENT commands — the pool must never share a process across them. */
+    readonly poolKey: string;
     /** The agent may ignore the `_meta.outputSchema` forward, so the runner must also state the
      *  schema in the prompt — otherwise the model returns JSON with keys it invented and the
      *  repair ladder can never converge on a contract the model was never shown. */

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

@@ -1 +1 @@
-{"version":3,"file":"custom.d.ts","sourceRoot":"","sources":["../../src/backends/custom.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAIxD,qBAAa,gBAAiB,YAAW,OAAO;IAOlC,OAAO,CAAC,QAAQ,CAAC,MAAM;IANnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;oFAEgF;IAChF,QAAQ,CAAC,mBAAmB,QAAQ;gBAEP,MAAM,EAAE,iBAAiB;IAItD,WAAW,IAAI,WAAW;IAS1B,mBAAmB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAQ1D,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAM9E,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAQ5E,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO;CAGpD"}
+{"version":3,"file":"custom.d.ts","sourceRoot":"","sources":["../../src/backends/custom.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAIxD,qBAAa,gBAAiB,YAAW,OAAO;IAUlC,OAAO,CAAC,QAAQ,CAAC,MAAM;IATnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;mGAC+F;IAC/F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;oFAEgF;IAChF,QAAQ,CAAC,mBAAmB,QAAQ;gBAEP,MAAM,EAAE,iBAAiB;IAUtD,WAAW,IAAI,WAAW;IAS1B,mBAAmB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAQ1D,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAM9E,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAQ5E,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO;CAGpD"}

package/dist/backends/custom.js

@@ -1,9 +1,26 @@
+// CustomAcpBackend — drives ANY registered ACP agent (registry.ts), not just the built-in
+// Claude/Codex pair. The generic dialect it speaks is the one this repo already publishes:
+//   - schema IN:   the bare turn-level `_meta.outputSchema` (same key the @automatalabs/codex-acp
+//                  fork reads), as a plain JSON Schema. An agent that honors it constrains its
+//                  final message natively; an agent that ignores it still works — the runner's
+//                  validate/re-prompt ladder repairs off the final text.
+//   - result OUT:  JSON.parse of the final assistant message (with a balanced-block fallback),
+//                  exactly like Codex — no vendor extension notification required.
+//   - config-level `_meta`: the registry entry's static `sessionMeta` rides every session/new
+//                  (per-call RunOptions.meta merges over it in the ACP client; backend-computed
+//                  keys and the runId stamp win over both).
+// SessionMetaInputs (Codex base/developer instruction overrides) are IGNORED — they are a
+// codex-acp vendor contract; a custom agent's knobs travel through the generic meta channels.
+import { createHash } from "node:crypto";
 import { META_KEYS } from "@automatalabs/shared-types";
 import { toJsonSchema } from "../schema-strict.js";
 import { parseFinalJson } from "../structured-output.js";
 export class CustomAcpBackend {
     config;
     id;
+    /** id + spawn-config hash: two registries (e.g. two scripts' `meta.backends`) may declare
+     *  the SAME name with DIFFERENT commands — the pool must never share a process across them. */
+    poolKey;
     /** The agent may ignore the `_meta.outputSchema` forward, so the runner must also state the
      *  schema in the prompt — otherwise the model returns JSON with keys it invented and the
      *  repair ladder can never converge on a contract the model was never shown. */
@@ -11,6 +28,12 @@ export class CustomAcpBackend {
     constructor(config) {
         this.config = config;
         this.id = config.name;
+        const spawnIdentity = JSON.stringify({
+            command: config.command,
+            args: config.args ?? [],
+            env: config.env ?? {},
+        });
+        this.poolKey = `${config.name}#${createHash("sha256").update(spawnIdentity).digest("hex").slice(0, 12)}`;
     }
     spawnConfig() {
         return {

package/dist/capabilities.d.ts

@@ -0,0 +1,46 @@
+import { type AgentCapabilities, type Implementation, type InitializeResponse } from "@agentclientprotocol/sdk";
+import { type McpServerConfig } from "@automatalabs/shared-types";
+/** The bare `_meta` keys whose emission is gated by the fork's custom-capability advertisement.
+ *  Each is named EXACTLY like the advertised flag that gates it, so `support[key] === true` is the
+ *  whole test. session/new carries baseInstructions/developerInstructions and session/prompt carries
+ *  outputSchema — one list covers both (a key absent from a given `_meta` is simply skipped). */
+export declare const GATED_CUSTOM_META_KEYS: readonly string[];
+/** The capability state a pooled connection derives from its initialize response. */
+export interface NegotiatedCapabilities {
+    /** The protocol version the agent selected (echoes the client's when supported, else the agent's
+     *  latest). Validated by isSupportedProtocolVersion before the connection is used. */
+    protocolVersion: number;
+    /** The agent's full advertised capabilities — an empty object when the agent sent none (every
+     *  capability is then UNSUPPORTED per the ACP spec). */
+    agent: AgentCapabilities;
+    /** The agent's self-identification, when it sent agentInfo. */
+    agentInfo: Implementation | undefined;
+    /** Whether session/close is advertised (gates the best-effort release-time close). */
+    supportsClose: boolean;
+    /** The parsed @automatalabs/codex-acp custom-capability block (the namespaced `_meta` object), or
+     *  undefined when the agent did not advertise the namespace at all — the legacy passthrough. */
+    customMetaSupport: Record<string, unknown> | undefined;
+}
+/** Parse an initialize response into the connection's derived capability state. */
+export declare function negotiateCapabilities(response: InitializeResponse): NegotiatedCapabilities;
+/** True only when the agent selected EXACTLY PROTOCOL_VERSION. This client implements that one wire
+ *  version and adapts its behavior to no other, so any other selected version — older or newer —
+ *  means close the connection per the ACP spec's SHOULD-close rule. Per the spec the agent echoes
+ *  the requested version when it supports it, else its own latest; we do NOT accept older versions
+ *  (we cannot speak them) — the equality is the whole test. */
+export declare function isSupportedProtocolVersion(version: number): boolean;
+/** Remove the fork's custom bare `_meta` keys the connected agent did NOT advertise support for.
+ *  A no-op when the agent advertised no namespace (`support` undefined => legacy => every key
+ *  passes) or the meta is empty/undefined. Never mutates its input; collapses to undefined if
+ *  gating empties the object (so no `_meta` is sent at all). */
+export declare function gateCustomMeta(meta: Record<string, unknown> | undefined, support: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+/** The first client-provided MCP server whose transport the agent did NOT advertise, or undefined
+ *  when every server is serviceable. stdio is ALWAYS serviceable (the baseline transport); http/sse
+ *  are gated on mcpCapabilities.{http,sse}. Lenient for legacy agents: when the agent advertised no
+ *  mcpCapabilities at all we cannot know its transports, so we do not gate (preserving today's
+ *  send-and-let-the-agent-decide behavior for minimal/custom servers). */
+export declare function unsupportedMcpServer(servers: McpServerConfig[] | undefined, agent: AgentCapabilities): {
+    name: string;
+    transport: "http" | "sse";
+} | undefined;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAeA,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AAEpC;;;iGAGiG;AACjG,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAInD,CAAC;AAEF,qFAAqF;AACrF,MAAM,WAAW,sBAAsB;IACrC;0FACsF;IACtF,eAAe,EAAE,MAAM,CAAC;IACxB;4DACwD;IACxD,KAAK,EAAE,iBAAiB,CAAC;IACzB,+DAA+D;IAC/D,SAAS,EAAE,cAAc,GAAG,SAAS,CAAC;IACtC,sFAAsF;IACtF,aAAa,EAAE,OAAO,CAAC;IACvB;oGACgG;IAChG,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CACxD;AAED,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,sBAAsB,CAS1F;AAUD;;;;+DAI+D;AAC/D,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED;;;gEAGgE;AAChE,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC3C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAWrC;AAED;;;;0EAI0E;AAC1E,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,eAAe,EAAE,GAAG,SAAS,EACtC,KAAK,EAAE,iBAAiB,GACvB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAAA;CAAE,GAAG,SAAS,CAYzD"}

package/dist/capabilities.js

@@ -0,0 +1,89 @@
+// Negotiated ACP capabilities for one pooled connection — the derived state the connection acts on
+// after its ONE-TIME `initialize` handshake. Parses the InitializeResponse into: the agent's chosen
+// protocolVersion (validated against what this client speaks), its full advertised agentCapabilities
+// + agentInfo, whether session/close is supported, and the @automatalabs/codex-acp fork's custom
+// capability advertisement (the namespaced `_meta` block gating which bare `_meta` inputs the client
+// may send).
+//
+// GATING PHILOSOPHY — lenient for legacy agents. An agent that advertises NOTHING is treated as
+// today's behavior (every gated key still sent), because the currently-published fork
+// (@automatalabs/codex-acp ≤ 1.2.0) and arbitrary custom ACP servers honor these inputs WITHOUT
+// advertising them; a strict "omitted => unsupported" reading would silently regress them. Only once
+// an agent DOES advertise the fork namespace (opts into negotiation) is each bare key gated on its
+// same-named flag — and, symmetrically, only once an agent advertises mcpCapabilities is an
+// unsupported MCP transport rejected. Truthfully-advertised absence still gates (per spec) WITHIN an
+// advertised capability; total silence is the legacy passthrough.
+import { PROTOCOL_VERSION, } from "@agentclientprotocol/sdk";
+import { CODEX_CUSTOM_CAPABILITY_NAMESPACE, CODEX_META_KEYS, META_KEYS, } from "@automatalabs/shared-types";
+/** The bare `_meta` keys whose emission is gated by the fork's custom-capability advertisement.
+ *  Each is named EXACTLY like the advertised flag that gates it, so `support[key] === true` is the
+ *  whole test. session/new carries baseInstructions/developerInstructions and session/prompt carries
+ *  outputSchema — one list covers both (a key absent from a given `_meta` is simply skipped). */
+export const GATED_CUSTOM_META_KEYS = [
+    META_KEYS.outputSchema,
+    CODEX_META_KEYS.baseInstructions,
+    CODEX_META_KEYS.developerInstructions,
+];
+/** Parse an initialize response into the connection's derived capability state. */
+export function negotiateCapabilities(response) {
+    const agent = response.agentCapabilities ?? {};
+    return {
+        protocolVersion: response.protocolVersion,
+        agent,
+        agentInfo: response.agentInfo ?? undefined,
+        supportsClose: Boolean(agent.sessionCapabilities?.close),
+        customMetaSupport: readCustomNamespace(agent._meta),
+    };
+}
+function readCustomNamespace(meta) {
+    if (!meta || typeof meta !== "object")
+        return undefined;
+    const block = meta[CODEX_CUSTOM_CAPABILITY_NAMESPACE];
+    return block && typeof block === "object" && !Array.isArray(block)
+        ? block
+        : undefined;
+}
+/** True only when the agent selected EXACTLY PROTOCOL_VERSION. This client implements that one wire
+ *  version and adapts its behavior to no other, so any other selected version — older or newer —
+ *  means close the connection per the ACP spec's SHOULD-close rule. Per the spec the agent echoes
+ *  the requested version when it supports it, else its own latest; we do NOT accept older versions
+ *  (we cannot speak them) — the equality is the whole test. */
+export function isSupportedProtocolVersion(version) {
+    return version === PROTOCOL_VERSION;
+}
+/** Remove the fork's custom bare `_meta` keys the connected agent did NOT advertise support for.
+ *  A no-op when the agent advertised no namespace (`support` undefined => legacy => every key
+ *  passes) or the meta is empty/undefined. Never mutates its input; collapses to undefined if
+ *  gating empties the object (so no `_meta` is sent at all). */
+export function gateCustomMeta(meta, support) {
+    if (!meta || !support)
+        return meta;
+    let gated;
+    for (const key of GATED_CUSTOM_META_KEYS) {
+        if (key in meta && support[key] !== true) {
+            gated ??= { ...meta };
+            delete gated[key];
+        }
+    }
+    const result = gated ?? meta;
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+/** The first client-provided MCP server whose transport the agent did NOT advertise, or undefined
+ *  when every server is serviceable. stdio is ALWAYS serviceable (the baseline transport); http/sse
+ *  are gated on mcpCapabilities.{http,sse}. Lenient for legacy agents: when the agent advertised no
+ *  mcpCapabilities at all we cannot know its transports, so we do not gate (preserving today's
+ *  send-and-let-the-agent-decide behavior for minimal/custom servers). */
+export function unsupportedMcpServer(servers, agent) {
+    const mcp = agent.mcpCapabilities;
+    if (!mcp || !servers)
+        return undefined;
+    for (const server of servers) {
+        if ("type" in server && server.type === "http" && mcp.http !== true) {
+            return { name: server.name, transport: "http" };
+        }
+        if ("type" in server && server.type === "sse" && mcp.sse !== true) {
+            return { name: server.name, transport: "sse" };
+        }
+    }
+    return undefined;
+}

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 export { AcpAgentRunner, createAcpRunner, selectBackend } from "./runner.js";
 export type { AcpRunnerOptions } from "./runner.js";
-export { BACKENDS_ENV, resolveBackendRegistry } from "./registry.js";
+export { BACKENDS_ENV, registryWithRunBackends, resolveBackendRegistry } from "./registry.js";
 export type { BackendRegistry, CustomBackendConfig, RegisteredBackend } from "./registry.js";
 export { PooledConnection, SessionHandle } from "./acp-client.js";
 export type { AcpSessionOptions, PooledConnectionDeps } from "./acp-client.js";
+export { GATED_CUSTOM_META_KEYS, gateCustomMeta, isSupportedProtocolVersion, negotiateCapabilities, unsupportedMcpServer, } from "./capabilities.js";
+export type { NegotiatedCapabilities } from "./capabilities.js";
 export { AcpAgentPool, resolvePoolSize } from "./pool.js";
 export type { AcpPoolOptions, AcpPoolDeps } from "./pool.js";
 export { TypedEventEmitter, emitSessionUpdate } from "./events.js";

package/dist/index.d.ts.map

@@ -1 +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;AAC7E,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACrE,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE7F,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,WAAW,EAAE,MAAM,WAAW,CAAC;AAG7D,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACnE,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,OAAO,EACP,SAAS,EACT,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,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,cAAc,EACd,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"}
+{"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;AAC7E,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC9F,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE7F,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAClE,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAI/E,OAAO,EACL,sBAAsB,EACtB,cAAc,EACd,0BAA0B,EAC1B,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC1D,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAG7D,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACnE,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,OAAO,EACP,SAAS,EACT,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,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,cAAc,EACd,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

@@ -6,8 +6,11 @@
 // @automatalabs/workflows facade (which mcp-server builds on) via createAcpRunner().
 export { AcpAgentRunner, createAcpRunner, selectBackend } from "./runner.js";
 // The custom-backend registry: run ANY ACP agent as an agent() target.
-export { BACKENDS_ENV, resolveBackendRegistry } from "./registry.js";
+export { BACKENDS_ENV, registryWithRunBackends, resolveBackendRegistry } from "./registry.js";
 export { PooledConnection, SessionHandle } from "./acp-client.js";
+// ACP capability negotiation: parse/validate the initialize response and gate what the client
+// sends (custom `_meta` keys, MCP transports) on what the connected agent advertised.
+export { GATED_CUSTOM_META_KEYS, gateCustomMeta, isSupportedProtocolVersion, negotiateCapabilities, unsupportedMcpServer, } from "./capabilities.js";
 export { AcpAgentPool, resolvePoolSize } from "./pool.js";
 // The typed ACP event bus surfaced on AcpAgentRunner (`runner.on(name, evt => …)`).
 export { TypedEventEmitter, emitSessionUpdate } from "./events.js";

package/dist/pool.d.ts.map

@@ -1 +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;AAC1F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAKhD,MAAM,WAAW,cAAc;IAC7B,mGAAmG;IACnG,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;kGACkG;AAClG,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAUvD;AAED,qBAAa,YAAY;IASrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IARvB,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;gBAGvB,OAAO,GAAE,cAAmB,EACX,IAAI,GAAE,WAAgB;IAKzC,8FAA8F;IACxF,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC;IAMhF;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAqBxB,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"}
+{"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;AAC1F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAKhD,MAAM,WAAW,cAAc;IAC7B,mGAAmG;IACnG,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;kGACkG;AAClG,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAUvD;AAED,qBAAa,YAAY;IASrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IARvB,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;gBAGvB,OAAO,GAAE,cAAmB,EACX,IAAI,GAAE,WAAgB;IAKzC,8FAA8F;IACxF,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC;IAMhF;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAwBxB,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

@@ -38,7 +38,10 @@ export class AcpAgentPool {
      * double-book a connection.
      */
     selectConnection(backend) {
-        const connections = this.connectionsFor(backend.id);
+        // Pool identity: poolKey (id + spawn-config hash for custom backends) over bare id, so two
+        // runs declaring the same NAME with different COMMANDS never share a process.
+        const key = backend.poolKey ?? backend.id;
+        const connections = this.connectionsFor(key);
         const live = connections.filter((c) => c.alive);
         const idle = live.find((c) => c.activeSessions === 0);
         if (idle)
@@ -46,7 +49,7 @@ export class AcpAgentPool {
         if (live.length < this.size) {
             this.installExitHook();
             const connection = PooledConnection.create(backend, {
-                onDead: (dead) => this.drop(backend.id, dead),
+                onDead: (dead) => this.drop(key, dead),
                 onEvent: this.deps.onEvent,
             });
             connections.push(connection);
@@ -55,17 +58,17 @@ export class AcpAgentPool {
         // 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);
+    connectionsFor(key) {
+        let arr = this.byBackend.get(key);
         if (!arr) {
             arr = [];
-            this.byBackend.set(id, arr);
+            this.byBackend.set(key, arr);
         }
         return arr;
     }
     /** Evict a dead connection so it is never handed out again. */
-    drop(id, connection) {
-        const arr = this.byBackend.get(id);
+    drop(key, connection) {
+        const arr = this.byBackend.get(key);
         if (!arr)
             return;
         const index = arr.indexOf(connection);

package/dist/registry.d.ts

@@ -23,4 +23,12 @@ export type BackendRegistry = ReadonlyMap<string, RegisteredBackend>;
  * misroute at run time.
  */
 export declare function resolveBackendRegistry(option?: Record<string, CustomBackendConfig>, env?: NodeJS.ProcessEnv): BackendRegistry;
+/**
+ * Layer a RUN-SCOPED registry (an approved script-declared `meta.backends`, arriving via
+ * RunOptions.backends) UNDER the host registry: run entries are validated with the same rules
+ * (reserved names rejected), and a host-registered name always wins on conflict — a script can
+ * never hijack a name the operator configured. Returns the host registry unchanged when the
+ * run declares nothing.
+ */
+export declare function registryWithRunBackends(host: BackendRegistry, run?: Record<string, CustomBackendConfig>): BackendRegistry;
 //# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,YAAY,wBAAwB,CAAC;AAKlD,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,mFAAmF;IACnF,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B;2FACuF;IACvF,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,yEAAyE;AACzE,MAAM,WAAW,iBAAkB,SAAQ,mBAAmB;IAC5D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAErE;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EAC5C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,eAAe,CAwBjB"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,YAAY,wBAAwB,CAAC;AAKlD,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,mFAAmF;IACnF,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B;2FACuF;IACvF,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,yEAAyE;AACzE,MAAM,WAAW,iBAAkB,SAAQ,mBAAmB;IAC5D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAErE;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EAC5C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,eAAe,CAwBjB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,eAAe,EACrB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,GACxC,eAAe,CAQjB"}

package/dist/registry.js

@@ -39,6 +39,24 @@ export function resolveBackendRegistry(option, env = process.env) {
     }
     return registry;
 }
+/**
+ * Layer a RUN-SCOPED registry (an approved script-declared `meta.backends`, arriving via
+ * RunOptions.backends) UNDER the host registry: run entries are validated with the same rules
+ * (reserved names rejected), and a host-registered name always wins on conflict — a script can
+ * never hijack a name the operator configured. Returns the host registry unchanged when the
+ * run declares nothing.
+ */
+export function registryWithRunBackends(host, run) {
+    if (!run || Object.keys(run).length === 0)
+        return host;
+    const merged = new Map();
+    for (const [name, config] of Object.entries(run)) {
+        merged.set(...validateEntry(name, config, "script backends (meta.backends)"));
+    }
+    for (const [name, entry] of host)
+        merged.set(name, entry); // host wins on conflict
+    return merged;
+}
 function validateEntry(rawName, config, source) {
     const name = rawName.toLowerCase();
     if (!NAME_PATTERN.test(name)) {

package/dist/runner.d.ts.map

@@ -1 +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,EAEL,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAGlB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAI5C,OAAO,EAA0B,KAAK,eAAe,EAAE,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAQvG;0FAC0F;AAC1F,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD;6FACyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CAChD;AAED,qBAAa,cAAe,YAAW,WAAW;IAChD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC,sFAAsF;IACtF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C;uGACmG;IACnG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8C;IACrE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgE;gBAE9E,OAAO,GAAE,gBAAqB;IAK1C;;;;;;;;OAQG;IACH,EAAE,CAAC,CAAC,SAAS,YAAY,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAI9E,+EAA+E;IAC/E,IAAI,CAAC,CAAC,SAAS,YAAY,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAIhF,GAAG,CAAC,CAAC,SAAS,YAAY,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,IAAI;IAIzE,kBAAkB,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,IAAI;IAI7C,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM;IAInC,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;IA+F1B;qGACiG;IAC3F,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAI/B;AAED;;;qDAGqD;AACrD,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,cAAc,CAE1E;AAmFD;;;;oCAIoC;AACpC,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,OAAO,CAM1G"}
+{"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,EAEL,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAGlB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAI5C,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACzB,MAAM,eAAe,CAAC;AAQvB;0FAC0F;AAC1F,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD;6FACyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CAChD;AAED,qBAAa,cAAe,YAAW,WAAW;IAChD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC,sFAAsF;IACtF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C;uGACmG;IACnG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8C;IACrE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgE;gBAE9E,OAAO,GAAE,gBAAqB;IAK1C;;;;;;;;OAQG;IACH,EAAE,CAAC,CAAC,SAAS,YAAY,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAI9E,+EAA+E;IAC/E,IAAI,CAAC,CAAC,SAAS,YAAY,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAIhF,GAAG,CAAC,CAAC,SAAS,YAAY,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,IAAI;IAIzE,kBAAkB,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,IAAI;IAI7C,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM;IAInC,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;IA2G1B;qGACiG;IAC3F,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAI/B;AAED;;;qDAGqD;AACrD,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,cAAc,CAE1E;AAmFD;;;;oCAIoC;AACpC,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,OAAO,CAM1G"}

package/dist/runner.js

@@ -22,7 +22,7 @@ import { TypedEventEmitter, } from "./events.js";
 import { ClaudeBackend } from "./backends/claude.js";
 import { CodexBackend } from "./backends/codex.js";
 import { CustomAcpBackend } from "./backends/custom.js";
-import { resolveBackendRegistry } from "./registry.js";
+import { registryWithRunBackends, resolveBackendRegistry, } from "./registry.js";
 import { mapThrownError } from "./errors-map.js";
 import { toJsonSchema } from "./schema-strict.js";
 import { resolveStructuredOutput } from "./structured-output.js";
@@ -66,7 +66,20 @@ export class AcpAgentRunner {
     async run(prompt, options = {}) {
         const opts = options;
         const schema = opts.schema;
-        const backend = selectBackend(opts, this.backends);
+        // Layer any run-scoped backends (an APPROVED script-declared meta.backends) under the
+        // host registry. Malformed/reserved entries fail the call loudly and are NOT retried —
+        // re-running a misdeclared registry can never succeed.
+        let registry;
+        try {
+            registry = registryWithRunBackends(this.backends, opts.backends);
+        }
+        catch (error) {
+            throw new WorkflowError(error.message, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, {
+                recoverable: false,
+                agentLabel: opts.label,
+            });
+        }
+        const backend = selectBackend(opts, registry);
         const policy = { allow: opts.toolNames, deny: opts.disallowedToolNames };
         const cwd = opts.cwd ?? process.cwd();
         const session = await this.pool.acquire(backend, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automatalabs/acp-agents",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -24,11 +24,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@agentclientprotocol/sdk": "1.0.0",
-    "@agentclientprotocol/claude-agent-acp": "0.53.0",
-    "@automatalabs/codex-acp": "1.2.0",
+    "@agentclientprotocol/sdk": "1.1.0",
+    "@agentclientprotocol/claude-agent-acp": "0.55.0",
+    "@automatalabs/codex-acp": "1.3.0",
     "typebox": "1.3.2",
-    "@automatalabs/shared-types": "0.4.0"
+    "@automatalabs/shared-types": "0.6.0"
   },
   "scripts": {
     "build": "tsc -b",