@browserbridge/bbx 1.2.0 → 1.4.0

package/packages/protocol/src/types.ts

@@ -0,0 +1,574 @@
+export type BridgeRequestSource = 'cli' | 'mcp';
+
+export type Capability =
+  | 'page.read'
+  | 'page.evaluate'
+  | 'dom.read'
+  | 'styles.read'
+  | 'layout.read'
+  | 'viewport.control'
+  | 'navigation.control'
+  | 'screenshot.partial'
+  | 'patch.dom'
+  | 'patch.styles'
+  | 'cdp.dom_snapshot'
+  | 'cdp.box_model'
+  | 'cdp.styles'
+  | 'cdp.input'
+  | 'automation.input'
+  | 'tabs.manage'
+  | 'performance.read'
+  | 'network.read';
+
+export type ErrorCode =
+  | 'ACCESS_DENIED'
+  | 'TAB_MISMATCH'
+  | 'ELEMENT_STALE'
+  | 'RESULT_TRUNCATED'
+  | 'RATE_LIMITED'
+  | 'INTERNAL_ERROR'
+  | 'INVALID_REQUEST'
+  | 'NATIVE_HOST_UNAVAILABLE'
+  | 'EXTENSION_DISCONNECTED'
+  | 'TIMEOUT';
+
+export type BridgeMethod =
+  | 'access.request'
+  | 'tabs.list'
+  | 'tabs.create'
+  | 'tabs.close'
+  | 'skill.get_runtime_context'
+  | 'setup.get_status'
+  | 'setup.install'
+  | 'page.get_state'
+  | 'page.evaluate'
+  | 'page.get_console'
+  | 'page.wait_for_load_state'
+  | 'page.get_storage'
+  | 'page.get_text'
+  | 'page.get_network'
+  | 'navigation.navigate'
+  | 'navigation.reload'
+  | 'navigation.go_back'
+  | 'navigation.go_forward'
+  | 'dom.query'
+  | 'dom.describe'
+  | 'dom.get_text'
+  | 'dom.get_attributes'
+  | 'dom.wait_for'
+  | 'dom.find_by_text'
+  | 'dom.find_by_role'
+  | 'dom.get_html'
+  | 'dom.get_accessibility_tree'
+  | 'layout.get_box_model'
+  | 'layout.hit_test'
+  | 'styles.get_computed'
+  | 'styles.get_matched_rules'
+  | 'viewport.scroll'
+  | 'viewport.resize'
+  | 'input.click'
+  | 'input.focus'
+  | 'input.type'
+  | 'input.press_key'
+  | 'input.set_checked'
+  | 'input.select_option'
+  | 'input.hover'
+  | 'input.drag'
+  | 'input.scroll_into_view'
+  | 'screenshot.capture_region'
+  | 'screenshot.capture_element'
+  | 'screenshot.capture_full_page'
+  | 'patch.apply_styles'
+  | 'patch.apply_dom'
+  | 'patch.list'
+  | 'patch.rollback'
+  | 'patch.commit_session_baseline'
+  | 'cdp.get_document'
+  | 'cdp.get_dom_snapshot'
+  | 'cdp.get_box_model'
+  | 'cdp.get_computed_styles_for_node'
+  | 'cdp.dispatch_key_event'
+  | 'performance.get_metrics'
+  | 'log.tail'
+  | 'health.ping'
+  | 'daemon.metrics';
+
+export type CostClass = 'cheap' | 'moderate' | 'heavy' | 'extreme';
+
+export interface BridgeMeta {
+  protocol_version?: string;
+  token_budget?: number | null;
+  transport_bytes?: number;
+  transport_approx_tokens?: number;
+  transport_cost_class?: CostClass;
+  text_bytes?: number;
+  text_approx_tokens?: number;
+  text_cost_class?: CostClass;
+  image_approx_tokens?: number;
+  image_bytes?: number;
+  source?: BridgeRequestSource;
+  response_bytes?: number;
+  approx_tokens?: number;
+  cost_class?: CostClass;
+  debugger_backed?: boolean;
+  budget_applied?: boolean;
+  budget_truncated?: boolean;
+  continuation_hint?: string | null;
+  [key: string]: unknown;
+}
+
+export interface BridgeParams {
+  [key: string]: unknown;
+}
+
+export interface BridgeRequest {
+  id: string;
+  method: BridgeMethod;
+  tab_id: number | null;
+  params: BridgeParams;
+  meta: Required<Pick<BridgeMeta, 'protocol_version' | 'token_budget'>> & Record<string, unknown>;
+}
+
+export interface BridgeRecovery {
+  hint: string;
+  retry?: boolean;
+  retryAfterMs?: number;
+}
+
+export interface BridgeFailure {
+  code: ErrorCode;
+  message: string;
+  details: unknown;
+  recovery?: BridgeRecovery;
+}
+
+export interface BridgeSuccessResponse {
+  id: string;
+  ok: true;
+  result: unknown;
+  error: null;
+  meta: { protocol_version: string } & Record<string, unknown>;
+}
+
+export interface BridgeFailureResponse {
+  id: string;
+  ok: false;
+  result: null;
+  error: BridgeFailure;
+  meta: { protocol_version: string } & Record<string, unknown>;
+}
+
+export type BridgeResponse = BridgeSuccessResponse | BridgeFailureResponse;
+
+export interface BudgetOptions {
+  maxNodes?: number;
+  maxDepth?: number;
+  textBudget?: number;
+  includeBbox?: boolean;
+  attributeAllowlist?: string[];
+}
+
+export interface Budget {
+  maxNodes: number;
+  maxDepth: number;
+  textBudget: number;
+  includeBbox: boolean;
+  attributeAllowlist: string[];
+}
+
+export interface TruncateResult {
+  value: string;
+  truncated: boolean;
+  omitted: number;
+}
+
+export interface DomQueryParams extends BudgetOptions {
+  selector?: string;
+  withinRef?: string | null;
+}
+
+export interface NormalizedDomQuery extends BridgeParams {
+  selector: string;
+  withinRef: string | null;
+  budget: Budget;
+}
+
+export interface StyleQueryParams {
+  elementRef?: string;
+  target?: InputTarget;
+  properties?: string[];
+}
+
+export interface NormalizedStyleQuery extends BridgeParams {
+  elementRef: string;
+  target: InputTarget;
+  properties: string[];
+}
+
+export interface InputTarget {
+  elementRef?: string;
+  selector?: string;
+}
+
+export interface InputActionParams {
+  target?: InputTarget;
+  button?: 'left' | 'middle' | 'right';
+  clickCount?: number;
+  text?: string;
+  clear?: boolean;
+  submit?: boolean;
+  key?: string;
+  modifiers?: string[];
+}
+
+export interface NormalizedInputAction extends BridgeParams {
+  target: InputTarget;
+  button: 'left' | 'middle' | 'right';
+  clickCount: number;
+  text: string;
+  clear: boolean;
+  submit: boolean;
+  key: string;
+  modifiers: string[];
+}
+
+export interface CdpDispatchKeyEventParams {
+  key?: string;
+  code?: string;
+  modifiers?: string[] | number;
+}
+
+export interface CdpNodeIdParams {
+  nodeId?: number;
+}
+
+export interface NormalizedCdpDispatchKeyEventParams extends BridgeParams {
+  key: string;
+  code: string;
+  modifiers: string[] | number;
+}
+
+export interface NormalizedCdpNodeIdParams extends BridgeParams {
+  nodeId: number;
+}
+
+export interface CheckedActionParams {
+  target?: InputTarget;
+  checked?: boolean;
+}
+
+export interface NormalizedCheckedAction extends BridgeParams {
+  target: InputTarget;
+  checked: boolean;
+}
+
+export interface SelectActionParams {
+  target?: InputTarget;
+  values?: string[];
+  labels?: string[];
+  indexes?: number[];
+}
+
+export interface NormalizedSelectAction extends BridgeParams {
+  target: InputTarget;
+  values: string[];
+  labels: string[];
+  indexes: number[];
+}
+
+export interface ViewportActionParams {
+  target?: InputTarget;
+  top?: number;
+  left?: number;
+  behavior?: 'auto' | 'smooth';
+  relative?: boolean;
+}
+
+export interface NormalizedViewportAction extends BridgeParams {
+  target: InputTarget;
+  top: number;
+  left: number;
+  behavior: 'auto' | 'smooth';
+  relative: boolean;
+}
+
+export interface NavigationActionParams {
+  url?: string;
+  waitForLoad?: boolean;
+  timeoutMs?: number;
+}
+
+export interface NormalizedNavigationAction extends BridgeParams {
+  url: string;
+  waitForLoad: boolean;
+  timeoutMs: number;
+}
+
+export interface PatchOperationParams {
+  patchId?: string | null;
+  target?: Record<string, unknown>;
+  operation?: string | null;
+  name?: string | null;
+  declarations?: Record<string, string>;
+  value?: unknown;
+  important?: boolean;
+  verify?: boolean;
+}
+
+export interface NormalizedPatchOperation extends BridgeParams {
+  patchId: string | null;
+  target: Record<string, unknown>;
+  operation: string | null;
+  name: string | null;
+  declarations: Record<string, string>;
+  value: unknown;
+  important: boolean;
+  verify: boolean;
+}
+
+export interface McpClientStatus {
+  key: string;
+  label: string;
+  detected: boolean;
+  configPath: string;
+  configExists: boolean;
+  configured: boolean;
+}
+
+export interface SkillInstallationStatus {
+  name: string;
+  path: string;
+  exists: boolean;
+  managed: boolean;
+  version: string | null;
+}
+
+export interface SkillTargetStatus {
+  key: string;
+  label: string;
+  detected: boolean;
+  basePath: string;
+  installed: boolean;
+  managed: boolean;
+  installedVersion: string | null;
+  currentVersion: string | null;
+  updateAvailable: boolean;
+  skills: SkillInstallationStatus[];
+}
+
+export interface SetupStatus {
+  scope: 'global' | 'local';
+  mcpClients: McpClientStatus[];
+  skillTargets: SkillTargetStatus[];
+}
+
+export interface SetupInstallParams {
+  action?: 'install' | 'uninstall';
+  kind?: 'mcp' | 'skill';
+  target?: string;
+}
+
+export interface SetupInstallResult {
+  action: 'install' | 'uninstall';
+  kind: 'mcp' | 'skill';
+  target: string;
+  paths: string[];
+}
+
+export interface EvaluateParams {
+  expression?: string;
+  awaitPromise?: boolean;
+  timeoutMs?: number;
+  returnByValue?: boolean;
+}
+
+export interface NormalizedEvaluateParams extends BridgeParams {
+  expression: string;
+  awaitPromise: boolean;
+  timeoutMs: number;
+  returnByValue: boolean;
+}
+
+export interface ConsoleParams {
+  level?: string;
+  clear?: boolean;
+  limit?: number;
+}
+
+export interface NormalizedConsoleParams extends BridgeParams {
+  level: string;
+  clear: boolean;
+  limit: number;
+}
+
+export interface WaitForParams {
+  selector?: string;
+  text?: string;
+  state?: 'attached' | 'detached' | 'visible' | 'hidden';
+  timeoutMs?: number;
+}
+
+export interface NormalizedWaitForParams extends BridgeParams {
+  selector: string;
+  text: string | null;
+  state: 'attached' | 'detached' | 'visible' | 'hidden';
+  timeoutMs: number;
+}
+
+export interface FindByTextParams {
+  text?: string;
+  exact?: boolean;
+  selector?: string;
+  maxResults?: number;
+}
+
+export interface NormalizedFindByTextParams extends BridgeParams {
+  text: string;
+  exact: boolean;
+  selector: string;
+  maxResults: number;
+}
+
+export interface FindByRoleParams {
+  role?: string;
+  name?: string;
+  selector?: string;
+  maxResults?: number;
+}
+
+export interface NormalizedFindByRoleParams extends BridgeParams {
+  role: string;
+  name: string;
+  selector: string;
+  maxResults: number;
+}
+
+export interface GetHtmlParams {
+  elementRef?: string;
+  target?: InputTarget;
+  outer?: boolean;
+  maxLength?: number;
+}
+
+export interface NormalizedGetHtmlParams extends BridgeParams {
+  elementRef: string;
+  target: InputTarget;
+  outer: boolean;
+  maxLength: number;
+}
+
+export interface HoverParams {
+  target?: InputTarget;
+  duration?: number;
+  modifiers?: string[];
+}
+
+export interface NormalizedHoverParams extends BridgeParams {
+  target: InputTarget;
+  duration: number;
+  modifiers: string[];
+}
+
+export interface DragParams {
+  source?: InputTarget;
+  destination?: InputTarget;
+  offsetX?: number;
+  offsetY?: number;
+}
+
+export interface NormalizedDragParams extends BridgeParams {
+  source: InputTarget;
+  destination: InputTarget;
+  offsetX: number;
+  offsetY: number;
+}
+
+export interface StorageParams {
+  type?: 'local' | 'session';
+  keys?: string[];
+}
+
+export interface NormalizedStorageParams extends BridgeParams {
+  type: 'local' | 'session';
+  keys: string[] | null;
+}
+
+export interface WaitForLoadStateParams {
+  waitForLoad?: boolean;
+  timeoutMs?: number;
+}
+
+export interface NormalizedWaitForLoadStateParams extends BridgeParams {
+  waitForLoad: boolean;
+  timeoutMs: number;
+}
+
+export interface TabCreateParams {
+  url?: string;
+  active?: boolean;
+}
+
+export interface NormalizedTabCreateParams extends BridgeParams {
+  url: string;
+  active: boolean;
+}
+
+export interface TabCloseParams {
+  tabId?: number;
+}
+
+export interface NormalizedTabCloseParams extends BridgeParams {
+  tabId: number;
+}
+
+export interface AccessibilityTreeParams {
+  maxDepth?: number;
+  maxNodes?: number;
+}
+
+export interface NormalizedAccessibilityTreeParams extends BridgeParams {
+  maxDepth: number;
+  maxNodes: number;
+}
+
+export interface NetworkParams {
+  clear?: boolean;
+  limit?: number;
+  urlPattern?: string;
+}
+
+export interface NormalizedNetworkParams extends BridgeParams {
+  clear: boolean;
+  limit: number;
+  urlPattern: string | null;
+}
+
+export interface PageTextParams {
+  textBudget?: number;
+}
+
+export interface NormalizedPageTextParams extends BridgeParams {
+  textBudget: number;
+}
+
+export interface LogTailParams {
+  limit?: number;
+}
+
+export interface NormalizedLogTailParams extends BridgeParams {
+  limit: number;
+}
+
+export interface ViewportResizeParams {
+  width?: number;
+  height?: number;
+  deviceScaleFactor?: number;
+  reset?: boolean;
+}
+
+export interface NormalizedViewportResizeParams extends BridgeParams {
+  width: number;
+  height: number;
+  deviceScaleFactor: number;
+  reset: boolean;
+}

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.'

