@vellumai/assistant 0.8.5 → 0.8.7-dev.202606052118.34cd356

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

@@ -1,19 +1,25 @@
 import { afterAll, beforeEach, describe, expect, test } from "bun:test";
 
+import { setOverridesForTesting } from "../__tests__/feature-flag-test-helpers.js";
 import { installAcpConfigStub } from "./__tests__/helpers/acp-config-stub.js";
 import { installWhichStub } from "./__tests__/helpers/which-stub.js";
+import { ACP_FLAG_KEY } from "./feature-gate.js";
 
 const config = await installAcpConfigStub();
 const which = installWhichStub();
 
 afterAll(() => {
   which.restore();
+  setOverridesForTesting({});
 });
 
 const { resolveAcpAgent, listAcpAgents } = await import("./resolve-agent.js");
 
 beforeEach(() => {
   config.setConfig({});
+  // Default: no flag overrides, so the `acp` flag falls back to its registry
+  // default (false) and enablement comes from the config stub alone.
+  setOverridesForTesting({});
   // Default: every command on PATH so binary preflight passes unless a test
   // explicitly says otherwise.
   which.setWhich((cmd) => `/usr/local/bin/${cmd}`);
@@ -24,7 +30,7 @@ beforeEach(() => {
 // ---------------------------------------------------------------------------
 
 describe("resolveAcpAgent", () => {
-  test("returns acp_disabled when config.acp.enabled is false", () => {
+  test("returns acp_disabled when both the feature flag and config.acp.enabled are off", () => {
     config.setConfig({ enabled: false });
 
     const result = resolveAcpAgent("claude");
@@ -33,10 +39,23 @@ describe("resolveAcpAgent", () => {
     if (result.ok) return;
     expect(result.reason).toBe("acp_disabled");
     if (result.reason !== "acp_disabled") return;
+    expect(result.hint).toContain("ACP Coding Agents");
+    expect(result.hint).toContain("feature flag");
     expect(result.hint).toContain("acp.enabled");
     expect(result.hint).toContain("config.json");
   });
 
+  test("resolution proceeds when the acp feature flag is on and config.acp.enabled is false", () => {
+    config.setConfig({ enabled: false });
+    setOverridesForTesting({ [ACP_FLAG_KEY]: true });
+
+    const result = resolveAcpAgent("claude");
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.agent.command).toBe("claude-agent-acp");
+  });
+
   test("user config wins over default profile", () => {
     config.setConfig({
       agents: {
@@ -78,6 +97,79 @@ describe("resolveAcpAgent", () => {
     expect(result.agent.command).toBe("claude-agent-acp");
   });
 
+  test("falls back to the gemini default profile when no user entry", () => {
+    config.setConfig({ agents: {} });
+
+    const result = resolveAcpAgent("gemini");
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.agent.command).toBe("gemini");
+    expect(result.agent.args).toEqual(["--acp"]);
+  });
+
+  test.each([
+    ["claude code", "claude-agent-acp"],
+    ["Claude Code", "claude-agent-acp"],
+    ["claude-code", "claude-agent-acp"],
+    ["claude_code", "claude-agent-acp"],
+    ["codex cli", "codex-acp"],
+    ["OpenAI Codex", "codex-acp"],
+    ["gemini cli", "gemini"],
+    ["Gemini CLI", "gemini"],
+    ["google gemini", "gemini"],
+  ])("alias %p resolves to the %p profile", (alias, command) => {
+    config.setConfig({ agents: {} });
+
+    const result = resolveAcpAgent(alias);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.agent.command).toBe(command);
+  });
+
+  test("user config entry literally keyed 'claude code' beats the alias", () => {
+    config.setConfig({
+      agents: {
+        "claude code": {
+          command: "my-claude-fork",
+          args: [],
+          description: "user-defined agent that happens to share an alias",
+        },
+      },
+    });
+
+    const result = resolveAcpAgent("claude code");
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.agent.command).toBe("my-claude-fork");
+  });
+
+  test("alias re-runs the normal lookup, so a user override of the canonical id wins", () => {
+    config.setConfig({
+      agents: {
+        claude: { command: "my-custom-claude", args: [] },
+      },
+    });
+
+    const result = resolveAcpAgent("claude code");
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.agent.command).toBe("my-custom-claude");
+  });
+
+  test("non-alias unknown id still returns unknown_agent", () => {
+    config.setConfig({ agents: {} });
+
+    const result = resolveAcpAgent("cursor cli");
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toBe("unknown_agent");
+  });
+
   test("returns unknown_agent with merged available list when id not found", () => {
     config.setConfig({
       agents: {
@@ -92,7 +184,12 @@ describe("resolveAcpAgent", () => {
     expect(result.reason).toBe("unknown_agent");
     if (result.reason !== "unknown_agent") return;
     // Defaults plus user-only ids, deduped, in stable order (defaults first).
-    expect(result.available).toEqual(["claude", "codex", "user-only"]);
+    expect(result.available).toEqual([
+      "claude",
+      "codex",
+      "gemini",
+      "user-only",
+    ]);
   });
 
   test("unknown_agent available list contains both defaults when user config is empty", () => {
@@ -106,6 +203,7 @@ describe("resolveAcpAgent", () => {
     if (result.reason !== "unknown_agent") return;
     expect(result.available).toContain("claude");
     expect(result.available).toContain("codex");
+    expect(result.available).toContain("gemini");
   });
 
   test("returns binary_not_found with the registered install hint", () => {
@@ -207,7 +305,7 @@ describe("resolveAcpAgent", () => {
 // ---------------------------------------------------------------------------
 
 describe("listAcpAgents", () => {
-  test("returns enabled: false with empty agents when ACP is disabled", () => {
+  test("returns enabled: false with empty agents when both the flag and config are off", () => {
     config.setConfig({ enabled: false });
 
     const result = listAcpAgents();
@@ -216,14 +314,28 @@ describe("listAcpAgents", () => {
     expect(result.agents).toEqual([]);
   });
 
-  test("includes both bundled defaults when user config is empty", () => {
+  test("returns the catalog when the acp feature flag is on and config.acp.enabled is false", () => {
+    config.setConfig({ enabled: false });
+    setOverridesForTesting({ [ACP_FLAG_KEY]: true });
+
+    const result = listAcpAgents();
+
+    expect(result.enabled).toBe(true);
+    expect(result.agents.map((a) => a.id)).toEqual([
+      "claude",
+      "codex",
+      "gemini",
+    ]);
+  });
+
+  test("includes all bundled defaults when user config is empty", () => {
     config.setConfig({ agents: {} });
 
     const result = listAcpAgents();
 
     expect(result.enabled).toBe(true);
     const ids = result.agents.map((a) => a.id);
-    expect(ids).toEqual(["claude", "codex"]);
+    expect(ids).toEqual(["claude", "codex", "gemini"]);
     for (const entry of result.agents) {
       expect(entry.source).toBe("default");
       expect(entry.available).toBe(true);
@@ -245,6 +357,7 @@ describe("listAcpAgents", () => {
     which.setWhich({
       "my-claude": "/usr/bin/my-claude",
       "codex-acp": "/usr/bin/codex-acp",
+      gemini: "/usr/bin/gemini",
     });
 
     const result = listAcpAgents();
@@ -269,6 +382,32 @@ describe("listAcpAgents", () => {
     expect(codex?.setupHint).toBe("npm i -g @zed-industries/codex-acp");
   });
 
+  test("unavailable gemini surfaces the @google/gemini-cli install hint", () => {
+    config.setConfig({ agents: {} });
+    which.setWhich({
+      "claude-agent-acp": "/usr/bin/claude-agent-acp",
+      "codex-acp": "/usr/bin/codex-acp",
+    });
+
+    const result = listAcpAgents();
+
+    const gemini = result.agents.find((a) => a.id === "gemini");
+    expect(gemini?.available).toBe(false);
+    expect(gemini?.unavailableReason).toBe("'gemini' is not on PATH");
+    expect(gemini?.setupHint).toBe("npm i -g @google/gemini-cli");
+  });
+
+  test("aliases are resolution sugar, not catalog entries", () => {
+    config.setConfig({ agents: {} });
+
+    // "gemini cli" resolves via the alias...
+    expect(resolveAcpAgent("gemini cli").ok).toBe(true);
+
+    // ...but the catalog lists only canonical ids.
+    const ids = listAcpAgents().agents.map((a) => a.id);
+    expect(ids).toEqual(["claude", "codex", "gemini"]);
+  });
+
   test("user-only agent appended after defaults in stable order", () => {
     config.setConfig({
       agents: {
@@ -282,6 +421,7 @@ describe("listAcpAgents", () => {
     which.setWhich({
       "claude-agent-acp": "/x",
       "codex-acp": "/x",
+      gemini: "/x",
       "my-binary": "/x",
     });
 
@@ -290,9 +430,10 @@ describe("listAcpAgents", () => {
     expect(result.agents.map((a) => a.id)).toEqual([
       "claude",
       "codex",
+      "gemini",
       "my-agent",
     ]);
-    const userOnly = result.agents[2];
+    const userOnly = result.agents[3];
     expect(userOnly.source).toBe("config");
     expect(userOnly.description).toBe("user-only");
   });

package/src/acp/resolve-agent.ts

@@ -3,8 +3,11 @@
  *
  * `resolveAcpAgent(id)` merges user-provided `config.acp.agents[id]` (wins on
  * overlap) with the bundled `DEFAULT_ACP_AGENT_PROFILES` so common agents like
- * `claude` and `codex` Just Work whenever `acp.enabled: true` — no per-user
- * config required. The result is a discriminated union covering every reason
+ * `claude` and `codex` Just Work whenever ACP is enabled (the `acp` feature
+ * flag or `acp.enabled: true`; see `feature-gate.ts`), with no per-user
+ * config required. Natural names ("claude code", "Gemini CLI") resolve via
+ * `AGENT_ID_ALIASES` when the raw id misses both maps. The result is a
+ * discriminated union covering every reason
  * a spawn might fail before we even start the agent process: ACP disabled,
  * unknown agent id, or binary missing from PATH. Callers (acp_spawn,
  * acp_list_agents, and the `/v1/acp/spawn` HTTP route) get a single source
@@ -21,6 +24,7 @@ import {
 } from "../config/acp-defaults.js";
 import type { AcpAgentConfig } from "../config/acp-schema.js";
 import { getConfig } from "../config/loader.js";
+import { isAcpEnabled } from "./feature-gate.js";
 
 /**
  * Whether this agent's entry came from user config (wins over default) or
@@ -29,8 +33,11 @@ import { getConfig } from "../config/loader.js";
  */
 type AcpAgentSource = "config" | "default";
 
-type ResolveAcpAgentResult =
+export type ResolveAcpAgentResult =
   | { ok: true; agent: AcpAgentConfig }
+  | ResolveAcpAgentFailure;
+
+export type ResolveAcpAgentFailure =
   | { ok: false; reason: "acp_disabled"; hint: string }
   | { ok: false; reason: "unknown_agent"; available: string[] }
   | {
@@ -40,6 +47,33 @@ type ResolveAcpAgentResult =
       command: string;
     };
 
+/**
+ * Single source of truth for the user-facing message of each resolver
+ * failure reason. Every caller that surfaces a resolve failure (acp_spawn
+ * tool, /v1/acp/spawn route, AcpSessionManager.resumeFromHistory) renders
+ * the same copy through this helper; only the transport wrapping (tool
+ * error result vs. HTTP error class vs. thrown Error) differs per caller.
+ */
+export function formatResolveFailure(
+  agentId: string,
+  failure: ResolveAcpAgentFailure,
+): string {
+  switch (failure.reason) {
+    case "acp_disabled":
+      return failure.hint;
+    case "unknown_agent":
+      return `Unknown agent "${agentId}". Available: ${failure.available.join(", ")}.`;
+    case "binary_not_found":
+      return `${failure.command} is not on PATH. ${failure.hint}`;
+    default: {
+      const _exhaustive: never = failure;
+      throw new Error(
+        `Unexpected acp resolver reason: ${(_exhaustive as { reason: string }).reason}`,
+      );
+    }
+  }
+}
+
 interface AcpAgentEntry {
   id: string;
   command: string;
@@ -56,7 +90,7 @@ interface AcpAgentEntry {
  * the same string instead of duplicating near-identical copy.
  */
 export const ACP_DISABLED_HINT =
-  "Set 'acp.enabled': true in ~/.vellum/workspace/config.json (or via the runtime config endpoint).";
+  "Enable the \"ACP Coding Agents\" feature flag in the client's feature flags UI (or set 'acp.enabled': true in ~/.vellum/workspace/config.json).";
 
 function installHintFor(command: string): string {
   const pkg = DEFAULT_AGENT_NPM_PACKAGES[command];
@@ -76,14 +110,54 @@ function findAgentBinary(agent: AcpAgentConfig): string | null {
   return Bun.which(agent.command, PATH != null ? { PATH } : undefined);
 }
 
+/**
+ * Natural-name aliases for the bundled agent ids, keyed by normalized form
+ * (see `normalizeAgentId`). Resolution sugar only: aliases are consulted as a
+ * last-resort fallback in `lookupAgent` and never appear in the
+ * `listAcpAgents` catalog.
+ */
+const AGENT_ID_ALIASES: Record<string, string> = {
+  claudecode: "claude",
+  codexcli: "codex",
+  openaicodex: "codex",
+  geminicli: "gemini",
+  googlegemini: "gemini",
+};
+
+/**
+ * Normalize a raw agent id for alias matching: lowercase and strip spaces,
+ * underscores, and hyphens so "Claude Code", "claude-code", and
+ * "claude_code" all hit the same alias entry.
+ */
+function normalizeAgentId(id: string): string {
+  return id.toLowerCase().replace(/[\s_-]/g, "");
+}
+
 /**
  * Resolve an id against user config first, then bundled defaults. Returns the
  * resolved entry plus a `source` label so callers can surface "user override
  * vs bundled default" without re-deriving it.
+ *
+ * When the raw id misses both maps, fall back to `AGENT_ID_ALIASES` so
+ * natural names like "claude code" or "Gemini CLI" resolve to the canonical
+ * id. The alias is consulted ONLY after both direct lookups miss, so a user
+ * config entry literally keyed "claude code" always wins over the alias.
  */
 function lookupAgent(
   userAgents: Record<string, AcpAgentConfig>,
   id: string,
+): { agent: AcpAgentConfig; source: AcpAgentSource } | undefined {
+  const direct = directLookup(userAgents, id);
+  if (direct) return direct;
+  const canonicalId = AGENT_ID_ALIASES[normalizeAgentId(id)];
+  return canonicalId !== undefined
+    ? directLookup(userAgents, canonicalId)
+    : undefined;
+}
+
+function directLookup(
+  userAgents: Record<string, AcpAgentConfig>,
+  id: string,
 ): { agent: AcpAgentConfig; source: AcpAgentSource } | undefined {
   const userAgent = userAgents[id];
   if (userAgent) return { agent: userAgent, source: "config" };
@@ -109,7 +183,7 @@ function mergedAgentIds(userAgents: Record<string, AcpAgentConfig>): string[] {
  * Resolve an ACP agent id to its config + binary preflight result.
  *
  * Order of checks:
- * 1. ACP must be enabled in config.
+ * 1. ACP must be enabled (feature flag or config; see `isAcpEnabled`).
  * 2. The id must resolve to an agent (user config wins; falls back to defaults).
  * 3. The agent's `command` must be discoverable via `Bun.which` (PATH lookup).
  *
@@ -118,7 +192,7 @@ function mergedAgentIds(userAgents: Record<string, AcpAgentConfig>): string[] {
  */
 export function resolveAcpAgent(id: string): ResolveAcpAgentResult {
   const config = getConfig();
-  if (!config.acp.enabled) {
+  if (!isAcpEnabled(config)) {
     return { ok: false, reason: "acp_disabled", hint: ACP_DISABLED_HINT };
   }
 
@@ -160,7 +234,7 @@ export function listAcpAgents(): {
   agents: AcpAgentEntry[];
 } {
   const config = getConfig();
-  if (!config.acp.enabled) {
+  if (!isAcpEnabled(config)) {
     return { enabled: false, agents: [] };
   }
 

package/src/acp/resume-hint.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared `claude --resume` hint for ACP sessions.
+ *
+ * `claude --resume <id>` is Claude Code-specific (the claude-agent-acp
+ * adapter binary). Other adapters resume differently or not at all, so the
+ * hint is gated by the resolved binary, not the agent id - this stays
+ * correct when a user aliases an id to a different binary.
+ *
+ * Used by the `acp_spawn` tool's success payload and the session manager's
+ * completion notification so both surfaces render identical copy. Returns
+ * an empty string for non-claude commands; callers add their own
+ * surrounding separators.
+ */
+export function claudeResumeHint(
+  command: string,
+  cwd: string,
+  sessionId: string,
+): string {
+  return command === "claude-agent-acp"
+    ? `To resume: cd ${cwd} && claude --resume ${sessionId}`
+    : "";
+}