@vellumai/assistant 0.8.0 → 0.8.1

package/src/tools/browser/cdp-client/factory.ts

@@ -97,6 +97,13 @@ export interface GetCdpClientOptions {
    * and disables failover.
    */
   mode?: BrowserMode;
+  /**
+   * Explicit target client id. When provided, the extension backend routes
+   * to this specific client instead of auto-resolving to the most-recently-
+   * active same-actor host_browser client. Mirrors the `target_client_id`
+   * pattern on host_bash/host_file/host_cu.
+   */
+  targetClientId?: string;
 }
 
 /**
@@ -151,10 +158,11 @@ export function getCdpClient(
   options?: GetCdpClientOptions,
 ): ScopedCdpClient {
   const mode: BrowserMode = options?.mode ?? "auto";
+  const targetClientId = options?.targetClientId;
   const candidates =
     mode === "auto"
-      ? buildCandidateList(context)
-      : buildPinnedCandidateList(context, mode);
+      ? buildCandidateList(context, targetClientId)
+      : buildPinnedCandidateList(context, mode, targetClientId);
 
   log.debug(
     {
@@ -182,8 +190,9 @@ export function getCdpClient(
 export function buildPinnedCandidateList(
   context: ToolContext,
   mode: Exclude<BrowserMode, "auto">,
+  targetClientId?: string,
 ): BackendCandidate[] {
-  const { conversationId } = context;
+  const { conversationId, sourceActorPrincipalId } = context;
 
   switch (mode) {
     case "extension": {
@@ -213,6 +222,9 @@ export function buildPinnedCandidateList(
             const client = createExtensionCdpClient(
               hostBrowserProxy,
               conversationId,
+              undefined,
+              sourceActorPrincipalId,
+              targetClientId,
             );
             const backend = createExtensionBackend({
               isAvailable: () => true,
@@ -286,11 +298,57 @@ export function buildPinnedCandidateList(
  *
  * Exported for testing.
  */
