@browserbridge/bbx 1.3.0 → 1.5.0

package/packages/native-host/src/daemon.js

@@ -36,6 +36,11 @@ import {
   getBridgeTransport,
   getSocketPath,
 } from './config.js';
+import {
+  ensureBridgeAuthToken,
+  normalizeBridgeAuthToken,
+  readBridgeAuthToken,
+} from './auth-token.js';
 import { normalizeDaemonLogger } from './daemon-logger.js';
 import { writeJsonLine } from './framing.js';
 
@@ -47,8 +52,8 @@ const DAEMON_VERSION = loadDaemonVersion();
 /** @typedef {import('../../protocol/src/types.js').SetupStatus} SetupStatus */
 /** @typedef {import('./config.js').BridgeTransport} BridgeTransport */
 /** @typedef {import('./daemon-logger.js').DaemonLoggerLike} DaemonLoggerLike */
-/** @typedef {import('node:net').Socket & { __clientId?: string, __extensionId?: string, __browserName?: string, __profileLabel?: string, __accessEnabled?: boolean, __lastActiveAt?: number }} ClientSocket */
-/** @typedef {{ socket: ClientSocket, timeoutId: NodeJS.Timeout, source?: string, method?: string, targets: Set<ClientSocket>, lastErrorResponse?: import('../../protocol/src/types.js').BridgeResponse }} PendingEntry */
+/** @typedef {import('node:net').Socket & { __clientId?: string, __extensionId?: string, __browserName?: string, __profileLabel?: string, __accessEnabled?: boolean, __lastActiveAt?: number, __authenticated?: boolean }} ClientSocket */
+/** @typedef {{ socket: ClientSocket, timeoutId: NodeJS.Timeout, source?: string, method?: string, protocolVersion?: string, targets: Set<ClientSocket>, lastErrorResponse?: import('../../protocol/src/types.js').BridgeResponse }} PendingEntry */
 /**
  * @typedef {{
  *   installAgentFiles: typeof import('../../agent-client/src/install.js').installAgentFiles,
@@ -134,6 +139,7 @@ export function isWindowsNamedPipePath(socketPath) {
  *   browserName?: string,
  *   profileLabel?: string,
  *   accessEnabled?: boolean,
+ *   authToken?: string,
  *   at?: number
  * }} DaemonMessage
  */
