browser-automation-skill 0.71.0

package/scripts/lib/tool/playwright-cli.sh

@@ -0,0 +1,155 @@
+# scripts/lib/tool/playwright-cli.sh — Playwright CLI 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
+# All verb-dispatch functions in this file currently shell to the playwright
+# binary (real path) OR to ${PLAYWRIGHT_CLI_BIN:-playwright} (overridable for
+# tests, which set it to tests/stubs/playwright-cli).
+#
+# Adapters are LEAVES — never source another adapter. Shared logic factors into
+# scripts/lib/<concern>.sh (sibling to lib/tool/).
+
+[ -n "${_BROWSER_TOOL_PLAYWRIGHT_CLI_LOADED:-}" ] && return 0
+readonly _BROWSER_TOOL_PLAYWRIGHT_CLI_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_PLAYWRIGHT_CLI_BIN="${PLAYWRIGHT_CLI_BIN:-playwright-cli}"
+readonly _BROWSER_TOOL_PLAYWRIGHT_CLI_DEFAULT_VIEWPORT="1280x800"
+
+# --- Identity functions (called by framework once or for queries) ---
+
+tool_metadata() {
+  cat <<'EOF'
+{
+  "name": "playwright-cli",
+  "abi_version": 1,
+  "version_pin": "1.49.x",
+  "cheatsheet_path": "references/playwright-cli-cheatsheet.md",
+  "install_hint": "npm i -g playwright @playwright/test @playwright/cli && playwright install chromium"
+}
+EOF
+}
+
+tool_capabilities() {
+  cat <<'EOF'
+{
+  "verbs": {
+    "open":     { "flags": ["--headed", "--viewport", "--user-agent"] },
+    "click":    { "flags": ["--ref", "--selector"] },
+    "fill":     { "flags": ["--ref", "--text"] },
+    "snapshot": { "flags": ["--depth"] }
+  }
+}
+EOF
+}
+
+tool_doctor_check() {
+  if ! command -v "${_BROWSER_TOOL_PLAYWRIGHT_CLI_BIN}" >/dev/null 2>&1; then
+    cat <<EOF
+{ "ok": false, "binary": "${_BROWSER_TOOL_PLAYWRIGHT_CLI_BIN}", "error": "not on PATH",
+  "install_hint": "npm i -g playwright @playwright/test @playwright/cli && playwright install chromium" }
+EOF
+    return 0
+  fi
+  local version
+  version="$("${_BROWSER_TOOL_PLAYWRIGHT_CLI_BIN}" --version 2>/dev/null || printf 'unknown')"
+  printf '{"ok":true,"binary":"%s","version":"%s"}\n' \
+    "${_BROWSER_TOOL_PLAYWRIGHT_CLI_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).
+
+# Skill→tool argv translation: real playwright-cli takes most args as positional
+# (e.g. `open <url>`, `click <ref>`, `fill <ref> <text>`). Adapters are the
+# translation boundary — verb scripts speak skill-flag surface, adapters convert.
+
+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
+    "${_BROWSER_TOOL_PLAYWRIGHT_CLI_BIN}" open "${url}" "${rest[@]}"
+  else
+    "${_BROWSER_TOOL_PLAYWRIGHT_CLI_BIN}" 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
+  "${_BROWSER_TOOL_PLAYWRIGHT_CLI_BIN}" 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
+  if [ "${use_stdin}" = "1" ]; then
+    # playwright-cli has no stdin-secret mode; passing the secret as a
+    # positional arg would leak it via argv (anti-pattern AP-7). Reject —
+    # routing should pick playwright-lib (Phase 4) which reads stdin in node.
+    return 41
+  fi
+  [ -n "${target}" ] && [ -n "${text}" ] || return 41
+  "${_BROWSER_TOOL_PLAYWRIGHT_CLI_BIN}" fill "${target}" "${text}" "${rest[@]}"
+}
+
+tool_snapshot() {
+  # snapshot takes no required args; --depth N pass-through is a real
+  # playwright-cli flag (recognised by the binary natively).
+  "${_BROWSER_TOOL_PLAYWRIGHT_CLI_BIN}" snapshot "$@"
+}
+
+tool_inspect() {
+  # Real playwright-cli has no `inspect` subcommand; the closest composition
+  # (snapshot + eval per-ref) is non-trivial and lives in Phase 5 chrome-
+  # devtools-mcp adapter (which has first-class console + network + eval).
+  return 41
+}
+
+tool_audit() {
+  return 41
+}
+
+tool_extract() {
+  return 41
+}
+
+tool_eval() {
+  "${_BROWSER_TOOL_PLAYWRIGHT_CLI_BIN}" eval "$@"
+}

