@automatalabs/acp-agents 1.2.7 → 1.3.0

package/dist/agent/types.d.ts

@@ -0,0 +1,221 @@
+import type { PromptResponse, SessionConfigOption, SessionModeState, StopReason, ToolCallContent, ToolCallLocation, ToolCallStatus, ToolKind, Usage } from "@agentclientprotocol/sdk";
+import type { AgentHistoryEntry, AgentUsage, McpServerConfig, PromptImage, WorkflowError } from "@automatalabs/shared-types";
+import type { TSchema } from "typebox";
+import type { AuthStore } from "../auth/auth-store.js";
+import type { ClientHandlers } from "../client-handlers.js";
+import type { HarnessConfigReport, HarnessModelsView } from "../config-catalog.js";
+import type { AcpElicitationEvent, AcpPermissionEvent, AcpRunnerEventMap, AcpSessionUpdate } from "../events.js";
+import type { ElicitationResolver, PermissionResolver, ToolPolicy } from "../permissions.js";
+import type { ProviderStore } from "../provider-store.js";
+import type { CustomBackendConfig } from "../registry.js";
+export type { SessionConfigOption, SessionModeState };
+export interface AcpAgentOptions {
+    /** ABSOLUTE path that exists and is a directory. Validated synchronously in the constructor and
+     *  the statics BEFORE any process spawns (SCRIPT_VALIDATION_ERROR otherwise). Sent as the
+     *  session/new|fork|resume|load `cwd`. */
+    cwd: string;
+    /** Model routing spec with the runner's grammar (`resolveModelRoute`): the first `/`-segment
+     *  routes to a registered custom backend (wins) or a built-in; the remainder is the backend's
+     *  model id VERBATIM and is sent as `session/set_config_option { configId: "model" }` right after
+     *  the session opens. An unrouted spec (no known first segment) goes WHOLE to the default backend
+     *  (`AGENTPRISM_DEFAULT_BACKEND`, else `claude`). Omitted = default backend, no model selection. */
+    model?: string;
+    /** Session mode. Explicit ids are strict (unadvertised → SCRIPT_VALIDATION_ERROR at open).
+     *  Omitted = the backend's `defaultModeId` when advertised (claude `auto`, codex `agent`,
+     *  opencode `build`; pi/custom none). */
+    mode?: string;
+    /** Applied verbatim via `session/set_config_option` in ascending option-id order after model
+     *  selection. `"model"` is reserved (SCRIPT_VALIDATION_ERROR in the constructor). Ids not in the
+     *  advertised catalog fail at open with SCRIPT_VALIDATION_ERROR listing the advertised ids. */
+    configOptions?: Record<string, string | boolean>;
+    /** Session-level structured-output contract (typebox). Claude: `_meta.claudeCode.options.outputFormat`
+     *  at session/new|resume|load|fork; Codex: `_meta.outputSchema` on every turn; OpenCode/pi/custom:
+     *  the client-hosted `StructuredOutput` HTTP MCP tool injected into `mcpServers` when the agent
+     *  advertises `mcpCapabilities.http`, plus the in-prompt contract. Each turn reports
+     *  `structured` / `structuredError`; there is no repair ladder. */
+    schema?: TSchema;
+    /** Client-provided MCP servers (stdio/http/sse/acp). Capability-gated by the connection exactly
+     *  like the runner. */
+    mcpServers?: McpServerConfig[];
+    /** Headless permission auto-policy: allow/deny lists + `defaultOutcome` (default "allow"). */
+    tools?: ToolPolicy;
+    /** Session-scoped async permission resolver; wins over `tools` unless the request matches an
+     *  explicit list (same precedence as the runner: resolver > policy). */
+    onPermissionRequest?: PermissionResolver;
+    /** Elicitation responder; its presence is what advertises `elicitation` at initialize. */
+    onElicitation?: ElicitationResolver;
+    /** Generic session/new `_meta` passthrough. Layered UNDER backend-computed keys (shallow, like
+     *  the runner) and, when `raw !== false`, OVER `backend.rawMessagesMeta()`. */
+    meta?: Record<string, unknown>;
+    /** Codex-only session instructions → bare `_meta.baseInstructions` / `_meta.developerInstructions`. */
+    instructions?: {
+        base?: string;
+        developer?: string;
+    };
+    /** Human label stamped on every event context and every WorkflowError `agentLabel`; never on
+     *  the wire. */
+    label?: string;
+    /** Custom backend registry merged over `AGENTPRISM_BACKENDS` exactly like
+     *  `createAcpRunner({ backends })`. Read once in the constructor; malformed →
+     *  SCRIPT_VALIDATION_ERROR. Forks inherit it and cannot override it. */
+    backends?: Record<string, CustomBackendConfig>;
+    /** Agent-lifetime abort: rejects queued work with `signal.reason`, cancels an in-flight turn,
+     *  then closes. Not inherited by forks. */
+    signal?: AbortSignal;
+    /** Default true: the session log is retained across turns so `history`/`text` are cumulative
+     *  and a fork can seed its child. `false` maps to `retainSessionLog: false` (history/text hold
+     *  only the latest turn). */
+    retainHistory?: boolean;
+    /** Default true: ask the backend to emit its vendor notifications (`_claude/sdkMessage` on
+     *  Claude) so they reach `on("raw_message")` and `turn.raw`. `false` skips
+     *  `backend.rawMessagesMeta()` (a schema still turns raw messages on for Claude because the
+     *  schema channel needs them). */
+    raw?: boolean;
+    /** Optional shared auth store (default off = each agent's own login). Forks share the parent's. */
+    authStore?: AuthStore;
+    /** Optional shared provider-intent store. Forks share the parent's. */
+    providerStore?: ProviderStore;
+    /** Client-side fs/terminal/mcp handlers advertised at initialize (validated with
+     *  `validateClientHandlers`). */
+    clientHandlers?: ClientHandlers;
+}
+export interface AcpAgentPromptOptions {
+    /** Appended as image content blocks (validated with `validatePromptImages`; string prompts
+     *  become `[text, ...images]`). */
+    images?: readonly PromptImage[];
+    /** Turn `_meta` passthrough, merged UNDER the backend's turn meta (backend keys win direct
+     *  collisions, exactly like the runner's `mergeTurnMeta`). */
+    meta?: Record<string, unknown>;
+    /** Applied via `session/set_config_option` BEFORE this turn, inside the FIFO; STICKY for the
+     *  session. Same validation as the constructor option. */
+    configOptions?: Record<string, string | boolean>;
+    /** Applied via `session/set_mode` before this turn, inside the FIFO; sticky; strict. */
+    mode?: string;
+    /** Per-turn schema override. Allowed ONLY when the backend carries the schema on the turn and
+     *  does not embed it in the prompt (today: Codex). Otherwise SCRIPT_VALIDATION_ERROR naming the
+     *  backend and pointing at the constructor `schema` option. */
+    schema?: TSchema;
+    /** Per-call abort: queued, or started but not yet on the wire (the lazy open, the per-turn
+     *  `configOptions`/`mode`) → rejects with the reason without sending; in flight →
+     *  `session/cancel`, then rejects with the reason. The one way to stop a turn `cancel()` cannot
+     *  reach: `cancel()` targets only a turn whose `session/prompt` is on the wire. */
+    signal?: AbortSignal;
+}
+export interface AcpAgentSteerOptions {
+    images?: readonly PromptImage[];
+    meta?: Record<string, unknown>;
+}
+export interface AcpAgentCloseOptions {
+    /** true = skip `session/close` so the agent-persisted session stays re-openable via
+     *  `AcpAgent.resume/load/fork(ref)`. The dedicated process is disposed either way. */
+    keep?: boolean;
+}
+/** Everything a fork may override. The backend is fixed by the parent: a `model` override must
+ *  route to the same backend (poolKey-equal) or SCRIPT_VALIDATION_ERROR. `backends`, `authStore`,
+ *  `providerStore`, `clientHandlers` are inherited and not overridable. `label` defaults to
+ *  `<parent label>/fork-<n>` (or `fork-<n>`); `signal` is never inherited. `cwd` defaults to the
+ *  parent's; a different cwd is rejected on `cwd: "source-only"` backends (`FORK_SESSION_TRAITS`). */
+export type AcpAgentForkOptions = Partial<Omit<AcpAgentOptions, "backends" | "authStore" | "providerStore" | "clientHandlers">>;
+/** Options for the cold statics. `cwd` defaults to `ref.cwd`; `model` must route to `ref.backendId`. */
+export type AcpAgentReopenOptions = Partial<AcpAgentOptions>;
+export interface AcpAgentProbeOptions {
+    /** One exact routed spec (`modelSpecs: [model]`): selected before the catalog is read. */
+    model?: string;
+    /** More exact specs. */
+    models?: string[];
+    /** Backend-only targets. Default (no `harnesses`, no model specs): every built-in plus every
+     *  registered custom backend. */
+    harnesses?: string[];
+    /** Substring or `/regex/` over leaf model ids → `catalog.models[*].matches`. */
+    modelFilter?: string;
+    backends?: Record<string, CustomBackendConfig>;
+    cwd?: string;
+    probeTimeoutMs?: number;
+    probeConcurrency?: number;
+    signal?: AbortSignal;
+}
+export type AcpAgentCatalog = HarnessConfigReport & {
+    models: HarnessModelsView[];
+};
+export interface AcpAgentUpdateRecord {
+    readonly update: AcpSessionUpdate;
+    readonly receivedAt: number;
+}
+export interface AcpAgentRawRecord {
+    readonly method: string;
+    readonly message: unknown;
+    readonly receivedAt: number;
+}
+export interface AcpAgentToolCall {
+    readonly toolCallId: string;
+    /** SDK UNSTABLE `ToolCall.name` / `ToolCallUpdate.name`, verbatim. */
+    readonly name?: string;
+    readonly title: string;
+    readonly kind?: ToolKind;
+    /** Last seen; "pending" when the agent sent none. */
+    readonly status: ToolCallStatus;
+    readonly rawInput?: unknown;
+    readonly rawOutput?: unknown;
+    readonly content?: ToolCallContent[];
+    readonly locations?: ToolCallLocation[];
+    /** Shallow merge of every `_meta` seen for this id. */
+    readonly meta?: Record<string, unknown>;
+}
+export interface AcpAgentTurnUsage {
+    /** THIS turn's tokens: `response.usage` mapped to `AgentUsage` (every installed adapter reports
+     *  the turn, not the session — `PROMPT_USAGE_SCOPES`); `cost` = the clamped delta of the
+     *  cumulative `usage_update` cost gauge across the turn. When the response carries no `usage`,
+     *  tokens fall back to the context-token gauge delta exactly like `UsageAccumulator.delta()`. */
+    readonly turn: AgentUsage;
+    /** Running per-field sum of every turn THIS AcpAgent ran (`cost` = the latest gauge value),
+     *  including this one. Starts at zero at open/fork/resume/load — replayed history and the
+     *  parent's turns are not counted. */
+    readonly session: AgentUsage;
+    /** `response.usage` verbatim. */
+    readonly response?: Usage;
+}
+export interface AcpAgentTurn {
+    /** The wire object, `_meta` intact (no SDK response mapping on session/prompt). */
+    readonly response: PromptResponse;
+    /** `= response.stopReason`; NEVER thrown on (refusal/max_tokens/cancelled included). */
+    readonly stopReason: StopReason;
+    /** This turn's assistant messages joined by "\n\n" (`SessionHandle.foldedTurnText()`). */
+    readonly text: string;
+    /** Every session/update of this turn, structuredClone'd (verbatim objects, `_meta` intact). */
+    readonly updates: ReadonlyArray<AcpAgentUpdateRecord>;
+    /** Every `raw_message` of this turn (Claude `_claude/sdkMessage`). */
+    readonly raw: ReadonlyArray<AcpAgentRawRecord>;
+    /** tool_call ⊕ tool_call_update folded by toolCallId, first-seen order. */
+    readonly toolCalls: ReadonlyArray<AcpAgentToolCall>;
+    readonly permissions: ReadonlyArray<AcpPermissionEvent>;
+    readonly elicitations: ReadonlyArray<AcpElicitationEvent>;
+    readonly usage: AcpAgentTurnUsage;
+    /** Validated (typebox Convert + Check) when a schema was active for the turn. */
+    readonly structured?: unknown;
+    /** Why `structured` is absent although a schema was active. */
+    readonly structuredError?: string;
+    /** This turn's accumulator entries (copies). Per CHUNK, not per message: one `assistant`/`text`
+     *  entry per streamed `agent_message_chunk` and one `tool`/`toolCall` entry per `tool_call`, so
+     *  `history.length` is not a message count — `text` is the folded, per-message view. */
+    readonly history: readonly AgentHistoryEntry[];
+}
+/** A `prompt()` rejection for a turn the agent walled with a typed session failure (codex-acp's
+ *  negotiated extension): the runner's mapped `WorkflowError` (`mapTypedSessionFailure`, so codes,
+ *  `recoverable` and `details` keep their tested contract) carrying the COMPLETE turn — verbatim
+ *  `response` incl. `_meta`, `usage`, `updates`, `raw`, `toolCalls`, `history` — so nothing is
+ *  stripped. Narrow with `isAcpAgentTurnError`. */
+export type AcpAgentTurnError = WorkflowError & {
+    readonly turn: AcpAgentTurn;
+};
+/** Same keys/payloads as the runner bus (no new cross-cutting names); turn boundaries are the
+ *  `prompt()` promise. */
+export type AcpAgentEventMap = AcpRunnerEventMap;
+export type AcpAgentEventName = keyof AcpAgentEventMap;
+export type AcpAgentEventListener<K extends AcpAgentEventName> = (event: AcpAgentEventMap[K]) => void;
+/** `idle` (constructed, nothing spawned) → `opening` → `ready` ⇄ `busy` (a queued op is executing)
+ *  → `closed` (set the instant `close()` is called, the constructor signal aborts, or the process
+ *  dies). */
+export type AcpAgentState = "idle" | "opening" | "ready" | "busy" | "closed";
+/** The all-zero `AgentUsage` every agent starts from (frozen; never mutated in place). */
+export declare const ZERO_USAGE: AgentUsage;
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/agent/types.js

