@vellumai/assistant 0.8.8 → 0.8.9-dev.202606091926.ebb2d62

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

@@ -28,48 +28,82 @@ import {
   getCredentialMetadata,
   upsertCredentialMetadata,
 } from "../tools/credentials/metadata-store.js";
+import { getLogger } from "../util/logger.js";
 import type { AcpAgentConfig } from "./types.js";
 
+const log = getLogger("acp:prepare-agent-env");
+
 const ACP_SPAWN_TOOL = "acp_spawn";
+const ACP_SERVICE = "acp";
 
 /**
- * Ensure the `acp/claude_oauth_token` credential has metadata that allows
- * the `acp_spawn` tool to read it, but only for legacy/unmanaged cases:
+ * Ensure an `acp/<field>` credential has metadata that allows the
+ * `acp_spawn` tool to read it, but only for legacy/unmanaged cases:
  *
- * - No metadata at all → create with `allowedTools: ["acp_spawn"]`.
- * - Metadata exists with an empty `allowedTools` → default provisioning
+ * - No metadata at all: create with `allowedTools: ["acp_spawn"]`.
+ * - Metadata exists with an empty `allowedTools`: default provisioning
  *   path (user ran `credentials set` without `--allowed-tools`), add it.
- * - Metadata exists with a non-empty `allowedTools` → explicit policy set
- *   by the user/admin. Respect it even if `acp_spawn` is absent — the
- *   broker will deny the read and the preflight will throw.
+ * - Metadata exists with a non-empty `allowedTools`: explicit policy set
+ *   by the user/admin. Respect it even if `acp_spawn` is absent; the
+ *   broker will deny the read and the caller decides whether that's fatal.
  */