package/scripts/lib/tool/playwright-lib.sh

@@ -0,0 +1,106 @@
+# scripts/lib/tool/playwright-lib.sh — Playwright (node-bridge) tool adapter.
+#
+# Implements the Tool Adapter Extension Model contract from
+# docs/superpowers/specs/2026-04-30-tool-adapter-extension-model-design.md §2.
+#
+# Routes verb dispatch to scripts/lib/node/playwright-driver.mjs which speaks
+# the real Playwright API. Stub mode (BROWSER_SKILL_LIB_STUB=1) is used by
+# tests + CI; real mode lands when the driver's real branch ships.
+#
+# Distinction from playwright-cli adapter:
+# - playwright-cli shells to a binary that takes positional args (translation
+#   needed at adapter boundary).
+# - playwright-lib shells to a node script that speaks skill-flag surface
+#   directly (driver constructs Playwright API calls), so no translation here.
+# - playwright-lib supports --secret-stdin natively (driver reads stdin in node).
+# - playwright-lib supports session loading via BROWSER_SKILL_STORAGE_STATE env.
+
+[ -n "${_BROWSER_TOOL_PLAYWRIGHT_LIB_LOADED:-}" ] && return 0
+readonly _BROWSER_TOOL_PLAYWRIGHT_LIB_LOADED=1
+
+# Required by spec 2026-05-01-token-efficient-adapter-output-design §8.
+# shellcheck source=../output.sh
+# shellcheck disable=SC1091
+source "$(dirname "${BASH_SOURCE[0]}")/../output.sh"
+
+readonly _BROWSER_TOOL_PLAYWRIGHT_LIB_NODE_BIN="${BROWSER_SKILL_NODE_BIN:-node}"
+readonly _BROWSER_TOOL_PLAYWRIGHT_LIB_DRIVER="$(dirname "${BASH_SOURCE[0]}")/../node/playwright-driver.mjs"
+
+# --- Identity functions ---
+
+tool_metadata() {
+  cat <<'EOF'
+{
+  "name": "playwright-lib",
+  "abi_version": 1,
+  "version_pin": "1.59.x",
+  "cheatsheet_path": "references/playwright-lib-cheatsheet.md",
+  "install_hint": "npm i -g playwright @playwright/test && playwright install chromium"
+}
+EOF
+}
+
+tool_capabilities() {
+  cat <<'EOF'
+{
+  "verbs": {
+    "open":     { "flags": ["--headed", "--viewport", "--user-agent", "--storage-state"] },
+    "click":    { "flags": ["--ref", "--selector"] },
+    "fill":     { "flags": ["--ref", "--text", "--secret-stdin"] },
+    "snapshot": { "flags": ["--depth"] },
+    "login":    { "flags": ["--storage-state"] }
+  },
+  "session_load": true
+}
+EOF
+}
+
+tool_doctor_check() {
+  if ! command -v "${_BROWSER_TOOL_PLAYWRIGHT_LIB_NODE_BIN}" >/dev/null 2>&1; then
+    cat <<EOF
+{ "ok": false, "binary": "${_BROWSER_TOOL_PLAYWRIGHT_LIB_NODE_BIN}", "error": "node not on PATH",
+  "install_hint": "brew install node (>=20)" }
+EOF
+    return 0
+  fi
+  if [ ! -f "${_BROWSER_TOOL_PLAYWRIGHT_LIB_DRIVER}" ]; then
+    printf '{"ok":false,"binary":"%s","error":"driver missing","driver_path":"%s"}\n' \
+      "${_BROWSER_TOOL_PLAYWRIGHT_LIB_NODE_BIN}" "${_BROWSER_TOOL_PLAYWRIGHT_LIB_DRIVER}"
+    return 0
+  fi
+  local node_version
+  node_version="$("${_BROWSER_TOOL_PLAYWRIGHT_LIB_NODE_BIN}" --version 2>/dev/null || printf 'unknown')"
+  printf '{"ok":true,"binary":"%s","node_version":"%s"}\n' \
+    "${_BROWSER_TOOL_PLAYWRIGHT_LIB_NODE_BIN}" "${node_version}"
+}
+
+# --- Verb-dispatch functions ---
+# Driver receives skill-flag argv directly; no translation needed.
+# BROWSER_SKILL_STORAGE_STATE (set by verb script when --site/--as resolved)
+# is forwarded as --storage-state PATH to the driver when present.
+
+_drive() {
+  local verb="$1"
+  shift
+  local extra=()
+  if [ -n "${BROWSER_SKILL_STORAGE_STATE:-}" ]; then
+    extra+=(--storage-state "${BROWSER_SKILL_STORAGE_STATE}")
+  fi
+  "${_BROWSER_TOOL_PLAYWRIGHT_LIB_NODE_BIN}" "${_BROWSER_TOOL_PLAYWRIGHT_LIB_DRIVER}" \
+    "${verb}" "${extra[@]}" "$@"
+}
+
+tool_open()     { _drive open     "$@"; }
+tool_click()    { _drive click    "$@"; }
+tool_fill()     { _drive fill     "$@"; }
+tool_snapshot() { _drive snapshot "$@"; }
+tool_inspect()  { return 41; }   # Phase 5 chrome-devtools-mcp territory.
+tool_audit()    { return 41; }
+tool_extract()  { return 41; }
+tool_eval()     { _drive eval     "$@"; }
+
+# Phase-2 carry-forward: login was emitted with tool=playwright-lib-stub before
+# this adapter existed. Now login routes here; verb script's tool field becomes
+# tool=playwright-lib. The driver's stub mode currently echoes a canned login
+# fixture; real mode launches a headed browser for storageState capture.
+tool_login() { _drive login "$@"; }

