@vellumai/assistant 0.6.2 → 0.6.3

package/src/runtime/http-server.ts

@@ -5,13 +5,18 @@
  * configured port (default: 7821).
  */
 
-import { existsSync, readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, resolve } from "node:path";
 
 import type { ServerWebSocket } from "bun";
 
-import type { BrowserRelayWebSocketData } from "../browser-extension-relay/server.js";
-import { extensionRelayServer } from "../browser-extension-relay/server.js";
 import {
   startGuardianActionSweep,
   stopGuardianActionSweep,
@@ -63,17 +68,24 @@ import {
 } from "../security/oauth-callback-registry.js";
 import { UserError } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
+import { getRuntimePortFilePath } from "../util/platform.js";
 import { buildAssistantEvent } from "./assistant-event.js";
 import { assistantEventHub } from "./assistant-event-hub.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "./assistant-scope.js";
 // Auth
-import { authenticateRequest } from "./auth/middleware.js";
+import {
+  authenticateHostBrowserResultRequest,
+  authenticateRequest,
+} from "./auth/middleware.js";
+import { parseSub } from "./auth/subject.js";
 import {
   mintDaemonDeliveryToken,
   mintUiPageToken,
   verifyToken,
 } from "./auth/token-service.js";
+import { verifyHostBrowserCapability } from "./capability-tokens.js";
 import { sweepFailedEvents } from "./channel-retry-sweep.js";
+import { getChromeExtensionRegistry } from "./chrome-extension-registry.js";
 import { httpError } from "./http-errors.js";
 import type { RouteDefinition } from "./http-router.js";
 import { HttpRouter } from "./http-router.js";
@@ -110,6 +122,8 @@ import { attachmentRouteDefinitions } from "./routes/attachment-routes.js";
 import { handleGetAudio } from "./routes/audio-routes.js";
 import { avatarRouteDefinitions } from "./routes/avatar-routes.js";
 import { brainGraphRouteDefinitions } from "./routes/brain-graph-routes.js";
+import { browserCdpRouteDefinitions } from "./routes/browser-cdp-routes.js";
+import { handleBrowserExtensionPair } from "./routes/browser-extension-pair-routes.js";
 import { btwRouteDefinitions } from "./routes/btw-routes.js";
 import { callRouteDefinitions } from "./routes/call-routes.js";
 import {
@@ -147,6 +161,12 @@ import { handleGuardianBootstrap } from "./routes/guardian-bootstrap-routes.js";
 import { handleGuardianRefresh } from "./routes/guardian-refresh-routes.js";
 import { heartbeatRouteDefinitions } from "./routes/heartbeat-routes.js";
 import { hostBashRouteDefinitions } from "./routes/host-bash-routes.js";
+import {
+  hostBrowserRouteDefinitions,
+  resolveHostBrowserEvent,
+  resolveHostBrowserResultByRequestId,
+  resolveHostBrowserSessionInvalidated,
+} from "./routes/host-browser-routes.js";
 import { hostCuRouteDefinitions } from "./routes/host-cu-routes.js";
 import { hostFileRouteDefinitions } from "./routes/host-file-routes.js";
 import {
@@ -228,6 +248,40 @@ const DEFAULT_HOSTNAME = "127.0.0.1";
 /** Global hard cap on request body size (512 MB — accommodates large .vbundle backup imports). */
 const MAX_REQUEST_BODY_BYTES = 512 * 1024 * 1024;
 
+/**
+ * WebSocket data attached to `/v1/browser-relay` connections. The route
+ * is used exclusively by the chrome-extension CDP proxy — outbound
+ * `host_browser_request` frames are pushed through the
+ * {@link ChromeExtensionRegistry}, and inbound `host_browser_result`
+ * frames are dispatched through
+ * `resolveHostBrowserResultByRequestId`. The extension may also submit
+ * results via `POST /v1/host-browser-result` (both transports resolve
+ * through the same core function).
+ */
+interface BrowserRelayWebSocketData {
+  wsType: "browser-relay";
+  connectionId: string;
+  /**
+   * Guardian identity derived from the JWT claims at WebSocket upgrade
+   * time. Used by the ChromeExtensionRegistry to route
+   * host_browser_request frames to the correct extension. Undefined when
+   * HTTP auth is disabled (dev bypass) or when the token's sub cannot be
+   * parsed into an actor principal.
+   */
+  guardianId?: string;
+  /**
+   * Stable per-extension-install identifier supplied by the client on
+   * the WebSocket handshake (via the `clientInstanceId` query param or
+   * the `x-client-instance-id` header). Plumbed into the
+   * ChromeExtensionRegistry so multiple parallel installs for the same
+   * guardian (e.g. two Chrome profiles, two desktops) don't evict each
+   * other on register/unregister. Undefined on older extension builds
+   * — the registry synthesizes a connection-scoped fallback key in
+   * that case for backwards-compatible single-instance semantics.
+   */
+  clientInstanceId?: string;
+}
+
 export class RuntimeHttpServer {
   private server: ReturnType<typeof Bun.serve> | null = null;
   private port: number;
@@ -329,9 +383,20 @@ export class RuntimeHttpServer {
         open(ws) {
           const data = ws.data as AllWebSocketData;
           if ("wsType" in data && data.wsType === "browser-relay") {
-            extensionRelayServer.handleOpen(
-              ws as ServerWebSocket<BrowserRelayWebSocketData>,
-            );
+            // When the JWT sub resolved to a guardian principal at upgrade
+            // time, register this connection with the chrome-extension
+            // registry so host_browser_request frames can be routed to it.
+            if (data.guardianId) {
+              const now = Date.now();
+              getChromeExtensionRegistry().register({
+                id: data.connectionId,
+                guardianId: data.guardianId,
+                clientInstanceId: data.clientInstanceId,
+                ws,
+                connectedAt: now,
+                lastActiveAt: now,
+              });
+            }
             return;
           }
           const callSessionId = (data as RelayWebSocketData).callSessionId;
@@ -351,11 +416,119 @@ export class RuntimeHttpServer {
               ? message
               : new TextDecoder().decode(message);
           if ("wsType" in data && data.wsType === "browser-relay") {
-            extensionRelayServer.handleMessage(
-              ws as ServerWebSocket<BrowserRelayWebSocketData>,
-              raw,
-            );
-            return;
+            // Inbound frames on `/v1/browser-relay` carry one of:
+            //   - `host_browser_result` — paired response to an outbound
+            //     `host_browser_request` (see PR2).
+            //   - `host_browser_event` — unsolicited CDP event forwarded
+            //     from the extension's `chrome.debugger.onEvent`
+            //     subscription (PR10).
+            //   - `host_browser_session_invalidated` — detach
+            //     notification forwarded from the extension's
+            //     `chrome.debugger.onDetach` subscription (PR10).
+            //
+            // Every supported frame type delegates into a shared
+            // resolver exported from `host-browser-routes.ts` so the
+            // validation and resolution semantics stay in lockstep
+            // with the HTTP path. Malformed or unsupported frames are
+            // logged at debug and swallowed — we never throw out of a
+            // WebSocket `message` handler because an uncaught
+            // exception would tear down the whole socket for an
+            // attacker-controlled payload.
+            let parsed: unknown;
+            try {
+              parsed = JSON.parse(raw);
+            } catch (err) {
+              log.debug(
+                {
+                  connectionId: data.connectionId,
+                  error: err instanceof Error ? err.message : String(err),
+                },
+                "browser-relay: dropped non-JSON inbound frame",
+              );
+              return;
+            }
+            if (!parsed || typeof parsed !== "object") {
+              log.debug(
+                { connectionId: data.connectionId },
+                "browser-relay: dropped non-object inbound frame",
+              );
+              return;
+            }
+            const frame = parsed as Record<string, unknown>;
+            switch (frame.type) {
+              case "host_browser_result": {
+                const resolution = resolveHostBrowserResultByRequestId({
+                  requestId: frame.requestId,
+                  content: frame.content,
+                  isError: frame.isError,
+                });
+                if (!resolution.ok) {
+                  log.warn(
+                    {
+                      connectionId: data.connectionId,
+                      requestId:
+                        typeof frame.requestId === "string"
+                          ? frame.requestId
+                          : undefined,
+                      code: resolution.code,
+                      message: resolution.message,
+                    },
+                    "browser-relay: host_browser_result frame rejected",
+                  );
+                }
+                return;
+              }
+              case "host_browser_event": {
+                const resolution = resolveHostBrowserEvent({
+                  method: frame.method,
+                  params: frame.params,
+                  cdpSessionId: frame.cdpSessionId,
+                });
+                if (!resolution.ok) {
+                  log.warn(
+                    {
+                      connectionId: data.connectionId,
+                      method:
+                        typeof frame.method === "string"
+                          ? frame.method
+                          : undefined,
+                      code: resolution.code,
+                      message: resolution.message,
+                    },
+                    "browser-relay: host_browser_event frame rejected",
+                  );
+                }
+                return;
+              }
+              case "host_browser_session_invalidated": {
+                const resolution = resolveHostBrowserSessionInvalidated({
+                  targetId: frame.targetId,
+                  reason: frame.reason,
+                });
+                if (!resolution.ok) {
+                  log.warn(
+                    {
+                      connectionId: data.connectionId,
+                      targetId:
+                        typeof frame.targetId === "string"
+                          ? frame.targetId
+                          : undefined,
+                      code: resolution.code,
+                      message: resolution.message,
+                    },
+                    "browser-relay: host_browser_session_invalidated frame rejected",
+                  );
+                }
+                return;
+              }
+              default: {
+                log.debug(
+                  { connectionId: data.connectionId, type: frame.type },
+                  "browser-relay: dropped unsupported inbound frame type",
+                );
+                return;
+              }
+            }
           }
           const callSessionId = (data as RelayWebSocketData).callSessionId;
           if (callSessionId) {
@@ -366,11 +539,12 @@ export class RuntimeHttpServer {
         close(ws, code, reason) {
           const data = ws.data as AllWebSocketData;
           if ("wsType" in data && data.wsType === "browser-relay") {
-            extensionRelayServer.handleClose(
-              ws as ServerWebSocket<BrowserRelayWebSocketData>,
-              code,
-              reason?.toString(),
-            );
+            // Always attempt to unregister — the registry uses connectionId
+            // as the key and no-ops if the entry is absent (e.g. when the
+            // connection was never registered because guardianId was
+            // undefined, or when it was superseded by a newer registration
+            // for the same guardian).
+            getChromeExtensionRegistry().unregister(data.connectionId);
             return;
           }
           const callSessionId = (data as RelayWebSocketData).callSessionId;
@@ -388,7 +562,51 @@ export class RuntimeHttpServer {
       },
     });
 
-    if (this.processMessage) {
+    this.startBackgroundSweeps();
+
+    log.info(
+      "Running in gateway-only ingress mode. Direct webhook routes disabled.",
+    );
+    if (!isLoopbackHost(this.hostname)) {
+      log.warn(
+        "RUNTIME_HTTP_HOST is not bound to loopback. This may expose the runtime to direct public access.",
+      );
+    }
+
+    this.pairingStore.start();
+
+    if (hasUngatedHttpAuthDisabled()) {
+      log.warn(
+        "DISABLE_HTTP_AUTH is set but VELLUM_UNSAFE_AUTH_BYPASS=1 is not — auth bypass is IGNORED and HTTP authentication remains enabled. Set VELLUM_UNSAFE_AUTH_BYPASS=1 to confirm the bypass.",
+      );
+    } else if (isHttpAuthDisabled()) {
+      log.warn(
+        "DISABLE_HTTP_AUTH is set — HTTP API authentication is DISABLED. All API endpoints are accessible without a bearer token. Do not use in production.",
+      );
+    }
+
+    log.info(
+      {
+        port: this.actualPort,
+        hostname: this.hostname,
+        auth: !!this.bearerToken,
+      },
+      "Runtime HTTP server listening",
+    );
+
+    // Advertise the actual port to thin helpers that need to reach the
+    // runtime without inheriting the daemon's environment (e.g. the
+    // chrome-extension native messaging helper, spawned by Chrome).
+    this.writeRuntimePortFile(this.actualPort);
+  }
+
+  /**
+   * Start background sweep timers: retry sweep for failed channel events,
+   * guardian approval/action expiry sweeps, and canonical guardian expiry.
+   * Extracted from start() to allow future callers to defer sweep startup.
+   */
+  private startBackgroundSweeps(): void {
+    if (this.processMessage && !this.retrySweepTimer) {
       const pm = this.processMessage;
       const mintBt = () => mintDaemonDeliveryToken();
       this.retrySweepTimer = setInterval(() => {
@@ -416,36 +634,76 @@ export class RuntimeHttpServer {
 
     startCanonicalGuardianExpirySweep();
     log.info("Canonical guardian request expiry sweep started");
+  }
 
-    log.info(
-      "Running in gateway-only ingress mode. Direct webhook routes disabled.",
-    );
-    if (!isLoopbackHost(this.hostname)) {
+  /**
+   * Atomically publish the runtime HTTP port to ~/.vellum/runtime-port so
+   * external helpers can locate a non-default `RUNTIME_HTTP_PORT` without
+   * any manifest changes. Best-effort — write failures never block
+   * daemon startup (see assistant/AGENTS.md "Daemon startup philosophy").
+   */
+  private writeRuntimePortFile(actualPort: number): void {
+    try {
+      const portFile = getRuntimePortFilePath();
+      const dir = dirname(portFile);
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
+      const tmpPath = `${portFile}.tmp.${process.pid}`;
+      writeFileSync(tmpPath, String(actualPort), { mode: 0o644 });
+      renameSync(tmpPath, portFile);
+      log.info({ portFile, actualPort }, "Wrote runtime port file");
+    } catch (err) {
       log.warn(
-        "RUNTIME_HTTP_HOST is not bound to loopback. This may expose the runtime to direct public access.",
+        { err },
+        "Failed to write runtime port file; non-default assistant ports may require --assistant-port on thin helpers",
       );
     }
+  }
 
-    this.pairingStore.start();
-
-    if (hasUngatedHttpAuthDisabled()) {
-      log.warn(
-        "DISABLE_HTTP_AUTH is set but VELLUM_UNSAFE_AUTH_BYPASS=1 is not — auth bypass is IGNORED and HTTP authentication remains enabled. Set VELLUM_UNSAFE_AUTH_BYPASS=1 to confirm the bypass.",
-      );
-    } else if (isHttpAuthDisabled()) {
-      log.warn(
-        "DISABLE_HTTP_AUTH is set — HTTP API authentication is DISABLED. All API endpoints are accessible without a bearer token. Do not use in production.",
-      );
+  /**
+   * Remove the runtime port file written by `writeRuntimePortFile`.
+   * Called from `stop()` on clean shutdown so a stale file does not
+   * point thin helpers (e.g. the chrome-extension native messaging
+   * helper) at a dead port until the next daemon start overwrites it.
+   * Best-effort — unlink failures never block shutdown.
+   *
+   * The unlink is conditional: we only remove the file if its current
+   * contents still match this server's port. The runtime-port file
+   * lives at the user-home level (`~/.vellum/runtime-port`) and is
+   * therefore shared across multiple daemon instances running on
+   * different `RUNTIME_HTTP_PORT`s. If a sibling instance has already
+   * rewritten the file with its own port, deleting it would strand
+   * thin helpers on the default port `7821` and break their ability
+   * to reach the still-running sibling.
+   *
+   * Note: this only runs on graceful shutdown. A crash leaves the
+   * file in place; the next successful startup overwrites it.
+   */
+  private removeRuntimePortFile(): void {
+    try {
+      const portFile = getRuntimePortFilePath();
+      if (!existsSync(portFile)) return;
+      // Read-then-compare-then-unlink. Race-safe enough: the worst case
+      // is that another instance writes the file between our read and
+      // our unlink, in which case we erroneously delete its mapping.
+      // That window is short (a few microseconds) and a sibling startup
+      // will rewrite the file on its next port-publish call. The much
+      // more common multi-instance race — sibling already overwrote
+      // before our stop() runs — is correctly handled here as a no-op.
+      const current = readFileSync(portFile, "utf-8").trim();
+      if (current !== String(this.actualPort)) {
+        log.info(
+          { portFile, current, actualPort: this.actualPort },
+          "Leaving runtime port file alone — owned by another instance",
+        );
+        return;
+      }
+      unlinkSync(portFile);
+      log.info({ portFile }, "Removed runtime port file");
+    } catch (err) {
+      log.warn({ err }, "Failed to remove runtime port file");
     }
-
-    log.info(
-      {
-        port: this.actualPort,
-        hostname: this.hostname,
-        auth: !!this.bearerToken,
-      },
-      "Runtime HTTP server listening",
-    );
   }
 
   async stop(): Promise<void> {
@@ -462,6 +720,7 @@ export class RuntimeHttpServer {
       this.server = null;
       log.info("Runtime HTTP server stopped");
     }
+    this.removeRuntimePortFile();
   }
 
   private async handleRequest(
@@ -532,6 +791,13 @@ export class RuntimeHttpServer {
       return handlePairingStatus(url, this.pairingContext);
     }
 
+    // Chrome extension capability-token pair endpoint — unauthenticated but
+    // restricted to loopback peers + an extension-id allowlist. Used by the
+    // native messaging helper to bootstrap a scoped token.
+    if (path === "/v1/browser-extension-pair") {
+      return await handleBrowserExtensionPair(req, server);
+    }
+
     // Guardian bootstrap and refresh endpoints — before JWT auth because
     // bootstrap is the first endpoint called to obtain a JWT, and refresh
     // needs to work when the access token is expired. Bootstrap has its
@@ -546,7 +812,19 @@ export class RuntimeHttpServer {
 
     // JWT bearer authentication — replaces the old shared-secret comparison.
     // authenticateRequest handles dev bypass (DISABLE_HTTP_AUTH) internally.
-    const authResult = authenticateRequest(req);
+    //
+    // Special-case: /v1/host-browser-result POST accepts either a
+    // daemon-minted JWT (legacy/cloud) or a host_browser capability
+    // token (self-hosted chrome extension). The chrome extension's
+    // HTTP fallback (`postHostBrowserResult`) hands over the same
+    // capability token it presented to `/v1/browser-relay`, so the
+    // POST route must understand both auth shapes. Every other route
+    // keeps the JWT-only flow via `authenticateRequest`.
+    const normalizedPath = path.endsWith("/") ? path.slice(0, -1) : path;
+    const authResult =
+      normalizedPath === "/v1/host-browser-result" && req.method === "POST"
+        ? authenticateHostBrowserResultRequest(req)
+        : authenticateRequest(req);
     if (!authResult.ok) {
       return authResult.response;
     }
@@ -634,15 +912,110 @@ export class RuntimeHttpServer {
       );
     }
 
+    // When auth is enabled we accept two different kinds of token on the
+    // `/v1/browser-relay` handshake:
+    //
+    //   1. **Capability token** — a signed `host_browser_command`
+    //      capability minted by `mintHostBrowserCapability()` and handed
+    //      to the chrome extension by the native-messaging pair flow
+    //      (`/v1/browser-extension-pair`). This is the preferred,
+    //      self-hosted default: the extension never has to touch a
+    //      gateway JWT.
+    //   2. **JWT** (audience `vellum-daemon`) — the legacy path used by
+    //      the gateway-proxied cloud flow and by any compatibility
+    //      callers that still hold a daemon-bound JWT. In that case we
+    //      parse the JWT `sub` to extract the actor principal id and
+    //      fall back to the explicit `x-guardian-id` / `guardianId`
+    //      query param for service-token paths (see below).
+    //
+    // When auth is disabled (dev bypass), guardianId remains undefined
+    // and the registration is skipped — host_browser_request routing
+    // requires an authenticated guardian.
+    //
+    // Gateway path: when the WebSocket upgrade is proxied through the
+    // gateway, the upstream token minted by `mintServiceToken()` has
+    // `sub=svc:gateway:self` with no actor principal id. The gateway
+    // parses the downstream edge token's `actorPrincipalId` and forwards
+    // it as an explicit `guardianId` query parameter (and/or header) so
+    // we can register the connection under the real guardian. Missing
+    // guardian context on this path is rejected (fail closed).
+    // Read the client-supplied stable instance id off the handshake.
+    // The extension generates this on first run and persists it in
+    // chrome.storage so it survives service-worker restarts and
+    // browser restarts. The header form is preferred so gateway
+    // forwarding and proxy logs don't surface instance ids in the
+    // URL, but we also accept a query param for fetch-based clients
+    // that can't mutate headers. An empty string is treated as absent
+    // so sparse clients don't end up all sharing the same legacy key.
+    const rawInstanceHeader = req.headers.get("x-client-instance-id")?.trim();
+    const rawInstanceQuery = new URL(req.url).searchParams
+      .get("clientInstanceId")
+      ?.trim();
+    const clientInstanceId =
+      (rawInstanceHeader ?? "") || (rawInstanceQuery ?? "") || undefined;
+
+    let guardianId: string | undefined;
     if (!isHttpAuthDisabled()) {
       const wsUrl = new URL(req.url);
       const token = wsUrl.searchParams.get("token");
       if (!token) {
         return httpError("UNAUTHORIZED", "Unauthorized", 401);
       }
-      const jwtResult = verifyToken(token, "vellum-daemon");
-      if (!jwtResult.ok) {
-        return httpError("UNAUTHORIZED", "Unauthorized", 401);
+      // 1) Capability-token path (self-hosted default). The chrome
+      //    extension presents the token it received from the native
+      //    messaging pair flow. We derive `guardianId` from the
+      //    capability claims directly — the claims are HMAC-signed by
+      //    the same daemon so there is no cross-tenant risk.
+      const capabilityClaims = verifyHostBrowserCapability(token);
+      if (capabilityClaims) {
+        guardianId = capabilityClaims.guardianId;
+      } else {
+        // 2) JWT compatibility path (gateway / legacy). Fall back to the
+        //    existing verifyToken+parseSub flow so cloud callers and any
+        //    old self-hosted clients still holding a daemon JWT
+        //    continue to work during the cutover.
+        const jwtResult = verifyToken(token, "vellum-daemon");
+        if (!jwtResult.ok) {
+          return httpError("UNAUTHORIZED", "Unauthorized", 401);
+        }
+        const subResult = parseSub(jwtResult.claims.sub);
+        if (subResult.ok && subResult.actorPrincipalId) {
+          // Direct actor principal — this is the loopback / desktop path.
+          guardianId = subResult.actorPrincipalId;
+        } else {
+          // Service-token path (gateway-forwarded). The gateway must plumb
+          // the resolved actor principal as an explicit `x-guardian-id`
+          // header or `guardianId` query param. Header takes precedence
+          // because headers are easier for the gateway to forward without
+          // rewriting the URL.
+          const headerGuardianId =
+            req.headers.get("x-guardian-id")?.trim() ?? "";
+          const queryGuardianId =
+            wsUrl.searchParams.get("guardianId")?.trim() ?? "";
+          const fallbackGuardianId = headerGuardianId || queryGuardianId;
+          if (fallbackGuardianId) {
+            guardianId = fallbackGuardianId;
+          } else {
+            // Fail closed: a service-token relay upgrade without a
+            // guardian context cannot be routed safely. Allowing the
+            // upgrade to proceed creates an unscoped socket that never
+            // registers in the ChromeExtensionRegistry.
+            log.warn(
+              {
+                principalType: subResult.ok
+                  ? subResult.principalType
+                  : "unknown",
+                sub: jwtResult.claims.sub,
+              },
+              "Browser relay upgrade denied: missing guardian context on service-token path",
+            );
+            return httpError(
+              "UNAUTHORIZED",
+              "Browser relay requires guardian context",
+              401,
+            );
+          }
+        }
       }
     }
 
@@ -651,6 +1024,8 @@ export class RuntimeHttpServer {
       data: {
         wsType: "browser-relay",
         connectionId,
+        guardianId,
+        clientInstanceId,
       } satisfies BrowserRelayWebSocketData,
     });
     if (!upgraded) {
@@ -833,6 +1208,7 @@ export class RuntimeHttpServer {
       lastMessageAt: conversation.lastMessageAt,
       conversationType: conversation.conversationType ?? "standard",
       source: conversation.source ?? "user",
+      hostAccess: conversation.hostAccess === 1,
       ...(conversation.scheduleJobId
         ? { scheduleJobId: conversation.scheduleJobId }
         : {}),
@@ -997,29 +1373,6 @@ export class RuntimeHttpServer {
       }),
       ...ttsRouteDefinitions(),
 
-      // Browser relay — not extracted into a domain module because
-      // these two routes depend on the in-process extensionRelayServer
-      // singleton which is only available here.
-      {
-        endpoint: "browser-relay/status",
-        method: "GET",
-        handler: () => Response.json(extensionRelayServer.getStatus()),
-      },
-      {
-        endpoint: "browser-relay/command",
-        method: "POST",
-        handler: async ({ req }) => {
-          const body = (await req.json()) as Record<string, unknown>;
-          const resp = await extensionRelayServer.sendCommand(
-            body as Omit<
-              import("../browser-extension-relay/protocol.js").ExtensionCommand,
-              "id"
-            >,
-          );
-          return Response.json(resp);
-        },
-      },
-
       // Conversation list and seen signal — kept inline because they
       // depend on multiple cross-cutting stores that aren't grouped
       // into a single domain module.
@@ -1209,6 +1562,8 @@ export class RuntimeHttpServer {
       ...globalSearchRouteDefinitions(),
       ...approvalRouteDefinitions(),
       ...hostBashRouteDefinitions(),
+      ...hostBrowserRouteDefinitions(),
+      ...browserCdpRouteDefinitions(),
       ...hostCuRouteDefinitions(),
       ...hostFileRouteDefinitions(),
       ...(this.getSkillContext