-export function buildCandidateList(context: ToolContext): BackendCandidate[] {
-  const { conversationId } = context;
+export function buildCandidateList(context: ToolContext, targetClientId?: string): BackendCandidate[] {
+  const { conversationId, sourceActorPrincipalId } = context;
   const candidates: BackendCandidate[] = [];
   const hostBrowserProxy = HostBrowserProxy.instance;
 
+  // When a specific host client is targeted, only the extension proxy can
+  // route to it. Skip the fallback chain entirely: if the extension is
+  // unavailable, fail loudly rather than silently routing to a different
+  // browser.
+  if (targetClientId != null) {
+    if (!hostBrowserProxy.hasExtensionClient()) {
+      throw new CdpError(
+        "transport_error",
+        `Cannot reach target_client_id "${targetClientId}": no Chrome Extension connected`,
+        {
+          attemptDiagnostics: [
+            {
+              candidateKind: "extension",
+              inclusionReason: "target_client_id requires extension proxy",
+              stage: "candidate_selection",
+              errorCode: "transport_error",
+              errorMessage: "no Chrome Extension connected",
+            },
+          ],
+        },
+      );
+    }
+    return [
+      {
+        kind: "extension",
+        reason: `target_client_id override: ${targetClientId}`,
+        create() {
+          const client = createExtensionCdpClient(
+            hostBrowserProxy,
+            conversationId,
+            undefined,
+            sourceActorPrincipalId,
+            targetClientId,
+          );
+          const backend = createExtensionBackend({
+            isAvailable: () => true,
+            sendCdp: (command, signal) =>
+              dispatchThroughClient(client, command, signal),
+            dispose: () => client.dispose(),
+          });
+          return { client, backend };
+        },
+      },
+    ];
+  }
+
   // 1. Extension -- preferred when a Chrome Extension client is connected.
   if (hostBrowserProxy.hasExtensionClient()) {
     candidates.push({
@@ -300,6 +358,9 @@ export function buildCandidateList(context: ToolContext): BackendCandidate[] {
         const client = createExtensionCdpClient(
           hostBrowserProxy,
           conversationId,
+          undefined,
+          sourceActorPrincipalId,
+          targetClientId,
         );
         const backend = createExtensionBackend({
           isAvailable: () => true,

package/src/tools/browser/runtime-check.ts

@@ -2,8 +2,11 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { ensureBun } from "../../util/bun-runtime.js";
+import { getLogger } from "../../util/logger.js";
 import { getExternalDir } from "../../util/platform.js";
 
+const log = getLogger("runtime-check");
+
 export interface BrowserRuntimeStatus {
   playwrightAvailable: boolean;
   chromiumInstalled: boolean;
@@ -110,6 +113,80 @@ export async function importPlaywright(): Promise<typeof import("playwright")> {
   return mod as unknown as typeof import("playwright");
 }
 
+/** In-flight headless shell install promise to deduplicate concurrent callers. */
+let headlessShellInstalling: Promise<void> | undefined;
+
+/**
+ * Ensure the Chromium headless shell binary is available on disk.
+ * Downloads it on-demand via `playwright install --only-shell chromium`
+ * if the binary is missing. Only installs the lightweight headless shell
+ * (~111 MB), not the full Chrome for Testing browser.
+ */
+export async function ensureChromiumHeadlessShell(
+  pw: typeof import("playwright"),
+): Promise<void> {
+  try {
+    const execPath = pw.chromium.executablePath();
+    if (existsSync(execPath)) return;
+  } catch {
+    // executablePath() may throw if the browser registry is missing
+  }
+
+  if (headlessShellInstalling) {
+    await headlessShellInstalling;
+    return;
+  }
+
+  headlessShellInstalling = (async () => {
+    log.info("Chromium headless shell not found, installing...");
+    const bunPath = await ensureBun();
+
+    // Run the CLI from the same directory where importPlaywright() installed
+    // the package so the resolved playwright version matches the pw module.
+    const externalDir = getExternalDir();
+    const externalPwExists = existsSync(
+      join(externalDir, "node_modules", "playwright", "package.json"),
+    );
+
+    const proc = Bun.spawn(
+      [bunPath, "x", "playwright", "install", "--only-shell", "chromium"],
+      {
+        stdout: "pipe",
+        stderr: "pipe",
+        cwd: externalPwExists ? externalDir : undefined,
+      },
+    );
+    const timeoutMs = 120_000;
+    let timer: ReturnType<typeof setTimeout>;
+    const exitCode = await Promise.race([
+      proc.exited.finally(() => clearTimeout(timer)),
+      new Promise<never>(
+        (_, reject) =>
+          (timer = setTimeout(() => {
+            proc.kill();
+            reject(
+              new Error(
+                `Chromium headless shell install timed out after ${timeoutMs / 1000}s`,
+              ),
+            );
+          }, timeoutMs)),
+      ),
+    ]);
+    if (exitCode === 0) {
+      log.info("Chromium headless shell installed successfully");
+    } else {
+      const stderr = await new Response(proc.stderr).text();
+      throw new Error(
+        `Failed to install Chromium headless shell: ${stderr.trim() || `exit code ${exitCode}`}`,
+      );
+    }
+  })().finally(() => {
+    headlessShellInstalling = undefined;
+  });
+
+  await headlessShellInstalling;
+}
+
 export async function checkBrowserRuntime(): Promise<BrowserRuntimeStatus> {
   // Diagnostic only - no side effects (no playwright installation)
   let chromium: { executablePath: () => string };

package/src/tools/memory/register.test.ts

@@ -126,7 +126,7 @@ describe("recallTool definition", () => {
       type: "array",
       items: {
         type: "string",
-        enum: ["memory", "pkb", "conversations", "workspace"],
+        enum: ["memory", "conversations", "workspace"],
       },
     });
     expect(properties.max_results).toMatchObject({
@@ -179,7 +179,7 @@ describe("recallTool.execute", () => {
     const result = await recallTool.execute(
       {
         query: "release notes",
-        sources: ["pkb", "workspace"],
+        sources: ["memory", "workspace"],
         max_results: 4,
         depth: "deep",
       },
@@ -193,7 +193,7 @@ describe("recallTool.execute", () => {
     expect(recallCalls).toHaveLength(1);
     expect(recallCalls[0]?.input).toEqual({
       query: "release notes",
-      sources: ["pkb", "workspace"],
+      sources: ["memory", "workspace"],
       max_results: 4,
       depth: "deep",
     });

package/src/tools/memory/register.ts

@@ -6,6 +6,7 @@ import {
   type RememberInput,
 } from "../../memory/graph/tool-handlers.js";
 import {
+  getRememberDescription,
   graphRecallDefinition,
   graphRememberDefinition,
 } from "../../memory/graph/tools.js";
@@ -18,12 +19,19 @@ import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 
 class RememberTool implements Tool {
   name = "remember";
+  // Surfaced in registry listings. The flag-aware description used during
+  // actual tool dispatch is computed lazily in `getDefinition()` below so it
+  // tracks config changes across daemon lifetime without needing a tool
+  // re-registration pass.
   description = graphRememberDefinition.description;
   category = "memory";
   defaultRiskLevel = RiskLevel.Low;
 
   getDefinition(): ToolDefinition {
-    return graphRememberDefinition;
+    return {
+      ...graphRememberDefinition,
+      description: getRememberDescription(getConfig()),
+    };
   }
 
   async execute(

package/src/tools/network/__tests__/web-search.test.ts

@@ -4,6 +4,7 @@ import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 let mockWebSearchProvider: string | undefined = "perplexity";
 let mockBraveSecureKey: string | undefined;
 let mockPerplexitySecureKey: string | undefined;
+let mockTavilySecureKey: string | undefined;
 
 // Capture the registered tool
 let capturedTool: any = null;
@@ -26,6 +27,7 @@ mock.module("../../../security/secure-keys.js", () => ({
   getProviderKeyAsync: async (provider: string) => {
     if (provider === "brave") return mockBraveSecureKey;
     if (provider === "perplexity") return mockPerplexitySecureKey;
+    if (provider === "tavily") return mockTavilySecureKey;
     return undefined;
   },
 }));
@@ -52,6 +54,7 @@ describe("web_search tool", () => {
     mockWebSearchProvider = "perplexity";
     mockBraveSecureKey = undefined;
     mockPerplexitySecureKey = undefined;
+    mockTavilySecureKey = undefined;
   });
 
   afterEach(() => {
@@ -347,6 +350,125 @@ describe("web_search tool", () => {
     expect(callCount).toBe(4);
   });
 
+  // ---- Tavily provider ----------------------------------------------------
+
+  test("executes Tavily search successfully", async () => {
+    mockWebSearchProvider = "tavily";
+    mockTavilySecureKey = "tvly-test-key";
+    globalThis.fetch = (async () => {
+      return new Response(
+        JSON.stringify({
+          results: [
+            {
+              title: "Tavily Result 1",
+              url: "https://example.com/tavily-1",
+              content: "First Tavily result",
+              score: 0.91,
+            },
+            {
+              title: "Tavily Result 2",
+              url: "https://example.com/tavily-2",
+              content: "Second Tavily result",
+            },
+          ],
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    }) as any;
+
+    const result = await execute({ query: "what is TypeScript" });
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain("Tavily Result 1");
+    expect(result.content).toContain("https://example.com/tavily-1");
+    expect(result.content).toContain("Score: 0.910");
+  });
+
+  test("Tavily sends correct request format", async () => {
+    mockWebSearchProvider = "tavily";
+    mockTavilySecureKey = "tvly-test-key";
+    let capturedUrl = "";
+    let capturedBody: any = null;
+    let capturedHeaders: any = null;
+    globalThis.fetch = (async (url: string, init?: RequestInit) => {
+      capturedUrl = url;
+      capturedBody = JSON.parse(init?.body as string);
+      capturedHeaders = new Headers(init?.headers);
+      return new Response(JSON.stringify({ results: [] }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    }) as any;
+
+    await execute({ query: "test query", count: 50, freshness: "pm" });
+    expect(capturedUrl).toContain("api.tavily.com/search");
+    expect(capturedBody.query).toBe("test query");
+    expect(capturedBody.search_depth).toBe("advanced");
+    expect(capturedBody.max_results).toBe(20);
+    expect(capturedBody.time_range).toBe("month");
+    expect(capturedHeaders.get("authorization")).toBe("Bearer tvly-test-key");
+  });
+
+  test("Tavily skips invalid freshness values", async () => {
+    mockWebSearchProvider = "tavily";
+    mockTavilySecureKey = "tvly-key";
+    let capturedBody: any = null;
+    globalThis.fetch = (async (_url: string, init?: RequestInit) => {
+      capturedBody = JSON.parse(init?.body as string);
+      return new Response(JSON.stringify({ results: [] }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    }) as any;
+
+    await execute({ query: "test", freshness: "invalid" });
+    expect(capturedBody.time_range).toBeUndefined();
+  });
+
+  test("Tavily returns no results message when response is empty", async () => {
+    mockWebSearchProvider = "tavily";
+    mockTavilySecureKey = "tvly-key";
+    globalThis.fetch = (async () => {
+      return new Response(JSON.stringify({ results: [] }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    }) as any;
+
+    const result = await execute({ query: "obscure query" });
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain("No results found");
+  });
+
+  test.each([401, 403])("Tavily handles %d auth error", async (status) => {
+    mockWebSearchProvider = "tavily";
+    mockTavilySecureKey = "bad-key";
+    globalThis.fetch = (async () => {
+      return new Response("Auth error", { status });
+    }) as any;
+
+    const result = await execute({ query: "test" });
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("Invalid or expired Tavily API key");
+  });
+
+  test("Tavily handles 429 rate limit after max retries", async () => {
+    mockWebSearchProvider = "tavily";
+    mockTavilySecureKey = "tvly-key";
+    let callCount = 0;
+    globalThis.fetch = (async () => {
+      callCount++;
+      return new Response("Too Many Requests", {
+        status: 429,
+        headers: { "retry-after": "0" },
+      });
+    }) as any;
+
+    const result = await execute({ query: "test" });
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("rate limit exceeded");
+    expect(callCount).toBe(4);
+  });
+
   // ---- Provider fallback --------------------------------------------------
 
   test("falls back from perplexity to brave when perplexity has no key", async () => {
@@ -385,6 +507,40 @@ describe("web_search tool", () => {
     expect(capturedUrl).toContain("perplexity");
   });
 
+  test("falls back to tavily when earlier providers have no key", async () => {
+    mockWebSearchProvider = "perplexity";
+    mockTavilySecureKey = "tvly-fallback-key";
+    let capturedUrl = "";
+    globalThis.fetch = (async (url: string) => {
+      capturedUrl = url;
+      return new Response(JSON.stringify({ results: [] }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    }) as any;
+
+    const result = await execute({ query: "fallback test" });
+    expect(result.isError).toBe(false);
+    expect(capturedUrl).toContain("tavily");
+  });
+
+  test("falls back from tavily to perplexity when tavily has no key", async () => {
+    mockWebSearchProvider = "tavily";
+    mockPerplexitySecureKey = "pplx-fallback-key";
+    let capturedUrl = "";
+    globalThis.fetch = (async (url: string) => {
+      capturedUrl = url;
+      return new Response(
+        JSON.stringify({ choices: [{ message: { content: "fallback" } }] }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    }) as any;
+
+    const result = await execute({ query: "fallback test" });
+    expect(result.isError).toBe(false);
+    expect(capturedUrl).toContain("perplexity");
+  });
+
   test("maps inference-provider-native to perplexity", async () => {
     mockWebSearchProvider = "inference-provider-native";
     mockPerplexitySecureKey = "pplx-key";