@vellumai/assistant 0.12.1 → 0.12.2-staging.2

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/claude-token-refresh.ts

@@ -0,0 +1,150 @@
+/**
+ * Renewal policy for the Claude OAuth credential the ACP spawn path injects as
+ * `CLAUDE_CODE_OAUTH_TOKEN`. Storage lives in `acp-claude-oauth.ts`; this
+ * module owns only the decision to refresh and the handling of what comes back.
+ *
+ * Setting `CLAUDE_CODE_OAUTH_TOKEN` tells the Claude Agent SDK to treat the
+ * value as a static bearer token: its own credential store and refresh
+ * machinery are skipped entirely. The SDK does expose a host-refresh hook,
+ * `getOAuthToken`, but `claude-agent-acp` never passes it through and it is
+ * absent from the SDK's public typings. With the env-var contract the adapter
+ * gives us, the daemon is the only thing that can renew this token.
+ *
+ * Every failure mode here returns without throwing and lets the spawn proceed
+ * with whatever token is stored. A dead token then fails at the adapter as a
+ * structured ACP `auth_required`, which raises the Connect card. Renewal is
+ * the fast path, not the error path, so it must never be the thing that fails
+ * a spawn.
+ *
+ * When the provider rejects the refresh token itself (revoked, or rotated out
+ * from under us), the stored refresh token is dropped. The recorded expiry is
+ * kept, because that pair (expired, no way to renew) is what makes
+ * `hasAcpClaudeToken()` answer "not connected" and keep the inline Connect
+ * card on screen.
+ */
+
+import {
+  isCredentialError,
+  RefreshDeduplicator,
+} from "@vellumai/credential-storage";
+
+import { refreshOAuth2Token } from "../security/oauth2.js";
+import { getLogger } from "../util/logger.js";
+import {
+  CLAUDE_OAUTH_CONFIG,
+  clearAcpClaudeRefreshToken,
+  forgetAcpClaudeRenewalStateIfUnbound,
+  hasStoredAcpClaudeAccessToken,
+  isAcpClaudeTokenExpiring,
+  persistRefreshedAcpClaudeTokens,
+  readAcpClaudeRefreshToken,
+} from "./acp-claude-oauth.js";
+import { ACP_OAUTH_TOKEN_FIELD } from "./acp-credentials.js";
+import { acpSpawnCredentialDenialReason } from "./prepare-agent-env.js";
+
+const log = getLogger("acp:claude-token-refresh");
+
+/**
+ * Single in-flight refresh across concurrent spawns. Anthropic rotates the
+ * refresh token on use, so two parallel refreshes would race and one would
+ * invalidate the other's token.
+ */
+const deduplicator = new RefreshDeduplicator();
+const REFRESH_KEY = "acp:claude";
+
+/**
+ * Renew the stored Claude access token if it is expiring and a refresh token
+ * is available. Returns without throwing in every failure mode. Never returns
+ * the token: the plaintext read boundary stays with the credential broker, so
+ * callers re-read through it as usual.
+ */
+export async function ensureFreshAcpClaudeToken(): Promise<void> {
+  // An explicit `allowedTools` that omits `acp_spawn` means the broker will
+  // deny the read this renewal exists to feed, so there is nothing to gain by
+  // spending a refresh token here. Checking first also keeps a passive spawn
+  // from touching a credential the workspace has fenced off.
+  if (acpSpawnCredentialDenialReason(ACP_OAUTH_TOKEN_FIELD) !== undefined) {
+    return;
+  }
+  // Companions can outlive a deleted access token. Renewal exists to replace
+  // that field, not to mint a new credential after the user removed it.
+  if (!(await hasStoredAcpClaudeAccessToken())) {
+    return;
+  }
+  try {
+    await forgetAcpClaudeRenewalStateIfUnbound();
+  } catch (err) {
+    log.debug(
+      { err },
+      "Could not drop unbound Claude OAuth renewal state before refresh",
+    );
+  }
+  if (!(await isAcpClaudeTokenExpiring())) {
+    return;
+  }
+
+  const refreshToken = await readAcpClaudeRefreshToken();
+  if (!refreshToken) {
+    log.info(
+      "Claude OAuth token is expiring and no refresh token is stored; " +
+        "the spawn will surface auth_required so the user can reconnect",
+    );
+    return;
+  }
+
+  try {
+    await deduplicator.deduplicate(REFRESH_KEY, () => doRefresh(refreshToken));
+  } catch (err) {
+    log.debug({ err }, "Claude OAuth token refresh did not complete");
+  }
+}
+
+async function doRefresh(refreshToken: string): Promise<string> {
+  log.info("Refreshing the Claude OAuth token for ACP");
+
+  let result;
+  try {
+    result = await refreshOAuth2Token(
+      CLAUDE_OAUTH_CONFIG.tokenExchangeUrl,
+      CLAUDE_OAUTH_CONFIG.clientId,
+      refreshToken,
+      // PKCE public client, so no secret. Anthropic's token endpoint takes a
+      // JSON body, matching the authorization-code exchange.
+      undefined,
+      undefined,
+      CLAUDE_OAUTH_CONFIG.tokenExchangeBodyFormat,
+    );
+  } catch (err) {
+    if (isCredentialError(err)) {
+      log.warn(
+        { err },
+        "Claude OAuth refresh token was rejected; dropping it so the account reads as needing a reconnect",
+      );
+      await clearAcpClaudeRefreshToken(refreshToken);
+    } else {
+      log.warn({ err }, "Claude OAuth token refresh failed transiently");
+    }
+    throw err;
+  }
+
+  if (!result.accessToken) {
+    log.warn(
+      "Claude OAuth refresh returned no usable access token; dropping the refresh token so the account reads as needing a reconnect",
+    );
+    await clearAcpClaudeRefreshToken(refreshToken);
+    throw new Error("Claude OAuth refresh returned no access token");
+  }
+
+  const persisted = await persistRefreshedAcpClaudeTokens(
+    {
+      accessToken: result.accessToken,
+      refreshToken: result.refreshToken,
+      expiresIn: result.expiresIn,
+    },
+    refreshToken,
+  );
+  if (persisted) {
+    log.info("Claude OAuth token refreshed");
+  }
+  return result.accessToken;
+}

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;
+}

