From 3dcdfee1e19038c2d0122fc74ebf50c0b612cd5b Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 07:37:59 -0400
Subject: [PATCH] docs: document browser client APIs

---
 .../src/browser/client-actions-core.ts        | 11 ++++++++
 .../src/browser/client-actions-observe.ts     |  8 ++++++
 .../src/browser/client-actions-types.ts       |  6 +++++
 .../browser/src/browser/client-actions-url.ts |  5 ++++
 .../browser/src/browser/client-actions.ts     |  5 ++++
 .../src/browser/client-actions.types.ts       |  8 ++++++
 .../browser/src/browser/client-fetch.ts       |  8 ++++++
 extensions/browser/src/browser/client.ts      | 25 +++++++++++++++++++
 .../browser/src/browser/client.types.ts       |  9 +++++++
 9 files changed, 85 insertions(+)

diff --git a/extensions/browser/src/browser/client-actions-core.ts b/extensions/browser/src/browser/client-actions-core.ts
index a1f507aa21f4..85d6433faad2 100644
--- a/extensions/browser/src/browser/client-actions-core.ts
+++ b/extensions/browser/src/browser/client-actions-core.ts
@@ -1,3 +1,9 @@
+/**
+ * Browser client action helpers.
+ *
+ * Wraps browser-control action endpoints for navigation, dialog/file hooks,
+ * screenshots, and element actions used by the Browser agent tool.
+ */
 import {
   addTimerTimeoutGraceMs,
   clampPositiveTimerTimeoutMs,
@@ -51,6 +57,7 @@ function resolveBrowserActRequestTimeoutMs(req: BrowserActRequest): number {
   return Math.max(...candidateTimeouts);
 }
 
+/** Navigate a browser tab through the control server. */
 export async function browserNavigate(
   baseUrl: string | undefined,
   opts: {
@@ -68,6 +75,7 @@ export async function browserNavigate(
   });
 }
 
+/** Arm a one-shot browser dialog handler. */
 export async function browserArmDialog(
   baseUrl: string | undefined,
   opts: {
@@ -94,6 +102,7 @@ export async function browserArmDialog(
   });
 }
 
+/** Arm or execute a browser file chooser upload. */
 export async function browserArmFileChooser(
   baseUrl: string | undefined,
   opts: {
@@ -122,6 +131,7 @@ export async function browserArmFileChooser(
   });
 }
 
+/** Execute one normalized browser action request. */
 export async function browserAct(
   baseUrl: string | undefined,
   req: BrowserActRequest,
@@ -136,6 +146,7 @@ export async function browserAct(
   });
 }
 
