@automatalabs/acp-agents 0.4.1 → 0.5.1

package/README.md

@@ -86,8 +86,9 @@ From [`src/index.ts`](./src/index.ts):
 
 - **`createAcpRunner(options?)`** — factory returning an `AcpAgentRunner` (this is what `@automatalabs/workflows` injects into the engine).
 - **`AcpAgentRunner`** — the `AgentRunner` implementation; `run(prompt, options)` and `dispose()`.
-- **`selectBackend({ model, tier })`** — the cross-provider routing rule: which backend a spec maps to.
-- **`ClaudeBackend` / `CodexBackend`** — the two backend strategies (spawn config + per-backend schema wiring).
+- **`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.
 - **`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.
@@ -96,7 +97,8 @@ Also exported: `AcpAgentPool` / `resolvePoolSize`, `PooledConnection` / `Session
 
 | Variable | Effect |
 | --- | --- |
-| `AGENTPRISM_DEFAULT_BACKEND` | Backend when `model`/`tier` don't pick one (`codex` selects Codex; anything else is Claude). |
+| `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_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

@@ -39,6 +39,10 @@ export interface AcpSessionOptions {
     signal?: AbortSignal;
     /** Client-provided MCP servers to attach at session/new. Omitted => `[]` (the default). */
     mcpServers?: McpServerConfig[];
+    /** Generic session-scoped `_meta` passthrough (RunOptions.meta). Merged FIRST, under the
+     *  backend-computed `_meta` and the runId stamp, so user keys never clobber the schema /
+     *  correlation channels. Omitted => the request `_meta` is whatever the backend set. */
+    meta?: Record<string, unknown>;
     /** Engine run id, stamped onto session/new `_meta` (META_KEYS.runId) as a correlation id.
      *  Omitted => no runId `_meta` is stamped (the request `_meta` is whatever the backend set). */
     runId?: string;

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

@@ -171,6 +171,14 @@ class MultiplexClient {
         });
     }
 }
