@automatalabs/acp-agents 0.7.0 → 0.8.0

package/README.md

@@ -45,7 +45,18 @@ try {
 }
 ```
 
-`run()` accepts the full `RunOptions` seam: `schema`, `model`, `tier`, `cwd`, `instructions`, `label`, `signal` (cancellation), `toolNames` / `disallowedToolNames`, `mcpServers`, `runId`, `baseInstructions` / `developerInstructions` (Codex-only, see below), `onUsage`, `onModelResolved`, `onModelFallback`, and `onHistory`. See `@automatalabs/shared-types` for the field-by-field contract.
+`run()` accepts the full `RunOptions` seam: `schema`, `model`, `tier`, `cwd`, `instructions`, `label`, `signal` (cancellation), `toolNames` / `disallowedToolNames`, `mcpServers`, `images` (see below), `runId`, `baseInstructions` / `developerInstructions` (Codex-only, see below), `onUsage`, `onModelResolved`, `onModelFallback`, and `onHistory`. See `@automatalabs/shared-types` for the field-by-field contract.
+
+### Image attachments (`images`)
+
+`images` appends base64 image `ContentBlock`s to the first prompt turn. The client adapts content to what the connected agent advertised at `initialize`: when the agent does not advertise `promptCapabilities.image`, each attachment degrades to a bracketed text note naming the mime type (never an error, never silently dropped). Repair/re-prompt turns stay text-only.
+
+```ts
+await runner.run("What's in this screenshot?", {
+  cwd: "/abs/path/to/worktree",
+  images: [{ data: base64Png, mimeType: "image/png" }],
+});
+```
 
 ### Codex session instructions (`baseInstructions` / `developerInstructions`)
 
@@ -65,6 +76,24 @@ await runner.run("Cut the release.", {
 });
 ```
 
+## Client-side fs / terminal handlers (`clientHandlers`)
+
+By default the agent uses its **own** built-in file and exec tools — the client never sees those operations. Register `clientHandlers` to interpose: the client then advertises exactly what you registered at `initialize` (`fs.readTextFile` / `fs.writeTextFile` per-method; `terminal` only when **all five** terminal methods are provided) and routes the agent's `fs/*` and `terminal/*` requests to your handlers. Every handler receives the request params plus an `AcpSessionContext` — `sessionId`, the session's **own** `cwd`, `label`, `runId` — so a pooled process serving many sessions still gets per-session isolation.
+
+**Confinement is your job.** The library routes requests and supplies the session context; enforcing worktree roots, resolving symlinks, scoping environment variables, bounding output, and applying timeouts belongs in your handler implementation. Requests for methods you did not register are rejected with a JSON-RPC method-not-found error (agents that respect the advertisement never send them).
+
+```ts
+const runner = createAcpRunner({
+  clientHandlers: {
+    fs: {
+      readTextFile: async ({ path }, { cwd }) => ({ content: await confinedRead(cwd, path) }),
+      writeTextFile: async ({ path, content }, { cwd }) => { await confinedWrite(cwd, path, content); },
+    },
+    // terminal: { createTerminal, terminalOutput, waitForTerminalExit, killTerminal, releaseTerminal },
+  },
+});
+```
+
 ## Listening in: live ACP events
 
 `AcpAgentRunner` is also a typed event bus — `runner.on(name, listener)` bubbles up the live ACP stream of every run (streaming text, tool calls, usage, permissions). Event names are the ACP `sessionUpdate` discriminants (`agent_message_chunk`, `tool_call`, `usage_update`, …) plus the cross-cutting `session_update` (catch-all), `permission_request`, `raw_message`, `session_open` / `session_close`, and `backend_error`. Each payload carries a `{ sessionId, backendId, label?, runId? }` context envelope (a pooled runner multiplexes many runs at once). `on()` / `once()` return an unsubscribe thunk; `off()` and `removeAllListeners()` round it out. Listeners are best-effort observers — a throwing listener never affects the run.
@@ -88,7 +117,9 @@ From [`src/index.ts`](./src/index.ts):
 - **`AcpAgentRunner`** — the `AgentRunner` implementation; `run(prompt, options)` and `dispose()`.
 - **`selectBackend({ model, tier }, registry?)`** — the cross-provider routing rule: which backend a spec maps to (registered custom names match first, exact or `name/<inner-model>`).
 - **`ClaudeBackend` / `CodexBackend`** — the two built-in backend strategies (spawn config + per-backend schema wiring).
-- **`CustomAcpBackend` / `resolveBackendRegistry` / `BACKENDS_ENV`** — the custom-backend registry: run **any** ACP agent as a named backend via `createAcpRunner({ backends: { name: { command, args?, env?, sessionMeta? } } })` or the `AGENTPRISM_BACKENDS` env var (JSON, same shape; the option wins per name; `claude`/`codex` reserved). Custom backends carry a `schema` as turn-level `_meta.outputSchema` and read the result off the final message as JSON.
+- **`CustomAcpBackend` / `resolveBackendRegistry` / `BACKENDS_ENV`** — the custom-backend registry: run **any** ACP agent as a named backend via `createAcpRunner({ backends: { name: { command, args?, env?, sessionMeta?, customCapabilities? } } })` or the `AGENTPRISM_BACKENDS` env var (JSON, same shape; the option wins per name; `claude`/`codex` reserved). Custom backends carry a `schema` as turn-level `_meta.outputSchema` and read the result off the final message as JSON. `customCapabilities: { namespace, gatedKeys }` declares the agent's `agentCapabilities._meta` negotiation contract: once the agent advertises that namespace, each declared bare `_meta` key is sent only when its same-named flag is `true` (no declaration = never gated).
+- **`clientCapabilitiesFor` + the `ClientHandlers` / `FsHandlers` / `TerminalHandlers` / `AcpSessionContext` types** — the client-side fs/terminal interposition surface (see above).
+- **`negotiateCapabilities` / `adaptPromptContent` / `gateCustomMeta` / `unsupportedMcpServer` + `NegotiatedCapabilities`** — the `initialize` capability-negotiation primitives; the negotiated record for a live connection is exposed on `PooledConnection.capabilities`.
 - **`toJsonSchema(schema)` / `toStrictJsonSchema(schema)`** — turn a typebox schema into the on-the-wire shapes: a plain JSON Schema for Claude `outputFormat`, and an OpenAI-strict-normalized schema for Codex `outputSchema`.
 
 Also exported: `AcpAgentPool` / `resolvePoolSize`, `PooledConnection` / `SessionHandle`, `decidePermission`, `UsageAccumulator`, `resolveStructuredOutput` / `extractValidated` / `findJsonBlock` / `validateValue`, `errorText` / `mapThrownError`, and the event surface `TypedEventEmitter` / `AcpRunnerEventMap` / `AcpEventName` / `AcpEventListener` / `AcpEventContext` / `AcpSessionUpdate` (+ the per-event payload types), plus their associated types.
