@pwrdrvr/agent-acp 0.15.0 → 0.16.1

package/dist/index.d.ts

@@ -14,7 +14,16 @@ interface AcpJsonRpcTransport {
  *  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()`. */
 interface AcpAgentConnection {
     initialize(params: Record<string, unknown>): Promise<unknown>;
     newSession(params: Record<string, unknown>): Promise<unknown>;
@@ -22,7 +31,6 @@ interface AcpAgentConnection {
     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>;
@@ -301,7 +309,11 @@ type AcpPromptContentBlock = {
     mimeType: string;
     data: string;
 };
-type AcpRuntimeOptionSource = "mode" | "model" | "configOption";
+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";
 type AcpAgentClientOptions = {
     /** The transport (real stdio or a fake). */
     transport: AcpJsonRpcTransport;
@@ -372,6 +384,11 @@ declare class AcpAgentClient implements AgentBackend {
     private unsubscribeRequest;
     private initialized;
     private runtimeCapabilities?;
+    /** What `initialize` reported: agent-level, and never any one session's. The
+     *  base a session's own menus are built on — the client-wide snapshot above is
+     *  whichever session wrote last, and a fresh session must not inherit its
+     *  menus or their current values. */
+    private initializeCapabilities?;
     constructor(options: AcpAgentClientOptions);
     private readonly clientName;
     private readonly clientTitle;
@@ -389,8 +406,9 @@ declare 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.
@@ -480,6 +498,25 @@ declare class AcpAgentClient implements AgentBackend {
      *  releasing here never blocks resume. */
     archiveThread(threadId: string): Promise<void>;
     setMode(threadId: string, modeId: string): Promise<void>;
+    /** 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 THIS session's menus on the following
+     *  `startTurn`, so the refresh this write leaves behind is what it reads. */
     setModel(threadId: string, modelId: string): Promise<void>;
     setConfigOption(threadId: string, optionId: string, value: string): Promise<void>;
     close(): Promise<void>;
@@ -505,7 +542,17 @@ declare class AcpAgentClient implements AgentBackend {
     /** Read an image file and build an ACP `image` content block (base64 + inferred
      *  mimeType). Throws on read failure; the caller catches + skips. */
     private imageBlockFromPath;
+    /** Normalize `result` into a capability snapshot, filling what it omits from
+     *  `base`. Required, not defaulted: an explicit `undefined` would trigger a
+     *  default parameter, and the only default on hand is the client-wide
+     *  snapshot — which may be another session's. */
     private captureRuntimeCapabilities;
+    /** The option menus to consult when choosing a value for `threadId`. A
+     *  session with none of its own gets the agent-level `initialize` menus, never
+     *  another session's. */
+    private sessionCapabilities;
+    /** What a session's menus are built on: its own, or `initialize`'s. */
+    private sessionBase;
     private notifyRuntimeCapabilities;
     private emitThreadSettings;
     private requireSession;
@@ -518,9 +565,10 @@ declare class AcpAgentClient implements AgentBackend {
     supportsSseMcp(): boolean;
 }
 /** Pick the value to set on a "thinking" config option for a neutral reasoning
- *  token: low-effort → the OFF-like value, high-effort → the ON-like value.
- *  Returns undefined when the token isn't an effort signal we recognize, or the
- *  option has no value of the needed polarity (caller leaves the option alone).
+ *  token: high-effort → the ON-like value; low-effort → the OFF-like value, or,
+ *  when the agent offers only graded levels, the LOW one — the closest thing to
+ *  off it has. Returns undefined when the token isn't an effort signal we
+ *  recognize, or the option has no value to match (caller leaves it alone).
  *  Exported for testing. */
 declare function reasoningValueForThoughtLevel(reasoning: string, values: ReadonlyArray<AcpRuntimeConfigOptionValue>): string | undefined;
 

package/dist/index.js

@@ -144,8 +144,9 @@ var AcpConnection = class {
         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 {};
@@ -701,9 +702,10 @@ function acpRuntimeSupportsSseMcp(capabilities) {
   return capabilities?.agentCapabilities?.mcp?.sse === true;
 }
 function modelConfigOption(capabilities) {
-  return capabilities?.configOptions?.find(
-    (option) => option.category === "model" || option.id === "model"
-  );
+  return capabilities?.configOptions?.find(isModelConfigOption);
+}
+function isModelConfigOption(option) {
+  return option.category === "model" || option.id === "model";
 }
 function modelIdFromCapabilities(capabilities) {
   return capabilities?.models?.currentModelId ?? modelConfigOption(capabilities)?.currentValue;
@@ -750,6 +752,8 @@ function acpSessionRuntimeStateFromUpdate(update, now) {
     return currentModeId ? { currentModeId, updatedAt: now } : void 0;
   }
   if (kind === "config_option_update") {
+    const fullSet = configOptionUpdateSet(update);
+    if (fullSet !== void 0) return runtimeStateFromConfigOptionSet(fullSet, now);
     const configOption = asRecord(update.configOption ?? update.config_option) ?? update;
     const id = readString(configOption, "id") ?? readString(configOption, "configOptionId") ?? readString(configOption, "configId");
     const value = readString(configOption, "currentValue") ?? readString(configOption, "value");
@@ -767,6 +771,24 @@ function mergeAcpRuntimeState(existing, update) {
     }
   };
 }
+function configOptionUpdateSet(update) {
+  if (readKind(update) !== "config_option_update") return void 0;
+  const set = update.configOptions ?? update.config_options;
+  return Array.isArray(set) ? set : void 0;
+}
+function runtimeStateFromConfigOptionSet(set, now) {
+  const options = readConfigOptions(set);
+  const configValues = Object.fromEntries(
+    options.flatMap(
+      (option) => option.currentValue !== void 0 ? [[option.id, option.currentValue]] : []
+    )
+  );
+  if (Object.keys(configValues).length === 0) return void 0;
+  const state = { configValues, updatedAt: now };
+  const model = options.find(isModelConfigOption)?.currentValue;
+  if (model !== void 0) state.currentModelId = model;
+  return state;
+}
 function modeLabelFor(capabilities, modeId) {
   return capabilities?.modes?.availableModes.find((mode) => mode.id === modeId)?.label;
 }
@@ -1005,6 +1027,11 @@ var AcpAgentClient = class {
   unsubscribeRequest = void 0;
   initialized = false;
   runtimeCapabilities;
+  /** What `initialize` reported: agent-level, and never any one session's. The
+   *  base a session's own menus are built on — the client-wide snapshot above is
+   *  whichever session wrote last, and a fresh session must not inherit its
+   *  menus or their current values. */
+  initializeCapabilities;
   constructor(options) {
     this.transport = options.transport;
     this.strategy = options.strategy;
@@ -1061,8 +1088,9 @@ var AcpAgentClient = class {
    * 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.
@@ -1217,6 +1245,7 @@ var AcpAgentClient = class {
         normalizer: new AcpSessionNormalizer({ quirks: this.strategy.quirks }),
         turnId: void 0,
         runtimeState: void 0,
+        runtimeCapabilities: void 0,
         pendingTurn: void 0,
         pendingInstructions: options.instructions,
         mcpServerNames: configuredMcpServers.map((server) => server.name)
@@ -1258,6 +1287,7 @@ var AcpAgentClient = class {
       normalizer: new AcpSessionNormalizer({ quirks: this.strategy.quirks }),
       turnId: void 0,
       runtimeState: void 0,
+      runtimeCapabilities: void 0,
       pendingTurn: void 0,
       pendingInstructions: options.instructions,
       // Remember ONLY the MCP servers attached to THIS session so the host's
@@ -1270,9 +1300,11 @@ var AcpAgentClient = class {
     }
     const runtimeCapabilities = this.captureRuntimeCapabilities(
       options.lifecycle === "load" ? "session-load" : "session-new",
-      result
+      result,
+      this.sessionBase(session)
     );
     if (runtimeCapabilities) {
+      session.runtimeCapabilities = runtimeCapabilities;
       const runtimeState = acpSessionRuntimeStateFromCapabilities(
         runtimeCapabilities,
         this.now()
@@ -1440,7 +1472,33 @@ var AcpAgentClient = class {
   async setMode(threadId, modeId) {
     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 THIS session's menus on the following
+   *  `startTurn`, so the refresh this write leaves behind is what it reads. */
   async setModel(threadId, modelId) {
+    const capabilities = this.sessionCapabilities(threadId);
+    const advertisesModelsCapability = (capabilities?.models?.availableModels?.length ?? 0) > 0;
+    const option = modelConfigOption(capabilities);
+    if (!advertisesModelsCapability && option !== void 0) {
+      await this.setRuntimeOption(threadId, "modelConfigOption", option.id, modelId);
+      return;
+    }
     await this.setRuntimeOption(threadId, "model", modelId, modelId);
   }
   async setConfigOption(threadId, optionId, value) {
@@ -1489,8 +1547,13 @@ var AcpAgentClient = class {
       },
       ACP_REQUEST_TIMEOUT_MS
     );
-    const runtimeCapabilities = this.captureRuntimeCapabilities("initialize", result);
+    const runtimeCapabilities = this.captureRuntimeCapabilities(
+      "initialize",
+      result,
+      this.initializeCapabilities
+    );
     if (runtimeCapabilities) {
+      this.initializeCapabilities = runtimeCapabilities;
       this.notifyRuntimeCapabilities({ runtimeCapabilities });
     }
     this.initialized = true;
@@ -1516,17 +1579,28 @@ var AcpAgentClient = class {
       this.logger.debug("acp session/update for unknown session", { protocolSessionId });
       return;
     }
+    if (configOptionUpdateSet(update) !== void 0) {
+      const refreshed = this.captureRuntimeCapabilities(
+        // A live refresh of this session's menus, not a load: keep the source
+        // they were opened with.
+        session.runtimeCapabilities?.source ?? "session-new",
+        update,
+        this.sessionBase(session)
+      );
+      if (refreshed) session.runtimeCapabilities = refreshed;
+    }
     const runtimeState = acpSessionRuntimeStateFromUpdate(update, this.now());
     if (runtimeState) {
       session.runtimeState = mergeAcpRuntimeState(session.runtimeState, runtimeState);
-      if (this.runtimeCapabilities) {
+      const capabilities = this.sessionCapabilities(session.threadId);
+      if (capabilities) {
         this.notifyRuntimeCapabilities({
           threadId: session.threadId,
-          runtimeCapabilities: this.runtimeCapabilities,
+          runtimeCapabilities: capabilities,
           runtimeState: session.runtimeState
         });
       }
-      this.emitThreadSettings(session, this.runtimeCapabilities, session.runtimeState);
+      this.emitThreadSettings(session, capabilities, session.runtimeState);
       return;
     }
     const updateKind = readString2(update, "sessionUpdate");
@@ -1596,10 +1670,30 @@ var AcpAgentClient = class {
       optionId,
       value
     );
-    const runtimeCapabilities = this.captureRuntimeCapabilities("session-load", result);
-    const requested = source === "configOption" ? { configValues: { [optionId]: value }, updatedAt: this.now() } : source === "mode" ? { currentModeId: value, updatedAt: this.now() } : { currentModelId: value, updatedAt: this.now() };
+    const runtimeCapabilities = this.captureRuntimeCapabilities(
+      "session-load",
+      result,
+      this.sessionBase(session)
+    );
+    if (runtimeCapabilities) session.runtimeCapabilities = runtimeCapabilities;
+    const requested = source === "configOption" ? { configValues: { [optionId]: value }, updatedAt: this.now() } : source === "mode" ? { currentModeId: 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;
+    const reply = asRecord2(result);
+    const reported = runtimeStateFromConfigOptionSet(
+      reply?.configOptions ?? reply?.config_options,
+      this.now()
+    );
+    if (reported) session.runtimeState = mergeAcpRuntimeState(session.runtimeState, reported);
+    const effectiveCapabilities = this.sessionCapabilities(threadId);
     if (effectiveCapabilities) {
       this.notifyRuntimeCapabilities({
         threadId,
@@ -1610,7 +1704,7 @@ var AcpAgentClient = class {
     this.emitThreadSettings(session, effectiveCapabilities, session.runtimeState);
   }
   async setRuntimeOptionOnTransport(protocolSessionId, source, optionId, value) {
-    if (source === "configOption") {
+    if (source === "configOption" || source === "modelConfigOption") {
       return await this.transport.request("session/set_config_option", {
         sessionId: protocolSessionId,
         configId: optionId,
@@ -1640,7 +1734,8 @@ var AcpAgentClient = class {
    *  If nothing matches we leave it alone — the caller's `.catch` debug-logs. */
   async applyReasoning(threadId, reasoning) {
     const target = reasoning.toLowerCase();
-    const modes = this.runtimeCapabilities?.modes?.availableModes ?? [];
+    const capabilities = this.sessionCapabilities(threadId);
+    const modes = capabilities?.modes?.availableModes ?? [];
     const modeMatch = modes.find(
       (mode) => mode.id.toLowerCase() === target || typeof mode.label === "string" && mode.label.toLowerCase() === target
     );
@@ -1648,7 +1743,7 @@ var AcpAgentClient = class {
       await this.setMode(threadId, modeMatch.id);
       return;
     }
-    const thinking = this.runtimeCapabilities?.configOptions?.find(
+    const thinking = capabilities?.configOptions?.find(
       (option) => option.category === "thought_level" || option.id === "thinking"
     );
     if (thinking !== void 0) {
@@ -1678,18 +1773,32 @@ var AcpAgentClient = class {
       data: data.toString("base64")
     };
   }
-  captureRuntimeCapabilities(source, result) {
+  /** Normalize `result` into a capability snapshot, filling what it omits from
+   *  `base`. Required, not defaulted: an explicit `undefined` would trigger a
+   *  default parameter, and the only default on hand is the client-wide
+   *  snapshot — which may be another session's. */
+  captureRuntimeCapabilities(source, result, base) {
     const runtimeCapabilities = normalizeAcpRuntimeCapabilities({
       value: result,
       now: this.now(),
       source,
-      ...this.runtimeCapabilities !== void 0 ? { initialize: this.runtimeCapabilities } : {}
+      ...base !== void 0 ? { initialize: base } : {}
     });
     if (runtimeCapabilities) {
       this.runtimeCapabilities = runtimeCapabilities;
     }
     return runtimeCapabilities;
   }
+  /** The option menus to consult when choosing a value for `threadId`. A
+   *  session with none of its own gets the agent-level `initialize` menus, never
+   *  another session's. */
+  sessionCapabilities(threadId) {
+    return this.sessionBase(this.sessions.get(threadId));
+  }
+  /** What a session's menus are built on: its own, or `initialize`'s. */
+  sessionBase(session) {
+    return session?.runtimeCapabilities ?? this.initializeCapabilities;
+  }
   notifyRuntimeCapabilities(event) {
     this.runtimeCapabilitiesHandler?.({
       ...event.threadId !== void 0 ? { threadId: event.threadId } : {},
@@ -1767,6 +1876,7 @@ function thoughtLevelPolarity(value) {
   const haystack = `${value.value} ${value.label ?? ""}`.toLowerCase();
   if (/\b(off|none|disabled?|no)\b/.test(haystack)) return "off";
   if (/\b(on|enabled?|high|full|yes)\b/.test(haystack)) return "on";
+  if (/\b(low|minimal|min|minimum)\b/.test(haystack)) return "low";
   return "other";
 }
 function reasoningValueForThoughtLevel(reasoning, values) {
@@ -1774,8 +1884,9 @@ function reasoningValueForThoughtLevel(reasoning, values) {
   const wantOff = LOW_EFFORT_TOKENS.has(token);
   const wantOn = HIGH_EFFORT_TOKENS.has(token);
   if (!wantOff && !wantOn) return void 0;
-  const desired = wantOff ? "off" : "on";
-  return values.find((value) => thoughtLevelPolarity(value) === desired)?.value;
+  const withPolarity = (polarity) => values.find((value) => thoughtLevelPolarity(value) === polarity);
+  if (wantOn) return withPolarity("on")?.value;
+  return (withPolarity("off") ?? withPolarity("low"))?.value;
 }
 function buildApprovalRequest(args) {
   const toolCall = asRecord2(args.params.toolCall) ?? {};