docs: document browser server context

steipete · steipete · commit 5ab430fa11ee · 2026-06-04T07:53:45.000-04:00
diff --git a/extensions/browser/src/browser/server-context.availability.ts b/extensions/browser/src/browser/server-context.availability.ts
@@ -1,3 +1,7 @@
+/**
+ * Browser profile availability operations: reachability probes, managed Chrome
+ * launch/restart, Chrome MCP attach, and profile stop handling.
+ */
 import fs from "node:fs";
 import { resolveCdpReachabilityPolicy } from "./cdp-reachability-policy.js";
 import {
@@ -133,6 +137,7 @@ function assertManagedLaunchNotCoolingDown(profileName: string, profileState: Pr
   );
 }
 
+/** Builds reachability, ensure, and stop operations for one resolved browser profile. */
 export function createProfileAvailability({
   opts,
   profile,
diff --git a/extensions/browser/src/browser/server-context.chrome-test-harness.ts b/extensions/browser/src/browser/server-context.chrome-test-harness.ts
@@ -1,3 +1,6 @@
+/**
+ * Shared Chrome module mocks for Browser server-context tests.
+ */
 import { vi } from "vitest";
 import { installChromeUserDataDirHooks } from "./chrome-user-data-dir.test-harness.js";
 
diff --git a/extensions/browser/src/browser/server-context.constants.ts b/extensions/browser/src/browser/server-context.constants.ts
@@ -1,5 +1,9 @@
+/**
+ * Timing and size constants for Browser profile/tab runtime operations.
+ */
 import { DEFAULT_BROWSER_LOCAL_CDP_READY_TIMEOUT_MS } from "./constants.js";
 
+/** Maximum managed page tabs kept open before best-effort cleanup starts. */
 export const MANAGED_BROWSER_PAGE_TAB_LIMIT = 8;
 
 export const OPEN_TAB_DISCOVERY_WINDOW_MS = 2000;
diff --git a/extensions/browser/src/browser/server-context.lifecycle.ts b/extensions/browser/src/browser/server-context.lifecycle.ts
@@ -1,7 +1,12 @@
+/**
+ * Browser profile lifecycle helpers shared by availability, reset, and runtime
+ * teardown.
+ */
 import type { ResolvedBrowserProfile } from "./config.js";
 import { getBrowserProfileCapabilities } from "./profile-capabilities.js";
 import { getPwAiModule } from "./pw-ai-module.js";
 
+/** Resolves how an idle stop should behave for local, remote, or attach-only profiles. */
 export function resolveIdleProfileStopOutcome(profile: ResolvedBrowserProfile): {
   stopped: boolean;
   closePlaywright: boolean;
@@ -19,6 +24,7 @@ export function resolveIdleProfileStopOutcome(profile: ResolvedBrowserProfile):
   };
 }
 
+/** Closes cached Playwright CDP connections for one profile without requiring the module. */
 export async function closePlaywrightBrowserConnectionForProfile(cdpUrl?: string): Promise<void> {
   try {
     const mod = await getPwAiModule({ mode: "soft" });
diff --git a/extensions/browser/src/browser/server-context.remote-profile-tab-ops.test-helpers.ts b/extensions/browser/src/browser/server-context.remote-profile-tab-ops.test-helpers.ts
@@ -1,5 +1,9 @@
+/**
+ * Lazy-loaded dependency bundle for remote-profile tab operation tests.
+ */
 import { afterEach, beforeEach, vi } from "vitest";
 
+/** Modules and helpers shared by remote-profile tab operation tests. */
 export type RemoteProfileTestDeps = {
   cdpModule: typeof import("./cdp.js");
   chromeModule: typeof import("./chrome.js");
@@ -16,6 +20,7 @@ export type RemoteProfileTestDeps = {
 
 let remoteProfileTestDepsPromise: Promise<RemoteProfileTestDeps> | undefined;
 
+/** Loads remote-profile tab operation dependencies after Chrome mocks are installed. */
 export async function loadRemoteProfileTestDeps(): Promise<RemoteProfileTestDeps> {
   remoteProfileTestDepsPromise ??= (async () => {
     await import("./server-context.chrome-test-harness.js");
@@ -49,6 +54,7 @@ export async function loadRemoteProfileTestDeps(): Promise<RemoteProfileTestDeps
   return await remoteProfileTestDepsPromise;
 }
 
+/** Installs per-test mock reset and Playwright connection cleanup. */
 export function installRemoteProfileTestLifecycle(deps: RemoteProfileTestDeps): void {
   beforeEach(() => {
     vi.clearAllMocks();
diff --git a/extensions/browser/src/browser/server-context.remote-tab-ops.harness.ts b/extensions/browser/src/browser/server-context.remote-tab-ops.harness.ts
@@ -1,3 +1,6 @@
+/**
+ * Remote-tab operation harness for Browser server-context tests.
+ */
 import { vi } from "vitest";
 import { withBrowserFetchPreconnect } from "../../test-fetch.js";
 import { resolveCdpControlPolicy } from "./cdp-reachability-policy.js";
@@ -6,8 +9,10 @@ import { createProfileSelectionOps } from "./server-context.selection.js";
 import { createProfileTabOps } from "./server-context.tab-ops.js";
 import type { BrowserServerState, ProfileRuntimeState } from "./server-context.types.js";
 
+/** Original global fetch restored between remote-tab harness tests. */
 export const originalFetch = globalThis.fetch;
 
+/** Creates Browser server state for remote or local profile tab tests. */
 export function makeState(
   profile: "remote" | "openclaw",
 ): BrowserServerState & { profiles: Map<string, { lastTargetId?: string | null }> } {
@@ -95,6 +100,7 @@ function resolveProfileForTest(
   };
 }
 
+/** Creates a minimal Browser route context for profile operation tests. */
 export function createTestBrowserRouteContext(opts: { getState: () => BrowserServerState }) {
   const forProfile = (profileName?: string) => {
     const state = opts.getState();
@@ -125,6 +131,7 @@ export function createTestBrowserRouteContext(opts: { getState: () => BrowserSer
   return { forProfile };
 }
 
+/** Creates a remote profile context with a preconnected fetch mock. */
 export function createRemoteRouteHarness(fetchMock?: (url: unknown) => Promise<Response>) {
   const activeFetchMock = fetchMock ?? makeUnexpectedFetchMock();
   global.fetch = withBrowserFetchPreconnect(activeFetchMock);
@@ -133,6 +140,7 @@ export function createRemoteRouteHarness(fetchMock?: (url: unknown) => Promise<R
   return { state, remote: ctx.forProfile("remote"), fetchMock: activeFetchMock };
 }
 
+/** Returns a page lister that yields prepared responses in order. */
 export function createSequentialPageLister<T>(responses: T[]) {
   return async () => {
     const next = responses.shift();
@@ -151,6 +159,7 @@ type JsonListEntry = {
   type: "page";
 };
 
+/** Creates a /json/list fetch mock with static entries. */
 export function createJsonListFetchMock(entries: JsonListEntry[]) {
   return async (url: unknown) => {
     const u = String(url);
@@ -174,6 +183,7 @@ function makeManagedTab(id: string, ordinal: number): JsonListEntry {
   };
 }
 
+/** Creates eight old managed tabs plus one new tab for cleanup-limit tests. */
 export function makeManagedTabsWithNew(params?: { newFirst?: boolean }): JsonListEntry[] {
   const oldTabs = Array.from({ length: 8 }, (_, index) =>
     makeManagedTab(`OLD${index + 1}`, index + 1),
diff --git a/extensions/browser/src/browser/server-context.reset.ts b/extensions/browser/src/browser/server-context.reset.ts
@@ -1,3 +1,6 @@
+/**
+ * Browser profile reset operations for local managed profiles.
+ */
 import fs from "node:fs";
 import type { ResolvedBrowserProfile } from "./config.js";
 import { BrowserResetUnsupportedError } from "./errors.js";
@@ -18,6 +21,7 @@ type ResetOps = {
   resetProfile: () => Promise<{ moved: boolean; from: string; to?: string }>;
 };
 
+/** Builds the reset-profile operation for one resolved browser profile. */
 export function createProfileResetOps({
   profile,
   getProfileState,
diff --git a/extensions/browser/src/browser/server-context.selection.ts b/extensions/browser/src/browser/server-context.selection.ts
@@ -1,3 +1,6 @@
+/**
+ * Browser tab selection operations for default tab choice, focus, and close.
+ */
 import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
 import type { SsrFPolicy } from "../infra/net/ssrf.js";
 import { fetchOk, normalizeCdpHttpBaseForJsonEndpoints } from "./cdp.helpers.js";
@@ -26,6 +29,7 @@ type SelectionOps = {
   closeTab: (targetId: string) => Promise<void>;
 };
 
+/** Builds tab selection/focus/close operations for one resolved browser profile. */
 export function createProfileSelectionOps({
   profile,
   getProfileState,
diff --git a/extensions/browser/src/browser/server-context.tab-ops.ts b/extensions/browser/src/browser/server-context.tab-ops.ts
@@ -1,3 +1,6 @@
+/**
+ * Browser tab listing, opening, labeling, and alias management for one profile.
+ */
 import { resolveBrowserNavigationProxyMode } from "./browser-proxy-mode.js";
 import { resolveCdpControlPolicy } from "./cdp-reachability-policy.js";
 import { isSelectableCdpBrowserTarget } from "./cdp-target-filter.js";
@@ -170,6 +173,7 @@ function assignTabAliases(profileState: ProfileRuntimeState, tabs: BrowserTab[])
   return tabs.map((tab) => assignTabAlias({ profileState, tab }));
 }
 
+/** Builds list/open/label tab operations for one resolved browser profile. */
 export function createProfileTabOps({
   profile,
   state,
diff --git a/extensions/browser/src/browser/server-context.test-harness.ts b/extensions/browser/src/browser/server-context.test-harness.ts
@@ -1,9 +1,13 @@
+/**
+ * Test factories for Browser profile/runtime state and launched Chrome mocks.
+ */
 import type { ChildProcessWithoutNullStreams } from "node:child_process";
 import { EventEmitter } from "node:events";
 import type { RunningChrome } from "./chrome.js";
 import type { ResolvedBrowserProfile } from "./config.js";
 import type { BrowserServerState } from "./server-context.js";
 
+/** Creates a resolved Browser profile for unit tests. */
 export function makeBrowserProfile(
   overrides: Partial<ResolvedBrowserProfile> = {},
 ): ResolvedBrowserProfile {
@@ -21,6 +25,7 @@ export function makeBrowserProfile(
   };
 }
 
+/** Creates Browser server state around a test profile. */
 export function makeBrowserServerState(params?: {
   profile?: ResolvedBrowserProfile;
   resolvedOverrides?: Partial<BrowserServerState["resolved"]>;
@@ -69,6 +74,7 @@ export function makeBrowserServerState(params?: {
   };
 }
 
+/** Mocks a launched OpenClaw Chrome process with the supplied pid. */
 export function mockLaunchedChrome(
   launchOpenClawChrome: { mockResolvedValue: (value: RunningChrome) => unknown },
   pid: number,
diff --git a/extensions/browser/src/browser/server-context.ts b/extensions/browser/src/browser/server-context.ts
@@ -1,3 +1,7 @@
+/**
+ * Browser route context factory that wires profile-scoped runtime operations for
+ * the Browser control server.
+ */
 import {
   resolveCdpControlPolicy,
   resolveCdpReachabilityPolicy,
@@ -37,6 +41,7 @@ export type {
   ProfileStatus,
 } from "./server-context.types.js";
 
+/** Lists configured and runtime-known Browser profile names without duplicates. */
 export function listKnownProfileNames(state: BrowserServerState): string[] {
   const names = new Set(Object.keys(state.resolved.profiles));
   for (const name of state.profiles.keys()) {
@@ -129,6 +134,7 @@ function createProfileContext(
   };
 }
 
+/** Creates the Browser route context used by control-server route handlers. */
 export function createBrowserRouteContext(opts: ContextOptions): BrowserRouteContext {
   const refreshConfigFromDisk = opts.refreshConfigFromDisk === true;
 
diff --git a/extensions/browser/src/browser/server-context.types.ts b/extensions/browser/src/browser/server-context.types.ts
@@ -1,13 +1,15 @@
+/**
+ * Shared Browser server context types used by route handlers and profile
+ * operation factories.
+ */
 import type { Server } from "node:http";
 import type { RunningChrome } from "./chrome.js";
 import type { BrowserTab, BrowserTransport } from "./client.types.js";
 import type { ResolvedBrowserConfig, ResolvedBrowserProfile } from "./config.js";
 
 export type { BrowserTab };
 
-/**
- * Runtime state for a single profile's Chrome instance.
- */
+/** Runtime state for a single profile's Chrome instance. */
 export type ProfileRuntimeState = {
   profile: ResolvedBrowserProfile;
   running: RunningChrome | null;
@@ -31,6 +33,7 @@ export type ProfileRuntimeState = {
   } | null;
 };
 
+/** Runtime state for the Browser control server. */
 export type BrowserServerState = {
   server?: Server | null;
   port: number;
@@ -58,6 +61,7 @@ type BrowserProfileActions = {
   resetProfile: () => Promise<{ moved: boolean; from: string; to?: string }>;
 };
 
+/** Profile-aware operations exposed to Browser route handlers. */
 export type BrowserRouteContext = {
   state: () => BrowserServerState;
   forProfile: (profileName?: string) => ProfileContext;
@@ -66,10 +70,12 @@ export type BrowserRouteContext = {
   mapTabError: (err: unknown) => { status: number; message: string } | null;
 } & BrowserProfileActions;
 
+/** Operations scoped to a single resolved Browser profile. */
 export type ProfileContext = {
   profile: ResolvedBrowserProfile;
 } & BrowserProfileActions;
 
+/** Status payload returned by Browser profile listing. */
 export type ProfileStatus = {
   name: string;
   transport: BrowserTransport;
@@ -85,6 +91,7 @@ export type ProfileStatus = {
   reconcileReason?: string | null;
 };
 
+/** Inputs for creating a Browser route context. */
 export type ContextOptions = {
   getState: () => BrowserServerState | null;
   onEnsureAttachTarget?: (profile: ResolvedBrowserProfile) => Promise<void>;
diff --git a/extensions/browser/src/browser/server-lifecycle.ts b/extensions/browser/src/browser/server-lifecycle.ts
@@ -1,3 +1,6 @@
+/**
+ * Browser server lifecycle helpers for relay setup and profile shutdown.
+ */
 import { stopOpenClawChrome } from "./chrome.js";
 import type { ResolvedBrowserConfig } from "./config.js";
 import {
@@ -6,6 +9,7 @@ import {
   listKnownProfileNames,
 } from "./server-context.js";
 
+/** Ensures extension relay compatibility hooks for configured profiles. */
 export async function ensureExtensionRelayForProfiles(_params: {
   resolved: ResolvedBrowserConfig;
   onWarn: (message: string) => void;
@@ -15,6 +19,7 @@ export async function ensureExtensionRelayForProfiles(_params: {
   // breaking cleanup rather than changing the call graph in a patch release.
 }
 
+/** Stops every known Browser profile during runtime shutdown. */
 export async function stopKnownBrowserProfiles(params: {
   getState: () => BrowserServerState | null;
   onWarn: (message: string) => void;
diff --git a/extensions/browser/src/browser/server-middleware.ts b/extensions/browser/src/browser/server-middleware.ts
@@ -1,3 +1,7 @@
+/**
+ * Shared Express middleware for Browser control routes, including auth marking,
+ * JSON parsing, abort signals, and mutation CSRF checks.
+ */
 import type { Express, Request } from "express";
 import express from "express";
 import { browserMutationGuardMiddleware } from "./csrf.js";
@@ -9,6 +13,7 @@ type BrowserAuthMarkedRequest = Request & {
   [BROWSER_AUTH_VERIFIED_FLAG]?: boolean;
 };
 
+/** Returns whether Browser auth middleware already verified this request. */
 export function hasVerifiedBrowserAuth(req: Request): boolean {
   return (req as BrowserAuthMarkedRequest)[BROWSER_AUTH_VERIFIED_FLAG] === true;
 }
@@ -17,6 +22,7 @@ function markVerifiedBrowserAuth(req: Request) {
   (req as BrowserAuthMarkedRequest)[BROWSER_AUTH_VERIFIED_FLAG] = true;
 }
 
+/** Installs common Browser control-server middleware. */
 export function installBrowserCommonMiddleware(app: Express) {
   app.use((req, res, next) => {
     const ctrl = new AbortController();
@@ -42,6 +48,7 @@ export function installBrowserCommonMiddleware(app: Express) {
   app.use(browserMutationGuardMiddleware());
 }
 
+/** Installs optional token/password auth for Browser control-server requests. */
 export function installBrowserAuthMiddleware(
   app: Express,
   auth: { token?: string; password?: string },
diff --git a/extensions/browser/src/browser/server.agent-contract.test-harness.ts b/extensions/browser/src/browser/server.agent-contract.test-harness.ts
@@ -1,10 +1,15 @@
+/**
+ * Agent-contract test harness for starting the Browser control server and
+ * posting JSON through a real fetch implementation.
+ */
 import {
   getBrowserControlServerBaseUrl,
   installBrowserControlServerHooks,
   startBrowserControlServerFromConfig,
 } from "./server.control-server.test-harness.js";
 import { getBrowserTestFetch } from "./test-support/fetch.js";
 
+/** Installs Browser control-server hooks for agent-contract tests. */
 export function installAgentContractHooks() {
   installBrowserControlServerHooks();
 }
@@ -50,6 +55,7 @@ async function postStartWithRetry(params: {
   throw lastError;
 }
 
+/** Starts the Browser control server and returns its base URL. */
 export async function startServerAndBase(): Promise<string> {
   await startBrowserControlServerFromConfig();
   const base = getBrowserControlServerBaseUrl();
@@ -58,6 +64,7 @@ export async function startServerAndBase(): Promise<string> {
   return base;
 }
 
+/** Posts JSON to a Browser control-server route and parses the JSON response. */
 export async function postJson<T>(url: string, body?: unknown): Promise<T> {
   const realFetch = getBrowserTestFetch();
   const res = await realFetch(url, {
diff --git a/extensions/browser/src/browser/server.control-server.test-harness.ts b/extensions/browser/src/browser/server.control-server.test-harness.ts
diff --git a/extensions/browser/src/browser/session-tab-cleanup.ts b/extensions/browser/src/browser/session-tab-cleanup.ts
diff --git a/extensions/browser/src/browser/session-tab-registry.ts b/extensions/browser/src/browser/session-tab-registry.ts
