@vellumai/assistant 0.6.4 → 0.6.5

package/src/stt/daemon-batch-transcriber.ts

@@ -10,6 +10,7 @@
  * - OpenAI Whisper (`openai-whisper`)
  * - Deepgram (`deepgram`)
  * - Google Gemini (`google-gemini`)
+ * - xAI (`xai`)
  */
 
 import type {
@@ -120,6 +121,36 @@ class GoogleGeminiBatchTranscriber implements BatchTranscriber {
   }
 }
 
+// ---------------------------------------------------------------------------
+// xAI adapter — implements BatchTranscriber on top of the xAI audio
+// transcription provider.
+// ---------------------------------------------------------------------------
+
+/**
+ * Wraps `XAIProvider` behind the `BatchTranscriber` contract.
+ *
+ * Same error-propagation semantics as WhisperBatchTranscriber: raw provider
+ * errors pass through unchanged.
+ */
+class XAIBatchTranscriber implements BatchTranscriber {
+  readonly providerId = "xai" as const;
+  readonly boundaryId = "daemon-batch" as const;
+
+  private readonly apiKey: string;
+
+  constructor(apiKey: string) {
+    this.apiKey = apiKey;
+  }
+
+  async transcribe(
+    request: SttTranscribeRequest,
+  ): Promise<SttTranscribeResult> {
+    const { XAIProvider } = await import("../providers/speech-to-text/xai.js");
+    const provider = new XAIProvider(this.apiKey);
+    return provider.transcribe(request.audio, request.mimeType, request.signal);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Error normalization
 // ---------------------------------------------------------------------------
@@ -185,6 +216,8 @@ export function createDaemonBatchTranscriber(
       return new DeepgramBatchTranscriber(apiKey);
     case "google-gemini":
       return new GoogleGeminiBatchTranscriber(apiKey);
+    case "xai":
+      return new XAIBatchTranscriber(apiKey);
     default: {
       // Exhaustive check — compile error if a new SttProviderId is added
       // without a corresponding case here.

package/src/stt/stt-stream-session.ts

@@ -30,6 +30,10 @@
  *   configurable window.
  */
 
+import {
+  listProviderIds,
+  supportsBoundary,
+} from "../providers/speech-to-text/provider-catalog.js";
 import { getLogger } from "../util/logger.js";
 import type { StreamingTranscriber, SttStreamServerEvent } from "./types.js";
 
@@ -172,10 +176,13 @@ export class SttStreamSession {
           { provider: this.provider },
           "Streaming transcriber unavailable for provider",
         );
+        const streamingProviders = listProviderIds()
+          .filter((id) => supportsBoundary(id, "daemon-streaming"))
+          .join(", ");
         this.sendEvent({
           type: "error",
           category: "provider-error",
-          message: `Streaming transcription is not supported for provider "${this.provider}". Supported providers: deepgram, google-gemini, openai-whisper.`,
+          message: `Streaming transcription is not supported for provider "${this.provider}". Supported providers: ${streamingProviders}.`,
         });
         this.sendEvent({ type: "closed" });
         this.state = "closed";

package/src/stt/types.ts

@@ -20,7 +20,11 @@
  * Canonical provider identifiers for daemon-hosted STT backends.
  * Extend this union as new providers are integrated.
  */
-export type SttProviderId = "openai-whisper" | "deepgram" | "google-gemini";
+export type SttProviderId =
+  | "openai-whisper"
+  | "deepgram"
+  | "google-gemini"
+  | "xai";
 
 /**
  * Telephony-specific STT capability class.

package/src/subagent/manager.ts

@@ -17,6 +17,7 @@ import {
 } from "../daemon/conversation.js";
 import type { ServerMessage } from "../daemon/message-protocol.js";
 import { bootstrapConversation } from "../memory/conversation-bootstrap.js";
+import { CallSiteRoutingProvider } from "../providers/call-site-routing.js";
 import { RateLimitProvider } from "../providers/ratelimit.js";
 import { getProvider } from "../providers/registry.js";
 import { createAbortReason } from "../util/abort-reasons.js";
@@ -155,7 +156,9 @@ export class SubagentManager {
    * `onSubagentFinished`.  Used by fork spawn to resolve the parent's
    * system prompt when `config.parentSystemPrompt` is not provided.
    */
-  resolveParentConversation?: (conversationId: string) => Conversation | undefined;
+  resolveParentConversation?: (
+    conversationId: string,
+  ) => Conversation | undefined;
 
   // ── Spawn ───────────────────────────────────────────────────────────
 
@@ -211,7 +214,19 @@ export class SubagentManager {
 
     // ── Build conversation dependencies ─────────────────────────────
     const appConfig = getConfig();
-    let provider = getProvider(appConfig.services.inference.provider);
+    let provider = getProvider(appConfig.llm.default.provider);
+    // Per-call `options.config.callSite` (e.g. `subagentSpawn`) can resolve
+    // to a provider name that differs from `llm.default.provider`. Wrap the
+    // default provider so the actual transport routes correctly per call,
+    // rather than only forwarding metadata to the default's HTTP client.
+    // See `providers/call-site-routing.ts`.
+    provider = new CallSiteRoutingProvider(provider, (name) => {
+      try {
+        return getProvider(name);
+      } catch {
+        return undefined;
+      }
+    });
     const { rateLimit } = appConfig;
     if (rateLimit.maxRequestsPerMinute > 0) {
       provider = new RateLimitProvider(
@@ -227,19 +242,21 @@ export class SubagentManager {
       if (config.parentSystemPrompt) {
         systemPrompt = config.parentSystemPrompt;
       } else if (this.resolveParentConversation) {
-        const parentConv = this.resolveParentConversation(config.parentConversationId);
+        const parentConv = this.resolveParentConversation(
+          config.parentConversationId,
+        );
         const resolved = parentConv?.getCurrentSystemPrompt();
         if (!resolved) {
           throw new Error(
             "Fork spawn requires a parent system prompt but neither config.parentSystemPrompt " +
-            "nor resolveParentConversation yielded one.",
+              "nor resolveParentConversation yielded one.",
           );
         }
         systemPrompt = resolved;
       } else {
         throw new Error(
           "Fork spawn requires a parent system prompt but neither config.parentSystemPrompt " +
-          "is set nor resolveParentConversation callback is wired.",
+            "is set nor resolveParentConversation callback is wired.",
         );
       }
     } else {
@@ -247,7 +264,7 @@ export class SubagentManager {
         config.systemPromptOverride ??
         buildSubagentSystemPrompt({ ...config, id: subagentId }, role);
     }
-    const maxTokens = appConfig.maxTokens;
+    const maxTokens = appConfig.llm.default.maxTokens;
     const workingDir = getSandboxWorkingDir();
 
     const memoryPolicy: ConversationMemoryPolicy = isFork
@@ -266,10 +283,16 @@ export class SubagentManager {
     const now = Date.now();
     // For forks, default sendResultToUser to false (silent) unless explicitly true.
     const resolvedSendResultToUser = isFork
-      ? (config.sendResultToUser === true ? true : false)
+      ? config.sendResultToUser === true
+        ? true
+        : false
       : config.sendResultToUser;
     const state: SubagentState = {
-      config: { ...config, id: subagentId, sendResultToUser: resolvedSendResultToUser },
+      config: {
+        ...config,
+        id: subagentId,
+        sendResultToUser: resolvedSendResultToUser,
+      },
       status: "pending",
       conversationId: conversationRecord.id,
       isFork,
@@ -413,7 +436,9 @@ export class SubagentManager {
       // This prepends the inherited context so the fork has full conversational
       // awareness while the objective becomes the latest user turn.
       if (managed.state.isFork && managed.state.config.parentMessages) {
-        conversation.injectInheritedContext(managed.state.config.parentMessages);
+        conversation.injectInheritedContext(
+          managed.state.config.parentMessages,
+        );
         // Release the parent message arrays now that they've been injected — holding
         // them in SubagentState.config would retain significant memory until the TTL
         // sweep disposes this entry (up to 30 minutes for terminal subagents).
@@ -439,7 +464,9 @@ export class SubagentManager {
           ].join("\n")
         : objective;
       const messageId = await conversation.persistUserMessage(message, []);
-      await conversation.runAgentLoop(message, messageId, onEvent);
+      await conversation.runAgentLoop(message, messageId, onEvent, {
+        callSite: "subagentSpawn",
+      });
 
       // Agent loop completed successfully.
       // Copy usage stats from the conversation before sending status (which includes usage).
@@ -634,7 +661,9 @@ export class SubagentManager {
       const conversation = managed.conversation;
       const messageId = await conversation.persistUserMessage(trimmed, []);
       conversation
-        .runAgentLoop(trimmed, messageId, onEvent)
+        .runAgentLoop(trimmed, messageId, onEvent, {
+          callSite: "subagentSpawn",
+        })
         .catch((err) => {
           log.error({ subagentId, err }, "Subagent message processing failed");
         });
@@ -900,8 +929,7 @@ export class SubagentManager {
     const prefix = managed.state.isFork ? "Fork" : "Subagent";
     let notificationString = `[${prefix} "${info.label}" — ${urgency}] ${message}`;
     if (urgency === "blocked") {
-      notificationString +=
-        `\nUse subagent_message to send guidance to this ${prefix.toLowerCase()}.`;
+      notificationString += `\nUse subagent_message to send guidance to this ${prefix.toLowerCase()}.`;
     }
 
     try {

package/src/tasks/ephemeral-permissions.ts

@@ -1,5 +1,10 @@
+import { SCOPED_TOOLS } from "@vellumai/ces-contracts";
+
 import type { TrustRule } from "../permissions/types.js";
 
+/** O(1) lookup set for scoped tool names. */
+const SCOPED_TOOLS_SET: ReadonlySet<string> = new Set(SCOPED_TOOLS);
+
 // In-memory map: task_run_id -> ephemeral rules
 const activeTaskRules = new Map<string, TrustRule[]>();
 
@@ -29,9 +34,8 @@ export function clearTaskRunRules(taskRunId: string): void {
  * default rules (50) so pre-approved tools aren't shadowed by default
  * `ask` rules (which would trigger prompting and auto-deny in
  * non-interactive task runs), but below user rules (100) so user deny
- * rules still take precedence. `allowHighRisk` is intentionally omitted:
- * high-risk tool invocations still flow through the normal risk-classification
- * path rather than being blanket-approved.
+ * rules still take precedence. High-risk tool invocations still flow through
+ * the normal risk-classification path rather than being blanket-approved.
  */
 export function buildTaskRules(
   taskRunId: string,
@@ -42,7 +46,8 @@ export function buildTaskRules(
     id: `ephemeral:${taskRunId}:${tool}`,
     tool,
     pattern: "**",
-    scope: "everywhere",
+    // Only include scope for scoped tools — non-scoped tools don't carry scope.
+    ...(SCOPED_TOOLS_SET.has(tool) ? { scope: "everywhere" } : {}),
     decision: "allow" as const,
     priority: 75,
     createdAt: Date.now(),

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

@@ -45,6 +45,7 @@ const CHECKPOINT_KEY_LIFECYCLE_WATERMARK =
 const CHECKPOINT_KEY_LIFECYCLE_WATERMARK_ID =
   "telemetry:lifecycle: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;
 const MAX_CONSECUTIVE_BATCHES = 10;
 const TELEMETRY_PATH = "/v1/telemetry/ingest/";
@@ -54,13 +55,21 @@ const TELEMETRY_PATH = "/v1/telemetry/ingest/";
 // ---------------------------------------------------------------------------
 
 export class UsageTelemetryReporter {
+  private initialFlushTimer: ReturnType<typeof setTimeout> | null = null;
   private timer: ReturnType<typeof setInterval> | null = null;
   private activeFlush: Promise<void> | null = null;
 
   start(): void {
-    this.flush().catch((err) => {
-      log.warn({ err }, "Initial usage telemetry flush failed");
-    });
+    // Delay the first flush to allow the credential infrastructure (CES
+    // handshake) to complete. Without this delay, VellumPlatformClient.create()
+    // returns null because the credential backend hasn't resolved yet, causing
+    // telemetry to fall back to anonymous mode permanently.
+    this.initialFlushTimer = setTimeout(() => {
+      this.initialFlushTimer = null;
+      this.flush().catch((err) => {
+        log.warn({ err }, "Initial usage telemetry flush failed");
+      });
+    }, INITIAL_FLUSH_DELAY_MS);
     this.timer = setInterval(() => {
       this.flush().catch((err) => {
         log.warn({ err }, "Scheduled usage telemetry flush failed");
@@ -69,6 +78,10 @@ export class UsageTelemetryReporter {
   }
 
   async stop(): Promise<void> {
+    if (this.initialFlushTimer) {
+      clearTimeout(this.initialFlushTimer);
+      this.initialFlushTimer = null;
+    }
     if (this.timer) {
       clearInterval(this.timer);
       this.timer = null;
@@ -157,6 +170,15 @@ export class UsageTelemetryReporter {
       // Resolve auth context — authenticated path uses client, anonymous path
       // sends unauthenticated (telemetry endpoints are public).
       const client = await VellumPlatformClient.create();
+      log.debug(
+        {
+          authenticated: !!client,
+          usageCount: events.length,
+          turnCount: turnEvents.length,
+          lifecycleCount: lifecycleEvents.length,
+        },
+        "Telemetry flush: resolved auth context",
+      );
 
       // Build payload
       const typedEvents: TelemetryEvent[] = [
@@ -222,9 +244,9 @@ export class UsageTelemetryReporter {
       }
 
       if (!resp.ok) {
-        await resp.text(); // consume body to release connection
+        const body = await resp.text();
         log.warn(
-          { status: resp.status },
+          { status: resp.status, authenticated: !!client, body },
           "Usage telemetry POST failed — will retry next cycle",
         );
         return;

package/src/tools/browser/__tests__/browser-status.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, mock, test } from "bun:test";
+import { beforeEach, describe, expect, mock, test } from "bun:test";
 
 import type { ToolContext } from "../../types.js";
 import {
@@ -14,6 +14,11 @@ const probeOutcomes: Record<string, ProbeOutcome> = {
   [BROWSER_STATUS_MODE.CDP_INSPECT]: "ok",
   [BROWSER_STATUS_MODE.LOCAL]: "ok",
 };
+const probeErrors: Record<string, CdpError | null> = {
+  [BROWSER_STATUS_MODE.EXTENSION]: null,
+  [BROWSER_STATUS_MODE.CDP_INSPECT]: null,
+  [BROWSER_STATUS_MODE.LOCAL]: null,
+};
 
 const buildCandidateListMock = mock((_context: ToolContext) => [
   { kind: BROWSER_STATUS_MODE.EXTENSION, reason: "mock" },
@@ -30,7 +35,10 @@ const getCdpClientMock = mock(
       conversationId: "test-conversation",
       send: mock(async () => {
         if (outcome === "fail") {
-          throw new CdpError("transport_error", `${mode} probe failed`);
+          throw (
+            probeErrors[mode] ??
+            new CdpError("transport_error", `${mode} probe failed`)
+          );
         }
         return { result: { value: "complete" } };
       }),
@@ -86,6 +94,15 @@ function makeContext(overrides: Partial<ToolContext> = {}): ToolContext {
 }
 
 describe("executeBrowserStatus", () => {
+  beforeEach(() => {
+    probeOutcomes[BROWSER_STATUS_MODE.EXTENSION] = "ok";
+    probeOutcomes[BROWSER_STATUS_MODE.CDP_INSPECT] = "ok";
+    probeOutcomes[BROWSER_STATUS_MODE.LOCAL] = "ok";
+    probeErrors[BROWSER_STATUS_MODE.EXTENSION] = null;
+    probeErrors[BROWSER_STATUS_MODE.CDP_INSPECT] = null;
+    probeErrors[BROWSER_STATUS_MODE.LOCAL] = null;
+  });
+
   test("reports extension preflight-unavailable when no host browser proxy is bound", async () => {
     const result = await executeBrowserStatus({}, makeContext());
     expect(result.isError).toBe(false);
@@ -120,4 +137,30 @@ describe("executeBrowserStatus", () => {
       `${BROWSER_STATUS_INPUT_FIELD.CHECK_LOCAL_LAUNCH} must be a boolean`,
     );
   });
+
+  test("reports extension as connected when probe fails on restricted chrome:// page", async () => {
+    probeOutcomes[BROWSER_STATUS_MODE.EXTENSION] = "fail";
+    probeErrors[BROWSER_STATUS_MODE.EXTENSION] = new CdpError(
+      "cdp_error",
+      "Cannot access a chrome:// URL",
+    );
+
+    const result = await executeBrowserStatus(
+      {},
+      makeContext({
+        hostBrowserProxy: {
+          isAvailable: () => true,
+        } as ToolContext["hostBrowserProxy"],
+      }),
+    );
+    expect(result.isError).toBe(false);
+    const payload = JSON.parse(result.content);
+    const extension = payload.modes.find(
+      (m: { mode: string }) => m.mode === BROWSER_STATUS_MODE.EXTENSION,
+    );
+    expect(extension).toBeDefined();
+    expect(extension.available).toBe(true);
+    expect(extension.verified).toBe("active_probe");
+    expect(extension.details.restrictedActiveTab).toBe(true);
+  });
 });

package/src/tools/browser/browser-execution.ts

@@ -4,6 +4,7 @@ import { getLogger } from "../../util/logger.js";
 import { truncate } from "../../util/truncate.js";
 import { safeStringSlice } from "../../util/unicode.js";
 import { credentialBroker } from "../credentials/broker.js";
+import { BROWSER_FILL_CAPABILITY } from "../credentials/tool-policy.js";
 import {
   isPrivateOrLocalHost,
   parseUrl,
@@ -86,19 +87,22 @@ type StatusCheckMode = BrowserStatusMode;
 
 const MODE_TRADEOFFS: Record<StatusCheckMode, string[]> = {
   [BROWSER_STATUS_MODE.EXTENSION]: [
-    "Controls the user's existing Chrome profile and tabs.",
+    "This is the preferred approach for all things browser-use.",
+    "It requires a one-time install of the Vellum Assistant Chrome Extension.",
+    "More secure than relying on Chrome's native remote debugging functionality.",
     "Requires the Vellum extension to be paired and actively connected.",
-    "Best when the user wants the assistant to operate in their real browser session.",
   ],
   [BROWSER_STATUS_MODE.CDP_INSPECT]: [
-    "Controls an existing Chrome instance launched with --remote-debugging-port.",
-    "Does not require the extension to be connected.",
-    "Requires remote debugging to stay enabled on localhost, which is more manual to maintain.",
+    "This is the second-best approach for all things browser-use, after the native Vellum Assistant Chrome Extension.",
+    "It requires Chrome version 146 or greater",
+    "It requires toggling on remote debugging in Chrome Settings",
+    "It's prone to phishing attacks from other local processes that may try to do their own remote debugging.",
   ],
   [BROWSER_STATUS_MODE.LOCAL]: [
-    "Runs a dedicated Playwright-managed Chromium profile.",
-    "Most isolated and reliable fallback when extension/CDP inspect are unavailable.",
+    "The least-preferred approach for all things browser-use.",
+    "Considered a last-resort fallback if the user has not installed the Chrome Extension or enabled remote debugging in Chrome, and has indicated that they do not want to.",
     "Does not use the user's existing browser profile, so sessions/cookies may differ.",
+    "Requires that Playwright and Chromium are installed on the host machine,",
   ],
 };
 
@@ -192,9 +196,9 @@ const REMEDIATION_HINTS: Record<string, string[]> = {
   ],
   // cdp-inspect backend — discovery-level failures
   "cdp-inspect:unreachable": [
-    "Ensure Chrome/Chromium is running with --remote-debugging-port=9222.",
+    "Ensure that Chrome is on version 146 or higher by going to chrome://settings/help.",
+    'Ensure that you have toggled on "Allow remote debugging for this browser instance" by going to chrome://inspect/#remote-debugging',
     "Verify no firewall or antivirus is blocking localhost:9222.",
-    "Try: /Applications/Google\\ Chrome.app/Contents/MacOS/Google\\ Chrome --remote-debugging-port=9222",
   ],
   "cdp-inspect:non_chrome": [
     "The process listening on the configured port is not Chrome/Chromium.",
@@ -322,6 +326,14 @@ function collectRemediationHints(
   return hints;
 }
 
+/**
+ * Detect the common extension CDP failure where the active tab is a
+ * restricted Chrome internal page (e.g. `chrome://newtab`).
+ */
+function isRestrictedChromePageProbeError(error: CdpError): boolean {
+  return error.message.toLowerCase().includes("chrome://");
+}
+
 /**
  * Parse browser_mode from input and acquire a CdpClient. Returns
  * either a `{ cdp, browserMode }` pair on success or a pre-formatted
@@ -530,7 +542,7 @@ export function resolveElement(
     }
     return {
       resolved: null,
-      error: `Error: element_id "${elementId}" not found. Run browser_snapshot first to get current element IDs.`,
+      error: `Error: element_id "${elementId}" not found. Run a snapshot first to get current element IDs.`,
     };
   }
 
@@ -740,8 +752,8 @@ export async function executeBrowserNavigate(
           ).blockedAddress)
       ) {
         // Navigate the page away from the private target to prevent
-        // follow-up tool calls (e.g. browser_snapshot) from reading
-        // the already-loaded private content.
+        // follow-up operations (e.g. snapshot) from reading the
+        // already-loaded private content.
         try {
           await navigateAndWait(
             cdp,
@@ -847,7 +859,7 @@ export async function executeBrowserNavigate(
 
     if (navigationTimedOut) {
       lines.push(
-        `Note: Page is still loading (document.readyState timed out). The page should still be interactive - use browser_snapshot to check.`,
+        `Note: Page is still loading (document.readyState timed out). The page should still be interactive - take a snapshot to check.`,
       );
     }
 
@@ -917,14 +929,12 @@ export async function executeBrowserNavigate(
               lines.push("");
               lines.push(formatAuthChallenge(postCaptchaAuth));
               lines.push("");
+              lines.push("Handle this by interacting with the login form:");
               lines.push(
-                "Handle this by using browser tools to interact with the login form:",
-              );
-              lines.push(
-                "1. Use browser_snapshot to find the sign-in form elements",
+                "1. Take a snapshot to find the sign-in form elements",
               );
               lines.push(
-                "2. Use browser_fill_credential to fill email/password from credential_store",
+                "2. Use credential fill to enter email/password from credential_store",
               );
               lines.push(
                 "3. For email verification codes, use ui_show with a form to ask the user for the code mid-turn",
@@ -944,18 +954,14 @@ export async function executeBrowserNavigate(
           }
         } else {
           // Login / 2FA / OAuth - the agent should handle these itself
-          // using browser tools + credential_store. Don't hand off.
+          // using browser operations + credential_store. Don't hand off.
           lines.push("");
           lines.push(formatAuthChallenge(challenge));
           lines.push("");
+          lines.push("Handle this by interacting with the login form:");
+          lines.push("1. Take a snapshot to find the sign-in form elements");
           lines.push(
-            "Handle this by using browser tools to interact with the login form:",
-          );
-          lines.push(
-            "1. Use browser_snapshot to find the sign-in form elements",
-          );
-          lines.push(
-            "2. Use browser_fill_credential to fill email/password from credential_store",
+            "2. Use credential fill to enter email/password from credential_store",
           );
           lines.push(
             "3. For email verification codes, use ui_show with a form to ask the user for the code mid-turn",
@@ -1006,7 +1012,7 @@ export async function executeBrowserNavigate(
   }
 }
 
-// ── browser_snapshot ─────────────────────────────────────────────────
+// ── snapshot ─────────────────────────────────────────────────────────
 
 export async function executeBrowserSnapshot(
   _input: Record<string, unknown>,
@@ -1938,7 +1944,7 @@ export async function executeBrowserExtract(
   }
 }
 
-// ── browser_fill_credential ──────────────────────────────────────────
+// ── browser credential fill ──────────────────────────────────────────
 
 export async function executeBrowserFillCredential(
   input: Record<string, unknown>,
@@ -1996,7 +2002,7 @@ export async function executeBrowserFillCredential(
     const result = await credentialBroker.browserFill({
       service,
       field,
-      toolName: "browser_fill_credential",
+      toolName: BROWSER_FILL_CAPABILITY,
       domain: pageDomain,
       fill: async (value) => {
         // Clear-then-focus-then-insert via the shared helper. We
@@ -2087,24 +2093,22 @@ function modeTradeoffs(mode: StatusCheckMode): string[] {
 
 function extensionSetupActions(): string[] {
   return [
-    "Install and enable the Vellum Relay Chrome extension.",
-    "Open the extension popup and click Pair with local assistant.",
-    "Keep the extension connected to the assistant relay.",
+    "Install the Vellum Assistant Chrome extension from the Chrome Web Store: https://chromewebstore.google.com/detail/vellum-assistant-browser/hphbdmpffeigpcdjkckleobjmhhokpne",
+    "Open the extension and pair with your assistant.",
   ];
 }
 
 function cdpInspectSetupActions(): string[] {
   return [
-    "Launch Chrome with --remote-debugging-port=9222 (or your configured port).",
-    "Keep Chrome running while browser tools are in use.",
-    "Ensure the configured host is loopback (localhost / 127.0.0.1 / ::1).",
+    "Update Chrome to the latest version by going to chrome://settings/help",
+    "Navigate directly to chrome://inspect/#remote-debugging",
+    'Check the box next to "Allow remote debugging for this browser instance"',
   ];
 }
 
 function localSetupActions(): string[] {
   return [
-    "Install assistant dependencies with bun install in assistant/.",
-    "Install Chromium for Playwright: bunx playwright install chromium.",
+    "Ask your assistant to install playwright and chromium on your host machine.",
   ];
 }
 
@@ -2299,6 +2303,29 @@ async function checkExtensionModeStatus(
     };
   }
 
+  if (isRestrictedChromePageProbeError(probe.error)) {
+    return {
+      mode: BROWSER_STATUS_MODE.EXTENSION,
+      available: true,
+      verified: "active_probe",
+      autoCandidate,
+      summary:
+        "Extension mode transport is connected, but the active Chrome tab is a restricted chrome:// page. Switch to a regular website tab if browser actions fail.",
+      userActions: [
+        "Switch Chrome to a regular http(s) tab (not chrome://...) and retry.",
+      ],
+      tradeoffs: modeTradeoffs(BROWSER_STATUS_MODE.EXTENSION),
+      details: {
+        proxyBound,
+        proxyConnected,
+        restrictedActiveTab: true,
+        errorCode: probe.error.code,
+        diagnostic: probe.diagnostic,
+        attemptDiagnostics: probe.error.attemptDiagnostics ?? [],
+      },
+    };
+  }
+
   return {
     mode: BROWSER_STATUS_MODE.EXTENSION,
     available: false,
@@ -2547,7 +2574,7 @@ export async function executeBrowserStatus(
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     return {
-      content: `Error: browser_status failed: ${msg}`,
+      content: `Error: browser status check failed: ${msg}`,
       isError: true,
     };
   }