@@ -98,7 +129,7 @@ Also exported: `AcpAgentPool` / `resolvePoolSize`, `PooledConnection` / `Session
 | Variable | Effect |
 | --- | --- |
 | `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_BACKENDS` | Custom ACP backends as JSON: `{"<name>": {"command": "…", "args": […], "env": {…}, "sessionMeta": {…}, "customCapabilities": {"namespace": "…", "gatedKeys": […]}}}`. |
 | `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. |

package/dist/acp-client.d.ts

@@ -1,4 +1,4 @@
-import { ClientSideConnection, type PromptResponse, type SessionConfigOption, type SessionNotification } from "@agentclientprotocol/sdk";
+import { ClientSideConnection, type ContentBlock, type PromptResponse, type SessionConfigOption, type SessionNotification } from "@agentclientprotocol/sdk";
 import type { TSchema } from "typebox";
 import { type AgentHistoryEntry, type McpServerConfig } from "@automatalabs/shared-types";
 import type { Backend, BackendId, StructuredSource } from "./backend.js";
@@ -6,6 +6,7 @@ import { type NegotiatedCapabilities } from "./capabilities.js";
 import { type AcpEventSink } from "./events.js";
 import { type ToolPolicy } from "./permissions.js";
 import { UsageAccumulator } from "./usage.js";
