browser-automation-skill 0.71.0

package/references/recipes/visual-rescue-hook.md

@@ -0,0 +1,182 @@
+# Recipe — visual-rescue hook (Path 3)
+
+`browser-do.sh` exposes a hook seam BETWEEN Phase-13 fingerprint-rescue
+failure and the cloud-LLM fall-through. The hook decides whether a cached
+selector is still semantically the right target — typically by looking at
+a screenshot through a local VLM. When the hook says yes, the cache is
+preserved + no cloud-LLM round-trip happens.
+
+## When this fires
+
+```
+cached selector + page fingerprint match    → 0 LLM tokens
+  ↓ DOM diff detected
+Phase-13 silent fingerprint rescue           → 0 LLM tokens
+  ↓ rescue failed (no good selector candidate)
+[HOOK FIRES HERE]   ← Path 3
+  ↓ hook returns "yes" → keep cache, 0 cloud tokens
+  ↓ hook returns "no" / unreachable → fall through
+cloud LLM ref-resolution                     → 1 LLM round-trip
+```
+
+## Enabling the hook
+
+Two env vars must be set when invoking `browser-do --intent ...`:
+
+```bash
+export BROWSER_SKILL_VISION_FALLBACK=1
+export BROWSER_SKILL_VISUAL_RESCUE_CMD=/abs/path/to/your-hook.sh
+chmod +x "${BROWSER_SKILL_VISUAL_RESCUE_CMD}"
+```
+
+If either is unset (or the hook isn't executable), the tier is skipped
+silently and behaviour matches today's baseline.
+
+### Fast start — use the bundled default probe
+
+A ready-to-use canonical probe ships at `scripts/lib/visual-rescue-default.sh`
+(text-mode v1 — see "Modes" below). Wire it directly:
+
+```bash
+export BROWSER_SKILL_VISION_FALLBACK=1
+export BROWSER_SKILL_VISUAL_RESCUE_CMD="$(realpath scripts/lib/visual-rescue-default.sh)"
+# Optional — defaults to http://127.0.0.1:8080 (matches `bash scripts/browser-vlm.sh start`)
+# export BROWSER_SKILL_VLM_PORT=8080
+```
+
+That gets Path 3 live with zero custom code. Confirm wiring via doctor:
+
+```bash
+bash scripts/browser-doctor.sh | grep "local VLM"
+# ok: local VLM reachable @ http://127.0.0.1:8080 …
+```
+
+## Modes
+
+**v1 — text-mode (the bundled default).** Reads the accessibility-tree YAML
+snapshot, sends `(intent, selector, snapshot-text)` to the local LLM, asks
+yes/no. Cheap (~200ms total), works against any OpenAI-compatible endpoint
+(local llama-server, vLLM, ollama, etc — not just VLMs).
+
+**v2 — vision-mode (planned).** Crops a screenshot of the cached element's
+bbox, sends image to a VLM, asks yes/no. Stronger signal for visual-only UIs
+(canvas elements, custom-painted widgets), but needs screenshot-from-live-
+session infrastructure that isn't shipped yet. Roll your own per the example
+below until v2 lands.
+
+## Hook contract
+
+The hook is invoked with **three positional args**:
+
+```bash
+your-hook.sh SITE INTENT CACHED_SELECTOR
+```
+
+- `SITE` — registered site name (e.g. `prod-app`)
+- `INTENT` — natural-language intent from the original `browser-do --intent` call
+- `CACHED_SELECTOR` — the CSS selector that was retrieved from `~/.browser-skill/memory/<site>/archetypes/<id>.json` (the one Phase-13 rescue couldn't salvage)
+
+The hook must write **exactly `yes` or `no` to stdout** (single line, no
+JSON envelope). Any other output is treated as "no". Exit code:
+
+- `0` + stdout `yes` → cache preserved; verb dispatch reports success
+- `0` + stdout `no` → fall through to cloud LLM
+- non-zero exit → fall through (treated as "unreachable")
+
+Stderr is ignored by `browser-do`; use it for hook-internal logging.
+
+## Reference implementation — llama.cpp + Qwen3-VL-4B
+
+A minimum hook that screenshots the current page (via `browser-snapshot.sh`
++ `browser-inspect.sh --screenshot`) and asks a local Qwen3-VL through
+`llama-server` is shown below. This is a SAMPLE — write your own to taste.
+
+```bash
+#!/usr/bin/env bash
+# ~/.browser-skill/hooks/visual-rescue-llama.sh
+set -euo pipefail
+site="$1"; intent="$2"; selector="$3"
+
+vlm_host="${BROWSER_SKILL_VLM_HOST:-127.0.0.1}"
+vlm_port="${BROWSER_SKILL_VLM_PORT:-8080}"
+endpoint="http://${vlm_host}:${vlm_port}/v1/chat/completions"
+
+# Quick reachability gate — silent skip if VLM not running.
+if ! curl -sfm 2 "http://${vlm_host}:${vlm_port}/health" >/dev/null; then
+  printf 'no\n'
+  exit 1
+fi
+
+# Take a transient screenshot via the inspect verb (Phase 7 captures dir).
+# Find the most-recent screenshot file under captures/.
+SCRIPTS_DIR="${BROWSER_SKILL_SCRIPTS_DIR:-${HOME}/.claude/skills/browser-automation-skill/scripts}"
+bash "${SCRIPTS_DIR}/browser-inspect.sh" --site "${site}" --screenshot --capture \
+  >/dev/null 2>&1 || { printf 'no\n'; exit 1; }
+captures_dir="${BROWSER_SKILL_HOME:-${HOME}/.browser-skill}/captures"
+latest_id="$(jq -r '.latest' "${captures_dir}/_index.json" 2>/dev/null)"
+png_path="${captures_dir}/${latest_id}/inspect-screenshot.png"
+[ -f "${png_path}" ] || { printf 'no\n'; exit 1; }
+
+# Ask the VLM: yes/no probe.
+b64="$(base64 -i "${png_path}" | tr -d '\n')"
+prompt="The user wants to: '${intent}'. The cached element was at CSS selector '${selector}'. Looking at this page, is there still a target element that matches the intent? Answer with ONLY 'yes' or 'no'."
+
+resp="$(curl -sS -m 30 "${endpoint}" -H 'Content-Type: application/json' \
+  -d "$(jq -n --arg img "data:image/png;base64,${b64}" --arg p "${prompt}" '
+    {model:"q",max_tokens:5,messages:[{role:"user",content:[
+      {type:"text",text:$p},
+      {type:"image_url",image_url:{url:$img}}
+    ]}]}')" 2>/dev/null)"
+
+completion="$(printf '%s' "${resp}" | jq -r '.choices[0].message.content // ""' 2>/dev/null)"
+case "${completion,,}" in
+  *yes*) printf 'yes\n' ;;
+  *)     printf 'no\n' ;;
+esac
+```
+
+Smoke test the hook in isolation:
+
+```bash
+echo "site=prod-app intent='click submit' selector='button.submit'"
+~/.browser-skill/hooks/visual-rescue-llama.sh prod-app 'click submit' 'button.submit'
+# → yes / no
+```
+
+## Telemetry
+
+When the hook reports "yes" and `browser-do` accepts the rescue:
+
+- A `_kind:"visual_rescue"` event line appears on stdout (machine-readable)
+- A separate event lands in `~/.browser-skill/memory/stats.jsonl` with
+  `gen_ai_tool_name:"browser-do.visual_rescue"` and `rescued:true`. Run
+  `browser-stats report --route browser-do` to see your visual-rescue rate.
+
+When the hook reports "no" or fails, NO visual_rescue event is emitted
+(the original Phase-13 cache_miss + fail_count path runs unchanged).
+
+## Cost frame
+
+Rough numbers from the Phase-14 bench session (M3 Pro + Qwen3-VL-4B-q4_K_M):
+
+| Step | Latency | Cloud tokens |
+|---|---:|---:|
+| Screenshot via inspect | ~1.5 s | 0 |
+| base64 + curl + VLM yes/no | ~0.4 s | 0 |
+| **Path 3 total** | **~2 s** | **0** |
+| Cloud LLM ref-resolution (alternative) | ~1 s | full prompt + response |
+
+Path 3 wins when avoided cloud-LLM cost exceeds local latency cost. For
+high-volume cache flows (your registered prod sites with repeat actions),
+this is "always" — the 2 s pays off after one avoided LLM round-trip.
+
+## Why a hook, not a built-in
+
+The skill is intentionally agnostic about HOW the visual probe reasons —
+some users will want screenshot-crop + Qwen3-VL, others UI-TARS-7B,
+others a yes/no LLM-as-judge against a text snapshot. Hardcoding one
+approach would close the design space. The hook contract lets each user
+ship their preferred probe without forking the skill.
+
+A built-in default probe is planned for a future release; this recipe
+will become the canonical reference once it lands.

package/references/stats-prices.json

@@ -0,0 +1,42 @@
+{
+  "_doc": "Anthropic model prices in USD per token. Sourced from docs.anthropic.com/pricing as of 2026-05-15. Used by `browser-stats report` to convert token counts into $ at query time (re-priceable). Override path via env: BROWSER_STATS_PRICES_FILE.",
+  "_last_updated": "2026-05-15",
+  "models": {
+    "claude-opus-4-7": {
+      "input": 0.000005,
+      "output": 0.000025,
+      "cache_create_5m": 0.00000625,
+      "cache_create_1h": 0.00001000,
+      "cache_create": 0.00000625,
+      "cache_read": 0.00000050
+    },
+    "claude-sonnet-4-6": {
+      "input": 0.000003,
+      "output": 0.000015,
+      "cache_create_5m": 0.00000375,
+      "cache_create_1h": 0.00000600,
+      "cache_create": 0.00000375,
+      "cache_read": 0.00000030
+    },
+    "claude-haiku-4-5": {
+      "input": 0.000001,
+      "output": 0.000005,
+      "cache_create_5m": 0.00000125,
+      "cache_create_1h": 0.00000200,
+      "cache_create": 0.00000125,
+      "cache_read": 0.00000010
+    }
+  },
+  "modifiers": {
+    "_doc": "Multipliers applied at report time. `inference_geo=us` adds 1.1x; fast_mode is 6x and stacks; batch is 0.5x (mutually exclusive with fast_mode).",
+    "inference_geo_us": 1.1,
+    "fast_mode": 6.0,
+    "batch": 0.5
+  },
+  "server_tools": {
+    "_doc": "Server-side tool use billed per request, not tokens.",
+    "web_search_request": 0.01,
+    "web_fetch_request": 0.0,
+    "code_execution_session_hour": 0.08
+  }
+}

package/references/stats-schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/xicv/browser-automation-skill/references/stats-schema.json",
+  "title": "browser-automation-skill stats event",
+  "description": "One JSONL line per adapter invocation written to ${BROWSER_SKILL_HOME}/memory/stats.jsonl. Field naming follows OpenInference + OTel GenAI v1.40 conventions (snake_case dot-name flattening) for forward-compat with OTLP exporters and Langfuse/Phoenix.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "ts",
+    "span_id",
+    "trace_id",
+    "verb",
+    "adapter_route",
+    "outcome",
+    "rc",
+    "duration_ms",
+    "argv_bytes",
+    "stdout_bytes",
+    "stderr_bytes"
+  ],
+  "properties": {
+    "schema_version":      {"type": "integer", "const": 1},
+    "ts":                  {"type": "string", "format": "date-time", "description": "ISO 8601 with ms precision (UTC)."},
+    "span_id":             {"type": "string", "pattern": "^[0-9a-f]{16}$"},
+    "trace_id":            {"type": "string", "pattern": "^[0-9a-f]{16}$"},
+    "parent_span_id":      {"type": ["string", "null"]},
+    "session_id":          {"type": ["string", "null"], "description": "$CLAUDE_SESSION_ID if injected."},
+
+    "gen_ai_operation_name": {"type": "string", "const": "execute_tool"},
+    "gen_ai_tool_name":      {"type": "string", "description": "e.g. 'chrome-devtools-mcp.click'. OTel-compliant."},
+    "gen_ai_tool_type":      {"type": "string", "enum": ["function", "extension", "datastore"]},
+
+    "verb":                {"type": "string", "description": "browser-* verb (open, click, fill, extract, ...)."},
+    "adapter_route":       {"type": "string", "enum": ["chrome-devtools-mcp", "playwright-cli", "playwright-lib", "obscura"]},
+    "site":                {"type": ["string", "null"]},
+
+    "selector_kind":       {"type": "string", "enum": ["a11y_ref", "css", "xpath", "role", "text", "none"]},
+    "selector_value":      {"type": ["string", "null"]},
+
+    "duration_ms":         {"type": "integer", "minimum": 0},
+    "argv_bytes":          {"type": "integer", "minimum": 0, "description": "Total argv bytes — input-token proxy when SDK fields absent."},
+    "stdout_bytes":        {"type": "integer", "minimum": 0, "description": "Captured stdout bytes — output-token proxy."},
+    "stderr_bytes":        {"type": "integer", "minimum": 0},
+    "rc":                  {"type": "integer", "description": "Adapter exit code (lib/common.sh EXIT_* table)."},
+
+    "outcome":             {"type": "string", "enum": ["success", "fail", "partial", "skipped"]},
+    "failure_mode":        {
+      "type": ["string", "null"],
+      "enum": [null,
+        "element_not_found", "element_ambiguous", "wrong_element_acted",
+        "stale_ref", "action_timeout", "navigation_mismatch",
+        "js_not_ready", "network_error", "captcha_blocked",
+        "auth_required", "popup_intercept", "extraction_mismatch",
+        "oblivious_success", "unknown_failure"
+      ],
+      "description": "Phase 14 (Bundle #3) added unknown_failure as the catch-all so rc!=0 events with no classifier match surface in stats tune histograms instead of being dropped as null."
+    },
+
+    "model":               {"type": ["string", "null"], "description": "From $CLAUDE_MODEL env. Null when invoked outside Claude Code."},
+    "service_tier":        {"type": ["string", "null"], "enum": [null, "standard", "priority", "batch"]},
+
+    "gen_ai_usage_input_tokens":               {"type": ["integer", "null"], "minimum": 0},
+    "gen_ai_usage_output_tokens":              {"type": ["integer", "null"], "minimum": 0},
+    "gen_ai_usage_cache_read_input_tokens":    {"type": ["integer", "null"], "minimum": 0},
+    "gen_ai_usage_cache_creation_input_tokens":{"type": ["integer", "null"], "minimum": 0},
+
+    "post_condition_target_type":  {"type": ["string", "null"], "enum": [null, "url", "element_path", "element_value"]},
+    "post_condition_matcher":      {"type": ["string", "null"], "enum": [null, "exact", "include", "semantic"]},
+    "post_condition_expected":     {"type": ["string", "null"]},
+    "post_condition_observed":     {"type": ["string", "null"]},
+    "post_condition_hit":          {"type": ["boolean", "null"]},
+
+    "rescued":                     {"type": ["boolean", "null"], "description": "Phase 13 fingerprint rescue outcome. true=cache silently healed (selector overwritten, fail_count reset); false=rescue attempted but failed; null=rescue not attempted (default for adapter-direct events)."},
+    "fingerprint_from_selector":   {"type": ["string", "null"], "description": "Phase 13: the cached selector that went stale. Null when rescued != true."},
+    "fingerprint_to_selector":     {"type": ["string", "null"], "description": "Phase 13: the rescued selector that replaced the stale one. Null when rescued != true."}
+  }
+}

