@browserbridge/bbx 1.7.5 → 1.7.7

package/README.md

@@ -114,7 +114,7 @@ Browser Bridge is optimized for the opposite starting point: **inspect the state
 
 On Ubuntu, Chromium is commonly installed as a strict snap, and Flatpak Chromium is similarly sandboxed. If native messaging stays disconnected there, use a non-sandboxed Chromium-based browser such as Google Chrome, Brave, or Edge.
 
-MCP mode is self-contained: the server exposes tools, startup instructions, and prompt templates, so a separate CLI skill is not required for MCP guidance.
+MCP mode is self-contained: the server exposes tools and startup instructions, so a separate CLI skill is not required for MCP guidance.
 
 ## How it works
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.7.5",
+  "version": "1.7.7",
   "private": false,
   "keywords": [
     "agent-tools",
@@ -56,7 +56,7 @@
     "test": "c8 node --test",
     "coverage": "c8 report --reporter=text --reporter=text-summary",
     "coverage:review": "c8 report --reporter=json-summary && node scripts/review-coverage.mjs",
-    "coverage:check": "c8 check-coverage --lines 80 --branches 75",
+    "coverage:check": "c8 check-coverage --lines 92 --branches 83",
     "typecheck": "tsc --noEmit",
     "postinstall": "node packages/native-host/bin/postinstall.js",
     "package:extension": "node scripts/package-extension.mjs",
@@ -75,13 +75,13 @@
   "devDependencies": {
     "@types/chrome": "^0.2.2",
     "@types/node": "^26.1.1",
-    "c8": "^11.0.0",
+    "c8": "^12.0.0",
     "linkedom": "^0.18.13",
-    "oxfmt": "^0.58.0",
-    "oxlint": "^1.73.0",
+    "oxfmt": "^0.59.0",
+    "oxlint": "^1.74.0",
     "typescript": "^7.0.2"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   }
 }

package/packages/agent-client/src/cli-args.js

@@ -0,0 +1,152 @@
+// @ts-check
+
+import { METHODS } from '../../protocol/src/index.js';
+import { methodNeedsTab, parseIntArg, parseJsonObject } from './cli-helpers.js';
+
+/** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
+
+/**
+ * Read all of stdin as UTF-8 text. Resolves once stdin closes.
+ *
+ * @returns {Promise<string>}
+ */
+export function readStdin() {
+  return new Promise((resolve, reject) => {
+    const chunks = /** @type {Buffer[]} */ ([]);
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
+    process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf8').trim()));
+    process.stdin.on('error', reject);
+    if (process.stdin.isTTY) {
+      resolve('');
+    }
+  });
+}
+
+/**
+ * Extract the global --remote flag from anywhere in the argument list.
+ * Exits with a usage error when the flag is present without a value.
+ *
+ * @param {string[]} args
+ * @returns {{ remoteId: string | null, explicit: boolean, rest: string[] }}
+ */
+export function extractRemoteFlag(args) {
+  const rest = [...args];
+  const index = rest.indexOf('--remote');
+  if (index === -1) {
+    return { remoteId: null, explicit: false, rest };
+  }
+  const remoteId = rest[index + 1];
+  if (!remoteId || remoteId.startsWith('--')) {
+    process.stderr.write('--remote requires a destination name (see `bbx remote list`).\n');
+    process.exit(1);
+  }
+  rest.splice(index, 2);
+  return { remoteId, explicit: true, rest };
+}
+
+/**
+ * @param {string[]} args
+ * @returns {{ tabId: number | null, rest: string[] }}
+ */
+export function extractTabFlag(args) {
+  const rest = [...args];
+  let tabId = null;
+  const tabIndex = rest.indexOf('--tab');
+  if (tabIndex !== -1) {
+    tabId = parseIntArg(rest[tabIndex + 1], 'tabId');
+    rest.splice(tabIndex, 2);
+  }
+  return { tabId, rest };
+}
+
+/**
+ * @param {string[]} args
+ * @returns {Promise<{ tabId: number | null, method: BridgeMethod, params: Record<string, unknown> }>}
+ */
+export async function parseCallCommand(args) {
+  const parsed = extractTabFlag(args);
+  const [first, second, ...extra] = parsed.rest;
+  if (!first) {
+    throw new Error('Usage: call [--tab <tabId>] <method> [paramsJson]');
+  }
+  if (extra.length > 0) {
+    throw new Error('Usage: call [--tab <tabId>] <method> [paramsJson]');
+  }
+
+  if (first.includes('.')) {
+    const method = /** @type {BridgeMethod} */ (first);
+    if (!METHODS.includes(method)) {
+      throw new Error(`Unknown method "${first}". Run bbx skill to see available methods.`);
+    }
+    let rawParams = second;
+    // Support piped stdin: `echo '{"key":"val"}' | bbx call method -`
+    if (rawParams === '-') {
+      rawParams = await readStdin();
+    }
+    return {
+      method,
+      tabId: methodNeedsTab(method) ? parsed.tabId : null,
+      params: parseJsonObject(rawParams),
+    };
+  }
+
+  throw new Error('Usage: call [--tab <tabId>] <method> [paramsJson]');
+}
+
+/**
+ * @param {string[]} args
+ * @returns {{ pattern: string, isBlock: boolean, statusCode: number, body: string | undefined }}
+ */
+export function parseInterceptAddArgs(args) {
+  const [pattern, ...optionArgs] = args;
+  if (!pattern || pattern.startsWith('--')) {
+    throw new Error(
+      'Usage: intercept add <urlPattern> [--respond <body>] [--status <code>] [--block]'
+    );
+  }
+
+  let isBlock = false;
+  let statusCode = 200;
+  let hasStatus = false;
+  let body;
+  for (let index = 0; index < optionArgs.length; index += 1) {
+    const option = optionArgs[index];
+    if (option === '--block') {
+      if (isBlock) {
+        throw new Error('The --block option may only be specified once.');
+      }
+      isBlock = true;
+      continue;
+    }
+    if (option === '--respond') {
+      const value = optionArgs[++index];
+      if (body !== undefined) {
+        throw new Error('The --respond option may only be specified once.');
+      }
+      if (value === undefined || value.startsWith('--')) {
+        throw new Error('--respond requires a body value.');
+      }
+      body = value;
+      continue;
+    }
+    if (option === '--status') {
+      if (hasStatus) {
+        throw new Error('The --status option may only be specified once.');
+      }
+      const value = optionArgs[++index];
+      statusCode = parseIntArg(value, 'status');
+      if (statusCode < 100 || statusCode > 599) {
+        throw new Error('status must be an integer between 100 and 599.');
+      }
+      hasStatus = true;
+      continue;
+    }
+    throw new Error(`Unknown or extra intercept add option "${option}".`);
+  }
+
+  if (isBlock && body !== undefined) {
+    throw new Error('Use either --block or --respond, not both.');
+  }
+  return { pattern, isBlock, statusCode, body };
+}

