@vellumai/assistant 0.12.1 → 0.12.2-staging.1

package/src/acp/agent-process.test.ts

@@ -194,7 +194,10 @@ describe("AcpAgentProcess.createSession auth_required handling", () => {
       },
     });
 
-    await expect(proc.createSession("/tmp")).resolves.toBe("session-1");
+    await expect(proc.createSession("/tmp")).resolves.toEqual({
+      sessionId: "session-1",
+      configOptions: [],
+    });
     expect(authenticateCalls()).toBe(1);
   });
 

package/src/acp/agent-process.ts

@@ -6,6 +6,7 @@
  */
 
 import { type ChildProcess, spawn } from "node:child_process";
+import { basename } from "node:path";
 import { Readable, Writable } from "node:stream";
 
 import type {
@@ -14,14 +15,25 @@ import type {
   AuthMethodEnvVar,
   Client,
   InitializeResponse,
+  LoadSessionResponse,
   NewSessionResponse,
   PromptResponse,
+  ResumeSessionResponse,
+  SessionConfigOption,
+  SetSessionConfigOptionRequest,
 } from "@agentclientprotocol/sdk";
 import * as acp from "@agentclientprotocol/sdk";
 
 import { getLogger } from "../util/logger.js";
-import { AcpAuthRequiredError, isAcpAuthRequired } from "./auth-required.js";
-import type { AcpAgentConfig } from "./types.js";
+import { safeStringSlice } from "../util/unicode.js";
+import {
+  AcpAuthRequiredError,
+  CLAUDE_ACP_COMMAND,
+  isAcpAuthRequired,
+  isClaudeAuthFailureMessage,
+  requestErrorReason,
+} from "./auth-required.js";
+import { type AcpAgentConfig, AcpConfigOptionRefusedError } from "./types.js";
 
 const log = getLogger("acp");
 
@@ -32,6 +44,16 @@ const log = getLogger("acp");
  */
 const STDERR_RETENTION_BYTES = 4096;
 
+/**
+ * Normalizes the SDK's optional-and-nullable config-option field to an array,
+ * so every session call hands its caller the same shape.
+ */
+function normalizeConfigOptions(
+  configOptions: SessionConfigOption[] | null | undefined,
+): SessionConfigOption[] {
+  return configOptions ?? [];
+}
+
 function isEnvVarMethod(
   method: AuthMethod,
 ): method is AuthMethodEnvVar & { type: "env_var" } {
@@ -142,7 +164,7 @@ export class AcpAgentProcess {
     // deriveFailureError reads from the end, so dropping the head is lossless.
     const line =
       text.length > STDERR_RETENTION_BYTES
-        ? text.slice(-STDERR_RETENTION_BYTES)
+        ? safeStringSlice(text, text.length - STDERR_RETENTION_BYTES)
         : text;
     this.stderrSeq += 1;
     this.stderrRing.push({ seq: this.stderrSeq, text: line });
@@ -355,16 +377,21 @@ export class AcpAgentProcess {
 
   /**
    * Creates a new ACP session in the specified working directory.
-   * Returns the session ID.
+   * Returns the session ID and the config options the agent reported.
    */
-  async createSession(cwd: string): Promise<string> {
+  async createSession(
+    cwd: string,
+  ): Promise<{ sessionId: string; configOptions: SessionConfigOption[] }> {
     log.info({ agentId: this.agentId, cwd }, "Creating ACP session");
 
     const result: NewSessionResponse = await this.withAuthRetry(() =>
       this.requireConnection().newSession({ cwd, mcpServers: [] }),
     );
 
-    return result.sessionId;
+    return {
+      sessionId: result.sessionId,
+      configOptions: normalizeConfigOptions(result.configOptions),
+    };
   }
 
   /**
@@ -375,12 +402,17 @@ export class AcpAgentProcess {
    * callers should suppress forwarding of those replayed updates (see
    * VellumAcpClientHandler.beginReplaySuppression).
    */
-  async loadSession(sessionId: string, cwd: string): Promise<void> {
+  async loadSession(
+    sessionId: string,
+    cwd: string,
+  ): Promise<{ configOptions: SessionConfigOption[] }> {
     log.info({ agentId: this.agentId, sessionId, cwd }, "Loading ACP session");
 
-    await this.withAuthRetry(() =>
+    const result: LoadSessionResponse = await this.withAuthRetry(() =>
       this.requireConnection().loadSession({ sessionId, cwd, mcpServers: [] }),
     );
+
+    return { configOptions: normalizeConfigOptions(result.configOptions) };
   }
 
   /**
@@ -390,16 +422,70 @@ export class AcpAgentProcess {
    * preferred when the agent advertises the capability
    * (see supportsSessionResume).
    */
-  async resumeSession(sessionId: string, cwd: string): Promise<void> {
+  async resumeSession(
+    sessionId: string,
+    cwd: string,
+  ): Promise<{ configOptions: SessionConfigOption[] }> {
     log.info({ agentId: this.agentId, sessionId, cwd }, "Resuming ACP session");
 
-    await this.withAuthRetry(() =>
+    const result: ResumeSessionResponse = await this.withAuthRetry(() =>
       this.requireConnection().resumeSession({
         sessionId,
         cwd,
         mcpServers: [],
       }),
     );
+
+    return { configOptions: normalizeConfigOptions(result.configOptions) };
+  }
+
+  /**
+   * Sets one session config option (e.g. the model selector) via
+   * `session/set_config_option`. The agent answers with the full refreshed
+   * option set, which is returned to the caller.
+   *
+   * A boolean value sends the `type: "boolean"` request variant; a string
+   * sends the value-id variant.
+   */
+  async setConfigOption(
+    sessionId: string,
+    configId: string,
+    value: string | boolean,
+  ): Promise<SessionConfigOption[]> {
+    log.info(
+      { agentId: this.agentId, sessionId, configId, value },
+      "Setting ACP session config option",
+    );
+
+    const request: SetSessionConfigOptionRequest =
+      typeof value === "boolean"
+        ? { sessionId, configId, type: "boolean", value }
+        : { sessionId, configId, value };
+
+    const response = await this.withAuthRetry(async () => {
+      try {
+        return await this.requireConnection().setSessionConfigOption(request);
+      } catch (err) {
+        // Wrapped here, at the request itself, so `withAuthRetry` still sees
+        // an auth_required answer and a caller cannot confuse the adapter's
+        // refusal with a transport or authentication failure. Claude's
+        // expired-token failure travels as a generic error whose reason is
+        // the only signal, so under the Claude adapter it is left for the
+        // caller to classify.
+        if (err instanceof acp.RequestError && !isAcpAuthRequired(err)) {
+          const reason = requestErrorReason(err);
+          const claudeAuthFailure =
+            basename(this.config.command) === CLAUDE_ACP_COMMAND &&
+            isClaudeAuthFailureMessage(reason);
+          if (!claudeAuthFailure) {
+            throw new AcpConfigOptionRefusedError(reason);
+          }
+        }
+        throw err;
+      }
+    });
+
+    return normalizeConfigOptions(response.configOptions);
   }
 
   /**

package/src/acp/auth-required.ts

@@ -8,7 +8,8 @@
  * 2. Credentials present but rejected (the expired/revoked case): the CLI
  *    surfaces the API 401 as an error message it authors, and the adapter
  *    relays it as a generic -32603 internal error, NOT as `auth_required`.
- *    {@link isClaudeAuthFailureMessage}.
+ *    {@link isClaudeAuthFailureMessage}, over the text
+ *    {@link requestErrorReason} decodes out of the rejection.
  *
  * A positive detection becomes {@link ACP_CLAUDE_AUTH_REQUIRED_CODE} on the
  * `acp_auth_required` event, which the client turns into the inline
@@ -81,6 +82,54 @@ export function isClaudeAuthFailureMessage(
   );
 }
 
+/** Messages the SDK's `RequestError` factories build when given no text. */
+const GENERIC_RPC_MESSAGES: ReadonlySet<string> = new Set([
+  "Parse error",
+  "Invalid request",
+  "Invalid params",
+  "Internal error",
+  "Request cancelled",
+  "Authentication required",
+  "Resource not found",
+]);
+
+/**
+ * The sentence behind a JSON-RPC rejection. An adapter that throws a plain
+ * Error reaches the client as a bare "Internal error" whose real text the
+ * agent-side SDK moved into `data.details`. An adapter that raises
+ * `RequestError.internalError(data, text)` keeps its words in the message and
+ * only supplemental context in `data`, so a specific message wins. Behind a
+ * generic message such as "Invalid params", `data.details` or the serialized
+ * payload supplies the reason instead. Duck-typed like
+ * {@link isAcpAuthRequired}:
+ * `message` is read as a property, so a rejection that arrives as a plain
+ * object off the wire decodes the same as an `Error` instance.
+ */
+export function requestErrorReason(err: unknown): string {
+  if (typeof err !== "object" || err === null) {
+    return String(err);
+  }
+  const { data, message } = err as { data?: unknown; message?: unknown };
+  const own = typeof message === "string" ? message : String(err);
+  if (data == null) {
+    return own;
+  }
+  if (
+    typeof message === "string" &&
+    message.length > 0 &&
+    !GENERIC_RPC_MESSAGES.has(message)
+  ) {
+    return message;
+  }
+  const details = (data as { details?: unknown }).details;
+  if (typeof details === "string" && details.length > 0) {
+    return details;
+  }
+  // JSON.stringify answers undefined for a value it cannot represent.
+  const serialized: string | undefined = JSON.stringify(data);
+  return serialized ?? own;
+}
+
 /** The adapter whose auth failures the Connect Claude flow can repair. */
 export const CLAUDE_ACP_COMMAND = "claude-agent-acp";
 

package/src/acp/auto-install.test.ts

@@ -78,7 +78,7 @@ describe("ensureAdapterInstalled", () => {
     expect(args).toEqual([
       "add",
       "--global",
-      "@agentclientprotocol/claude-agent-acp",
+      "@agentclientprotocol/claude-agent-acp@0.75.1",
     ]);
   });
 
@@ -198,8 +198,8 @@ describe("ensureAdapterInstalled", () => {
       (call) => (call[1] as string[])[2],
     );
     expect(installedPackages.sort()).toEqual([
-      "@agentclientprotocol/claude-agent-acp",
-      "@agentclientprotocol/codex-acp",
+      "@agentclientprotocol/claude-agent-acp@0.75.1",
+      "@agentclientprotocol/codex-acp@1.10.0",
     ]);
   });
 });
@@ -232,7 +232,7 @@ describe("resolveAgentWithAutoInstall - resolution order", () => {
     // The resolved command is the REAL binary, not a `bun x` wrapper.
     expect(result.resolved.agent.command).toBe("claude-agent-acp");
     expect(result.autoInstalledPackage).toBe(
-      "@agentclientprotocol/claude-agent-acp",
+      "@agentclientprotocol/claude-agent-acp@0.75.1",
     );
     expect(result.failureMessage).toBeUndefined();
     expect(execFileMock).toHaveBeenCalledTimes(1);
@@ -264,12 +264,14 @@ describe("resolveAgentWithAutoInstall - resolution order", () => {
       return;
     }
     expect(result.resolved.agent.command).toBe("codex-acp");
-    expect(result.autoInstalledPackage).toBe("@agentclientprotocol/codex-acp");
+    expect(result.autoInstalledPackage).toBe(
+      "@agentclientprotocol/codex-acp@1.10.0",
+    );
     expect(execFileMock).toHaveBeenCalledTimes(1);
     expect(execFileMock.mock.calls[0][1]).toEqual([
       "add",
       "--global",
-      "@agentclientprotocol/codex-acp",
+      "@agentclientprotocol/codex-acp@1.10.0",
     ]);
   });
 
@@ -295,7 +297,7 @@ describe("resolveAgentWithAutoInstall - resolution order", () => {
     expect(result.resolved.ok).toBe(false);
     expect(result.failureMessage).toContain("claude-agent-acp is not on PATH");
     expect(result.failureMessage).toContain(
-      "bun add -g @agentclientprotocol/claude-agent-acp",
+      "bun add -g @agentclientprotocol/claude-agent-acp@0.75.1",
     );
     expect(result.failureMessage).toContain("network is down");
     for (const call of execFileMock.mock.calls) {

package/src/acp/client-handler.ts

@@ -21,6 +21,7 @@ import type {
   ReleaseTerminalResponse,
   RequestPermissionRequest,
   RequestPermissionResponse,
+  SessionConfigOption,
   SessionNotification,
   TerminalOutputRequest,
   TerminalOutputResponse,
@@ -103,6 +104,9 @@ export class VellumAcpClientHandler implements Client {
     private readonly acpSessionId: string,
     private readonly sendToVellum: (msg: AssistantEvent) => void,
     private readonly parentConversationId: string,
+    private readonly onConfigOptions?: (
+      configOptions: SessionConfigOption[],
+    ) => void,
   ) {}
 
   /** Forwards an update to Vellum, stamping a contiguous per-session `seq`. */
@@ -182,7 +186,12 @@ export class VellumAcpClientHandler implements Client {
   async sessionUpdate(params: SessionNotification): Promise<void> {
     const update = params.update;
 
-    if (this.suppressForwarding) {
+    // Config options are current state rather than transcript history, so they
+    // are applied even while a replay is being suppressed.
+    if (
+      this.suppressForwarding &&
+      update.sessionUpdate !== "config_option_update"
+    ) {
       log.debug(
         { acpSessionId: this.acpSessionId, updateType: update.sessionUpdate },
         "Dropping replayed session update during suppression",
@@ -286,10 +295,14 @@ export class VellumAcpClientHandler implements Client {
         break;
       }
 
+      case "config_option_update": {
+        this.onConfigOptions?.(update.configOptions);
+        break;
+      }
+
       default: {
         // Other update types (available_commands_update, current_mode_update,
-        // config_option_update, session_info_update) are not forwarded to
-        // Vellum.
+        // session_info_update) are not forwarded to Vellum.
         log.debug(
           {
             acpSessionId: this.acpSessionId,

package/src/acp/model-config.test.ts

@@ -0,0 +1,166 @@
+/**
+ * Tests for the pure ACP model-config helpers: flattening an adapter's model
+ * `SessionConfigOption` into publishable model info, and the spawn-time
+ * precedence ladder.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import type { SessionConfigOption } from "@agentclientprotocol/sdk";
+
+import {
+  MODEL_OPTION_MODELS,
+  modelOption,
+} from "./__tests__/helpers/acp-model-option.js";
+import { deriveModelInfo, resolveAcpModel } from "./model-config.js";
+
+const flatModelOption = modelOption("sonnet");
+
+describe("deriveModelInfo", () => {
+  test("flattens flat options and reports the current value", () => {
+    expect(deriveModelInfo([flatModelOption])).toEqual({
+      model: "sonnet",
+      modelConfigId: "model",
+      availableModels: MODEL_OPTION_MODELS,
+    });
+  });
+
+  test("flattens grouped options and carries the group name", () => {
+    const grouped: SessionConfigOption = {
+      type: "select",
+      id: "model",
+      name: "Model",
+      category: "model",
+      currentValue: "opus",
+      options: [
+        {
+          group: "anthropic",
+          name: "Anthropic",
+          options: [
+            { value: "opus", name: "Opus" },
+            { value: "haiku", name: "Haiku", description: "Fast" },
+          ],
+        },
+        {
+          group: "aliases",
+          name: "Aliases",
+          options: [{ value: "best", name: "Best available" }],
+        },
+      ],
+    };
+
+    expect(deriveModelInfo([grouped])).toEqual({
+      model: "opus",
+      modelConfigId: "model",
+      availableModels: [
+        { value: "opus", label: "Opus", group: "Anthropic" },
+        {
+          value: "haiku",
+          label: "Haiku",
+          description: "Fast",
+          group: "Anthropic",
+        },
+        { value: "best", label: "Best available", group: "Aliases" },
+      ],
+    });
+  });
+
+  test("matches on id alone when no category is reported", () => {
+    const uncategorized: SessionConfigOption = {
+      type: "select",
+      id: "model",
+      name: "Model",
+      currentValue: "haiku",
+      options: [{ value: "haiku", name: "Haiku" }],
+    };
+
+    const info = deriveModelInfo([uncategorized]);
+
+    expect(info.modelConfigId).toBe("model");
+    expect(info.model).toBe("haiku");
+  });
+
+  test("matches on category alone when the id differs", () => {
+    const byCategory: SessionConfigOption = {
+      type: "select",
+      id: "llm",
+      name: "LLM",
+      category: "model",
+      currentValue: "gpt-5",
+      options: [{ value: "gpt-5", name: "GPT-5" }],
+    };
+
+    expect(deriveModelInfo([byCategory]).modelConfigId).toBe("llm");
+  });
+
+  test("ignores a boolean option even when its category is model", () => {
+    const booleanOption: SessionConfigOption = {
+      type: "boolean",
+      id: "model",
+      name: "Model",
+      category: "model",
+      currentValue: true,
+    };
+
+    expect(deriveModelInfo([booleanOption])).toEqual({ availableModels: [] });
+  });
+
+  test("skips non-model select options and picks the first match", () => {
+    const mode: SessionConfigOption = {
+      type: "select",
+      id: "mode",
+      name: "Mode",
+      category: "mode",
+      currentValue: "ask",
+      options: [{ value: "ask", name: "Ask" }],
+    };
+
+    expect(deriveModelInfo([mode, flatModelOption]).modelConfigId).toBe(
+      "model",
+    );
+  });
+
+  test("returns no model info for an empty array", () => {
+    expect(deriveModelInfo([])).toEqual({ availableModels: [] });
+  });
+
+  test("returns no model info for null", () => {
+    expect(deriveModelInfo(null)).toEqual({ availableModels: [] });
+  });
+
+  test("returns no model info for undefined", () => {
+    expect(deriveModelInfo(undefined)).toEqual({ availableModels: [] });
+  });
+});
+
+describe("resolveAcpModel", () => {
+  test("prefers the requested model over the per-agent one", () => {
+    expect(
+      resolveAcpModel({ requestedModel: "opus", agentModel: "haiku" }),
+    ).toBe("opus");
+  });
+
+  test("falls back to the per-agent model", () => {
+    expect(resolveAcpModel({ agentModel: "haiku" })).toBe("haiku");
+  });
+
+  test("returns undefined when every rung is unset", () => {
+    expect(resolveAcpModel({})).toBeUndefined();
+  });
+
+  test("treats blank and whitespace-only values as unset", () => {
+    expect(
+      resolveAcpModel({ requestedModel: "\t\n", agentModel: "haiku" }),
+    ).toBe("haiku");
+  });
+
+  test("returns undefined when every rung is whitespace", () => {
+    expect(
+      resolveAcpModel({ requestedModel: " ", agentModel: "  " }),
+    ).toBeUndefined();
+  });
+
+  test("trims the value it returns", () => {
+    expect(resolveAcpModel({ requestedModel: "  opus  " })).toBe("opus");
+  });
+});

package/src/acp/model-config.ts

@@ -0,0 +1,138 @@
+/**
+ * Pure helpers for ACP session model selection.
+ *
+ * ACP 0.25.0 has no `session/set_model`: a model is one `SessionConfigOption`
+ * among the set an adapter reports from `session/new`, `session/load`,
+ * `session/resume`, and `session/set_config_option`. `deriveModelInfo` turns
+ * that raw set into the trio the daemon publishes and persists (current model,
+ * selectable options, and the config id to write back through
+ * `setSessionConfigOption`), flattening the grouped `options` variant so
+ * callers never branch on it.
+ *
+ * The model option is identified by `type === "select"` and `id === "model"`
+ * or `category === "model"` only. Option `name` is a human label an adapter
+ * may localize or restyle at will, so it is never matched against.
+ *
+ * `resolveAcpModel` is the precedence ladder a spawn or a resume walks before
+ * it talks to the adapter: an explicit request beats the per-agent default from
+ * `acp.agents.<id>.model`, and nothing named there leaves the adapter on its
+ * own. Values are adapter-reported aliases (`opus`, `sonnet`), never Assistant
+ * catalog ids, and are passed through unvalidated: only the adapter knows what
+ * it accepts.
+ *
+ * Both helpers are synchronous and side-effect free.
+ */
+
+import type {
+  SessionConfigOption,
+  SessionConfigSelectGroup,
+  SessionConfigSelectOption,
+} from "@agentclientprotocol/sdk";
+import type { z } from "zod";
+
+import type { AcpSessionModelUpdateEventSchema } from "../api/events/acp-session-model-update.js";
+
+/**
+ * A selectable model as reported by the adapter, flattened out of its group.
+ * Derived from the event schema so the published wire shape and the shape the
+ * daemon carries in memory cannot drift apart.
+ */
+export type AcpModelOption = z.infer<
+  typeof AcpSessionModelUpdateEventSchema
+>["availableModels"][number];
+
+/** What an adapter's config-option set says about the session's model. */
+export type AcpModelInfo = {
+  model?: string;
+  availableModels: AcpModelOption[];
+  modelConfigId?: string;
+};
+
+type ResolveAcpModelInput = {
+  requestedModel?: string;
+  agentModel?: string;
+};
+
+type ModelSelectOption = Extract<SessionConfigOption, { type: "select" }>;
+
+function isGroup(
+  entry: SessionConfigSelectOption | SessionConfigSelectGroup,
+): entry is SessionConfigSelectGroup {
+  return "group" in entry;
+}
+
+function toModelOption(
+  option: SessionConfigSelectOption,
+  group?: string,
+): AcpModelOption {
+  return {
+    value: option.value,
+    label: option.name,
+    ...(option.description ? { description: option.description } : {}),
+    ...(group ? { group } : {}),
+  };
+}
+
+/**
+ * The adapter's model selector, if it advertises one. `category` is UX-only
+ * per the ACP spec, so a `model` id counts too; non-select options never do.
+ */
+function findModelConfigOption(
+  configOptions: SessionConfigOption[] | null | undefined,
+): ModelSelectOption | undefined {
+  return configOptions?.find(
+    (option): option is ModelSelectOption =>
+      option.type === "select" &&
+      (option.id === "model" || option.category === "model"),
+  );
+}
+
+/**
+ * Extract current model, selectable models, and the config id to write back.
+ * Returns `{ availableModels: [] }` when the adapter advertises no model
+ * selector, which is how the whole feature degrades to invisible.
+ */
+export function deriveModelInfo(
+  configOptions: SessionConfigOption[] | null | undefined,
+): AcpModelInfo {
+  const modelOption = findModelConfigOption(configOptions);
+
+  if (!modelOption) {
+    return { availableModels: [] };
+  }
+
+  const availableModels: AcpModelOption[] = [];
+  for (const entry of modelOption.options) {
+    if (isGroup(entry)) {
+      for (const option of entry.options) {
+        availableModels.push(toModelOption(option, entry.name));
+      }
+      continue;
+    }
+    availableModels.push(toModelOption(entry));
+  }
+
+  return {
+    ...(modelOption.currentValue ? { model: modelOption.currentValue } : {}),
+    availableModels,
+    modelConfigId: modelOption.id,
+  };
+}
+
+/**
+ * Pick the model a session should start on. Blank and whitespace-only values
+ * count as unset so an empty config field never pins anything.
+ */
+export function resolveAcpModel(
+  input: ResolveAcpModelInput,
+): string | undefined {
+  const ladder = [input.requestedModel, input.agentModel];
+
+  for (const candidate of ladder) {
+    const trimmed = candidate?.trim();
+    if (trimmed) {
+      return trimmed;
+    }
+  }
+  return undefined;
+}