@vellumai/assistant 0.6.5 → 0.7.0

package/src/tools/acp/spawn.test.ts

@@ -0,0 +1,379 @@
+import * as realChildProcess from "node:child_process";
+import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { installAcpConfigStub } from "../../acp/__tests__/helpers/acp-config-stub.js";
+import { installWhichStub } from "../../acp/__tests__/helpers/which-stub.js";
+import type { ToolContext } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Mock infrastructure
+// ---------------------------------------------------------------------------
+
+type ExecCallback = (
+  err: Error | null,
+  stdout: string | Buffer,
+  stderr: string | Buffer,
+) => void;
+
+interface ExecScript {
+  /** When set, the call rejects with this error. */
+  error?: Error;
+  /** When set, the call resolves with this stdout. */
+  stdout?: string;
+}
+
+/**
+ * Per-call scripted responses for `execFile`. Keyed by `${command} ${args[0]}`
+ * so tests can target `npm ls` and `npm view` independently.
+ */
+const execScripts: Map<string, ExecScript> = new Map();
+
+const execFileMock = mock(
+  (
+    command: string,
+    args: string[],
+    _options: unknown,
+    callback?: ExecCallback,
+  ) => {
+    const key = `${command} ${args[0]}`;
+    const script = execScripts.get(key);
+    queueMicrotask(() => {
+      if (!callback) return;
+      if (!script) {
+        callback(new Error(`No script for ${key}`), "", "");
+        return;
+      }
+      if (script.error) {
+        callback(script.error, "", "");
+        return;
+      }
+      callback(null, script.stdout ?? "", "");
+    });
+    // Return value is not used by execFileWithTimeout.
+    return {} as ReturnType<typeof realChildProcess.execFile>;
+  },
+);
+
+mock.module("node:child_process", () => ({
+  ...realChildProcess,
+  execFile: execFileMock,
+}));
+
+// Default ACP config used by these tests: the `unknown-agent` entry is here
+// to give the "no version check" test a configured agent whose binary isn't
+// in DEFAULT_AGENT_NPM_PACKAGES.
+const DEFAULT_TEST_AGENTS = {
+  claude: { command: "claude-agent-acp", args: [] },
+  codex: { command: "codex-acp", args: [] },
+  "unknown-agent": { command: "some-other-binary", args: [] },
+};
+
+const config = await installAcpConfigStub();
+const which = installWhichStub();
+
+afterAll(() => {
+  which.restore();
+});
+
+mock.module("../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+// Stub session manager so we don't actually spawn child processes.
+const spawnMock = mock(
+  async (
+    _agentId: string,
+    _agentConfig: unknown,
+    _task: string,
+    _cwd: string,
+    _parentConversationId: string,
+    _sendToVellum: (msg: unknown) => void,
+  ) => ({
+    acpSessionId: "acp-session-test",
+    protocolSessionId: "proto-session-test",
+  }),
+);
+
+// Spread the real module's exports so transitive importers that pull other
+// names from `../../acp/index.js` (e.g. `broadcastToAllClients` from the
+// HTTP route layer) still resolve at parse time. Bun's `mock.module` is
+// process-global and returns *exactly* the keys the factory returns —
+// without the spread, any module evaluated after this test file errors at
+// load with "Export named '<X>' not found".
+const realAcpModule = await import("../../acp/index.js");
+mock.module("../../acp/index.js", () => ({
+  ...realAcpModule,
+  getAcpSessionManager: () => ({ spawn: spawnMock }),
+}));
+
+const { executeAcpSpawn, _resetAdapterVersionCacheForTests } =
+  await import("./spawn.js");
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeContext(): ToolContext {
+  return {
+    workingDir: "/tmp",
+    conversationId: "test-conversation",
+    trustClass: "guardian",
+    sendToClient: () => {},
+  } as ToolContext;
+}
+
+beforeEach(() => {
+  execScripts.clear();
+  execFileMock.mockClear();
+  spawnMock.mockClear();
+  _resetAdapterVersionCacheForTests();
+  config.setConfig({ agents: DEFAULT_TEST_AGENTS });
+  which.setWhich((cmd) => `/usr/local/bin/${cmd}`);
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("executeAcpSpawn — version check", () => {
+  test("execFile failure: spawn proceeds without warning", async () => {
+    execScripts.set("npm ls", { error: new Error("npm not installed") });
+    execScripts.set("npm view", { error: new Error("npm not installed") });
+
+    const result = await executeAcpSpawn(
+      { agent: "claude", task: "do something" },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(false);
+    expect(result.content).not.toContain("outdated");
+    expect(result.content).not.toContain("Note:");
+    // Spawn was actually invoked.
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    // Sanity: payload shape preserved.
+    const lines = result.content.split("\n\n");
+    const payload = JSON.parse(lines[0]);
+    expect(payload.acpSessionId).toBe("acp-session-test");
+    expect(payload.status).toBe("running");
+  });
+
+  test("outdated version: spawn proceeds AND warning appears in content", async () => {
+    execScripts.set("npm ls", {
+      stdout: JSON.stringify({
+        dependencies: {
+          "@agentclientprotocol/claude-agent-acp": { version: "0.1.0" },
+        },
+      }),
+    });
+    execScripts.set("npm view", { stdout: "0.2.0\n" });
+
+    const result = await executeAcpSpawn(
+      { agent: "claude", task: "do something" },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain("outdated");
+    expect(result.content).toContain("@agentclientprotocol/claude-agent-acp");
+    expect(result.content).toContain("0.1.0");
+    expect(result.content).toContain("0.2.0");
+    expect(result.content).toContain(
+      "npm install -g @agentclientprotocol/claude-agent-acp@0.2.0",
+    );
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    // Payload still parses as JSON before the warning suffix.
+    const [payloadJson] = result.content.split("\n\n");
+    const payload = JSON.parse(payloadJson);
+    expect(payload.acpSessionId).toBe("acp-session-test");
+  });
+
+  test("up-to-date version: spawn proceeds, no warning", async () => {
+    execScripts.set("npm ls", {
+      stdout: JSON.stringify({
+        dependencies: {
+          "@agentclientprotocol/claude-agent-acp": { version: "0.2.0" },
+        },
+      }),
+    });
+    execScripts.set("npm view", { stdout: "0.2.0\n" });
+
+    const result = await executeAcpSpawn(
+      { agent: "claude", task: "do something" },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(false);
+    expect(result.content).not.toContain("outdated");
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("unknown command: no version check is performed", async () => {
+    // No execScripts set — if the implementation tried to run npm, the
+    // mock would callback with "No script for ..." and we could detect
+    // the failure. But since the registry doesn't include this command,
+    // the implementation should skip the check entirely without calling
+    // execFile.
+    execFileMock.mockClear();
+
+    const result = await executeAcpSpawn(
+      { agent: "unknown-agent", task: "do something" },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(false);
+    expect(execFileMock).not.toHaveBeenCalled();
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    // No outdated note suffix.
+    expect(result.content).not.toContain("outdated");
+  });
+
+  test("cached null result: second call does not reprobe", async () => {
+    execScripts.set("npm ls", { error: new Error("npm not installed") });
+    execScripts.set("npm view", { error: new Error("npm not installed") });
+
+    await executeAcpSpawn({ agent: "claude", task: "task 1" }, makeContext());
+    const firstCallCount = execFileMock.mock.calls.length;
+    expect(firstCallCount).toBeGreaterThan(0);
+
+    await executeAcpSpawn({ agent: "claude", task: "task 2" }, makeContext());
+    // No additional execFile calls — result was cached.
+    expect(execFileMock.mock.calls.length).toBe(firstCallCount);
+  });
+
+  test("cached outdated result: second call does not reprobe but still warns", async () => {
+    execScripts.set("npm ls", {
+      stdout: JSON.stringify({
+        dependencies: {
+          "@agentclientprotocol/claude-agent-acp": { version: "0.1.0" },
+        },
+      }),
+    });
+    execScripts.set("npm view", { stdout: "0.2.0\n" });
+
+    const first = await executeAcpSpawn(
+      { agent: "claude", task: "task 1" },
+      makeContext(),
+    );
+    expect(first.content).toContain("outdated");
+    const firstCallCount = execFileMock.mock.calls.length;
+
+    const second = await executeAcpSpawn(
+      { agent: "claude", task: "task 2" },
+      makeContext(),
+    );
+    expect(second.content).toContain("outdated");
+    // No additional execFile calls — outdated info was cached.
+    expect(execFileMock.mock.calls.length).toBe(firstCallCount);
+  });
+});
+
+describe("executeAcpSpawn — input validation", () => {
+  test("missing task returns error", async () => {
+    const result = await executeAcpSpawn({ agent: "claude" }, makeContext());
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("task");
+  });
+
+  test("missing sendToClient returns error", async () => {
+    const result = await executeAcpSpawn(
+      { agent: "claude", task: "do something" },
+      { ...makeContext(), sendToClient: undefined },
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("No client connected");
+  });
+
+  test("unknown agent in config returns error", async () => {
+    const result = await executeAcpSpawn(
+      { agent: "nonexistent", task: "do something" },
+      makeContext(),
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('Unknown agent "nonexistent"');
+    // New error message lists the merged catalog (defaults + user agents).
+    expect(result.content).toContain("Available:");
+  });
+
+  test("acp disabled returns error with config hint", async () => {
+    config.setConfig({ enabled: false, agents: DEFAULT_TEST_AGENTS });
+    const result = await executeAcpSpawn(
+      { agent: "claude", task: "do something" },
+      makeContext(),
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("acp.enabled");
+  });
+
+  test("missing binary returns install hint", async () => {
+    which.setWhich({});
+    const result = await executeAcpSpawn(
+      { agent: "claude", task: "do something" },
+      makeContext(),
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("claude-agent-acp is not on PATH");
+    expect(result.content).toContain(
+      "npm i -g @agentclientprotocol/claude-agent-acp",
+    );
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+
+  test("default-profile fallback when user config is empty", async () => {
+    // No user `agents.codex` entry, but `agent: "codex"` works via the bundled
+    // default profile (command: "codex-acp"). The resolver merges defaults
+    // automatically.
+    config.setConfig({ agents: {} });
+    execScripts.set("npm ls", { error: new Error("npm not installed") });
+    execScripts.set("npm view", { error: new Error("npm not installed") });
+
+    const result = await executeAcpSpawn(
+      { agent: "codex", task: "do something" },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(false);
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    // The agentConfig handed to spawn() should be the bundled default.
+    const agentConfigArg = spawnMock.mock.calls[0][1] as { command: string };
+    expect(agentConfigArg.command).toBe("codex-acp");
+  });
+});
+
+describe("executeAcpSpawn — per-agent resume hint", () => {
+  test("claude payload includes the `claude --resume` hint", async () => {
+    execScripts.set("npm ls", { error: new Error("npm not installed") });
+    execScripts.set("npm view", { error: new Error("npm not installed") });
+
+    const result = await executeAcpSpawn(
+      { agent: "claude", task: "do something" },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(false);
+    const [payloadJson] = result.content.split("\n\n");
+    const payload = JSON.parse(payloadJson);
+    expect(payload.message).toContain("claude --resume");
+    expect(payload.message).toContain("To resume this session later");
+  });
+
+  test("non-claude payload omits the `claude --resume` hint", async () => {
+    // `claude --resume <id>` is Claude Code-specific. Codex (and any other
+    // adapter) should not have that command suggested back to the user.
+    execScripts.set("npm ls", { error: new Error("npm not installed") });
+    execScripts.set("npm view", { error: new Error("npm not installed") });
+
+    const result = await executeAcpSpawn(
+      { agent: "codex", task: "do something" },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(false);
+    const [payloadJson] = result.content.split("\n\n");
+    const payload = JSON.parse(payloadJson);
+    expect(payload.message).not.toContain("claude --resume");
+    expect(payload.message).not.toContain("To resume this session later");
+  });
+});

package/src/tools/acp/spawn.ts

@@ -1,68 +1,128 @@
 import { execFile } from "node:child_process";
-import { promisify } from "node:util";
 
 import { getAcpSessionManager } from "../../acp/index.js";
-import { getConfig } from "../../config/loader.js";
+import { resolveAcpAgent } from "../../acp/resolve-agent.js";
+import { DEFAULT_AGENT_NPM_PACKAGES } from "../../config/acp-defaults.js";
 import { getLogger } from "../../util/logger.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
-const execFileAsync = promisify(execFile);
 const log = getLogger("acp:spawn");
 
-/** Cache so we only check once per process lifetime. */
-let adapterVersionChecked = false;
+/** Per-call timeout for `npm` probes. Best-effort: timeouts are non-fatal. */
+const NPM_PROBE_TIMEOUT_MS = 5_000;
+
+/**
+ * Cache of resolved version-check outcomes — including `null` for "skipped" —
+ * keyed by command. Lives for the process lifetime so retries don't reprobe.
+ */
+const adapterVersionCache = new Map<string, AdapterVersionInfo | null>();
 
 interface AdapterVersionInfo {
   outdated: true;
   installed: string;
   latest: string;
+  packageName: string;
+}
+
+/**
+ * Run `execFile` with an AbortController-driven timeout. Returns the stdout
+ * on success; throws on error or timeout. Caller treats any throw as a
+ * best-effort skip.
+ */
+function execFileWithTimeout(
+  command: string,
+  args: string[],
+  timeoutMs: number,
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    execFile(
+      command,
+      args,
+      { signal: controller.signal, encoding: "utf8" },
+      (err, stdout) => {
+        clearTimeout(timer);
+        if (err) {
+          reject(err);
+          return;
+        }
+        resolve(stdout);
+      },
+    );
+  });
 }
 
 /**
- * Checks if the globally-installed claude-agent-acp adapter is outdated.
- * Runs at most once per process lifetime. Does NOT auto-update — returns
- * version info so the caller can ask the user first.
+ * Checks if the globally-installed ACP adapter for `command` is outdated.
+ * Best-effort: any error or timeout returns `null` (skipped). Unknown
+ * commands also return `null`. Results are cached per-command for the
+ * process lifetime.
+ *
+ * Note: `npm ls -g` doesn't see Homebrew/tarball installs, so a "not found"
+ * here doesn't mean the binary is missing — it just means we can't compare
+ * versions. The caller must NEVER block the spawn on this result.
  */
 async function checkAdapterVersion(
   command: string,
 ): Promise<AdapterVersionInfo | null> {
-  if (adapterVersionChecked || command !== "claude-agent-acp") {
+  if (adapterVersionCache.has(command)) {
+    return adapterVersionCache.get(command) ?? null;
+  }
+
+  const packageName = DEFAULT_AGENT_NPM_PACKAGES[command];
+  if (!packageName) {
+    adapterVersionCache.set(command, null);
     return null;
   }
 
   try {
-    const { stdout: installedRaw } = await execFileAsync("npm", [
-      "ls",
-      "-g",
-      "--json",
-      "@zed-industries/claude-agent-acp",
-    ]);
-    const { stdout: latestRaw } = await execFileAsync("npm", [
-      "view",
-      "@zed-industries/claude-agent-acp",
-      "version",
+    const [installedRaw, latestRaw] = await Promise.all([
+      execFileWithTimeout(
+        "npm",
+        ["ls", "-g", "--json", packageName],
+        NPM_PROBE_TIMEOUT_MS,
+      ),
+      execFileWithTimeout(
+        "npm",
+        ["view", packageName, "version"],
+        NPM_PROBE_TIMEOUT_MS,
+      ),
     ]);
 
     const installed =
-      JSON.parse(installedRaw)?.dependencies?.[
-        "@zed-industries/claude-agent-acp"
-      ]?.version;
+      JSON.parse(installedRaw)?.dependencies?.[packageName]?.version;
     const latest = latestRaw.trim();
 
-    adapterVersionChecked = true;
-
     if (!installed || !latest || installed === latest) {
+      adapterVersionCache.set(command, null);
       return null;
     }
 
-    log.info({ installed, latest }, "claude-agent-acp is outdated");
-    return { outdated: true, installed, latest };
+    log.info({ installed, latest, packageName }, "ACP adapter is outdated");
+    const info: AdapterVersionInfo = {
+      outdated: true,
+      installed,
+      latest,
+      packageName,
+    };
+    adapterVersionCache.set(command, info);
+    return info;
   } catch (err) {
-    log.warn({ err }, "Failed to check claude-agent-acp version");
+    log.warn(
+      { err, packageName },
+      "Failed to check ACP adapter version (best-effort, skipping)",
+    );
+    adapterVersionCache.set(command, null);
     return null;
   }
 }
 
+/** @internal — exposed for tests only. */
+export function _resetAdapterVersionCacheForTests(): void {
+  adapterVersionCache.clear();
+}
+
 export async function executeAcpSpawn(
   input: Record<string, unknown>,
   context: ToolContext,
@@ -74,19 +134,32 @@ export async function executeAcpSpawn(
     return { content: '"task" is required.', isError: true };
   }
 
-  const config = getConfig();
-  if (!config.acp?.enabled) {
-    return { content: "ACP is not enabled in config.", isError: true };
-  }
-
-  const agentConfig = config.acp.agents[agent];
-  if (!agentConfig) {
-    const available = Object.keys(config.acp.agents).join(", ") || "none";
-    return {
-      content: `Unknown agent "${agent}". Available: ${available}`,
-      isError: true,
-    };
+  const resolved = resolveAcpAgent(agent);
+  if (!resolved.ok) {
+    switch (resolved.reason) {
+      case "acp_disabled":
+        return { content: resolved.hint, isError: true };
+      case "unknown_agent":
+        return {
+          content: `Unknown agent "${agent}". Available: ${resolved.available.join(
+            ", ",
+          )}.`,
+          isError: true,
+        };
+      case "binary_not_found":
+        return {
+          content: `${resolved.command} is not on PATH. ${resolved.hint}`,
+          isError: true,
+        };
+      default: {
+        const _exhaustive: never = resolved;
+        throw new Error(
+          `Unexpected acp resolver reason: ${(_exhaustive as { reason: string }).reason}`,
+        );
+      }
+    }
   }
+  const agentConfig = resolved.agent;
 
   const sendToClient = context.sendToClient as
     | ((msg: { type: string; [key: string]: unknown }) => void)
@@ -98,16 +171,9 @@ export async function executeAcpSpawn(
     };
   }
 
-  // Check if the ACP adapter is outdated before spawning
+  // Best-effort version check — never blocks the spawn. If outdated, we
+  // append a non-blocking warning to the success payload.
   const versionInfo = await checkAdapterVersion(agentConfig.command);
-  if (versionInfo) {
-    return {
-      content:
-        `claude-agent-acp is outdated (installed: ${versionInfo.installed}, latest: ${versionInfo.latest}). ` +
-        `Ask the user if they'd like to update. If yes, run: npm install -g @zed-industries/claude-agent-acp@${versionInfo.latest} — then retry acp_spawn.`,
-      isError: true,
-    };
-  }
 
   try {
     const manager = getAcpSessionManager();
@@ -121,20 +187,34 @@ export async function executeAcpSpawn(
       sendToClient as (msg: unknown) => void,
     );
 
-    return {
-      content: JSON.stringify({
-        acpSessionId,
-        protocolSessionId,
-        agent,
-        cwd,
-        status: "running",
-        message:
-          `ACP agent "${agent}" spawned (session: ${protocolSessionId}). ` +
-          `Results stream back via SSE. You will be notified when it completes. ` +
-          `To resume this session later, run: cd ${cwd} && claude --resume ${protocolSessionId}`,
-      }),
-      isError: false,
-    };
+    // `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.
+    const resumeHint =
+      agentConfig.command === "claude-agent-acp"
+        ? ` To resume this session later, run: cd ${cwd} && claude --resume ${protocolSessionId}`
+        : "";
+    const payload = JSON.stringify({
+      acpSessionId,
+      protocolSessionId,
+      agent,
+      cwd,
+      status: "running",
+      message:
+        `ACP agent "${agent}" spawned (session: ${protocolSessionId}). ` +
+        `Results stream back via SSE. You will be notified when it completes.${resumeHint}`,
+    });
+
+    let content = payload;
+    if (versionInfo) {
+      content +=
+        `\n\nNote: ${versionInfo.packageName} is outdated ` +
+        `(installed: ${versionInfo.installed}, latest: ${versionInfo.latest}). ` +
+        `To update, run: npm install -g ${versionInfo.packageName}@${versionInfo.latest}`;
+    }
+
+    return { content, isError: false };
   } catch (err) {
     const msg =
       err instanceof Error