+/** 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) {
+    const present = layers.filter((l) => Boolean(l && Object.keys(l).length > 0));
+    if (present.length === 0)
+        return undefined;
+    return Object.assign({}, ...present);
+}
 /** Merge the engine runId correlation stamp into a backend's session/new `_meta`. Returns the
  *  meta unchanged when no runId is given (so a backend that sends no `_meta` keeps sending none). */
 function stampRunId(meta, runId) {
@@ -316,12 +324,15 @@ export class PooledConnection {
         try {
             await this.ready;
             const state = new SessionState(opts.policy, opts.label, opts.runId);
-            // The backend's vendor `_meta` (Claude schema channel; Codex base/developer instructions)
-            // plus the optional engine runId correlation stamp. When none is present, no `_meta` is sent.
-            const meta = stampRunId(this.backend.sessionMeta(opts.schema, {
+            // 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, {
                 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.

package/dist/backend.d.ts

@@ -1,5 +1,9 @@
 import type { TSchema } from "typebox";
-export type BackendId = "claude" | "codex";
+/** The two built-in backends. Custom registry backends extend the id space beyond these. */
+export type BuiltinBackendId = "claude" | "codex";
+/** A backend id: one of the built-ins, or the registered name of a custom ACP backend
+ *  (see registry.ts). The pool keys connections by this id, so ids must be stable. */
+export type BackendId = string;
 export interface SpawnConfig {
     command: string;
     args: string[];
@@ -22,11 +26,22 @@ export interface SessionMetaInputs {
 }
 export interface Backend {
     readonly id: BackendId;
+    /** 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 —
+     *  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;
     /** How to launch this backend's ACP server over stdio. */
     spawnConfig(): SpawnConfig;
-    /** `_meta` for session/new (undefined when this backend carries nothing there). `inputs`
-     *  carries optional per-session extras (e.g. Codex base/developer instructions); a backend
-     *  that has no use for them ignores it. */
+    /** OPTIONAL backend-level `_meta` DEFAULTS for session/new (e.g. a custom registry entry's
+     *  static `sessionMeta`). Lowest precedence: per-call RunOptions.meta merges OVER these,
+     *  and sessionMeta()'s protocol-critical keys merge over both. */
+    sessionMetaDefaults?(): Record<string, unknown> | undefined;
+    /** PROTOCOL-CRITICAL `_meta` for session/new (undefined when this backend carries nothing
+     *  there) — e.g. the Claude schema channel. Highest precedence below the runId stamp: these
+     *  keys win over the generic user passthrough. `inputs` carries optional per-session extras
+     *  (e.g. Codex base/developer instructions); a backend that has no use for them ignores it. */
     sessionMeta(schema: TSchema | undefined, inputs?: SessionMetaInputs): Record<string, unknown> | undefined;
     /** `_meta` for session/prompt (undefined when this backend carries the schema at session/new). */
     promptMeta(schema: TSchema | undefined): Record<string, unknown> | undefined;

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,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE3C,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,0DAA0D;IAC1D,WAAW,IAAI,WAAW,CAAC;IAC3B;;+CAE2C;IAC3C,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;;;;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/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;CAoBpD"}
+{"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"}

package/dist/backends/codex.js

@@ -10,7 +10,7 @@ import { createRequire } from "node:module";
 import { CODEX_META_KEYS, META_KEYS } from "@automatalabs/shared-types";
 import { splitArgs } from "../backend.js";
 import { toStrictJsonSchema } from "../schema-strict.js";
-import { findJsonBlock } from "../structured-output.js";
+import { parseFinalJson } from "../structured-output.js";
 const require = createRequire(import.meta.url);
 export class CodexBackend {
     id = "codex";
@@ -46,26 +46,8 @@ export class CodexBackend {
         return { [META_KEYS.outputSchema]: toStrictJsonSchema(schema) };
     }
     nativeStructured(source) {
-        const text = source.currentTurnText().trim();
-        if (!text)
-            return undefined;
-        // The constrained final message is pure JSON; parse it directly, then fall back to a
-        // balanced-block extraction if the turn also emitted leading prose.
-        try {
-            return JSON.parse(text);
-        }
-        catch {
-            // fall through to block extraction
-        }
-        const block = findJsonBlock(text);
-        if (block !== undefined) {
-            try {
-                return JSON.parse(block);
-            }
-            catch {
-                // give up; the runner's ladder will re-prompt / extract.
-            }
-        }
-        return undefined;
+        // The constrained final message is pure JSON; parse it directly, with a balanced-block
+        // fallback if the turn also emitted leading prose.
+        return parseFinalJson(source.currentTurnText());
     }
 }

package/dist/backends/custom.d.ts

@@ -0,0 +1,18 @@
+import type { TSchema } from "typebox";
+import type { Backend, SpawnConfig, StructuredSource } from "../backend.js";
+import type { RegisteredBackend } from "../registry.js";
+export declare class CustomAcpBackend implements Backend {
+    private readonly config;
+    readonly id: 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. */
+    readonly embedSchemaInPrompt = true;
+    constructor(config: RegisteredBackend);
+    spawnConfig(): SpawnConfig;
+    sessionMetaDefaults(): Record<string, unknown> | undefined;
+    sessionMeta(_schema: TSchema | undefined): Record<string, unknown> | undefined;
+    promptMeta(schema: TSchema | undefined): Record<string, unknown> | undefined;
+    nativeStructured(source: StructuredSource): unknown;
+}
+//# sourceMappingURL=custom.d.ts.map

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

@@ -0,0 +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"}

package/dist/backends/custom.js

@@ -0,0 +1,47 @@
+import { META_KEYS } from "@automatalabs/shared-types";
+import { toJsonSchema } from "../schema-strict.js";
+import { parseFinalJson } from "../structured-output.js";
+export class CustomAcpBackend {
+    config;
+    id;
+    /** 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. */
+    embedSchemaInPrompt = true;
+    constructor(config) {
+        this.config = config;
+        this.id = config.name;
+    }
+    spawnConfig() {
+        return {
+            command: this.config.command,
+            args: [...(this.config.args ?? [])],
+            // Registry-declared env merges OVER the inherited environment.
+            env: { ...process.env, ...(this.config.env ?? {}) },
+        };
+    }
+    sessionMetaDefaults() {
+        // The registry entry's static `_meta` — DEFAULTS, so per-call RunOptions.meta overrides
+        // them. Return a copy so callers can merge without mutating config.
+        const staticMeta = this.config.sessionMeta;
+        if (!staticMeta || Object.keys(staticMeta).length === 0)
+            return undefined;
+        return { ...staticMeta };
+    }
+    sessionMeta(_schema) {
+        // The schema rides the turn (see promptMeta); a custom backend has no protocol-critical
+        // session/new `_meta` of its own.
+        return undefined;
+    }
+    promptMeta(schema) {
+        if (!schema)
+            return undefined;
+        // Plain JSON Schema (NOT OpenAI-strict-normalized — strictness is a Codex/Responses-API
+        // constraint, not part of the generic dialect). Agents that ignore it are repaired by the
+        // runner's ladder.
+        return { [META_KEYS.outputSchema]: toJsonSchema(schema) };
+    }
+    nativeStructured(source) {
+        return parseFinalJson(source.currentTurnText());
+    }
+}

package/dist/index.d.ts

@@ -1,18 +1,22 @@
 export { AcpAgentRunner, createAcpRunner, selectBackend } from "./runner.js";
+export type { AcpRunnerOptions } from "./runner.js";
+export { BACKENDS_ENV, 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 { AcpAgentPool, resolvePoolSize } from "./pool.js";
 export type { AcpPoolOptions, AcpPoolDeps } from "./pool.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, SessionMetaInputs, SpawnConfig, StructuredSource } from "./backend.js";
+export type { Backend, BackendId, BuiltinBackendId, SessionMetaInputs, SpawnConfig, StructuredSource, } from "./backend.js";
 export { ClaudeBackend } from "./backends/claude.js";
 export { CodexBackend } from "./backends/codex.js";
+export { CustomAcpBackend } from "./backends/custom.js";
 export { decidePermission } from "./permissions.js";
 export type { ToolPolicy } from "./permissions.js";
 export { UsageAccumulator } from "./usage.js";
 export { toJsonSchema, toStrictJsonSchema } from "./schema-strict.js";
-export { extractValidated, findJsonBlock, resolveStructuredOutput, validateValue, } from "./structured-output.js";
+export { extractValidated, findJsonBlock, parseFinalJson, resolveStructuredOutput, validateValue, } from "./structured-output.js";
 export type { ResolveOptions, StructuredSession } from "./structured-output.js";
 export { errorText, mapThrownError } from "./errors-map.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -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;AAE7E,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAClE,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC1D,YAAY,EAAE,cAAc,EAAE,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,EAAE,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACzG,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEtE,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,uBAAuB,EACvB,aAAa,GACd,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}
+{"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"}

package/dist/index.js

@@ -5,14 +5,17 @@
 // @automatalabs/workflow-engine; the two siblings meet ONLY at AgentRunner, injected by the
 // @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 { PooledConnection, SessionHandle } from "./acp-client.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";
 export { ClaudeBackend } from "./backends/claude.js";
 export { CodexBackend } from "./backends/codex.js";
+export { CustomAcpBackend } from "./backends/custom.js";
 export { decidePermission } from "./permissions.js";
 export { UsageAccumulator } from "./usage.js";
 export { toJsonSchema, toStrictJsonSchema } from "./schema-strict.js";
-export { extractValidated, findJsonBlock, resolveStructuredOutput, validateValue, } from "./structured-output.js";
+export { extractValidated, findJsonBlock, parseFinalJson, resolveStructuredOutput, validateValue, } from "./structured-output.js";
 export { errorText, mapThrownError } from "./errors-map.js";

package/dist/registry.d.ts

@@ -0,0 +1,26 @@
+export declare const BACKENDS_ENV = "AGENTPRISM_BACKENDS";
+/** How to spawn (and optionally pre-configure) one custom ACP backend. */
+export interface CustomBackendConfig {
+    /** The ACP server executable (absolute path or on PATH). */
+    command: string;
+    /** Arguments for the command. Default []. */
+    args?: string[];
+    /** Extra environment for the subprocess, merged OVER the inherited process.env. */
+    env?: Record<string, string>;
+    /** 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>;
+}
+/** A validated registry entry: the (lowercased) name plus its config. */
+export interface RegisteredBackend extends CustomBackendConfig {
+    name: string;
+}
+export type BackendRegistry = ReadonlyMap<string, RegisteredBackend>;
+/**
+ * Resolve the custom-backend registry: env-declared backends first, programmatic `backends`
+ * merged over them (option wins per name). Throws on malformed JSON, invalid names/configs, or
+ * reserved names — a misconfigured registry should fail LOUDLY at construction, not silently
+ * misroute at run time.
+ */
+export declare function resolveBackendRegistry(option?: Record<string, CustomBackendConfig>, env?: NodeJS.ProcessEnv): BackendRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +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"}

package/dist/registry.js

@@ -0,0 +1,82 @@
+// The custom-backend REGISTRY — lets any ACP agent plug in as an agent() target, not just the
+// built-in Claude/Codex pair. A registered backend is (name -> how to spawn it + optional static
+// session `_meta`), resolved once at runner construction from:
+//   1. the programmatic option: createAcpRunner({ backends: { name: config } })   (wins per name)
+//   2. the env var AGENTPRISM_BACKENDS: a JSON object of the same shape
+// Routing then matches `model`/`tier` specs against registered names FIRST (exact name, or
+// `name/<inner-model>` prefix), before the built-in claude/codex heuristics — see runner.ts.
+// Names are case-insensitive (stored lowercased); "claude" and "codex" are reserved because the
+// built-ins own their ids (and their own AGENTPRISM_*_ACP_CMD override channel).
+export const BACKENDS_ENV = "AGENTPRISM_BACKENDS";
+const RESERVED_NAMES = new Set(["claude", "codex"]);
+const NAME_PATTERN = /^[a-z][a-z0-9._-]*$/;
+/**
+ * Resolve the custom-backend registry: env-declared backends first, programmatic `backends`
+ * merged over them (option wins per name). Throws on malformed JSON, invalid names/configs, or
+ * reserved names — a misconfigured registry should fail LOUDLY at construction, not silently
+ * misroute at run time.
+ */
+export function resolveBackendRegistry(option, env = process.env) {
+    const registry = new Map();
+    const raw = env[BACKENDS_ENV];
+    if (raw !== undefined && raw.trim() !== "") {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (error) {
+            throw new Error(`${BACKENDS_ENV} is not valid JSON: ${error.message}`);
+        }
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error(`${BACKENDS_ENV} must be a JSON object of { "<name>": { "command": … } }`);
+        }
+        for (const [name, config] of Object.entries(parsed)) {
+            registry.set(...validateEntry(name, config, BACKENDS_ENV));
+        }
+    }
+    for (const [name, config] of Object.entries(option ?? {})) {
+        registry.set(...validateEntry(name, config, "backends option"));
+    }
+    return registry;
+}
+function validateEntry(rawName, config, source) {
+    const name = rawName.toLowerCase();
+    if (!NAME_PATTERN.test(name)) {
+        throw new Error(`${source}: invalid backend name "${rawName}" (must match ${NAME_PATTERN}, matched case-insensitively)`);
+    }
+    if (RESERVED_NAMES.has(name)) {
+        throw new Error(`${source}: backend name "${rawName}" is reserved for the built-in backend (use AGENTPRISM_${name.toUpperCase()}_ACP_CMD to override how it spawns)`);
+    }
+    if (config === null || typeof config !== "object" || Array.isArray(config)) {
+        throw new Error(`${source}: backend "${rawName}" must be an object with at least { command }`);
+    }
+    const c = config;
+    if (typeof c.command !== "string" || c.command.trim() === "") {
+        throw new Error(`${source}: backend "${rawName}" needs a non-empty string "command"`);
+    }
+    if (c.args !== undefined && !(Array.isArray(c.args) && c.args.every((a) => typeof a === "string"))) {
+        throw new Error(`${source}: backend "${rawName}" "args" must be an array of strings`);
+    }
+    if (c.env !== undefined && !isStringRecord(c.env)) {
+        throw new Error(`${source}: backend "${rawName}" "env" must be an object of string values`);
+    }
+    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`);
+    }
+    return [
+        name,
+        {
+            name,
+            command: c.command,
+            ...(c.args !== undefined ? { args: c.args } : {}),
+            ...(c.env !== undefined ? { env: c.env } : {}),
+            ...(c.sessionMeta !== undefined ? { sessionMeta: c.sessionMeta } : {}),
+        },
+    ];
+}
+function isStringRecord(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        Object.values(value).every((v) => typeof v === "string"));
+}

package/dist/runner.d.ts

@@ -3,13 +3,23 @@ import type { TSchema } from "typebox";
 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. */
+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. */
+    backends?: Record<string, CustomBackendConfig>;
+}
 export declare class AcpAgentRunner implements AgentRunner {
     private readonly pool;
+    /** The resolved custom-backend registry (env + option, validated at construction). */
+    private readonly backends;
     /** Typed bus carrying every ACP event from every pooled session. Beyond the AgentRunner seam
      *  (additive observability) — subscribing never affects a run and never enters the resume hash. */
     private readonly events;
     private readonly emitEvent;
-    constructor(options?: AcpPoolOptions);
+    constructor(options?: AcpRunnerOptions);
     /**
      * Listen in on the live ACP stream. `name` is an ACP `sessionUpdate` discriminant
      * ("agent_message_chunk", "tool_call", "usage_update", …) or one of the cross-cutting events
@@ -31,12 +41,17 @@ export declare class AcpAgentRunner implements AgentRunner {
     dispose(): Promise<void>;
 }
 /** Factory the mcp-server composition root calls to inject the runner into the engine. The pool
- *  size is a runner-level option (default 1, else AGENTPRISM_ACP_POOL_SIZE) — NOT a RunOptions
- *  field, so it never enters hashAgentCall / the resume identity. */
-export declare function createAcpRunner(options?: AcpPoolOptions): AcpAgentRunner;
-/** Pick the backend by model/tier. Cross-provider routing = which ACP server to spawn. */
+ *  size and the custom-backend registry are runner-level options — NOT RunOptions fields, so they
+ *  never enter hashAgentCall / the resume identity. Env fallbacks: AGENTPRISM_ACP_POOL_SIZE for
+ *  size, AGENTPRISM_BACKENDS (JSON) for backends. */
+export declare function createAcpRunner(options?: AcpRunnerOptions): AcpAgentRunner;
+/** 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
+ *  heuristics; then the default backend (AGENTPRISM_DEFAULT_BACKEND — which may itself name
+ *  a registered custom backend). */
 export declare function selectBackend(opts: {
     model?: string;
     tier?: string;
-}): Backend;
+}, registry?: BackendRegistry): Backend;
 //# sourceMappingURL=runner.d.ts.map

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;AAS5C,qBAAa,cAAe,YAAW,WAAW;IAChD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC;uGACmG;IACnG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8C;IACrE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgE;gBAE9E,OAAO,GAAE,cAAmB;IAIxC;;;;;;;;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;IAuF1B;qGACiG;IAC3F,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAI/B;AAED;;qEAEqE;AACrE,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,cAAc,CAExE;AAoED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAG9E"}
+{"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"}

package/dist/runner.js

@@ -21,16 +21,22 @@ import { AcpAgentPool } from "./pool.js";
 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 { mapThrownError } from "./errors-map.js";
+import { toJsonSchema } from "./schema-strict.js";
 import { resolveStructuredOutput } from "./structured-output.js";
 export class AcpAgentRunner {
     pool;
+    /** The resolved custom-backend registry (env + option, validated at construction). */
+    backends;
     /** Typed bus carrying every ACP event from every pooled session. Beyond the AgentRunner seam
      *  (additive observability) — subscribing never affects a run and never enters the resume hash. */
     events = new TypedEventEmitter();
     emitEvent = (name, event) => this.events.emit(name, event);
     constructor(options = {}) {
         this.pool = new AcpAgentPool(options, { onEvent: this.emitEvent });
+        this.backends = resolveBackendRegistry(options.backends);
     }
     /**
      * Listen in on the live ACP stream. `name` is an ACP `sessionUpdate` discriminant
@@ -60,7 +66,7 @@ export class AcpAgentRunner {
     async run(prompt, options = {}) {
         const opts = options;
         const schema = opts.schema;
-        const backend = selectBackend(opts);
+        const backend = selectBackend(opts, this.backends);
         const policy = { allow: opts.toolNames, deny: opts.disallowedToolNames };
         const cwd = opts.cwd ?? process.cwd();
         const session = await this.pool.acquire(backend, {
@@ -69,6 +75,9 @@ export class AcpAgentRunner {
             policy,
             signal: opts.signal,
             mcpServers: opts.mcpServers,
+            // Generic session-scoped _meta passthrough (RunOptions.meta) — merged UNDER the
+            // backend-computed keys and the runId stamp in openSession. Additive; never hashed.
+            meta: opts.meta,
             // Engine correlation id -> session/new _meta (META_KEYS.runId). Additive; never hashed.
             runId: opts.runId,
             // Stamped onto emitted ACP events as context (never sent on the wire).
@@ -80,9 +89,14 @@ export class AcpAgentRunner {
         });
         try {
             opts.signal?.throwIfAborted();
-            await applyModelSelection(session, opts);
-            const text = buildPrompt(prompt, opts, Boolean(schema));
-            const promptMeta = backend.promptMeta(schema);
+            // For a CUSTOM backend chosen by its registered name, the name itself is routing, not a
+            // model id: "browser" selects nothing; "browser/foo" selects "foo". Built-ins get the
+            // 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);
+            // 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);
             opts.signal?.throwIfAborted();
             // Inspect the turn's stop reason BEFORE the text/schema path: a refusal or truncation
@@ -153,8 +167,9 @@ export class AcpAgentRunner {
     }
 }
 /** Factory the mcp-server composition root calls to inject the runner into the engine. The pool
- *  size is a runner-level option (default 1, else AGENTPRISM_ACP_POOL_SIZE) — NOT a RunOptions
- *  field, so it never enters hashAgentCall / the resume identity. */
+ *  size and the custom-backend registry are runner-level options — NOT RunOptions fields, so they
+ *  never enter hashAgentCall / the resume identity. Env fallbacks: AGENTPRISM_ACP_POOL_SIZE for
+ *  size, AGENTPRISM_BACKENDS (JSON) for backends. */
 export function createAcpRunner(options) {
     return new AcpAgentRunner(options);
 }
@@ -188,9 +203,9 @@ function assertNormalStopReason(stopReason, label) {
             return;
     }
 }
-async function applyModelSelection(session, opts) {
-    // `model` wins; `tier` is consulted only when `model` is unset (frozen contract).
-    const spec = opts.model ?? opts.tier;
+async function applyModelSelection(session, spec, opts) {
+    // `spec` is opts.model ?? opts.tier (`model` wins — frozen contract), with a custom
+    // backend's routing name already stripped by innerModelSpec.
     if (!spec)
         return;
     const { matched, resolved, modifierFallbacks } = await session.selectModel(spec);
@@ -204,28 +219,75 @@ async function applyModelSelection(session, opts) {
     for (const fallback of modifierFallbacks ?? [])
         opts.onModelFallback?.(fallback);
 }
-function buildPrompt(prompt, opts, structured) {
+function buildPrompt(prompt, opts, schema, backend) {
     const parts = [];
     if (opts.instructions)
         parts.push(opts.instructions);
     if (opts.label)
         parts.push(`Task label: ${opts.label}`);
     parts.push(prompt);
-    if (structured) {
-        parts.push([
+    if (schema) {
+        const contract = [
             "Final output contract:",
             "- Your FINAL message MUST be a single JSON object that conforms to the required output schema.",
             "- Output ONLY that JSON object — no prose, no explanation, and no markdown code fences.",
             "- If you need to inspect files or run commands first, do so, then emit the JSON object as your final message.",
-        ].join("\n"));
+        ];
+        if (backend.embedSchemaInPrompt) {
+            // The agent behind a custom backend may ignore the `_meta.outputSchema` forward, so the
+            // schema must be STATED, not just wired — otherwise the model invents its own keys and
+            // the repair ladder can never converge. Built-ins skip this: their native constraint
+            // channel is authoritative.
+            contract.push(`- The required output schema (JSON Schema):\n${JSON.stringify(toJsonSchema(schema))}`);
+        }
+        parts.push(contract.join("\n"));
     }
     return parts.join("\n\n");
 }
-/** Pick the backend by model/tier. Cross-provider routing = which ACP server to spawn. */
-export function selectBackend(opts) {
-    const id = backendIdForSpec(opts.model) ?? backendIdForSpec(opts.tier) ?? defaultBackendId();
+/** 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
+ *  heuristics; then the default backend (AGENTPRISM_DEFAULT_BACKEND — which may itself name
+ *  a registered custom backend). */
+export function selectBackend(opts, registry) {
+    const custom = customBackendForSpec(opts.model, registry) ?? customBackendForSpec(opts.tier, registry);
+    if (custom)
+        return custom;
+    const id = backendIdForSpec(opts.model) ?? backendIdForSpec(opts.tier) ?? defaultBackendId(registry);
+    if (typeof id !== "string")
+        return id; // the default resolved to a registered custom backend
     return id === "codex" ? new CodexBackend() : new ClaudeBackend();
 }
+/** Match a model/tier spec against the registry: the whole spec, or its `<name>/` prefix. */
+function customBackendForSpec(spec, registry) {
+    if (!spec || !registry || registry.size === 0)
+        return undefined;
+    const lower = spec.toLowerCase();
+    const slash = lower.indexOf("/");
+    const name = slash > 0 ? lower.slice(0, slash) : lower;
+    const config = registry.get(name);
+    return config ? new CustomAcpBackend(config) : undefined;
+}
+/** Strip a custom backend's routing name off the model/tier spec: the spec `"name"` selects no
+ *  inner model; `"name/foo"` selects `"foo"`. Built-in backends receive the spec unchanged, and
+ *  a spec that reached a custom DEFAULT backend without naming it also passes through (the
+ *  agent's own catalog may know it). */
+function innerModelSpec(spec, backend) {
+    if (!spec || !(backend instanceof CustomAcpBackend))
+        return spec;
+    const lower = spec.toLowerCase();
+    if (lower === backend.id)
+        return undefined;
+    if (lower.startsWith(`${backend.id}/`))
+        return spec.slice(backend.id.length + 1) || undefined;
+    return spec;
+}
+/** Merge the generic turn-scoped meta passthrough UNDER the backend-computed turn meta. */
+function mergeTurnMeta(user, backend) {
+    if (!user)
+        return backend;
+    return { ...user, ...(backend ?? {}) };
+}
 function backendIdForSpec(spec) {
     if (!spec)
         return undefined;
@@ -243,6 +305,14 @@ function backendIdForSpec(spec) {
         return "claude";
     return undefined;
 }
-function defaultBackendId() {
-    return process.env.AGENTPRISM_DEFAULT_BACKEND?.toLowerCase() === "codex" ? "codex" : "claude";
+/** Resolve the default backend: a registered custom name wins (returned as a Backend), else
+ *  the built-in id. An unknown/unset value falls back to "claude" (the historical default). */
+function defaultBackendId(registry) {
+    const name = process.env.AGENTPRISM_DEFAULT_BACKEND?.toLowerCase();
+    if (name && registry) {
+        const config = registry.get(name);
+        if (config)
+            return new CustomAcpBackend(config);
+    }
+    return name === "codex" ? "codex" : "claude";
 }

package/dist/structured-output.d.ts

@@ -5,6 +5,14 @@ import type { TSchema } from "typebox";
  * raw JSON string, or undefined when none is found. (Ported VERBATIM from pi agent.ts.)
  */
 export declare function findJsonBlock(text: string): string | undefined;
+/**
+ * Parse a turn's final assistant text as JSON: direct parse first (a natively-constrained
+ * final message is pure JSON), then a balanced-block extraction when the turn also emitted
+ * leading prose. Returns undefined when no parseable JSON is present (the caller's ladder
+ * re-prompts). Shared by the Codex backend and every custom registry backend — the "read the
+ * structured result off the final message" convention is the generic ACP dialect.
+ */
+export declare function parseFinalJson(text: string): unknown;
 /** Coerce an already-parsed value toward the schema and accept it only if it then validates. */
 export declare function validateValue(value: unknown, schema: TSchema): unknown;
 /**

package/dist/structured-output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"structured-output.d.ts","sourceRoot":"","sources":["../src/structured-output.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAIvC;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAa9D;AAED,gGAAgG;AAChG,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAQtE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAUvE;AAED,sGAAsG;AACtG,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,+DAA+D;IAC/D,QAAQ,IAAI,MAAM,CAAC;IACnB,8FAA8F;IAC9F,SAAS,IAAI,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAQD;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,OAAO,CAAC,CA0BlB"}
+{"version":3,"file":"structured-output.d.ts","sourceRoot":"","sources":["../src/structured-output.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAIvC;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAa9D;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAiBpD;AAED,gGAAgG;AAChG,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAQtE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAUvE;AAED,sGAAsG;AACtG,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,+DAA+D;IAC/D,QAAQ,IAAI,MAAM,CAAC;IACnB,8FAA8F;IAC9F,SAAS,IAAI,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAQD;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,OAAO,CAAC,CA0BlB"}

package/dist/structured-output.js

@@ -23,6 +23,34 @@ export function findJsonBlock(text) {
     }
     return undefined;
 }
+/**
+ * Parse a turn's final assistant text as JSON: direct parse first (a natively-constrained
+ * final message is pure JSON), then a balanced-block extraction when the turn also emitted
+ * leading prose. Returns undefined when no parseable JSON is present (the caller's ladder
+ * re-prompts). Shared by the Codex backend and every custom registry backend — the "read the
+ * structured result off the final message" convention is the generic ACP dialect.
+ */
+export function parseFinalJson(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return undefined;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        // fall through to block extraction
+    }
+    const block = findJsonBlock(trimmed);
+    if (block !== undefined) {
+        try {
+            return JSON.parse(block);
+        }
+        catch {
+            // give up; the runner's ladder will re-prompt / extract.
+        }
+    }
+    return undefined;
+}
 /** Coerce an already-parsed value toward the schema and accept it only if it then validates. */
 export function validateValue(value, schema) {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automatalabs/acp-agents",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
     "@agentclientprotocol/claude-agent-acp": "0.53.0",
     "@automatalabs/codex-acp": "1.2.0",
     "typebox": "1.3.2",
-    "@automatalabs/shared-types": "0.3.1"
+    "@automatalabs/shared-types": "0.4.0"
   },
   "scripts": {
     "build": "tsc -b",