browser-automation-skill 0.71.0

package/scripts/lib/tool/chrome-devtools-mcp.sh

@@ -0,0 +1,349 @@
+# scripts/lib/tool/chrome-devtools-mcp.sh — Chrome DevTools MCP tool adapter.
+#
+# Implements the Tool Adapter Extension Model contract from
+# docs/superpowers/specs/2026-04-30-tool-adapter-extension-model-design.md §2.
+#
+# Identity: tool_metadata, tool_capabilities, tool_doctor_check
+# Verb dispatch: tool_open, tool_click, tool_fill, tool_snapshot,
+#                tool_inspect, tool_audit, tool_extract, tool_eval
+#
+# Path A introduction: this adapter is reachable only via
+# `--tool=chrome-devtools-mcp`. Router promotion (Path B) for verbs like
+# `inspect`, `audit`, and capture-flag variants of primitives (per parent spec
+# Appendix B) is deferred to phase-05 part 1d.
+#
+# Architecture (phase-05 parts 1b / 1c / 1c-ii):
+# Verb-dispatch shells to a node ESM bridge at
+# scripts/lib/node/chrome-devtools-bridge.mjs which mirrors playwright-lib's
+# playwright-driver.mjs:
+# - Stub mode (BROWSER_SKILL_LIB_STUB=1): bridge looks up sha256(argv) in
+#   tests/fixtures/chrome-devtools-mcp/<sha>.json and echoes the contents.
+# - Real mode (one-shot): bridge spawns ${CHROME_DEVTOOLS_MCP_BIN} per call,
+#   does the MCP initialize handshake, dispatches one tools/call, exits.
+#   Used for stateless verbs (open / snapshot / eval / audit) when no daemon.
+# - Real mode (daemon, part 1c-ii): bridge daemon-start spawns a long-lived
+#   MCP child, holds the eN↔uid ref map, exposes verb dispatch over TCP
+#   loopback IPC. Stateful verbs (click / fill) require a running daemon and
+#   route through it. State at ${BROWSER_SKILL_HOME}/cdt-mcp-daemon.json.
+#
+# CHROME_DEVTOOLS_MCP_BIN env var semantics: in part 1 this was "the binary
+# the adapter shells to (real or stub)"; in part 1b it shifts to "the upstream
+# MCP server binary the bridge spawns in real mode". In stub mode it is
+# unused. The shift is documented in CHANGELOG and the cheatsheet.
+#
+# Adapters are LEAVES — never source another adapter (AP-2). Shared logic
+# factors into scripts/lib/<concern>.sh (sibling to lib/tool/).
+
+[ -n "${_BROWSER_TOOL_CHROME_DEVTOOLS_MCP_LOADED:-}" ] && return 0
+readonly _BROWSER_TOOL_CHROME_DEVTOOLS_MCP_LOADED=1
+
+# Required by spec 2026-05-01-token-efficient-adapter-output-design §8: every
+# adapter sources output.sh so verb-dispatch emits JSON via emit_summary /
+# emit_event rather than hand-rolled printf. Lint tier 3 enforces this.
+# shellcheck source=../output.sh
+# shellcheck disable=SC1091
+source "$(dirname "${BASH_SOURCE[0]}")/../output.sh"
+
+readonly _BROWSER_TOOL_CHROME_DEVTOOLS_MCP_NODE_BIN="${BROWSER_SKILL_NODE_BIN:-node}"
+readonly _BROWSER_TOOL_CHROME_DEVTOOLS_MCP_BRIDGE="$(dirname "${BASH_SOURCE[0]}")/../node/chrome-devtools-bridge.mjs"
+readonly _BROWSER_TOOL_CHROME_DEVTOOLS_MCP_MCP_SERVER_BIN="${CHROME_DEVTOOLS_MCP_BIN:-chrome-devtools-mcp}"
+
+# --- Identity functions ---
+
+tool_metadata() {
+  cat <<'EOF'
+{
+  "name": "chrome-devtools-mcp",
+  "abi_version": 1,
+  "version_pin": "0.x",
+  "cheatsheet_path": "references/chrome-devtools-mcp-cheatsheet.md",
+  "install_hint": "npm i -g chrome-devtools-mcp (or run via 'npx chrome-devtools-mcp@latest' over stdio MCP)"
+}
+EOF
+}
+
+tool_capabilities() {
+  cat <<'EOF'
+{
+  "verbs": {
+    "open":     { "flags": ["--headed", "--url"] },
+    "click":    { "flags": ["--ref"] },
+    "fill":     { "flags": ["--ref", "--text", "--secret-stdin"] },
+    "snapshot": { "flags": ["--depth"] },
+    "press":    { "flags": ["--key"] },
+    "select":   { "flags": ["--ref", "--value", "--label", "--index"] },
+    "hover":    { "flags": ["--ref"] },
+    "wait":     { "flags": ["--selector", "--state", "--timeout"] },
+    "drag":     { "flags": ["--src-ref", "--dst-ref"] },
+    "upload":   { "flags": ["--ref", "--path"] },
+    "route":    { "flags": ["--pattern", "--action"] },
+    "tab-list": { "flags": [] },
+    "tab-switch": { "flags": ["--by-index", "--by-url-pattern"] },
+    "tab-close":  { "flags": ["--tab-id", "--by-url-pattern"] },
+    "inspect":  { "flags": ["--capture-console", "--capture-network", "--screenshot"] },
+    "audit":    { "flags": ["--lighthouse", "--perf-trace"] },
+    "extract":  { "flags": ["--selector", "--eval"] },
+    "eval":     { "flags": ["--expression"] }
+  }
+}
+EOF
+}
+
+tool_doctor_check() {
+  if ! command -v "${_BROWSER_TOOL_CHROME_DEVTOOLS_MCP_NODE_BIN}" >/dev/null 2>&1; then
+    cat <<EOF
+{ "ok": false, "binary": "${_BROWSER_TOOL_CHROME_DEVTOOLS_MCP_NODE_BIN}", "error": "node not on PATH",
+  "install_hint": "brew install node (>=20)" }
+EOF
+    return 0
+  fi
+  if [ ! -f "${_BROWSER_TOOL_CHROME_DEVTOOLS_MCP_BRIDGE}" ]; then
+    printf '{"ok":false,"binary":"%s","error":"bridge missing","bridge_path":"%s"}\n' \
+      "${_BROWSER_TOOL_CHROME_DEVTOOLS_MCP_NODE_BIN}" "${_BROWSER_TOOL_CHROME_DEVTOOLS_MCP_BRIDGE}"
+    return 0
+  fi
+  local node_version
+  node_version="$("${_BROWSER_TOOL_CHROME_DEVTOOLS_MCP_NODE_BIN}" --version 2>/dev/null || printf 'unknown')"
+  printf '{"ok":true,"binary":"%s","node_version":"%s","mcp_server_bin":"%s","note":"real-mode MCP transport: 8/8 verbs (open/snapshot/eval/audit/inspect/extract one-shot or daemon; click/fill require daemon)"}\n' \
+    "${_BROWSER_TOOL_CHROME_DEVTOOLS_MCP_NODE_BIN}" "${node_version}" "${_BROWSER_TOOL_CHROME_DEVTOOLS_MCP_MCP_SERVER_BIN}"
+}
+
+# --- Verb-dispatch functions ---
+# Argv translation: skill flags → bridge's `<verb> [args...]` surface. Bridge
+# in stub mode hashes that surface (sha256 of args joined+terminated by NUL)
+# and looks up the fixture. Bridge in real mode (part 1c) translates to
+# MCP `tools/call` requests against the upstream chrome-devtools-mcp server.
+
+_drive() {
+  "${_BROWSER_TOOL_CHROME_DEVTOOLS_MCP_NODE_BIN}" "${_BROWSER_TOOL_CHROME_DEVTOOLS_MCP_BRIDGE}" "$@"
+}
+
+tool_open() {
+  local url=""
+  local rest=()
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --url) url="$2"; shift 2 ;;
+      *)     rest+=("$1"); shift ;;
+    esac
+  done
+  if [ -n "${url}" ]; then
+    _drive open "${url}" "${rest[@]}"
+  else
+    _drive open "${rest[@]}"
+  fi
+}
+
+tool_click() {
+  local target=""
+  local rest=()
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --ref|--selector) target="$2"; shift 2 ;;
+      *)                rest+=("$1"); shift ;;
+    esac
+  done
+  [ -n "${target}" ] || return 41
+  _drive click "${target}" "${rest[@]}"
+}
+
+tool_fill() {
+  local target="" text="" use_stdin=0
+  local rest=()
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --ref|--selector) target="$2"; shift 2 ;;
+      --text)           text="$2";   shift 2 ;;
+      --secret-stdin)   use_stdin=1; shift ;;
+      *)                rest+=("$1"); shift ;;
+    esac
+  done
+  [ -n "${target}" ] || return 41
+  if [ "${use_stdin}" = "1" ]; then
+    _drive fill "${target}" --secret-stdin "${rest[@]}"
+    return $?
+  fi
+  [ -n "${text}" ] || return 41
+  _drive fill "${target}" "${text}" "${rest[@]}"
+}
+
+tool_snapshot() {
+  _drive snapshot "$@"
+}
+
+tool_inspect() {
+  _drive inspect "$@"
+}
+
+tool_audit() {
+  _drive audit "$@"
+}
+
+tool_extract() {
+  _drive extract "$@"
+}
+
+tool_eval() {
+  local expression=""
+  local rest=()
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --expression) expression="$2"; shift 2 ;;
+      *)            rest+=("$1"); shift ;;
+    esac
+  done
+  if [ -n "${expression}" ]; then
+    _drive eval "${expression}" "${rest[@]}"
+  else
+    _drive eval "${rest[@]}"
+  fi
+}
+
+tool_press() {
+  local key=""
+  local rest=()
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --key) key="$2"; shift 2 ;;
+      *)     rest+=("$1"); shift ;;
+    esac
+  done
+  [ -n "${key}" ] || return 41
+  _drive press "${key}" "${rest[@]}"
+}
+
+tool_select() {
+  local ref=""
+  local mode_flag="" mode_val=""
+  local rest=()
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --ref|--selector)    ref="$2"; shift 2 ;;
+      --value|--label|--index)
+        mode_flag="$1"; mode_val="$2"; shift 2 ;;
+      *)                   rest+=("$1"); shift ;;
+    esac
+  done
+  [ -n "${ref}" ] || return 41
+  [ -n "${mode_flag}" ] || return 41
+  _drive select "${ref}" "${mode_flag}" "${mode_val}" "${rest[@]}"
+}
+
+tool_hover() {
+  local target=""
+  local rest=()
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --ref|--selector) target="$2"; shift 2 ;;
+      *)                rest+=("$1"); shift ;;
+    esac
+  done
+  [ -n "${target}" ] || return 41
+  _drive hover "${target}" "${rest[@]}"
+}
+
+tool_wait() {
+  local selector=""
+  local rest=()
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --selector) selector="$2"; shift 2 ;;
+      *)          rest+=("$1"); shift ;;
+    esac
+  done
+  [ -n "${selector}" ] || return 41
+  _drive wait "${selector}" "${rest[@]}"
+}
+
+tool_drag() {
+  local src_ref="" dst_ref=""
+  local rest=()
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --src-ref) src_ref="$2"; shift 2 ;;
+      --dst-ref) dst_ref="$2"; shift 2 ;;
+      *)         rest+=("$1"); shift ;;
+    esac
+  done
+  [ -n "${src_ref}" ] || return 41
+  [ -n "${dst_ref}" ] || return 41
+  _drive drag "${src_ref}" "${dst_ref}" "${rest[@]}"
+}
+
+tool_upload() {
+  local ref="" path=""
+  local rest=()
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --ref)  ref="$2";  shift 2 ;;
+      --path) path="$2"; shift 2 ;;
+      *)      rest+=("$1"); shift ;;
+    esac
+  done
+  [ -n "${ref}" ]  || return 41
+  [ -n "${path}" ] || return 41
+  _drive upload "${ref}" "${path}" "${rest[@]}"
+}
+
+tool_route() {
+  local pattern="" action=""
+  local rest=()
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --pattern) pattern="$2"; shift 2 ;;
+      --action)  action="$2";  shift 2 ;;
+      *)         rest+=("$1"); shift ;;
+    esac
+  done
+  [ -n "${pattern}" ] || return 41
+  [ -n "${action}" ]  || return 41
+  _drive route "${pattern}" "${action}" "${rest[@]}"
+}
+
+# Phase-6 part 8-i: read-only tab enumeration. No flags. Bridge dispatches
+# to runTabListViaDaemon which caches the result in the daemon's `tabs` slot.
+tool_tab-list() {
+  _drive tab-list "$@"
+}
+
+# Phase-6 part 8-ii: switch active tab via mutex selectors. Daemon-side
+# resolves to a tab_id, calls MCP select_page, updates currentTab pointer.
+tool_tab-switch() {
+  local by_index="" by_url_pattern=""
+  local rest=()
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --by-index)        by_index="$2";        shift 2 ;;
+      --by-url-pattern)  by_url_pattern="$2";  shift 2 ;;
+      *)                 rest+=("$1"); shift ;;
+    esac
+  done
+  if [ -n "${by_index}" ]; then
+    _drive tab-switch --by-index "${by_index}" "${rest[@]}"
+  elif [ -n "${by_url_pattern}" ]; then
+    _drive tab-switch --by-url-pattern "${by_url_pattern}" "${rest[@]}"
+  else
+    return 41
+  fi
+}
+
+# Phase-6 part 8-iii: close a tab. Splice + upstream close + null currentTab
+# on match. Mutex on the two selectors (enforced bash-side; bridge re-checks).
+tool_tab-close() {
+  local tab_id="" by_url_pattern=""
+  local rest=()
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --tab-id)          tab_id="$2";          shift 2 ;;
+      --by-url-pattern)  by_url_pattern="$2";  shift 2 ;;
+      *)                 rest+=("$1"); shift ;;
+    esac
+  done
+  if [ -n "${tab_id}" ]; then
+    _drive tab-close --tab-id "${tab_id}" "${rest[@]}"
+  elif [ -n "${by_url_pattern}" ]; then
+    _drive tab-close --by-url-pattern "${by_url_pattern}" "${rest[@]}"
+  else
+    return 41
+  fi
+}