package/references/tool-versions.md

@@ -0,0 +1,8 @@
+# Tool versions (autogenerated — do not edit; run scripts/regenerate-docs.sh)
+
+| Tool | Version pin | Install hint | Cheatsheet |
+|---|---|---|---|
+| chrome-devtools-mcp | 0.x | npm i -g chrome-devtools-mcp (or run via 'npx chrome-devtools-mcp@latest' over stdio MCP) | [references/chrome-devtools-mcp-cheatsheet.md](../references/chrome-devtools-mcp-cheatsheet.md) |
+| obscura | 0.x | download release from https://github.com/h4ckf0r0day/obscura/releases (no Chrome/Node required); keep obscura + obscura-worker side-by-side | [references/obscura-cheatsheet.md](../references/obscura-cheatsheet.md) |
+| playwright-cli | 1.49.x | npm i -g playwright @playwright/test @playwright/cli && playwright install chromium | [references/playwright-cli-cheatsheet.md](../references/playwright-cli-cheatsheet.md) |
+| playwright-lib | 1.59.x | npm i -g playwright @playwright/test && playwright install chromium | [references/playwright-lib-cheatsheet.md](../references/playwright-lib-cheatsheet.md) |

package/scripts/browser-add-site.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# add-site — register a site profile under sites/<name>.json.
+set -euo pipefail
+IFS=$'\n\t'
+umask 077
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/common.sh"
+# shellcheck source=lib/site.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/site.sh"
+init_paths
+
+name=""; url=""; viewport="1280x800"; user_agent=""; stealth="false"
+default_session=""; default_tool=""; label=""
+force=0; dry_run=0
+
+usage() {
+  cat <<'USAGE'
+Usage: add-site --name NAME --url URL [options]
+
+  --name NAME              site name (required, used as filename)
+  --url  URL               site URL (must start with http:// or https://)
+  --viewport WxH           viewport (default 1280x800)
+  --user-agent UA          override user agent
+  --stealth                set stealth flag (default false)
+  --default-session NAME   default session for verbs that omit --session
+  --default-tool NAME      default tool for verbs that omit --tool
+  --label TEXT             human-readable description
+  --force                  overwrite an existing site
+  --dry-run                print planned action; write nothing
+  -h, --help               this message
+USAGE
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --name)             name="$2";              shift 2 ;;
+    --url)              url="$2";               shift 2 ;;
+    --viewport)         viewport="$2";          shift 2 ;;
+    --user-agent)       user_agent="$2";        shift 2 ;;
+    --stealth)          stealth="true";         shift ;;
+    --default-session)  default_session="$2";   shift 2 ;;
+    --default-tool)     default_tool="$2";      shift 2 ;;
+    --label)            label="$2";             shift 2 ;;
+    --force)            force=1;                shift ;;
+    --dry-run)          dry_run=1;              shift ;;
+    -h|--help)          usage; exit 0 ;;
+    *)                  die "${EXIT_USAGE_ERROR}" "unknown flag: $1" ;;
+  esac
+done
+
+[ -n "${name}" ] || { usage; die "${EXIT_USAGE_ERROR}" "--name is required"; }
+[ -n "${url}" ]  || { usage; die "${EXIT_USAGE_ERROR}" "--url is required"; }
+case "${url}" in
+  http://*|https://*) ;;
+  *) die "${EXIT_USAGE_ERROR}" "url must start with http:// or https:// (got: ${url})" ;;
+esac
+[[ "${viewport}" =~ ^[0-9]+x[0-9]+$ ]] \
+  || die "${EXIT_USAGE_ERROR}" "viewport must be WIDTHxHEIGHT (got: ${viewport})"
+# Defense in depth: validate name fields the script is about to embed in paths.
+assert_safe_name "${name}" "site-name"
+[ -z "${default_session}" ] || assert_safe_name "${default_session}" "default-session"
+vw="${viewport%x*}"; vh="${viewport#*x}"
+
+started_at_ms="$(now_ms)"
+
+if site_exists "${name}" && [ "${force}" -ne 1 ]; then
+  die "${EXIT_USAGE_ERROR}" "site already exists: ${name} (use --force to overwrite)"
+fi
+
+profile_json="$(jq -nc \
+  --arg n "${name}" \
+  --arg u "${url}" \
+  --argjson vw "${vw}" --argjson vh "${vh}" \
+  --arg ua "${user_agent}" \
+  --argjson stealth "${stealth}" \
+  --arg ds "${default_session}" \
+  --arg dt "${default_tool}" \
+  --arg lbl "${label}" \
+  '{
+    name: $n, url: $u,
+    viewport: {width: $vw, height: $vh},
+    user_agent: (if $ua == "" then null else $ua end),
+    stealth: $stealth,
+    default_session: (if $ds == "" then null else $ds end),
+    default_tool:    (if $dt == "" then null else $dt end),
+    label: $lbl,
+    schema_version: 1
+  }')"
+
+now_ts="$(now_iso)"
+meta_json="$(jq -nc \
+  --arg n "${name}" \
+  --arg now "${now_ts}" \
+  '{name: $n, created_at: $now, last_used_at: $now}')"
+
+if [ "${dry_run}" -eq 1 ]; then
+  ok "dry-run: would write ${SITES_DIR}/${name}.json"
+  duration_ms=$(( $(now_ms) - started_at_ms ))
+  summary_json verb=add-site tool=none why=dry-run status=ok would_run=true \
+               site="${name}" duration_ms="${duration_ms}"
+  exit "${EXIT_OK}"
+fi
+
+site_save "${name}" "${profile_json}" "${meta_json}"
+ok "site added: ${name}"
+
+duration_ms=$(( $(now_ms) - started_at_ms ))
+summary_json verb=add-site tool=none why=write-profile status=ok \
+             site="${name}" duration_ms="${duration_ms}"

