Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions .changeset/acp-model-config-option-route.md
Original file line number Diff line number Diff line change
@@ -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 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.

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`.
54 changes: 49 additions & 5 deletions packages/agent-acp/src/acp-client.ts
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ import {
acpSessionRuntimeStateFromUpdate,
mergeAcpRuntimeState,
modeLabelFor,
modelConfigOption,
modelIdFromCapabilities,
normalizeAcpRuntimeCapabilities,
type AcpRuntimeCapabilities,
Expand All @@ -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). */
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -753,7 +762,33 @@ 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 —
* `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<void> {
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);
}

Expand Down Expand Up @@ -985,7 +1020,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) {
Expand All @@ -1006,7 +1050,7 @@ export class AcpAgentClient implements AgentBackend {
optionId: string,
value: string
): Promise<unknown> {
if (source === "configOption") {
if (source === "configOption" || source === "modelConfigOption") {
return await this.transport.request("session/set_config_option", {
sessionId: protocolSessionId,
configId: optionId,
Expand Down
17 changes: 13 additions & 4 deletions packages/agent-acp/src/acp-connection.ts
Original file line number Diff line number Diff line change
Expand Up @@ -35,15 +35,23 @@ 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.<name> 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<string, unknown>): Promise<unknown>;
newSession(params: Record<string, unknown>): Promise<unknown>;
loadSession(params: Record<string, unknown>): Promise<unknown>;
prompt(params: Record<string, unknown>): Promise<unknown>;
cancel(params: Record<string, unknown>): Promise<void>;
setSessionMode(params: Record<string, unknown>): Promise<unknown>;
setSessionModel(params: Record<string, unknown>): Promise<unknown>;
authenticate(params: Record<string, unknown>): Promise<unknown>;
request(method: string, params: Record<string, unknown>): Promise<unknown>;
notify(method: string, params: Record<string, unknown>): Promise<void>;
Expand Down Expand Up @@ -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 {};
Expand Down
42 changes: 39 additions & 3 deletions packages/agent-acp/test/acp-connection.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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. */
Expand All @@ -14,7 +14,6 @@ function stubConnection(overrides: Partial<AcpAgentConnection> = {}): 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),
Expand Down Expand Up @@ -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" });
Expand Down Expand Up @@ -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<keyof AcpAgentConnection, (typeof ACP_CONNECTION_METHODS)[number]>;
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.<name> 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");
});
});
114 changes: 114 additions & 0 deletions packages/agent-acp/test/model-selection-route.test.ts
Original file line number Diff line number Diff line change
@@ -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<string, unknown>;
}> {
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<string | undefined> = [];
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");
});
});
Loading