package/skills/browser-bridge/references/interaction.md

@@ -32,7 +32,7 @@ bbx call navigation.go_forward
 
 ```bash
 bbx call viewport.scroll '{"top":640,"behavior":"smooth"}'
-bbx call viewport.scroll '{"elementRef":"el_123","top":200}'
+bbx call viewport.scroll '{"target":{"elementRef":"el_123"},"top":200}'
 ```
 
 Scrolls the window or a specific scrollable element.
@@ -125,10 +125,10 @@ bbx scroll 640              # scroll down 640px
 bbx scroll 0 200            # scroll right 200px
 bbx scroll 0                # scroll to top (top=0)
 bbx call viewport.scroll '{"top":640,"behavior":"smooth"}'
-bbx call viewport.scroll '{"elementRef":"el_123","top":200}'
+bbx call viewport.scroll '{"target":{"elementRef":"el_123"},"top":200}'
 ```
 
-Scrolls the window by default. Pass an `elementRef` to scroll an inner scrollable container.
+Scrolls the window by default. Pass `target: { elementRef }` to scroll an inner scrollable container.
 
 ### Scroll target into view
 
@@ -205,7 +205,7 @@ bbx call input.drag '{"source":{"elementRef":"el_src"},"destination":{"elementRe
 With pixel offsets for precise positioning:
 
 ```bash
-bbx call input.drag '{"source":{"elementRef":"el_src"},"destination":{"elementRef":"el_dst"},"sourceOffset":{"x":10,"y":10},"destinationOffset":{"x":5,"y":5}}'
+bbx call input.drag '{"source":{"elementRef":"el_src"},"destination":{"elementRef":"el_dst"},"offsetX":5,"offsetY":5}'
 ```
 
 Event sequence: `mousedown → dragstart → drag → dragenter → dragover → drop → dragend → mouseup`.
@@ -225,10 +225,10 @@ Find elements matching visible text. Faster than `dom.query` when you know the l
 
 ```bash
 bbx find 'Submit Order'
-bbx call dom.find_by_text '{"text":"Add to Cart","scope":"button","exact":false}'
+bbx call dom.find_by_text '{"text":"Add to Cart","selector":"button","exact":false}'
 ```
 
-- `scope`: optional CSS selector to narrow search (e.g. `"button"`, `".sidebar"`)
+- `selector`: optional CSS selector to narrow search (e.g. `"button"`, `".sidebar"`)
 - `exact`: `true` for exact match, `false` (default) for substring/case-insensitive
 
 ### By ARIA role