@vellumai/assistant 0.8.6 → 0.8.7-dev.202606052118.34cd356

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,125 @@
+/**
+ * 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]}`.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { installExecFileStub } from "./__tests__/helpers/exec-file-stub.js";
+
+const { execScripts, execFileMock, reset } = installExecFileStub();
+
+// 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, _resetAdapterInstallCacheForTests } =
+  await import("./auto-install.js");
+
+beforeEach(() => {
+  reset();
+  _resetAdapterInstallCacheForTests();
+});
+
+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",
+    ]);
+  });
+});

package/src/acp/auto-install.ts

@@ -0,0 +1,174 @@
+/**
+ * Silent auto-install for known ACP adapter binaries.
+ *
+ * When a spawn fails 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)
+  );
+}

package/src/acp/prepare-agent-env.ts

@@ -13,15 +13,54 @@
  *
  * The fix: have this single helper own injection + preflight, and have
  * every caller route through it before calling `manager.spawn`.
+ *
+ * Credential reads go through the credential broker (`serverUse`) so they
+ * are policy-gated (tool allowlist) and audit-logged. This keeps
+ * `prepare-agent-env.ts` off the secure-keys import allowlist — the broker
+ * owns the plaintext read boundary.
  */
 
 import { basename } from "node:path";
 
 import { FailedDependencyError } from "../runtime/routes/errors.js";
-import { credentialKey } from "../security/credential-key.js";
-import { getSecureKeyAsync } from "../security/secure-keys.js";
+import { credentialBroker } from "../tools/credentials/broker.js";
+import {
+  getCredentialMetadata,
+  upsertCredentialMetadata,
+} from "../tools/credentials/metadata-store.js";
 import type { AcpAgentConfig } from "./types.js";
 
+const ACP_SPAWN_TOOL = "acp_spawn";
+
+/**
+ * Ensure the `acp/claude_oauth_token` credential has metadata that allows
+ * the `acp_spawn` tool to read it, but only for legacy/unmanaged cases:
+ *
+ * - No metadata at all → create with `allowedTools: ["acp_spawn"]`.
+ * - Metadata exists with an empty `allowedTools` → default provisioning
+ *   path (user ran `credentials set` without `--allowed-tools`), add it.
+ * - Metadata exists with a non-empty `allowedTools` → explicit policy set
+ *   by the user/admin. Respect it even if `acp_spawn` is absent — the
+ *   broker will deny the read and the preflight will throw.
+ */
+function ensureAcpTokenPolicy(): void {
+  const meta = getCredentialMetadata("acp", "claude_oauth_token");
+  if (!meta) {
+    upsertCredentialMetadata("acp", "claude_oauth_token", {
+      allowedTools: [ACP_SPAWN_TOOL],
+      usageDescription:
+        "Claude OAuth token for ACP agent authentication",
+    });
+    return;
+  }
+  const tools = meta.allowedTools ?? [];
+  if (tools.length === 0) {
+    upsertCredentialMetadata("acp", "claude_oauth_token", {
+      allowedTools: [ACP_SPAWN_TOOL],
+    });
+  }
+}
+
 /**
  * Returns a NEW config with any required credentials merged into `env`.
  * Does NOT mutate the input. Throws `FailedDependencyError` if a required
@@ -39,9 +78,8 @@ import type { AcpAgentConfig } from "./types.js";
  *   1. `acp.agents.<id>.env.CLAUDE_CODE_OAUTH_TOKEN` in `config.json` —
  *      the user-supplied env override on the resolved agent config.
  *   2. Secure store via CLI: `assistant credentials set --service acp \
- *        --field claude_oauth_token <token>` — written to the canonical
- *      `credential/{service}/{field}` key built by `credentialKey()`,
- *      used as fallback when (1) is unset.
+ *        --field claude_oauth_token <token>` — read through the
+ *      credential broker for policy enforcement and audit logging.
  * After resolution, this asserts the token is present (from either route)
  * before spawning. The "fail-fast" throw is symmetric with the existing
  * `binary_not_found` preflight in `resolveAcpAgent` and strictly better
@@ -58,12 +96,15 @@ export async function prepareAgentEnv(
 
   if (commandBasename === "claude-agent-acp") {
     if (!env.CLAUDE_CODE_OAUTH_TOKEN) {
-      const claudeToken = await getSecureKeyAsync(
-        credentialKey("acp", "claude_oauth_token"),
-      );
-      if (claudeToken) {
-        env.CLAUDE_CODE_OAUTH_TOKEN = claudeToken;
-      }
+      ensureAcpTokenPolicy();
+      await credentialBroker.serverUse<void>({
+        service: "acp",
+        field: "claude_oauth_token",
+        toolName: ACP_SPAWN_TOOL,
+        execute: async (token) => {
+          env.CLAUDE_CODE_OAUTH_TOKEN = token;
+        },
+      });
     }
     if (!env.CLAUDE_CODE_OAUTH_TOKEN) {
       throw new FailedDependencyError(