package/src/acp/prepare-agent-env.ts

@@ -199,6 +199,26 @@ export function acpSpawnCredentialDenialReason(
  * mode, including a simply-absent credential, as `{ success: false,
  * reason }`, so callers choose whether a miss is fatal.
  */
+/**
+ * Vault path for `CLAUDE_CODE_OAUTH_TOKEN`. Renews first so a near-expired
+ * stored token is replaced before the broker read. Config overrides never
+ * reach here, so this does not spend the vault refresh token on a spawn
+ * that will not use it.
+ */
+async function injectClaudeOauthFromVault(
+  env: Record<string, string>,
+): Promise<string | undefined> {
+  const { ensureFreshAcpClaudeToken } =
+    await import("./claude-token-refresh.js");
+  await ensureFreshAcpClaudeToken();
+  return injectCredential(
+    env,
+    ACP_OAUTH_TOKEN_FIELD,
+    "CLAUDE_CODE_OAUTH_TOKEN",
+    ACP_CLAUDE_OAUTH_USAGE_DESCRIPTION,
+  );
+}
+
 async function injectCredential(
   env: Record<string, string>,
   field: string,
@@ -371,12 +391,7 @@ export async function prepareAgentEnv(
     }
     let missReason: string | undefined;
     if (!env.CLAUDE_CODE_OAUTH_TOKEN) {
-      missReason = await injectCredential(
-        env,
-        ACP_OAUTH_TOKEN_FIELD,
-        "CLAUDE_CODE_OAUTH_TOKEN",
-        ACP_CLAUDE_OAUTH_USAGE_DESCRIPTION,
-      );
+      missReason = await injectClaudeOauthFromVault(env);
     }
     // Any api-key-shaped value still standing here came from the vault read:
     // the config override was already dropped above, and the read only runs