package/scripts/browser-assert.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# scripts/browser-assert.sh — verify-style assertion verb (Phase 9 part 1-ii).
+#
+# Usage:
+#   bash scripts/browser-assert.sh --selector CSS --text-contains TEXT \
+#        [--site NAME] [--tool NAME] [--dry-run]
+#
+# Thin wrapper: shells to `bash scripts/browser-extract.sh --selector CSS`
+# (subprocess; routes through router + chrome-devtools-mcp by default);
+# parses the extracted text; bash-side compares against --text-contains
+# predicate. NO new tool_assert function on adapters — composition over ABI
+# extension (per design doc §6 + plan-doc 2026-05-10-phase-09-part-1-ii §A1).
+#
+# Exit codes:
+#   0  — assertion passed
+#   13 — EXIT_ASSERTION_FAILED — predicate did not match
+#   2  — EXIT_USAGE_ERROR (missing required flag)
+#   1  — EXIT_GENERIC_ERROR (extract subprocess failed)
+
+set -euo pipefail
+IFS=$'\n\t'
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/common.sh"
+# shellcheck source=lib/output.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/output.sh"
+# shellcheck source=lib/verb_helpers.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/verb_helpers.sh"
+
+init_paths
+
+SUMMARY_T0="$(now_ms)"; export SUMMARY_T0
+
+parse_verb_globals "$@"
+
+selector=""
+text_contains=""
+i=0
+while [ "${i}" -lt "${#REMAINING_ARGV[@]}" ]; do
+  case "${REMAINING_ARGV[i]}" in
+    --selector)
+      selector="${REMAINING_ARGV[i+1]:-}"
+      [ -n "${selector}" ] || die "${EXIT_USAGE_ERROR}" "--selector requires a value"
+      i=$((i + 2))
+      ;;
+    --text-contains)
+      text_contains="${REMAINING_ARGV[i+1]:-}"
+      [ -n "${text_contains}" ] || die "${EXIT_USAGE_ERROR}" "--text-contains requires a value"
+      i=$((i + 2))
+      ;;
+    *)
+      i=$((i + 1))
+      ;;
+  esac
+done
+
+[ -n "${selector}" ]      || die "${EXIT_USAGE_ERROR}" "assert requires --selector CSS"
+[ -n "${text_contains}" ] || die "${EXIT_USAGE_ERROR}" "assert requires --text-contains TEXT"
+
+if [ "${ARG_DRY_RUN:-0}" = "1" ]; then
+  ok "dry-run: would assert selector=${selector} text_contains=${text_contains}"
+  emit_summary verb=assert tool=none why=dry-run status=ok \
+    selector="${selector}" text_contains="${text_contains}" dry_run=true
+  exit 0
+fi
+
+# Compose: shell to browser-extract.sh to get the selector's text. The extract
+# verb's stdout is one event line + one summary line. We parse the event line.
+set +e
+extract_out="$(bash "${SCRIPT_DIR}/browser-extract.sh" --selector "${selector}" 2>&1)"
+extract_rc=$?
+set -e
+
+if [ "${extract_rc}" -ne 0 ]; then
+  emit_summary verb=assert tool=extract why=composition status=error \
+    selector="${selector}" text_contains="${text_contains}" \
+    error="extract subprocess failed (rc=${extract_rc})"
+  exit "${EXIT_GENERIC_ERROR}"
+fi
+
+# Find the extract event line; collect all matched text. The shipped extract
+# event shape is {"event":"extract","selector":"...","matches":["Welcome","Hello"]}
+# (matches[] is array of strings — see tests/fixtures/chrome-devtools-mcp/
+# 05efe417...json). Fall through to .text for the playwright-cli shape.
+got_text="$(
+  printf '%s\n' "${extract_out}" \
+    | jq -r -s '
+        map(select(.event == "extract")) | .[0] |
+        (.text // (.matches // []) | if type == "array" then join("\n") else . end)' 2>/dev/null \
+    || printf ''
+)"
+
+if printf '%s' "${got_text}" | grep -qF -- "${text_contains}"; then
+  emit_summary verb=assert tool=extract why=composition status=ok \
+    selector="${selector}" text_contains="${text_contains}"
+  exit 0
+fi
+
+emit_summary verb=assert tool=extract why=composition status=error \
+  selector="${selector}" text_contains="${text_contains}" \
+  expected="${text_contains}" got="${got_text}"
+exit "${EXIT_ASSERTION_FAILED}"

