@vellumai/assistant 0.8.7 → 0.8.8-dev.202606052332.17fc8ea

package/src/acp/resolve-agent.ts

@@ -3,24 +3,39 @@
  *
  * `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.
  *
+ * When the adapter binary is NOT on PATH but `bun` is and the command has a
+ * vendored entry in `DEFAULT_AGENT_NPM_PACKAGES`, the resolver rewrites the
+ * agent to run via `bun x --bun <package>` instead of failing. bunx fetches
+ * the package into its cache on first use, so platform-hosted assistants
+ * whose image ships bun (but no node and no npm) work out of the box with
+ * no global install. The original command is preserved as `adapterCommand`
+ * so downstream consumers (env injection, resume hints, version probe) keep
+ * gating on the canonical adapter identity.
+ *
  * `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-or-bunx resolution.
  */
 
+import { basename } from "node:path";
+
 import {
   DEFAULT_ACP_AGENT_PROFILES,
   DEFAULT_AGENT_NPM_PACKAGES,
 } 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 +44,51 @@ import { getConfig } from "../config/loader.js";
  */
 type AcpAgentSource = "config" | "default";
 
-type ResolveAcpAgentResult =
-  | { ok: true; agent: AcpAgentConfig }
+/**
+ * A resolver-produced agent config, ready to spawn. `adapterCommand` carries
+ * the canonical adapter identity (e.g. "claude-agent-acp") even when the
+ * spawn command was rewritten to run via `bun x`, so consumers that gate
+ * behavior on the adapter (env injection in `prepare-agent-env.ts`, resume
+ * hints, the version probe in `tools/acp/spawn.ts`) stay correct for
+ * bunx-resolved agents.
+ */
+export interface ResolvedAcpAgent extends AcpAgentConfig {
+  adapterCommand: string;
+}
+
+/**
+ * Canonical adapter identity for a (possibly rewritten) agent config.
+ * Resolver-produced configs carry `adapterCommand` explicitly; plain configs
+ * that never went through the resolver fall back to the command basename so
+ * user-supplied agent configs keep working.
+ */
+export function adapterCommandOf(config: {
+  command: string;
+  adapterCommand?: string;
+}): string {
+  return config.adapterCommand ?? basename(config.command);
+}
+
+/**
+ * Whether the config was rewritten by the resolver to run through `bun x`
+ * (the only path where the canonical adapter identity diverges from the
+ * actual spawn command).
+ */
+export function runsViaBunx(config: {
+  command: string;
+  adapterCommand?: string;
+}): boolean {
+  return (
+    config.adapterCommand !== undefined &&
+    config.adapterCommand !== basename(config.command)
+  );
+}
+
+export type ResolveAcpAgentResult =
+  | { ok: true; agent: ResolvedAcpAgent }
+  | ResolveAcpAgentFailure;
+
+export type ResolveAcpAgentFailure =
   | { ok: false; reason: "acp_disabled"; hint: string }
   | { ok: false; reason: "unknown_agent"; available: string[] }
   | {
@@ -40,6 +98,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 +141,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];
@@ -66,24 +151,99 @@ function installHintFor(command: string): string {
 }
 
 /**
- * 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
- * relies on a custom PATH to locate the binary doesn't fail preflight.
+ * override wins over the assistant's PATH. Mirror that here so a config that
+ * relies on a custom PATH to locate the binary (or `bun`, for the bunx
+ * rewrite) 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 it cannot
+ * spawn. The ONLY place the bunx rewrite happens:
+ *
+ * 1. Binary on PATH → use it directly (`adapterCommand` = command basename).
+ * 2. Binary missing, command has a vendored npm package mapping, and `bun`
+ *    is on PATH → rewrite to `bun x --bun <package> <original args>`. bunx
+ *    fetches the package on first use, preserving the
+ *    install-latest-on-first-use design with no global install.
+ * 3. Otherwise → null (callers fall back to npm auto-install or surface the
+ *    install hint).
+ *
+ * Security boundary (mirrors `auto-install.ts`): only commands present in
+ * `DEFAULT_AGENT_NPM_PACKAGES` are ever rewritten. The package names are
+ * vendored constants, NOT user input: an arbitrary command from user config
+ * must never be turned into a `bun x <attacker-controlled-name>` execution.
+ */
+function resolveRunnableAgent(agent: AcpAgentConfig): ResolvedAcpAgent | null {
+  if (whichOnAgentPath(agent, agent.command)) {
+    return { ...agent, adapterCommand: basename(agent.command) };
+  }
+  const packageName = DEFAULT_AGENT_NPM_PACKAGES[agent.command];
+  if (!packageName || !whichOnAgentPath(agent, "bun")) return null;
+  return {
+    ...agent,
+    command: "bun",
+    args: ["x", "--bun", packageName, ...agent.args],
+    adapterCommand: agent.command,
+  };
+}
+
+/**
+ * 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 +269,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, or the bunx rewrite
+ *    applies (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 +294,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 +304,7 @@ export function resolveAcpAgent(id: string): ResolveAcpAgentResult {
     };
   }
 
-  return { ok: true, agent };
+  return { ok: true, agent: runnable };
 }
 
 /**
@@ -160,7 +322,7 @@ export function listAcpAgents(): {
   agents: AcpAgentEntry[];
 } {
   const config = getConfig();
-  if (!config.acp.enabled) {
+  if (!isAcpEnabled(config)) {
     return { enabled: false, agents: [] };
   }
 
@@ -168,7 +330,9 @@ 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-or-bunx resolution as `resolveAcpAgent`: an agent whose
+    // binary is missing but would spawn via `bun x` IS available.
+    const available = resolveRunnableAgent(agent) !== null;
     const entry: AcpAgentEntry = {
       id,
       command: agent.command,

package/src/acp/resume-hint.ts

@@ -0,0 +1,25 @@
+/**
+ * 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
+ * CANONICAL adapter command (`adapterCommandOf` in `resolve-agent.ts`), not
+ * the raw spawn command, so the hint still fires when the claude adapter is
+ * run via `bun x` (spawn command "bun").
+ *
+ * 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}`
+    : "";
+}