@browserbridge/bbx 1.11.3 → 1.12.0

package/packages/protocol/src/summary.js

@@ -56,12 +56,192 @@ import { sanitizeIncidentalUrl } from './incidental-sanitizer.js';
  * }} BatchItemSummary
  */
 
+/** Evaluate values longer than this stay out of the summary; evidence holds them. */
+const MAX_EVALUATE_SUMMARY_CHARS = 160;
+const EVALUATE_PREVIEW_CHARS = 80;
+
+/**
+ * Keep evaluate summaries short: small values inline, larger ones as a shape
+ * description, because the full value is already delivered in evidence.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+function summarizeEvaluateValue(value) {
+  const json = JSON.stringify(value) ?? String(value);
+  if (json.length <= MAX_EVALUATE_SUMMARY_CHARS) return json;
+  const shape = Array.isArray(value)
+    ? `${value.length} item(s)`
+    : value && typeof value === 'object'
+      ? `${Object.keys(value).length} key(s)`
+      : `${json.length} chars`;
+  return `${shape}, ${json.length} chars as JSON; full value in evidence.value`;
+}
+
+/**
+ * @param {string | undefined} method
+ * @param {Record<string, unknown>} result
+ * @returns {string}
+ */
+function describeTabResult(method, result) {
+  const url = typeof result.url === 'string' && result.url ? ` (${result.url})` : '';
+  switch (method) {
+    case 'navigation.reload':
+      return `Reloaded tab ${result.tabId}${url}.`;
+    case 'navigation.go_back':
+      return `Navigated back in tab ${result.tabId}${url}.`;
+    case 'navigation.go_forward':
+      return `Navigated forward in tab ${result.tabId}${url}.`;
+    case 'tabs.activate':
+      return `Tab ${result.tabId} activated${url}.`;
+    case 'page.wait_for_load_state':
+      return `Tab ${result.tabId} ${typeof result.status === 'string' ? result.status : 'ready'}${url}.`;
+    default:
+      return `Tab ${result.tabId} created${url}.`;
+  }
+}
+
+const ROUTINE_STRATEGIES = new Set(['elementRef', 'selector-first', 'locator-first']);
+
+/**
+ * Keep input evidence lean: resolution/execution metadata only when something
+ * notable happened (scroll, wait, ranking, recovery, CDP, fallback), plus any
+ * observed effects. Routine successes cost a few tokens instead of ~100.
+ *
+ * @param {Record<string, unknown>} r
+ * @param {Record<string, unknown>} [extra]
+ * @returns {Record<string, unknown>}
+ */
+function compactInputEvidence(r, extra = {}) {
+  /** @type {Record<string, unknown>} */
+  const evidence = { elementRef: r.elementRef ?? null, ...extra };
+  const resolution = toRecord(r.resolution);
+  if (
+    resolution.scrolled === true ||
+    resolution.recovered === true ||
+    (typeof resolution.waitedMs === 'number' && resolution.waitedMs > 0) ||
+    (typeof resolution.strategy === 'string' && !ROUTINE_STRATEGIES.has(resolution.strategy))
+  ) {
+    /** @type {Record<string, unknown>} */
+    const notable = { strategy: resolution.strategy };
+    for (const key of ['scrolled', 'recovered', 'waitedMs', 'candidateCount', 'oldRef', 'newRef']) {
+      const value = resolution[key];
+      if (value !== undefined && value !== false && !(key === 'candidateCount' && value === 1)) {
+        notable[key] = value;
+      }
+    }
+    evidence.resolution = notable;
+  }
+  const execution = toRecord(r.execution);
+  if (execution.actualMode === 'cdp' || execution.fallbackReason) {
+    evidence.execution = {
+      actualMode: execution.actualMode,
+      ...(execution.fallbackReason ? { fallbackReason: execution.fallbackReason } : {}),
+    };
+  }
+  if (r.effects && typeof r.effects === 'object') evidence.effects = r.effects;
+  return Object.fromEntries(Object.entries(evidence).filter(([, value]) => value !== undefined));
+}
+
+/**
+ * Health evidence without idle diagnostics: zero-valued recovery counters,
+ * internal latency stats, and idle debugger/capture state are dropped, which
+ * cuts a routine health check from ~1k tokens to ~200.
+ *
+ * @param {Record<string, unknown>} result
+ * @returns {Record<string, unknown>}
+ */
+function compactHealthEvidence(result) {
+  const { recovery, domBaselines, debugger: debuggerState, capture, ...rest } = result;
+  /** @type {Record<string, unknown>} */
+  const evidence = { ...rest };
+  /** @type {Record<string, Record<string, unknown>>} */
+  const activeRecovery = {};
+  for (const [scope, value] of Object.entries(toRecord(recovery))) {
+    const events = toRecord(toRecord(value).events);
+    for (const [event, stats] of Object.entries(events)) {
+      const record = toRecord(stats);
+      if (record.attempts || record.pending || record.activeLoop) {
+        activeRecovery[`${scope}.${event}`] = {
+          attempts: record.attempts,
+          failures: record.failures,
+          ...(record.activeLoop ? { activeLoop: true } : {}),
+        };
+      }
+    }
+  }
+  if (Object.keys(activeRecovery).length) evidence.recovery = activeRecovery;
+  const baselineCount = toRecord(domBaselines).baselineCount;
+  if (typeof baselineCount === 'number' && baselineCount > 0) {
+    evidence.domBaselines = { baselineCount, bytes: toRecord(domBaselines).bytes };
+  }
+  const debuggerRecord = toRecord(debuggerState);
+  if (debuggerState && (debuggerRecord.status !== 'idle' || debuggerRecord.attachedTabCount)) {
+    evidence.debugger = debuggerState;
+  }
+  const captureRecord = toRecord(capture);
+  if (capture && captureRecord.state !== 'stopped') evidence.capture = capture;
+  return evidence;
+}
+
+/**
+ * One-line digest of observed post-action effects.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+function describeEffects(value) {
+  if (!value || typeof value !== 'object') return '';
+  const effects = /** @type {Record<string, unknown>} */ (value);
+  /** @type {string[]} */
+  const parts = [];
+  if (effects.navigation === 'unloading') parts.push('page is navigating');
+  if (typeof effects.url === 'string') parts.push(`URL → ${truncateUrl(effects.url)}`);
+  for (const dialog of Array.isArray(effects.dialogs) ? effects.dialogs : []) {
+    const record = toRecord(dialog);
+    parts.push(
+      `${record.role ?? 'dialog'}${record.name ? ` "${record.name}"` : ''} opened [${record.ref}]`
+    );
+  }
+  for (const message of Array.isArray(effects.messages) ? effects.messages : []) {
+    const record = toRecord(message);
+    parts.push(`${record.role ?? 'status'}: "${record.text}"`);
+  }
+  const focused = toRecord(effects.focused);
+  if (focused.ref)
+    parts.push(
+      `focus → ${focused.role ?? ''}${focused.name ? ` "${focused.name}"` : ''} [${focused.ref}]`
+    );
+  const dom = toRecord(effects.dom);
+  if (typeof dom.added === 'number' || typeof dom.removed === 'number') {
+    parts.push(`DOM +${dom.added ?? 0}/-${dom.removed ?? 0}`);
+  }
+  if (toRecord(effects.target).removed === true) parts.push('target removed');
+  if (!parts.length) return effects.changed === false ? ' No visible effect.' : '';
+  return ` Effects: ${parts.join('; ')}.`;
+}
+
 /** @type {Record<string, ActionSummary>} */
 const ACTION_SUMMARIES = {
-  hovered: {
-    text: (r) => `Hover ${r.hovered ? 'active' : 'failed'} on ${r.elementRef}.`,
+  performed: {
+    text: (r) => {
+      const failures = Array.isArray(r.failures) ? r.failures.length : 0;
+      return `Performed ${r.completed ?? 0}/${r.total ?? 0} step(s) in ${r.elapsedMs ?? 0}ms${failures ? ` with ${failures} failed step(s)` : ''}.`;
+    },
+    evidence: (r) => r,
+  },
+  touched: {
+    text: (r) => {
+      const mode = toRecord(r.execution).actualMode;
+      return `Touched ${r.pointCount ?? 0} point(s)${typeof mode === 'string' ? ` via ${mode}` : ''}.`;
+    },
     evidence: (r) => r,
   },
+  hovered: {
+    text: (r) =>
+      `Hover ${r.hovered ? 'active' : 'failed'} on ${r.elementRef}.${describeEffects(r.effects)}`,
+    evidence: (r) => compactInputEvidence(r),
+  },
   dragged: {
     text: (r) =>
       `Drag ${r.dragged ? 'completed' : 'failed'}: ${r.sourceRef} → ${r.destinationRef}.`,
@@ -71,33 +251,25 @@ const ACTION_SUMMARIES = {
   clicked: {
     text: (r) => {
       const mode = toRecord(r.execution).actualMode;
-      return `Clicked ${r.elementRef ?? 'element'}${typeof mode === 'string' ? ` via ${mode}` : ''}.`;
+      return `Clicked ${r.elementRef ?? 'element'}${typeof mode === 'string' ? ` via ${mode}` : ''}.${describeEffects(r.effects)}`;
     },
-    evidence: (r) => ({
-      elementRef: r.elementRef,
-      resolution: r.resolution,
-      execution: r.execution,
-    }),
+    evidence: (r) => compactInputEvidence(r),
   },
   focused: {
-    text: (r) => `Focused ${r.elementRef ?? 'element'}.`,
-    evidence: (r) => ({
-      elementRef: r.elementRef,
-      resolution: r.resolution,
-      execution: r.execution,
-    }),
+    text: (r) => `Focused ${r.elementRef ?? 'element'}.${describeEffects(r.effects)}`,
+    evidence: (r) => compactInputEvidence(r),
   },
   typed: {
-    text: (r) => `Typed into ${r.elementRef ?? 'element'}.`,
-    evidence: (r) => ({
-      elementRef: r.elementRef,
-      resolution: r.resolution,
-      execution: r.execution,
-    }),
+    text: (r) => `Typed into ${r.elementRef ?? 'element'}.${describeEffects(r.effects)}`,
+    evidence: (r) => compactInputEvidence(r, { value: r.value }),
   },
   pressed: {
-    text: (r) => `Key pressed${r.key ? ` (${r.key})` : ''}.`,
-    evidence: (r) => r,
+    text: (r) => `Key pressed${r.key ? ` (${r.key})` : ''}.${describeEffects(r.effects)}`,
+    evidence: (r) => {
+      const { resolution: _resolution, execution: _execution, effects: _effects, ...rest } = r;
+      const { elementRef: _elementRef, ...compact } = compactInputEvidence(r);
+      return { ...rest, ...compact };
+    },
   },
   navigated: {
     text: (r) => `Navigated to ${r.url ?? 'page'}.`,
@@ -183,6 +355,19 @@ function getMetaCostClass(meta, field) {
  * @returns {BridgeSummary}
  */
 export function summarizeBridgeResponse(response, method) {
+  const summarized = summarizeBridgeResponseBody(response, method);
+  const routingNote = response.ok ? getTabRoutingNote(response.meta) : null;
+  return routingNote
+    ? { ...summarized, summary: `${summarized.summary} ${routingNote}` }
+    : summarized;
+}
+
+/**
+ * @param {BridgeResponse} response
+ * @param {string} [method]
+ * @returns {BridgeSummary}
+ */
+function summarizeBridgeResponseBody(response, method) {
   const protocolWarning = getProtocolWarning(response.meta);
   if (!response.ok) {
     const recovery = response.error.recovery ?? getErrorRecovery(response.error.code);
@@ -291,7 +476,7 @@ export function summarizeBridgeResponse(response, method) {
       access == null
         ? ''
         : access.enabled
-          ? ` Access: ${access.routeReady ? `ready on tab ${access.routeTabId}.` : `enabled${typeof access.reason === 'string' ? ` (${access.reason})` : '.'}`}`
+          ? ` Access: ${access.routeReady ? `ready on tab ${access.routeTabId}.` : `enabled${typeof access.reason === 'string' ? ` (${access.reason})` : '.'}`}${typeof access.workingTabId === 'number' && access.workingTabId !== access.routeTabId ? ` Your working tab is ${access.workingTabId}.` : ''}`
           : ' Access: disabled.';
     const connectedExtensions = Array.isArray(result.connectedExtensions)
       ? /** @type {Array<Record<string, unknown>>} */ (result.connectedExtensions)
@@ -310,7 +495,7 @@ export function summarizeBridgeResponse(response, method) {
         `Daemon: ${result.daemon}. Extension: ${extensionSummary}.${accessSummary}`,
         protocolWarning
       ),
-      evidence: result,
+      evidence: compactHealthEvidence(result),
     };
   }
   if (Array.isArray(result.mcpClients) && Array.isArray(result.skillTargets)) {
@@ -411,6 +596,18 @@ export function summarizeBridgeResponse(response, method) {
       })),
     };
   }
+  if (typeof result.outline === 'string') {
+    const count = typeof result.count === 'number' ? result.count : 0;
+    const refs = result.source === 'dom' ? '; refs work as input targets' : '';
+    return {
+      ok: true,
+      summary: appendProtocolWarning(
+        `Accessibility outline: ${count} node(s)${result.truncated === true ? ', truncated' : ''}${refs}.`,
+        protocolWarning
+      ),
+      evidence: result.outline,
+    };
+  }
   if (
     Array.isArray(result.nodes) &&
     typeof result.total === 'number' &&
@@ -469,6 +666,7 @@ export function summarizeBridgeResponse(response, method) {
       if (Array.isArray(n.children) && n.children.length) {
         entry.childCount = n.children.length;
       }
+      if (n.visible === false) entry.visible = false;
       return entry;
     });
     const isFind = method === 'dom.find_by_text' || method === 'dom.find_by_role';
@@ -486,6 +684,9 @@ export function summarizeBridgeResponse(response, method) {
       } else {
         summary = `Found ${count} matching element(s)${scanned === null ? '' : ` after scanning ${scanned}`}.`;
       }
+      if (typeof result.hiddenMatches === 'number' && result.hiddenMatches > 0) {
+        summary += ` ${result.hiddenMatches} hidden match(es) omitted (includeHidden: true to list).`;
+      }
       return {
         ok: true,
         summary: appendProtocolWarning(summary, protocolWarning),
@@ -545,7 +746,10 @@ export function summarizeBridgeResponse(response, method) {
     } else if (isNull) {
       repr = '';
     } else if (typeof result.value === 'string') {
-      repr = result.value.length > 200 ? `${result.value.slice(0, 199)}\u2026` : result.value;
+      repr =
+        result.value.length > MAX_EVALUATE_SUMMARY_CHARS
+          ? `${result.value.length} chars, starts ${JSON.stringify(result.value.slice(0, EVALUATE_PREVIEW_CHARS))}\u2026`
+          : result.value;
     } else if (
       typeof result.value === 'object' &&
       result.value !== null &&
@@ -553,7 +757,7 @@ export function summarizeBridgeResponse(response, method) {
     ) {
       repr = '(empty - may be a Promise, Map, or non-serializable value)';
     } else {
-      repr = JSON.stringify(result.value);
+      repr = summarizeEvaluateValue(result.value);
     }
     const typeLabel = isNull ? 'null' : result.type;
     return {
@@ -692,20 +896,18 @@ export function summarizeBridgeResponse(response, method) {
     return {
       ok: true,
       summary: appendProtocolWarning(
-        `${method} completed via ${execution.actualMode ?? 'dom'}${result.elementRef ? ` on ${result.elementRef}` : ''}.`,
+        `${method} completed via ${execution.actualMode ?? 'dom'}${result.elementRef ? ` on ${result.elementRef}` : ''}.${describeEffects(result.effects)}`,
         protocolWarning
       ),
-      evidence: {
-        elementRef: result.elementRef ?? null,
-        sourceRef: result.sourceRef ?? null,
-        destinationRef: result.destinationRef ?? null,
+      evidence: compactInputEvidence(result, {
+        sourceRef: result.sourceRef ?? undefined,
+        destinationRef: result.destinationRef ?? undefined,
         typed: result.typed,
         checked: result.checked,
         selectedValues: result.selectedValues,
         mode: result.mode,
-        resolution: result.resolution,
-        execution: result.execution,
-      },
+        value: result.value,
+      }),
     };
   }
   if (typeof result.tabId === 'number' && typeof result.url === 'string') {
@@ -724,10 +926,7 @@ export function summarizeBridgeResponse(response, method) {
     }
     return {
       ok: true,
-      summary: appendProtocolWarning(
-        `Tab ${result.tabId} created${result.url ? ` (${result.url})` : ''}.`,
-        protocolWarning
-      ),
+      summary: appendProtocolWarning(describeTabResult(actionMethod, result), protocolWarning),
       evidence: result,
     };
   }
@@ -947,6 +1146,18 @@ function getProtocolWarning(meta) {
     : null;
 }
 
+/**
+ * Tell the agent when it kept working in its own tab while the user looked at
+ * a different one, so "this tab" requests can be redirected explicitly.
+ *
+ * @param {Record<string, unknown> | null | undefined} meta
+ * @returns {string | null}
+ */
+function getTabRoutingNote(meta) {
+  if (typeof meta?.tab_id !== 'number' || typeof meta.active_tab_id !== 'number') return null;
+  return `Ran in working tab ${meta.tab_id}; the user's active tab is ${meta.active_tab_id} (pass tabId to switch).`;
+}
+
 /**
  * @param {string} summary
  * @param {string | null} warning

package/packages/protocol/src/types.ts

@@ -119,6 +119,8 @@ export type BridgeMethod =
   | 'input.select_option'
   | 'input.hover'
   | 'input.drag'
+  | 'input.touch'
+  | 'input.perform'
   | 'input.scroll_into_view'
   | 'screenshot.capture_region'
   | 'screenshot.capture_element'
@@ -164,6 +166,14 @@ export interface BridgeMeta {
   continuation_hint?: string | null;
   automatic_retry?: { attempt: 2; reason: 'retryable_error' };
   stale_recovery?: 'success' | 'failure';
+  /** Agent session for sticky working-tab routing; unset callers share a default. */
+  agent_session?: string;
+  /** Tab the request ran in. */
+  tab_id?: number;
+  /** How the tab was chosen: explicit tabId, the agent's working tab, or the active tab. */
+  tab_routing?: 'explicit' | 'working' | 'active';
+  /** Present when the user's active tab differs from the tab the request ran in. */
+  active_tab_id?: number;
   [key: string]: unknown;
 }
 
@@ -442,13 +452,42 @@ export interface NormalizedStyleQuery extends BridgeParams {
 
 export interface InputTarget {
   elementRef?: string;
+  /** CSS selector; with a locator it narrows the locator's candidates. */
   selector?: string;
+  /** ARIA role, e.g. "button" or "textbox". */
+  role?: string;
+  /** Accessible name (substring, case-insensitive unless exact). */
+  name?: string;
+  /** Visible text of the innermost matching element. */
+  text?: string;
+  /** Associated label text for form controls. */
+  label?: string;
+  placeholder?: string;
+  /** data-testid / data-test-id / data-test / data-qa value. */
+  testId?: string;
+  exact?: boolean;
+  /** Zero-based index among visible locator matches. */
+  nth?: number;
+}
+
+export interface InputWaitObserveParams {
+  /** Wait up to this long for the target to exist and become actionable (0 disables). */
+  timeoutMs?: number;
+  /** Report post-action effects; true or { settleMs }. Defaults on for click/press_key/select/check. */
+  observe?: boolean | { settleMs?: number } | null;
 }
 
-export type InputExecutionMode = 'dom' | 'cdp';
+/** auto picks cdp only when trusted input is likely required (or the debugger is already attached). */
+export type InputExecutionMode = 'dom' | 'cdp' | 'auto';
 
 export interface InputResolutionMetadata {
-  strategy: 'elementRef' | 'selector-first' | 'selector-ranked' | 'stale-recovery';
+  strategy:
+    | 'elementRef'
+    | 'selector-first'
+    | 'selector-ranked'
+    | 'locator-first'
+    | 'locator-ranked'
+    | 'stale-recovery';
   candidateCount: number;
   evaluatedCount: number;
   scrolled: boolean;
@@ -458,6 +497,8 @@ export interface InputResolutionMetadata {
   newRef?: string;
   matchedFields?: string[];
   confidenceBasis?: string;
+  /** Time spent waiting for the target to become actionable. */
+  waitedMs?: number;
 }
 
 export interface InputExecutionMetadata {
@@ -468,7 +509,7 @@ export interface InputExecutionMetadata {
   targetCoordinates?: { x: number; y: number };
 }
 
-export interface InputActionParams {
+export interface InputActionParams extends InputWaitObserveParams {
   target?: InputTarget;
   button?: 'left' | 'middle' | 'right';
   clickCount?: number;
@@ -479,6 +520,7 @@ export interface InputActionParams {
   submit?: boolean;
   key?: string;
   modifiers?: string[];
+  holdMs?: number;
   executionMode?: InputExecutionMode;
   recoverStale?: boolean;
 }
@@ -494,10 +536,106 @@ export interface NormalizedInputAction extends BridgeParams {
   submit: boolean;
   key: string;
   modifiers: string[];
+  holdMs: number;
   executionMode: InputExecutionMode;
   recoverStale: boolean;
 }
 
+// Nullable fields let already-normalized params pass through normalization again.
+export interface TouchPositionParams {
+  target?: InputTarget | null;
+  x?: number | null;
+  y?: number | null;
+}
+
+export interface TouchPointParams extends TouchPositionParams {
+  to?: TouchPositionParams | null;
+}
+
+export interface TouchParams {
+  points?: TouchPointParams[];
+  holdMs?: number;
+  moveSteps?: number;
+  executionMode?: InputExecutionMode;
+  recoverStale?: boolean;
+}
+
+export type NormalizedTouchPosition =
+  | { target: InputTarget; x: null; y: null }
+  | { target: null; x: number; y: number };
+
+export type NormalizedTouchPoint = NormalizedTouchPosition & {
+  to: NormalizedTouchPosition | null;
+};
+
+export interface NormalizedTouchParams extends BridgeParams {
+  points: NormalizedTouchPoint[];
+  holdMs: number;
+  moveSteps: number;
+  executionMode: InputExecutionMode;
+  recoverStale: boolean;
+}
+
+export type PerformStepMethod =
+  | 'input.click'
+  | 'input.focus'
+  | 'input.type'
+  | 'input.fill'
+  | 'input.press_key'
+  | 'input.set_checked'
+  | 'input.select_option'
+  | 'input.hover'
+  | 'input.drag'
+  | 'input.touch'
+  | 'input.scroll_into_view'
+  | 'viewport.scroll'
+  | 'dom.wait_for'
+  | 'page.wait_for_load_state';
+
+export interface PerformStepParams {
+  method?: string;
+  params?: Record<string, unknown>;
+  delayMs?: number | null;
+  atMs?: number | null;
+}
+
+export interface PerformParams {
+  steps?: PerformStepParams[];
+  executionMode?: InputExecutionMode;
+  timeoutMs?: number;
+  continueOnError?: boolean;
+}
+
+export interface NormalizedPerformStep {
+  method: PerformStepMethod;
+  params: Record<string, unknown>;
+  delayMs: number;
+  atMs: number | null;
+}
+
+export interface NormalizedPerformParams extends BridgeParams {
+  steps: NormalizedPerformStep[];
+  timeoutMs: number;
+  continueOnError: boolean;
+}
+
+export interface PerformStepFailure {
+  index: number;
+  method: PerformStepMethod;
+  code: string;
+  message: string;
+  details?: unknown;
+}
+
+export interface PerformResult {
+  performed: true;
+  completed: number;
+  total: number;
+  elapsedMs: number;
+  startedAtMs: number[];
+  failures: PerformStepFailure[];
+}
+
 export interface CdpDispatchKeyEventParams {
   key?: string;
   code?: string;
@@ -526,7 +664,7 @@ export interface NormalizedCdpDomSnapshotParams extends BridgeParams {
   computedStyles: string[];
 }
 
-export interface CheckedActionParams {
+export interface CheckedActionParams extends InputWaitObserveParams {
   target?: InputTarget;
   checked?: boolean;
   executionMode?: InputExecutionMode;
@@ -540,7 +678,7 @@ export interface NormalizedCheckedAction extends BridgeParams {
   recoverStale: boolean;
 }
 
-export interface SelectActionParams {
+export interface SelectActionParams extends InputWaitObserveParams {
   target?: InputTarget;
   values?: string[];
   labels?: string[];
@@ -717,6 +855,7 @@ export interface FindByTextParams {
   exact?: boolean;
   selector?: string;
   maxResults?: number;
+  includeHidden?: boolean;
 }
 
 export interface NormalizedFindByTextParams extends BridgeParams {
@@ -724,20 +863,25 @@ export interface NormalizedFindByTextParams extends BridgeParams {
   exact: boolean;
   selector: string;
   maxResults: number;
+  includeHidden: boolean;
 }
 
 export interface FindByRoleParams {
   role?: string;
   name?: string;
+  exact?: boolean;
   selector?: string;
   maxResults?: number;
+  includeHidden?: boolean;
 }
 
 export interface NormalizedFindByRoleParams extends BridgeParams {
   role: string;
   name: string;
+  exact: boolean;
   selector: string;
   maxResults: number;
+  includeHidden: boolean;
 }
 
 export interface GetHtmlParams {
@@ -754,7 +898,7 @@ export interface NormalizedGetHtmlParams extends BridgeParams {
   maxLength: number;
 }
 
-export interface HoverParams {
+export interface HoverParams extends InputWaitObserveParams {
   target?: InputTarget;
   duration?: number;
   modifiers?: string[];
@@ -770,7 +914,7 @@ export interface NormalizedHoverParams extends BridgeParams {
   recoverStale: boolean;
 }
 
-export interface DragParams {
+export interface DragParams extends InputWaitObserveParams {
   source?: InputTarget;
   destination?: InputTarget;
   offsetX?: number;
@@ -954,6 +1098,10 @@ export interface AccessibilityTreeParams {
   maxNodes?: number;
   compact?: boolean;
   interactiveOnly?: boolean;
+  /** cdp (default): Chrome's AX tree via the debugger. dom: content-script outline with elementRefs, no debugger. */
+  source?: 'cdp' | 'dom';
+  /** outline: one compact `- role "name" [ref]` line per node (default for source=dom). */
+  format?: 'tree' | 'outline';
 }
 
 export interface NormalizedAccessibilityTreeParams extends BridgeParams {
@@ -962,6 +1110,8 @@ export interface NormalizedAccessibilityTreeParams extends BridgeParams {
   maxNodes: number;
   compact: boolean;
   interactiveOnly: boolean;
+  source?: 'dom';
+  format?: 'outline';
 }
 
 export interface AccessibilityTreeNode {