@vellumai/assistant 0.8.8 → 0.8.9-staging.2

package/src/tools/acp/spawn.ts

@@ -1,128 +1,12 @@
-import { execFile } from "node:child_process";
+import { basename } from "node:path";
 
+import { resolveAgentWithAutoInstall } from "../../acp/auto-install.js";
 import { getAcpSessionManager } from "../../acp/index.js";
 import { prepareAgentEnv } from "../../acp/prepare-agent-env.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 { formatResolveFailure } from "../../acp/resolve-agent.js";
+import { claudeResumeHint } from "../../acp/resume-hint.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
-
-const log = getLogger("acp:spawn");
-
-/** 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 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 (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 [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?.[packageName]?.version;
-    const latest = latestRaw.trim();
-
-    if (!installed || !latest || installed === latest) {
-      adapterVersionCache.set(command, null);
-      return null;
-    }
-
-    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, 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();
-}
+import { getSendToClient } from "./context.js";
 
 export async function executeAcpSpawn(
   input: Record<string, unknown>,
@@ -135,34 +19,11 @@ export async function executeAcpSpawn(
     return { content: '"task" is required.', 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 sendToClient = context.sendToClient as
-    | ((msg: { type: string; [key: string]: unknown }) => void)
-    | undefined;
+  // Pure precondition: check for a connected client BEFORE any side effects
+  // (auto-install mutates the host via a `bun` global install and can block
+  // for up to the install timeout). Without a client the spawn cannot
+  // succeed anyway.
+  const sendToClient = getSendToClient(context);
   if (!sendToClient) {
     return {
       content: "No client connected - cannot spawn ACP agent.",
@@ -170,6 +31,17 @@ export async function executeAcpSpawn(
     };
   }
 
+  // Resolve the agent, silently auto-installing a missing allowlisted
+  // adapter binary (see acp/auto-install.ts). Shared with the HTTP route.
+  const { resolved, autoInstalledPackage, failureMessage } =
+    await resolveAgentWithAutoInstall(agent);
+  if (failureMessage) {
+    return { content: failureMessage, isError: true };
+  }
+  if (!resolved.ok) {
+    return { content: formatResolveFailure(agent, resolved), isError: true };
+  }
+
   // Inject required env vars and preflight via the shared helper. Mirrors
   // the HTTP route at `runtime/routes/acp-routes.ts:spawnSession` — both
   // call sites MUST go through `prepareAgentEnv` before `manager.spawn`,
@@ -184,10 +56,6 @@ export async function executeAcpSpawn(
     return { content: msg, isError: true };
   }
 
-  // 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);
-
   try {
     const manager = getAcpSessionManager();
     const cwd = (input.cwd as string) || context.workingDir;
@@ -197,17 +65,21 @@ export async function executeAcpSpawn(
       task,
       cwd,
       context.conversationId,
-      sendToClient as (msg: unknown) => void,
+      sendToClient,
     );
 
-    // `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}`
-        : "";
+    // Claude Code-only resume hint; empty for other adapters. Keyed off the
+    // resolved command basename (always the real adapter binary). See
+    // acp/resume-hint.ts for the gating rationale.
+    const hint = claudeResumeHint(
+      basename(agentConfig.command),
+      cwd,
+      protocolSessionId,
+    );
+    const resumeHint = hint ? ` ${hint}` : "";
+    const installNote = autoInstalledPackage
+      ? ` Installed ${autoInstalledPackage} automatically.`
+      : "";
     const payload = JSON.stringify({
       acpSessionId,
       protocolSessionId,
@@ -216,18 +88,11 @@ export async function executeAcpSpawn(
       status: "running",
       message:
         `ACP agent "${agent}" spawned (session: ${protocolSessionId}). ` +
-        `Results stream back via SSE. You will be notified when it completes.${resumeHint}`,
+        `Results stream back via SSE. You will be notified when it completes.` +
+        `${installNote}${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 };
+    return { content: payload, isError: false };
   } catch (err) {
     const msg =
       err instanceof Error

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

@@ -7,6 +7,7 @@ interface SteerCall {
   instruction: string;
 }
 
+// Direct steer (no connected client -> no resume fallback).
 const steerCalls: SteerCall[] = [];
 const defaultSteer = (acpSessionId: string, instruction: string) => {
   steerCalls.push({ acpSessionId, instruction });
@@ -15,6 +16,13 @@ const defaultSteer = (acpSessionId: string, instruction: string) => {
 let steerImpl: (acpSessionId: string, instruction: string) => Promise<void> =
   defaultSteer;
 
+// steerOrResume (connected client path).
+const steerOrResumeCalls: Array<SteerCall & { send: unknown }> = [];
+let steerOrResumeImpl: (
+  acpSessionId: string,
+  instruction: string,
+) => Promise<{ resumed: boolean }> = async () => ({ resumed: false });
+
 // Spread the real module's exports so transitive importers that pull other
 // names from `../../acp/index.js` still resolve at parse time. Bun's `mock.module` is
 // process-global and returns *exactly* the keys the factory returns.
@@ -24,35 +32,50 @@ mock.module("../../acp/index.js", () => ({
   getAcpSessionManager: () => ({
     steer: (acpSessionId: string, instruction: string) =>
       steerImpl(acpSessionId, instruction),
+    steerOrResume: (
+      acpSessionId: string,
+      instruction: string,
+      send: unknown,
+    ) => {
+      steerOrResumeCalls.push({ acpSessionId, instruction, send });
+      return steerOrResumeImpl(acpSessionId, instruction);
+    },
   }),
 }));
 
 const { executeAcpSteer } = await import("./steer.js");
 
-function makeContext(): ToolContext {
+function makeContext(opts?: { withClient?: boolean }): ToolContext {
   return {
     workingDir: "/tmp",
     conversationId: "conv-test",
     trustClass: "guardian",
-  };
+    ...(opts?.withClient ? { sendToClient: () => {} } : {}),
+  } as ToolContext;
 }
 
 beforeEach(() => {
   steerCalls.length = 0;
+  steerOrResumeCalls.length = 0;
   steerImpl = defaultSteer;
+  steerOrResumeImpl = async () => ({ resumed: false });
 });
 
 describe("executeAcpSteer", () => {
-  test("happy path: returns steered status and forwards args to manager", async () => {
+  test("happy path: returns steered status and forwards args to steerOrResume", async () => {
     const result = await executeAcpSteer(
       { acp_session_id: "acp-123", instruction: "stop, do X instead" },
-      makeContext(),
+      makeContext({ withClient: true }),
     );
 
     expect(result.isError).toBe(false);
-    expect(steerCalls).toEqual([
-      { acpSessionId: "acp-123", instruction: "stop, do X instead" },
-    ]);
+    expect(steerOrResumeCalls).toHaveLength(1);
+    expect(steerOrResumeCalls[0]).toMatchObject({
+      acpSessionId: "acp-123",
+      instruction: "stop, do X instead",
+    });
+    expect(typeof steerOrResumeCalls[0]!.send).toBe("function");
+    expect(steerCalls).toEqual([]);
 
     const parsed = JSON.parse(result.content as string);
     expect(parsed).toEqual({
@@ -71,6 +94,7 @@ describe("executeAcpSteer", () => {
     expect(result.isError).toBe(true);
     expect(result.content).toContain('"instruction" is required');
     expect(steerCalls).toEqual([]);
+    expect(steerOrResumeCalls).toEqual([]);
   });
 
   test("missing acp_session_id returns isError", async () => {
@@ -82,9 +106,23 @@ describe("executeAcpSteer", () => {
     expect(result.isError).toBe(true);
     expect(result.content).toContain('"acp_session_id" is required');
     expect(steerCalls).toEqual([]);
+    expect(steerOrResumeCalls).toEqual([]);
+  });
+
+  test("no connected client: steers directly and never resumes", async () => {
+    const result = await executeAcpSteer(
+      { acp_session_id: "acp-direct", instruction: "redirect" },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(false);
+    expect(steerCalls).toEqual([
+      { acpSessionId: "acp-direct", instruction: "redirect" },
+    ]);
+    expect(steerOrResumeCalls).toEqual([]);
   });
 
-  test("manager.steer throwing 'session not found' surfaces the error", async () => {
+  test("'session not found' without a connected client surfaces the error", async () => {
     steerImpl = () =>
       Promise.reject(new Error('ACP session "acp-x" not found'));
 
@@ -96,5 +134,64 @@ describe("executeAcpSteer", () => {
     expect(result.isError).toBe(true);
     expect(result.content).toContain('Could not steer ACP session "acp-x"');
     expect(result.content).toContain("not found");
+    expect(steerOrResumeCalls).toEqual([]);
+  });
+
+  test("resumed session reports the resumed flag and message", async () => {
+    steerOrResumeImpl = async () => ({ resumed: true });
+
+    const result = await executeAcpSteer(
+      { acp_session_id: "acp-gone", instruction: "keep going" },
+      makeContext({ withClient: true }),
+    );
+
+    expect(result.isError).toBe(false);
+    expect(steerOrResumeCalls).toHaveLength(1);
+
+    const parsed = JSON.parse(result.content as string);
+    expect(parsed).toEqual({
+      acpSessionId: "acp-gone",
+      status: "steered",
+      resumed: true,
+      message:
+        "Session was resumed from history; new instruction is now running.",
+    });
+  });
+
+  test("resume failure returns its actionable error message", async () => {
+    steerOrResumeImpl = () =>
+      Promise.reject(
+        new Error(
+          'ACP session "acp-legacy" was recorded before resume support (no working directory persisted) and cannot be resumed. Spawn a new session instead.',
+        ),
+      );
+
+    const result = await executeAcpSteer(
+      { acp_session_id: "acp-legacy", instruction: "more work" },
+      makeContext({ withClient: true }),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain(
+      'Could not steer ACP session "acp-legacy"',
+    );
+    expect(result.content).toContain("recorded before resume support");
+  });
+
+  test("plain steer errors surface unchanged", async () => {
+    steerOrResumeImpl = () =>
+      Promise.reject(
+        new Error(
+          'ACP session "acp-init" is not running (status: initializing)',
+        ),
+      );
+
+    const result = await executeAcpSteer(
+      { acp_session_id: "acp-init", instruction: "redirect" },
+      makeContext({ withClient: true }),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("is not running");
   });
 });

package/src/tools/acp/steer.ts

@@ -1,9 +1,10 @@
 import { getAcpSessionManager } from "../../acp/index.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
+import { getSendToClient } from "./context.js";
 
 export async function executeAcpSteer(
   input: Record<string, unknown>,
-  _context: ToolContext,
+  context: ToolContext,
 ): Promise<ToolExecutionResult> {
   const acpSessionId = input.acp_session_id as string;
   if (!acpSessionId) {
@@ -15,24 +16,54 @@ export async function executeAcpSteer(
     return { content: '"instruction" is required.', isError: true };
   }
 
-  try {
-    const manager = getAcpSessionManager();
-    await manager.steer(acpSessionId, instruction);
+  const manager = getAcpSessionManager();
+  const sendToClient = getSendToClient(context);
 
-    return {
-      content: JSON.stringify({
-        acpSessionId,
-        status: "steered",
-        message:
-          "Interrupted in-flight prompt; new instruction is now running.",
-      }),
-      isError: false,
-    };
+  try {
+    if (!sendToClient) {
+      // Without a connected client there is no one to receive a resumed
+      // session's events, so skip the transparent resume fallback and
+      // steer the in-memory session only.
+      await manager.steer(acpSessionId, instruction);
+      return steeredResult(acpSessionId, { resumed: false });
+    }
+    // Sessions no longer in memory (completed, or lost to a daemon
+    // restart) are transparently resumed from persisted history and the
+    // instruction fired in the same call. Failure messages carry the
+    // actionable hint (e.g. "recorded before resume support", agent
+    // capability missing).
+    const { resumed } = await manager.steerOrResume(
+      acpSessionId,
+      instruction,
+      sendToClient,
+    );
+    return steeredResult(acpSessionId, { resumed });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    return {
-      content: `Could not steer ACP session "${acpSessionId}": ${msg}`,
-      isError: true,
-    };
+    return steerError(acpSessionId, msg);
   }
 }
+
+function steeredResult(
+  acpSessionId: string,
+  opts: { resumed: boolean },
+): ToolExecutionResult {
+  return {
+    content: JSON.stringify({
+      acpSessionId,
+      status: "steered",
+      ...(opts.resumed ? { resumed: true } : {}),
+      message: opts.resumed
+        ? "Session was resumed from history; new instruction is now running."
+        : "Interrupted in-flight prompt; new instruction is now running.",
+    }),
+    isError: false,
+  };
+}
+
+function steerError(acpSessionId: string, msg: string): ToolExecutionResult {
+  return {
+    content: `Could not steer ACP session "${acpSessionId}": ${msg}`,
+    isError: true,
+  };
+}