@vellumai/assistant 0.6.5 → 0.7.0

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

@@ -255,13 +255,17 @@ export class XAIRealtimeTranscriber implements StreamingTranscriber {
     await new Promise<void>((resolve, reject) => {
       let settled = false;
 
-      const handshakeTimer = setTimeout(() => {
-        if (settled) return;
-        settled = true;
-        this.forceClose();
-        reject(new Error("xAI realtime connect timeout"));
-      }, this.connectTimeoutMs);
-
+      // Listener references, captured so we can detach them from the
+      // abandoned socket on every reject/timeout path. Without this,
+      // `forceClose()` → `ws.close()` triggers an asynchronous `close`
+      // event (and real WebSocket impls commonly chain `error` → `close`)
+      // on the old socket. With the listeners still attached, that stray
+      // event routes through the `settled === true` branch into
+      // `handleProviderClose`, which calls `emitClosedAndCleanup()` and
+      // sets `this.closed = true`. A subsequent `start()` then resolves
+      // but `sendAudio` / `stop` / timers all no-op because `this.closed`
+      // is sticky — retry is silently dead. Detaching the handlers
+      // before `forceClose()` closes that window.
       const settleResolve = () => {
         if (settled) return;
         settled = true;
@@ -273,6 +277,9 @@ export class XAIRealtimeTranscriber implements StreamingTranscriber {
         if (settled) return;
         settled = true;
         clearTimeout(handshakeTimer);
+        // Detach listeners BEFORE `forceClose()` so stray close/error
+        // events on the abandoned socket can't flip `this.closed`.
+        detachHandshakeListeners();
         // Null out this.ws (via forceClose) so the instance can be
         // reused for a retry. Without this, a subsequent start() call
         // would throw "start() called twice" even though no session
@@ -288,9 +295,8 @@ export class XAIRealtimeTranscriber implements StreamingTranscriber {
       const onOpen = () => {
         ws.removeEventListener("open", onOpen);
       };
-      ws.addEventListener("open", onOpen);
 
-      ws.addEventListener("message", (ev: { data: unknown }) => {
+      const onMessage = (ev: { data: unknown }) => {
         if (!settled) {
           if (tryParseHandshakeFrame(ev.data)?.type === "transcript.created") {
             settleResolve();
@@ -303,9 +309,9 @@ export class XAIRealtimeTranscriber implements StreamingTranscriber {
           return;
         }
         this.handleProviderMessage(ev.data);
-      });
+      };
 
-      ws.addEventListener("close", (ev: { code: number; reason: string }) => {
+      const onClose = (ev: { code: number; reason: string }) => {
         if (!settled) {
           // 401 / 403 on connect arrive as WebSocket close codes 4001 /
           // 4003 in most runtimes (or 1008 policy-violation in others).
@@ -320,9 +326,9 @@ export class XAIRealtimeTranscriber implements StreamingTranscriber {
           return;
         }
         this.handleProviderClose(ev.code, ev.reason);
-      });
+      };
 
-      ws.addEventListener("error", (ev: unknown) => {
+      const onError = (ev: unknown) => {
         if (!settled) {
           const msg =
             ev instanceof Error
@@ -334,7 +340,26 @@ export class XAIRealtimeTranscriber implements StreamingTranscriber {
           return;
         }
         this.handleProviderError(ev);
-      });
+      };
+
+      const detachHandshakeListeners = () => {
+        ws.removeEventListener("message", onMessage);
+        ws.removeEventListener("close", onClose);
+        ws.removeEventListener("error", onError);
+      };
+
+      const handshakeTimer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        detachHandshakeListeners();
+        this.forceClose();
+        reject(new Error("xAI realtime connect timeout"));
+      }, this.connectTimeoutMs);
+
+      ws.addEventListener("open", onOpen);
+      ws.addEventListener("message", onMessage);
+      ws.addEventListener("close", onClose);
+      ws.addEventListener("error", onError);
     });
 
     this.resetInactivityTimer();

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

@@ -1,13 +1,13 @@
 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;
+const XAI_STT_URL = "https://api.x.ai/v1/stt";
+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 {
+function extensionFromMime(mimeType: string): string {
   const map: Record<string, string> = {
     "audio/wav": "wav",
     "audio/x-wav": "wav",
@@ -31,7 +31,7 @@ export function extensionFromMime(mimeType: string): string {
  * `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 {
+function buildXaiFormData(audio: Buffer, mimeType: string): FormData {
   const ext = extensionFromMime(mimeType);
 
   const formData = new FormData();
@@ -51,7 +51,7 @@ export function buildXaiFormData(audio: Buffer, mimeType: string): FormData {
  * xAI returns a richer shape (`{ text, language, duration, words }`) — we only
  * consume `text`.
  */
-export async function xaiTranscribe(
+async function xaiTranscribe(
   apiKey: string,
   audio: Buffer,
   mimeType: string,

package/src/providers/thinking-config.ts

@@ -0,0 +1,34 @@
+type ThinkingConfigRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is ThinkingConfigRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function normalizeThinkingConfigForWire(
+  thinking: unknown,
+): ThinkingConfigRecord | undefined {
+  if (!isRecord(thinking)) return undefined;
+
+  if (typeof thinking.type === "string") {
+    return thinking;
+  }
+
+  if (thinking.enabled === true) {
+    return { type: "adaptive" };
+  }
+
+  if (thinking.enabled === false) {
+    return { type: "disabled" };
+  }
+
+  return undefined;
+}
+
+export function isThinkingConfigDisabled(thinking: unknown): boolean {
+  return normalizeThinkingConfigForWire(thinking)?.type === "disabled";
+}
+
+export function isThinkingConfigEnabled(thinking: unknown): boolean {
+  const normalized = normalizeThinkingConfigForWire(thinking);
+  return normalized !== undefined && normalized.type !== "disabled";
+}

package/src/providers/types.ts

@@ -1,3 +1,6 @@
+import type { ToolDefinition } from "@vellumai/skill-host-contracts";
+export type { ToolDefinition };
+
 import type { LLMCallSite } from "../config/schemas/llm.js";
 import { ProviderError } from "../util/errors.js";
 
@@ -31,6 +34,11 @@ export interface ToolUseContent {
   id: string;
   name: string;
   input: Record<string, unknown>;
+  providerMetadata?: {
+    gemini?: {
+      thoughtSignature?: string;
+    };
+  };
 }
 
 export interface ThinkingContent {
@@ -82,12 +90,6 @@ export interface Message {
   content: ContentBlock[];
 }
 
-export interface ToolDefinition {
-  name: string;
-  description: string;
-  input_schema: object;
-}
-
 export type ModelIntent =
   | "latency-optimized"
   | "quality-optimized"
@@ -140,13 +142,23 @@ export interface SendMessageConfig {
   model?: string;
   /**
    * 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.
+   * provider/model/maxTokens/effort/speed/verbosity/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";
+  /**
+   * Optional ad-hoc profile override applied per request. When set, the
+   * resolver layers `llm.profiles[overrideProfile]` between the workspace's
+   * `activeProfile` and the call-site's named profile (see
+   * `resolveCallSiteConfig`). Used by per-conversation pinned profiles to
+   * override the workspace default for a single send. Missing profile names
+   * silently fall through.
+   */
+  overrideProfile?: string;
+  effort?: "none" | "low" | "medium" | "high" | "xhigh" | "max";
   speed?: "standard" | "fast";
+  verbosity?: "low" | "medium" | "high";
   [key: string]: unknown;
 }
 

package/src/runtime/AGENTS.md

@@ -65,13 +65,13 @@ 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 **self-hosted** deployments, `host_browser_request` frames 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 **cloud/platform-hosted** deployments, the chrome extension connects via SSE (`GET /v1/events` with `X-Vellum-Interface-Id: chrome-extension`) and `host_browser_request` frames travel through `assistantEventHub` to the SSE stream. The extension POSTs results back to `POST /v1/host-browser-result`. Transport selection is handled by `resolveHostBrowserSender()` which checks the `ChromeExtensionRegistry` first (WS), then the `ClientRegistry` for an SSE-connected chrome-extension client. 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.
 
 `Conversation.hostBrowserSenderOverride` is the integration point between the turn layer and the registry. When any turn enters the routes layer and the guardian has an active extension connection in the `ChromeExtensionRegistry`, `conversation-routes.ts` resolves the registry entry and sets the override to a sender that writes to that WebSocket. This applies to chrome-extension turns (where the registry is the only transport) and macOS turns (where the extension connection lets browser tools route through the user's real Chrome session instead of cdp-inspect/local). `Conversation.restoreBrowserProxyAvailability()` re-threads the override on queue drain — without this, the drain path would clobber the registry-routed sender with the default `sendToClient` (pointed at the SSE hub) and `host_browser_request` frames would stop reaching the extension mid-queue.
 
-Capability token bootstrap for self-hosted deployments is handled by `routes/browser-extension-pair-routes.ts` (loopback-only; mints a guardian-bound HMAC capability token via `capability-tokens.ts`). Cloud deployments issue guardian-bound JWTs via the gateway's WorkOS-backed flow — `browser-extension-pair-routes.ts` is not involved.
+Capability token bootstrap for self-hosted deployments is handled by the gateway (`gateway/src/http/routes/browser-extension-pair.ts`) which mints a guardian-bound HMAC capability token. The daemon delegates token verification to the gateway via IPC (`verify_capability_token`) — it must never read secrets from `GATEWAY_SECURITY_DIR` or any other gateway-owned directory. Cloud deployments issue guardian-bound JWTs via the gateway's WorkOS-backed flow.
 
 See `docs/browser-use-architecture-phase2.md` for the full wire diagram and component inventory.
 
@@ -79,11 +79,21 @@ 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. On other interfaces, requires an active transport (WS registry or SSE chrome-extension client) | WS via `ChromeExtensionRegistry` (self-hosted), SSE via `assistantEventHub` (cloud extension or macOS) |
+| 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** (self-hosted): 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`.
+- **Extension SSE** (cloud/platform): When no WebSocket entry exists but a `chrome-extension` client is registered in the `ClientRegistry` (connected via `GET /v1/events`), `resolveHostBrowserSender()` returns the `onEvent` SSE hub sender and sets `hasSseExtension = true`. `host_browser_request` frames travel through `assistantEventHub` to the extension's SSE stream. The extension POSTs results back to `/v1/host-browser-result`. This path is used for any `canServiceSseBrowser()` interface (`web`, `chrome-extension`, `macos`).
+- **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`.
+
+All three 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 +108,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

@@ -15,7 +15,14 @@
  * `memory/conversation-crud.js`.
  */
 
-import { beforeEach, describe, expect, test } from "bun:test";
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// Stub the DB-backed override-profile read so unit tests don't need a
+// real SQLite database. The wake helper calls this on every invocation
+// to honor the conversation's pinned inference profile.
+mock.module("../../memory/conversation-crud.js", () => ({
+  getConversationOverrideProfile: () => undefined,
+}));
 
 import type { AgentEvent } from "../../agent/loop.js";
 import type { Message } from "../../providers/types.js";
@@ -195,11 +202,32 @@ describe("wakeAgentForOpportunity", () => {
     // Hint was included in the run input, but baseline is unchanged.
     expect(target.runCalls).toHaveLength(1);
     const input = target.runCalls[0]!.input;
-    expect(input).toHaveLength(3); // 2 baseline + 1 hint
+    expect(input).toHaveLength(5); // 2 baseline + 3 hint (user + assistant + user)
     expect(input[2]).toEqual({
       role: "user",
       content: [
-        { type: "text", text: "[opportunity:unit-test] someone asked a question" },
+        {
+          type: "text",
+          text: "[system] The following assistant message comes from an external system.",
+        },
+      ],
+    });
+    expect(input[3]).toEqual({
+      role: "assistant",
+      content: [
+        {
+          type: "text",
+          text: "[opportunity:unit-test] someone asked a question",
+        },
+      ],
+    });
+    expect(input[4]).toEqual({
+      role: "user",
+      content: [
+        {
+          type: "text",
+          text: "[system] End of message from external system, continue the conversation.",
+        },
       ],
     });
   });
@@ -723,9 +751,7 @@ describe("wakeAgentForOpportunity", () => {
     };
     const toolResultUserMsg: Message = {
       role: "user",
-      content: [
-        { type: "tool_result", tool_use_id: "tu-1", content: "ok" },
-      ],
+      content: [{ type: "tool_result", tool_use_id: "tu-1", content: "ok" }],
     };
     const followup: Message = {
       role: "assistant",
@@ -776,9 +802,7 @@ describe("wakeAgentForOpportunity", () => {
       };
       const toolResultUserMsg: Message = {
         role: "user",
-        content: [
-          { type: "tool_result", tool_use_id: "tu-1", content: "ok" },
-        ],
+        content: [{ type: "tool_result", tool_use_id: "tu-1", content: "ok" }],
       };
       const followup: Message = {
         role: "assistant",

package/src/runtime/__tests__/client-registry.test.ts

@@ -0,0 +1,271 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+
+import {
+  __resetClientRegistryForTests,
+  ClientRegistry,
+  getClientRegistry,
+} from "../client-registry.js";
+
+describe("ClientRegistry", () => {
+  beforeEach(() => {
+    __resetClientRegistryForTests();
+  });
+
+  // ── register ──────────────────────────────────────────────────────────────
+
+  test("register creates a new entry with derived capabilities", () => {
+    const registry = new ClientRegistry();
+    const entry = registry.register({
+      clientId: "mac-1",
+      interfaceId: "macos",
+    });
+
+    expect(entry.clientId).toBe("mac-1");
+    expect(entry.interfaceId).toBe("macos");
+    expect(entry.capabilities).toContain("host_bash");
+    expect(entry.capabilities).toContain("host_file");
+    expect(entry.capabilities).toContain("host_cu");
+    expect(entry.capabilities).toContain("host_browser");
+    expect(entry.connectedAt).toBeGreaterThan(0);
+    expect(entry.lastActiveAt).toBeGreaterThanOrEqual(entry.connectedAt);
+  });
+
+  test("register derives empty capabilities for cli interface", () => {
+    const registry = new ClientRegistry();
+    const entry = registry.register({
+      clientId: "cli-1",
+      interfaceId: "cli",
+    });
+
+    expect(entry.capabilities).toEqual([]);
+  });
+
+  test("register derives host_browser capability for chrome-extension", () => {
+    const registry = new ClientRegistry();
+    const entry = registry.register({
+      clientId: "ext-1",
+      interfaceId: "chrome-extension",
+    });
+
+    expect(entry.capabilities).toEqual(["host_browser"]);
+  });
+
+  test("register refreshes lastActiveAt on re-register with same clientId", () => {
+    const registry = new ClientRegistry();
+    const first = registry.register({
+      clientId: "mac-1",
+      interfaceId: "macos",
+    });
+    const firstActive = first.lastActiveAt;
+
+    // Advance time slightly
+    const second = registry.register({
+      clientId: "mac-1",
+      interfaceId: "macos",
+    });
+
+    // Same object reference — refreshed in place
+    expect(second).toBe(first);
+    expect(second.lastActiveAt).toBeGreaterThanOrEqual(firstActive);
+    // connectedAt should NOT change on refresh
+    expect(second.connectedAt).toBe(first.connectedAt);
+  });
+
+  test("register does not increase size on re-register", () => {
+    const registry = new ClientRegistry();
+    registry.register({ clientId: "mac-1", interfaceId: "macos" });
+    registry.register({ clientId: "mac-1", interfaceId: "macos" });
+    expect(registry.size).toBe(1);
+  });
+
+  // ── unregister ────────────────────────────────────────────────────────────
+
+  test("unregister removes the entry", () => {
+    const registry = new ClientRegistry();
+    registry.register({ clientId: "mac-1", interfaceId: "macos" });
+    expect(registry.size).toBe(1);
+
+    registry.unregister("mac-1");
+    expect(registry.size).toBe(0);
+    expect(registry.get("mac-1")).toBeUndefined();
+  });
+
+  test("unregister is a no-op for unknown clientId", () => {
+    const registry = new ClientRegistry();
+    registry.register({ clientId: "mac-1", interfaceId: "macos" });
+    registry.unregister("unknown");
+    expect(registry.size).toBe(1);
+  });
+
+  // ── touch ─────────────────────────────────────────────────────────────────
+
+  test("touch updates lastActiveAt", () => {
+    const registry = new ClientRegistry();
+    const entry = registry.register({
+      clientId: "mac-1",
+      interfaceId: "macos",
+    });
+    const before = entry.lastActiveAt;
+    registry.touch("mac-1");
+    expect(entry.lastActiveAt).toBeGreaterThanOrEqual(before);
+  });
+
+  test("touch is a no-op for unknown clientId", () => {
+    const registry = new ClientRegistry();
+    // Should not throw
+    registry.touch("unknown");
+  });
+
+  // ── get ───────────────────────────────────────────────────────────────────
+
+  test("get returns the entry for a registered clientId", () => {
+    const registry = new ClientRegistry();
+    const entry = registry.register({
+      clientId: "mac-1",
+      interfaceId: "macos",
+    });
+    expect(registry.get("mac-1")).toBe(entry);
+  });
+
+  test("get returns undefined for unknown clientId", () => {
+    const registry = new ClientRegistry();
+    expect(registry.get("unknown")).toBeUndefined();
+  });
+
+  // ── listAll ───────────────────────────────────────────────────────────────
+
+  test("listAll returns entries sorted by lastActiveAt descending", () => {
+    const registry = new ClientRegistry();
+    registry.register({ clientId: "old", interfaceId: "cli" });
+    // Touch the second one to make it most recent
+    registry.register({ clientId: "new", interfaceId: "macos" });
+
+    const all = registry.listAll();
+    expect(all.length).toBe(2);
+    expect(all[0].lastActiveAt).toBeGreaterThanOrEqual(all[1].lastActiveAt);
+  });
+
+  test("listAll returns empty array when no clients registered", () => {
+    const registry = new ClientRegistry();
+    expect(registry.listAll()).toEqual([]);
+  });
+
+  // ── listByCapability ──────────────────────────────────────────────────────
+
+  test("listByCapability filters to clients with matching capability", () => {
+    const registry = new ClientRegistry();
+    registry.register({ clientId: "mac-1", interfaceId: "macos" });
+    registry.register({ clientId: "cli-1", interfaceId: "cli" });
+    registry.register({ clientId: "ext-1", interfaceId: "chrome-extension" });
+
+    const bashCapable = registry.listByCapability("host_bash");
+    expect(bashCapable.length).toBe(1);
+    expect(bashCapable[0].clientId).toBe("mac-1");
+
+    const browserCapable = registry.listByCapability("host_browser");
+    expect(browserCapable.length).toBe(2);
+    // macOS now supports host_browser too
+    const ids = browserCapable.map((e) => e.clientId).sort();
+    expect(ids).toEqual(["ext-1", "mac-1"]);
+  });
+
+  test("listByCapability returns empty when no clients match", () => {
+    const registry = new ClientRegistry();
+    registry.register({ clientId: "cli-1", interfaceId: "cli" });
+    expect(registry.listByCapability("host_bash")).toEqual([]);
+  });
+
+  // ── getMostRecentByCapability ─────────────────────────────────────────────
+
+  test("getMostRecentByCapability returns the most recently active client", () => {
+    const registry = new ClientRegistry();
+    const mac1 = registry.register({ clientId: "mac-1", interfaceId: "macos" });
+    const mac2 = registry.register({ clientId: "mac-2", interfaceId: "macos" });
+
+    // Ensure deterministic ordering — both may register within the same ms
+    mac1.lastActiveAt = Date.now() - 5000;
+    mac2.lastActiveAt = Date.now();
+
+    const best = registry.getMostRecentByCapability("host_bash");
+    expect(best).toBeDefined();
+    expect(best!.clientId).toBe("mac-2");
+  });
+
+  test("getMostRecentByCapability returns undefined when no clients match", () => {
+    const registry = new ClientRegistry();
+    registry.register({ clientId: "cli-1", interfaceId: "cli" });
+    expect(registry.getMostRecentByCapability("host_bash")).toBeUndefined();
+  });
+
+  // ── toJSON ────────────────────────────────────────────────────────────────
+
+  test("toJSON serializes with ISO timestamps", () => {
+    const registry = new ClientRegistry();
+    const entry = registry.register({
+      clientId: "mac-1",
+      interfaceId: "macos",
+    });
+
+    const json = ClientRegistry.toJSON(entry);
+    expect(json.clientId).toBe("mac-1");
+    expect(json.interfaceId).toBe("macos");
+    expect(json.capabilities).toContain("host_bash");
+    expect(json.connectedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+    expect(json.lastActiveAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+  });
+
+  // ── evictStale ─────────────────────────────────────────────────────────────
+
+  test("evictStale removes entries older than maxAgeMs", () => {
+    const registry = new ClientRegistry();
+    const entry = registry.register({
+      clientId: "old-mac",
+      interfaceId: "macos",
+    });
+    // Backdate lastActiveAt by 1 hour
+    entry.lastActiveAt = Date.now() - 60 * 60 * 1000;
+
+    const evicted = registry.evictStale(30 * 60 * 1000); // 30 min threshold
+    expect(evicted).toBe(1);
+    expect(registry.size).toBe(0);
+  });
+
+  test("evictStale keeps fresh entries", () => {
+    const registry = new ClientRegistry();
+    registry.register({ clientId: "fresh", interfaceId: "macos" });
+
+    const evicted = registry.evictStale(30 * 60 * 1000);
+    expect(evicted).toBe(0);
+    expect(registry.size).toBe(1);
+  });
+
+  test("listAll triggers lazy eviction", () => {
+    const registry = new ClientRegistry();
+    const entry = registry.register({
+      clientId: "stale-cli",
+      interfaceId: "cli",
+    });
+    entry.lastActiveAt = Date.now() - 60 * 60 * 1000;
+
+    registry.register({ clientId: "fresh-mac", interfaceId: "macos" });
+
+    const all = registry.listAll();
+    expect(all.length).toBe(1);
+    expect(all[0].clientId).toBe("fresh-mac");
+  });
+
+  // ── singleton ─────────────────────────────────────────────────────────────
+
+  test("getClientRegistry returns a singleton", () => {
+    const a = getClientRegistry();
+    const b = getClientRegistry();
+    expect(a).toBe(b);
+  });
+
+  test("__resetClientRegistryForTests clears the singleton", () => {
+    const a = getClientRegistry();
+    __resetClientRegistryForTests();
+    const b = getClientRegistry();
+    expect(a).not.toBe(b);
+  });
+});