@@ -146,7 +152,8 @@ export class BridgeDaemon {
    *   listenOptions?: import('node:net').ListenOptions | null,
    *   setupStatusLoader?: () => Promise<SetupStatus>,
    *   setupInstaller?: (params: Record<string, unknown>) => Promise<SetupInstallResult>,
-   *   logger?: DaemonLoggerLike | Pick<Console, 'log' | 'error'>
+   *   logger?: DaemonLoggerLike | Pick<Console, 'log' | 'error'>,
+   *   authToken?: string | null
    * }} [options={}]
    */
   constructor({
@@ -156,6 +163,7 @@ export class BridgeDaemon {
     setupStatusLoader = collectSetupStatus,
     setupInstaller = installSetupTarget,
     logger = undefined,
+    authToken = undefined,
   } = {}) {
     this.transport = socketPath ? createSocketBridgeTransport(socketPath) : transport;
     this.socketPath =
@@ -196,6 +204,15 @@ export class BridgeDaemon {
     this.totalResponseTimeMs = 0;
     /** @type {Map<string, number>} */
     this.requestStartTimes = new Map();
+    /** @type {string | null | undefined} */
+    this.authToken = authToken;
+  }
+
+  /**
+   * @returns {boolean}
+   */
+  isAuthRequired() {
+    return Boolean(this.authToken);
   }
 
   /**
@@ -260,6 +277,7 @@ export class BridgeDaemon {
     if (!pending) {
       return undefined;
     }
+    clearTimeout(pending.timeoutId);
     this.pendingRequests.delete(requestId);
     this.removePendingRequestIndex(this.pendingRequestsByOwnerSocket, pending.socket, requestId);
     for (const targetSocket of pending.targets) {
@@ -306,7 +324,20 @@ export class BridgeDaemon {
    * @returns {void}
    */
   registerSocket(socket, message) {
+    if (this.isAuthRequired() && normalizeBridgeAuthToken(message.authToken) !== this.authToken) {
+      this.logger.error('socket registration rejected', { role: message.role ?? null });
+      void writeJsonLine(socket, {
+        type: 'registration_failed',
+        error: {
+          code: ERROR_CODES.ACCESS_DENIED,
+          message: 'Bridge daemon authentication failed.',
+        },
+      }).finally(() => socket.destroy());
+      return;
+    }
+
     if (message.role === 'extension') {
+      socket.__authenticated = true;
       const extensionId = randomUUID();
       socket.__extensionId = extensionId;
       socket.__browserName =
@@ -326,6 +357,7 @@ export class BridgeDaemon {
     }
 
     if (message.role === 'agent') {
+      socket.__authenticated = true;
       const clientId = message.clientId || randomUUID();
       this.agentSockets.set(clientId, socket);
       socket.__clientId = clientId;
@@ -342,6 +374,10 @@ export class BridgeDaemon {
    * @returns {Promise<BridgeDaemon>}
    */
   async start() {
+    if (this.authToken === undefined) {
+      this.authToken = this.transport.type === 'tcp' ? await ensureBridgeAuthToken() : null;
+    }
+
     if (this.transport.type === 'socket' && !isWindowsNamedPipePath(this.socketPath)) {
       const socketDir = path.dirname(this.socketPath);
       await fs.promises.mkdir(socketDir, { recursive: true });
@@ -372,14 +408,22 @@ export class BridgeDaemon {
       typedSocket.on('error', (err) => {
         this.logger.error('socket error', { message: err.message });
       });
-      parseJsonLines(typedSocket, (raw) => {
-        const message = /** @type {DaemonMessage} */ (raw);
-        void this.handleClientMessage(typedSocket, message).catch((err) => {
-          this.logger.error('handler error', {
-            message: err instanceof Error ? err.message : String(err),
+      parseJsonLines(
+        typedSocket,
+        (raw) => {
+          const message = /** @type {DaemonMessage} */ (raw);
+          void this.handleClientMessage(typedSocket, message).catch((err) => {
+            this.logger.error('handler error', {
+              message: err instanceof Error ? err.message : String(err),
+            });
           });
-        });
-      });
+        },
+        {
+          onProtocolError: (error) => {
+            this.logger.error('socket protocol error', { message: error.message });
+          },
+        }
+      );
       typedSocket.on('close', () => this.handleSocketClose(typedSocket));
     });
 
@@ -477,6 +521,10 @@ export class BridgeDaemon {
       return this.registerSocket(socket, message);
     }
 
+    if (this.isAuthRequired() && !socket.__authenticated) {
+      return this.rejectUnauthenticatedMessage(socket, message);
+    }
+
     if (message?.type === 'log') {
       this.pushLog(message.entry ?? {});
       return;
@@ -515,13 +563,73 @@ export class BridgeDaemon {
     });
   }
 
+  /**
+   * @param {ClientSocket} socket
+   * @param {DaemonMessage} message
+   * @returns {Promise<void>}
+   */
+  async rejectUnauthenticatedMessage(socket, message) {
+    if (message?.type === 'agent.request') {
+      const candidate =
+        message.request && typeof message.request === 'object'
+          ? /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (message.request))
+          : {};
+      const response = createFailure(
+        typeof candidate.id === 'string' && candidate.id.trim() ? candidate.id : 'unauthenticated',
+        ERROR_CODES.ACCESS_DENIED,
+        'Register with the daemon auth token before sending bridge requests.',
+        null,
+        typeof candidate.method === 'string' ? { method: candidate.method } : {}
+      );
+      await writeJsonLine(socket, { type: 'agent.response', response });
+      return;
+    }
+
+    await writeJsonLine(socket, {
+      type: 'error',
+      error: {
+        code: ERROR_CODES.ACCESS_DENIED,
+        message: 'Register with the daemon auth token before sending bridge messages.',
+      },
+    });
+  }
+
   /**
    * @param {ClientSocket} socket
    * @param {DaemonMessage} message
    * @returns {Promise<void>}
    */
   async handleAgentRequest(socket, message) {
-    const request = validateBridgeRequest(message.request);
+    /** @type {BridgeRequest} */
+    let request;
+    try {
+      request = validateBridgeRequest(message.request);
+    } catch (error) {
+      const candidate =
+        message.request && typeof message.request === 'object'
+          ? /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (message.request))
+          : {};
+      const response = createFailure(
+        typeof candidate.id === 'string' && candidate.id.trim() ? candidate.id : 'invalid_request',
+        ERROR_CODES.INVALID_REQUEST,
+        error instanceof Error ? error.message : String(error),
+        null,
+        typeof candidate.method === 'string' ? { method: candidate.method } : {}
+      );
+      await writeJsonLine(socket, { type: 'agent.response', response });
+      return;
+    }
+
+    if (this.pendingRequests.has(request.id)) {
+      const response = createFailure(
+        request.id,
+        ERROR_CODES.INVALID_REQUEST,
+        `Request id ${JSON.stringify(request.id)} is already in flight.`
+      );
+      await writeJsonLine(socket, { type: 'agent.response', response });
+      return;
+    }
+
     if (request.method === 'health.ping') {
       if (this.extensionSockets.size === 0) {
         const response = createSuccess(request.id, {
@@ -654,6 +762,7 @@ export class BridgeDaemon {
     this.trackPendingRequest(request.id, {
       socket,
       method: request.method,
+      protocolVersion: request.meta?.protocol_version,
       source: typeof request.meta?.source === 'string' ? request.meta.source : '',
       targets: new Set(targets),
       timeoutId: setTimeout(() => {
@@ -669,6 +778,12 @@ export class BridgeDaemon {
         void writeJsonLine(pending.socket, {
           type: 'agent.response',
           response,
+        }).catch((error) => {
+          this.logger.error('timeout response write failed', {
+            requestId: request.id,
+            method: pending.method,
+            message: error instanceof Error ? error.message : String(error),
+          });
         });
       }, this.pendingTimeoutMs),
     });
@@ -792,7 +907,6 @@ export class BridgeDaemon {
     this.removePendingTarget(responseMessage.id, pending, socket);
 
     if (responseMessage.ok) {
-      clearTimeout(pending.timeoutId);
       this.clearPendingRequest(responseMessage.id, pending);
       this.recordRequestCompletion(responseMessage.id, true);
       this.pushLog({
@@ -812,6 +926,7 @@ export class BridgeDaemon {
                 socketPath: this.socketPath,
                 transport: formatBridgeTransport(this.transport),
                 connectedExtensions: this.getConnectedExtensionsSnapshot(),
+                ...getVersionNegotiationPayload(pending.protocolVersion),
                 .../** @type {Record<string, unknown>} */ (responseMessage.result),
                 daemonVersion: DAEMON_VERSION,
                 daemon_supported_versions: SUPPORTED_VERSIONS,
@@ -849,7 +964,9 @@ export class BridgeDaemon {
 
     if (socket.__clientId) {
       this.logger.info('agent disconnected', { clientId: socket.__clientId });
-      this.agentSockets.delete(socket.__clientId);
+      if (this.agentSockets.get(socket.__clientId) === socket) {
+        this.agentSockets.delete(socket.__clientId);
+      }
     }
 
     const ownedRequestIds = this.pendingRequestsByOwnerSocket.get(socket);
@@ -859,7 +976,6 @@ export class BridgeDaemon {
         if (!pending) {
           continue;
         }
-        clearTimeout(pending.timeoutId);
         this.clearPendingRequest(id, pending);
         this.recordRequestCompletion(id, false);
       }
@@ -873,7 +989,13 @@ export class BridgeDaemon {
           continue;
         }
         this.removePendingTarget(id, pending, socket);
-        void this.finishPendingRequestIfExhausted(id, pending);
+        void this.finishPendingRequestIfExhausted(id, pending).catch((error) => {
+          this.logger.error('pending exhaustion response failed', {
+            requestId: id,
+            method: pending.method,
+            message: error instanceof Error ? error.message : String(error),
+          });
+        });
       }
     }
   }
@@ -891,7 +1013,6 @@ export class BridgeDaemon {
       return;
     }
 
-    clearTimeout(pending.timeoutId);
     this.clearPendingRequest(requestId, pending);
     this.recordRequestCompletion(requestId, false);
 
@@ -958,10 +1079,22 @@ export class BridgeDaemon {
 export async function pingExistingDaemon(transport) {
   const resolvedTransport =
     typeof transport === 'string' ? createSocketBridgeTransport(transport) : transport;
+  const authToken = resolvedTransport.type === 'tcp' ? await readBridgeAuthToken() : null;
   return new Promise((resolve) => {
-    const timeout = setTimeout(() => {
+    let settled = false;
+    /** @param {boolean} value */
+    function finish(value) {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
       socket.destroy();
-      resolve(false);
+      resolve(value);
+    }
+
+    const timeout = setTimeout(() => {
+      finish(false);
     }, DAEMON_EXISTING_SOCKET_PING_TIMEOUT_MS);
 
     const socket =
@@ -969,27 +1102,37 @@ export async function pingExistingDaemon(transport) {
         ? net.createConnection({ host: resolvedTransport.host, port: resolvedTransport.port })
         : net.createConnection(resolvedTransport.socketPath);
     socket.once('error', () => {
-      clearTimeout(timeout);
-      resolve(false);
+      finish(false);
     });
 
     let buf = '';
     socket.setEncoding('utf8');
     socket.on('data', (chunk) => {
       buf += chunk;
-      if (buf.includes('\n')) {
-        clearTimeout(timeout);
-        socket.destroy();
+      while (buf.includes('\n')) {
+        const index = buf.indexOf('\n');
+        const line = buf.slice(0, index).trim();
+        buf = buf.slice(index + 1);
+        if (!line) {
+          continue;
+        }
         try {
-          const msg = JSON.parse(buf.slice(0, buf.indexOf('\n')).trim());
-          resolve(msg?.response?.result?.daemon === 'ok');
+          const msg = JSON.parse(line);
+          if (msg?.type === 'agent.response') {
+            finish(msg?.response?.result?.daemon === 'ok');
+          }
         } catch {
-          resolve(false);
+          finish(false);
         }
       }
     });
 
     socket.once('connect', () => {
+      if (authToken) {
+        socket.write(
+          `${JSON.stringify({ type: 'register', role: 'agent', clientId: 'ping_probe', authToken })}\n`
+        );
+      }
       socket.write(
         `${JSON.stringify({
           type: 'agent.request',
@@ -1011,7 +1154,10 @@ export async function pingExistingDaemon(transport) {
  * @returns {SetupInstallParams & { action: 'install' | 'uninstall', kind: 'mcp' | 'skill', target: string }}
  */
 export function normalizeSetupInstallParams(params) {
-  const action = params.action === 'uninstall' ? 'uninstall' : 'install';
+  const action = params.action == null ? 'install' : params.action;
+  if (action !== 'install' && action !== 'uninstall') {
+    throw new Error('setup.install action must be "install" or "uninstall".');
+  }
   const kind = params.kind === 'mcp' || params.kind === 'skill' ? params.kind : null;
   const target = typeof params.target === 'string' ? params.target.trim().toLowerCase() : '';
   if (!kind) {
@@ -1020,7 +1166,7 @@ export function normalizeSetupInstallParams(params) {
   if (!target) {
     throw new Error('setup.install requires a target.');
   }
-  return { action, kind, target };
+  return { action: /** @type {'install' | 'uninstall'} */ (action), kind, target };
 }
 
 /**

package/packages/native-host/src/framing.js

@@ -2,7 +2,7 @@
 
 import { once } from 'node:events';
 
-import { MAX_NATIVE_MESSAGE_BYTES } from '../../protocol/src/index.js';
+import { MAX_JSON_LINE_BYTES, MAX_NATIVE_MESSAGE_BYTES } from '../../protocol/src/index.js';
 
 /**
  * @param {NodeJS.WritableStream} stream
@@ -193,7 +193,12 @@ export function createNativeMessageReader(stream, onMessage, onProtocolError) {
  * @returns {Promise<void>}
  */
 export async function writeJsonLine(socket, message) {
-  if (!socket.write(`${JSON.stringify(message)}\n`)) {
+  const line = `${JSON.stringify(message)}\n`;
+  const byteLength = Buffer.byteLength(line.slice(0, -1), 'utf8');
+  if (byteLength > MAX_JSON_LINE_BYTES) {
+    throw new Error(`JSON line exceeds ${MAX_JSON_LINE_BYTES} bytes: ${byteLength}`);
+  }
+  if (!socket.write(line)) {
     await once(socket, 'drain');
   }
 }

package/packages/native-host/src/native-host.js

@@ -2,7 +2,8 @@
 
 import net from 'node:net';
 
-import { createFailure, ERROR_CODES } from '../../protocol/src/index.js';
+import { createFailure, ERROR_CODES, MAX_JSON_LINE_BYTES } from '../../protocol/src/index.js';
+import { readBridgeAuthToken } from './auth-token.js';
 import { createSocketBridgeTransport, getBridgeTransport } from './config.js';
 import { spawnBridgeDaemonProcess } from './daemon-process.js';
 import { createNativeMessageReader, createNativeMessageWriter, writeJsonLine } from './framing.js';
@@ -146,11 +147,21 @@ export async function runNativeHost({
   socket.once('close', cleanupStdinEndListener);
   socket.once('end', cleanupStdinEndListener);
   socket.once('error', cleanupStdinEndListener);
-  await writeJsonLine(socket, { type: 'register', role: 'extension' });
+  const authToken = resolvedTransport.type === 'tcp' ? await readBridgeAuthToken() : null;
+  await writeJsonLine(socket, {
+    type: 'register',
+    role: 'extension',
+    ...(authToken ? { authToken } : {}),
+  });
 
   let lineBuffer = '';
   socket.on('data', (chunk) => {
     lineBuffer += chunk;
+    if (!lineBuffer.includes('\n') && Buffer.byteLength(lineBuffer, 'utf8') > MAX_JSON_LINE_BYTES) {
+      console.error(`native-host: daemon JSON line exceeded ${MAX_JSON_LINE_BYTES} bytes`);
+      socket.destroy();
+      return;
+    }
     while (lineBuffer.includes('\n')) {
       const index = lineBuffer.indexOf('\n');
       const line = lineBuffer.slice(0, index).trim();
@@ -158,6 +169,11 @@ export async function runNativeHost({
       if (!line) {
         continue;
       }
+      if (Buffer.byteLength(line, 'utf8') > MAX_JSON_LINE_BYTES) {
+        console.error(`native-host: daemon JSON line exceeded ${MAX_JSON_LINE_BYTES} bytes`);
+        socket.destroy();
+        return;
+      }
       let message;
       try {
         message = JSON.parse(line);

package/packages/protocol/src/defaults.js

@@ -24,6 +24,9 @@ export const DEFAULT_DEVICE_SCALE_FACTOR = 0;
 /** Maximum size of a Chrome native messaging message in bytes. */
 export const MAX_NATIVE_MESSAGE_BYTES = 1_048_576;
 
+/** Maximum size of one newline-delimited daemon socket message in bytes. */
+export const MAX_JSON_LINE_BYTES = MAX_NATIVE_MESSAGE_BYTES;
+
 /** Default timeout for a bridge request awaiting an extension response (ms). */
 export const DEFAULT_DAEMON_PENDING_TIMEOUT_MS = 30_000;
 

package/packages/protocol/src/json-lines.js

@@ -1,18 +1,42 @@
 // @ts-check
 
+import { MAX_JSON_LINE_BYTES } from './defaults.js';
+
 /**
  * Install a newline-delimited JSON parser on a socket's `data` event.
  *
  * @param {import('node:net').Socket} socket
  * @param {(message: unknown) => void} onMessage
+ * @param {{ maxLineBytes?: number, onProtocolError?: (error: Error) => void }} [options]
  * @returns {void}
  */
-export function parseJsonLines(socket, onMessage) {
+export function parseJsonLines(socket, onMessage, options = {}) {
   let buffer = '';
+  const maxLineBytes =
+    typeof options.maxLineBytes === 'number' && Number.isFinite(options.maxLineBytes)
+      ? Math.max(1, Math.floor(options.maxLineBytes))
+      : MAX_JSON_LINE_BYTES;
   socket.setEncoding('utf8');
+
+  /**
+   * @param {Error} error
+   * @returns {void}
+   */
+  function fail(error) {
+    options.onProtocolError?.(error);
+    const destroy = /** @type {{ destroy?: (() => void) | undefined }} */ (socket).destroy;
+    if (typeof destroy === 'function') {
+      destroy.call(socket);
+    }
+  }
+
   /** @param {string} chunk */
   socket.on('data', (chunk) => {
     buffer += chunk;
+    if (!buffer.includes('\n') && Buffer.byteLength(buffer, 'utf8') > maxLineBytes) {
+      fail(new Error(`JSON line exceeds ${maxLineBytes} bytes.`));
+      return;
+    }
     while (buffer.includes('\n')) {
       const index = buffer.indexOf('\n');
       const line = buffer.slice(0, index).trim();
@@ -20,6 +44,10 @@ export function parseJsonLines(socket, onMessage) {
       if (!line) {
         continue;
       }
+      if (Buffer.byteLength(line, 'utf8') > maxLineBytes) {
+        fail(new Error(`JSON line exceeds ${maxLineBytes} bytes.`));
+        return;
+      }
       try {
         onMessage(JSON.parse(line));
       } catch {

package/packages/protocol/src/protocol.js

@@ -97,7 +97,9 @@ export const SUPPORTED_VERSIONS = Object.freeze(['1.0']);
  * @returns {number}
  */
 function clampInt(value, min, max, fallback) {
-  return Math.min(Math.max(Number(value) || fallback, min), max);
+  const numeric = Number(value);
+  const integer = Number.isFinite(numeric) && numeric !== 0 ? Math.trunc(numeric) : fallback;
+  return Math.min(Math.max(integer, min), max);
 }
 
 /** @type {ReadonlyArray<BridgeMethod>} */
@@ -672,6 +674,9 @@ export function normalizeHoverParams(params = {}) {
         : undefined
     ),
     duration: clampInt(params.duration, 0, 5_000, 0),
+    modifiers: Array.isArray(params.modifiers)
+      ? params.modifiers.filter((modifier) => typeof modifier === 'string' && modifier.trim())
+      : [],
   };
 }
 

package/packages/protocol/src/types.ts

@@ -460,11 +460,13 @@ export interface NormalizedGetHtmlParams extends BridgeParams {
 export interface HoverParams {
   target?: InputTarget;
   duration?: number;
+  modifiers?: string[];
 }
 
 export interface NormalizedHoverParams extends BridgeParams {
   target: InputTarget;
   duration: number;
+  modifiers: string[];
 }
 
 export interface DragParams {

package/skills/browser-bridge/SKILL.md

@@ -10,14 +10,16 @@ Token-efficient Chrome tab inspection, interaction, and CSS/DOM patching through
 This CLI skill is for agents that can run shell commands and where direct `bbx` control fits better than MCP tools: manual debugging, terminal reproduction, install/doctor flows, raw protocol access, or environments without MCP.
 
 Skill name: `browser-bridge` (also known as `bbx`). In GitHub Copilot, invoke as `/browser-bridge`. `bbx` is the CLI command used throughout this skill.
-Use a subagent for bridge calls; return only concise findings to the parent.
-For open-ended investigation, prefer a smaller, lower-cost subagent first. Start with structured reads (`page.get_state`, `dom.query`, `page.get_text`, `styles.get_computed`, `bbx batch`) and escalate to screenshots or debugger-backed methods only when structured evidence is insufficient.
+When the runtime supports subagents, delegate bridge inspection to a smaller, lower-cost worker and return only concise findings to the parent.
+For open-ended investigation, start with structured reads (`page.get_state`, `dom.query`, `page.get_text`, `styles.get_computed`, `bbx batch`) and escalate to screenshots or debugger-backed methods only when structured evidence is insufficient.
 
 ## CLI
 
 ```bash
 bbx status                  # daemon + extension health
 bbx doctor                  # install/access readiness
+bbx access-request          # ask user to enable access for the focused window
+bbx restart                 # start/restart the local daemon non-interactively
 bbx call <method> '{...}'   # any RPC method (raw output)
 bbx <method> '{...}'        # direct alias for an exact bridge method such as page.get_state
 bbx call --tab 123 <method> '{...}' # explicit tab override
@@ -59,6 +61,7 @@ bbx navigate <url>                   # navigate to URL
 bbx reload                           # reload current page
 bbx back                             # navigate back
 bbx forward                          # navigate forward
+bbx scroll <top> [left]              # scroll viewport
 bbx resize <width> <height>          # resize viewport
 ```
 
@@ -77,7 +80,7 @@ bbx patch-text <ref> <text...>       # apply text patch
 bbx patches                          # list active patches
 bbx rollback <patchId>               # rollback a patch
 bbx screenshot <ref> [outPath]       # capture partial element screenshot
-bbx call screenshot.capture_full_page '{}' # full-page screenshot when document context matters
+bbx call screenshot.capture_full_page '{}' # raw base64; avoid unless document context matters
 ```
 
 ## Access Flow
@@ -114,8 +117,8 @@ After access is enabled:
 | `EXTENSION_DISCONNECTED`  | After 3s | Check Chrome is running; `bbx status` to verify, then retry                               |
 | `NATIVE_HOST_UNAVAILABLE` | No       | Run `bbx doctor` to diagnose the installation                                             |
 | `INTERNAL_ERROR`          | Once     | Retry once; if persistent, check `page.get_console` for details                           |
-| `DAEMON_OFFLINE`          | No       | Daemon not running - start with `bbx-daemon`                                              |
-| `CONNECTION_LOST`         | Yes      | Socket dropped mid-request - retry; if persistent, restart daemon                         |
+| `DAEMON_OFFLINE`          | No       | Daemon not running - start with `bbx restart`                                             |
+| `CONNECTION_LOST`         | Yes      | Socket dropped mid-request - retry; if persistent, run `bbx restart`                      |
 | `BRIDGE_TIMEOUT`          | Once     | Extension took too long - retry once with simpler call                                    |
 
 Error responses now include a machine-readable `error.recovery` field with `retry`, `retryAfterMs`, `alternativeMethod`, and `hint`.
@@ -160,6 +163,12 @@ For a natural-language inspection task:
 4. Escalate to `screenshot.capture_element`, `screenshot.capture_region`, or other debugger-backed methods only when structured reads are ambiguous or visual confirmation is required.
 5. Return concise findings and evidence, not raw dumps.
 
+CLI-first starter:
+
+```bash
+bbx batch '[{"method":"page.get_state"},{"method":"dom.query","params":{"selector":"main","maxNodes":10,"maxDepth":3,"textBudget":400,"attributeAllowlist":["id","class","data-testid"]}},{"method":"page.get_text","params":{"textBudget":2000}}]'
+```
+
 ## Common Workflows
 
 ### Debug a CSS layout issue
@@ -269,6 +278,13 @@ Return: verdict, tab id + origin, minimal evidence set. No raw HTML or base64 im
 
 Every CLI shortcut command produces consistent `{ok, summary, evidence}` JSON. Use `bbx call <method>` for raw protocol output when needed.
 
+## CLI Raw Params Gotchas
+
+- Use `selector`, not `scope`, to narrow `dom.find_by_text` and `dom.find_by_role`.
+- Wrap interaction targets as `target: { elementRef }` or `target: { selector }`; `viewport.scroll` also uses the `target` wrapper for element scrolling.
+- `input.drag` uses `source`, `destination`, and optional destination offsets `offsetX` / `offsetY`.
+- Raw `screenshot.capture_region` and `screenshot.capture_full_page` return base64 JSON; prefer `bbx screenshot <ref> [outPath]` when one element is enough.
+
 ## Response Shapes
 
 The summarizer auto-detects response types and produces concise summaries:

package/skills/browser-bridge/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: 'Browser Bridge'
   short_description: 'Token-efficient Chrome tab inspection, interaction, and patching via local bridge'
-  default_prompt: 'Use the browser-bridge skill for Chrome tab inspection, interaction, and patching. Start with `bbx status` to confirm connectivity. If ACCESS_DENIED, ask the user to click Enable in the extension popup/side panel, then retry. Default routing follows the active tab; use `--tab` only for a different tab. Prefer structured reads (`dom.query`, `styles.get_computed`) over screenshots. Batch independent reads with `bbx batch`. Use `bbx skill` for runtime presets.'
+  default_prompt: 'Use the browser-bridge skill for Chrome tab inspection, interaction, and patching. Start with `bbx status` to confirm connectivity; if the daemon is offline, run `bbx restart`. If ACCESS_DENIED, ask the user to click Enable in the extension popup/side panel, then retry. Default routing follows the active tab; use `--tab` only for a different tab. Prefer structured reads (`dom.query`, `styles.get_computed`) over screenshots. Batch independent reads with `bbx batch`. Use `bbx skill` for runtime presets.'