+/** Capture a screenshot through the browser control server. */
 export async function browserScreenshotAction(
   baseUrl: string | undefined,
   opts: {
diff --git a/extensions/browser/src/browser/client-actions-observe.ts b/extensions/browser/src/browser/client-actions-observe.ts
index 6dba12dbfe5b..48d965643b9e 100644
--- a/extensions/browser/src/browser/client-actions-observe.ts
+++ b/extensions/browser/src/browser/client-actions-observe.ts
@@ -1,3 +1,9 @@
+/**
+ * Browser client observation helpers.
+ *
+ * Wraps browser-control endpoints that read console/debug data or save page
+ * output without directly mutating page state.
+ */
 import type { BrowserActionPathResult } from "./client-actions-types.js";
 import { buildProfileQuery, withBaseUrl } from "./client-actions-url.js";
 import { fetchBrowserJson } from "./client-fetch.js";
@@ -18,6 +24,7 @@ function buildQuerySuffix(params: Array<[string, string | boolean | undefined]>)
   return encoded.length > 0 ? `?${encoded}` : "";
 }
 
+/** Read browser console messages for a tab. */
 export async function browserConsoleMessages(
   baseUrl: string | undefined,
   opts: { level?: string; targetId?: string; profile?: string } = {},
@@ -35,6 +42,7 @@ export async function browserConsoleMessages(
   }>(withBaseUrl(baseUrl, `/console${suffix}`), { timeoutMs: 20000 });
 }
 
+/** Save the current page as PDF through browser control. */
 export async function browserPdfSave(
   baseUrl: string | undefined,
   opts: { targetId?: string; profile?: string } = {},
diff --git a/extensions/browser/src/browser/client-actions-types.ts b/extensions/browser/src/browser/client-actions-types.ts
index a45b76b7cc3b..37142b4aebf3 100644
--- a/extensions/browser/src/browser/client-actions-types.ts
+++ b/extensions/browser/src/browser/client-actions-types.ts
@@ -1,11 +1,17 @@
+/**
+ * Shared result types for browser client action helpers.
+ */
+/** Generic success result for action endpoints. */
 export type BrowserActionOk = { ok: true };
 
+/** Success result carrying the affected tab and optional URL. */
 export type BrowserActionTabResult = {
   ok: true;
   targetId: string;
   url?: string;
 };
 
+/** Success result carrying a filesystem output path. */
 export type BrowserActionPathResult = {
   ok: true;
   path: string;
diff --git a/extensions/browser/src/browser/client-actions-url.ts b/extensions/browser/src/browser/client-actions-url.ts
index 25c47fa6dba4..d6b1eaa9d3ba 100644
--- a/extensions/browser/src/browser/client-actions-url.ts
+++ b/extensions/browser/src/browser/client-actions-url.ts
@@ -1,7 +1,12 @@
+/**
+ * URL helpers for browser client action requests.
+ */
+/** Build a query string for profile-scoped browser requests. */
 export function buildProfileQuery(profile?: string): string {
   return profile ? `?profile=${encodeURIComponent(profile)}` : "";
 }
 
+/** Prefix a browser-control path with an optional base URL. */
 export function withBaseUrl(baseUrl: string | undefined, path: string): string {
   const trimmed = baseUrl?.trim();
   if (!trimmed) {
diff --git a/extensions/browser/src/browser/client-actions.ts b/extensions/browser/src/browser/client-actions.ts
index 9b1ff638d25e..796eb84f0dc7 100644
--- a/extensions/browser/src/browser/client-actions.ts
+++ b/extensions/browser/src/browser/client-actions.ts
@@ -1,3 +1,8 @@
+/**
+ * Public browser action client barrel.
+ *
+ * Re-exports the action helpers used by Browser tool registration and tests.
+ */
 export {
   browserAct,
   browserArmDialog,
diff --git a/extensions/browser/src/browser/client-actions.types.ts b/extensions/browser/src/browser/client-actions.types.ts
index b4aa244a28d2..aba943e02dcd 100644
--- a/extensions/browser/src/browser/client-actions.types.ts
+++ b/extensions/browser/src/browser/client-actions.types.ts
@@ -1,9 +1,17 @@
+/**
+ * Browser action request types.
+ *
+ * Defines the closed action union accepted by browser-control `/act` routes and
+ * reused by the Browser agent tool.
+ */
+/** Form field descriptor used by fill actions. */
 export type BrowserFormField = {
   ref: string;
   type: string;
   value?: string | number | boolean;
 };
 
+/** Normalized browser action request sent to the control server. */
 export type BrowserActRequest =
   | {
       kind: "click";
diff --git a/extensions/browser/src/browser/client-fetch.ts b/extensions/browser/src/browser/client-fetch.ts
index 9cfd803b1027..82f6d1625158 100644
--- a/extensions/browser/src/browser/client-fetch.ts
+++ b/extensions/browser/src/browser/client-fetch.ts
@@ -1,3 +1,9 @@
+/**
+ * Browser control client transport.
+ *
+ * Sends requests to either an absolute HTTP browser-control URL or the local
+ * in-process dispatcher, adding loopback auth and operator-facing diagnostics.
+ */
 import { parseBrowserHttpUrl } from "openclaw/plugin-sdk/browser-config";
 import { resolveTimerTimeoutMs } from "openclaw/plugin-sdk/number-runtime";
 import { fetchWithSsrFGuard } from "openclaw/plugin-sdk/ssrf-runtime";
@@ -274,6 +280,7 @@ async function fetchHttpJson<T>(
   }
 }
 
+/** Fetch JSON from browser control over HTTP or local dispatcher transport. */
 export async function fetchBrowserJson<T>(
   url: string,
   init?: RequestInit & { timeoutMs?: number },
@@ -386,6 +393,7 @@ export async function fetchBrowserJson<T>(
   }
 }
 
+/** Focused test hooks for browser client transport internals. */
 export const testApi = {
   withLoopbackBrowserAuth: withLoopbackBrowserAuthImpl,
 };
diff --git a/extensions/browser/src/browser/client.ts b/extensions/browser/src/browser/client.ts
index 5eeff7e96cb9..111adc6948f8 100644
--- a/extensions/browser/src/browser/client.ts
+++ b/extensions/browser/src/browser/client.ts
@@ -1,3 +1,9 @@
+/**
+ * Browser control client API.
+ *
+ * Provides typed helpers for status, profile lifecycle, tabs, and snapshots
+ * over the browser-control transport.
+ */
 import {
   clampPositiveTimerTimeoutMs,
   resolveTimerTimeoutMs,
@@ -66,6 +72,7 @@ async function sendTabTargetRequest(params: {
   });
 }
 
+/** Profile status record returned by browser profile listing. */
 export type ProfileStatus = {
   name: string;
   transport?: BrowserTransport;
@@ -81,6 +88,7 @@ export type ProfileStatus = {
   reconcileReason?: string | null;
 };
 
+/** Result returned when a managed browser profile directory is reset. */
 export type BrowserResetProfileResult = {
   ok: true;
   moved: boolean;
@@ -88,6 +96,7 @@ export type BrowserResetProfileResult = {
   to?: string;
 };
 
+/** Snapshot response returned by browserSnapshot. */
 export type SnapshotResult =
   | {
       ok: true;
@@ -121,6 +130,7 @@ export type SnapshotResult =
       browserState?: unknown;
     };
 
+/** Read browser-control status for the selected profile. */
 export async function browserStatus(
   baseUrl?: string,
   opts?: { profile?: string; timeoutMs?: number },
@@ -130,6 +140,7 @@ export async function browserStatus(
   });
 }
 
+/** Run browser doctor checks for the selected profile. */
 export async function browserDoctor(
   baseUrl?: string,
   opts?: { profile?: string; deep?: boolean },
@@ -149,6 +160,7 @@ export async function browserDoctor(
   });
 }
 
+/** List configured browser profiles and their current status. */
 export async function browserProfiles(
   baseUrl?: string,
   opts?: { timeoutMs?: number },
@@ -162,6 +174,7 @@ export async function browserProfiles(
   return res.profiles ?? [];
 }
 
+/** Start the selected browser profile. */
 export async function browserStart(
   baseUrl?: string,
   opts?: { profile?: string; timeoutMs?: number },
@@ -169,6 +182,7 @@ export async function browserStart(
   await sendProfilePost(baseUrl, "/start", opts, 15000);
 }
 
+/** Stop the selected browser profile. */
 export async function browserStop(
   baseUrl?: string,
   opts?: { profile?: string; timeoutMs?: number },
@@ -176,6 +190,7 @@ export async function browserStop(
   await sendProfilePost(baseUrl, "/stop", opts, 15000);
 }
 
+/** Reset the selected managed browser profile directory. */
 export async function browserResetProfile(
   baseUrl?: string,
   opts?: { profile?: string },
@@ -190,6 +205,7 @@ export async function browserResetProfile(
   );
 }
 
+/** Result returned after creating a browser profile. */
 export type BrowserCreateProfileResult = {
   ok: true;
   profile: string;
@@ -201,6 +217,7 @@ export type BrowserCreateProfileResult = {
   isRemote: boolean;
 };
 
+/** Create and persist a browser profile. */
 export async function browserCreateProfile(
   baseUrl: string | undefined,
   opts: {
@@ -228,12 +245,14 @@ export async function browserCreateProfile(
   );
 }
 
+/** Result returned after deleting a browser profile. */
 export type BrowserDeleteProfileResult = {
   ok: true;
   profile: string;
   deleted: boolean;
 };
 
+/** Delete a configured browser profile. */
 export async function browserDeleteProfile(
   baseUrl: string | undefined,
   profile: string,
@@ -247,6 +266,7 @@ export async function browserDeleteProfile(
   );
 }
 
+/** List tabs for the selected browser profile. */
 export async function browserTabs(
   baseUrl?: string,
   opts?: { profile?: string; timeoutMs?: number },
@@ -260,6 +280,7 @@ export async function browserTabs(
   return res.tabs ?? [];
 }
 
+/** Open a new tab in the selected browser profile. */
 export async function browserOpenTab(
   baseUrl: string | undefined,
   url: string,
@@ -273,6 +294,7 @@ export async function browserOpenTab(
   });
 }
 
+/** Focus an existing browser tab. */
 export async function browserFocusTab(
   baseUrl: string | undefined,
   targetId: string,
@@ -282,6 +304,7 @@ export async function browserFocusTab(
   await sendTabTargetRequest({ baseUrl, path: "/tabs/focus", method: "POST", opts, body });
 }
 
+/** Close an existing browser tab. */
 export async function browserCloseTab(
   baseUrl: string | undefined,
   targetId: string,
@@ -291,6 +314,7 @@ export async function browserCloseTab(
   await sendTabTargetRequest({ baseUrl, path, method: "DELETE", opts });
 }
 
+/** Execute legacy index-based tab actions. */
 export async function browserTabAction(
   baseUrl: string | undefined,
   opts: {
@@ -311,6 +335,7 @@ export async function browserTabAction(
   });
 }
 
+/** Capture an ARIA or AI snapshot for the selected tab. */
 export async function browserSnapshot(
   baseUrl: string | undefined,
   opts: {
diff --git a/extensions/browser/src/browser/client.types.ts b/extensions/browser/src/browser/client.types.ts
index 4c8f3d75791a..002428d14fe2 100644
--- a/extensions/browser/src/browser/client.types.ts
+++ b/extensions/browser/src/browser/client.types.ts
@@ -1,3 +1,9 @@
+/**
+ * Browser client response types.
+ *
+ * Shared by the browser control client, CLI, and Browser agent tool.
+ */
+/** Browser transport backing the selected profile. */
 export type BrowserTransport = "cdp" | "chrome-mcp";
 type BrowserHeadlessSource =
   | "request"
@@ -7,6 +13,7 @@ type BrowserHeadlessSource =
   | "linux-display-fallback"
   | "default";
 
+/** Browser status response returned by the control server. */
 export type BrowserStatus = {
   enabled: boolean;
   profile?: string;
@@ -38,6 +45,7 @@ export type BrowserStatus = {
   attachOnly: boolean;
 };
 
+/** Browser tab record exposed by tab listing and tab mutation endpoints. */
 export type BrowserTab = {
   /** Best handle for agents to pass back as targetId: label, then tabId, then raw targetId. */
   suggestedTargetId?: string;
@@ -52,6 +60,7 @@ export type BrowserTab = {
   type?: string;
 };
 
+/** ARIA snapshot node exposed in structured snapshot responses. */
 export type SnapshotAriaNode = {
   ref: string;
   role: string;