@vellumai/assistant 0.6.4 → 0.6.6

package/src/providers/speech-to-text/xai.test.ts

@@ -0,0 +1,155 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { XAIProvider } from "./xai.js";
+
+const TEST_API_KEY = "xai-test-key-for-unit-tests";
+
+describe("XAIProvider", () => {
+  let originalFetch: typeof globalThis.fetch;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  test("successful transcription returns trimmed text", async () => {
+    globalThis.fetch = (async (
+      _url: string | URL | Request,
+      _init?: RequestInit,
+    ) => {
+      return new Response(JSON.stringify({ text: "  hello  " }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }) as typeof fetch;
+
+    const provider = new XAIProvider(TEST_API_KEY);
+    const result = await provider.transcribe(
+      Buffer.from("fake-audio"),
+      "audio/ogg",
+    );
+
+    expect(result).toEqual({ text: "hello" });
+  });
+
+  test("API error throws with status and partial body", async () => {
+    const errorBody = JSON.stringify({
+      error: {
+        message: "Invalid API key provided",
+        type: "invalid_request_error",
+      },
+    });
+
+    globalThis.fetch = (async (
+      _url: string | URL | Request,
+      _init?: RequestInit,
+    ) => {
+      return new Response(errorBody, {
+        status: 401,
+        headers: { "Content-Type": "application/json" },
+      });
+    }) as typeof fetch;
+
+    const provider = new XAIProvider(TEST_API_KEY);
+
+    await expect(
+      provider.transcribe(Buffer.from("fake-audio"), "audio/wav"),
+    ).rejects.toThrow("xAI STT error (401)");
+  });
+
+  test("sends correct FormData structure (no model field, file blob with correct MIME)", async () => {
+    let capturedBody: FormData | undefined;
+    let capturedHeaders: HeadersInit | undefined;
+
+    globalThis.fetch = (async (
+      url: string | URL | Request,
+      init?: RequestInit,
+    ) => {
+      capturedBody = init?.body as FormData;
+      capturedHeaders = init?.headers;
+      expect(url).toBe("https://api.x.ai/v1/stt");
+      expect(init?.method).toBe("POST");
+
+      return new Response(JSON.stringify({ text: "transcribed" }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }) as typeof fetch;
+
+    const provider = new XAIProvider(TEST_API_KEY);
+    await provider.transcribe(Buffer.from("fake-audio"), "audio/mpeg");
+
+    // Verify authorization header
+    expect(capturedHeaders).toEqual({
+      Authorization: `Bearer ${TEST_API_KEY}`,
+    });
+
+    // Verify FormData contents
+    expect(capturedBody).toBeInstanceOf(FormData);
+
+    // xAI does not use a `model` field.
+    expect(capturedBody!.get("model")).toBeNull();
+
+    const file = capturedBody!.get("file");
+    expect(file).toBeInstanceOf(Blob);
+    expect((file as Blob).type).toBe("audio/mpeg");
+  });
+
+  test("returns empty text when API returns empty text field", async () => {
+    globalThis.fetch = (async () => {
+      return new Response(JSON.stringify({ text: "" }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }) as unknown as typeof fetch;
+
+    const provider = new XAIProvider(TEST_API_KEY);
+    const result = await provider.transcribe(
+      Buffer.from("silence"),
+      "audio/wav",
+    );
+
+    expect(result).toEqual({ text: "" });
+  });
+
+  test("returns empty text when API response has no text property", async () => {
+    globalThis.fetch = (async () => {
+      return new Response(JSON.stringify({}), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }) as unknown as typeof fetch;
+
+    const provider = new XAIProvider(TEST_API_KEY);
+    const result = await provider.transcribe(
+      Buffer.from("silence"),
+      "audio/wav",
+    );
+
+    expect(result).toEqual({ text: "" });
+  });
+
+  test("error body is truncated to 300 characters", async () => {
+    const longBody = "x".repeat(500);
+
+    globalThis.fetch = (async () => {
+      return new Response(longBody, { status: 500 });
+    }) as unknown as typeof fetch;
+
+    const provider = new XAIProvider(TEST_API_KEY);
+
+    try {
+      await provider.transcribe(Buffer.from("audio"), "audio/wav");
+      expect.unreachable("should have thrown");
+    } catch (err) {
+      const msg = (err as Error).message;
+      expect(msg).toContain("xAI STT error (500)");
+      // The body portion should be at most 300 chars
+      const bodyPart = msg.replace("xAI STT error (500): ", "");
+      expect(bodyPart.length).toBeLessThanOrEqual(300);
+    }
+  });
+});

package/src/providers/speech-to-text/xai.ts

@@ -0,0 +1,97 @@
+import type { SttTranscribeResult } from "../../stt/types.js";
+
+export const XAI_STT_URL = "https://api.x.ai/v1/stt";
+export const DEFAULT_TIMEOUT_MS = 60_000;
+
+/**
+ * Derive a filename extension from a MIME type so the xAI STT API can detect
+ * the audio format. Falls back to "audio" when the MIME type is unrecognised.
+ */
+export function extensionFromMime(mimeType: string): string {
+  const map: Record<string, string> = {
+    "audio/wav": "wav",
+    "audio/x-wav": "wav",
+    "audio/mpeg": "mp3",
+    "audio/mp3": "mp3",
+    "audio/ogg": "ogg",
+    "audio/opus": "opus",
+    "audio/webm": "webm",
+    "audio/mp4": "m4a",
+    "audio/x-m4a": "m4a",
+    "audio/flac": "flac",
+  };
+  const base = mimeType.split(";")[0].trim().toLowerCase();
+  return map[base] ?? "audio";
+}
+
+/**
+ * Build a FormData payload for the xAI `/v1/stt` endpoint.
+ *
+ * xAI does not require a `model` field. The xAI docs explicitly require the
+ * `file` field to be appended LAST in the multipart body, so we only append
+ * the file here (no other fields in v1).
+ */
+export function buildXaiFormData(audio: Buffer, mimeType: string): FormData {
+  const ext = extensionFromMime(mimeType);
+
+  const formData = new FormData();
+  // xAI requires the `file` field to be LAST in the multipart body.
+  formData.append(
+    "file",
+    new Blob([new Uint8Array(audio)], { type: mimeType }),
+    `audio.${ext}`,
+  );
+
+  return formData;
+}
+
+/**
+ * Send audio to the xAI STT API and return the transcribed text.
+ *
+ * xAI returns a richer shape (`{ text, language, duration, words }`) — we only
+ * consume `text`.
+ */
+export async function xaiTranscribe(
+  apiKey: string,
+  audio: Buffer,
+  mimeType: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  const formData = buildXaiFormData(audio, mimeType);
+
+  const effectiveSignal = signal ?? AbortSignal.timeout(DEFAULT_TIMEOUT_MS);
+
+  const response = await fetch(XAI_STT_URL, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${apiKey}` },
+    body: formData,
+    signal: effectiveSignal,
+  });
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new Error(
+      `xAI STT error (${response.status}): ${body.slice(0, 300)}`,
+    );
+  }
+
+  const result = (await response.json()) as { text?: string };
+  return result.text?.trim() ?? "";
+}
+
+export class XAIProvider {
+  private readonly apiKey: string;
+
+  constructor(apiKey: string) {
+    this.apiKey = apiKey;
+  }
+
+  async transcribe(
+    audio: Buffer,
+    mimeType: string,
+    signal?: AbortSignal,
+  ): Promise<SttTranscribeResult> {
+    const text = await xaiTranscribe(this.apiKey, audio, mimeType, signal);
+    return { text };
+  }
+}

package/src/providers/types.ts

@@ -1,3 +1,6 @@
+import type { LLMCallSite } from "../config/schemas/llm.js";
+import { ProviderError } from "../util/errors.js";
+
 export interface TextContent {
   type: "text";
   text: string;
@@ -126,12 +129,23 @@ export type ProviderEvent =
       toolUseId: string;
       input: Record<string, unknown>;
     }
-  | { type: "server_tool_complete"; toolUseId: string; isError: boolean; content?: unknown[] };
+  | {
+      type: "server_tool_complete";
+      toolUseId: string;
+      isError: boolean;
+      content?: unknown[];
+    };
 
 export interface SendMessageConfig {
   model?: string;
-  modelIntent?: ModelIntent;
-  effort?: "low" | "medium" | "high" | "max";
+  /**
+   * LLM call-site identifier. `RetryProvider` resolves
+   * provider/model/maxTokens/effort/speed/temperature/thinking/contextWindow
+   * via `resolveCallSiteConfig(callSite, config.llm)`, falling back to
+   * `llm.default` when no callSite-specific entry is present.
+   */
+  callSite?: LLMCallSite;
+  effort?: "low" | "medium" | "high" | "xhigh" | "max";
   speed?: "standard" | "fast";
   [key: string]: unknown;
 }
@@ -160,3 +174,79 @@ export interface Provider {
     options?: SendMessageOptions,
   ): Promise<ProviderResponse>;
 }
+
+// ── Context-overflow error ────────────────────────────────────────────
+
+export interface ContextOverflowErrorOptions {
+  /** Actual tokens the request was estimated/measured to consume, when the provider reports it. */
+  actualTokens?: number;
+  /** Context-window cap the provider enforced, when reported in the error body. */
+  maxTokens?: number;
+  /** HTTP status reported by the provider. Defaults to 400. */
+  statusCode?: number;
+  /** Underlying error to preserve the cause chain (standard Error.cause). */
+  cause?: unknown;
+}
+
+/**
+ * Thrown by provider clients when the request exceeded the model's context
+ * window (HTTP 400 `context_length_exceeded`, Anthropic's `prompt_too_long`,
+ * Gemini's resource-exhausted category, etc.).
+ *
+ * Extends `ProviderError` so existing `instanceof ProviderError` classifiers
+ * (`util/retry.ts`, `daemon/conversation-error.ts`) continue to see it as a
+ * typed 4xx provider error and apply the right policy. The
+ * `actualTokens`/`maxTokens` fields carry structured counts when the
+ * provider reports them, avoiding brittle regex parsing at the caller.
+ *
+ * A regex-on-message fallback still exists in
+ * `daemon/parse-actual-tokens-from-error.ts` as a safety net for adapters
+ * that rewrap the error (e.g. managed-proxy) before it reaches the agent
+ * loop.
+ */
+export class ContextOverflowError extends ProviderError {
+  public readonly actualTokens?: number;
+  public readonly maxTokens?: number;
+
+  constructor(
+    message: string,
+    provider: string,
+    options: ContextOverflowErrorOptions = {},
+  ) {
+    super(
+      message,
+      provider,
+      options.statusCode ?? 400,
+      options.cause !== undefined ? { cause: options.cause } : undefined,
+    );
+    this.name = "ContextOverflowError";
+    this.actualTokens = options.actualTokens;
+    this.maxTokens = options.maxTokens;
+  }
+}
+
+export function isContextOverflowError(
+  err: unknown,
+): err is ContextOverflowError {
+  return err instanceof ContextOverflowError;
+}
+
+/**
+ * Extract `actualTokens` / `maxTokens` from provider overflow messages of the
+ * form "N tokens > M maximum" or bare "N > M". Returns an empty object when
+ * neither count is parseable — callers should treat this as "matched the
+ * overflow signal but counts unknown".
+ */
+export function extractOverflowTokensFromMessage(message: string): {
+  actualTokens?: number;
+  maxTokens?: number;
+} {
+  const match = message.match(/(\d[\d,]*)\s*(?:tokens?\s*)?[>≥]\s*(\d[\d,]*)/i);
+  if (!match) return {};
+  const actual = parseInt(match[1].replace(/,/g, ""), 10);
+  const max = parseInt(match[2].replace(/,/g, ""), 10);
+  const out: { actualTokens?: number; maxTokens?: number } = {};
+  if (!isNaN(actual) && actual > 0) out.actualTokens = actual;
+  if (!isNaN(max) && max > 0) out.maxTokens = max;
+  return out;
+}

package/src/runtime/AGENTS.md

@@ -18,9 +18,9 @@ Approvals are **orthogonal to message sending**. The assistant asks for approval
 
 - **Discovery**: Clients discover pending approvals via SSE events (`confirmation_request`, `secret_request`) which include a `requestId`.
 - **Resolution**: Clients respond via standalone endpoints keyed by `requestId`:
-  - `POST /v1/confirm` — `{ requestId, decision, selectedPattern?, selectedScope? }`. Valid decisions: `"allow"`, `"allow_10m"`, `"allow_conversation"`, `"deny"`, `"always_allow"`, `"always_deny"`, `"always_allow_high_risk"`. For persistent decisions (`always_allow`, `always_deny`, `always_allow_high_risk`), `selectedPattern` and `selectedScope` are validated against the server-provided allowlist/scope options from the original confirmation request before trust rules are persisted.
+  - `POST /v1/confirm` — `{ requestId, decision, selectedPattern?, selectedScope? }`. Valid decisions: `"allow"`, `"allow_10m"`, `"allow_conversation"`, `"deny"`, `"always_allow"`, `"always_deny"`. For persistent decisions (`always_allow`, `always_deny`), `selectedPattern` and `selectedScope` are validated against the server-provided allowlist/scope options from the original confirmation request before trust rules are persisted.
   - `POST /v1/secret` — `{ requestId, value, delivery }`
-  - `POST /v1/trust-rules` — `{ requestId, pattern, scope, decision, allowHighRisk? }`. Validates pattern/scope against server-provided options. Does not resolve the confirmation itself.
+  - `POST /v1/trust-rules` — `{ requestId, pattern, scope, decision }`. Validates pattern/scope against server-provided options. Does not resolve the confirmation itself.
 - **Tracking**: The `pending-interactions` tracker (`assistant/src/runtime/pending-interactions.ts`) maps `requestId → conversation`. Use `register()` to track, `resolve()` to consume, `getByConversation()` to query.
 
 Do NOT couple approval handling to message sending. Do NOT add run/status tracking to the send path.
@@ -65,7 +65,7 @@ Host browser allows the assistant to proxy CDP (Chrome DevTools Protocol) JSON-R
 
 The `chrome-extension` interface in `INTERFACE_IDS` is a non-interactive transport that supports only the `host_browser` capability — it does NOT support `host_bash`, `host_file`, or `host_cu`. This is encoded in `supportsHostProxy(id, capability)`: passing a capability argument returns `true` for `chrome-extension` only when the capability is `host_browser`; the no-arg form returns `false` for `chrome-extension` (so legacy desktop-only call sites that assume full-desktop proxy availability continue to gate correctly).
 
-Unlike the SSE-based host proxies used by the macOS client, `host_browser_request` frames for the chrome-extension interface do NOT travel through `assistantEventHub`. Instead they are routed through the `ChromeExtensionRegistry` singleton (`runtime/chrome-extension-registry.ts`), which tracks active chrome-extension WebSocket connections keyed by `(guardianId, clientInstanceId)`. The registry is populated on WebSocket `open` and drained on `close` inside `http-server.ts`'s `/v1/browser-relay` handlers — see the `wsType === "browser-relay"` branches.
+For the chrome-extension interface, `host_browser_request` frames do NOT travel through `assistantEventHub`. Instead they are routed through the `ChromeExtensionRegistry` singleton (`runtime/chrome-extension-registry.ts`), which tracks active chrome-extension WebSocket connections keyed by `(guardianId, clientInstanceId)`. The registry is populated on WebSocket `open` and drained on `close` inside `http-server.ts`'s `/v1/browser-relay` handlers — see the `wsType === "browser-relay"` branches. For macOS, `host_browser_request` frames travel through `assistantEventHub` (SSE) by default; when the guardian also has an active extension connection, the registry-routed WebSocket sender takes precedence.
 
 A single guardian may have multiple parallel extension installs connected at once (two Chrome profiles, two desktops sharing a sync identity). Each install generates a stable `clientInstanceId` on first run, persists it in `chrome.storage.local`, and sends it on every WebSocket handshake as a query param (`clientInstanceId=...`) or header (`x-client-instance-id`). The registry keys inner entries by that id so sibling installs don't evict each other on register/unregister. The default `send(guardianId, msg)` path routes to whichever instance has the most recent activity (`lastActiveAt`); `sendToInstance(guardianId, clientInstanceId, msg)` pins a specific install. Older extension builds that omit the id get a connection-scoped `legacy:<connectionId>` fallback key so they degrade gracefully to single-instance semantics.
 
@@ -79,11 +79,20 @@ See `docs/browser-use-architecture-phase2.md` for the full wire diagram and comp
 
 On macOS-originated turns, the CDP factory (`tools/browser/cdp-client/factory.ts`) evaluates three browser backends in strict priority order. Each candidate is tried lazily; if the first command fails with a transport-level error, the factory falls over to the next candidate. CDP protocol errors (the browser understood the command but rejected it) do NOT trigger failover.
 
-| Priority | Backend         | Condition                                                                                                                                                                                           | Source                                                                                 |
-| -------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| 1        | **Extension**   | `hostBrowserProxy` present AND `isAvailable()` returns `true` (registry-routed WebSocket is connected)                                                                                              | `ChromeExtensionRegistry` via `resolveHostBrowserSender()` in `conversation-routes.ts` |
-| 2        | **cdp-inspect** | (a) `hostBrowser.cdpInspect.enabled` is `true` in config, OR (b) `transportInterface === "macos"` AND `desktopAuto.enabled` is `true` (default) AND the cooldown from a prior failure is not active | Config + `desktopAuto` policy in factory                                               |
-| 3        | **Local**       | Always present as the final fallback                                                                                                                                                                | Playwright sacrificial-profile browser managed by `browserManager`                     |
+| Priority | Backend                    | Condition                                                                                                                                                                                           | Transport                                                                                              |
+| -------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| 1        | **Extension / host proxy** | `hostBrowserProxy` present AND `isAvailable()` returns `true`. On macOS, the proxy is always provisioned (SSE sender when no extension is present, registry-routed when extension is connected)     | WS via `ChromeExtensionRegistry` (extension present) or SSE via `assistantEventHub` (macOS host proxy) |
+| 2        | **cdp-inspect**            | (a) `hostBrowser.cdpInspect.enabled` is `true` in config, OR (b) `transportInterface === "macos"` AND `desktopAuto.enabled` is `true` (default) AND the cooldown from a prior failure is not active | Direct CDP WebSocket to `localhost:9222`                                                               |
+| 3        | **Local**                  | Always present as the final fallback                                                                                                                                                                | In-process Playwright CDP via `browserManager`                                                         |
+
+**Transport selection for the extension/host-proxy backend:**
+
+The "extension" backend label is a misnomer inherited from the original Phase 2 design where only the Chrome Extension provided host-browser access. In the current architecture, two transports can power this backend:
+
+- **Extension WebSocket**: When the `ChromeExtensionRegistry` has an active entry for the guardian, `resolveHostBrowserSender()` returns a registry-routed sender. `host_browser_request` frames travel over the `/v1/browser-relay` WebSocket to the Chrome extension, which executes CDP commands via `chrome.debugger`.
+- **macOS SSE bridge**: When the macOS desktop client is connected but no extension is present, `resolveHostBrowserSender()` returns the `onEvent` SSE hub sender. `host_browser_request` frames travel through `assistantEventHub` to the desktop client's SSE connection. The desktop client executes CDP commands against the local Chrome and POSTs results back to `/v1/host-browser-result`.
+
+Both transports use the same `HostBrowserProxy` → `ExtensionCdpClient` pipeline. The `browser_status` output distinguishes the transport via the `details.transport` field: `"extension-ws"` or `"macos-sse"`.
 
 **Fallback criteria for cdp-inspect (desktop-auto):**
 
@@ -98,24 +107,24 @@ On macOS-originated turns, the CDP factory (`tools/browser/cdp-client/factory.ts
 
 All CDP-backed browser tools (`browser_navigate`, `browser_snapshot`, `browser_screenshot`, `browser_click`, `browser_type`, `browser_hover`, `browser_scroll`, `browser_press_key`, `browser_select_option`, `browser_wait_for`, `browser_extract`, `browser_fill_credential`, `browser_attach`, `browser_detach`, `browser_close`, `browser_status`) accept an optional `browser_mode` input parameter that overrides the automatic backend selection for that invocation.
 
-| Value            | Behavior                                                                 |
-| ---------------- | ------------------------------------------------------------------------ |
-| `auto` (default) | Existing priority-ordered fallback: extension -> cdp-inspect -> local    |
-| `extension`      | Pin to chrome-extension backend. Fails immediately if proxy unavailable. |
-| `cdp-inspect`    | Pin to CDP inspect/debugger backend. Fails if endpoint unreachable.      |
-| `local`          | Pin to local Playwright-managed browser. No fallback.                    |
-| `cdp-debugger`   | Alias for `cdp-inspect`.                                                 |
-| `playwright`     | Alias for `local`.                                                       |
+| Value            | Behavior                                                                     |
+| ---------------- | ---------------------------------------------------------------------------- |
+| `auto` (default) | Existing priority-ordered fallback: extension -> cdp-inspect -> local        |
+| `extension`      | Pin to extension/host-proxy backend. Fails immediately if proxy unavailable. |
+| `cdp-inspect`    | Pin to CDP inspect/debugger backend. Fails if endpoint unreachable.          |
+| `local`          | Pin to local Playwright-managed browser. No fallback.                        |
+| `cdp-debugger`   | Alias for `cdp-inspect`.                                                     |
+| `playwright`     | Alias for `local`.                                                           |
 
 **Strict pinned-mode semantics**: When `browser_mode` is set to a specific backend (not `auto`), the factory builds exactly one candidate and disables failover. If the pinned backend is unavailable, the tool returns a detailed error including:
 
 - The requested mode
 - An ordered list of attempted backends with exact failure reasons
-- A remediation checklist tailored by backend and failure code (e.g. "Ensure Chrome is running with --remote-debugging-port=9222")
+- A remediation checklist tailored by backend, failure code, and transport (e.g. for macOS SSE: "Verify the Vellum desktop app is running"; for extension: "Ensure Chrome is running with the extension paired")
 
 **Auto-mode fallback logging**: In auto mode, fallback transitions are logged at `warn` level with structured metadata including the full candidate sequence and per-candidate failure reasons. This ensures fallback events are always observable in production logs.
 
-**Test coverage:** Regression tests for `browser_mode` wiring live in `__tests__/headless-browser-mode.test.ts`. E2E regression tests for backend precedence live in `__tests__/host-browser-e2e-cloud.test.ts` (extension path) and `__tests__/conversation-routes-disk-view.test.ts` (macOS fallback path). Unit tests for pinned candidate construction and failover live in `tools/browser/cdp-client/__tests__/factory.test.ts`.
+**Test coverage:** Regression tests for `browser_mode` wiring live in `__tests__/headless-browser-mode.test.ts`. E2E regression tests for backend precedence live in `__tests__/host-browser-e2e-cloud.test.ts` (extension path and macOS SSE bridge path) and `__tests__/conversation-routes-disk-view.test.ts` (macOS fallback path). Unit tests for pinned candidate construction and failover live in `tools/browser/cdp-client/__tests__/factory.test.ts`. Browser status tests covering macOS host-browser diagnostics live in `tools/browser/__tests__/browser-status.test.ts`.
 
 ### Channel approvals (Telegram, Slack)
 

package/src/runtime/__tests__/agent-wake.test.ts

@@ -490,12 +490,53 @@ describe("wakeAgentForOpportunity", () => {
     expect(result.producedToolCalls).toBe(false);
   });
 
-  test("returns invoked: false when the conversation cannot be resolved", async () => {
+  test("returns invoked: false with reason 'not_found' when the conversation cannot be resolved", async () => {
     const result = await wakeAgentForOpportunity(
       { conversationId: "missing", hint: "x", source: "y" },
       { resolveTarget: async () => null },
     );
-    expect(result).toEqual({ invoked: false, producedToolCalls: false });
+    expect(result).toEqual({
+      invoked: false,
+      producedToolCalls: false,
+      reason: "not_found",
+    });
+  });
+
+  test("returns invoked: false with reason 'timeout' when the target stays busy past the wait-until-idle window", async () => {
+    // Resolver returns a target that is permanently `processing`. Fast-
+    // forward the injected `now` past the 30s deadline so waitUntilIdle
+    // returns false. Without the distinct `timeout` reason, callers
+    // cannot tell this case apart from "not_found".
+    const history: Message[] = [];
+    const target: WakeTarget = {
+      conversationId: "conv-busy",
+      agentLoop: { run: async () => history },
+      getMessages: () => history,
+      pushMessage: () => {},
+      emitAgentEvent: () => {},
+      isProcessing: () => true,
+      markProcessing: () => {},
+      persistTailMessage: async () => {},
+    };
+    let t = 0;
+    const now = () => {
+      // First call establishes the deadline at +30_000. Every subsequent
+      // call jumps past the deadline so the polling loop exits after one
+      // 50ms tick.
+      const v = t;
+      t += 31_000;
+      return v;
+    };
+
+    const result = await wakeAgentForOpportunity(
+      { conversationId: "conv-busy", hint: "x", source: "y" },
+      { resolveTarget: async () => target, now },
+    );
+    expect(result).toEqual({
+      invoked: false,
+      producedToolCalls: false,
+      reason: "timeout",
+    });
   });
 
   test("agent loop error is treated as a no-op", async () => {

package/src/runtime/__tests__/browser-extension-pair-routes.test.ts

@@ -26,7 +26,7 @@ import {
   verifyHostBrowserCapability,
 } from "../capability-tokens.js";
 import {
-  ALLOWED_EXTENSION_ORIGINS,
+  getAllowedExtensionOrigins,
   handleBrowserExtensionPair,
   NATIVE_HOST_MARKER_HEADER,
   NATIVE_HOST_MARKER_VALUE,
@@ -55,10 +55,10 @@ const lanPeerServer = mockServer("192.168.1.10");
 const publicPeerServer = mockServer("203.0.113.50");
 
 const ALLOWED_ORIGIN = (() => {
-  const first = Array.from(ALLOWED_EXTENSION_ORIGINS)[0];
+  const first = Array.from(getAllowedExtensionOrigins())[0];
   if (!first) {
     throw new Error(
-      "ALLOWED_EXTENSION_ORIGINS must contain at least one extension origin for tests",
+      "getAllowedExtensionOrigins() must contain at least one extension origin for tests",
     );
   }
   return first;