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

package/src/telemetry/usage-telemetry-reporter.ts

@@ -15,6 +15,7 @@ import {
   getPlatformUserId,
 } from "../config/env.js";
 import { getConfig } from "../config/loader.js";
+import { queryUnreportedAuthFallbackEvents } from "../memory/auth-fallback-events-store.js";
 import {
   getMemoryCheckpoint,
   setMemoryCheckpoint,
@@ -47,6 +48,10 @@ const CHECKPOINT_KEY_ONBOARDING_WATERMARK =
   "telemetry:onboarding:last_reported_at";
 const CHECKPOINT_KEY_ONBOARDING_WATERMARK_ID =
   "telemetry:onboarding:last_reported_id";
+const CHECKPOINT_KEY_AUTH_FALLBACK_WATERMARK =
+  "telemetry:auth_fallback:last_reported_at";
+const CHECKPOINT_KEY_AUTH_FALLBACK_WATERMARK_ID =
+  "telemetry:auth_fallback:last_reported_id";
 const REPORT_INTERVAL_MS = 5 * 60 * 1000;
 const INITIAL_FLUSH_DELAY_MS = 30_000; // Delay first flush to let CES handshake complete
 const BATCH_SIZE = 500;
@@ -139,6 +144,7 @@ export class UsageTelemetryReporter {
         setMemoryCheckpoint(CHECKPOINT_KEY_TURN_WATERMARK, now);
         setMemoryCheckpoint(CHECKPOINT_KEY_LIFECYCLE_WATERMARK, now);
         setMemoryCheckpoint(CHECKPOINT_KEY_ONBOARDING_WATERMARK, now);
+        setMemoryCheckpoint(CHECKPOINT_KEY_AUTH_FALLBACK_WATERMARK, now);
         return;
       }
 
@@ -171,6 +177,14 @@ export class UsageTelemetryReporter {
         getMemoryCheckpoint(CHECKPOINT_KEY_ONBOARDING_WATERMARK_ID) ??
         undefined;
 
+      // Read auth-fallback watermark (compound cursor: createdAt + id)
+      const authFallbackWatermark = Number(
+        getMemoryCheckpoint(CHECKPOINT_KEY_AUTH_FALLBACK_WATERMARK) ?? "0",
+      );
+      const authFallbackWatermarkId =
+        getMemoryCheckpoint(CHECKPOINT_KEY_AUTH_FALLBACK_WATERMARK_ID) ??
+        undefined;
+
       // Query unreported events
       const events = queryUnreportedUsageEvents(
         watermark,
@@ -192,12 +206,18 @@ export class UsageTelemetryReporter {
         onboardingWatermarkId,
         BATCH_SIZE,
       );
+      const authFallbackEvents = queryUnreportedAuthFallbackEvents(
+        authFallbackWatermark,
+        authFallbackWatermarkId,
+        BATCH_SIZE,
+      );
 
       if (
         events.length === 0 &&
         turnEvents.length === 0 &&
         lifecycleEvents.length === 0 &&
-        onboardingEvents.length === 0
+        onboardingEvents.length === 0 &&
+        authFallbackEvents.length === 0
       )
         return;
 
@@ -211,6 +231,7 @@ export class UsageTelemetryReporter {
           turnCount: turnEvents.length,
           lifecycleCount: lifecycleEvents.length,
           onboardingCount: onboardingEvents.length,
+          authFallbackCount: authFallbackEvents.length,
         },
         "Telemetry flush: resolved auth context",
       );
@@ -337,6 +358,25 @@ export class UsageTelemetryReporter {
             assistant_version: APP_VERSION,
           }),
         ),
+        ...authFallbackEvents.map(
+          (e): TelemetryEvent => ({
+            type: "auth_fallback",
+            daemon_event_id: e.id,
+            recorded_at: e.createdAt,
+            guard: e.guard,
+            path: e.path,
+            failure_kind: e.failureKind,
+            count: e.count,
+            window_start: e.windowStart,
+            window_end: e.windowEnd,
+            // Aggregated counts forwarded by the gateway carry no record-time
+            // binary version; stamp the running binary's `APP_VERSION` so the
+            // wire value is concrete rather than an explicit null that would
+            // override the envelope under the platform's per-event-wins
+            // contract.
+            assistant_version: APP_VERSION,
+          }),
+        ),
       ];
 
       const organizationId = getPlatformOrganizationId() || undefined;