package/scripts/lib/tool/obscura.sh

@@ -0,0 +1,249 @@
+# scripts/lib/tool/obscura.sh — Obscura tool adapter (shell only; verb-dispatch
+# stubs land real-mode in 8-1-ii / 8-1-iii).
+#
+# Implements the Tool Adapter Extension Model contract from
+# docs/superpowers/specs/2026-04-30-tool-adapter-extension-model-design.md §2.
+#
+# Identity: tool_metadata, tool_capabilities, tool_doctor_check
+# Verb dispatch: tool_open, tool_click, tool_fill, tool_snapshot, tool_inspect,
+#                tool_audit, tool_extract, tool_eval
+#
+# Obscura (https://github.com/h4ckf0r0day/obscura, Apache 2.0, Rust) ships in
+# two modes:
+#   1. Stateless one-shot CLI: `obscura fetch <url>` + `obscura scrape <urls...>`
+#   2. CDP server daemon:      `obscura serve --port 9222`
+#
+# This adapter targets ONLY mode 1 — the unique lane vs incumbents (parallel
+# scrape + stealth + 30/70 MB footprint). Mode 2 overlaps with playwright-lib's
+# CDP transport and will land there via a future --cdp-endpoint flag, NOT here.
+#
+# Reachable via --tool=obscura only in 8-1-i (Path A "ship-without-promotion"
+# per spec 2026-04-30 §4.4). Router promotion to default for --scrape /
+# --stealth lands in a follow-up PR (8-2-i, Path B).
+#
+# Adapters are LEAVES — never source another adapter. Shared logic factors into
+# scripts/lib/<concern>.sh (sibling to lib/tool/).
+
+[ -n "${_BROWSER_TOOL_OBSCURA_LOADED:-}" ] && return 0
+readonly _BROWSER_TOOL_OBSCURA_LOADED=1
+
+# Required by spec 2026-05-01-token-efficient-adapter-output-design §8: every
+# adapter sources output.sh so verb-dispatch emits JSON via emit_summary /
+# emit_event rather than hand-rolled printf. Lint tier 3 enforces this.
+# shellcheck source=../output.sh
+# shellcheck disable=SC1091
+source "$(dirname "${BASH_SOURCE[0]}")/../output.sh"
+
+readonly _BROWSER_TOOL_OBSCURA_BIN="${OBSCURA_BIN:-obscura}"
+
+# --- Identity functions (called by framework once or for queries) ---
+
+tool_metadata() {
+  cat <<'EOF'
+{
+  "name": "obscura",
+  "abi_version": 1,
+  "version_pin": "0.x",
+  "cheatsheet_path": "references/obscura-cheatsheet.md",
+  "install_hint": "download release from https://github.com/h4ckf0r0day/obscura/releases (no Chrome/Node required); keep obscura + obscura-worker side-by-side"
+}
+EOF
+}
+
+tool_capabilities() {
+  # Only `extract` declared — obscura's unique lane is stateless fetch/scrape.
+  # Stateful navigation (open/click/fill/snapshot) belongs to playwright-cli /
+  # playwright-lib / chrome-devtools-mcp; declaring them here would let the
+  # router fall back to obscura for verbs it can't actually serve.
+  #
+  # Flags array is advisory in v1 (per spec 2026-04-30 §2.1) — `--scrape` and
+  # `--stealth` are listed for documentation; real flag plumbing lands in
+  # 8-1-ii / 8-1-iii.
+  cat <<'EOF'
+{
+  "verbs": {
+    "extract": { "flags": ["--scrape", "--stealth", "--eval", "--selector"] }
+  }
+}
+EOF
+}
+
+tool_doctor_check() {
+  if ! command -v "${_BROWSER_TOOL_OBSCURA_BIN}" >/dev/null 2>&1; then
+    cat <<EOF
+{ "ok": false, "binary": "${_BROWSER_TOOL_OBSCURA_BIN}", "error": "not on PATH",
+  "install_hint": "download release from https://github.com/h4ckf0r0day/obscura/releases (no Chrome/Node required); keep obscura + obscura-worker side-by-side" }
+EOF
+    return 0
+  fi
+  local version
+  version="$("${_BROWSER_TOOL_OBSCURA_BIN}" --version 2>/dev/null || printf 'unknown')"
+  printf '{"ok":true,"binary":"%s","version":"%s"}\n' \
+    "${_BROWSER_TOOL_OBSCURA_BIN}" "${version}"
+}
+
+# --- Verb-dispatch functions ---
+# Each function:
+#   - Reads named flags from "$@".
+#   - Never accepts secrets in argv (uses --secret-stdin pattern).
+#   - Emits zero-or-more streaming JSON lines to stdout.
+#   - Returns 41 if it cannot handle the op (defensive — router shouldn't route
+#     here, but the guard is cheap).
+#
+# Phase 8 part 1-i: every verb returns 41. tool_extract becomes real-mode in
+# 8-1-ii (--scrape; this PR) and 8-1-iii (--stealth). All other verbs stay 41
+# forever — obscura is intentionally a one-shot extract-only adapter.
+
+tool_open()     { return 41; }
+tool_click()    { return 41; }
+tool_fill()     { return 41; }
+tool_snapshot() { return 41; }
+tool_inspect()  { return 41; }
+tool_audit()    { return 41; }
+tool_eval()     { return 41; }
+
+# tool_extract — Phase 8 part 1-ii (--scrape) + 1-iii (--stealth).
+#
+# Modes (router/verb selects via flags; mutually exclusive):
+#   --scrape <url1> <url2> ... [--eval EXPR] [--concurrency N]
+#       Wraps `obscura scrape u1 u2 ... --eval EXPR --format json`. Emits one
+#       `scrape_url` event per URL on stdout (success or error shape from
+#       obscura's per-result divergence in run_parallel_scrape).
+#   --stealth <url> --eval EXPR
+#       Wraps `obscura fetch <url> --stealth --eval EXPR`. Single URL.
+#       --eval REQUIRED (without it, obscura fetch dumps full HTML — too large
+#       for the streaming-event contract). Emits one `extract_stealth` event:
+#       {event, url, eval, time_ms}. Adapter times the call (fetch doesn't
+#       report time). `eval` always emitted as string (obscura fetch --eval
+#       prints raw, not wrapped JSON; typed parsing deferred).
+#   --selector / --eval (single URL, no --scrape / --stealth) — never supported
+#       here; routed to chrome-devtools-mcp / playwright-cli.
+#
+# Returns:
+#   0  on successful adapter call (per-URL event stream may include errors).
+#   2  on USAGE_ERROR (empty URL list with --scrape; missing URL or --eval
+#      with --stealth).
+#   41 if no recognized mode OR mutually-exclusive modes selected.
+tool_extract() {
+  local mode_scrape=0 mode_stealth=0 eval_expr="" concurrency=""
+  local urls=()
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --scrape)      mode_scrape=1; shift ;;
+      --stealth)     mode_stealth=1; shift ;;
+      --eval)        eval_expr="$2"; shift 2 ;;
+      --concurrency) concurrency="$2"; shift 2 ;;
+      --selector|--site|--tool|--dry-run|--raw)
+        # Recognised skill flags not consumed by this adapter.
+        case "$1" in
+          --dry-run|--raw) shift ;;
+          *)               shift 2 ;;
+        esac
+        ;;
+      --*)
+        # Unknown flag — passthrough to obscura would mask config drift; reject.
+        return 41
+        ;;
+      *)             urls+=("$1"); shift ;;
+    esac
+  done
+
+  # Mutually-exclusive mode selection.
+  if [ "${mode_scrape}" = "1" ] && [ "${mode_stealth}" = "1" ]; then
+    return 41
+  fi
+
+  if [ "${mode_scrape}" = "1" ]; then
+    _tool_extract_scrape "${eval_expr}" "${concurrency}" "${urls[@]}"
+    return $?
+  fi
+
+  if [ "${mode_stealth}" = "1" ]; then
+    _tool_extract_stealth "${eval_expr}" "${urls[@]}"
+    return $?
+  fi
+
+  # No recognised mode. Other one-shot extract paths route elsewhere.
+  return 41
+}
+
+# _tool_extract_scrape EVAL_EXPR CONCURRENCY URLS...
+# Internal helper — wraps `obscura scrape`.
+_tool_extract_scrape() {
+  local eval_expr="$1" concurrency="$2"
+  shift 2
+  local urls=("$@")
+
+  if [ "${#urls[@]}" -eq 0 ]; then
+    return 2
+  fi
+
+  # Canonical argv (sha256-of-argv must be stable for fixture-based stub):
+  #   scrape <urls...> [--eval EXPR] [--concurrency N] --format json
+  local args=("scrape" "${urls[@]}")
+  [ -n "${eval_expr}" ]   && args+=(--eval "${eval_expr}")
+  [ -n "${concurrency}" ] && args+=(--concurrency "${concurrency}")
+  args+=(--format json)
+
+  local raw
+  if ! raw="$("${_BROWSER_TOOL_OBSCURA_BIN}" "${args[@]}" 2>/dev/null)"; then
+    return 41
+  fi
+
+  # Reshape obscura's per-URL .results[] into one streaming event line per URL.
+  # Direct jq pass-through preserves the eval field's JSON typing (string /
+  # number / array / null / object — emit_event can't carry arbitrary JSON
+  # values). Summary line built by browser-extract.sh via emit_summary.
+  printf '%s' "${raw}" | jq -c '
+    .results[] |
+    {event: "scrape_url"} +
+      if has("error") then
+        {url, error, time_ms}
+      else
+        {url, title, eval, time_ms}
+      end
+  ' || return 41
+
+  return 0
+}
+
+# _tool_extract_stealth EVAL_EXPR URLS...
+# Internal helper — wraps `obscura fetch <url> --stealth --eval EXPR`.
+# Single URL (rejects 0 or ≥2). --eval required.
+_tool_extract_stealth() {
+  local eval_expr="$1"
+  shift
+  local urls=("$@")
+
+  if [ "${#urls[@]}" -ne 1 ]; then
+    return 2
+  fi
+  if [ -z "${eval_expr}" ]; then
+    return 2
+  fi
+  local url="${urls[0]}"
+
+  # Canonical argv: fetch <url> --stealth --eval EXPR
+  local args=("fetch" "${url}" --stealth --eval "${eval_expr}")
+
+  # No time_ms field (obscura fetch doesn't report timing; the verb-script's
+  # summary already carries end-to-end duration_ms via SUMMARY_T0). Adapters
+  # are leaves — don't source common.sh's now_ms; don't fabricate timing.
+  local raw
+  if ! raw="$("${_BROWSER_TOOL_OBSCURA_BIN}" "${args[@]}" 2>/dev/null)"; then
+    return 41
+  fi
+
+  # obscura fetch --eval prints raw evaluated result (string unquoted; other
+  # JSON-encoded). Strip trailing newline; emit as string. Typed parsing
+  # deferred — callers needing typed results should JSON.stringify in EXPR.
+  local eval_out
+  eval_out="${raw%$'\n'}"
+
+  jq -nc \
+    --arg url "${url}" \
+    --arg eval_val "${eval_out}" \
+    '{event: "extract_stealth", url: $url, eval: $eval_val}'
+
+  return 0
+}