package/packages/agent-client/src/cli-batch.js

@@ -0,0 +1,140 @@
+// @ts-check
+
+import {
+  getProtocolVersion,
+  METHODS,
+  summarizeBatchErrorItem,
+  summarizeBatchResponseItem,
+} from '../../protocol/src/index.js';
+import { methodNeedsTab } from './cli-helpers.js';
+import { requestBridge } from './runtime.js';
+
+/** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
+/** @typedef {import('./types.js').BridgeRequestSource} BridgeRequestSource */
+
+/**
+ * @typedef {{
+ *   method: string,
+ *   tabId: null,
+ *   ok: false,
+ *   summary: string,
+ *   evidence: null,
+ *   durationMs: 0,
+ *   approxTokens: 0,
+ *   meta: { protocol_version: string },
+ *   error: { code: 'INVALID_REQUEST', message: string },
+ *   response: null,
+ * }} InvalidBatchItem
+ */
+
+/**
+ * @typedef {ReturnType<typeof summarizeBatchResponseItem>
+ *   | ReturnType<typeof summarizeBatchErrorItem>
+ *   | InvalidBatchItem} BatchResultItem
+ */
+
+/**
+ * Build the standard invalid-request batch item.
+ *
+ * @param {string} method
+ * @param {string} message
+ * @returns {InvalidBatchItem}
+ */
+function invalidBatchItem(method, message) {
+  return {
+    method,
+    tabId: null,
+    ok: false,
+    summary: `INVALID_REQUEST: ${message}`,
+    evidence: null,
+    durationMs: 0,
+    approxTokens: 0,
+    meta: { protocol_version: getProtocolVersion() },
+    error: {
+      code: 'INVALID_REQUEST',
+      message,
+    },
+    response: null,
+  };
+}
+
+/**
+ * Parse and execute `bbx batch '[...]'`: validate each call, run them in
+ * parallel against the bridge, and return per-call summary items.
+ *
+ * @param {import('./client.js').BridgeClient} client
+ * @param {string | undefined} input - Raw JSON array argument
+ * @param {BridgeRequestSource} source - Request source tag (e.g. 'cli')
+ * @returns {Promise<BatchResultItem[]>}
+ */
+export async function runBatchCalls(client, input, source) {
+  if (!input) {
+    throw new Error('Usage: batch \'[{"method":"...","params":{...}}, ...]\'');
+  }
+  let calls;
+  try {
+    calls = JSON.parse(input);
+  } catch {
+    throw new Error('Invalid JSON syntax. Expected a JSON array of bridge calls.');
+  }
+  if (!Array.isArray(calls)) {
+    throw new Error('Batch input must be a JSON array.');
+  }
+  if (!client.connected) {
+    await client.connect();
+  }
+  return Promise.all(
+    calls.map(async (call) => {
+      if (!call || typeof call !== 'object' || Array.isArray(call)) {
+        return invalidBatchItem('', 'Each batch call needs a method.');
+      }
+      const batchCall = /** @type {Record<string, unknown>} */ (call);
+      if (typeof batchCall.method !== 'string') {
+        return invalidBatchItem('', 'Each batch call needs a method.');
+      }
+      if (!METHODS.includes(/** @type {BridgeMethod} */ (batchCall.method))) {
+        return invalidBatchItem(batchCall.method, `Unknown bridge method "${batchCall.method}".`);
+      }
+      const method = /** @type {BridgeMethod} */ (batchCall.method);
+      if (
+        batchCall.params !== undefined &&
+        (!batchCall.params ||
+          typeof batchCall.params !== 'object' ||
+          Array.isArray(batchCall.params))
+      ) {
+        return invalidBatchItem(method, 'Batch call params must be a JSON object.');
+      }
+      const params =
+        batchCall.params === undefined
+          ? {}
+          : /** @type {Record<string, unknown>} */ (batchCall.params);
+      const tabId =
+        methodNeedsTab(method) &&
+        typeof batchCall.tabId === 'number' &&
+        Number.isInteger(batchCall.tabId) &&
+        batchCall.tabId > 0
+          ? batchCall.tabId
+          : null;
+      const startTime = Date.now();
+      try {
+        const response = await requestBridge(client, method, params, {
+          tabId,
+          source,
+        });
+        return summarizeBatchResponseItem({
+          method,
+          tabId,
+          response,
+          durationMs: Date.now() - startTime,
+        });
+      } catch (err) {
+        return summarizeBatchErrorItem({
+          method,
+          tabId,
+          error: err,
+          durationMs: Date.now() - startTime,
+        });
+      }
+    })
+  );
+}