@@ -422,12 +462,27 @@ export class UsageTelemetryReporter {
         );
       }
 
+      // Advance auth-fallback watermark (compound cursor)
+      if (authFallbackEvents.length > 0) {
+        const lastAuthFallback =
+          authFallbackEvents[authFallbackEvents.length - 1];
+        setMemoryCheckpoint(
+          CHECKPOINT_KEY_AUTH_FALLBACK_WATERMARK,
+          String(lastAuthFallback.createdAt),
+        );
+        setMemoryCheckpoint(
+          CHECKPOINT_KEY_AUTH_FALLBACK_WATERMARK_ID,
+          lastAuthFallback.id,
+        );
+      }
+
       // If we got a full batch of any type, there may be more — recurse
       if (
         events.length === BATCH_SIZE ||
         turnEvents.length === BATCH_SIZE ||
         lifecycleEvents.length === BATCH_SIZE ||
-        onboardingEvents.length === BATCH_SIZE
+        onboardingEvents.length === BATCH_SIZE ||
+        authFallbackEvents.length === BATCH_SIZE
       ) {
         await this._doFlush(batchCount + 1);
       }

package/src/tools/acp/context.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared ToolContext accessors for the ACP tools.
+ */
+
+import type { ServerMessage } from "../../daemon/message-protocol.js";
+import type { ToolContext } from "../types.js";
+
+/**
+ * Narrows `ToolContext.sendToClient` to the `ServerMessage` sender the ACP
+ * session manager expects. ToolContext types the callback against an
+ * index-signature message shape (`{ type: string; [key: string]: unknown }`)
+ * that ServerMessage's union members don't structurally satisfy, so the
+ * cast lives here once instead of being duplicated at every ACP tool call
+ * site.
+ */
+export function getSendToClient(
+  context: ToolContext,
+): ((msg: ServerMessage) => void) | undefined {
+  return context.sendToClient as ((msg: ServerMessage) => void) | undefined;
+}

package/src/tools/acp/list-agents.test.ts

@@ -47,7 +47,7 @@ describe("executeAcpListAgents", () => {
     expect(parsed.hint).toContain("config.json");
   });
 