-function ensureAcpTokenPolicy(): void {
-  const meta = getCredentialMetadata("acp", "claude_oauth_token");
+function ensureAcpCredentialPolicy(
+  field: string,
+  usageDescription: string,
+): void {
+  const meta = getCredentialMetadata(ACP_SERVICE, field);
   if (!meta) {
-    upsertCredentialMetadata("acp", "claude_oauth_token", {
+    upsertCredentialMetadata(ACP_SERVICE, field, {
       allowedTools: [ACP_SPAWN_TOOL],
-      usageDescription:
-        "Claude OAuth token for ACP agent authentication",
+      usageDescription,
     });
     return;
   }
   const tools = meta.allowedTools ?? [];
   if (tools.length === 0) {
-    upsertCredentialMetadata("acp", "claude_oauth_token", {
+    upsertCredentialMetadata(ACP_SERVICE, field, {
       allowedTools: [ACP_SPAWN_TOOL],
     });
   }
 }
 
+/**
+ * Read an `acp/<field>` credential through the broker and inject it into
+ * `env` under `envVar`. Returns the broker's failure reason when the value
+ * was not injected (missing credential, denied policy, no stored value),
+ * or undefined on success. Never throws: `serverUse` signals every failure
+ * mode, including a simply-absent credential, as `{ success: false,
+ * reason }`, so callers choose whether a miss is fatal.
+ */
+async function injectCredential(
+  env: Record<string, string>,
+  field: string,
+  envVar: string,
+  usageDescription: string,
+): Promise<string | undefined> {
+  ensureAcpCredentialPolicy(field, usageDescription);
+  const result = await credentialBroker.serverUse<void>({
+    service: ACP_SERVICE,
+    field,
+    toolName: ACP_SPAWN_TOOL,
+    execute: async (value) => {
+      env[envVar] = value;
+    },
+  });
+  return result.success ? undefined : result.reason;
+}
+
 /**
  * Returns a NEW config with any required credentials merged into `env`.
  * Does NOT mutate the input. Throws `FailedDependencyError` if a required
  * credential is missing from both the user-supplied env override and the
  * secure store.
  *
- * Gating is keyed off the resolved agent COMMAND (basename), not the
- * user-facing agent id, so a custom `acp.agents.my-claude = { command:
- * "claude-agent-acp", ... }` alias still gets the env it needs.
+ * Gating is keyed off the resolved command basename, not the user-facing
+ * agent id. A custom `acp.agents.my-claude = { command: "claude-agent-acp",
+ * ... }` alias (or a full path like `/opt/bin/claude-agent-acp`) still gets
+ * the env it needs. Because resolution always yields the real adapter binary
+ * (never a `bun x` wrapper), the basename is the canonical adapter identity.
  *
  * For `claude-agent-acp` the only required env var is
  * `CLAUDE_CODE_OAUTH_TOKEN`. Two provisioning routes converge on it, with
@@ -84,6 +118,11 @@ function ensureAcpTokenPolicy(): void {
  * before spawning. The "fail-fast" throw is symmetric with the existing
  * `binary_not_found` preflight in `resolveAcpAgent` and strictly better
  * than a `warn` + zombie subprocess 10 seconds later.
+ *
+ * For `gemini` the env var is `GEMINI_API_KEY`, provisioned the same two
+ * ways (config.json override wins, vault field `gemini_api_key` second),
+ * but it is OPTIONAL: the Gemini CLI supports its own OAuth login, so a
+ * vault miss proceeds without the key instead of failing the spawn.
  */
 export async function prepareAgentEnv(
   agentConfig: AcpAgentConfig,
@@ -92,19 +131,16 @@ export async function prepareAgentEnv(
   // agent reference. The local `env` binding sidesteps TS narrowing
   // limitations on the optional `AcpAgentConfig.env` field.
   const env: Record<string, string> = { ...(agentConfig.env ?? {}) };
-  const commandBasename = basename(agentConfig.command);
+  const adapterCommand = basename(agentConfig.command);
 
-  if (commandBasename === "claude-agent-acp") {
+  if (adapterCommand === "claude-agent-acp") {
     if (!env.CLAUDE_CODE_OAUTH_TOKEN) {
-      ensureAcpTokenPolicy();
-      await credentialBroker.serverUse<void>({
-        service: "acp",
-        field: "claude_oauth_token",
-        toolName: ACP_SPAWN_TOOL,
-        execute: async (token) => {
-          env.CLAUDE_CODE_OAUTH_TOKEN = token;
-        },
-      });
+      await injectCredential(
+        env,
+        "claude_oauth_token",
+        "CLAUDE_CODE_OAUTH_TOKEN",
+        "Claude OAuth token for ACP agent authentication",
+      );
     }
     if (!env.CLAUDE_CODE_OAUTH_TOKEN) {
       throw new FailedDependencyError(
@@ -113,6 +149,23 @@ export async function prepareAgentEnv(
           "(or set it under acp.agents.<id>.env in config.json).",
       );
     }
+  } else if (adapterCommand === "gemini") {
+    if (!env.GEMINI_API_KEY) {
+      const missReason = await injectCredential(
+        env,
+        "gemini_api_key",
+        "GEMINI_API_KEY",
+        "Gemini API key for ACP agent authentication",
+      );
+      if (missReason !== undefined) {
+        // Optional credential: Gemini CLI can authenticate via its own
+        // OAuth login, so a vault miss must not fail the spawn.
+        log.debug(
+          { reason: missReason },
+          "Gemini API key unavailable from the vault; spawning without GEMINI_API_KEY",
+        );
+      }
+    }
   }
 
   return { ...agentConfig, env };

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

@@ -24,19 +24,6 @@ beforeEach(() => {
 // ---------------------------------------------------------------------------
 
 describe("resolveAcpAgent", () => {
-  test("returns acp_disabled when config.acp.enabled is false", () => {
-    config.setConfig({ enabled: false });
-
-    const result = resolveAcpAgent("claude");
-
-    expect(result.ok).toBe(false);
-    if (result.ok) return;
-    expect(result.reason).toBe("acp_disabled");
-    if (result.reason !== "acp_disabled") return;
-    expect(result.hint).toContain("acp.enabled");
-    expect(result.hint).toContain("config.json");
-  });
-
   test("user config wins over default profile", () => {
     config.setConfig({
       agents: {
@@ -78,6 +65,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 +152,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 +171,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", () => {
@@ -118,7 +184,7 @@ describe("resolveAcpAgent", () => {
     if (result.ok) return;
     expect(result.reason).toBe("binary_not_found");
     if (result.reason !== "binary_not_found") return;
-    expect(result.hint).toBe("npm i -g @agentclientprotocol/claude-agent-acp");
+    expect(result.hint).toBe("bun add -g @agentclientprotocol/claude-agent-acp");
     expect(result.command).toBe("claude-agent-acp");
   });
 
@@ -158,7 +224,7 @@ describe("resolveAcpAgent", () => {
     if (result.ok) return;
     expect(result.reason).toBe("binary_not_found");
     if (result.reason !== "binary_not_found") return;
-    expect(result.hint).toBe("npm i -g @zed-industries/codex-acp");
+    expect(result.hint).toBe("bun add -g @zed-industries/codex-acp");
   });
 
   test("binary preflight honors agent.env.PATH override (matches spawn env)", () => {
@@ -200,30 +266,74 @@ describe("resolveAcpAgent", () => {
     if (!result.ok) return;
     expect(result.agent.args).toEqual(["--verbose"]);
   });
+
+  test("resolves a full-path command directly without rewriting it", () => {
+    config.setConfig({
+      agents: {
+        custom: { command: "/opt/bin/claude-agent-acp", args: [] },
+      },
+    });
+
+    const direct = resolveAcpAgent("claude");
+    expect(direct.ok).toBe(true);
+    if (!direct.ok) return;
+    expect(direct.agent.command).toBe("claude-agent-acp");
+
+    const fullPath = resolveAcpAgent("custom");
+    expect(fullPath.ok).toBe(true);
+    if (!fullPath.ok) return;
+    expect(fullPath.agent.command).toBe("/opt/bin/claude-agent-acp");
+  });
 });
 
 // ---------------------------------------------------------------------------
-// listAcpAgents
+// resolveAcpAgent - missing binaries are never run from the task cwd
 // ---------------------------------------------------------------------------
 
-describe("listAcpAgents", () => {
-  test("returns enabled: false with empty agents when ACP is disabled", () => {
-    config.setConfig({ enabled: false });
+describe("resolveAcpAgent - missing binary", () => {
+  test("binary missing + bun present: still binary_not_found (no bunx rewrite)", () => {
+    // bun on PATH no longer makes a missing adapter "runnable" at resolve
+    // time: the sandboxed install happens separately, never as a `bun x`
+    // rewrite in the untrusted cwd.
+    config.setConfig({ agents: {} });
+    which.setWhich({ bun: "/usr/local/bin/bun" });
 
-    const result = listAcpAgents();
+    const result = resolveAcpAgent("claude");
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toBe("binary_not_found");
+    if (result.reason !== "binary_not_found") return;
+    expect(result.command).toBe("claude-agent-acp");
+    expect(result.hint).toBe("bun add -g @agentclientprotocol/claude-agent-acp");
+  });
+
+  test("binary missing + bun missing: binary_not_found with the bun hint", () => {
+    config.setConfig({ agents: {} });
+    which.setWhich({});
 
-    expect(result.enabled).toBe(false);
-    expect(result.agents).toEqual([]);
+    const result = resolveAcpAgent("claude");
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toBe("binary_not_found");
+    if (result.reason !== "binary_not_found") return;
+    expect(result.hint).toBe("bun add -g @agentclientprotocol/claude-agent-acp");
   });
+});
 
-  test("includes both bundled defaults when user config is empty", () => {
+// ---------------------------------------------------------------------------
+// listAcpAgents
+// ---------------------------------------------------------------------------
+
+describe("listAcpAgents", () => {
+  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 +355,7 @@ describe("listAcpAgents", () => {
     which.setWhich({
       "my-claude": "/usr/bin/my-claude",
       "codex-acp": "/usr/bin/codex-acp",
+      gemini: "/usr/bin/gemini",
     });
 
     const result = listAcpAgents();
@@ -257,6 +368,27 @@ describe("listAcpAgents", () => {
     expect(codex?.source).toBe("default");
   });
 
+  test("missing binaries are listed unavailable even when bun is present", () => {
+    // bun presence no longer makes a missing adapter available: it is
+    // installed on demand at spawn time, not run via `bun x` from the cwd.
+    config.setConfig({ agents: {} });
+    which.setWhich({ bun: "/usr/local/bin/bun" });
+
+    const result = listAcpAgents();
+
+    for (const entry of result.agents) {
+      expect(entry.available).toBe(false);
+      expect(entry.unavailableReason).toBeDefined();
+      expect(entry.setupHint).toContain("bun add -g");
+    }
+    // The catalog keeps the canonical adapter commands.
+    expect(result.agents.map((a) => a.command)).toEqual([
+      "claude-agent-acp",
+      "codex-acp",
+      "gemini",
+    ]);
+  });
+
   test("unavailable agent surfaces install hint derived from DEFAULT_AGENT_NPM_PACKAGES", () => {
     config.setConfig({ agents: {} });
     which.setWhich({ "claude-agent-acp": "/usr/bin/claude-agent-acp" });
@@ -266,7 +398,33 @@ describe("listAcpAgents", () => {
     const codex = result.agents.find((a) => a.id === "codex");
     expect(codex?.available).toBe(false);
     expect(codex?.unavailableReason).toBe("'codex-acp' is not on PATH");
-    expect(codex?.setupHint).toBe("npm i -g @zed-industries/codex-acp");
+    expect(codex?.setupHint).toBe("bun add -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("bun add -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", () => {
@@ -282,6 +440,7 @@ describe("listAcpAgents", () => {
     which.setWhich({
       "claude-agent-acp": "/x",
       "codex-acp": "/x",
+      gemini: "/x",
       "my-binary": "/x",
     });
 
@@ -290,9 +449,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");
   });