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

package/src/acp/agent-process.ts

@@ -34,6 +34,7 @@ export type AcpClientFactory = (agent: Agent) => Client;
 export class AcpAgentProcess {
   private proc: ChildProcess | null = null;
   private connection: acp.ClientSideConnection | null = null;
+  private initializeResponse: InitializeResponse | null = null;
 
   constructor(
     public readonly agentId: string,
@@ -99,7 +100,7 @@ export class AcpAgentProcess {
 
     log.info({ agentId: this.agentId }, "Initializing ACP connection");
 
-    return this.connection.initialize({
+    const response = await this.connection.initialize({
       protocolVersion: acp.PROTOCOL_VERSION,
       clientInfo: { name: "vellum", version: "1.0.0" },
       clientCapabilities: {
@@ -107,6 +108,28 @@ export class AcpAgentProcess {
         terminal: true,
       },
     });
+
+    this.initializeResponse = response;
+    return response;
+  }
+
+  /**
+   * Whether the agent advertised support for `session/load` at initialize.
+   * Returns false before initialize() resolves.
+   */
+  get supportsLoadSession(): boolean {
+    return this.initializeResponse?.agentCapabilities?.loadSession === true;
+  }
+
+  /**
+   * Whether the agent advertised support for `session/resume` at initialize.
+   * Returns false before initialize() resolves.
+   */
+  get supportsSessionResume(): boolean {
+    return (
+      this.initializeResponse?.agentCapabilities?.sessionCapabilities?.resume !=
+      null
+    );
   }
 
   /**
@@ -128,6 +151,41 @@ export class AcpAgentProcess {
     return result.sessionId;
   }
 
+  /**
+   * Loads a previously persisted ACP session via `session/load`.
+   *
+   * Per the ACP spec, the agent replays the session's conversation history
+   * as `session/update` notifications before the load response resolves;
+   * callers should suppress forwarding of those replayed updates (see
+   * VellumAcpClientHandler.beginReplaySuppression).
+   */
+  async loadSession(sessionId: string, cwd: string): Promise<void> {
+    if (!this.connection) {
+      throw new Error(`ACP agent "${this.agentId}" is not spawned`);
+    }
+
+    log.info({ agentId: this.agentId, sessionId, cwd }, "Loading ACP session");
+
+    await this.connection.loadSession({ sessionId, cwd, mcpServers: [] });
+  }
+
+  /**
+   * Resumes a previously persisted ACP session via `session/resume`.
+   *
+   * Unlike `session/load`, resume performs no history replay, so it is
+   * preferred when the agent advertises the capability
+   * (see supportsSessionResume).
+   */
+  async resumeSession(sessionId: string, cwd: string): Promise<void> {
+    if (!this.connection) {
+      throw new Error(`ACP agent "${this.agentId}" is not spawned`);
+    }
+
+    log.info({ agentId: this.agentId, sessionId, cwd }, "Resuming ACP session");
+
+    await this.connection.resumeSession({ sessionId, cwd, mcpServers: [] });
+  }
+
   /**
    * Sends a prompt to an existing ACP session.
    * Returns the prompt response (includes stopReason).
@@ -175,6 +233,7 @@ export class AcpAgentProcess {
       this.proc = null;
     }
     this.connection = null;
+    this.initializeResponse = null;
   }
 
   /**
@@ -205,5 +264,6 @@ export class AcpAgentProcess {
 
     this.proc = null;
     this.connection = null;
+    this.initializeResponse = null;
   }
 }

package/src/acp/auto-install.test.ts

@@ -0,0 +1,196 @@
+/**
+ * Tests for the silent ACP adapter auto-installer.
+ *
+ * `execFile` is stubbed via the shared `installExecFileStub` helper: a
+ * process-global `mock.module("node:child_process", ...)` driven by per-call
+ * scripted responses keyed on `${command} ${args[0]}`. The
+ * `resolveAgentWithAutoInstall` ordering suite additionally stubs the ACP
+ * config and `Bun.which` so it can flip bun / adapter-binary presence.
+ */
+
+import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { installAcpConfigStub } from "./__tests__/helpers/acp-config-stub.js";
+import { installExecFileStub } from "./__tests__/helpers/exec-file-stub.js";
+import { installWhichStub } from "./__tests__/helpers/which-stub.js";
+
+const { execScripts, execFileMock, reset } = installExecFileStub();
+const config = await installAcpConfigStub();
+const which = installWhichStub();
+
+afterAll(() => {
+  which.restore();
+});
+
+// Spread the real module so other test files that load logger consumers
+// (e.g. `truncateForLog` importers) after this process-global mock still
+// resolve every named export.
+const realLogger = await import("../util/logger.js");
+mock.module("../util/logger.js", () => ({
+  ...realLogger,
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+const {
+  ensureAdapterInstalled,
+  resolveAgentWithAutoInstall,
+  _resetAdapterInstallCacheForTests,
+} = await import("./auto-install.js");
+
+beforeEach(() => {
+  reset();
+  _resetAdapterInstallCacheForTests();
+  config.setConfig({ agents: {} });
+  which.setWhich({});
+});
+
+describe("ensureAdapterInstalled", () => {
+  test("known command: runs `npm i -g <pkg>` and reports installed", async () => {
+    execScripts.set("npm i", { stdout: "" });
+
+    const result = await ensureAdapterInstalled("claude-agent-acp");
+
+    expect(result).toEqual({ installed: true });
+    expect(execFileMock).toHaveBeenCalledTimes(1);
+    const [command, args] = execFileMock.mock.calls[0];
+    expect(command).toBe("npm");
+    expect(args).toEqual([
+      "i",
+      "-g",
+      "@agentclientprotocol/claude-agent-acp",
+    ]);
+  });
+
+  test("unknown command: never invokes npm (security allowlist)", async () => {
+    const result = await ensureAdapterInstalled("some-arbitrary-binary");
+
+    expect(result.installed).toBe(false);
+    expect(result.error).toBeUndefined();
+    expect(execFileMock).not.toHaveBeenCalled();
+  });
+
+  test("npm failure: reports the error and does not install", async () => {
+    execScripts.set("npm i", {
+      error: new Error("EACCES: permission denied"),
+    });
+
+    const result = await ensureAdapterInstalled("codex-acp");
+
+    expect(result.installed).toBe(false);
+    expect(result.error).toContain("EACCES");
+  });
+
+  test("failed install is retried on the next call", async () => {
+    execScripts.set("npm i", { error: new Error("network down") });
+    const first = await ensureAdapterInstalled("claude-agent-acp");
+    expect(first.installed).toBe(false);
+
+    execScripts.set("npm i", { stdout: "" });
+    const second = await ensureAdapterInstalled("claude-agent-acp");
+    expect(second.installed).toBe(true);
+    expect(execFileMock).toHaveBeenCalledTimes(2);
+  });
+
+  test("successful install is cached for the process lifetime", async () => {
+    execScripts.set("npm i", { stdout: "" });
+
+    await ensureAdapterInstalled("claude-agent-acp");
+    await ensureAdapterInstalled("claude-agent-acp");
+
+    expect(execFileMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("concurrent calls dedupe to exactly one `npm i -g`", async () => {
+    execScripts.set("npm i", { stdout: "" });
+
+    const [a, b, c] = await Promise.all([
+      ensureAdapterInstalled("claude-agent-acp"),
+      ensureAdapterInstalled("claude-agent-acp"),
+      ensureAdapterInstalled("claude-agent-acp"),
+    ]);
+
+    expect(a.installed).toBe(true);
+    expect(b.installed).toBe(true);
+    expect(c.installed).toBe(true);
+    expect(execFileMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("different commands install independently", async () => {
+    execScripts.set("npm i", { stdout: "" });
+
+    const [claude, codex] = await Promise.all([
+      ensureAdapterInstalled("claude-agent-acp"),
+      ensureAdapterInstalled("codex-acp"),
+    ]);
+
+    expect(claude.installed).toBe(true);
+    expect(codex.installed).toBe(true);
+    expect(execFileMock).toHaveBeenCalledTimes(2);
+    const installedPackages = execFileMock.mock.calls.map(
+      (call) => (call[1] as string[])[2],
+    );
+    expect(installedPackages.sort()).toEqual([
+      "@agentclientprotocol/claude-agent-acp",
+      "@zed-industries/codex-acp",
+    ]);
+  });
+});
+
+describe("resolveAgentWithAutoInstall - resolution order", () => {
+  test("binary missing + bun present: resolves via bunx without invoking npm", async () => {
+    which.setWhich({ bun: "/usr/local/bin/bun" });
+
+    const result = await resolveAgentWithAutoInstall("claude");
+
+    expect(result.resolved.ok).toBe(true);
+    if (!result.resolved.ok) return;
+    expect(result.resolved.agent.command).toBe("bun");
+    expect(result.resolved.agent.adapterCommand).toBe("claude-agent-acp");
+    expect(result.autoInstalledPackage).toBeUndefined();
+    expect(result.failureMessage).toBeUndefined();
+    expect(execFileMock).not.toHaveBeenCalled();
+  });
+
+  test("binary + bun missing, npm install succeeds: falls back to the npm flow", async () => {
+    let installed = false;
+    which.setWhich((cmd) =>
+      installed && cmd === "claude-agent-acp"
+        ? "/usr/local/bin/claude-agent-acp"
+        : null,
+    );
+    execScripts.set("npm i", {
+      stdout: "",
+      onCall: () => {
+        installed = true;
+      },
+    });
+
+    const result = await resolveAgentWithAutoInstall("claude");
+
+    expect(result.resolved.ok).toBe(true);
+    if (!result.resolved.ok) return;
+    expect(result.resolved.agent.command).toBe("claude-agent-acp");
+    expect(result.autoInstalledPackage).toBe(
+      "@agentclientprotocol/claude-agent-acp",
+    );
+    expect(execFileMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("binary, bun, and npm all missing: failure message carries the hint and install error", async () => {
+    execScripts.set("npm i", { error: new Error("spawn npm ENOENT") });
+
+    const result = await resolveAgentWithAutoInstall("claude");
+
+    expect(result.resolved.ok).toBe(false);
+    expect(result.failureMessage).toContain(
+      "claude-agent-acp is not on PATH",
+    );
+    expect(result.failureMessage).toContain(
+      "npm i -g @agentclientprotocol/claude-agent-acp",
+    );
+    expect(result.failureMessage).toContain("ENOENT");
+  });
+});

package/src/acp/auto-install.ts

@@ -0,0 +1,177 @@
+/**
+ * Silent auto-install for known ACP adapter binaries.
+ *
+ * Fallback path: the resolver (`resolve-agent.ts`) already rewrites missing
+ * allowlisted adapters to run via `bun x` when `bun` is on PATH, so
+ * `binary_not_found` only reaches this module when bun is absent (or the
+ * command has no package mapping). When a spawn does fail preflight with
+ * `binary_not_found`, callers (the `acp_spawn` tool and the `/v1/acp/spawn`
+ * route) call `resolveAgentWithAutoInstall(agentId)`, which tries a global
+ * npm install of the mapped adapter package, then re-resolves and continues.
+ * On failure they fall back to the existing actionable install hint.
+ *
+ * Security boundary: only commands present in `DEFAULT_AGENT_NPM_PACKAGES`
+ * are ever installed. The package names are vendored constants, NOT user
+ * input: an arbitrary command from user config must never be turned into
+ * an `npm i -g <attacker-controlled-name>` execution.
+ */
+
+import { execFile } from "node:child_process";
+
+import { DEFAULT_AGENT_NPM_PACKAGES } from "../config/acp-defaults.js";
+import { getLogger } from "../util/logger.js";
+import {
+  resolveAcpAgent,
+  type ResolveAcpAgentResult,
+} from "./resolve-agent.js";
+
+const log = getLogger("acp:auto-install");
+
+/** Per-install timeout for `npm i -g`. Generous: cold npm caches are slow. */
+const NPM_INSTALL_TIMEOUT_MS = 120_000;
+
+export interface AdapterInstallResult {
+  installed: boolean;
+  error?: string;
+}
+
+/**
+ * Per-command install promises. Concurrent spawns for the same missing
+ * binary dedupe to a single `npm i -g`; successful results are cached for
+ * the process lifetime. Failed installs are evicted so a later spawn can
+ * retry (e.g. after the user fixes network or npm permissions).
+ */
+const installPromises = new Map<string, Promise<AdapterInstallResult>>();
+
+/**
+ * Run `execFile` with an AbortController-driven timeout. Returns the stdout
+ * on success; throws on error or timeout. Shared by the adapter installer
+ * here and the version probes in `tools/acp/spawn.ts`.
+ */
+export 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);
+      },
+    );
+  });
+}
+
+/**
+ * Install the npm package mapped to `command` if (and only if) the command
+ * is a known adapter binary. Unknown commands resolve to
+ * `{ installed: false }` without ever invoking npm (see the security
+ * boundary note in the module doc).
+ */
+export function ensureAdapterInstalled(
+  command: string,
+): Promise<AdapterInstallResult> {
+  const packageName = DEFAULT_AGENT_NPM_PACKAGES[command];
+  if (!packageName) {
+    return Promise.resolve({ installed: false });
+  }
+
+  const inFlight = installPromises.get(command);
+  if (inFlight) return inFlight;
+
+  const promise = runInstall(command, packageName).then((result) => {
+    if (!result.installed) installPromises.delete(command);
+    return result;
+  });
+  installPromises.set(command, promise);
+  return promise;
+}
+
+async function runInstall(
+  command: string,
+  packageName: string,
+): Promise<AdapterInstallResult> {
+  log.info({ command, packageName }, "Auto-installing missing ACP adapter");
+  try {
+    await execFileWithTimeout(
+      "npm",
+      ["i", "-g", packageName],
+      NPM_INSTALL_TIMEOUT_MS,
+    );
+    log.info({ command, packageName }, "ACP adapter auto-install succeeded");
+    return { installed: true };
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    log.warn(
+      { err, command, packageName },
+      "ACP adapter auto-install failed (falling back to install hint)",
+    );
+    return { installed: false, error };
+  }
+}
+
+export interface ResolveWithAutoInstallResult {
+  /** The final resolver outcome (post-install re-resolve when applicable). */
+  resolved: ResolveAcpAgentResult;
+  /** Set when a missing adapter binary was silently installed via npm. */
+  autoInstalledPackage?: string;
+  /**
+   * Set when the auto-install itself failed: the original install hint
+   * augmented with the npm failure reason. Callers should surface this
+   * instead of re-deriving a message from `resolved`.
+   */
+  failureMessage?: string;
+}
+
+/**
+ * Resolve an ACP agent id, silently auto-installing the mapped adapter
+ * package when (and only when) the failure is a missing allowlisted binary.
+ * Shared by the `acp_spawn` tool and the `/v1/acp/spawn` route so the
+ * resolve-install-re-resolve flow has a single implementation; callers map
+ * the result to their transport (tool error result vs. HTTP error class).
+ */
+export async function resolveAgentWithAutoInstall(
+  agentId: string,
+): Promise<ResolveWithAutoInstallResult> {
+  const resolved = resolveAcpAgent(agentId);
+  if (resolved.ok || resolved.reason !== "binary_not_found") {
+    return { resolved };
+  }
+
+  const { command, hint } = resolved;
+  const install = await ensureAdapterInstalled(command);
+  if (install.installed) {
+    const retried = resolveAcpAgent(agentId);
+    if (retried.ok) {
+      log.info(
+        { agentId, command },
+        "Auto-installed missing ACP adapter binary",
+      );
+      return {
+        resolved: retried,
+        autoInstalledPackage: DEFAULT_AGENT_NPM_PACKAGES[command],
+      };
+    }
+  } else if (install.error) {
+    return {
+      resolved,
+      failureMessage: `${command} is not on PATH. ${hint} (auto-install failed: ${install.error})`,
+    };
+  }
+  return { resolved };
+}
+
+/** @internal: exposed for tests only. */
+export function _resetAdapterInstallCacheForTests(): void {
+  installPromises.clear();
+}

package/src/acp/client-handler.ts

@@ -51,6 +51,7 @@ interface TerminalState {
 export class VellumAcpClientHandler implements Client {
   private terminals = new Map<string, TerminalState>();
   private accumulatedText = "";
+  private suppressForwarding = false;
   /** Tracks pending ACP permission requestIds for cleanup on session close. */
   readonly pendingRequestIds = new Set<string>();
 
@@ -65,8 +66,38 @@ export class VellumAcpClientHandler implements Client {
     private readonly parentConversationId: string,
   ) {}
 
+  /**
+   * Begins suppressing session updates from being forwarded to Vellum.
+   *
+   * Per the ACP spec, `session/load` replays the entire conversation history
+   * as `session/update` notifications before the load response resolves. The
+   * parent conversation already received those events during the original
+   * run, so re-forwarding them would duplicate them into the conversation and
+   * the ring buffer. Callers wrap `loadSession` in
+   * beginReplaySuppression()/endReplaySuppression() to drop the replay.
+   * `session/resume` performs no replay, which is why it is preferred when
+   * the agent supports it.
+   */
+  beginReplaySuppression(): void {
+    this.suppressForwarding = true;
+  }
+
+  /** Ends replay suppression; subsequent updates flow normally. */
+  endReplaySuppression(): void {
+    this.suppressForwarding = false;
+  }
+
   async sessionUpdate(params: SessionNotification): Promise<void> {
     const update = params.update;
+
+    if (this.suppressForwarding) {
+      log.debug(
+        { acpSessionId: this.acpSessionId, updateType: update.sessionUpdate },
+        "Dropping replayed session update during suppression",
+      );
+      return;
+    }
+
     log.debug(
       { acpSessionId: this.acpSessionId, updateType: update.sessionUpdate },
       "ACP session update received",

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)
+  );
+}