package/packages/agent-client/src/cli-output.js

@@ -0,0 +1,57 @@
+// @ts-check
+
+import { sanitizeOutput } from './cli-helpers.js';
+import { CLI_HELP_SECTIONS } from './command-registry.js';
+import { annotateBridgeSummary, summarizeBridgeResponse } from './subagent.js';
+
+/**
+ * @param {unknown} value
+ * @returns {void}
+ */
+export function printJson(value) {
+  process.stdout.write(
+    `${JSON.stringify(sanitizeOutput(value), null, process.stdout.isTTY ? 2 : undefined)}\n`
+  );
+}
+
+/**
+ * @param {import('../../protocol/src/types.js').BridgeResponse} response
+ * @param {string} [method] - Optional method name for disambiguation
+ * @returns {Promise<void>}
+ */
+export async function printSummary(response, method) {
+  if (!response.ok) {
+    process.exitCode = 1;
+  }
+  printJson(annotateBridgeSummary(summarizeBridgeResponse(response, method), response));
+}
+
+/**
+ * @param {import('../../protocol/src/types.js').BridgeResponse} response
+ * @returns {void}
+ */
+export function printCallResponse(response) {
+  if (response.ok) {
+    printJson(response.result);
+    return;
+  }
+
+  process.exitCode = 1;
+  const errorText = `${response.error.code}: ${response.error.message}`;
+  process.stderr.write(
+    `${process.stderr.isTTY ? `\u001b[31m${sanitizeOutput(errorText)}\u001b[0m` : sanitizeOutput(errorText)}\n`
+  );
+  printJson(response);
+}
+
+/**
+ * @returns {void}
+ */
+export function printUsage() {
+  const blocks = ['Usage: bbx [--remote <name>] <command> [args]'];
+  for (const section of CLI_HELP_SECTIONS) {
+    blocks.push('', `${section.title}:`);
+    blocks.push(...section.lines.map((line) => `  ${line}`));
+  }
+  process.stdout.write(`${blocks.join('\n')}\n`);
+}