browser-automation-skill 0.71.0

package/scripts/browser-doctor.sh

@@ -0,0 +1,365 @@
+#!/usr/bin/env bash
+# browser-doctor — health check, exits non-zero on issues. Zero network calls.
+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"
+init_paths
+
+started_at_ms="$(now_ms)"
+problems=0
+
+# Required check: increments problems on miss. Doctor will exit non-zero.
+check_cmd() {
+  local cmd="$1" hint="$2"
+  if command -v "${cmd}" >/dev/null 2>&1; then
+    ok "${cmd} found: $(command -v "${cmd}")"
+  else
+    warn "${cmd} NOT FOUND"
+    warn "  remediation: ${hint}"
+    problems=$((problems + 1))
+  fi
+}
+
+# Advisory check: prints status but does NOT increment problems. Use for tools
+# that are required by later phases but optional in the current phase, OR for
+# tools that the user will install when they actually need them.
+check_cmd_advisory() {
+  local cmd="$1" hint="$2"
+  if command -v "${cmd}" >/dev/null 2>&1; then
+    ok "${cmd} found: $(command -v "${cmd}")"
+  else
+    warn "${cmd} NOT FOUND (advisory only — does not fail doctor)"
+    warn "  remediation: ${hint}"
+  fi
+}
+
+check_bash_version() {
+  local major="${BASH_VERSINFO[0]:-0}"
+  if [ "${major}" -ge 4 ]; then
+    ok "bash version: ${BASH_VERSION}"
+  else
+    warn "bash ${BASH_VERSION} is too old (need >= 4)"
+    warn "  remediation: brew install bash"
+    problems=$((problems + 1))
+  fi
+}
+
+check_home() {
+  if [ ! -d "${BROWSER_SKILL_HOME}" ]; then
+    warn "${BROWSER_SKILL_HOME} does not exist"
+    warn "  remediation: run ./install.sh from the repo root"
+    problems=$((problems + 1))
+    return 0
+  fi
+  local mode
+  mode="$(file_mode "${BROWSER_SKILL_HOME}")"
+  [ -n "${mode}" ] || mode="?"
+  if [ "${mode}" != "700" ]; then
+    warn "${BROWSER_SKILL_HOME} has mode ${mode}, expected 700"
+    warn "  remediation: chmod 700 ${BROWSER_SKILL_HOME}"
+    problems=$((problems + 1))
+  else
+    ok "${BROWSER_SKILL_HOME} mode 700"
+  fi
+}
+
+ok "browser-skill home: ${BROWSER_SKILL_HOME}"
+ok "browser-skill doctor"
+
+check_cmd jq "brew install jq (macOS) or apt install jq (Debian)"
+check_cmd python3 "brew install python3 (macOS) or apt install python3"
+check_bash_version
+check_home
+# Tools below are recommended but not required in Phase 1; later phases will
+# elevate these to required and add version-pinning logic.
+check_cmd node "brew install node (>=20) — required by playwright-cli adapter; was advisory in Phase 1-2"
+
+check_disk_encryption() {
+  case "$(uname -s)" in
+    Darwin)
+      if command -v fdesetup >/dev/null 2>&1; then
+        local status
+        status="$(fdesetup status 2>/dev/null || true)"
+        case "${status}" in
+          *"FileVault is On"*)  ok "disk encryption: FileVault on" ;;
+          *"FileVault is Off"*) warn "disk encryption: FileVault OFF (advisory — 0600 modes are paper without disk encryption)" ;;
+          *)                    warn "disk encryption: status unknown (fdesetup said: ${status:-empty})" ;;
+        esac
+      else
+        warn "disk encryption: fdesetup not found (cannot verify)"
+      fi
+      ;;
+    Linux)
+      if command -v lsblk >/dev/null 2>&1 && lsblk -o NAME,FSTYPE 2>/dev/null | grep -q crypto_LUKS; then
+        ok "disk encryption: LUKS-backed volume detected"
+      else
+        warn "disk encryption: no LUKS volume found (advisory)"
+      fi
+      ;;
+    *)
+      warn "disk encryption: unknown OS — please verify manually"
+      ;;
+  esac
+}
+
+check_disk_encryption
+
+# --- Adapter aggregation (extension model §5.2) ---
+# Walk lib/tool/*.sh in subshells; collect each adapter's tool_doctor_check.
+# Subshell isolation prevents tool_open / tool_click / etc. from colliding.
+adapters_ok=0
+adapters_failed=0
+adapter_files=("${LIB_TOOL_DIR}"/*.sh)
+
+if [ ! -f "${adapter_files[0]}" ]; then
+  warn "no adapters found under ${LIB_TOOL_DIR}"
+else
+  for adapter_file in "${adapter_files[@]}"; do
+    adapter_name="$(basename "${adapter_file}" .sh)"
+    result="$(
+      # shellcheck source=/dev/null
+      source "${adapter_file}" 2>/dev/null
+      tool_doctor_check 2>/dev/null
+    )" || result='{"ok":false,"error":"adapter source failed"}'
+
+    jq -c --arg n "${adapter_name}" '. + {check:"adapter",adapter:$n}' <<<"${result}"
+
+    if [ "$(printf '%s' "${result}" | jq -r .ok 2>/dev/null)" = "true" ]; then
+      adapters_ok=$((adapters_ok + 1))
+      ok "adapter ${adapter_name}: ok"
+    else
+      adapters_failed=$((adapters_failed + 1))
+      warn "adapter ${adapter_name}: $(printf '%s' "${result}" | jq -r '.error // "failed"')"
+    fi
+  done
+fi
+
+# --- Credentials count (advisory; never fails doctor) ---
+# Phase 5 part 2d: walk ${CREDENTIALS_DIR}/*.json and report per-backend.
+# .secret files are payload, not metadata, so they're skipped.
+creds_total=0
+creds_keychain=0
+creds_libsecret=0
+creds_plaintext=0
+if [ -d "${CREDENTIALS_DIR}" ]; then
+  shopt -s nullglob
+  for cred_file in "${CREDENTIALS_DIR}"/*.json; do
+    creds_total=$((creds_total + 1))
+    backend="$(jq -r .backend "${cred_file}" 2>/dev/null || printf 'unknown')"
+    case "${backend}" in
+      keychain)  creds_keychain=$((creds_keychain + 1)) ;;
+      libsecret) creds_libsecret=$((creds_libsecret + 1)) ;;
+      plaintext) creds_plaintext=$((creds_plaintext + 1)) ;;
+    esac
+  done
+  shopt -u nullglob
+fi
+ok "credentials: ${creds_total} total (keychain: ${creds_keychain}, libsecret: ${creds_libsecret}, plaintext: ${creds_plaintext})"
+
+# --- Captures sanitization counter (advisory; never fails doctor) ---
+# Phase 7 part 1-iv: walk ${CAPTURES_DIR}/*/meta.json and count total +
+# sanitized:false. Missing/null .sanitized treated as sanitized=true
+# (forward-compat with pre-7-1-iv captures).
+captures_total=0
+captures_unsanitized=0
+captures_unsanitized_ids=""
+if [ -d "${CAPTURES_DIR}" ]; then
+  shopt -s nullglob
+  for capture_meta in "${CAPTURES_DIR}"/*/meta.json; do
+    captures_total=$((captures_total + 1))
+    # Note: don't use `// true` — jq's `//` fires on null OR false, so a
+    # legit sanitized=false would resolve to "true". Read raw; missing field
+    # surfaces as "null" which is correctly NOT-equal-to-"false" below.
+    sanitized="$(jq -r '.sanitized' "${capture_meta}" 2>/dev/null || printf 'null')"
+    if [ "${sanitized}" = "false" ]; then
+      captures_unsanitized=$((captures_unsanitized + 1))
+      capture_id="$(jq -r '.capture_id // "?"' "${capture_meta}" 2>/dev/null || printf '?')"
+      captures_unsanitized_ids="${captures_unsanitized_ids:+${captures_unsanitized_ids}, }captures/${capture_id}/"
+    fi
+  done
+  shopt -u nullglob
+fi
+ok "captures: ${captures_total} total (sanitized:false: ${captures_unsanitized})"
+if [ "${captures_unsanitized}" -gt 0 ]; then
+  warn "${captures_unsanitized} capture(s) with sanitization disabled — review ${captures_unsanitized_ids}"
+fi
+
+# --- Pending migrations (advisory; never fails doctor) ---
+# Phase 10 follow-up. Sources lib/migrate.sh and calls migrate_check, which is
+# read-only by design (no lock acquired; MIG4 invariant from the Phase 10
+# design doc — "doctor never auto-migrates"). Doctor surfaces pending count
+# only; user invokes `browser-migrate run` to apply them.
+# shellcheck source=lib/migrate.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/migrate.sh"
+migrations_pending=0
+# migrate_check emits one _kind:migration_needed line per pending migrator,
+# then a summary line. Count the _kind events; ignore the summary.
+mig_out="$(migrate_check 2>/dev/null || true)"
+if [ -n "${mig_out}" ]; then
+  migrations_pending="$(printf '%s\n' "${mig_out}" \
+    | jq -s 'map(select(._kind == "migration_needed")) | length' 2>/dev/null \
+    || printf '0')"
+fi
+jq -nc --argjson n "${migrations_pending}" '{check:"migrations", pending:$n}'
+if [ "${migrations_pending}" -gt 0 ]; then
+  warn "${migrations_pending} pending migration(s) — run 'browser-migrate check' for details (advisory; never fails doctor)"
+else
+  ok "no pending migrations"
+fi
+
+# --- Memory cache hit-rate (advisory; forward-compat read side) ---
+# Phase 11 v2 will tee `verb=do mode=intent` summary lines into
+# ${BROWSER_SKILL_HOME}/memory/events.jsonl. Doctor's read side ships now;
+# absent file → "n/a" line. Lifetime ratio over all events (no time filter
+# until events carry timestamps).
+cache_events_log="${BROWSER_SKILL_HOME}/memory/events.jsonl"
+if [ -f "${cache_events_log}" ]; then
+  # Phase 12 part 2 audit: single jq pass extracts both counts (one file
+  # read, one fork) instead of two sequential `jq -s` slurps.
+  cache_pair="$(jq -s -r '
+    [(map(select(.cache_hit == true or .cache_hit == false)) | length),
+     (map(select(.cache_hit == true)) | length)] | @tsv
+  ' "${cache_events_log}" 2>/dev/null || printf '0\t0')"
+  IFS=$'\t' read -r cache_total cache_hits <<<"${cache_pair}"
+  cache_total="${cache_total:-0}"
+  cache_hits="${cache_hits:-0}"
+  if [ "${cache_total}" -gt 0 ]; then
+    # Integer-only math; bc not available everywhere and shellcheck dislikes pipe-to-bc.
+    cache_rate_pct=$(( cache_hits * 100 / cache_total ))
+    ok "memory cache hit rate: ${cache_rate_pct}% (${cache_hits}/${cache_total} events)"
+    jq -nc \
+      --argjson hits "${cache_hits}" \
+      --argjson total "${cache_total}" \
+      --argjson pct "${cache_rate_pct}" \
+      '{check:"memory_cache", hits:$hits, total:$total, hit_rate_pct:$pct}'
+  else
+    ok "memory cache hit rate: n/a (events log present but empty)"
+    jq -nc '{check:"memory_cache", hits:0, total:0, hit_rate_pct:null}'
+  fi
+else
+  ok "memory cache hit rate: n/a (no events yet — run 'browser-do --intent' to generate cache observations)"
+  jq -nc '{check:"memory_cache", hits:0, total:0, hit_rate_pct:null}'
+fi
+
+# --- Tier 3: recent_urls.jsonl line count (advisory; forward-compat read side) ---
+# Parallel to memory_cache check above. Phase 11 v2 Pick A6 (PR #125) added
+# the writer; doctor reports the line count so users see passive observation
+# is actually accumulating. Absent log → 0 entries (not an error).
+recent_urls_log="${BROWSER_SKILL_HOME}/memory/recent_urls.jsonl"
+if [ -f "${recent_urls_log}" ]; then
+  recent_urls_count="$(jq -s 'length' "${recent_urls_log}" 2>/dev/null || printf '0')"
+  ok "recent_urls: ${recent_urls_count} entries (passive navigation log)"
+else
+  recent_urls_count=0
+  ok "recent_urls: 0 entries (no navigations yet — run 'browser-open --site SITE --url URL' to populate)"
+fi
+jq -nc --argjson n "${recent_urls_count}" '{check:"recent_urls", count:$n}'
+
+# --- Tier 3: stats.jsonl — per-action telemetry health (Phase 12 part 1) ---
+# Parallel to memory_cache + recent_urls checks. Reports event count, success
+# rate over the last 7 days, and an oblivious_success warning when > 0. Absent
+# log → 0 entries (not an error). Doctor never rebuilds the SQLite mirror —
+# that's `browser-stats rebuild`'s job.
+stats_jsonl_log="${BROWSER_SKILL_HOME}/memory/stats.jsonl"
+if [ -f "${stats_jsonl_log}" ]; then
+  # Phase 12 part 2 audit: single jq pass extracts {total, success, oblivious}
+  # in one file read + one fork. Replaces 3× sequential `jq -s` slurps.
+  stats_triple="$(jq -s -r '
+    [length,
+     (map(select(.outcome == "success")) | length),
+     (map(select(.failure_mode == "oblivious_success")) | length)] | @tsv
+  ' "${stats_jsonl_log}" 2>/dev/null || printf '0\t0\t0')"
+  IFS=$'\t' read -r stats_total stats_success stats_oblivious <<<"${stats_triple}"
+  stats_total="${stats_total:-0}"
+  stats_success="${stats_success:-0}"
+  stats_oblivious="${stats_oblivious:-0}"
+  if [ "${stats_total}" -gt 0 ]; then
+    stats_success_pct=$(( stats_success * 100 / stats_total ))
+    ok "stats events: ${stats_total} (${stats_success_pct}% success)"
+  else
+    ok "stats events: 0 (log present but empty)"
+    stats_success_pct=0
+  fi
+  if [ "${stats_oblivious}" -gt 0 ]; then
+    warn "${stats_oblivious} oblivious_success event(s) — adapter reported ok but post-condition failed; run 'browser-stats report'"
+    # Phase 14+ stats-driven pruning surface: count (site, selector)
+    # GROUPS that have accumulated ≥3 oblivious_success events overall.
+    # Doctor stays date-agnostic so the jq is fast + ISO-8601-precision
+    # agnostic; `browser-stats prune --days N` does the date-filtered
+    # version when the user investigates.
+    prune_count="$(jq -s -r '
+      [ .[] | select(.failure_mode == "oblivious_success"
+                     and .site != null and .selector_value != null) ]
+      | group_by([.site, .selector_value])
+      | map(select(length >= 3))
+      | length
+    ' "${stats_jsonl_log}" 2>/dev/null || printf '0')"
+    if [ "${prune_count}" -gt 0 ]; then
+      warn "${prune_count} cache archetype(s) with ≥3 oblivious_success in last 7d — run 'browser-stats prune' for candidates, '--apply' to disable"
+    fi
+  fi
+  jq -nc \
+    --argjson total "${stats_total}" \
+    --argjson success "${stats_success}" \
+    --argjson oblivious "${stats_oblivious}" \
+    --argjson pct "${stats_success_pct:-0}" \
+    '{check:"stats", total:$total, success:$success, success_pct:$pct, oblivious_success:$oblivious}'
+else
+  ok "stats events: 0 (no telemetry yet — emitted automatically by open/click/fill/snapshot/extract)"
+  jq -nc '{check:"stats", total:0, success:0, success_pct:null, oblivious_success:0}'
+fi
+
+# --- Phase 14: local VLM reachability (advisory; OPTIONAL stack, never fails doctor) ---
+# Probes the same endpoint scripts/browser-vlm.sh defaults to. Honors the
+# same BROWSER_SKILL_VLM_HOST + BROWSER_SKILL_VLM_PORT env overrides so doctor
+# and the vlm wrapper agree on what "the local VLM" means.
+# Outcomes:
+#   reachable     → ok: "local VLM reachable @ http://HOST:PORT (advisory)"
+#   unreachable   → ok: "local VLM not running (advisory — see browser-vlm.sh start)"
+# Never warns. The VLM is opt-in for Path 3 cache-rescue; absence is normal.
+vlm_host="${BROWSER_SKILL_VLM_HOST:-127.0.0.1}"
+vlm_port="${BROWSER_SKILL_VLM_PORT:-8080}"
+vlm_endpoint="http://${vlm_host}:${vlm_port}"
+vlm_reachable="false"
+if curl -sfm 2 "${vlm_endpoint}/health" >/dev/null 2>&1; then
+  vlm_reachable="true"
+  ok "local VLM reachable @ ${vlm_endpoint} (advisory — Path 3 cache-rescue ready)"
+else
+  ok "local VLM not running @ ${vlm_endpoint} (advisory — start via 'bash scripts/browser-vlm.sh start' if Path 3 wanted)"
+fi
+jq -nc --arg endpoint "${vlm_endpoint}" --argjson reachable "${vlm_reachable}" \
+  '{check:"local_vlm", endpoint:$endpoint, reachable:$reachable}'
+
+duration_ms=$(( $(now_ms) - started_at_ms ))
+
+# Status semantics (§5.3 of extension-model spec).
+if [ "${problems}" -gt 0 ]; then
+  overall_status="error"
+  exit_code="${EXIT_PREFLIGHT_FAILED}"
+elif [ "${adapters_ok}" -eq 0 ] && [ "${adapters_failed}" -gt 0 ]; then
+  overall_status="error"
+  exit_code="${EXIT_PREFLIGHT_FAILED}"
+elif [ "${adapters_failed}" -gt 0 ]; then
+  overall_status="partial"
+  exit_code="${EXIT_OK}"
+else
+  overall_status="ok"
+  exit_code="${EXIT_OK}"
+fi
+
+if [ "${overall_status}" = "ok" ]; then
+  ok "all checks passed (${adapters_ok} adapter(s) ok)"
+else
+  warn "${problems} core problem(s); ${adapters_ok} adapter(s) ok, ${adapters_failed} failed"
+fi
+
+summary_json verb=doctor tool=none why=health-check status="${overall_status}" \
+  problems="${problems}" \
+  adapters_ok="${adapters_ok}" adapters_failed="${adapters_failed}" \
+  duration_ms="${duration_ms}"
+exit "${exit_code}"

package/scripts/browser-drag.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# scripts/browser-drag.sh — pointer drag from src element to dst element by ref.
+# Usage: bash scripts/browser-drag.sh [--site NAME] [--tool NAME] [--dry-run]
+#                                      [--raw] --src-ref eA --dst-ref eB
+#
+# Routes to chrome-devtools-mcp by default (Phase 6 part 5). Stateful —
+# requires running daemon (refMap precondition for BOTH src and dst). MCP
+# `drag` tool accepts {src_uid, dst_uid}. Selector-based path is a follow-up
+# sub-part if user demand surfaces.
+
+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
+
+src_ref="" dst_ref=""
+verb_argv=()
+i=0
+while [ "${i}" -lt "${#REMAINING_ARGV[@]}" ]; do
+  case "${REMAINING_ARGV[i]}" in
+    --src-ref)
+      src_ref="${REMAINING_ARGV[i+1]:-}"
+      [ -n "${src_ref}" ] || die "${EXIT_USAGE_ERROR}" "--src-ref requires a value"
+      verb_argv+=(--src-ref "${src_ref}")
+      i=$((i + 2))
+      ;;
+    --dst-ref)
+      dst_ref="${REMAINING_ARGV[i+1]:-}"
+      [ -n "${dst_ref}" ] || die "${EXIT_USAGE_ERROR}" "--dst-ref requires a value"
+      verb_argv+=(--dst-ref "${dst_ref}")
+      i=$((i + 2))
+      ;;
+    *)
+      verb_argv+=("${REMAINING_ARGV[i]}")
+      i=$((i + 1))
+      ;;
+  esac
+done
+
+[ -n "${src_ref}" ] || die "${EXIT_USAGE_ERROR}" "drag requires --src-ref eN"
+[ -n "${dst_ref}" ] || die "${EXIT_USAGE_ERROR}" "drag requires --dst-ref eN"
+
+if [ "${ARG_DRY_RUN:-0}" = "1" ]; then
+  ok "dry-run: would drag ${src_ref} → ${dst_ref}"
+  emit_summary verb=drag tool=none why=dry-run status=ok \
+               src_ref="${src_ref}" dst_ref="${dst_ref}" dry_run=true
+  exit 0
+fi
+
+picked="$(pick_tool drag "${verb_argv[@]}")"
+tool_name="${picked%%$'\t'*}"
+why="${picked#*$'\t'}"
+
+source_picked_adapter "${tool_name}"
+
+set +e
+adapter_out="$(invoke_with_retry drag "${verb_argv[@]}")"
+adapter_rc=$?
+set -e
+
+[ -n "${adapter_out}" ] && printf '%s\n' "${adapter_out}"
+
+if [ "${adapter_rc}" -eq 0 ]; then
+  emit_summary verb=drag tool="${tool_name}" why="${why}" status=ok \
+               src_ref="${src_ref}" dst_ref="${dst_ref}"
+  exit 0
+fi
+emit_summary verb=drag tool="${tool_name}" why="${why}" status=error \
+             src_ref="${src_ref}" dst_ref="${dst_ref}"
+exit "${adapter_rc}"

package/scripts/browser-extract.sh

@@ -0,0 +1,192 @@
+#!/usr/bin/env bash
+# scripts/browser-extract.sh — extract content via CSS selector / JS / scrape.
+# Usage: bash scripts/browser-extract.sh [--site NAME] [--tool NAME] [--dry-run]
+#                                        [--raw]
+#                                        ( --selector CSS | --eval JS
+#                                        | --scrape [--eval JS] [--concurrency N] URL... )
+#
+# Routes to chrome-devtools-mcp by default for selector / eval (post-1d router
+# promotion — only adapter with `evaluate_script` + `list_network_requests`
+# per parent spec Appendix B). `--scrape` and `--stealth` auto-route to obscura
+# via rule_scrape_flag / rule_stealth_flag (Phase 8-2-i, Path B).
+# Exactly one mode is required: --selector / --eval / --scrape / --stealth.
+
+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"
+# shellcheck source=lib/stats.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/stats.sh"
+
+init_paths
+
+SUMMARY_T0="$(now_ms)"; export SUMMARY_T0
+
+parse_verb_globals "$@"
+
+resolve_session_storage_state
+
+selector="" eval_js="" mode_scrape=0 mode_stealth=0 concurrency=""
+verb_argv=()
+positional_urls=()
+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"
+      verb_argv+=(--selector "${selector}")
+      i=$((i + 2))
+      ;;
+    --eval)
+      eval_js="${REMAINING_ARGV[i+1]:-}"
+      [ -n "${eval_js}" ] || die "${EXIT_USAGE_ERROR}" "--eval requires a value"
+      verb_argv+=(--eval "${eval_js}")
+      i=$((i + 2))
+      ;;
+    --scrape)
+      mode_scrape=1
+      verb_argv+=(--scrape)
+      i=$((i + 1))
+      ;;
+    --stealth)
+      mode_stealth=1
+      verb_argv+=(--stealth)
+      i=$((i + 1))
+      ;;
+    --concurrency)
+      concurrency="${REMAINING_ARGV[i+1]:-}"
+      [ -n "${concurrency}" ] || die "${EXIT_USAGE_ERROR}" "--concurrency requires a value"
+      verb_argv+=(--concurrency "${concurrency}")
+      i=$((i + 2))
+      ;;
+    --*)
+      # Unknown flag — passthrough to adapter (defensive; adapter will reject
+      # if it doesn't recognise it).
+      verb_argv+=("${REMAINING_ARGV[i]}")
+      i=$((i + 1))
+      ;;
+    *)
+      # Positional. In --scrape / --stealth mode these are URLs. Outside both
+      # modes the verb script has no use for positionals (selector/eval are
+      # flag-only).
+      if [ "${mode_scrape}" = "1" ] || [ "${mode_stealth}" = "1" ]; then
+        positional_urls+=("${REMAINING_ARGV[i]}")
+        verb_argv+=("${REMAINING_ARGV[i]}")
+      else
+        die "${EXIT_USAGE_ERROR}" "unexpected positional arg '${REMAINING_ARGV[i]}' (use --selector / --eval / --scrape / --stealth)"
+      fi
+      i=$((i + 1))
+      ;;
+  esac
+done
+
+if [ "${mode_scrape}" = "1" ] && [ "${mode_stealth}" = "1" ]; then
+  die "${EXIT_USAGE_ERROR}" "--scrape and --stealth are mutually exclusive"
+fi
+
+if [ "${mode_scrape}" = "1" ]; then
+  [ "${#positional_urls[@]}" -ge 1 ] || die "${EXIT_USAGE_ERROR}" "--scrape requires at least one URL"
+elif [ "${mode_stealth}" = "1" ]; then
+  [ "${#positional_urls[@]}" -eq 1 ] || die "${EXIT_USAGE_ERROR}" "--stealth requires exactly one URL"
+  [ -n "${eval_js}" ]               || die "${EXIT_USAGE_ERROR}" "--stealth requires --eval EXPR"
+elif [ -z "${selector}" ] && [ -z "${eval_js}" ]; then
+  die "${EXIT_USAGE_ERROR}" "extract requires --selector CSS, --eval JS, --scrape URL..., or --stealth URL"
+fi
+
+if [ "${ARG_DRY_RUN:-0}" = "1" ]; then
+  if [ "${mode_scrape}" = "1" ]; then
+    ok "dry-run: would scrape ${#positional_urls[@]} URL(s) via obscura"
+    emit_summary verb=extract tool=none why=dry-run status=ok mode=scrape \
+      total_urls="${#positional_urls[@]}" dry_run=true
+  elif [ "${mode_stealth}" = "1" ]; then
+    ok "dry-run: would stealth-fetch ${positional_urls[0]} via obscura"
+    emit_summary verb=extract tool=none why=dry-run status=ok mode=stealth \
+      url="${positional_urls[0]}" dry_run=true
+  else
+    ok "dry-run: would extract ${selector:-${eval_js}}"
+    emit_summary verb=extract tool=none why=dry-run status=ok selector="${selector}" dry_run=true
+  fi
+  exit 0
+fi
+
+picked="$(pick_tool extract "${verb_argv[@]}")"
+tool_name="${picked%%$'\t'*}"
+why="${picked#*$'\t'}"
+
+source_picked_adapter "${tool_name}"
+
+stats_t0="$(now_ms)"
+set +e
+adapter_out="$(invoke_with_retry extract "${verb_argv[@]}")"
+adapter_rc=$?
+set -e
+
+# Phase 12 part 1: per-action telemetry. extract covers chrome-devtools-mcp
+# (default) + obscura (--scrape/--stealth). observed=adapter_out so
+# element_value post-conditions can match extracted text/JSON.
+BROWSER_STATS_OBSERVED="${adapter_out}" \
+  stats_run_adapter_emit \
+    "extract" "${tool_name}" "${stats_t0}" "${adapter_rc}" "${adapter_out}" "" \
+    -- "${verb_argv[@]}" || true
+
+[ -n "${adapter_out}" ] && printf '%s\n' "${adapter_out}"
+
+if [ "${mode_scrape}" = "1" ]; then
+  # Aggregate per-URL events into success/failure counts for the summary line.
+  total="${#positional_urls[@]}"
+  successful=0
+  failed=0
+  if [ -n "${adapter_out}" ]; then
+    successful="$(printf '%s\n' "${adapter_out}" | jq -s 'map(select(.event=="scrape_url" and (.title // false))) | length' 2>/dev/null || printf '0')"
+    failed="$(    printf '%s\n' "${adapter_out}" | jq -s 'map(select(.event=="scrape_url" and (.error // false))) | length' 2>/dev/null || printf '0')"
+  fi
+  if [ "${adapter_rc}" -ne 0 ]; then
+    overall_status=error
+  elif [ "${failed}" = "0" ]; then
+    overall_status=ok
+  elif [ "${successful}" = "0" ]; then
+    overall_status=error
+  else
+    overall_status=partial
+  fi
+  emit_summary verb=extract tool="${tool_name}" why="${why}" \
+    status="${overall_status}" mode=scrape \
+    total_urls="${total}" successful="${successful}" failed="${failed}"
+  [ "${overall_status}" = "ok" ] && exit 0
+  exit "${adapter_rc}"
+fi
+
+if [ "${mode_stealth}" = "1" ]; then
+  if [ "${adapter_rc}" -ne 0 ]; then
+    overall_status=error
+  elif [ -z "${adapter_out}" ]; then
+    overall_status=empty
+  else
+    overall_status=ok
+  fi
+  emit_summary verb=extract tool="${tool_name}" why="${why}" \
+    status="${overall_status}" mode=stealth url="${positional_urls[0]}"
+  [ "${overall_status}" = "ok" ] && exit 0
+  exit "${adapter_rc}"
+fi
+
+if [ "${adapter_rc}" -eq 0 ]; then
+  emit_summary verb=extract tool="${tool_name}" why="${why}" status=ok selector="${selector}"
+  exit 0
+fi
+emit_summary verb=extract tool="${tool_name}" why="${why}" status=error selector="${selector}"
+exit "${adapter_rc}"