package/scripts/browser-audit.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# scripts/browser-audit.sh — run a Lighthouse / perf-trace audit.
+# Usage: bash scripts/browser-audit.sh [--site NAME] [--tool NAME] [--dry-run]
+#                                      [--raw] [--lighthouse] [--perf-trace]
+#
+# Routes to chrome-devtools-mcp by default (post-1d router promotion — only
+# adapter with `lighthouse_audit` and `performance_*` MCP tools per parent
+# spec Appendix B). `--lighthouse` is the implicit default; `--perf-trace`
+# can coexist.
+
+set -euo pipefail
+IFS=$'\n\t'
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/common.sh"
+# shellcheck source=lib/output.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/output.sh"
+# shellcheck source=lib/router.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/router.sh"
+# shellcheck source=lib/verb_helpers.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/verb_helpers.sh"
+
+init_paths
+
+SUMMARY_T0="$(now_ms)"; export SUMMARY_T0
+
+parse_verb_globals "$@"
+
+resolve_session_storage_state
+
+verb_argv=("${REMAINING_ARGV[@]}")
+
+# Default to --lighthouse when neither flag is provided. Adapter still sees
+# the flag in argv so router rules + capability filter can react.
+if ! _has_flag --lighthouse "${verb_argv[@]}" && ! _has_flag --perf-trace "${verb_argv[@]}"; then
+  verb_argv+=(--lighthouse)
+fi
+
+if [ "${ARG_DRY_RUN:-0}" = "1" ]; then
+  ok "dry-run: would run audit"
+  emit_summary verb=audit tool=none why=dry-run status=ok dry_run=true
+  exit 0
+fi
+
+picked="$(pick_tool audit "${verb_argv[@]}")"
+tool_name="${picked%%$'\t'*}"
+why="${picked#*$'\t'}"
+
+source_picked_adapter "${tool_name}"
+
+set +e
+adapter_out="$(invoke_with_retry audit "${verb_argv[@]}")"
+adapter_rc=$?
+set -e
+
+[ -n "${adapter_out}" ] && printf '%s\n' "${adapter_out}"
+
+if [ "${adapter_rc}" -eq 0 ]; then
+  emit_summary verb=audit tool="${tool_name}" why="${why}" status=ok
+  exit 0
+fi
+emit_summary verb=audit tool="${tool_name}" why="${why}" status=error
+exit "${adapter_rc}"