+import { type ClientHandlers } from "./client-handlers.js";
 interface RawResultSuccess {
     type: string;
     subtype: string;
@@ -14,6 +15,7 @@ interface RawResultSuccess {
 /** Per-session accumulator: assistant text, tool history, usage, the Claude raw structured_output,
  *  and the tool policy used to auto-answer permission requests for THIS session. */
 declare class SessionState {
+    readonly cwd: string;
     readonly policy: ToolPolicy;
     readonly label?: string | undefined;
     readonly runId?: string | undefined;
@@ -24,7 +26,7 @@ declare class SessionState {
     private turnStartIndex;
     /** `label`/`runId` are carried here ONLY so the MultiplexClient can stamp them onto emitted
      *  events as context — they never affect routing or the wire request. */
-    constructor(policy: ToolPolicy, label?: string | undefined, runId?: string | undefined);
+    constructor(cwd: string, policy: ToolPolicy, label?: string | undefined, runId?: string | undefined);
     /** Mark the start of a new turn so currentTurnText()/structured_output read only this turn. */
     beginTurn(): void;
     currentTurnText(): string;
@@ -61,6 +63,8 @@ export interface PooledConnectionDeps {
      *  session lifecycle change on this connection is bubbled up through it (additive observability;
      *  it is invoked AFTER the drain accumulation and never affects the run). */
     onEvent?: AcpEventSink;
+    /** Client-side ACP fs/terminal handlers advertised once and routed by sessionId. */
+    clientHandlers?: ClientHandlers;
 }
 /**
  * One long-lived ACP server subprocess + its held ACP client connection. Initialized ONCE and
@@ -76,6 +80,7 @@ export declare class PooledConnection {
     private readonly client;
     private readonly onDead;
     private readonly onEvent;
+    private readonly clientHandlers;
     /** Set true at the start of dispose() so the graceful-shutdown death is NOT reported as a crash. */
     private disposing;
     /** Resolves once `initialize` completed (or rejects if the process died first). */
@@ -98,8 +103,8 @@ export declare class PooledConnection {
     /** 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`. */
+    /** Drop the backend-declared 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;
@@ -117,9 +122,9 @@ export declare class PooledConnection {
     /** Best-effort ACP cancel for one session (wired to opts.signal). The PROCESS stays pooled. */
     cancelSession(sessionId: string): Promise<void>;
     /**
-     * Release a session: stop routing it, free the load slot, and best-effort session/close on the
-     * wire (capability-gated, bounded, never fatal). The PROCESS is NOT killed — it returns to the
-     * pool for the next agent() call.
+     * Release a session: move it to teardown-only routing, free the load slot, and best-effort
+     * session/close on the wire (capability-gated, bounded, never fatal). The PROCESS is NOT
+     * killed — it returns to the pool for the next agent() call.
      */
     releaseSession(sessionId: string): Promise<void>;
     /** Synchronous best-effort kill for a process-exit hook (no time to await a graceful close). */
@@ -180,7 +185,7 @@ export declare class SessionHandle implements StructuredSource {
     /** Set one session config option via the wire method and adopt the echoed catalog. */
     private applyConfigOption;
     /** Send a prompt turn and drain it; returns the final PromptResponse. */
-    prompt(text: string, promptMeta?: Record<string, unknown>): Promise<PromptResponse>;
+    prompt(content: string | ContentBlock[], promptMeta?: Record<string, unknown>): Promise<PromptResponse>;
     /** StructuredSource — the latest turn's assistant text. */
     currentTurnText(): string;
     /** StructuredSource — Claude's raw structured_output for the latest turn, if any. */

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

@@ -22,12 +22,13 @@
 // other sessions' updates interleave on the same wire.
 import { spawn } from "node:child_process";
 import { Readable, Writable } from "node:stream";
-import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION, } from "@agentclientprotocol/sdk";
+import { ClientSideConnection, CLIENT_METHODS, ndJsonStream, PROTOCOL_VERSION, RequestError, } from "@agentclientprotocol/sdk";
 import { META_KEYS, WorkflowError, WorkflowErrorCode, } from "@automatalabs/shared-types";
-import { gateCustomMeta, isSupportedProtocolVersion, negotiateCapabilities, unsupportedMcpServer, } from "./capabilities.js";
+import { adaptPromptContent, gateCustomMeta, isSupportedProtocolVersion, negotiateCapabilities, unsupportedMcpServer, } from "./capabilities.js";
 import { emitSessionUpdate } from "./events.js";
 import { decidePermission } from "./permissions.js";
 import { UsageAccumulator } from "./usage.js";
+import { clientCapabilitiesFor, } from "./client-handlers.js";
 /** A benign client identity. NOT JetBrains/IntelliJ 2026.1 — that exact identity makes
  *  codex-acp disable session config options (our model/effort routing channel). */
 const CLIENT_INFO = {
@@ -40,9 +41,11 @@ const CLAUDE_RAW_MESSAGE_METHOD = "_claude/sdkMessage";
 const CLOSE_SESSION_TIMEOUT_MS = 5_000;
 /** Bound the graceful SIGTERM shutdown before escalating to SIGKILL. */
 const DISPOSE_SIGKILL_GRACE_MS = 2_000;
+const TOMBSTONE_SESSION_CAP = 64;
 /** Per-session accumulator: assistant text, tool history, usage, the Claude raw structured_output,
  *  and the tool policy used to auto-answer permission requests for THIS session. */
 class SessionState {
+    cwd;
     policy;
     label;
     runId;
@@ -53,7 +56,8 @@ class SessionState {
     turnStartIndex = 0;
     /** `label`/`runId` are carried here ONLY so the MultiplexClient can stamp them onto emitted
      *  events as context — they never affect routing or the wire request. */
-    constructor(policy, label, runId) {
+    constructor(cwd, policy, label, runId) {
+        this.cwd = cwd;
         this.policy = policy;
         this.label = label;
         this.runId = runId;
@@ -113,25 +117,60 @@ class SessionState {
 class MultiplexClient {
     backendId;
     onEvent;
+    handlers;
     sessions = new Map();
+    /** Recently unregistered sessions kept ONLY for the teardown window: ACP agents may
+     *  legitimately release terminals (or finish fs/terminal cleanup) after this client releases
+     *  the session because session/close is cancel + free resources and the Agent owns terminal
+     *  release. Store only the slim routing context and cap it FIFO so the memory cost is bounded. */
+    tombstones = new Map();
     /** `backendId` stamps event context; `onEvent` (optional) bubbles every notification, permission
      *  request and session lifecycle change up to the runner's typed bus. */
-    constructor(backendId, onEvent) {
+    constructor(backendId, onEvent, handlers) {
         this.backendId = backendId;
         this.onEvent = onEvent;
+        this.handlers = handlers;
     }
     contextFor(sessionId, state) {
         return { sessionId, backendId: this.backendId, label: state?.label, runId: state?.runId };
     }
+    handlerContext(params) {
+        const state = this.sessions.get(params.sessionId);
+        if (state)
+            return { sessionId: params.sessionId, cwd: state.cwd, label: state.label, runId: state.runId };
+        const tombstone = this.tombstones.get(params.sessionId);
+        if (tombstone)
+            return { sessionId: params.sessionId, ...tombstone };
+        throw unknownSession(params.sessionId);
+    }
+    dispatch(params, wireMethod, handler) {
+        if (typeof handler !== "function")
+            throw methodNotAdvertised(wireMethod);
+        const ctx = this.handlerContext(params);
+        return handler(params, ctx);
+    }
     register(sessionId, state) {
+        this.tombstones.delete(sessionId);
         this.sessions.set(sessionId, state);
         this.onEvent?.("session_open", this.contextFor(sessionId, state));
     }
     unregister(sessionId) {
         const state = this.sessions.get(sessionId);
         this.sessions.delete(sessionId);
-        if (state)
+        if (state) {
+            this.tombstones.set(sessionId, {
+                cwd: state.cwd,
+                label: state.label,
+                runId: state.runId,
+            });
+            while (this.tombstones.size > TOMBSTONE_SESSION_CAP) {
+                const oldest = this.tombstones.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                this.tombstones.delete(oldest);
+            }
             this.onEvent?.("session_close", this.contextFor(sessionId, state));
+        }
     }
     requestPermission(params) {
         const state = this.sessions.get(params.sessionId);
@@ -146,6 +185,27 @@ class MultiplexClient {
         });
         return outcome;
     }
+    readTextFile(params) {
+        return this.dispatch(params, CLIENT_METHODS.fs_read_text_file, this.handlers?.fs?.readTextFile);
+    }
+    writeTextFile(params) {
+        return this.dispatch(params, CLIENT_METHODS.fs_write_text_file, this.handlers?.fs?.writeTextFile);
+    }
+    createTerminal(params) {
+        return this.dispatch(params, CLIENT_METHODS.terminal_create, this.handlers?.terminal?.createTerminal);
+    }
+    terminalOutput(params) {
+        return this.dispatch(params, CLIENT_METHODS.terminal_output, this.handlers?.terminal?.terminalOutput);
+    }
+    releaseTerminal(params) {
+        return this.dispatch(params, CLIENT_METHODS.terminal_release, this.handlers?.terminal?.releaseTerminal);
+    }
+    waitForTerminalExit(params) {
+        return this.dispatch(params, CLIENT_METHODS.terminal_wait_for_exit, this.handlers?.terminal?.waitForTerminalExit);
+    }
+    killTerminal(params) {
+        return this.dispatch(params, CLIENT_METHODS.terminal_kill, this.handlers?.terminal?.killTerminal);
+    }
     sessionUpdate(params) {
         const state = this.sessions.get(params.sessionId);
         // Fold into the accumulator FIRST (the drain contract), THEN bubble the event up unchanged.
@@ -172,6 +232,12 @@ class MultiplexClient {
         });
     }
 }
+function unknownSession(sessionId) {
+    return RequestError.invalidParams({ sessionId }, `unknown session: ${sessionId}`);
+}
+function methodNotAdvertised(method) {
+    return new RequestError(-32601, `${method} was not advertised by this client`, { method });
+}
 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. */
@@ -225,6 +291,7 @@ export class PooledConnection {
     client;
     onDead;
     onEvent;
+    clientHandlers;
     /** Set true at the start of dispose() so the graceful-shutdown death is NOT reported as a crash. */
     disposing = false;
     /** Resolves once `initialize` completed (or rejects if the process died first). */
@@ -243,7 +310,8 @@ export class PooledConnection {
         this.backendId = backend.id;
         this.onDead = deps.onDead;
         this.onEvent = deps.onEvent;
-        this.client = new MultiplexClient(this.backendId, this.onEvent);
+        this.clientHandlers = deps.clientHandlers;
+        this.client = new MultiplexClient(this.backendId, this.onEvent, deps.clientHandlers);
         const { command, args, env } = backend.spawnConfig();
         // NOTE: deliberately NO `cwd` here. cwd is per-SESSION (session/new), so one pooled process
         // serves runs in different worktrees without losing isolation.
@@ -296,10 +364,10 @@ export class PooledConnection {
     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`. */
+    /** Drop the backend-declared 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);
+        return gateCustomMeta(meta, this.negotiated?.customMetaSupport, this.negotiated?.gatedKeys);
     }
     /** Mark this connection dead exactly once, then ask the pool to evict it. Idempotent. */
     die(error) {
@@ -349,15 +417,14 @@ export class PooledConnection {
             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: {},
+                    // Truthful advertisement: computed from the consumer-provided handlers registered on
+                    // this runner. Omitted flags are unsupported; false flags are never sent deliberately.
+                    clientCapabilities: clientCapabilitiesFor(this.clientHandlers),
                     clientInfo: { ...CLIENT_INFO },
                 })),
                 deadline,
             ]);
-            const negotiated = negotiateCapabilities(response);
+            const negotiated = negotiateCapabilities(response, this.backend.customCapabilities);
             // 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
@@ -395,13 +462,13 @@ export class PooledConnection {
                 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);
+            const state = new SessionState(opts.cwd, 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. 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.
+            // is gated against the agent's advertised custom capabilities (a declared 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,
@@ -433,9 +500,9 @@ export class PooledConnection {
         }
     }
     /**
-     * Release a session: stop routing it, free the load slot, and best-effort session/close on the
-     * wire (capability-gated, bounded, never fatal). The PROCESS is NOT killed — it returns to the
-     * pool for the next agent() call.
+     * Release a session: move it to teardown-only routing, free the load slot, and best-effort
+     * session/close on the wire (capability-gated, bounded, never fatal). The PROCESS is NOT
+     * killed — it returns to the pool for the next agent() call.
      */
     async releaseSession(sessionId) {
         this.client.unregister(sessionId);
@@ -623,16 +690,18 @@ export class SessionHandle {
         this.configOptions = response.configOptions;
     }
     /** Send a prompt turn and drain it; returns the final PromptResponse. */
-    async prompt(text, promptMeta) {
+    async prompt(content, promptMeta) {
         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 prompt = typeof content === "string"
+            ? content
+            : adaptPromptContent(content, this.pooled.capabilities?.agent ?? {}, this.pooled.backendId);
+        // Gate the turn `_meta` against the agent's advertised custom capabilities: a declared
+        // turn-level key is dropped when the connected agent said it does not honor it.
         const gatedMeta = this.pooled.gateCustomMeta(promptMeta);
         const request = {
             sessionId: this.sessionId,
-            prompt,
+            prompt: typeof prompt === "string" ? [{ type: "text", text: prompt }] : prompt,
             ...(gatedMeta ? { _meta: gatedMeta } : {}),
         };
         const response = await this.pooled.race(this.pooled.rpc.prompt(request));

package/dist/backend.d.ts

@@ -37,6 +37,13 @@ export interface Backend {
      *  without the schema in the prompt, such an agent returns well-formed JSON with the WRONG
      *  KEYS and the repair ladder can never converge (it can fix prose, not unseen contracts). */
     readonly embedSchemaInPrompt?: boolean;
+    /** The agentCapabilities._meta namespace this backend's agent advertises under, and the bare
+     *  `_meta` keys gated by same-named boolean flags in that block; undefined = this backend has
+     *  no custom-capability contract (its custom `_meta`, if any, is never gated). */
+    readonly customCapabilities?: {
+        readonly namespace: string;
+        readonly gatedKeys: readonly string[];
+    };
     /** How to launch this backend's ACP server over stdio. */
     spawnConfig(): SpawnConfig;
     /** OPTIONAL backend-level `_meta` DEFAULTS for session/new (e.g. a custom registry entry's

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;;;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"}
+{"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;;sFAEkF;IAClF,QAAQ,CAAC,kBAAkB,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC;IACpG,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/codex.d.ts

@@ -2,6 +2,10 @@ import type { TSchema } from "typebox";
 import type { Backend, SessionMetaInputs, SpawnConfig, StructuredSource } from "../backend.js";
 export declare class CodexBackend implements Backend {
     readonly id: "codex";
+    readonly customCapabilities: {
+        readonly namespace: "@automatalabs/codex-acp";
+        readonly gatedKeys: readonly string[];
+    };
     spawnConfig(): SpawnConfig;
     sessionMeta(_schema: TSchema | undefined, inputs?: SessionMetaInputs): Record<string, unknown> | undefined;
     promptMeta(schema: TSchema | undefined): Record<string, unknown> | undefined;

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

@@ -1 +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,iBAAiB,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAO/F,qBAAa,YAAa,YAAW,OAAO;IAC1C,QAAQ,CAAC,EAAE,EAAG,OAAO,CAAU;IAE/B,WAAW,IAAI,WAAW;IAe1B,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,EAAE,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAY1G,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAK5E,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO;CAKpD"}
+{"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,iBAAiB,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAQ/F,qBAAa,YAAa,YAAW,OAAO;IAC1C,QAAQ,CAAC,EAAE,EAAG,OAAO,CAAU;IAC/B,QAAQ,CAAC,kBAAkB;;;MAGhB;IAEX,WAAW,IAAI,WAAW;IAe1B,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,EAAE,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAY1G,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAK5E,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO;CAKpD"}

package/dist/backends/codex.js

@@ -7,13 +7,18 @@
 // 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 { CODEX_META_KEYS, META_KEYS } from "@automatalabs/shared-types";
+import { CODEX_CUSTOM_CAPABILITY_NAMESPACE, CODEX_META_KEYS, META_KEYS } from "@automatalabs/shared-types";
 import { splitArgs } from "../backend.js";
+import { GATED_CUSTOM_META_KEYS } from "../capabilities.js";
 import { toStrictJsonSchema } from "../schema-strict.js";
 import { parseFinalJson } from "../structured-output.js";
 const require = createRequire(import.meta.url);
 export class CodexBackend {
     id = "codex";
+    customCapabilities = {
+        namespace: CODEX_CUSTOM_CAPABILITY_NAMESPACE,
+        gatedKeys: GATED_CUSTOM_META_KEYS,
+    };
     spawnConfig() {
         const env = process.env;
         const override = env.AGENTPRISM_CODEX_ACP_CMD;

package/dist/backends/custom.d.ts

@@ -11,6 +11,7 @@ export declare class CustomAcpBackend implements Backend {
      *  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. */
     readonly embedSchemaInPrompt = true;
+    readonly customCapabilities?: NonNullable<Backend["customCapabilities"]>;
     constructor(config: RegisteredBackend);
     spawnConfig(): SpawnConfig;
     sessionMetaDefaults(): Record<string, unknown> | undefined;

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

@@ -1 +1 @@
-{"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"}
+{"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;IAWlC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAVnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;mGAC+F;IAC/F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;oFAEgF;IAChF,QAAQ,CAAC,mBAAmB,QAAQ;IACpC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC;gBAE5C,MAAM,EAAE,iBAAiB;IAWtD,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

@@ -25,9 +25,12 @@ export class CustomAcpBackend {
      *  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. */
     embedSchemaInPrompt = true;
+    customCapabilities;
     constructor(config) {
         this.config = config;
         this.id = config.name;
+        if (config.customCapabilities)
+            this.customCapabilities = config.customCapabilities;
         const spawnIdentity = JSON.stringify({
             command: config.command,
             args: config.args ?? [],

package/dist/capabilities.d.ts

@@ -1,6 +1,7 @@
-import { type AgentCapabilities, type Implementation, type InitializeResponse } from "@agentclientprotocol/sdk";
+import { type AgentCapabilities, type ContentBlock, 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.
+import type { Backend } from "./backend.js";
+/** The bare `_meta` keys whose emission is gated by Codex'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). */
@@ -17,23 +18,33 @@ export interface NegotiatedCapabilities {
     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. */
+    /** The parsed backend-declared custom-capability block (the namespaced `_meta` object), or
+     *  undefined when the backend declared none or the agent did not advertise it — passthrough. */
     customMetaSupport: Record<string, unknown> | undefined;
+    /** The backend-declared bare `_meta` keys gated by customMetaSupport; undefined when this backend
+     *  has no custom-capability contract, so custom `_meta` is never gated. */
+    gatedKeys: readonly string[] | undefined;
 }
 /** Parse an initialize response into the connection's derived capability state. */
-export declare function negotiateCapabilities(response: InitializeResponse): NegotiatedCapabilities;
+export declare function negotiateCapabilities(response: InitializeResponse, customCapabilities?: Backend["customCapabilities"]): 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.
+/** Remove the declared 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;
+export declare function gateCustomMeta(meta: Record<string, unknown> | undefined, support: Record<string, unknown> | undefined, gatedKeys?: readonly string[]): Record<string, unknown> | undefined;
+/** Adapt prompt content to the agent's PromptCapabilities. ACP baseline content (text and
+ *  resource_link) is never gated; optional blocks follow the spec's capability table:
+ *  image->promptCapabilities.image, audio->promptCapabilities.audio, and resource->
+ *  promptCapabilities.embeddedContext. Unsupported optional blocks are represented as explicit
+ *  bracketed text notes so context is never silently lost. Returns the SAME array reference when
+ *  no block changes and never mutates the input or any surviving block. */
+export declare function adaptPromptContent(blocks: ContentBlock[], agent: AgentCapabilities, backendId: string): ContentBlock[];
 /** 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

package/dist/capabilities.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAkBA,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAQ5C;;;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;IACvD;+EAC2E;IAC3E,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC1C;AAED,mFAAmF;AACnF,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,kBAAkB,EAC5B,kBAAkB,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,GACjD,sBAAsB,CAYxB;AAaD;;;;+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,EAC5C,SAAS,GAAE,SAAS,MAAM,EAA2B,GACpD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAWrC;AAED;;;;;2EAK2E;AAC3E,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EAAE,EACtB,KAAK,EAAE,iBAAiB,EACxB,SAAS,EAAE,MAAM,GAChB,YAAY,EAAE,CAchB;AAkCD;;;;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

@@ -1,21 +1,29 @@
 // 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).
+// after its ONE-TIME `initialize` handshake. Parses the InitializeResponse + the backend's optional
+// custom-capability declaration into: the agent's chosen protocolVersion (validated against what this
+// client speaks), its full advertised agentCapabilities + agentInfo, whether session/close is
+// supported, and the declared custom-capability advertisement (the namespaced `_meta` block gating
+// which backend-declared bare `_meta` inputs the client may send). The negotiated record is a pure
+// parse of (response + declaration): `gatedKeys` captures the declaration at handshake time, and
+// PooledConnection gates against that captured list.
 //
-// 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.
+// GATING PHILOSOPHY — backend-declared and lenient for legacy agents. A backend with NO declaration
+// has NO custom-capability contract: its custom `_meta`, if any, is never gated, even when the agent
+// advertises some other backend's namespace. Once a backend declares a namespace + bare keys, an
+// agent that advertises NO usable namespace block is legacy passthrough (every declared key still
+// sent); malformed namespace values (non-object or arrays) are treated as not advertised. Only once
+// an agent DOES advertise the declared namespace object is each declared bare key gated on its
+// same-named flag === true. Symmetrically, only once an agent advertises mcpCapabilities is an
+// unsupported MCP transport rejected. Truthfully-advertised absence still gates 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.
+import { CODEX_META_KEYS, META_KEYS, } from "@automatalabs/shared-types";
+const PROMPT_CAPABILITY_BY_BLOCK_KIND = {
+    image: "image",
+    audio: "audio",
+    resource: "embeddedContext",
+};
+/** The bare `_meta` keys whose emission is gated by Codex'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). */
@@ -25,20 +33,23 @@ export const GATED_CUSTOM_META_KEYS = [
     CODEX_META_KEYS.developerInstructions,
 ];
 /** Parse an initialize response into the connection's derived capability state. */
-export function negotiateCapabilities(response) {
+export function negotiateCapabilities(response, customCapabilities) {
     const agent = response.agentCapabilities ?? {};
     return {
         protocolVersion: response.protocolVersion,
         agent,
         agentInfo: response.agentInfo ?? undefined,
         supportsClose: Boolean(agent.sessionCapabilities?.close),
-        customMetaSupport: readCustomNamespace(agent._meta),
+        customMetaSupport: customCapabilities
+            ? readCustomNamespace(agent._meta, customCapabilities.namespace)
+            : undefined,
+        gatedKeys: customCapabilities ? [...customCapabilities.gatedKeys] : undefined,
     };
 }
-function readCustomNamespace(meta) {
+function readCustomNamespace(meta, namespace) {
     if (!meta || typeof meta !== "object")
         return undefined;
-    const block = meta[CODEX_CUSTOM_CAPABILITY_NAMESPACE];
+    const block = meta[namespace];
     return block && typeof block === "object" && !Array.isArray(block)
         ? block
         : undefined;
@@ -51,15 +62,15 @@ function readCustomNamespace(meta) {
 export function isSupportedProtocolVersion(version) {
     return version === PROTOCOL_VERSION;
 }
-/** Remove the fork's custom bare `_meta` keys the connected agent did NOT advertise support for.
+/** Remove the declared 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) {
+export function gateCustomMeta(meta, support, gatedKeys = GATED_CUSTOM_META_KEYS) {
     if (!meta || !support)
         return meta;
     let gated;
-    for (const key of GATED_CUSTOM_META_KEYS) {
+    for (const key of gatedKeys) {
         if (key in meta && support[key] !== true) {
             gated ??= { ...meta };
             delete gated[key];
@@ -68,6 +79,53 @@ export function gateCustomMeta(meta, support) {
     const result = gated ?? meta;
     return Object.keys(result).length > 0 ? result : undefined;
 }
+/** Adapt prompt content to the agent's PromptCapabilities. ACP baseline content (text and
+ *  resource_link) is never gated; optional blocks follow the spec's capability table:
+ *  image->promptCapabilities.image, audio->promptCapabilities.audio, and resource->
+ *  promptCapabilities.embeddedContext. Unsupported optional blocks are represented as explicit
+ *  bracketed text notes so context is never silently lost. Returns the SAME array reference when
+ *  no block changes and never mutates the input or any surviving block. */
+export function adaptPromptContent(blocks, agent, backendId) {
+    let adapted;
+    for (let i = 0; i < blocks.length; i += 1) {
+        const block = blocks[i];
+        const replacement = unsupportedPromptBlockNote(block, agent, backendId);
+        if (replacement) {
+            adapted ??= blocks.slice(0, i);
+            adapted.push(replacement);
+        }
+        else if (adapted) {
+            adapted.push(block);
+        }
+    }
+    return adapted ?? blocks;
+}
+function unsupportedPromptBlockNote(block, agent, backendId) {
+    const capability = PROMPT_CAPABILITY_BY_BLOCK_KIND[block.type];
+    if (!capability || agent.promptCapabilities?.[capability] === true)
+        return undefined;
+    switch (block.type) {
+        case "image": {
+            const uriSuffix = typeof block.uri === "string" && block.uri.length > 0 ? `; uri=${block.uri}` : "";
+            return {
+                type: "text",
+                text: `[image omitted: ${block.mimeType}${uriSuffix} — the ${backendId} agent does not advertise promptCapabilities.image]`,
+            };
+        }
+        case "audio":
+            return {
+                type: "text",
+                text: `[audio omitted: ${block.mimeType} — the ${backendId} agent does not advertise promptCapabilities.audio]`,
+            };
+        case "resource":
+            return {
+                type: "text",
+                text: `[resource omitted: uri=${block.resource.uri} — the ${backendId} agent does not advertise promptCapabilities.embeddedContext]`,
+            };
+        default:
+            return 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

package/dist/client-handlers.d.ts

@@ -0,0 +1,27 @@
+import type { ClientCapabilities, CreateTerminalRequest, CreateTerminalResponse, KillTerminalRequest, KillTerminalResponse, ReadTextFileRequest, ReadTextFileResponse, ReleaseTerminalRequest, ReleaseTerminalResponse, TerminalOutputRequest, TerminalOutputResponse, WaitForTerminalExitRequest, WaitForTerminalExitResponse, WriteTextFileRequest, WriteTextFileResponse } from "@agentclientprotocol/sdk";
+export interface AcpSessionContext {
+    readonly sessionId: string;
+    readonly cwd: string;
+    readonly label?: string;
+    readonly runId?: string;
+}
+export interface FsHandlers {
+    readTextFile?(params: ReadTextFileRequest, ctx: AcpSessionContext): Promise<ReadTextFileResponse> | ReadTextFileResponse;
+    writeTextFile?(params: WriteTextFileRequest, ctx: AcpSessionContext): Promise<WriteTextFileResponse | void> | WriteTextFileResponse | void;
+}
+export interface TerminalHandlers {
+    createTerminal(params: CreateTerminalRequest, ctx: AcpSessionContext): Promise<CreateTerminalResponse> | CreateTerminalResponse;
+    terminalOutput(params: TerminalOutputRequest, ctx: AcpSessionContext): Promise<TerminalOutputResponse> | TerminalOutputResponse;
+    waitForTerminalExit(params: WaitForTerminalExitRequest, ctx: AcpSessionContext): Promise<WaitForTerminalExitResponse> | WaitForTerminalExitResponse;
+    killTerminal(params: KillTerminalRequest, ctx: AcpSessionContext): Promise<KillTerminalResponse | void> | KillTerminalResponse | void;
+    releaseTerminal(params: ReleaseTerminalRequest, ctx: AcpSessionContext): Promise<ReleaseTerminalResponse | void> | ReleaseTerminalResponse | void;
+}
+export interface ClientHandlers {
+    fs?: FsHandlers;
+    terminal?: TerminalHandlers;
+}
+/** The client capability advertisement derived solely from registered consumer handlers. */
+export declare function clientCapabilitiesFor(handlers: ClientHandlers | undefined): ClientCapabilities;
+/** Fail-fast validation for JavaScript consumers bypassing the TerminalHandlers type. */
+export declare function validateClientHandlers(handlers: ClientHandlers | undefined): void;
+//# sourceMappingURL=client-handlers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client-handlers.d.ts","sourceRoot":"","sources":["../src/client-handlers.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,EACtB,0BAA0B,EAC1B,2BAA2B,EAC3B,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,CAAC,CACX,MAAM,EAAE,mBAAmB,EAC3B,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,oBAAoB,CAAC,GAAG,oBAAoB,CAAC;IACxD,aAAa,CAAC,CACZ,MAAM,EAAE,oBAAoB,EAC5B,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,GAAG,qBAAqB,GAAG,IAAI,CAAC;CACzE;AAED,MAAM,WAAW,gBAAgB;IAC/B,cAAc,CACZ,MAAM,EAAE,qBAAqB,EAC7B,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,sBAAsB,CAAC,GAAG,sBAAsB,CAAC;IAC5D,cAAc,CACZ,MAAM,EAAE,qBAAqB,EAC7B,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,sBAAsB,CAAC,GAAG,sBAAsB,CAAC;IAC5D,mBAAmB,CACjB,MAAM,EAAE,0BAA0B,EAClC,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,2BAA2B,CAAC,GAAG,2BAA2B,CAAC;IACtE,YAAY,CACV,MAAM,EAAE,mBAAmB,EAC3B,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,GAAG,oBAAoB,GAAG,IAAI,CAAC;IACtE,eAAe,CACb,MAAM,EAAE,sBAAsB,EAC9B,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,GAAG,uBAAuB,GAAG,IAAI,CAAC;CAC7E;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,CAAC,EAAE,UAAU,CAAC;IAChB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CAC7B;AAUD,4FAA4F;AAC5F,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,GAAG,kBAAkB,CAY9F;AAED,yFAAyF;AACzF,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,GAAG,IAAI,CAMjF"}

package/dist/client-handlers.js

@@ -0,0 +1,39 @@
+const TERMINAL_HANDLER_METHODS = [
+    "createTerminal",
+    "terminalOutput",
+    "waitForTerminalExit",
+    "killTerminal",
+    "releaseTerminal",
+];
+/** The client capability advertisement derived solely from registered consumer handlers. */
+export function clientCapabilitiesFor(handlers) {
+    if (!handlers)
+        return {};
+    const capabilities = {};
+    const fs = handlers.fs;
+    const fsCapabilities = {};
+    if (typeof fs?.readTextFile === "function")
+        fsCapabilities.readTextFile = true;
+    if (typeof fs?.writeTextFile === "function")
+        fsCapabilities.writeTextFile = true;
+    if (Object.keys(fsCapabilities).length > 0)
+        capabilities.fs = fsCapabilities;
+    if (hasFullTerminalHandlers(handlers.terminal))
+        capabilities.terminal = true;
+    return capabilities;
+}
+/** Fail-fast validation for JavaScript consumers bypassing the TerminalHandlers type. */
+export function validateClientHandlers(handlers) {
+    if (!handlers?.terminal)
+        return;
+    const missing = missingTerminalMethods(handlers.terminal);
+    if (missing.length > 0) {
+        throw new Error(`clientHandlers.terminal missing required methods: ${missing.join(", ")}`);
+    }
+}
+function hasFullTerminalHandlers(terminal) {
+    return Boolean(terminal && missingTerminalMethods(terminal).length === 0);
+}
+function missingTerminalMethods(terminal) {
+    return TERMINAL_HANDLER_METHODS.filter((method) => typeof terminal[method] !== "function");
+}

package/dist/index.d.ts

@@ -4,10 +4,12 @@ export { BACKENDS_ENV, registryWithRunBackends, resolveBackendRegistry } from ".
 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 { GATED_CUSTOM_META_KEYS, adaptPromptContent, 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 { clientCapabilitiesFor } from "./client-handlers.js";
+export type { AcpSessionContext, ClientHandlers, FsHandlers, TerminalHandlers } from "./client-handlers.js";
 export { TypedEventEmitter, emitSessionUpdate } from "./events.js";
 export type { AcpRunnerEventMap, AcpEventName, AcpEventListener, AcpEventContext, AcpEventSink, AcpSessionUpdate, AcpUpdateKind, AcpPermissionEvent, AcpRawMessageEvent, AcpBackendErrorEvent, } from "./events.js";
 export type { Backend, BackendId, BuiltinBackendId, SessionMetaInputs, SpawnConfig, StructuredSource, } from "./backend.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,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"}
+{"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,kBAAkB,EAClB,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;AAI7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG5G,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

@@ -10,8 +10,11 @@ export { BACKENDS_ENV, registryWithRunBackends, resolveBackendRegistry } from ".
 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 { GATED_CUSTOM_META_KEYS, adaptPromptContent, gateCustomMeta, isSupportedProtocolVersion, negotiateCapabilities, unsupportedMcpServer, } from "./capabilities.js";
 export { AcpAgentPool, resolvePoolSize } from "./pool.js";
+// Consumer-provided client-side ACP handlers: fs/terminal routing plus truthful initialize
+// clientCapabilities derived from the registered handler set.
+export { clientCapabilitiesFor } from "./client-handlers.js";
 // The typed ACP event bus surfaced on AcpAgentRunner (`runner.on(name, evt => …)`).
 export { TypedEventEmitter, emitSessionUpdate } from "./events.js";
 export { ClaudeBackend } from "./backends/claude.js";

package/dist/pool.d.ts

@@ -1,9 +1,12 @@
 import type { Backend } from "./backend.js";
 import { SessionHandle, type AcpSessionOptions } from "./acp-client.js";
+import { type ClientHandlers } from "./client-handlers.js";
 import type { AcpEventSink } from "./events.js";
 export interface AcpPoolOptions {
     /** Long-lived processes to keep PER backend. Default 1; falls back to AGENTPRISM_ACP_POOL_SIZE. */
     size?: number;
+    /** Client-side ACP fs/terminal handlers advertised at initialize and routed per session. */
+    clientHandlers?: ClientHandlers;
 }
 /** Internal wiring the runner injects (NOT part of the public AcpPoolOptions surface): the typed
  *  event sink forwarded to every PooledConnection so ACP events bubble up to `runner.on(...)`. */
@@ -15,6 +18,7 @@ export declare function resolvePoolSize(option?: number): number;
 export declare class AcpAgentPool {
     private readonly deps;
     private readonly size;
+    private readonly clientHandlers;
     private readonly byBackend;
     private readonly onProcessExit;
     private exitHookInstalled;

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;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"}
+{"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,EAA0B,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACnF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAKhD,MAAM,WAAW,cAAc;IAC7B,mGAAmG;IACnG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4FAA4F;IAC5F,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;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;IAUrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IATvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAC5D,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;IAOzC,8FAA8F;IACxF,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC;IAMhF;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAyBxB,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

@@ -1,4 +1,5 @@
 import { PooledConnection } from "./acp-client.js";
+import { validateClientHandlers } from "./client-handlers.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. */
@@ -17,13 +18,16 @@ export function resolvePoolSize(option) {
 export class AcpAgentPool {
     deps;
     size;
+    clientHandlers;
     byBackend = new Map();
     onProcessExit = () => this.killAllSync();
     exitHookInstalled = false;
     disposed = false;
     constructor(options = {}, deps = {}) {
         this.deps = deps;
+        validateClientHandlers(options.clientHandlers);
         this.size = resolvePoolSize(options.size);
+        this.clientHandlers = options.clientHandlers;
     }
     /** Acquire a session for one agent() run: get/grow a pooled connection and open a session. */
     async acquire(backend, opts) {
@@ -51,6 +55,7 @@ export class AcpAgentPool {
             const connection = PooledConnection.create(backend, {
                 onDead: (dead) => this.drop(key, dead),
                 onEvent: this.deps.onEvent,
+                clientHandlers: this.clientHandlers,
             });
             connections.push(connection);
             return connection;

package/dist/registry.d.ts

@@ -10,6 +10,12 @@ export interface CustomBackendConfig {
     /** Static `_meta` sent on every session/new for this backend (backend-level defaults).
      *  Per-call RunOptions.meta merges over these; backend-computed keys win over both. */
     sessionMeta?: Record<string, unknown>;
+    /** agentCapabilities._meta namespace + bare `_meta` keys this custom agent negotiates.
+     *  Undefined means the backend's custom `_meta`, if any, is never gated. */
+    customCapabilities?: {
+        readonly namespace: string;
+        readonly gatedKeys: readonly string[];
+    };
 }
 /** A validated registry entry: the (lowercased) name plus its config. */
 export interface RegisteredBackend extends CustomBackendConfig {

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;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,eAAe,EACrB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,GACxC,eAAe,CAQjB"}
+{"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;IACtC;gFAC4E;IAC5E,kBAAkB,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC;CAC5F;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

@@ -81,6 +81,7 @@ function validateEntry(rawName, config, source) {
     if (c.sessionMeta !== undefined && (c.sessionMeta === null || typeof c.sessionMeta !== "object" || Array.isArray(c.sessionMeta))) {
         throw new Error(`${source}: backend "${rawName}" "sessionMeta" must be an object`);
     }
+    const customCapabilities = validateCustomCapabilities(c.customCapabilities, source, rawName);
     return [
         name,
         {
@@ -89,9 +90,27 @@ function validateEntry(rawName, config, source) {
             ...(c.args !== undefined ? { args: c.args } : {}),
             ...(c.env !== undefined ? { env: c.env } : {}),
             ...(c.sessionMeta !== undefined ? { sessionMeta: c.sessionMeta } : {}),
+            ...(customCapabilities !== undefined ? { customCapabilities } : {}),
         },
     ];
 }
+function validateCustomCapabilities(value, source, rawName) {
+    if (value === undefined)
+        return undefined;
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${source}: backend "${rawName}" "customCapabilities" must be an object`);
+    }
+    const c = value;
+    if (typeof c.namespace !== "string" || c.namespace.trim() === "") {
+        throw new Error(`${source}: backend "${rawName}" "customCapabilities.namespace" must be a non-empty string`);
+    }
+    if (!Array.isArray(c.gatedKeys) ||
+        c.gatedKeys.length === 0 ||
+        !c.gatedKeys.every((key) => typeof key === "string" && key.trim() !== "")) {
+        throw new Error(`${source}: backend "${rawName}" "customCapabilities.gatedKeys" must be a non-empty array of non-empty strings`);
+    }
+    return { namespace: c.namespace, gatedKeys: [...c.gatedKeys] };
+}
 function isStringRecord(value) {
     return (value !== null &&
         typeof value === "object" &&

package/dist/runner.d.ts

@@ -4,8 +4,8 @@ import { type AcpPoolOptions } from "./pool.js";
 import { type AcpEventListener, type AcpEventName } from "./events.js";
 import type { Backend } from "./backend.js";
 import { type BackendRegistry, type CustomBackendConfig } from "./registry.js";
-/** Constructor options for the runner: pool sizing PLUS the custom-backend registry.
- *  `backends` merges over (and wins against) env-declared AGENTPRISM_BACKENDS entries. */
+/** Constructor options for the runner: pool sizing, client-side handlers, and the custom-backend
+ *  registry. `backends` merges over (and wins against) env-declared AGENTPRISM_BACKENDS entries. */
 export interface AcpRunnerOptions extends AcpPoolOptions {
     /** Custom ACP backends, keyed by registered name (see registry.ts for the config shape
      *  and the routing rules). Names are case-insensitive; "claude"/"codex" are reserved. */

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,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"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAkBA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,WAAW,EAEhB,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;oGACoG;AACpG,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;IA8G1B;qGACiG;IAC3F,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAI/B;AAED;;;qDAGqD;AACrD,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,cAAc,CAE1E;AA2HD;;;;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

@@ -82,6 +82,7 @@ export class AcpAgentRunner {
         const backend = selectBackend(opts, registry);
         const policy = { allow: opts.toolNames, deny: opts.disallowedToolNames };
         const cwd = opts.cwd ?? process.cwd();
+        validatePromptImages(opts.images, opts.label);
         const session = await this.pool.acquire(backend, {
             cwd,
             schema,
@@ -107,10 +108,11 @@ export class AcpAgentRunner {
             // full spec unchanged (their catalogs match provider-prefixed and bare ids).
             await applyModelSelection(session, innerModelSpec(opts.model ?? opts.tier, backend), opts);
             const text = buildPrompt(prompt, opts, schema, backend);
+            const initialPrompt = opts.images && opts.images.length > 0 ? promptWithImages(text, opts.images) : text;
             // Generic turn-scoped _meta passthrough merged UNDER the backend-computed keys (e.g. the
             // outputSchema forward when a schema is set) — user meta never clobbers the schema channel.
             const promptMeta = mergeTurnMeta(opts.promptMeta, backend.promptMeta(schema));
-            const response = await session.prompt(text, promptMeta);
+            const response = await session.prompt(initialPrompt, promptMeta);
             opts.signal?.throwIfAborted();
             // Inspect the turn's stop reason BEFORE the text/schema path: a refusal or truncation
             // must surface distinctly here, never be misread as empty output or burned through the
@@ -257,6 +259,31 @@ function buildPrompt(prompt, opts, schema, backend) {
     }
     return parts.join("\n\n");
 }
+function validatePromptImages(images, label) {
+    if (!images || images.length === 0)
+        return;
+    for (let i = 0; i < images.length; i += 1) {
+        const image = images[i];
+        if (typeof image?.data !== "string" || image.data.trim() === "") {
+            throw new WorkflowError(`images[${i}].data must be a non-empty string`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: label });
+        }
+        if (typeof image.mimeType !== "string" || image.mimeType.trim() === "") {
+            throw new WorkflowError(`images[${i}].mimeType must be a non-empty string`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: label });
+        }
+        if (image.uri !== undefined && (typeof image.uri !== "string" || image.uri.trim() === "")) {
+            throw new WorkflowError(`images[${i}].uri must be a non-empty string when present`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: label });
+        }
+    }
+}
+function promptWithImages(text, images) {
+    const blocks = [{ type: "text", text }];
+    for (const image of images) {
+        blocks.push(image.uri === undefined
+            ? { type: "image", data: image.data, mimeType: image.mimeType }
+            : { type: "image", data: image.data, mimeType: image.mimeType, uri: image.uri });
+    }
+    return blocks;
+}
 /** Pick the backend by model/tier. Cross-provider routing = which ACP server to spawn.
  *  Registered CUSTOM names resolve FIRST (exact name, or `name/<inner-model>` prefix) so a
  *  registry entry is never shadowed by the built-in heuristics; then the claude/codex

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automatalabs/acp-agents",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
     "@agentclientprotocol/claude-agent-acp": "0.55.0",
     "@automatalabs/codex-acp": "1.3.0",
     "typebox": "1.3.2",
-    "@automatalabs/shared-types": "0.6.0"
+    "@automatalabs/shared-types": "0.7.0"
   },
   "scripts": {
     "build": "tsc -b",