docs: document browser route support

steipete · steipete · commit a3af4263532d · 2026-06-04T07:31:50.000-04:00
diff --git a/extensions/browser/src/browser/routes/agent.ts b/extensions/browser/src/browser/routes/agent.ts
@@ -1,10 +1,17 @@
+/**
+ * Browser agent route group registration.
+ *
+ * Bundles snapshot, action, debug, and storage endpoints under the agent-facing
+ * browser control API.
+ */
 import type { BrowserRouteContext } from "../server-context.js";
 import { registerBrowserAgentActRoutes } from "./agent.act.js";
 import { registerBrowserAgentDebugRoutes } from "./agent.debug.js";
 import { registerBrowserAgentSnapshotRoutes } from "./agent.snapshot.js";
 import { registerBrowserAgentStorageRoutes } from "./agent.storage.js";
 import type { BrowserRouteRegistrar } from "./types.js";
 
+/** Register all agent-facing browser route groups. */
 export function registerBrowserAgentRoutes(app: BrowserRouteRegistrar, ctx: BrowserRouteContext) {
   registerBrowserAgentSnapshotRoutes(app, ctx);
   registerBrowserAgentActRoutes(app, ctx);
diff --git a/extensions/browser/src/browser/routes/basic.ts b/extensions/browser/src/browser/routes/basic.ts
@@ -1,3 +1,9 @@
+/**
+ * Basic browser control routes.
+ *
+ * Serves status, doctor, start/stop, profile management, and simple health
+ * endpoints for the browser control server.
+ */
 import { redactCdpUrl } from "../cdp.helpers.js";
 import { snapshotAria } from "../cdp.js";
 import { getChromeMcpPid, takeChromeMcpSnapshot } from "../chrome-mcp.js";
@@ -304,6 +310,7 @@ function parseHeadlessStartOverride(params: {
   return { ok: true, headless };
 }
 
+/** Register basic browser lifecycle, status, doctor, and profile endpoints. */
 export function registerBrowserBasicRoutes(app: BrowserRouteRegistrar, ctx: BrowserRouteContext) {
   // List all profiles with their status
   app.get(
diff --git a/extensions/browser/src/browser/routes/dispatcher.ts b/extensions/browser/src/browser/routes/dispatcher.ts
@@ -1,3 +1,9 @@
+/**
+ * Browser route dispatcher.
+ *
+ * Provides an in-process request/response adapter so Gateway nodes can invoke
+ * the same route handlers without opening an HTTP socket.
+ */
 import { escapeRegExp } from "../../utils.js";
 import type { BrowserRouteContext } from "../server-context.js";
 import { registerBrowserRoutes } from "./index.js";
@@ -59,6 +65,7 @@ function normalizePath(path: string) {
   return path.startsWith("/") ? path : `/${path}`;
 }
 
+/** Create an in-process dispatcher for registered browser routes. */
 export function createBrowserRouteDispatcher(ctx: BrowserRouteContext) {
   const registry = createRegistry();
   registerBrowserRoutes(registry.router, ctx);
diff --git a/extensions/browser/src/browser/routes/existing-session-limits.ts b/extensions/browser/src/browser/routes/existing-session-limits.ts
@@ -1,3 +1,10 @@
+/**
+ * Existing-session browser capability-limit messages.
+ *
+ * Centralizes unsupported-operation text so route responses and tests stay
+ * stable while Chrome MCP support grows incrementally.
+ */
+/** User-facing messages for existing-session route limitations. */
 export const EXISTING_SESSION_LIMITS = {
   act: {
     clickSelector: "existing-session click does not support selector targeting yet; use ref.",
diff --git a/extensions/browser/src/browser/routes/existing-session.test-support.ts b/extensions/browser/src/browser/routes/existing-session.test-support.ts
@@ -1,3 +1,9 @@
+/**
+ * Test support for existing-session browser route modules.
+ *
+ * Supplies mocked agent.shared helpers and mutable tab/profile state for route
+ * tests that exercise Chrome MCP branches without launching Chrome.
+ */
 import { vi } from "vitest";
 import {
   assertBrowserNavigationResultAllowed,
@@ -6,6 +12,7 @@ import {
 import type { BrowserRouteContext } from "../server-context.js";
 import type { BrowserRequest, BrowserResponse } from "./types.js";
 
+/** Mutable profile/tab state consumed by existing-session route mocks. */
 export const existingSessionRouteState = {
   profileCtx: {
     profile: {
@@ -29,6 +36,7 @@ export const existingSessionRouteState = {
   },
 };
 
+/** Create a vi mock module for routes that import agent.shared helpers. */
 export function createExistingSessionAgentSharedModule() {
   return {
     browserNavigationPolicyForProfile: vi.fn((ctx: BrowserRouteContext) =>
diff --git a/extensions/browser/src/browser/routes/index.ts b/extensions/browser/src/browser/routes/index.ts
@@ -1,10 +1,17 @@
+/**
+ * Browser control route root registration.
+ *
+ * Wires basic, tab, permission, and agent route groups onto the supplied HTTP
+ * or in-process route registrar.
+ */
 import type { BrowserRouteContext } from "../server-context.js";
 import { registerBrowserAgentRoutes } from "./agent.js";
 import { registerBrowserBasicRoutes } from "./basic.js";
 import { registerBrowserPermissionRoutes } from "./permissions.js";
 import { registerBrowserTabRoutes } from "./tabs.js";
 import type { BrowserRouteRegistrar } from "./types.js";
 
+/** Register every browser control route group. */
 export function registerBrowserRoutes(app: BrowserRouteRegistrar, ctx: BrowserRouteContext) {
   registerBrowserBasicRoutes(app, ctx);
   registerBrowserTabRoutes(app, ctx);
diff --git a/extensions/browser/src/browser/routes/output-paths.ts b/extensions/browser/src/browser/routes/output-paths.ts
@@ -1,11 +1,19 @@
+/**
+ * Browser route output-path helpers.
+ *
+ * Validates writable output paths against a route-specific root before any
+ * screenshot, trace, or download route writes to disk.
+ */
 import { ensureOutputDirectory } from "../output-directories.js";
 import { pathScope } from "./path-output.js";
 import type { BrowserResponse } from "./types.js";
 
+/** Ensure a browser output root exists before resolving child write paths. */
 export async function ensureOutputRootDir(rootDir: string): Promise<void> {
   await ensureOutputDirectory(rootDir);
 }
 
+/** Resolve a writable output path or send a 400 JSON response on scope errors. */
 export async function resolveWritableOutputPathOrRespond(params: {
   res: BrowserResponse;
   rootDir: string;
diff --git a/extensions/browser/src/browser/routes/path-output.ts b/extensions/browser/src/browser/routes/path-output.ts
@@ -1,3 +1,9 @@
+/**
+ * Browser route output-path barrel.
+ *
+ * Re-exports the path scope and default media directories used by route modules
+ * without exposing the broader browser paths implementation at each call site.
+ */
 export {
   DEFAULT_DOWNLOAD_DIR,
   DEFAULT_TRACE_DIR,
diff --git a/extensions/browser/src/browser/routes/permissions.ts b/extensions/browser/src/browser/routes/permissions.ts
@@ -1,3 +1,9 @@
+/**
+ * Browser permission routes.
+ *
+ * Grants required and optional browser permissions for an origin, preferring
+ * Playwright context APIs when available and falling back to raw CDP.
+ */
 import { uniqueStrings } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { formatErrorMessage } from "../../infra/errors.js";
 import type { SsrFPolicy } from "../../infra/net/ssrf.js";
@@ -14,6 +20,7 @@ const permissionRouteDeps = {
   getPwAiModule,
 };
 
+/** Test hook for replacing optional Playwright permission dependencies. */
 export const testing = {
   setDepsForTest(deps: { getPwAiModule?: typeof getPwAiModule } | null) {
     permissionRouteDeps.getPwAiModule = deps?.getPwAiModule ?? getPwAiModule;
@@ -138,6 +145,7 @@ function toPlaywrightPermission(permission: string): string | undefined {
   }
 }
 
+/** Register permission grant endpoints on the browser control server. */
 export function registerBrowserPermissionRoutes(
   app: BrowserRouteRegistrar,
   ctx: BrowserRouteContext,
diff --git a/extensions/browser/src/browser/routes/route-numeric.ts b/extensions/browser/src/browser/routes/route-numeric.ts
@@ -1,3 +1,9 @@
+/**
+ * Strict numeric parsers for browser route input.
+ *
+ * Converts query/body values into finite integer/timeout numbers while
+ * preserving route-specific error messages for JSON responses.
+ */
 import {
   parseStrictFiniteNumber,
   parseStrictInteger,
@@ -10,6 +16,7 @@ function hasRouteInputValue(value: unknown): boolean {
   return value != null;
 }
 
+/** Read an optional finite number route field. */
 export function readRouteFiniteNumber(value: unknown, fieldName: string): number | undefined {
   const parsed = parseStrictFiniteNumber(value);
   if (parsed === undefined && hasRouteInputValue(value)) {
@@ -18,6 +25,7 @@ export function readRouteFiniteNumber(value: unknown, fieldName: string): number
   return parsed;
 }
 
+/** Read an optional finite number, treating blank strings as absent. */
 export function readOptionalRouteFiniteNumber(
   value: unknown,
   fieldName: string,
@@ -28,6 +36,7 @@ export function readOptionalRouteFiniteNumber(
   return readRouteFiniteNumber(value, fieldName);
 }
 
+/** Read an optional integer route field. */
 export function readRouteInteger(
   value: unknown,
   fieldName: string,
@@ -40,6 +49,7 @@ export function readRouteInteger(
   return parsed;
 }
 
+/** Read an optional positive integer route field. */
 export function readRoutePositiveInteger(
   value: unknown,
   fieldName: string,
@@ -52,6 +62,7 @@ export function readRoutePositiveInteger(
   return parsed;
 }
 
+/** Read and normalize an optional positive timeout value. */
 export function readRouteTimerTimeoutMs(
   value: unknown,
   fieldName = "timeoutMs",
@@ -61,6 +72,7 @@ export function readRouteTimerTimeoutMs(
   return parsed === undefined ? undefined : normalizeBrowserTimerDelayMs(parsed, opts);
 }
 
+/** Read an optional non-negative integer route field. */
 export function readRouteNonNegativeInteger(
   value: unknown,
   fieldName: string,
diff --git a/extensions/browser/src/browser/routes/tabs.ts b/extensions/browser/src/browser/routes/tabs.ts
@@ -1,3 +1,9 @@
+/**
+ * Browser tab management routes.
+ *
+ * Lists, opens, focuses, closes, and mutates tabs while applying navigation
+ * policy checks and profile reachability probes.
+ */
 import { clampPositiveTimerTimeoutMs } from "openclaw/plugin-sdk/number-runtime";
 import {
   BrowserProfileUnavailableError,
@@ -191,6 +197,7 @@ async function runTabTargetMutation(params: {
   });
 }
 
+/** Register tab listing and mutation endpoints on the browser control server. */
 export function registerBrowserTabRoutes(app: BrowserRouteRegistrar, ctx: BrowserRouteContext) {
   app.get(
     "/tabs",
diff --git a/extensions/browser/src/browser/routes/test-helpers.ts b/extensions/browser/src/browser/routes/test-helpers.ts
@@ -1,5 +1,12 @@
+/**
+ * Lightweight browser route test helpers.
+ *
+ * Provides an in-memory route registrar and response object for focused route
+ * unit tests without standing up the HTTP server.
+ */
 import type { BrowserResponse, BrowserRouteHandler, BrowserRouteRegistrar } from "./types.js";
 
+/** Create an in-memory route app that records handlers by method and path. */
 export function createBrowserRouteApp() {
   const getHandlers = new Map<string, BrowserRouteHandler>();
   const postHandlers = new Map<string, BrowserRouteHandler>();
@@ -12,6 +19,7 @@ export function createBrowserRouteApp() {
   return { app, getHandlers, postHandlers, deleteHandlers };
 }
 
+/** Create a minimal response object that captures status and JSON body. */
 export function createBrowserRouteResponse() {
   let statusCode = 200;
   let jsonBody: unknown;
diff --git a/extensions/browser/src/browser/routes/types.ts b/extensions/browser/src/browser/routes/types.ts
@@ -1,3 +1,10 @@
+/**
+ * Minimal browser route HTTP types.
+ *
+ * Keeps route modules decoupled from Express-specific request/response types so
+ * the same handlers can run through HTTP and in-process dispatch.
+ */
+/** Request shape consumed by browser route handlers. */
 export type BrowserRequest = {
   params: Record<string, string>;
   query: Record<string, unknown>;
@@ -9,16 +16,19 @@ export type BrowserRequest = {
   signal?: AbortSignal;
 };
 
+/** Response shape used by browser route handlers. */
 export type BrowserResponse = {
   status: (code: number) => BrowserResponse;
   json: (body: unknown) => void;
 };
 
+/** Async route handler signature shared by HTTP and in-process dispatch. */
 export type BrowserRouteHandler = (
   req: BrowserRequest,
   res: BrowserResponse,
 ) => void | Promise<void>;
 
+/** Minimal registrar interface implemented by HTTP and test dispatchers. */
 export type BrowserRouteRegistrar = {
   get: (path: string, handler: BrowserRouteHandler) => void;
   post: (path: string, handler: BrowserRouteHandler) => void;
diff --git a/extensions/browser/src/browser/routes/utils.ts b/extensions/browser/src/browser/routes/utils.ts
@@ -1,10 +1,17 @@
+/**
+ * Browser route utility functions.
+ *
+ * Wraps async handlers, profile lookup, JSON errors, and route value coercion
+ * shared across browser control endpoints.
+ */
 import type { BrowserRouteContext, ProfileContext } from "../server-context.js";
 import type { BrowserRequest, BrowserResponse, BrowserRouteHandler } from "./types.js";
 
 function normalizeOptionalString(value: string): string | undefined {
   return value.trim() || undefined;
 }
 
+/** Convert thrown async route errors into next(error) calls for the HTTP layer. */
 export function asyncBrowserRoute(handler: BrowserRouteHandler): BrowserRouteHandler {
   return (req, res) => handler(req, res);
 }
@@ -13,6 +20,7 @@ export function asyncBrowserRoute(handler: BrowserRouteHandler): BrowserRouteHan
  * Extract profile name from query string or body and get profile context.
  * Query string takes precedence over body for consistency with GET routes.
  */
+/** Resolve the profile context requested by query/profile parameters. */
 export function getProfileContext(
   req: BrowserRequest,
   ctx: BrowserRouteContext,
@@ -39,17 +47,20 @@ export function getProfileContext(
   }
 }
 
+/** Send a simple JSON error response. */
 export function jsonError(res: BrowserResponse, status: number, message: string) {
   res.status(status).json({ error: message });
 }
 
+/** Coerce route values to strings while treating nullish values as empty. */
 export function toStringOrEmpty(value: unknown) {
   if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
     return normalizeOptionalString(String(value)) ?? "";
   }
   return "";
 }
 
+/** Coerce route numeric values from numbers or decimal strings. */
 export function toNumber(value: unknown) {
   if (typeof value === "number" && Number.isFinite(value)) {
     return value;
@@ -62,6 +73,7 @@ export function toNumber(value: unknown) {
   return undefined;
 }
 
+/** Coerce route boolean values from booleans or common string forms. */
 export function toBoolean(value: unknown) {
   if (typeof value === "boolean") {
     return value;
@@ -79,6 +91,7 @@ export function toBoolean(value: unknown) {
   return undefined;
 }
 
+/** Coerce a route value to a string array when every entry is a string. */
 export function toStringArray(value: unknown): string[] | undefined {
   if (!Array.isArray(value)) {
     return undefined;