@@ -0,0 +1,9 @@
+/** The all-zero `AgentUsage` every agent starts from (frozen; never mutated in place). */
+export const ZERO_USAGE = Object.freeze({
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    total: 0,
+    cost: 0,
+});

package/dist/backend.d.ts

@@ -95,6 +95,12 @@ export interface Backend {
      *  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;
+    /** OPTIONAL session `_meta` that switches the agent's vendor notification stream on (the
+     *  `raw_message` events — Claude's `_claude/sdkMessage`). Undefined when the agent has no such
+     *  stream. The AcpAgent SDK layers it UNDER the caller's `meta` and OVER `sessionMetaDefaults`
+     *  when `raw` is on; the one-shot runner never sends it (a schema run already enables the stream
+     *  through `sessionMeta`). */
+    rawMessagesMeta?(): Record<string, unknown> | undefined;
     /** Protocol-critical `_meta` for session/prompt (undefined when this backend carries the schema
      *  at session/new). These keys win direct collisions with caller prompt metadata; unrelated
      *  caller keys are transported unchanged. */

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;AACvC,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,iGAAiG;AACjG,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D;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,8FAA8F;IAC9F,eAAe,IAAI,MAAM,CAAC;IAC1B;;;4FAGwF;IACxF,gBAAgB,IAAI,MAAM,CAAC;IAC3B,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;IAC/B,0FAA0F;IAC1F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oGAAoG;IACpG,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,8FAA8F;AAC9F,MAAM,WAAW,qBAAqB;IACpC,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,gFAAgF;AAChF,MAAM,MAAM,2BAA2B,GAAG;IACxC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,OAAO,EAAE,yBAAyB,CAAC;CACpC,CAAC;AAEF,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB;;uEAEmE;IACnE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;0EAGsE;IACtE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;kGAI8F;IAC9F,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC;;qFAEiF;IACjF,QAAQ,CAAC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IAC9C;;;;;;;4CAOwC;IACxC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAClE;;;;6EAIyE;IACzE,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC;mGAC+F;IAC/F,qBAAqB,CAAC,CACpB,KAAK,EAAE,OAAO,EACd,QAAQ,CAAC,EAAE,qBAAqB,GAC/B,2BAA2B,GAAG,SAAS,CAAC;IAC3C,0DAA0D;IAC1D,WAAW,IAAI,WAAW,CAAC;IAC3B;;sEAEkE;IAClE,mBAAmB,CAAC,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACtF;;;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;;iDAE6C;IAC7C,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC7E,oGAAoG;IACpG,gBAAgB,CAAC,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC;CACtD;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":"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"}

package/dist/backends/claude.d.ts

@@ -13,6 +13,7 @@ export declare class ClaudeBackend implements Backend {
     sessionMetaDefaults(inputs?: SessionMetaInputs): Record<string, unknown> | undefined;
     sessionMeta(schema: TSchema | undefined, inputs?: SessionMetaInputs): Record<string, unknown> | undefined;
     promptMeta(): Record<string, unknown> | undefined;
+    rawMessagesMeta(): Record<string, unknown> | undefined;
     nativeStructured(source: StructuredSource): unknown;
 }
 export declare const claudeBackendDefinition: import("./define.js").BuiltinBackendDefinition<"claude">;

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

@@ -1 +1 @@
-{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/backends/claude.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EACV,OAAO,EACP,2BAA2B,EAC3B,qBAAqB,EACrB,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EACjB,MAAM,eAAe,CAAC;AASvB,+FAA+F;AAC/F,eAAO,MAAM,iBAAiB,EAAE,WAK/B,CAAC;AAEF,qBAAa,aAAc,YAAW,OAAO;IAI/B,QAAQ,CAAC,WAAW,EAAE,WAAW;IAH7C,QAAQ,CAAC,EAAE,EAAG,QAAQ,CAAU;IAChC,QAAQ,CAAC,aAAa,EAAG,MAAM,CAAU;gBAEpB,WAAW,GAAE,WAA+B;IAEjE,qBAAqB,CACnB,KAAK,EAAE,OAAO,EACd,QAAQ,CAAC,EAAE,qBAAqB,GAC/B,2BAA2B,GAAG,SAAS;IAa1C,WAAW,IAAI,WAAW;IAgB1B,mBAAmB,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAMpF,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,EAAE,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAuBzG,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAKjD,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO;CAGpD;AAQD,eAAO,MAAM,uBAAuB,0DA2BlC,CAAC"}
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/backends/claude.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EACV,OAAO,EACP,2BAA2B,EAC3B,qBAAqB,EACrB,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EACjB,MAAM,eAAe,CAAC;AASvB,+FAA+F;AAC/F,eAAO,MAAM,iBAAiB,EAAE,WAK/B,CAAC;AAEF,qBAAa,aAAc,YAAW,OAAO;IAI/B,QAAQ,CAAC,WAAW,EAAE,WAAW;IAH7C,QAAQ,CAAC,EAAE,EAAG,QAAQ,CAAU;IAChC,QAAQ,CAAC,aAAa,EAAG,MAAM,CAAU;gBAEpB,WAAW,GAAE,WAA+B;IAEjE,qBAAqB,CACnB,KAAK,EAAE,OAAO,EACd,QAAQ,CAAC,EAAE,qBAAqB,GAC/B,2BAA2B,GAAG,SAAS;IAa1C,WAAW,IAAI,WAAW;IAgB1B,mBAAmB,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAMpF,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,EAAE,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAuBzG,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAKjD,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAMtD,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO;CAGpD;AAQD,eAAO,MAAM,uBAAuB,0DA2BlC,CAAC"}

package/dist/backends/claude.js

@@ -86,6 +86,11 @@ export class ClaudeBackend {
         // Claude's schema is session-scoped (read at session/new); nothing on the turn.
         return undefined;
     }
+    rawMessagesMeta() {
+        // claude-agent-acp emits `_claude/sdkMessage` only when the session asks for it; a schema
+        // session already sets this through sessionMeta (the result rides that stream).
+        return { claudeCode: { emitRawSDKMessages: true } };
+    }
     nativeStructured(source) {
         return source.rawStructuredOutput();
     }

package/dist/config-catalog.d.ts

@@ -0,0 +1,173 @@
+import type { SessionConfigOption, SessionModeState } from "@agentclientprotocol/sdk";
+import { type CustomBackendConfig } from "./registry.js";
+import { type ProbedConfigOptions } from "./runner.js";
+export interface ValidateProbeRunner {
+    probeConfigOptions(spec?: string, opts?: {
+        cwd?: string;
+        selectModel?: boolean;
+        backends?: Record<string, CustomBackendConfig>;
+        signal?: AbortSignal;
+    }): Promise<ProbedConfigOptions>;
+    /** Every host-routable backend name. Used by protocol-native discovery. */
+    listBackends?(): string[];
+    /** Host-registered custom names, including deliberate built-in shadows. */
+    listCustomBackends?(): string[];
+    /** The host's backend selected when a workflow omits model. */
+    defaultBackendId?(): string;
+    /** Present on owned probe runners; shared host runners are never disposed by validation. */
+    dispose?(): Promise<void>;
+}
+export type ConfigProbeFactory = (backends: Record<string, CustomBackendConfig> | undefined) => ValidateProbeRunner;
+/** Package-internal hermetic test seam. Deliberately absent from the public index export. */
+export declare function setConfigProbeFactoryForTests(factory: ConfigProbeFactory): () => void;
+export interface ValidateHarnessOptions {
+    backendId: string;
+    /** AgentPrism's explicit mode when the call omits mode; absent for no-mode/custom backends. */
+    defaultModeId?: string;
+    /** The call's verbatim selected model; absent means the harness/session default. */
+    model?: string;
+    probed: boolean;
+    /** Present when probed=false: the harness's spawn/auth/session error. */
+    error?: string;
+    /** Effective advertised ACP modes; null means this backend/model supports no session modes. */
+    modes?: SessionModeState | null;
+    options?: SessionConfigOption[];
+}
+type SelectConfigOption = Extract<SessionConfigOption, {
+    type: "select";
+}>;
+/** Every leaf {value,label} the select advertises, flattening any advertised optgroups. */
+export declare function selectChoicePairs(option: SelectConfigOption): {
+    value: string;
+    label?: string;
+}[];
+export interface SelectChoiceGroup {
+    group: string;
+    count: number;
+}
+export interface SelectChoiceSummary {
+    total: number;
+    groups: SelectChoiceGroup[];
+}
+/**
+ * Group a select's choices for summary display. Prefers the harness-advertised optgroup
+ * labels; absent those, groups by the first "/"-segment of each value. Groups come back
+ * largest-first, ties broken by first appearance.
+ */
+export declare function summarizeSelectChoices(option: SelectConfigOption): SelectChoiceSummary;
+export interface ProbeHarnessConfigOptions {
+    /** Harness names to probe (built-in `claude` / `codex` / `opencode` / `pi` or a registered
+     *  custom name; any model spec routes like an agent() call's). Default: every routable
+     *  harness — the four built-ins plus each registered custom backend. */
+    harnesses?: string[];
+    /** Exact routed model specs to select before reading their model-specific option catalogs. */
+    modelSpecs?: string[];
+    /** Programmatic custom-backend registry, merged over the AGENTPRISM_BACKENDS env var
+     *  exactly like `createAcpRunner({ backends })`. */
+    backends?: Record<string, CustomBackendConfig>;
+    /** Session cwd for the probes. Default `process.cwd()` — harnesses may resolve
+     *  project-level configuration (and hence their catalog) from it. */
+    cwd?: string;
+    /** Host-owned no-prompt probe runner. When supplied it is reused and never disposed. */
+    probeRunner?: ValidateProbeRunner;
+    /** Per-probe cancellation deadline in milliseconds. Default 60,000; lifecycle
+     *  diagnostics can use a shorter bound. Must be a positive timer-safe integer. */
+    probeTimeoutMs?: number;
+    /** Maximum concurrent probes, from 1 to 16. Default 4. */
+    probeConcurrency?: number;
+    /** Shared discovery cancellation budget. Completed catalogs are retained; active
+     * probes are aborted and queued targets become failed entries without starting. */
+    signal?: AbortSignal;
+}
+export interface HarnessConfigReport {
+    /** True when every requested harness probed successfully. */
+    ok: boolean;
+    /** 0 = all probed; 1 = at least one probe failed. */
+    exitCode: 0 | 1;
+    /** One entry per requested harness, in request order — the same shape validate reports. */
+    harnessOptions: ValidateHarnessOptions[];
+    /** Bounded presentation alongside the complete supported catalog. */
+    authoringSummary?: HarnessConfigSummary;
+}
+export declare const DEFAULT_PROBE_TIMEOUT_MS = 60000;
+/**
+ * Probe each requested harness's advertised config-option catalog. A per-harness
+ * spawn/auth/session failure (or timeout) is reported as `probed:false` on that entry —
+ * never thrown. Only caller configuration errors throw: a malformed AGENTPRISM_BACKENDS /
+ * `backends` registry (loud at construction, mirroring `createAcpRunner`) or invalid options.
+ */
+export declare function probeHarnessConfig(options?: ProbeHarnessConfigOptions): Promise<HarnessConfigReport>;
+/** One harness's slice of the `config <harness> --models[=<filter>]` view. Without a
+ *  filter it carries the provider/group breakdown (never the leaf ids); with a filter it
+ *  carries only the matching leaf ids. There is no unfiltered leaf dump on any surface. */
+export interface HarnessModelsView {
+    backendId: string;
+    probed: boolean;
+    /** Present when probed=false. */
+    error?: string;
+    /** False when the harness advertises no `model` select option. */
+    hasModelOption: boolean;
+    /** The filter as given, when one was supplied. */
+    filter?: string;
+    /** Breakdown mode (no filter): total leaf count and per-group counts. */
+    total?: number;
+    groups?: SelectChoiceGroup[];
+    /** Filter mode: the leaf model ids matching the filter. */
+    matches?: string[];
+}
+/** Compile a `--models=<filter>` value into a leaf-value matcher. A value wrapped in
+ *  slashes (`/.../`) is a case-insensitive regex; anything else is a case-insensitive
+ *  substring. Throws a TypeError on an invalid regex (surfaced as a CLI usage error). */
+export declare function buildModelFilter(filter: string): (value: string) => boolean;
+/** Build the per-harness `--models` view. `filter` undefined = breakdown mode. */
+export declare function buildHarnessModelsView(report: HarnessConfigReport, filter?: string): HarnessModelsView[];
+export interface HarnessConfigSummaryModel {
+    modelId: string;
+    /** Exact executable route; browse selectors never appear here. */
+    route: string;
+}
+export interface HarnessConfigSummaryGroup {
+    provider: string;
+    count: number;
+    kind: "provider" | "aggregator";
+    /** Presentation only. Expand with modelFilter; never pass to agent(). */
+    selector?: string;
+    modelFilter: string;
+}
+export interface HarnessConfigSummaryEntry {
+    backendId: string;
+    /** Exact-model probe scope, when selected before reading options. */
+    model?: string;
+    probed: boolean;
+    error?: string;
+    hasModelOption: boolean;
+    /** Actual complete live catalog size, before presentation limits/preferences. */
+    total: number;
+    /** Current selection is separate from preferred models; it need not be preferred. */
+    currentModel?: string;
+    /** Present only when the current model is an advertised executable leaf. */
+    currentRoute?: string;
+    omittedCurrentModel?: true;
+    models: HarnessConfigSummaryModel[];
+    omittedModels: number;
+    groups: HarnessConfigSummaryGroup[];
+    omittedGroups: number;
+    omittedGroupModels: number;
+    preferenceSource?: "enabledModels";
+    /** Available preferred models before presentation limits. */
+    preferredTotal?: number;
+    unmatched: string[];
+    omittedUnmatched: number;
+}
+export interface HarnessConfigSummary {
+    /** One entry per requested probe, including unavailable backends, in request order. */
+    harnesses: HarnessConfigSummaryEntry[];
+}
+/** Compact live authoring guidance. Does not mutate or restrict the supported catalog.
+ * Lists are bounded per harness; omitted counts and exact expansion filters are explicit.
+ * Options such as effort remain authoritative only for the exact probed model. */
+export declare function buildHarnessConfigSummary(report: Pick<HarnessConfigReport, "harnessOptions">): HarnessConfigSummary;
+/** Format the bounded summary for both explicit discovery and missing-route diagnostics. */
+export declare function formatHarnessConfigSummary(summary: HarnessConfigSummary): string;
+export {};
+//# sourceMappingURL=config-catalog.d.ts.map

package/dist/config-catalog.d.ts.map

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