package/scripts/lib/verb_helpers.sh

@@ -0,0 +1,222 @@
+# scripts/lib/verb_helpers.sh — shared verb-script boilerplate.
+# Every scripts/browser-<verb>.sh sources this AFTER common.sh + router.sh.
+# See: docs/superpowers/plans/2026-05-01-phase-03-part-2-real-verbs.md Task 1
+# and docs/superpowers/plans/2026-05-01-phase-04-real-playwright-and-sessions.md Task 3.
+
+[ -n "${BROWSER_SKILL_VERB_HELPERS_LOADED:-}" ] && return 0
+readonly BROWSER_SKILL_VERB_HELPERS_LOADED=1
+
+# Site + session libs are needed by resolve_session_storage_state. Source
+# guards in those files prevent double-loading.
+# shellcheck source=site.sh
+# shellcheck disable=SC1091
+source "$(dirname "${BASH_SOURCE[0]}")/site.sh"
+# shellcheck source=session.sh
+# shellcheck disable=SC1091
+source "$(dirname "${BASH_SOURCE[0]}")/session.sh"
+
+# parse_verb_globals "$@" — peels off the global flags every verb supports:
+#   --site NAME           — site profile name (overrides 'current')
+#   --tool NAME           — force a specific adapter (sets ARG_TOOL → router)
+#   --dry-run             — print planned action, write nothing
+#   --raw                 — strip streaming + summary; emit only the value (spec §4)
+# Exports ARG_SITE / ARG_TOOL / ARG_DRY_RUN / ARG_RAW (unset if not present).
+# Remaining argv (non-global flags) goes into REMAINING_ARGV[].
+parse_verb_globals() {
+  REMAINING_ARGV=()
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --site)
+        [ -n "${2:-}" ] || die "${EXIT_USAGE_ERROR}" "--site requires a value"
+        ARG_SITE="$2"; export ARG_SITE
+        shift 2
+        ;;
+      --tool)
+        [ -n "${2:-}" ] || die "${EXIT_USAGE_ERROR}" "--tool requires a value"
+        ARG_TOOL="$2"; export ARG_TOOL
+        shift 2
+        ;;
+      --as)
+        [ -n "${2:-}" ] || die "${EXIT_USAGE_ERROR}" "--as requires a value"
+        ARG_AS="$2"; export ARG_AS
+        shift 2
+        ;;
+      --dry-run)
+        ARG_DRY_RUN=1; export ARG_DRY_RUN
+        shift
+        ;;
+      --raw)
+        ARG_RAW=1; export ARG_RAW
+        shift
+        ;;
+      *)
+        REMAINING_ARGV+=("$1")
+        shift
+        ;;
+    esac
+  done
+}
+
+# source_picked_adapter TOOL_NAME — source $LIB_TOOL_DIR/<name>.sh in the
+# current shell. Dies with EXIT_TOOL_MISSING if the file is absent.
+# Caller MUST have called init_paths first (sets LIB_TOOL_DIR).
+source_picked_adapter() {
+  local tool="$1"
+  local file="${LIB_TOOL_DIR}/${tool}.sh"
+  if [ ! -f "${file}" ]; then
+    die "${EXIT_TOOL_MISSING}" "adapter file not found: ${tool} (no ${file})"
+  fi
+  # shellcheck source=/dev/null
+  source "${file}"
+}
+
+# resolve_session_storage_state — maps ARG_SITE / ARG_AS to a storageState
+# file path; exports BROWSER_SKILL_STORAGE_STATE when applicable. The router's
+# rule_session_required reads that env var to prefer playwright-lib (the only
+# adapter declaring session_load: true).
+#
+# Resolution order:
+#   1. If neither ARG_SITE nor ARG_AS set → no-op (export nothing).
+#   2. If ARG_AS without ARG_SITE → EXIT_USAGE_ERROR (which site?).
+#   3. ARG_SITE missing on disk → EXIT_SITE_NOT_FOUND (23).
+#   4. Pick session: ARG_AS > site.default_session > nothing (no-op).
+#   5. Session missing on disk → EXIT_SESSION_EXPIRED (22) with self-healing hint.
+#   6. Session origin doesn't match site URL → EXIT_SESSION_EXPIRED (22).
+#   7. Otherwise: export BROWSER_SKILL_STORAGE_STATE=<sessions-dir>/<name>.json.
+resolve_session_storage_state() {
+  if [ -z "${ARG_SITE:-}" ] && [ -z "${ARG_AS:-}" ]; then
+    return 0
+  fi
+  if [ -z "${ARG_SITE:-}" ]; then
+    die "${EXIT_USAGE_ERROR}" "--as requires --site (which site does this session belong to?)"
+  fi
+
+  if ! site_exists "${ARG_SITE}"; then
+    die "${EXIT_SITE_NOT_FOUND}" "site '${ARG_SITE}' not registered (try: ${0##*/} add-site --name ${ARG_SITE} --url ...)"
+  fi
+
+  local profile site_url default_session session_name
+  profile="$(site_load "${ARG_SITE}")"
+  site_url="$(jq -r .url <<<"${profile}")"
+  default_session="$(jq -r '.default_session // ""' <<<"${profile}")"
+
+  if [ -n "${ARG_AS:-}" ]; then
+    session_name="${ARG_AS}"
+  elif [ -n "${default_session}" ]; then
+    session_name="${default_session}"
+  else
+    return 0
+  fi
+
+  if ! session_exists "${session_name}"; then
+    die "${EXIT_SESSION_EXPIRED}" "session '${session_name}' not found (run: ${0##*/} login --site ${ARG_SITE} --as ${session_name} --storage-state-file PATH)"
+  fi
+
+  # session_origin_check `die`s on mismatch — wrap in subshell so failure is
+  # caught here and we can emit a verb-aware self-healing hint.
+  if ! ( session_origin_check "${session_name}" "${site_url}" >/dev/null 2>&1 ); then
+    die "${EXIT_SESSION_EXPIRED}" "session '${session_name}' origins do not match site '${ARG_SITE}' (URL ${site_url}); re-login required"
+  fi
+
+  BROWSER_SKILL_STORAGE_STATE="${SESSIONS_DIR}/${session_name}.json"
+  export BROWSER_SKILL_STORAGE_STATE
+}
+
+# --- Phase 5 part 3-ii: transparent verb-retry on EXIT_SESSION_EXPIRED -------
+#
+# When a verb's adapter dispatch (tool_VERB) exits 22 (EXIT_SESSION_EXPIRED)
+# AND the current --site / --as has a credential with auto_relogin: true,
+# silently re-login via `bash browser-login.sh --auto` and retry the verb
+# EXACTLY ONCE. Per parent spec §4.4: every verb call → silent re-login →
+# retry, exactly one attempt. Wires into one verb (snapshot) in this PR;
+# remaining verbs in follow-ups.
+
+# invoke_with_retry VERB ARGS... — runs tool_${VERB} ARGS, returning its
+# stdout + exit code. On EXIT_SESSION_EXPIRED (22), if a credential with
+# auto_relogin: true exists for the resolved site/cred, runs login --auto
+# silently then retries the verb ONCE. Caller sees a single stdout + final rc.
+invoke_with_retry() {
+  local verb="$1"
+  shift
+
+  local out rc
+  set +e
+  out="$(tool_"${verb}" "$@")"
+  rc=$?
+  set -e
+
+  if [ "${rc}" -ne "${EXIT_SESSION_EXPIRED}" ]; then
+    printf '%s' "${out}"
+    return "${rc}"
+  fi
+  if ! _can_auto_relogin; then
+    printf '%s' "${out}"
+    return "${rc}"
+  fi
+  if ! _silent_relogin >/dev/null 2>&1; then
+    printf '%s' "${out}"
+    return "${rc}"
+  fi
+
+  # Re-resolve session storage state so the retry picks up the fresh file.
+  resolve_session_storage_state
+
+  set +e
+  out="$(tool_"${verb}" "$@")"
+  rc=$?
+  set -e
+  printf '%s' "${out}"
+  return "${rc}"
+}
+
+# _can_auto_relogin — returns 0 iff: ARG_SITE set + a credential exists
+# (resolved name = ARG_AS or site.default_session) + that credential's
+# metadata declares auto_relogin: true (default for new creds per part 2d).
+_can_auto_relogin() {
+  [ -n "${ARG_SITE:-}" ] || return 1
+  local cred_name
+  cred_name="$(_resolve_relogin_cred_name 2>/dev/null)" || return 1
+  [ -n "${cred_name}" ] || return 1
+
+  # credential.sh may not be sourced in every verb script. Source on demand.
+  if ! command -v credential_load >/dev/null 2>&1; then
+    # shellcheck source=credential.sh
+    # shellcheck disable=SC1091
+    source "$(dirname "${BASH_SOURCE[0]}")/credential.sh" 2>/dev/null || return 1
+  fi
+
+  local cred_meta auto_relogin
+  cred_meta="$(credential_load "${cred_name}" 2>/dev/null)" || return 1
+  auto_relogin="$(jq -r '.auto_relogin // false' <<<"${cred_meta}" 2>/dev/null)"
+  [ "${auto_relogin}" = "true" ]
+}
+
+# _resolve_relogin_cred_name — resolves the credential name for retry. Mirrors
+# session-resolution: prefer ARG_AS; fall back to site's default_session;
+# return non-zero if neither.
+_resolve_relogin_cred_name() {
+  if [ -n "${ARG_AS:-}" ]; then
+    printf '%s' "${ARG_AS}"
+    return 0
+  fi
+  if [ -n "${ARG_SITE:-}" ] && site_exists "${ARG_SITE}"; then
+    local profile default_session
+    profile="$(site_load "${ARG_SITE}")"
+    default_session="$(jq -r '.default_session // ""' <<<"${profile}" 2>/dev/null)"
+    if [ -n "${default_session}" ]; then
+      printf '%s' "${default_session}"
+      return 0
+    fi
+  fi
+  return 1
+}
+
+# _silent_relogin — runs `bash browser-login.sh --auto` for the resolved cred.
+# Stdout/stderr suppressed by caller (`>/dev/null 2>&1`). Returns its exit code.
+_silent_relogin() {
+  local cred_name
+  cred_name="$(_resolve_relogin_cred_name)" || return 1
+  local helpers_dir
+  helpers_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  bash "${helpers_dir}/../browser-login.sh" --auto --site "${ARG_SITE}" --as "${cred_name}"
+}