-  test("enabled, no user config: both defaults present with source 'default' and available based on Bun.which", async () => {
+  test("enabled, no user config: all defaults present with source 'default' and available based on Bun.which", async () => {
     config.setConfig({ agents: {} });
 
     const result = await executeAcpListAgents({}, makeContext());
@@ -58,6 +58,7 @@ describe("executeAcpListAgents", () => {
     expect(parsed.agents.map((a: { id: string }) => a.id)).toEqual([
       "claude",
       "codex",
+      "gemini",
     ]);
     for (const entry of parsed.agents) {
       expect(entry.source).toBe("default");
@@ -108,6 +109,11 @@ describe("executeAcpListAgents", () => {
     expect(codex.unavailableReason).toBe("'codex-acp' is not on PATH");
     expect(codex.setupHint).toBe("npm i -g @zed-industries/codex-acp");
 
+    const gemini = parsed.agents.find((a: { id: string }) => a.id === "gemini");
+    expect(gemini.available).toBe(false);
+    expect(gemini.unavailableReason).toBe("'gemini' is not on PATH");
+    expect(gemini.setupHint).toBe("npm i -g @google/gemini-cli");
+
     const claude = parsed.agents.find((a: { id: string }) => a.id === "claude");
     expect(claude.available).toBe(true);
     expect(claude.setupHint).toBeUndefined();

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

@@ -1,7 +1,7 @@
-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 { installExecFileStub } from "../../acp/__tests__/helpers/exec-file-stub.js";
 import { installWhichStub } from "../../acp/__tests__/helpers/which-stub.js";
 import type { ToolContext } from "../types.js";
 
@@ -9,55 +9,11 @@ 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,
-}));
+const {
+  execScripts,
+  execFileMock,
+  reset: resetExecFileStub,
+} = installExecFileStub();
 
 // 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
@@ -189,6 +145,9 @@ mock.module("../../acp/index.js", () => ({
 
 const { executeAcpSpawn, _resetAdapterVersionCacheForTests } =
   await import("./spawn.js");
+const { _resetAdapterInstallCacheForTests } = await import(
+  "../../acp/auto-install.js"
+);
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -204,10 +163,10 @@ function makeContext(): ToolContext {
 }
 
 beforeEach(() => {
-  execScripts.clear();
-  execFileMock.mockClear();
+  resetExecFileStub();
   spawnMock.mockClear();
   _resetAdapterVersionCacheForTests();
+  _resetAdapterInstallCacheForTests();
   config.setConfig({ agents: DEFAULT_TEST_AGENTS });
   which.setWhich((cmd) => `/usr/local/bin/${cmd}`);
   // Default: vault has a claude token so the preflight in `prepareAgentEnv`
@@ -391,8 +350,9 @@ describe("executeAcpSpawn — input validation", () => {
     expect(result.content).toContain("acp.enabled");
   });
 
-  test("missing binary returns install hint", async () => {
+  test("missing binary returns install hint when auto-install fails", async () => {
     which.setWhich({});
+    execScripts.set("npm i", { error: new Error("npm not installed") });
     const result = await executeAcpSpawn(
       { agent: "claude", task: "do something" },
       makeContext(),
@@ -426,6 +386,149 @@ describe("executeAcpSpawn — input validation", () => {
   });
 });
 
+describe("executeAcpSpawn: auto-install on missing binary", () => {
+  test("known command: installs the mapped package and spawn proceeds with a note", async () => {
+    // Binary appears on PATH only after `npm i -g` runs, simulating a
+    // successful global install.
+    let binaryOnPath = false;
+    which.setWhich((cmd) => (binaryOnPath ? `/usr/local/bin/${cmd}` : null));
+    execScripts.set("npm i", {
+      stdout: "",
+      onCall: () => {
+        binaryOnPath = true;
+      },
+    });
+    // Version probes after the install: best-effort, scripted to skip.
+    execScripts.set("npm ls", { error: new Error("skip") });
+    execScripts.set("npm view", { error: new Error("skip") });
+
+    const result = await executeAcpSpawn(
+      { agent: "claude", task: "do something" },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(false);
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    const [payloadJson] = result.content.split("\n\n");
+    const payload = JSON.parse(payloadJson);
+    expect(payload.message).toContain(
+      "Installed @agentclientprotocol/claude-agent-acp automatically.",
+    );
+    const installCalls = execFileMock.mock.calls.filter(
+      (call) => (call[1] as string[])[0] === "i",
+    );
+    expect(installCalls).toHaveLength(1);
+    expect(installCalls[0][1]).toEqual([
+      "i",
+      "-g",
+      "@agentclientprotocol/claude-agent-acp",
+    ]);
+  });
+
+  test("unknown command: no install attempted, plain hint returned", async () => {
+    which.setWhich({});
+
+    const result = await executeAcpSpawn(
+      { agent: "unknown-agent", task: "do something" },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("some-other-binary is not on PATH");
+    expect(result.content).toContain("Install 'some-other-binary'");
+    expect(result.content).not.toContain("auto-install failed");
+    expect(execFileMock).not.toHaveBeenCalled();
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+
+  test("no client connected: no install attempted even when the binary is missing", async () => {
+    // The no-client guard is a pure precondition and must run BEFORE the
+    // auto-install side effect: without a client the spawn fails anyway, so
+    // the host must not be mutated by `npm i -g` (which can also block for
+    // up to the install timeout).
+    which.setWhich({});
+
+    const result = await executeAcpSpawn(
+      { agent: "claude", task: "do something" },
+      { ...makeContext(), sendToClient: undefined },
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("No client connected");
+    expect(execFileMock).not.toHaveBeenCalled();
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+
+  test("npm failure: hint and install failure both surface", async () => {
+    which.setWhich({});
+    execScripts.set("npm i", {
+      error: new Error("EACCES: permission denied"),
+    });
+
+    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(result.content).toContain("auto-install failed");
+    expect(result.content).toContain("EACCES");
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+});
+
+describe("executeAcpSpawn - bunx fallback when binary missing", () => {
+  test("binary missing + bun present: spawns via `bun x` with env injection and resume hint, no npm calls", async () => {
+    // Only bun is on PATH - the platform-hosted image (bun, no node/npm).
+    which.setWhich({ bun: "/usr/local/bin/bun" });
+
+    const result = await executeAcpSpawn(
+      { agent: "claude", task: "do something" },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(false);
+    // No npm install AND no npm version probe: bunx fetches the package on
+    // first use and there is no global install to compare.
+    expect(execFileMock).not.toHaveBeenCalled();
+    expect(result.content).not.toContain("outdated");
+
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    const agentConfigArg = spawnMock.mock.calls[0][1] as {
+      command: string;
+      args: string[];
+      adapterCommand?: string;
+      env?: Record<string, string>;
+    };
+    expect(agentConfigArg.command).toBe("bun");
+    expect(agentConfigArg.args).toEqual([
+      "x",
+      "--bun",
+      "@agentclientprotocol/claude-agent-acp",
+    ]);
+    expect(agentConfigArg.adapterCommand).toBe("claude-agent-acp");
+    // CLAUDE_CODE_OAUTH_TOKEN injection still applies to the bunx-resolved
+    // claude adapter (gated on adapterCommand, not the spawn command).
+    expect(agentConfigArg.env?.CLAUDE_CODE_OAUTH_TOKEN).toBe(
+      "default-test-token",
+    );
+
+    const [payloadJson] = result.content.split("\n\n");
+    const payload = JSON.parse(payloadJson);
+    // No auto-install happened; the claude resume hint still fires.
+    expect(payload.message).not.toContain("Installed");
+    expect(payload.message).toContain("claude --resume");
+  });
+
+  // The bun-absent npm fallback is covered by the existing auto-install
+  // suite below ("known command: installs the mapped package..."), whose
+  // which-stub leaves bun off PATH until the install completes.
+});
+
 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") });
@@ -440,7 +543,7 @@ describe("executeAcpSpawn — per-agent resume hint", () => {
     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");
+    expect(payload.message).toContain("To resume:");
   });
 
   test("non-claude payload omits the `claude --resume` hint", async () => {
@@ -458,7 +561,7 @@ describe("executeAcpSpawn — per-agent resume hint", () => {
     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");
+    expect(payload.message).not.toContain("To resume:");
   });
 });
 

package/src/tools/acp/spawn.ts

@@ -1,11 +1,19 @@
-import { execFile } from "node:child_process";
-
+import {
+  execFileWithTimeout,
+  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 {
+  adapterCommandOf,
+  formatResolveFailure,
+  runsViaBunx,
+} from "../../acp/resolve-agent.js";
+import { claudeResumeHint } from "../../acp/resume-hint.js";
 import { DEFAULT_AGENT_NPM_PACKAGES } from "../../config/acp-defaults.js";
 import { getLogger } from "../../util/logger.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
+import { getSendToClient } from "./context.js";
 
 const log = getLogger("acp:spawn");
 
@@ -25,35 +33,6 @@ interface AdapterVersionInfo {
   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
@@ -135,34 +114,10 @@ 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 `npm i -g` 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 +125,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`,
@@ -185,8 +151,12 @@ export async function executeAcpSpawn(
   }
 
   // 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);
+  // append a non-blocking warning to the success payload. Skipped for
+  // bunx-resolved agents: there is no global npm install to compare (bun
+  // fetches the package on first use), and npm may not exist on the host.
+  const versionInfo = runsViaBunx(agentConfig)
+    ? null
+    : await checkAdapterVersion(adapterCommandOf(agentConfig));
 
   try {
     const manager = getAcpSessionManager();
@@ -197,17 +167,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
+    // canonical adapter command so it survives the bunx rewrite. See
+    // acp/resume-hint.ts for the gating rationale.
+    const hint = claudeResumeHint(
+      adapterCommandOf(agentConfig),
+      cwd,
+      protocolSessionId,
+    );
+    const resumeHint = hint ? ` ${hint}` : "";
+    const installNote = autoInstalledPackage
+      ? ` Installed ${autoInstalledPackage} automatically.`
+      : "";
     const payload = JSON.stringify({
       acpSessionId,
       protocolSessionId,
@@ -216,7 +190,8 @@ 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;