From ab24819bdb5da0c9ca78d0da89494e71c21481ed Mon Sep 17 00:00:00 2001 From: huntharo Date: Thu, 17 Sep 2026 19:00:26 -0400 Subject: [PATCH 1/2] fix(acp): route model selection to the config option ACP 1.3 defines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every ACP model selection failed with "conn.setSessionModel is not a function". ACP 1.3 has no session/set_model — it is absent from the SDK's AGENT_METHODS and ClientSideConnection exposes no setSessionModel — but AcpAgentConnection still declared one, and createConnection attaches the real ClientSideConnection with an `as unknown as` cast that erases the structural check. So the dead name type-checked and threw at runtime, on every startThread({ model }), for every agent. startThread catches and debug-logs, so the only symptom was a session quietly running on the agent's default model. Drop the declaration and its dispatch case; session/set_model now rides dispatch's default arm and goes out verbatim through the SDK's generic request(), so agents accepting it as a vendor extension keep working. Then route by what the agent advertises: session/set_config_option against the `model` option when it publishes no models.availableModels, session/set_model when it does. The read path already made exactly this distinction (modelIdFromCapabilities, modelsFromCapabilities); the two disagreeing let a host list models it could not then select. The config option's reply also carries the full refreshed config set, where set_model answers {} and refreshes only via an async notification — and on Kimi the model determines which thought levels exist, with applyReasoning reading runtimeCapabilities right afterwards. Pin the class, not just the case: a runtime list of AcpAgentConnection's methods, kept in step with the interface by two type assertions, is asserted against the real ClientSideConnection.prototype. Re-adding setSessionModel fails it with "expected 'undefined' to be 'function'". The old test could not catch this — it drove a hand-written stub that had the method, so the stub and the interface agreed with each other and both disagreed with the shipped SDK. Verified against Kimi Code CLI 0.29.2. Co-Authored-By: Claude Opus 5 --- .changeset/acp-model-config-option-route.md | 19 +++ packages/agent-acp/src/acp-client.ts | 52 +++++++- packages/agent-acp/src/acp-connection.ts | 17 ++- .../agent-acp/test/acp-connection.test.ts | 42 ++++++- .../test/model-selection-route.test.ts | 114 ++++++++++++++++++ 5 files changed, 232 insertions(+), 12 deletions(-) create mode 100644 .changeset/acp-model-config-option-route.md create mode 100644 packages/agent-acp/test/model-selection-route.test.ts diff --git a/.changeset/acp-model-config-option-route.md b/.changeset/acp-model-config-option-route.md new file mode 100644 index 0000000..20f94e5 --- /dev/null +++ b/.changeset/acp-model-config-option-route.md @@ -0,0 +1,19 @@ +--- +"@pwrdrvr/agent-acp": minor +--- + +Fix ACP model selection, which threw before the request ever left the process, and route it through the config option when that is how the agent advertises model choice. + +**The bug.** Every ACP model selection failed with `conn.setSessionModel is not a function`. ACP 1.3 has no `session/set_model`: it is absent from the SDK's `AGENT_METHODS`, and `ClientSideConnection` exposes no `setSessionModel`. But `AcpAgentConnection` still declared one, and `createConnection` attaches the real `ClientSideConnection` with an `as unknown as` cast that erases the structural check — so the dead name type-checked and threw at runtime, for every agent, on every `startThread({ model })`. `AcpAgentClient.startThread` catches and debug-logs it, so the only symptom was a session quietly running on the agent's default model. + +The declaration and its dispatch case are gone. `session/set_model` now rides `dispatch`'s default arm, which sends it verbatim through the SDK's generic `request()` — agents that still accept it as a vendor extension keep working. + +**The routing.** `setModel` now picks its route from the advertised capabilities: `session/set_config_option` against the `model` option (`category: "model"`, or a literal `model` id) when the agent publishes no `models.availableModels`, and `session/set_model` when it does. This is the write twin of a distinction the read path has always made — `modelIdFromCapabilities` and `modelsFromCapabilities` both fall back to the config option — and the two disagreeing is what let a host list models it could not then select. + +Preferring the config option is not only spec-correctness. Its reply carries the agent's full refreshed config set, so a capability-dependent step that runs straight afterwards sees the new state; `session/set_model` answers `{}` and refreshes only via an async `config_option_update` notification. That matters immediately: on Kimi, switching model changes which thought levels exist (`K2.7 Coding` offers only `on`, `K3` offers `low`/`high`/`max`), and `applyReasoning` runs off `runtimeCapabilities` right after the model is set. + +Measured against Kimi Code CLI 0.29.2, whose `session/new` returns a `model` config option and no `models` capability at all: `session/set_config_option {configId: "model"}` is accepted and echoes the new `currentValue`. Kimi does also still honour `session/set_model`, so for that agent the first half of this change alone restores the behaviour; the routing is what keeps it working on an agent that implements only what ACP 1.3 defines. + +A model write routed through a config option records both `currentModelId` and `configValues[id]` in the session's runtime state, so a consumer reading `thread_settings.model` need not know which route the agent exposed. + +Type changes: `AcpRuntimeOptionSource` gains `"modelConfigOption"`; `AcpAgentConnection` drops `setSessionModel`. diff --git a/packages/agent-acp/src/acp-client.ts b/packages/agent-acp/src/acp-client.ts index 7f9bfad..2cdee9b 100644 --- a/packages/agent-acp/src/acp-client.ts +++ b/packages/agent-acp/src/acp-client.ts @@ -49,6 +49,7 @@ import { acpSessionRuntimeStateFromUpdate, mergeAcpRuntimeState, modeLabelFor, + modelConfigOption, modelIdFromCapabilities, normalizeAcpRuntimeCapabilities, type AcpRuntimeCapabilities, @@ -70,7 +71,14 @@ export type AcpPromptContentBlock = | { type: "text"; text: string } | { type: "image"; mimeType: string; data: string }; -export type AcpRuntimeOptionSource = "mode" | "model" | "configOption"; +export type AcpRuntimeOptionSource = + | "mode" + | "model" + | "configOption" + /** A model write that travels as `session/set_config_option` because the + * agent exposes model choice as a config option rather than via the legacy + * top-level `models` capability. See `setModel`. */ + | "modelConfigOption"; export type AcpAgentClientOptions = { /** The transport (real stdio or a fake). */ @@ -256,8 +264,9 @@ export class AcpAgentClient implements AgentBackend { * Public `AgentBackend.startThread`: accepts NEUTRAL `AgentStartThreadOptions` * and maps them onto an ACP `session/new`. ACP supports: * • `cwd` → `session/new.cwd`. - * • `model` → applied via `session/set_model` after the session opens, when - * the agent advertises model selection (best-effort; debug-logged if not). + * • `model` → applied after the session opens, by whichever route the agent + * advertises: the `model` config option, or legacy `session/set_model` + * (best-effort; debug-logged if not). See `setModel`. * • `instructions` is NOT injected here — ACP `session/new` has no base- * instructions slot, matching the adapter's existing behavior. A host that * wants system framing sends it as leading turn text. @@ -753,7 +762,31 @@ export class AcpAgentClient implements AgentBackend { await this.setRuntimeOption(threadId, "mode", modeId, modeId); } + /** Apply a model selection by whichever route the agent actually advertises. + * + * ACP 1.3 has NO `session/set_model` — it is absent from `AGENT_METHODS`. + * An agent that offers model choice does it through a config option with + * `category: "model"` (Kimi's `session/new` returns exactly that, and nothing + * under `models`). Some agents still accept `session/set_model` as a vendor + * extension, and the `models.availableModels` shape is still honoured for + * them, but it is not what the protocol defines any more. + * + * Two reasons to prefer the config option when the agent offers it. The READ + * path already draws this distinction — `modelIdFromCapabilities` and + * `modelsFromCapabilities` both fall back to the config option — and the two + * disagreeing lets a host list models it cannot then select. And the config + * option's REPLY carries the agent's full refreshed config set, where + * `session/set_model` answers `{}` and refreshes only via an async + * notification: on Kimi the model determines which thought levels exist, and + * `applyReasoning` reads `runtimeCapabilities` immediately after this. */ async setModel(threadId: string, modelId: string): Promise { + const advertisesModelsCapability = + (this.runtimeCapabilities?.models?.availableModels?.length ?? 0) > 0; + const option = modelConfigOption(this.runtimeCapabilities); + if (!advertisesModelsCapability && option !== undefined) { + await this.setRuntimeOption(threadId, "modelConfigOption", option.id, modelId); + return; + } await this.setRuntimeOption(threadId, "model", modelId, modelId); } @@ -985,7 +1018,16 @@ export class AcpAgentClient implements AgentBackend { ? { configValues: { [optionId]: value }, updatedAt: this.now() } : source === "mode" ? { currentModeId: value, updatedAt: this.now() } - : { currentModelId: value, updatedAt: this.now() }; + : source === "modelConfigOption" + ? // Record BOTH: it IS the config option's value, and it IS the + // session's model. A consumer reading `currentModelId` must not + // have to know which route the agent happened to expose. + { + currentModelId: value, + configValues: { [optionId]: value }, + updatedAt: this.now() + } + : { currentModelId: value, updatedAt: this.now() }; session.runtimeState = mergeAcpRuntimeState(session.runtimeState, requested); const effectiveCapabilities = runtimeCapabilities ?? this.runtimeCapabilities; if (effectiveCapabilities) { @@ -1006,7 +1048,7 @@ export class AcpAgentClient implements AgentBackend { optionId: string, value: string ): Promise { - if (source === "configOption") { + if (source === "configOption" || source === "modelConfigOption") { return await this.transport.request("session/set_config_option", { sessionId: protocolSessionId, configId: optionId, diff --git a/packages/agent-acp/src/acp-connection.ts b/packages/agent-acp/src/acp-connection.ts index 25a8565..9dc47ba 100644 --- a/packages/agent-acp/src/acp-connection.ts +++ b/packages/agent-acp/src/acp-connection.ts @@ -35,7 +35,16 @@ import type { AcpJsonRpcTransport } from "./acp-transport"; * drives. Injectable (via `createConnection`) so the adapter can be unit-tested * without spawning a real agent. The library's `ClientSideConnection` satisfies * this structurally (its methods take typed schema params; we pass records that - * match at runtime). */ + * match at runtime). + * + * Every entry here MUST exist on the real `ClientSideConnection`. It is + * attached with an `as unknown as` cast (see `createConnection`), so a name + * that is merely plausible type-checks and then throws + * "conn. is not a function" at runtime, on the wire, against a user's + * agent. `setSessionModel` was such an entry: ACP 1.3 has no `session/set_model` + * at all, so every model selection died before it was sent. Anything the SDK + * does not expose as a typed method belongs in `dispatch`'s default arm, which + * sends it verbatim through `request()`. */ export interface AcpAgentConnection { initialize(params: Record): Promise; newSession(params: Record): Promise; @@ -43,7 +52,6 @@ export interface AcpAgentConnection { prompt(params: Record): Promise; cancel(params: Record): Promise; setSessionMode(params: Record): Promise; - setSessionModel(params: Record): Promise; authenticate(params: Record): Promise; request(method: string, params: Record): Promise; notify(method: string, params: Record): Promise; @@ -259,8 +267,9 @@ export class AcpConnection implements AcpJsonRpcTransport { return await conn.prompt(params); case "session/set_mode": return await conn.setSessionMode(params); - case "session/set_model": - return await conn.setSessionModel(params); + // `session/set_model` is deliberately NOT cased here: SDK 1.3 has no + // typed `setSessionModel`, so it goes out through the default arm's + // generic `request()` for agents still speaking the older method. case "session/cancel": await conn.cancel(params); return {}; diff --git a/packages/agent-acp/test/acp-connection.test.ts b/packages/agent-acp/test/acp-connection.test.ts index 395eee7..0a0e599 100644 --- a/packages/agent-acp/test/acp-connection.test.ts +++ b/packages/agent-acp/test/acp-connection.test.ts @@ -2,7 +2,7 @@ import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node: import { tmpdir } from "node:os"; import path from "node:path"; import { describe, expect, it, vi } from "vitest"; -import type { Client } from "@agentclientprotocol/sdk"; +import { ClientSideConnection, type Client } from "@agentclientprotocol/sdk"; import { AcpConnection, type AcpAgentConnection } from "../src/acp-connection"; /** A stub agent connection capturing calls + returning canned results. */ @@ -14,7 +14,6 @@ function stubConnection(overrides: Partial = {}): AcpAgentCo prompt: vi.fn(async () => ({ stopReason: "end_turn" })), cancel: vi.fn(async () => undefined), setSessionMode: vi.fn(async () => ({})), - setSessionModel: vi.fn(async () => ({})), authenticate: vi.fn(async () => ({})), request: vi.fn(async () => ({ ok: true })), notify: vi.fn(async () => undefined), @@ -62,8 +61,12 @@ describe("AcpConnection — request() maps method strings to library calls", () await acp.request("session/prompt", { sessionId: "sess-1", prompt: [] }); expect(conn.prompt).toHaveBeenCalledWith({ sessionId: "sess-1", prompt: [] }); + // `session/set_model` is NOT a typed SDK method — it rides the generic arm. await acp.request("session/set_model", { sessionId: "sess-1", modelId: "m" }); - expect(conn.setSessionModel).toHaveBeenCalledWith({ sessionId: "sess-1", modelId: "m" }); + expect(conn.request).toHaveBeenCalledWith("session/set_model", { + sessionId: "sess-1", + modelId: "m" + }); await acp.request("session/set_mode", { sessionId: "sess-1", modeId: "auto" }); expect(conn.setSessionMode).toHaveBeenCalledWith({ sessionId: "sess-1", modeId: "auto" }); @@ -291,3 +294,36 @@ rl.on("line", (line) => { } }); }); + +/** Every method `AcpAgentConnection` declares, as a runtime list. Kept in step + * with the interface by the two type assertions below — the array may not name + * a key the interface lacks, and `Unlisted` may not resolve to anything. */ +const ACP_CONNECTION_METHODS = [ + "initialize", + "newSession", + "loadSession", + "prompt", + "cancel", + "setSessionMode", + "authenticate", + "request", + "notify" +] as const satisfies readonly (keyof AcpAgentConnection)[]; + +type Unlisted = Exclude; +const _everyInterfaceMethodIsListed: [Unlisted] extends [never] ? true : never = true; +void _everyInterfaceMethodIsListed; + +describe("AcpAgentConnection is satisfied by the real ClientSideConnection", () => { + // `createConnection` attaches the SDK's ClientSideConnection with an + // `as unknown as AcpAgentConnection` cast, which erases the structural check. + // So a name on the interface that the SDK does not implement type-checks, and + // then throws "conn. is not a function" on a user's machine. That + // shipped: the interface (and its hand-written stub) carried + // `setSessionModel`, which ACP 1.3 does not have, so every ACP model + // selection failed before reaching the agent. Assert against the real class, + // not a stub that can agree with a wrong interface. + it.each(ACP_CONNECTION_METHODS)("ClientSideConnection implements %s", (method) => { + expect(typeof ClientSideConnection.prototype[method]).toBe("function"); + }); +}); diff --git a/packages/agent-acp/test/model-selection-route.test.ts b/packages/agent-acp/test/model-selection-route.test.ts new file mode 100644 index 0000000..7110c3d --- /dev/null +++ b/packages/agent-acp/test/model-selection-route.test.ts @@ -0,0 +1,114 @@ +import { describe, expect, it } from "vitest"; +import { AcpAgentClient } from "../src/acp-client"; +import { geminiStrategy, kimiStrategy } from "../src/strategies/index"; +import { FakeAcpAgentTransport } from "./fake-acp-agent"; + +/** Kimi Code CLI 0.29.2's REAL `session/new` result, trimmed to the model bits. + * Note what is NOT here: any `models` capability. Kimi exposes model choice + * ONLY as a config option, which is also the shape ACP 1.3 standardized on — + * `session/set_model` is absent from the SDK's `AGENT_METHODS` entirely. */ +const KIMI_SESSION_NEW = { + sessionId: "session-1", + configOptions: [ + { + type: "select", + id: "model", + name: "Model", + category: "model", + currentValue: "kimi-code/kimi-for-coding", + options: [ + { value: "kimi-code/kimi-for-coding", name: "K2.7 Coding" }, + { value: "kimi-code/k3", name: "K3" } + ] + } + ] +}; + +/** The older shape: an agent that advertises a first-class `models` capability. */ +const LEGACY_SESSION_NEW = { + sessionId: "session-1", + models: { + currentModelId: "gemini-2.5-flash", + availableModels: [{ id: "gemini-2.5-flash" }, { id: "gemini-2.5-pro" }] + } +}; + +function modelWrites(transport: FakeAcpAgentTransport): Array<{ + method: string; + params?: Record; +}> { + return transport.requests.filter( + (r) => r.method === "session/set_config_option" || r.method === "session/set_model" + ); +} + +describe("model selection routes by how the agent advertises it", () => { + it("sends a config-option write for an agent that has no models capability", async () => { + const transport = new FakeAcpAgentTransport({ + "session/new": KIMI_SESSION_NEW, + "session/set_config_option": {} + }); + const client = new AcpAgentClient({ transport, strategy: kimiStrategy }); + + const result = await client.startThread({ model: "kimi-code/k3" }); + + expect(modelWrites(transport)).toEqual([ + { + method: "session/set_config_option", + params: { sessionId: "session-1", configId: "model", value: "kimi-code/k3" } + } + ]); + // The selection applied, so the EFFECTIVE model is the requested one — not + // the `currentValue` the session opened with. + expect(result.model).toBe("kimi-code/k3"); + }); + + it("still uses session/set_model for an agent that advertises availableModels", async () => { + const transport = new FakeAcpAgentTransport({ + "session/new": LEGACY_SESSION_NEW, + "session/set_model": {} + }); + const client = new AcpAgentClient({ transport, strategy: geminiStrategy }); + + await client.startThread({ model: "gemini-2.5-pro" }); + + expect(modelWrites(transport)).toEqual([ + { + method: "session/set_model", + params: { sessionId: "session-1", modelId: "gemini-2.5-pro" } + } + ]); + }); + + it("reports the agent's own model when the config-option write is refused", async () => { + const transport = new FakeAcpAgentTransport({ + "session/new": KIMI_SESSION_NEW, + "session/set_config_option": new Error("unknown model: kimi-code/nope") + }); + const client = new AcpAgentClient({ transport, strategy: kimiStrategy }); + + const result = await client.startThread({ model: "kimi-code/nope" }); + + // A refused write must NOT be reported as applied — the session is still on + // whatever the agent opened with. + expect(result.model).toBe("kimi-code/kimi-for-coding"); + }); + + it("emits thread_settings carrying the model a config-option write selected", async () => { + const transport = new FakeAcpAgentTransport({ + "session/new": KIMI_SESSION_NEW, + "session/set_config_option": {} + }); + const client = new AcpAgentClient({ transport, strategy: kimiStrategy }); + const models: Array = []; + client.onEvent((event) => { + if (event.kind === "thread_settings") models.push(event.settings.model); + }); + + await client.startThread({ model: "kimi-code/k3" }); + + // A consumer reading `settings.model` must not have to know which route the + // agent happened to expose. + expect(models.at(-1)).toBe("kimi-code/k3"); + }); +}); From 5eeb5a5622e1387a8b3ebf1cc5eae237c6026b66 Mon Sep 17 00:00:00 2001 From: huntharo Date: Thu, 17 Sep 2026 19:14:42 -0400 Subject: [PATCH 2/2] docs(acp): correct when applyReasoning reads the refreshed capabilities MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit setModel runs in startThread; applyReasoning runs in startTurn, a later call — not "immediately after". The substance is unchanged (the model write must leave refreshed capabilities behind for reasoning to pick the right thought level), but the sequencing claim was wrong. Re-probed against Kimi Code CLI 2.0.0: still no `models` capability, so model remains a config option. Its thought levels are ["on"] under K2.7 Coding and ["low","high","max","on"] under K3. Co-Authored-By: Claude Opus 5 --- .changeset/acp-model-config-option-route.md | 2 +- packages/agent-acp/src/acp-client.ts | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/.changeset/acp-model-config-option-route.md b/.changeset/acp-model-config-option-route.md index 20f94e5..62a9016 100644 --- a/.changeset/acp-model-config-option-route.md +++ b/.changeset/acp-model-config-option-route.md @@ -10,7 +10,7 @@ The declaration and its dispatch case are gone. `session/set_model` now rides `d **The routing.** `setModel` now picks its route from the advertised capabilities: `session/set_config_option` against the `model` option (`category: "model"`, or a literal `model` id) when the agent publishes no `models.availableModels`, and `session/set_model` when it does. This is the write twin of a distinction the read path has always made — `modelIdFromCapabilities` and `modelsFromCapabilities` both fall back to the config option — and the two disagreeing is what let a host list models it could not then select. -Preferring the config option is not only spec-correctness. Its reply carries the agent's full refreshed config set, so a capability-dependent step that runs straight afterwards sees the new state; `session/set_model` answers `{}` and refreshes only via an async `config_option_update` notification. That matters immediately: on Kimi, switching model changes which thought levels exist (`K2.7 Coding` offers only `on`, `K3` offers `low`/`high`/`max`), and `applyReasoning` runs off `runtimeCapabilities` right after the model is set. +Preferring the config option is not only spec-correctness. Its reply carries the agent's full refreshed config set, so a capability-dependent step that runs straight afterwards sees the new state; `session/set_model` answers `{}` and refreshes only via an async `config_option_update` notification. That matters on Kimi, where the model DETERMINES which thought levels exist — `K2.7 Coding` offers only `on`, `K3` offers `low`/`high`/`max`. `applyReasoning` picks from `runtimeCapabilities` on the following `startTurn`, so the refresh the model write leaves behind is what it reads. Measured against Kimi Code CLI 0.29.2, whose `session/new` returns a `model` config option and no `models` capability at all: `session/set_config_option {configId: "model"}` is accepted and echoes the new `currentValue`. Kimi does also still honour `session/set_model`, so for that agent the first half of this change alone restores the behaviour; the routing is what keeps it working on an agent that implements only what ACP 1.3 defines. diff --git a/packages/agent-acp/src/acp-client.ts b/packages/agent-acp/src/acp-client.ts index 2cdee9b..15cad15 100644 --- a/packages/agent-acp/src/acp-client.ts +++ b/packages/agent-acp/src/acp-client.ts @@ -777,8 +777,10 @@ export class AcpAgentClient implements AgentBackend { * disagreeing lets a host list models it cannot then select. And the config * option's REPLY carries the agent's full refreshed config set, where * `session/set_model` answers `{}` and refreshes only via an async - * notification: on Kimi the model determines which thought levels exist, and - * `applyReasoning` reads `runtimeCapabilities` immediately after this. */ + * notification. On Kimi the model DETERMINES which thought levels exist — + * `K2.7 Coding` offers only `on`, `K3` offers `low`/`high`/`max` — and + * `applyReasoning` picks from `runtimeCapabilities` on the following + * `startTurn`, so the refresh this write leaves behind is what it reads. */ async setModel(threadId: string, modelId: string): Promise { const advertisesModelsCapability = (this.runtimeCapabilities?.models?.availableModels?.length ?? 0) > 0;