@vellumai/assistant 0.8.8 → 0.8.9-staging.2

package/src/acp/feature-gate.test.ts

@@ -0,0 +1,48 @@
+/**
+ * Tests for the ACP feature gate.
+ *
+ * `isAcpEnabled` is an OR of the `acp` feature flag and the legacy
+ * `config.acp.enabled` field: either switch enables the subsystem, and
+ * neither implicitly flips the other.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { setOverridesForTesting } from "../__tests__/feature-flag-test-helpers.js";
+import type { AssistantConfig } from "../config/schema.js";
+import { ACP_FLAG_KEY, isAcpEnabled } from "./feature-gate.js";
+
+beforeEach(() => {
+  setOverridesForTesting({});
+});
+
+afterEach(() => {
+  setOverridesForTesting({});
+});
+
+/** Minimal AssistantConfig carrying only the `acp` section the gate reads. */
+function makeConfig(acpEnabled: boolean): AssistantConfig {
+  return {
+    acp: { enabled: acpEnabled, maxConcurrentSessions: 4, agents: {} },
+  } as AssistantConfig;
+}
+
+describe("isAcpEnabled", () => {
+  test("returns false when both the flag and config.acp.enabled are off", () => {
+    expect(isAcpEnabled(makeConfig(false))).toBe(false);
+  });
+
+  test("returns true when config.acp.enabled is true and the flag is off", () => {
+    expect(isAcpEnabled(makeConfig(true))).toBe(true);
+  });
+
+  test("returns true when the flag is on and config.acp.enabled is false", () => {
+    setOverridesForTesting({ [ACP_FLAG_KEY]: true });
+    expect(isAcpEnabled(makeConfig(false))).toBe(true);
+  });
+
+  test("explicit flag-off override does not defeat config.acp.enabled", () => {
+    setOverridesForTesting({ [ACP_FLAG_KEY]: false });
+    expect(isAcpEnabled(makeConfig(true))).toBe(true);
+  });
+});

package/src/acp/feature-gate.ts

@@ -0,0 +1,34 @@
+/**
+ * ACP (Agent Client Protocol) feature gate.
+ *
+ * Single source of truth for whether the ACP subsystem is enabled. Modeled
+ * on `credential-execution/feature-gates.ts`: the flag key is declared in
+ * `meta/feature-flags/feature-flag-registry.json` and resolved through the
+ * unified feature-flag resolver.
+ *
+ * The gate is an OR of two independent switches:
+ *   1. `config.acp.enabled` — the original workspace config field. Preserved
+ *      so existing workspaces with `acp.enabled: true` keep working without
+ *      any migration.
+ *   2. The `acp` feature flag — adds a UI toggle. Flag state is persisted by
+ *      the gateway and hot-refreshed in the daemon via the
+ *      `feature_flags_changed` SSE event, so toggling it takes effect
+ *      without a restart or config-file edit.
+ */
+
+import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
+import type { AssistantConfig } from "../config/schema.js";
+
+/** Gate for the ACP coding-agent subsystem (must match the registry). */
+export const ACP_FLAG_KEY = "acp" as const;
+
+/**
+ * Whether ACP agent spawning/steering is enabled, via either the legacy
+ * `acp.enabled` config field or the `acp` feature flag (see module doc).
+ */
+export function isAcpEnabled(config: AssistantConfig): boolean {
+  return (
+    config.acp?.enabled === true ||
+    isAssistantFeatureFlagEnabled(ACP_FLAG_KEY, config)
+  );
+}

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

@@ -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", () => {
@@ -118,7 +216,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 +256,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,6 +298,60 @@ 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");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveAcpAgent - missing binaries are never run from the task cwd
+// ---------------------------------------------------------------------------
+
+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 = 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({});
+
+    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");
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -207,7 +359,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 +368,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 +411,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 +424,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 +454,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 +496,7 @@ describe("listAcpAgents", () => {
     which.setWhich({
       "claude-agent-acp": "/x",
       "codex-acp": "/x",
+      gemini: "/x",
       "my-binary": "/x",
     });
 
@@ -290,9 +505,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");
   });