@thinkbrowse/cli 0.1.0 → 0.1.2

package/dist/scripts/browse.sh

@@ -0,0 +1,1046 @@
+#!/bin/bash
+# browse — Portable browser automation for AI agent brains
+#
+# Modes:
+#   LOCAL:  Controls your Chrome browser via the native messaging host
+#           Port auto-discovered from ~/.thinkbrowse/port (written by native host on startup)
+#   CLOUD:  Controls a cloud Playwright browser via ThinkBrowse REST API
+#
+# Mode detection (in order):
+#   1. THINKBROWSE_LOCAL=true or THINKBROWSE_NATIVE=true → local mode
+#   2. Native host responding on discovered port → local mode
+#   3. THINKBROWSE_API_KEY or config file → cloud mode
+#
+# Deps: curl, jq
+#
+# Usage:
+#   browse session-create                   Create session, print ID
+#   browse session-artifacts <sid>          List cloud session artifacts
+#   browse artifact-download <id> [out]     Download artifact by ID (cloud mode)
+#   browse goto <sid> <url>                 Navigate to URL
+#   browse click <sid> <selector>           Click element
+#   browse extract <sid> [text|html]        Extract page content
+#   browse session-delete <sid>             Close session
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# --- Config ---
+CONFIG_FILE="$HOME/.config/thinkbrowse/config.json"
+PORT_DISCOVERY_FILE="$HOME/.thinkbrowse/port"
+TAB_DIR="/tmp/thinkbrowse-tabs"
+LOCAL_HOST="${THINKBROWSE_LOCAL_HOST:-127.0.0.1}"
+if [ "$LOCAL_HOST" = "localhost" ]; then
+  echo "WARN: localhost is non-deterministic (IPv4/IPv6); using 127.0.0.1 for ThinkBrowse bridge." >&2
+  LOCAL_HOST="127.0.0.1"
+fi
+
+# Port discovery: THINKBROWSE_LOCAL_PORT > THINKBROWSE_BRIDGE_PORT (legacy) > discovery file > default 3012
+resolve_local_port() {
+  if [ -n "${THINKBROWSE_LOCAL_PORT:-}" ]; then
+    echo "$THINKBROWSE_LOCAL_PORT"
+    return
+  fi
+  if [ -n "${THINKBROWSE_BRIDGE_PORT:-}" ]; then
+    echo "$THINKBROWSE_BRIDGE_PORT"
+    return
+  fi
+  if [ -f "$PORT_DISCOVERY_FILE" ]; then
+    local port
+    port=$(cat "$PORT_DISCOVERY_FILE" 2>/dev/null | tr -d '[:space:]')
+    if [[ "$port" =~ ^[0-9]+$ ]] && [ "$port" -gt 0 ] && [ "$port" -le 65535 ]; then
+      echo "$port"
+      return
+    fi
+  fi
+  echo "3012"
+}
+
+LOCAL_PORT=$(resolve_local_port)
+LOCAL_URL="http://$LOCAL_HOST:$LOCAL_PORT"
+
+is_thinkbrowse_health_response() {
+  local health_json="$1"
+  echo "$health_json" | jq -e '
+    .success == true
+    and (.data | type == "object")
+    and (.data.status == "ok")
+    and (.data.service == "thinkbrowse-native-host")
+    and ((.data.extensionConnected | type) == "boolean")
+  ' >/dev/null 2>&1
+}
+
+probe_local_bridge_health() {
+  local health_json
+  health_json=$(curl -4 -s --max-time 2 "$LOCAL_URL/health" 2>/dev/null || true)
+  if [ -z "$health_json" ]; then
+    return 1
+  fi
+  is_thinkbrowse_health_response "$health_json"
+}
+
+# --- Parse --mode flag before mode detection ---
+MODE_OVERRIDE=""
+ARGS=()
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --mode)
+      MODE_OVERRIDE="${2:-}"
+      shift 2
+      ;;
+    --mode=*)
+      MODE_OVERRIDE="${1#--mode=}"
+      shift
+      ;;
+    *)
+      ARGS+=("$1")
+      shift
+      ;;
+  esac
+done
+# Restore positional parameters without --mode flags
+set -- "${ARGS[@]+"${ARGS[@]}"}"
+
+# --- Mode Detection ---
+MODE=""
+
+if [ -n "$MODE_OVERRIDE" ]; then
+  case "$MODE_OVERRIDE" in
+    native|local) MODE="local" ;;  # native is now an alias for local
+    cloud) MODE="cloud" ;;
+    *)
+      echo "ERROR: Unknown --mode value '$MODE_OVERRIDE' (must be local or cloud)" >&2
+      exit 1
+      ;;
+  esac
+elif [ "${THINKBROWSE_NATIVE:-}" = "true" ] || [ "${THINKBROWSE_LOCAL:-}" = "true" ]; then
+  MODE="local"
+elif probe_local_bridge_health; then
+  MODE="local"
+else
+  # Try cloud mode
+  API_KEY=""
+  if [ -n "${THINKBROWSE_API_KEY:-}" ]; then
+    API_KEY="$THINKBROWSE_API_KEY"
+  elif [ -f "$CONFIG_FILE" ]; then
+    API_KEY=$(jq -r '.apiKey // empty' "$CONFIG_FILE" 2>/dev/null)
+  fi
+
+  if [ -n "${API_KEY:-}" ]; then
+    MODE="cloud"
+  else
+    echo "ERROR: No browser automation endpoint or API key found." >&2
+    echo "  Local mode:   Open Chrome with ThinkBrowse extension + native host installed" >&2
+    echo "  Cloud mode:   Set THINKBROWSE_API_KEY or create $CONFIG_FILE" >&2
+    exit 1
+  fi
+fi
+
+# --- Cloud config ---
+if [ "$MODE" = "cloud" ]; then
+  # Resolve API key for explicit --mode cloud and auto-detected cloud mode.
+  if [ -n "${THINKBROWSE_API_KEY:-}" ]; then
+    API_KEY="$THINKBROWSE_API_KEY"
+  elif [ -f "$CONFIG_FILE" ]; then
+    API_KEY=$(jq -r '.apiKey // empty' "$CONFIG_FILE" 2>/dev/null)
+  else
+    API_KEY=""
+  fi
+  if [ -z "${API_KEY:-}" ]; then
+    echo "ERROR: Cloud mode requires THINKBROWSE_API_KEY or $CONFIG_FILE" >&2
+    exit 1
+  fi
+  # Read apiUrl from config file, fall back to env var or default
+  CONFIG_API_URL=""
+  if [ -f "$CONFIG_FILE" ]; then
+    CONFIG_API_URL=$(jq -r '.apiUrl // empty' "$CONFIG_FILE" 2>/dev/null)
+  fi
+  BASE="${THINKBROWSE_URL:-${CONFIG_API_URL:-https://api.thinkbrowse.io}}"
+  H=(-H "X-API-Key: $API_KEY" -H "Content-Type: application/json")
+fi
+
+# --- Local session sync helpers ---
+LOCAL_SYNC_AUTH_INITIALIZED="false"
+LOCAL_SYNC_API_KEY=""
+LOCAL_SYNC_BASE=""
+
+init_local_sync_auth() {
+  if [ "$LOCAL_SYNC_AUTH_INITIALIZED" = "true" ]; then
+    return
+  fi
+
+  local cfg_api_key=""
+  local cfg_api_url=""
+  if [ -f "$CONFIG_FILE" ]; then
+    cfg_api_key=$(jq -r '.apiKey // empty' "$CONFIG_FILE" 2>/dev/null)
+    cfg_api_url=$(jq -r '.apiUrl // empty' "$CONFIG_FILE" 2>/dev/null)
+  fi
+
+  LOCAL_SYNC_API_KEY="${THINKBROWSE_API_KEY:-$cfg_api_key}"
+  LOCAL_SYNC_BASE="${THINKBROWSE_URL:-${cfg_api_url:-https://api.thinkbrowse.io}}"
+  LOCAL_SYNC_AUTH_INITIALIZED="true"
+}
+
+can_sync_local_session() {
+  local sid="$1"
+  [ "$MODE" = "local" ] || return 1
+  [[ "$sid" == local-* ]] && return 1
+  init_local_sync_auth
+  [ -n "${LOCAL_SYNC_API_KEY:-}" ]
+}
+
+sync_local_action_event() {
+  local sid="$1"
+  local action_type="$2"
+  local success="$3"
+  local details_json="${4:-{}}"
+  local error_msg="${5:-}"
+  local artifact_b64="${6:-}"
+
+  can_sync_local_session "$sid" || return 0
+
+  local payload
+  payload=$(jq -cn \
+    --arg type "$action_type" \
+    --arg success "$success" \
+    --arg details_raw "$details_json" \
+    --arg error "$error_msg" \
+    --arg artifact "$artifact_b64" \
+    '{
+      type: $type,
+      success: ($success == "true"),
+      details: ($details_raw | fromjson? // {})
+    }
+    + (if ($error|length) > 0 then { error: $error } else {} end)
+    + (if ($artifact|length) > 0 then { artifactBase64: $artifact, artifactMimeType: "image/png" } else {} end)
+    ')
+
+  curl -s \
+    -H "X-API-Key: $LOCAL_SYNC_API_KEY" \
+    -H "Content-Type: application/json" \
+    -X POST "$LOCAL_SYNC_BASE/api/sessions/$sid/local-sync/action" \
+    -d "$payload" >/dev/null 2>&1 || true
+}
+
+maybe_sync_local_command() {
+  local sid="$1"
+  local http_code="$2"
+  local body="$3"
+  shift 3
+
+  can_sync_local_session "$sid" || return 0
+
+  local method="POST"
+  local req_data=""
+  local req_url=""
+  local prev=""
+  for arg in "$@"; do
+    if [ "$prev" = "-X" ]; then
+      method="$arg"
+      prev=""
+      continue
+    fi
+    if [ "$prev" = "-d" ]; then
+      req_data="$arg"
+      prev=""
+      continue
+    fi
+    case "$arg" in
+      -X|-d)
+        prev="$arg"
+        ;;
+      http://*|https://*)
+        req_url="$arg"
+        ;;
+    esac
+  done
+
+  [ -n "$req_url" ] || return 0
+  [ "$method" = "POST" ] || return 0
+
+  local endpoint="${req_url##*/api/}"
+  local action_type=""
+  case "$endpoint" in
+    navigate) action_type="navigate" ;;
+    click) action_type="click" ;;
+    fill) action_type="fill" ;;
+    type) action_type="type" ;;
+    press) action_type="press" ;;
+    hover) action_type="hover" ;;
+    select) action_type="select" ;;
+    wait) action_type="wait" ;;
+    wait-for-text) action_type="wait" ;;
+    evaluate) action_type="evaluate" ;;
+    extract) action_type="extract" ;;
+    snapshot) action_type="snapshot" ;;
+    screenshot) action_type="screenshot" ;;
+    scroll) action_type="scroll" ;;
+    go-back) action_type="go-back" ;;
+    go-forward) action_type="go-forward" ;;
+    *) return 0 ;;
+  esac
+
+  local details_json="{}"
+  if [ -n "$req_data" ]; then
+    details_json=$(printf '%s' "$req_data" | jq -c '.' 2>/dev/null || echo '{}')
+  fi
+  details_json=$(jq -cn --arg endpoint "$endpoint" --arg details_raw "$details_json" '{ endpoint: $endpoint } + ($details_raw | fromjson? // {})')
+
+  local success_bool error_msg artifact_b64
+  success_bool=$(echo "$body" | jq -r 'if (.success == false) then "false" else "true" end' 2>/dev/null || echo "true")
+  error_msg=$(echo "$body" | jq -r '.error // .message // empty' 2>/dev/null || echo "")
+  artifact_b64=""
+  if [ "$action_type" = "screenshot" ]; then
+    artifact_b64=$(echo "$body" | jq -r '.data.screenshot // .screenshot // empty' 2>/dev/null || echo "")
+  fi
+
+  sync_local_action_event "$sid" "$action_type" "$success_bool" "$details_json" "$error_msg" "$artifact_b64"
+}
+
+# --- Local helpers ---
+
+# Check native host is reachable
+ensure_local() {
+  local health_json
+  health_json=$(curl -4 -s --max-time 2 "$LOCAL_URL/health" 2>/dev/null || true)
+
+  if [ -z "$health_json" ]; then
+    echo "ERROR: Native host not responding on $LOCAL_URL" >&2
+    echo "  Make sure Chrome is open with the ThinkBrowse extension installed." >&2
+    exit 1
+  fi
+
+  if ! is_thinkbrowse_health_response "$health_json"; then
+    echo "ERROR: Service on $LOCAL_URL is not the ThinkBrowse native host." >&2
+    echo "  Received /health payload: $health_json" >&2
+    echo "  This usually means another local service is using port $LOCAL_PORT" >&2
+    echo "  or localhost/IPv6 resolved to a different process." >&2
+    if command -v lsof >/dev/null 2>&1; then
+      echo "  Listening processes on :$LOCAL_PORT:" >&2
+      lsof -nP -iTCP:"$LOCAL_PORT" -sTCP:LISTEN >&2 || true
+    fi
+    echo "  Fix: keep ThinkBrowse on $LOCAL_HOST:$LOCAL_PORT, move conflicting services," >&2
+    echo "  or override host/port with THINKBROWSE_LOCAL_HOST / THINKBROWSE_LOCAL_PORT." >&2
+    exit 1
+  fi
+}
+
+# Save tab ID for a local session
+save_tab_id() {
+  local sid="$1" tab_id="$2"
+  mkdir -p "$TAB_DIR"
+  echo "$tab_id" > "$TAB_DIR/$sid"
+}
+
+# Load tab ID for a local session
+load_tab_id() {
+  local sid="$1"
+  local tab_file="$TAB_DIR/$sid"
+  if [ ! -f "$tab_file" ]; then
+    echo "ERROR: No tab found for session $sid" >&2
+    exit 1
+  fi
+  cat "$tab_file"
+}
+
+# Remove tab ID file for a local session
+remove_tab_id() {
+  local sid="$1"
+  rm -f "$TAB_DIR/$sid"
+}
+
+# curl wrapper for local/native HTTP endpoints with tab pinning + retry
+local_curl() {
+  local sid="$1"; shift
+  local tab_id
+  tab_id=$(load_tab_id "$sid")
+  local max_retries=3
+  local delay=1
+  for attempt in $(seq 1 $max_retries); do
+    RESP=$(curl -s -w "\n%{http_code}" -H "Content-Type: application/json" -H "X-Tab-Id: $tab_id" "$@")
+    HTTP_CODE=$(echo "$RESP" | tail -1)
+    BODY=$(echo "$RESP" | sed '$d')
+
+    # Check for TAB_NOT_FOUND — don't retry, clean up session
+    CODE=$(echo "$BODY" | jq -r '.code // empty' 2>/dev/null)
+    if [ "$CODE" = "TAB_NOT_FOUND" ]; then
+      echo "ERROR: Session tab was closed" >&2
+      remove_tab_id "$sid"
+      exit 1
+    fi
+
+    # Check for retryable conditions (structured field or HTTP status)
+    RETRYABLE=$(echo "$BODY" | jq -r '.retryable // false' 2>/dev/null)
+    case "$HTTP_CODE" in
+      503|504) RETRYABLE=true ;;
+    esac
+    if [ "$RETRYABLE" = "true" ] && [ "$attempt" -lt "$max_retries" ]; then
+      sleep $delay
+      delay=$((delay * 2))
+      continue
+    fi
+    maybe_sync_local_command "$sid" "$HTTP_CODE" "$BODY" "$@"
+    echo "$BODY"
+    return 0
+  done
+  maybe_sync_local_command "$sid" "$HTTP_CODE" "$BODY" "$@"
+  echo "$BODY"
+}
+
+# --- Cloud helpers ---
+
+# Retry helper for transient errors (Fly routing, timeouts, 502/503/504/524)
+retry_curl() {
+  local max_retries=4
+  local delay=1
+  for attempt in $(seq 1 $max_retries); do
+    RESP=$(curl -s -w "\n%{http_code}" "${H[@]}" "$@")
+    HTTP_CODE=$(echo "$RESP" | tail -1)
+    BODY=$(echo "$RESP" | sed '$d')
+
+    # Check for retryable conditions
+    SHOULD_RETRY=false
+
+    # Structured retryable field from bridge/cloud API
+    RETRYABLE=$(echo "$BODY" | jq -r '.retryable // false' 2>/dev/null)
+    if [ "$RETRYABLE" = "true" ]; then
+      SHOULD_RETRY=true
+    fi
+
+    # HTTP status codes that indicate transient failures
+    case "$HTTP_CODE" in
+      502|503|504|524) SHOULD_RETRY=true ;;
+    esac
+
+    # Legacy error string matching
+    ERROR=$(echo "$BODY" | jq -r '.error // empty' 2>/dev/null)
+    case "$ERROR" in
+      "Session not found"|"Session is still provisioning. Please wait for it to become active.")
+        SHOULD_RETRY=true ;;
+    esac
+
+    if [ "$SHOULD_RETRY" = "true" ] && [ "$attempt" -lt "$max_retries" ]; then
+      sleep $delay
+      delay=$((delay * 2))
+      continue
+    fi
+
+    echo "$BODY"
+    return 0
+  done
+  echo "$BODY"
+}
+
+# Validate local bridge identity once before command dispatch.
+if [ "$MODE" = "local" ]; then
+  ensure_local
+fi
+
+# --- Commands ---
+case "${1:-help}" in
+
+  # ========== Session Management ==========
+
+  session-create)
+    if [ "$MODE" = "local" ]; then
+      ensure_local
+      # Create a new tab via native host
+      RESP=$(curl -s -H "Content-Type: application/json" -X POST "$LOCAL_URL/api/tabs/new" \
+        -d '{"url":"about:blank"}')
+      SUCCESS=$(echo "$RESP" | jq -r '.success // false')
+      if [ "$SUCCESS" != "true" ]; then
+        echo "ERROR: Failed to create tab (mode: $MODE)" >&2
+        echo "$RESP" >&2
+        exit 1
+      fi
+      # Extract tab ID from response
+      TAB_ID=$(echo "$RESP" | jq -r '.data.tabId // .data.id // empty')
+      if [ -z "$TAB_ID" ]; then
+        echo "ERROR: No tab ID in response (mode: $MODE)" >&2
+        echo "$RESP" >&2
+        exit 1
+      fi
+      # Prefer backend-issued session IDs for local execution when API auth is available.
+      LOCAL_API_KEY=""
+      LOCAL_API_URL=""
+      if [ -n "${THINKBROWSE_API_KEY:-}" ]; then
+        LOCAL_API_KEY="$THINKBROWSE_API_KEY"
+      elif [ -f "$CONFIG_FILE" ]; then
+        LOCAL_API_KEY=$(jq -r '.apiKey // empty' "$CONFIG_FILE" 2>/dev/null)
+      fi
+      if [ -f "$CONFIG_FILE" ]; then
+        LOCAL_API_URL=$(jq -r '.apiUrl // empty' "$CONFIG_FILE" 2>/dev/null)
+      fi
+      LOCAL_BASE="${THINKBROWSE_URL:-${LOCAL_API_URL:-https://api.thinkbrowse.io}}"
+
+      SID=""
+      if [ -n "$LOCAL_API_KEY" ]; then
+        BACKEND_RESP=$(curl -s -H "X-API-Key: $LOCAL_API_KEY" -H "Content-Type: application/json" \
+          -X POST "$LOCAL_BASE/api/sessions/local" -d '{}')
+        SID=$(echo "$BACKEND_RESP" | jq -r '.data.sessionId // .sessionId // empty')
+      fi
+      if [ -z "$SID" ]; then
+        SID="local-$TAB_ID"
+      fi
+      save_tab_id "$SID" "$TAB_ID"
+      echo "$SID"
+    else
+      RESP=$(curl -s "${H[@]}" -X POST "$BASE/api/sessions" -d '{}')
+      SID=$(echo "$RESP" | jq -r '.data.sessionId // .sessionId // empty')
+      if [ -z "$SID" ]; then
+        echo "ERROR: Session creation failed" >&2
+        echo "$RESP" >&2
+        exit 1
+      fi
+      # Poll until ready (max 120s for cold machine start)
+      for i in $(seq 1 40); do
+        STATUS=$(curl -s "${H[@]}" "$BASE/api/sessions/$SID" | jq -r '.data.status // .status // "unknown"')
+        case "$STATUS" in
+          ready|active|running)
+            echo "$SID"
+            exit 0
+            ;;
+          creating|provisioning|pending)
+            printf "." >&2
+            sleep 3
+            ;;
+          failed|error|terminated)
+            echo "" >&2
+            echo "ERROR: Session $SID failed with status: $STATUS" >&2
+            exit 1
+            ;;
+        esac
+      done
+      echo "" >&2
+      echo "ERROR: Session $SID not ready after 120s" >&2
+      exit 1
+    fi
+    ;;
+
+  session-status)
+    if [ "$MODE" = "local" ]; then
+      ensure_local
+      TAB_ID=$(load_tab_id "$2")
+      curl -s -H "Content-Type: application/json" -H "X-Tab-Id: $TAB_ID" "$LOCAL_URL/sessions/$TAB_ID"
+    else
+      curl -s "${H[@]}" "$BASE/api/sessions/$2"
+    fi
+    ;;
+
+  session-delete)
+    if [ "$MODE" = "local" ]; then
+      TAB_ID=$(load_tab_id "$2")
+      curl -s -H "Content-Type: application/json" -X POST "$LOCAL_URL/api/tabs/close" \
+        -d "{\"tabId\":$TAB_ID}"
+      remove_tab_id "$2"
+    else
+      curl -s "${H[@]}" -X DELETE "$BASE/api/sessions/$2"
+    fi
+    ;;
+
+  session-details)
+    if [ "$MODE" = "local" ]; then
+      if can_sync_local_session "$2"; then
+        BACKEND_DETAILS=$(curl -s -H "X-API-Key: $LOCAL_SYNC_API_KEY" -H "Content-Type: application/json" \
+          -X GET "$LOCAL_SYNC_BASE/api/sessions/$2/details" 2>/dev/null || true)
+        if [ -n "$BACKEND_DETAILS" ] && [ "$(echo "$BACKEND_DETAILS" | jq -r '.success // false' 2>/dev/null)" = "true" ]; then
+          echo "$BACKEND_DETAILS"
+          exit 0
+        fi
+      fi
+      TAB_ID=$(load_tab_id "$2")
+      SESSION_JSON=$(curl -s -H "Content-Type: application/json" -H "X-Tab-Id: $TAB_ID" "$LOCAL_URL/sessions/$TAB_ID")
+      URL_VAL=$(echo "$SESSION_JSON" | jq -r '.data.url // ""')
+      TITLE_VAL=$(echo "$SESSION_JSON" | jq -r '.data.title // ""')
+      jq -n \
+        --arg sid "$2" \
+        --arg tabId "$TAB_ID" \
+        --arg url "$URL_VAL" \
+        --arg title "$TITLE_VAL" \
+        '{
+          success: true,
+          session: {
+            sessionId: $sid,
+            executionMode: "local",
+            executor: "native-host",
+            status: "active",
+            tabId: ($tabId|tonumber),
+            currentUrl: $url,
+            title: $title,
+            artifacts: [],
+            actions: [],
+            storageBacked: false
+          }
+        }'
+    else
+      retry_curl -X GET "$BASE/api/sessions/$2/details"
+    fi
+    ;;
+
+  session-actions)
+    if [ "$MODE" = "local" ]; then
+      if can_sync_local_session "$2"; then
+        LIMIT="${3:-50}"
+        OFFSET="${4:-0}"
+        TYPE="${5:-}"
+        ACTIONS_URL="$LOCAL_SYNC_BASE/api/sessions/$2/actions?limit=$LIMIT&offset=$OFFSET"
+        if [ -n "$TYPE" ]; then
+          ACTIONS_URL="${ACTIONS_URL}&type=$TYPE"
+        fi
+        BACKEND_ACTIONS=$(curl -s -H "X-API-Key: $LOCAL_SYNC_API_KEY" -H "Content-Type: application/json" \
+          -X GET "$ACTIONS_URL" 2>/dev/null || true)
+        if [ -n "$BACKEND_ACTIONS" ] && [ "$(echo "$BACKEND_ACTIONS" | jq -r '.success // false' 2>/dev/null)" = "true" ]; then
+          echo "$BACKEND_ACTIONS"
+          exit 0
+        fi
+      fi
+      TAB_ID=$(load_tab_id "$2")
+      CONSOLE_JSON=$(local_curl "$2" -X POST "$LOCAL_URL/api/console")
+      NETWORK_JSON=$(local_curl "$2" -X POST "$LOCAL_URL/api/network")
+      LIMIT="${3:-50}"
+      OFFSET="${4:-0}"
+      jq -n \
+        --arg sid "$2" \
+        --argjson limit "$LIMIT" \
+        --argjson offset "$OFFSET" \
+        --argjson console "$CONSOLE_JSON" \
+        --argjson network "$NETWORK_JSON" \
+        '{
+          success: true,
+          data: {
+            sessionId: $sid,
+            executionMode: "local",
+            actions: [],
+            console: ($console.data // []),
+            network: ($network.data // []),
+            total: 0,
+            successful: 0,
+            failed: 0,
+            hasMore: false,
+            note: "Local mode currently exposes console and network logs; action history persistence is cloud-only."
+          }
+        }'
+    else
+      LIMIT="${3:-50}"
+      OFFSET="${4:-0}"
+      TYPE="${5:-}"
+      ACTIONS_URL="$BASE/api/sessions/$2/actions?limit=$LIMIT&offset=$OFFSET"
+      if [ -n "$TYPE" ]; then
+        ACTIONS_URL="${ACTIONS_URL}&type=$TYPE"
+      fi
+      retry_curl -X GET "$ACTIONS_URL"
+    fi
+    ;;
+
+  session-artifacts)
+    if [ "$MODE" = "local" ]; then
+      if can_sync_local_session "$2"; then
+        BACKEND_ARTIFACTS=$(curl -s -H "X-API-Key: $LOCAL_SYNC_API_KEY" -H "Content-Type: application/json" \
+          -X GET "$LOCAL_SYNC_BASE/api/sessions/$2/artifacts" 2>/dev/null || true)
+        if [ -n "$BACKEND_ARTIFACTS" ] && [ "$(echo "$BACKEND_ARTIFACTS" | jq -r '.success // false' 2>/dev/null)" = "true" ]; then
+          echo "$BACKEND_ARTIFACTS"
+          exit 0
+        fi
+      fi
+      jq -n --arg sid "$2" '{
+        success: true,
+        sessionId: $sid,
+        executionMode: "local",
+        artifacts: [],
+        note: "Local mode does not persist artifacts to cloud storage. Use --mode cloud for reusable stored artifacts."
+      }'
+    else
+      retry_curl -X GET "$BASE/api/sessions/$2/artifacts"
+    fi
+    ;;
+
+  artifact-download)
+    if [ "$MODE" = "local" ]; then
+      echo "ERROR: artifact-download is available in cloud mode only (use --mode cloud)" >&2
+      exit 1
+    fi
+    ARTIFACT_ID="$2"
+    OUTFILE="${3:-artifact-$ARTIFACT_ID.bin}"
+    if ! curl -fsSL -H "X-API-Key: $API_KEY" "$BASE/api/storage/artifacts/$ARTIFACT_ID/download" -o "$OUTFILE"; then
+      echo "ERROR: Failed to download artifact $ARTIFACT_ID" >&2
+      exit 1
+    fi
+    echo "$OUTFILE"
+    ;;
+
+  # ========== Navigation ==========
+
+  goto)
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/navigate" \
+        -d "{\"url\":$(printf '%s' "$3" | jq -Rs)}"
+    else
+      retry_curl -X POST "$BASE/api/sessions/$2/navigate" \
+        -d "{\"url\":$(printf '%s' "$3" | jq -Rs)}"
+    fi
+    ;;
+
+  scroll)
+    DIR="${3:-down}"
+    AMT="${4:-500}"
+    if ! [[ "$AMT" =~ ^[0-9]+$ ]]; then
+      echo "ERROR: Amount must be a positive integer" >&2
+      exit 1
+    fi
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/scroll" \
+        -d "{\"direction\":\"$DIR\",\"amount\":$AMT}"
+    else
+      if [ "$DIR" = "up" ]; then
+        retry_curl -X POST "$BASE/api/sessions/$2/evaluate" \
+          -d "{\"script\":\"window.scrollBy(0, -$AMT)\"}"
+      else
+        retry_curl -X POST "$BASE/api/sessions/$2/evaluate" \
+          -d "{\"script\":\"window.scrollBy(0, $AMT)\"}"
+      fi
+    fi
+    ;;
+
+  # ========== Observation ==========
+
+  snapshot)
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/snapshot" \
+        | jq -r '.data // .error // "No snapshot available"'
+    else
+      retry_curl -X POST "$BASE/api/sessions/$2/snapshot" \
+        | jq -r '.snapshot // .error // "No snapshot available"'
+    fi
+    ;;
+
+  screenshot)
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/screenshot"
+    else
+      retry_curl -X POST "$BASE/api/sessions/$2/screenshot"
+    fi
+    ;;
+
+  extract)
+    TYPE="${3:-text}"
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/extract" \
+        -d "{\"type\":$(printf '%s' "$TYPE" | jq -Rs)}"
+    else
+      retry_curl -X POST "$BASE/api/sessions/$2/extract" \
+        -d "{\"type\":$(printf '%s' "$TYPE" | jq -Rs)}"
+    fi
+    ;;
+
+  # ========== Interaction ==========
+
+  click)
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/click" \
+        -d "{\"selector\":$(printf '%s' "$3" | jq -Rs)}"
+    else
+      retry_curl -X POST "$BASE/api/sessions/$2/click" \
+        -d "{\"selector\":$(printf '%s' "$3" | jq -Rs)}"
+    fi
+    ;;
+
+  fill)
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/fill" \
+        -d "{\"selector\":$(printf '%s' "$3" | jq -Rs),\"value\":$(printf '%s' "$4" | jq -Rs)}"
+    else
+      retry_curl -X POST "$BASE/api/sessions/$2/fill" \
+        -d "{\"selector\":$(printf '%s' "$3" | jq -Rs),\"value\":$(printf '%s' "$4" | jq -Rs)}"
+    fi
+    ;;
+
+  type)
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/type" \
+        -d "{\"selector\":$(printf '%s' "$3" | jq -Rs),\"text\":$(printf '%s' "$4" | jq -Rs)}"
+    else
+      retry_curl -X POST "$BASE/api/sessions/$2/type" \
+        -d "{\"selector\":$(printf '%s' "$3" | jq -Rs),\"text\":$(printf '%s' "$4" | jq -Rs)}"
+    fi
+    ;;
+
+  press)
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/press" \
+        -d "{\"key\":$(printf '%s' "$3" | jq -Rs)}"
+    else
+      retry_curl -X POST "$BASE/api/sessions/$2/press" \
+        -d "{\"key\":$(printf '%s' "$3" | jq -Rs)}"
+    fi
+    ;;
+
+  hover)
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/hover" \
+        -d "{\"selector\":$(printf '%s' "$3" | jq -Rs)}"
+    else
+      retry_curl -X POST "$BASE/api/sessions/$2/hover" \
+        -d "{\"selector\":$(printf '%s' "$3" | jq -Rs)}"
+    fi
+    ;;
+
+  select)
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/select" \
+        -d "{\"selector\":$(printf '%s' "$3" | jq -Rs),\"value\":$(printf '%s' "$4" | jq -Rs)}"
+    else
+      retry_curl -X POST "$BASE/api/sessions/$2/select" \
+        -d "{\"selector\":$(printf '%s' "$3" | jq -Rs),\"value\":$(printf '%s' "$4" | jq -Rs)}"
+    fi
+    ;;
+
+  wait)
+    TIMEOUT="${4:-10000}"
+    if ! [[ "$TIMEOUT" =~ ^[0-9]+$ ]]; then
+      echo "ERROR: Timeout must be a positive integer (ms)" >&2
+      exit 1
+    fi
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/wait" \
+        -d "{\"selector\":$(printf '%s' "$3" | jq -Rs),\"timeout\":$TIMEOUT}"
+    else
+      retry_curl -X POST "$BASE/api/sessions/$2/wait" \
+        -d "{\"selector\":$(printf '%s' "$3" | jq -Rs),\"timeout\":$TIMEOUT}"
+    fi
+    ;;
+
+  evaluate)
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/evaluate" \
+        -d "{\"script\":$(printf '%s' "$3" | jq -Rs)}"
+    else
+      retry_curl -X POST "$BASE/api/sessions/$2/evaluate" \
+        -d "{\"script\":$(printf '%s' "$3" | jq -Rs)}"
+    fi
+    ;;
+
+  # ========== Navigation History ==========
+
+  back)
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/go-back"
+    else
+      retry_curl -X POST "$BASE/api/sessions/$2/go-back"
+    fi
+    ;;
+
+  forward)
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/go-forward"
+    else
+      retry_curl -X POST "$BASE/api/sessions/$2/go-forward"
+    fi
+    ;;
+
+  # ========== Dialog Handling ==========
+
+  dialog)
+    local dialog_action="${3:-status}"
+    case "$dialog_action" in
+      status)
+        if [ "$MODE" = "local" ]; then
+          local_curl "$2" -X POST "$LOCAL_URL/api/dialog"
+        else
+          retry_curl -X GET "$BASE/api/sessions/$2/dialog"
+        fi
+        ;;
+      accept)
+        if [ "$MODE" = "local" ]; then
+          echo '{"info":"Dialogs are auto-handled in local mode"}'
+          local_curl "$2" -X POST "$LOCAL_URL/api/dialog"
+        else
+          retry_curl -X POST "$BASE/api/sessions/$2/dialog" \
+            -d "{\"accept\":true$([ -n "${4:-}" ] && echo ",\"promptText\":$(printf '%s' "$4" | jq -Rs)" || echo "")}"
+        fi
+        ;;
+      dismiss)
+        if [ "$MODE" = "local" ]; then
+          echo '{"info":"Dialogs are auto-handled in local mode"}'
+          local_curl "$2" -X POST "$LOCAL_URL/api/dialog"
+        else
+          retry_curl -X POST "$BASE/api/sessions/$2/dialog" \
+            -d '{"accept":false}'
+        fi
+        ;;
+      *)
+        echo "ERROR: Unknown dialog action: $dialog_action (use status, accept, dismiss)" >&2
+        exit 1
+        ;;
+    esac
+    ;;
+
+  # ========== Wait for Text ==========
+
+  wait-for-text)
+    local text_val="$3"
+    local wft_timeout="${4:-30000}"
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/wait-for-text" \
+        -d "{\"text\":$(printf '%s' "$text_val" | jq -Rs),\"timeout\":$wft_timeout}"
+    else
+      retry_curl -X POST "$BASE/api/sessions/$2/wait-for-text" \
+        -d "{\"text\":$(printf '%s' "$text_val" | jq -Rs),\"timeout\":$wft_timeout}"
+    fi
+    ;;
+
+  # ========== Observability ==========
+
+  console)
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/console"
+    else
+      retry_curl -X GET "$BASE/api/sessions/$2/console"
+    fi
+    ;;
+
+  network)
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/network"
+    else
+      retry_curl -X GET "$BASE/api/sessions/$2/network"
+    fi
+    ;;
+
+  url)
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/url"
+    else
+      # Cloud: extract URL from snapshot
+      retry_curl -X POST "$BASE/api/sessions/$2/evaluate" \
+        -d '{"script":"window.location.href"}'
+    fi
+    ;;
+
+  title)
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/title"
+    else
+      # Cloud: extract title from evaluate
+      retry_curl -X POST "$BASE/api/sessions/$2/evaluate" \
+        -d '{"script":"document.title"}'
+    fi
+    ;;
+
+  html)
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/html"
+    else
+      retry_curl -X POST "$BASE/api/sessions/$2/extract" \
+        -d '{"type":"html"}'
+    fi
+    ;;
+
+  clear-logs)
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/clear-logs"
+    else
+      echo "ERROR: clear-logs only available in local mode" >&2
+      exit 1
+    fi
+    ;;
+
+  # ========== Tab Management (local only) ==========
+
+  tabs)
+    if [ "$MODE" = "local" ]; then
+      curl -s -H "Content-Type: application/json" "$LOCAL_URL/api/tabs"
+    else
+      echo "ERROR: Tab management only available in local mode" >&2
+      exit 1
+    fi
+    ;;
+
+  switch-tab)
+    if [ "$MODE" = "local" ]; then
+      local_curl "$2" -X POST "$LOCAL_URL/api/tabs/switch" \
+        -d "{\"tabId\":$3}"
+    else
+      echo "ERROR: Tab management only available in local mode" >&2
+      exit 1
+    fi
+    ;;
+
+  # ========== Help ==========
+
+  help|*)
+    echo "browse — Portable browser automation for AI agents"
+    echo ""
+    echo "Mode: ${MODE:-not detected} (local=native host $LOCAL_HOST:$LOCAL_PORT, cloud=Playwright)"
+    echo ""
+    echo "Session Management:"
+    echo "  session-create                        Create session, print ID"
+    echo "  session-status <sid>                  Get session details"
+    echo "  session-delete <sid>                  Close session"
+    echo "  session-details <sid>                 Get session details (cloud/local)"
+    echo "  session-actions <sid> [limit] [off]   Get session actions/logs (cloud/local)"
+    echo "  session-artifacts <sid>               List session artifacts (cloud/local)"
+    echo "  artifact-download <id> [out]          Download cloud artifact by ID"
+    echo ""
+    echo "Navigation:"
+    echo "  goto <sid> <url>                      Navigate to URL"
+    echo "  back <sid>                            Go back in browser history"
+    echo "  forward <sid>                         Go forward in browser history"
+    echo "  scroll <sid> [up|down] [pixels]       Scroll page (default: down 500)"
+    echo ""
+    echo "Observation:"
+    echo "  snapshot <sid>                        Get DOM tree / accessibility snapshot"
+    echo "  screenshot <sid>                      Take screenshot"
+    echo "  extract <sid> [text|html]             Extract page content"
+    echo "  console <sid>                         Get browser console logs"
+    echo "  network <sid>                         Get network requests"
+    echo "  url <sid>                             Get current page URL"
+    echo "  title <sid>                           Get current page title"
+    echo "  html <sid>                            Get full page HTML"
+    echo ""
+    echo "Interaction:"
+    echo "  click <sid> <selector>                Click element"
+    echo "  fill <sid> <selector> <value>         Fill form field (clears first)"
+    echo "  type <sid> <selector> <text>          Type text (appends)"
+    echo "  press <sid> <key>                     Press key (Enter, Tab, Escape)"
+    echo "  hover <sid> <selector>                Hover over element"
+    echo "  select <sid> <selector> <value>       Select dropdown option"
+    echo "  wait <sid> <selector> [timeout_ms]    Wait for element (default 10000ms)"
+    echo "  wait-for-text <sid> <text> [timeout]  Wait for text to appear (default 30000ms)"
+    echo "  dialog <sid> [status|accept|dismiss]  Handle browser dialog (alert/confirm/prompt)"
+    echo "  evaluate <sid> <javascript>           Run JavaScript on page"
+    echo ""
+    echo "Local Only:"
+    echo "  clear-logs <sid>                      Clear console/network logs"
+    echo "  tabs                                  List all open tabs"
+    echo "  switch-tab <sid> <tabId>              Switch to specific tab"
+    echo ""
+    echo "Tab Listing Examples:"
+    echo "  browse tabs | jq -r '.data.tabs[] | \"\\(.id)\\t\\(.active)\\t\\(.url)\"'"
+    echo "  browse tabs | jq -r '.data.tabs[] | \"\\(.id)\\t\\(.active)\\t\\(.title)\\t\\(.url)\"'"
+    echo ""
+    echo "Flags:"
+    echo "  --mode local|cloud                    Override mode detection"
+    echo ""
+    echo "Port Discovery:"
+    echo "  The native host writes its port to ~/.thinkbrowse/port on startup."
+    echo "  This script reads it automatically. Override: THINKBROWSE_LOCAL_PORT env var."
+    echo ""
+    echo "Environment:"
+    echo "  THINKBROWSE_LOCAL=true                Force local mode"
+    echo "  THINKBROWSE_LOCAL_PORT=<port>         Override native host port"
+    echo "  THINKBROWSE_BRIDGE_PORT=<port>        Legacy override alias (deprecated)"
+    echo "  THINKBROWSE_API_KEY=...               Cloud API key"
+    echo "  THINKBROWSE_URL=...                   Cloud API base URL"
+    echo "  ~/.config/thinkbrowse/config.json     Cloud config file"
+    echo ""
+    echo "Mode detection order:"
+    echo "  1. --mode flag or THINKBROWSE_LOCAL=true"
+    echo "  2. Native host health check ($LOCAL_HOST:$LOCAL_PORT)"
+    echo "  3. THINKBROWSE_API_KEY or config file → cloud"
+    echo ""
+    echo "Docs:"
+    echo "  https://thinkbrowse.io/docs"
+    echo "  https://thinkbrowse.io/llms.txt"
+    ;;
+esac