@vellumai/assistant 0.8.8 → 0.8.9-staging.2

package/src/acp/resolve-agent.ts

@@ -3,16 +3,28 @@
  *
  * `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
  * of truth and matching actionable hints.
  *
+ * The resolver NEVER fetches or runs packages in the (untrusted) task cwd.
+ * When the adapter binary is missing, resolution simply fails with
+ * `binary_not_found`; the `resolveAgentWithAutoInstall` flow in
+ * `auto-install.ts` then performs a one-time sandboxed `bun` global install
+ * (clean temp cwd, secrets stripped from the installer env) and re-resolves.
+ * The resolved command is therefore ALWAYS the real adapter binary on PATH,
+ * so downstream gates (env injection, resume hints) key off the command
+ * basename directly.
+ *
  * `listAcpAgents()` exposes the merged catalog with availability info for
  * the `acp_list_agents` tool — same merge semantics, plus per-entry
- * `available` / `setupHint` derived from `Bun.which` + `DEFAULT_AGENT_NPM_PACKAGES`.
+ * `available` / `setupHint` derived from the same binary resolution.
  */
 
 import {
@@ -21,6 +33,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 +42,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 +56,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,34 +99,91 @@ 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];
   return pkg
-    ? `npm i -g ${pkg}`
+    ? `bun add -g ${pkg}`
     : `Install '${command}' and ensure it is on PATH.`;
 }
 
 /**
- * Resolve the binary using the same PATH the spawn will see. `AcpAgentProcess`
+ * Resolve a binary using the same PATH the spawn will see. `AcpAgentProcess`
  * spawns with `{ ...process.env, ...config.env }`, so a per-agent `env.PATH`
- * override wins over the daemon's PATH. Mirror that here so a config that
+ * override wins over the assistant's PATH. Mirror that here so a config that
  * relies on a custom PATH to locate the binary doesn't fail preflight.
  */
-function findAgentBinary(agent: AcpAgentConfig): string | null {
+function whichOnAgentPath(
+  agent: AcpAgentConfig,
+  command: string,
+): string | null {
   const PATH = agent.env?.PATH ?? process.env.PATH;
-  return Bun.which(agent.command, PATH != null ? { PATH } : undefined);
+  return Bun.which(command, PATH != null ? { PATH } : undefined);
+}
+
+/**
+ * Resolve an agent config to its runnable form, or `null` when its `command`
+ * is not on PATH. Resolution is pure preflight: the binary is used directly
+ * when present, and otherwise the agent cannot spawn (callers fall back to
+ * the sandboxed `bun` global install in `auto-install.ts`, then re-resolve).
+ *
+ * Crucially, this never fetches or executes anything in the task cwd: a
+ * missing binary returns `null` rather than running a package manager from
+ * the (untrusted) project directory.
+ */
+function resolveRunnableAgent(agent: AcpAgentConfig): AcpAgentConfig | null {
+  return whichOnAgentPath(agent, agent.command) ? agent : null;
+}
+
+/**
+ * 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,16 +209,17 @@ 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).
+ * 3. The agent must be runnable: its `command` on PATH (see
+ *    `resolveRunnableAgent`).
  *
  * Each failure mode carries an actionable hint so callers can surface a
  * single user-facing message without re-deriving the remediation.
  */
 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 };
   }
 
@@ -133,7 +234,8 @@ export function resolveAcpAgent(id: string): ResolveAcpAgentResult {
   }
 
   const { agent } = found;
-  if (!findAgentBinary(agent)) {
+  const runnable = resolveRunnableAgent(agent);
+  if (!runnable) {
     return {
       ok: false,
       reason: "binary_not_found",
@@ -142,7 +244,7 @@ export function resolveAcpAgent(id: string): ResolveAcpAgentResult {
     };
   }
 
-  return { ok: true, agent };
+  return { ok: true, agent: runnable };
 }
 
 /**
@@ -160,7 +262,7 @@ export function listAcpAgents(): {
   agents: AcpAgentEntry[];
 } {
   const config = getConfig();
-  if (!config.acp.enabled) {
+  if (!isAcpEnabled(config)) {
     return { enabled: false, agents: [] };
   }
 
@@ -168,7 +270,10 @@ export function listAcpAgents(): {
   const agents: AcpAgentEntry[] = mergedAgentIds(userAgents).map((id) => {
     // Non-null: ids come from `mergedAgentIds` so the lookup always resolves.
     const { agent, source } = lookupAgent(userAgents, id)!;
-    const available = findAgentBinary(agent) !== null;
+    // Same binary preflight as `resolveAcpAgent`: available iff the command
+    // is on PATH. A missing binary is auto-installed at spawn time, but the
+    // catalog reflects what is runnable right now.
+    const available = resolveRunnableAgent(agent) !== null;
     const entry: AcpAgentEntry = {
       id,
       command: agent.command,

package/src/acp/resume-hint.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 adapter, not the agent id - this stays
+ * correct when a user aliases an id to a different binary. Callers pass the
+ * resolved command basename, which is always the real adapter 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 adapters; 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}`
+    : "";
+}