package/scripts/lib/visual-rescue-default.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+# scripts/lib/visual-rescue-default.sh — canonical Path 3 probe (text-mode).
+#
+# Implements the BROWSER_SKILL_VISUAL_RESCUE_CMD hook contract from
+# scripts/browser-do.sh (Phase 14 Path 3). Decides whether a cached selector
+# is still semantically present on the page by sending the CURRENT
+# accessibility snapshot + the original intent to a local OpenAI-compatible
+# VLM endpoint (default: http://127.0.0.1:8080 — same as scripts/browser-vlm.sh).
+#
+# Mode: text-based (v1). Reads the accessibility-tree YAML snapshot (cheap,
+# ~2KB) and asks the VLM yes/no. NO screenshot is sent — a true vision-mode
+# default ships in a future commit once the screenshot-from-live-session
+# infrastructure lands.
+#
+# Why this is the right v1 default:
+#   - llama-server's text completion is much faster than vision (~200ms vs ~1500ms)
+#   - works against ANY OpenAI-compatible LLM, not just VLMs
+#   - accessibility snapshots already encode what UI is visible
+#   - no new infrastructure needed (browser-snapshot.sh is shipped)
+#
+# Hook contract (per browser-do.sh):
+#   $1 SITE   $2 INTENT   $3 CACHED_SELECTOR
+#   exit 0 + stdout "yes" → cache rescued
+#   exit 0 + stdout "no"  → fall through to cloud LLM
+#   non-zero exit         → fall through (treated as "unreachable")
+#
+# Env overrides:
+#   BROWSER_SKILL_VLM_HOST            127.0.0.1
+#   BROWSER_SKILL_VLM_PORT            8080
+#   BROWSER_SKILL_VLM_RESCUE_MODEL    "q"  (arbitrary tag; llama-server ignores)
+#   BROWSER_SKILL_VLM_RESCUE_TIMEOUT  30   (seconds, end-to-end)
+#   BROWSER_SKILL_SCRIPTS_DIR         derived from BASH_SOURCE if unset
+#   BROWSER_SKILL_RESCUE_SNAPSHOT_BYTES  2048 (truncation cap for snapshot text)
+
+set -euo pipefail
+IFS=$'\n\t'
+
+site="${1:-}"
+intent="${2:-}"
+selector="${3:-}"
+
+if [ -z "${site}" ] || [ -z "${intent}" ] || [ -z "${selector}" ]; then
+  echo "no"
+  exit 2
+fi
+
+vlm_host="${BROWSER_SKILL_VLM_HOST:-127.0.0.1}"
+vlm_port="${BROWSER_SKILL_VLM_PORT:-8080}"
+vlm_model="${BROWSER_SKILL_VLM_RESCUE_MODEL:-q}"
+vlm_timeout="${BROWSER_SKILL_VLM_RESCUE_TIMEOUT:-30}"
+snap_cap="${BROWSER_SKILL_RESCUE_SNAPSHOT_BYTES:-2048}"
+endpoint="http://${vlm_host}:${vlm_port}/v1/chat/completions"
+
+# Gate 1: reachability. With lazy auto-start (default ON), the probe will
+# try to spawn llama-server via browser-vlm.sh if it's down, and poll
+# /health up to BROWSER_SKILL_LAZY_START_TIMEOUT seconds (default 60).
+# Disable lazy-start by setting BROWSER_SKILL_LAZY_START=0 (the probe then
+# fails fast like v1).
+if ! curl -sfm 2 "http://${vlm_host}:${vlm_port}/health" >/dev/null 2>&1; then
+  if [ "${BROWSER_SKILL_LAZY_START:-1}" = "1" ]; then
+    SCRIPTS_DIR_FOR_VLM="${BROWSER_SKILL_SCRIPTS_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+    vlm_script="${SCRIPTS_DIR_FOR_VLM}/browser-vlm.sh"
+    if [ -f "${vlm_script}" ]; then
+      # Start in background — browser-vlm.sh handles nohup + pidfile.
+      bash "${vlm_script}" start >/dev/null 2>&1 || true
+      # Poll until /health responds OR timeout.
+      timeout_s="${BROWSER_SKILL_LAZY_START_TIMEOUT:-60}"
+      waited=0
+      while [ "${waited}" -lt "${timeout_s}" ]; do
+        if curl -sfm 2 "http://${vlm_host}:${vlm_port}/health" >/dev/null 2>&1; then
+          break
+        fi
+        sleep 2
+        waited=$((waited + 2))
+      done
+    fi
+  fi
+  # Final reachability check — if still down, give up gracefully.
+  if ! curl -sfm 2 "http://${vlm_host}:${vlm_port}/health" >/dev/null 2>&1; then
+    echo "no"
+    exit 1
+  fi
+fi
+
+# Gate 2: locate browser-snapshot.sh. Default to the skill's own scripts dir
+# resolved from this file's location.
+SCRIPTS_DIR="${BROWSER_SKILL_SCRIPTS_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+snap_script="${SCRIPTS_DIR}/browser-snapshot.sh"
+if [ ! -x "${snap_script}" ] && [ ! -f "${snap_script}" ]; then
+  echo "no"
+  exit 1
+fi
+
+# Gate 3: snapshot. browser-snapshot.sh emits NDJSON with summary as final
+# line; large snapshots get a snapshot_path reference (Phase 14 #1).
+snap_out="$(bash "${snap_script}" --site "${site}" 2>/dev/null | tail -1)"
+[ -n "${snap_out}" ] || { echo "no"; exit 1; }
+
+snap_text=""
+snap_path="$(printf '%s' "${snap_out}" | jq -r '.snapshot_path // ""' 2>/dev/null)"
+if [ -n "${snap_path}" ] && [ -f "${snap_path}" ]; then
+  snap_text="$(head -c "${snap_cap}" "${snap_path}")"
+fi
+
+# Fallback: no snapshot_path means inline (small page); just use whatever
+# the summary itself carried as observed text. If neither path nor inline
+# data lands, treat as unreachable.
+if [ -z "${snap_text}" ]; then
+  snap_text="$(printf '%s' "${snap_out}" \
+    | jq -r '.url // "", .title // ""' 2>/dev/null \
+    | tr '\n' ' ' \
+    | head -c "${snap_cap}")"
+fi
+
+[ -n "${snap_text}" ] || { echo "no"; exit 1; }
+
+# Gate 4: VLM probe. Yes/no prompt.
+prompt="A user wants to: '${intent}'. The cached element selector was '${selector}'. Here is the current page's accessibility snapshot (first ${snap_cap} bytes):
+
+${snap_text}
+
+Based ONLY on the snapshot, is there still an element on the page that matches the user's intent? Reply with ONLY one word: 'yes' or 'no'."
+
+resp="$(curl -sS -m "${vlm_timeout}" "${endpoint}" \
+  -H 'Content-Type: application/json' \
+  -d "$(jq -nc --arg p "${prompt}" --arg m "${vlm_model}" '
+    {model:$m, max_tokens:5,
+     messages:[{role:"user",content:$p}]}')" 2>/dev/null)" \
+  || { echo "no"; exit 1; }
+
+completion="$(printf '%s' "${resp}" | jq -r '.choices[0].message.content // ""' 2>/dev/null)"
+
+case "${completion,,}" in
+  *yes*) echo "yes"; ;;
+  *)     echo "no"; ;;
+esac
+
+# Phase 14+: touch a tracker file so the idle-stop watchdog (browser-vlm.sh
+# start spawns one) can tell when the VLM was last actually used. Without
+# this, /health pings from doctor + manual status checks would keep the
+# server alive forever.
+BROWSER_SKILL_HOME="${BROWSER_SKILL_HOME:-${HOME}/.browser-skill}"
+mkdir -p "${BROWSER_SKILL_HOME}" 2>/dev/null || true
+: > "${BROWSER_SKILL_HOME}/vlm.last-used" 2>/dev/null || true
+exit 0