@browserbridge/bbx 1.12.1 → 1.12.3

package/packages/mcp-server/src/handlers.js

@@ -16,6 +16,7 @@ import {
   summarizeToolResponse,
   withToolClient,
   REQUEST_SOURCE,
+  hasMcpBrowserTarget,
 } from './handlers-utils.js';
 
 export {
@@ -81,6 +82,9 @@ const HOME_DIR = os.homedir();
  */
 export async function handleStatusTool(args = {}) {
   try {
+    if (hasMcpBrowserTarget()) {
+      return callBridgeTool('health.ping', {}, { destinationId: args.destinationId });
+    }
     const requestedDestinationId =
       typeof args.destinationId === 'string' ? args.destinationId : null;
     if (requestedDestinationId && requestedDestinationId !== 'local') {
@@ -172,7 +176,7 @@ async function callRemoteHealth(destinationId) {
  */
 export async function handleSkillTool(args = {}) {
   try {
-    if (typeof args.destinationId === 'string') {
+    if (typeof args.destinationId === 'string' || hasMcpBrowserTarget()) {
       return callBridgeTool('skill.get_runtime_context', {}, { destinationId: args.destinationId });
     }
     const ctx = createRuntimeContext();

package/packages/mcp-server/src/server.js

@@ -54,13 +54,44 @@ import {
 import { applyWindowsTcpTransportDefaults } from '../../native-host/src/config.js';
 import { getMcpServerInstructions } from './guidance.js';
 import { isToolEnabledForEra, LOADABLE_TOOLSET_TOOLS } from './toolset.js';
+import { runWithMcpRequestTarget } from './handlers-utils.js';
 
 export const BUDGET_PRESET_DESCRIPTION = `Budget preset: "quick", "normal", or "deep" (defaults: query ${BUDGET_PRESETS.normal.maxNodes} nodes / depth ${BUDGET_PRESETS.normal.maxDepth} / text ${BUDGET_PRESETS.normal.textBudget}). Numeric fields override the preset when both are provided.`;
 export const TAB_ID_DESCRIPTION =
-  'Target a specific tab instead of the active tab in the enabled window.';
+  'Tab ID within the selected browser profile. With multiple profiles, also pass extensionId from tabs.list or health.ping.';
 export const DESTINATION_ID_DESCRIPTION =
   'Optional Browser Bridge destination ID from browser_status/browser_tabs; omit for local.';
 
+const BROWSER_TARGET_SCHEMA = {
+  extensionId: z
+    .string()
+    .trim()
+    .min(1)
+    .max(256)
+    .optional()
+    .describe(
+      'Exact browser connection ID from health.ping connectedExtensions or tabs.list. Reuse with tabId on every call; IDs are scoped to destinationId and change on reconnect.'
+    ),
+  targetBrowser: z
+    .string()
+    .trim()
+    .min(1)
+    .max(256)
+    .optional()
+    .describe(
+      'Browser name from health.ping connectedExtensions. Prefer extensionId when names are ambiguous.'
+    ),
+  targetProfile: z
+    .string()
+    .trim()
+    .min(1)
+    .max(256)
+    .optional()
+    .describe(
+      'Profile label from health.ping connectedExtensions. Prefer extensionId when labels are missing or duplicated.'
+    ),
+};
+
 const MCP_SERVER_VERSION = loadPackageVersion();
 
 /**
@@ -173,9 +204,24 @@ export function createBridgeMcpServer(options = {}) {
   const registerTool = (name, config, handler) => {
     const wrappedHandler = /** @type {typeof handler} */ (
       (args, context) =>
-        runWithMcpRequestEra(era, () => handler(args, context), context.mcpReq.signal)
+        runWithMcpRequestEra(
+          era,
+          () => runWithMcpRequestTarget(args, () => handler(args, context)),
+          context.mcpReq.signal
+        )
     );
-    const registration = server.registerTool(name, config, wrappedHandler);
+    const routedConfig =
+      name === 'browser_setup' || name === 'browser_toolset'
+        ? config
+        : {
+            ...config,
+            // Added optional routing fields are consumed by the wrapper; handlers keep
+            // their original, SDK-checked argument contracts.
+            inputSchema: /** @type {InputSchema} */ (
+              /** @type {unknown} */ (config.inputSchema.extend(BROWSER_TARGET_SCHEMA))
+            ),
+          };
+    const registration = server.registerTool(name, routedConfig, wrappedHandler);
     registrations.set(name, registration);
     if (!isToolEnabledForEra(name, era)) {
       registration.disable();
@@ -257,13 +303,26 @@ export function createBridgeMcpServer(options = {}) {
     {
       title: 'Browser Tabs',
       description:
-        'List, create, close, or activate browser tabs. List without destinationId aggregates configured destinations; other actions default to local. Only create a page when the user explicitly requests it.',
+        "List, create, close, or activate browser tabs. Unscoped list discovers tabs across enabled browser profiles and configured destinations. Reuse each tab's extensionId, destinationId, and tabId for subsequent calls. Other actions default to local. Only create a page when the user explicitly requests it.",
       inputSchema: z.object({
         action: z
           .enum(['list', 'create', 'close', 'activate'])
           .describe('"list" (preferred), "create" (only when needed), "close", or "activate"'),
         url: z.string().optional().describe('URL for create action'),
         active: z.boolean().optional().describe('Focus the new tab (default: true)'),
+        limit: z
+          .number()
+          .int()
+          .min(1)
+          .max(100)
+          .optional()
+          .describe('Requested tab page size. Omit for discovery of all tabs.'),
+        offset: z
+          .number()
+          .int()
+          .nonnegative()
+          .optional()
+          .describe('Tab page offset. With offset alone the page size is 10.'),
         tabId: z
           .number()
           .int()
@@ -1051,6 +1110,7 @@ export function createBridgeMcpServer(options = {}) {
                 .describe('Method params for this call'),
               tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
               destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
+              ...BROWSER_TARGET_SCHEMA,
               budgetPreset: z
                 .enum(['quick', 'normal', 'deep'])
                 .optional()

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

@@ -1282,7 +1282,9 @@ export class BridgeDaemon {
       typeof request.meta?.target_browser === 'string' ? request.meta.target_browser : null;
     const targetProfile =
       typeof request.meta?.target_profile === 'string' ? request.meta.target_profile : null;
-    const hasExplicitTarget = Boolean(targetBrowser || targetProfile);
+    const targetExtension =
+      typeof request.meta?.target_extension === 'string' ? request.meta.target_extension : null;
+    const hasExplicitTarget = Boolean(targetBrowser || targetProfile || targetExtension);
 
     const ownerPendingCount = this.pendingRequestsByOwnerSocket.get(socket)?.size ?? 0;
     if (
@@ -1311,13 +1313,42 @@ export class BridgeDaemon {
       request.method === 'dom.baseline.describe' ||
       request.method === 'dom.baseline.release';
     const baselineOwner = usesBaselineOwner ? this.domBaselines.get(baselineId ?? '') : null;
+    const candidates = [...this.extensionSockets.entries()].filter(
+      ([id, extension]) =>
+        (!targetExtension || id === targetExtension) &&
+        (!targetBrowser || extension.__browserName === targetBrowser) &&
+        (!targetProfile || extension.__profileLabel === targetProfile)
+    );
+    if (
+      !usesBaselineOwner &&
+      candidates.length > 1 &&
+      request.method !== 'health.ping' &&
+      request.method !== 'skill.get_runtime_context'
+    ) {
+      await writeJsonLine(socket, {
+        type: 'agent.response',
+        response: createFailure(
+          request.id,
+          ERROR_CODES.TAB_MISMATCH,
+          'Multiple browser profiles match this call. Select a connection with extensionId in MCP or meta.target_extension in raw requests, then list its tabs. A tabId alone does not select a profile. Do not disable other windows.',
+          {
+            reason: 'ambiguous_browser_target',
+            connectedExtensions: this.getConnectedExtensionsSnapshot(),
+          },
+          { method: request.method }
+        ),
+      });
+      this.recordDaemonRequestOutcome(request, false);
+      return;
+    }
     const target = usesBaselineOwner
       ? baselineOwner &&
+        (!targetExtension || this.extensionSockets.get(targetExtension) === baselineOwner) &&
         (!targetBrowser || baselineOwner.__browserName === targetBrowser) &&
         (!targetProfile || baselineOwner.__profileLabel === targetProfile)
         ? baselineOwner
         : null
-      : this.selectExtensionTarget(targetBrowser, targetProfile);
+      : this.selectExtensionTarget(targetBrowser, targetProfile, targetExtension);
 
     if (!target) {
       if (usesBaselineOwner) {
@@ -1339,9 +1370,12 @@ export class BridgeDaemon {
         request.id,
         ERROR_CODES.EXTENSION_DISCONNECTED,
         hasExplicitTarget
-          ? `No connected extension matches target_browser="${targetBrowser ?? '*'}" target_profile="${targetProfile ?? '*'}".`
+          ? `No connected extension matches target_browser="${targetBrowser ?? '*'}" target_profile="${targetProfile ?? '*'}" target_extension="${targetExtension ?? '*'}".`
           : 'The Chrome extension is not connected to the local bridge daemon.',
-        null,
+        {
+          reason: hasExplicitTarget ? 'browser_target_disconnected' : 'extension_disconnected',
+          connectedExtensions: this.getConnectedExtensionsSnapshot(),
+        },
         { method: request.method }
       );
       await writeJsonLine(socket, { type: 'agent.response', response });
@@ -1418,11 +1452,13 @@ export class BridgeDaemon {
    *
    * @param {string | null} targetBrowser
    * @param {string | null} targetProfile
+   * @param {string | null} [targetExtension]
    * @returns {ClientSocket | null}
    */
-  selectExtensionTarget(targetBrowser, targetProfile) {
-    const candidates = Array.from(this.extensionSockets.entries()).filter(([, extSocket]) => {
+  selectExtensionTarget(targetBrowser, targetProfile, targetExtension = null) {
+    const candidates = Array.from(this.extensionSockets.entries()).filter(([id, extSocket]) => {
       return (
+        (!targetExtension || id === targetExtension) &&
         (!targetBrowser || extSocket.__browserName === targetBrowser) &&
         (!targetProfile || extSocket.__profileLabel === targetProfile)
       );

package/packages/protocol/src/budget-presets.js

@@ -133,7 +133,9 @@ export function applyMethodBudgetPreset(method, params, budgetPreset) {
   const args = { ...params, budgetPreset };
   /** @type {Record<string, unknown>} */
   let normalized = args;
-  if (
+  if (method === 'webmcp.list_tools') {
+    normalized = applyLimitBudgetPreset(args, { quick: 5, normal: 20, deep: 100 });
+  } else if (
     method === 'dom.query' ||
     method === 'dom.get_accessibility_tree' ||
     method === 'dom.baseline.create'

package/packages/protocol/src/errors.js

@@ -3,6 +3,11 @@
 /** @typedef {import('./types.js').ErrorCode} ErrorCode */
 
 export const ERROR_CODES = Object.freeze({
+  WEBMCP_UNAVAILABLE: 'WEBMCP_UNAVAILABLE',
+  WEBMCP_TOOL_STALE: 'WEBMCP_TOOL_STALE',
+  WEBMCP_BUSY: 'WEBMCP_BUSY',
+  WEBMCP_APPROVAL_DENIED: 'WEBMCP_APPROVAL_DENIED',
+  WEBMCP_EXECUTION_UNCERTAIN: 'WEBMCP_EXECUTION_UNCERTAIN',
   ACCESS_DENIED: 'ACCESS_DENIED',
   TAB_MISMATCH: 'TAB_MISMATCH',
   ELEMENT_STALE: 'ELEMENT_STALE',
@@ -38,6 +43,27 @@ export const ERROR_CODES = Object.freeze({
  * @type {Readonly<Record<string, { retry: boolean, retryAfterMs?: number, alternativeMethod?: string, hint: string }>>}
  */
 export const ERROR_RECOVERY = Object.freeze({
+  [ERROR_CODES.WEBMCP_UNAVAILABLE]: {
+    retry: false,
+    hint: 'This document does not expose the current WebMCP consumer API. Use structured DOM/input methods; do not enable flags or inject a polyfill without user permission.',
+  },
+  [ERROR_CODES.WEBMCP_TOOL_STALE]: {
+    retry: false,
+    alternativeMethod: 'webmcp.list_tools',
+    hint: 'The tool reference expired or its document, catalog, or access session changed. Discover and inspect a fresh tool before a new deliberate action.',
+  },
+  [ERROR_CODES.WEBMCP_BUSY]: {
+    retry: false,
+    hint: 'Another WebMCP execution or approval is pending. Wait and inspect postconditions; a timed-out callback may still be running.',
+  },
+  [ERROR_CODES.WEBMCP_APPROVAL_DENIED]: {
+    retry: false,
+    hint: 'User approval was denied, closed, expired, or revoked. No tool was dispatched. Do not repeat the request unless the user asks.',
+  },
+  [ERROR_CODES.WEBMCP_EXECUTION_UNCERTAIN]: {
+    retry: false,
+    hint: 'The tool may have executed. Inspect DOM/page postconditions before another deliberate action. Never automatically retry or repeat the action through DOM input.',
+  },
   [ERROR_CODES.ACCESS_DENIED]: {
     retry: false,
     hint: 'Access is off for this window. Ask the user to click Enable in the Browser Bridge popup or side panel. Do not request access again until that window is enabled.',

package/packages/protocol/src/index.js

@@ -17,3 +17,5 @@ export * from './protocol.js';
 export * from './registry.js';
 export * from './recovery-telemetry.js';
 export * from './summary.js';
+export * from './tab-list.js';
+export * from './webmcp.js';

package/packages/protocol/src/protocol.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import { applyBudget } from './budget.js';
+import { normalizeWebMcpParams } from './webmcp.js';
 import {
   ARTIFACT_CHUNK_BYTES,
   BUDGET_PRESETS,
@@ -296,15 +297,22 @@ export function createSuccess(id, result, meta = {}) {
  * @returns {BridgeFailureResponse}
  */
 export function createFailure(id, code, message, details = null, meta = {}) {
-  const recovery = getErrorRecovery(code);
+  const recovery = getRoutingRecovery(code, details) ?? getErrorRecovery(code);
   const effectiveRecovery =
-    recovery && meta.method === 'sensitive.read'
+    meta.method === 'webmcp.execute_tool'
       ? {
           retry: false,
-          ...(recovery.alternativeMethod ? { alternativeMethod: recovery.alternativeMethod } : {}),
-          hint: `Sensitive reads are never retried automatically. ${recovery.hint}`,
+          hint: 'WebMCP executions are never retried automatically. Inspect postconditions if dispatch may have started; never replay through DOM fallback.',
         }
-      : recovery;
+      : recovery && meta.method === 'sensitive.read'
+        ? {
+            retry: false,
+            ...(recovery.alternativeMethod
+              ? { alternativeMethod: recovery.alternativeMethod }
+              : {}),
+            hint: `Sensitive reads are never retried automatically. ${recovery.hint}`,
+          }
+        : recovery;
   return {
     id,
     ok: false,
@@ -322,6 +330,35 @@ export function createFailure(id, code, message, details = null, meta = {}) {
   };
 }
 
+/**
+ * Routing errors need selection guidance, not closed-tab or global enable hints.
+ * @param {import('./types.js').ErrorCode} code
+ * @param {unknown} details
+ * @returns {import('./types.js').BridgeRecovery | null}
+ */
+function getRoutingRecovery(code, details) {
+  const reason =
+    details && typeof details === 'object' && 'reason' in details ? details.reason : null;
+  if (
+    (code === ERROR_CODES.TAB_MISMATCH && reason === 'ambiguous_browser_target') ||
+    (code === ERROR_CODES.EXTENSION_DISCONNECTED && reason === 'browser_target_disconnected')
+  ) {
+    return {
+      retry: false,
+      alternativeMethod: 'health.ping',
+      hint: 'Discover connectedExtensions with health.ping or list enabled profiles with MCP tabs.list. Select extensionId and tabId for the intended page. Do not disable unrelated windows or fall back to another profile.',
+    };
+  }
+  if (code === ERROR_CODES.ACCESS_DENIED && reason === 'no_enabled_browser_profiles') {
+    return {
+      retry: false,
+      alternativeMethod: 'health.ping',
+      hint: "Choose the intended extensionId from connectedExtensions before requesting access. Ask the user to enable only that profile's window.",
+    };
+  }
+  return null;
+}
+
 /**
  * @param {unknown} request
  * @returns {BridgeRequest}
@@ -409,6 +446,7 @@ export function validateBridgeRequest(request) {
     params: normalizeRequestParams(method, params),
     meta: {
       ...meta,
+      ...normalizeBrowserTargetMeta(meta),
       protocol_version:
         typeof meta.protocol_version === 'string' ? meta.protocol_version : getProtocolVersion(),
       token_budget: typeof meta.token_budget === 'number' ? meta.token_budget : null,
@@ -424,6 +462,37 @@ export function validateBridgeRequest(request) {
   };
 }
 
+/**
+ * Never turn a malformed explicit selector into implicit routing.
+ * @param {Record<string, unknown>} meta
+ * @returns {Pick<BridgeMeta, 'target_extension' | 'target_browser' | 'target_profile'>}
+ */
+function normalizeBrowserTargetMeta(meta) {
+  /** @type {Pick<BridgeMeta, 'target_extension' | 'target_browser' | 'target_profile'>} */
+  const target = {};
+  for (const field of /** @type {const} */ ([
+    'target_extension',
+    'target_browser',
+    'target_profile',
+  ])) {
+    const value = meta[field];
+    if (value === undefined) continue;
+    if (
+      typeof value !== 'string' ||
+      !value.trim() ||
+      value.length > 256 ||
+      hasAsciiControlCharacters(value)
+    ) {
+      throw new BridgeError(
+        ERROR_CODES.INVALID_REQUEST,
+        `meta.${field} must be a non-empty string of at most 256 characters without control characters.`
+      );
+    }
+    target[field] = value.trim();
+  }
+  return target;
+}
+
 /** @param {string} value @returns {boolean} */
 function hasAsciiControlCharacters(value) {
   for (let index = 0; index < value.length; index += 1) {
@@ -470,6 +539,15 @@ function normalizeAutomaticRetryMeta(source, value) {
  */
 export function normalizeRequestParams(method, params) {
   switch (method) {
+    case 'webmcp.list_tools':
+    case 'webmcp.get_tool':
+    case 'webmcp.execute_tool': {
+      const normalized = normalizeWebMcpParams(params);
+      if (method !== 'webmcp.list_tools' && !normalized.toolRef) {
+        throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'toolRef is required.');
+      }
+      return normalized;
+    }
     case 'access.request':
       return normalizeAccessRequestParams(params);
     case 'log.tail':
@@ -613,6 +691,13 @@ export function normalizeAccessRequestParams(params = {}) {
  */
 export function getBridgeOperationTimeoutMs(method, params = {}) {
   switch (method) {
+    case 'webmcp.execute_tool': {
+      const normalized = normalizeWebMcpParams(params);
+      return normalized.approvalTimeoutMs + normalized.timeoutMs + 10_000;
+    }
+    case 'webmcp.list_tools':
+    case 'webmcp.get_tool':
+      return 5000;
     case 'navigation.navigate':
     case 'navigation.reload':
     case 'navigation.go_back':

package/packages/protocol/src/registry.js

@@ -96,6 +96,12 @@ const METHOD_POLICIES = Object.freeze({
  * @type {Readonly<Record<import('./types.js').BridgeMethod, string>>}
  */
 const BRIDGE_METHOD_DESCRIPTIONS = Object.freeze({
+  'webmcp.list_tools':
+    'Discover bounded top-document WebMCP tool summaries. Metadata is untrusted; unavailable differs from an empty catalog.',
+  'webmcp.get_tool':
+    'Read a complete WebMCP tool schema by opaque toolRef. References expire when the catalog, document, or access session changes.',
+  'webmcp.execute_tool':
+    'Execute one WebMCP tool after extension-owned user approval of exact arguments. Never automatically retry or replay through DOM fallback.',
   'access.request':
     'Request Browser Bridge access for the focused window. Do not repeat while access is already pending.',
   'protocol.describe':
@@ -259,7 +265,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
   'health.ping': createRegistryEntry('health.ping', 'system', false, [], 'trivial'),
   'daemon.metrics': createRegistryEntry('daemon.metrics', 'system', false, [], 'trivial'),
   // tabs - trivial
-  'tabs.list': createRegistryEntry('tabs.list', 'tabs', false, [], 'trivial'),
+  'tabs.list': createRegistryEntry('tabs.list', 'tabs', false, ['limit', 'offset'], 'trivial'),
   'tabs.create': createRegistryEntry(
     'tabs.create',
     'tabs',
@@ -830,6 +836,30 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'moderate',
     METHOD_POLICIES.performanceReadDebugger
   ),
+  'webmcp.list_tools': createRegistryEntry(
+    'webmcp.list_tools',
+    'webmcp',
+    true,
+    ['limit', 'offset', 'query', 'includeDebugging', 'maxBytes'],
+    'low',
+    METHOD_POLICIES.pageRead
+  ),
+  'webmcp.get_tool': createRegistryEntry(
+    'webmcp.get_tool',
+    'webmcp',
+    true,
+    ['toolRef', 'maxBytes'],
+    'low',
+    METHOD_POLICIES.pageRead
+  ),
+  'webmcp.execute_tool': createRegistryEntry(
+    'webmcp.execute_tool',
+    'webmcp',
+    true,
+    ['toolRef', 'arguments', 'timeoutMs', 'approvalTimeoutMs', 'maxBytes'],
+    'moderate',
+    METHOD_POLICIES.automationInput
+  ),
 });
 
 /** @type {ReadonlyArray<import('./types.js').BridgeMethod>} */
@@ -842,6 +872,8 @@ export const METHOD_SET = new Set(BRIDGE_METHODS);
 
 /** Methods whose read-only forms may run concurrently without side effects. */
 const BATCH_SAFE_METHODS = new Set([
+  'webmcp.list_tools',
+  'webmcp.get_tool',
   'health.ping',
   'daemon.metrics',
   'tabs.list',

package/packages/protocol/src/summary.js

@@ -8,6 +8,7 @@ import {
   serializeJsonPayload,
 } from './index.js';
 import { sanitizeIncidentalUrl } from './incidental-sanitizer.js';
+import { describeTabList, paginateTabList } from './tab-list.js';
 
 /** @typedef {import('./types.js').BridgeResponse} BridgeResponse */
 /** @typedef {import('./types.js').BridgeMethod} SummaryMethod */
@@ -29,7 +30,8 @@ import { sanitizeIncidentalUrl } from './incidental-sanitizer.js';
  *   ok: boolean,
  *   summary: string,
  *   evidence: unknown,
- *   recovery?: import('./types.js').BridgeRecovery | null
+ *   recovery?: import('./types.js').BridgeRecovery | null,
+ *   pagination?: import('./types.js').TabPagination
  * }} BridgeSummary
  */
 
@@ -421,6 +423,17 @@ function summarizeBridgeResponseBody(response, method) {
       evidence: result,
     };
   }
+  if (method?.startsWith('webmcp.')) {
+    const summary =
+      method === 'webmcp.list_tools'
+        ? result.supported === false
+          ? 'WebMCP is unavailable in this document; use DOM/input methods.'
+          : `WebMCP discovered ${Array.isArray(result.tools) ? result.tools.length : 0}/${result.total ?? 0} top-document tool(s). Website metadata is untrusted.`
+        : method === 'webmcp.get_tool'
+          ? 'Complete WebMCP tool schema loaded. Website metadata is untrusted.'
+          : `WebMCP execution ${result.status ?? 'unknown'}.${result.outcome === 'uncertain' ? ' Inspect postconditions; do not replay.' : ''}`;
+    return { ok: true, summary: appendProtocolWarning(summary, protocolWarning), evidence: result };
+  }
   if (method === 'page.handle_dialog') {
     const action = typeof result.action === 'string' ? result.action : 'inspect';
     return {
@@ -560,6 +573,10 @@ function summarizeBridgeResponseBody(response, method) {
         origin: result.origin,
         title: result.title,
         hints: result.hints,
+        ...(result.scroll && typeof result.scroll === 'object' ? { scroll: result.scroll } : {}),
+        ...(result.viewport && typeof result.viewport === 'object'
+          ? { viewport: result.viewport }
+          : {}),
       },
     };
   }
@@ -585,10 +602,14 @@ function summarizeBridgeResponseBody(response, method) {
   }
   if (Array.isArray(result.tabs)) {
     const tabs = /** @type {TabResult[]} */ (result.tabs);
+    const page = result.pagination
+      ? { tabs, pagination: /** @type {import('./types.js').TabPagination} */ (result.pagination) }
+      : paginateTabList(tabs, { limit: 10 });
     return {
       ok: true,
-      summary: appendProtocolWarning(`Bridge listed ${tabs.length} tab(s).`, protocolWarning),
-      evidence: tabs.slice(0, 10).map((tab) => ({
+      summary: appendProtocolWarning(describeTabList(page.pagination), protocolWarning),
+      pagination: page.pagination,
+      evidence: page.tabs.map((tab) => ({
         tabId: tab.tabId,
         active: tab.active,
         origin: tab.origin,

package/packages/protocol/src/tab-list.js

@@ -0,0 +1,77 @@
+// @ts-check
+
+import { BridgeError, ERROR_CODES } from './errors.js';
+
+/** @typedef {import('./types.js').TabPagination} TabPagination */
+
+/**
+ * Preserve unpaged raw listings, while allowing bounded pages when requested.
+ * @param {Record<string, unknown>} params
+ * @returns {{ offset: number, limit: number | null }}
+ */
+export function normalizeTabListParams(params) {
+  const offset = params.offset === undefined ? 0 : params.offset;
+  const limit =
+    params.limit === undefined ? (params.offset === undefined ? null : 10) : params.limit;
+  if (typeof offset !== 'number' || !Number.isSafeInteger(offset) || offset < 0) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'tabs.list offset must be a non-negative integer.'
+    );
+  }
+  if (
+    (params.limit !== undefined || limit !== null) &&
+    (typeof limit !== 'number' || !Number.isInteger(limit) || limit < 1 || limit > 100)
+  ) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'tabs.list limit must be an integer from 1 to 100.'
+    );
+  }
+  return { offset, limit };
+}
+
+/**
+ * @param {number} totalCount
+ * @param {number} returnedCount
+ * @param {number} offset
+ * @returns {TabPagination}
+ */
+export function describeTabPage(totalCount, returnedCount, offset) {
+  return {
+    totalCount,
+    returnedCount,
+    offset,
+    omittedCount: Math.max(0, totalCount - returnedCount),
+    truncated: returnedCount < totalCount,
+    nextOffset: offset + returnedCount < totalCount ? offset + returnedCount : null,
+  };
+}
+
+/**
+ * @template T
+ * @param {T[]} tabs
+ * @param {Record<string, unknown>} [params]
+ * @returns {{ tabs: T[], pagination: TabPagination }}
+ */
+export function paginateTabList(tabs, params = {}) {
+  const { offset, limit } = normalizeTabListParams(params);
+  const sorted = [...tabs].sort((left, right) => {
+    /** @param {unknown} tab @returns {number} */
+    const priority = (tab) => {
+      const record =
+        tab && typeof tab === 'object' ? /** @type {Record<string, unknown>} */ (tab) : {};
+      return Number(record.working === true || record.active === true);
+    };
+    return priority(right) - priority(left);
+  });
+  const page = sorted.slice(offset, limit === null ? undefined : offset + limit);
+  return { tabs: page, pagination: describeTabPage(tabs.length, page.length, offset) };
+}
+
+/** @param {TabPagination} page @returns {string} */
+export function describeTabList(page) {
+  return page.truncated
+    ? `Bridge listed ${page.totalCount} tab(s); showing ${page.returnedCount} at offset ${page.offset}, ${page.omittedCount} omitted. Use tabs.list with limit and offset to retrieve another page.`
+    : `Bridge listed ${page.totalCount} tab(s).`;
+}