chore: import upstream snapshot with attribution

.claude-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "agent-browser",
+  "description": "Browser automation for AI agents",
+  "owner": {
+    "name": "Vercel",
+    "email": "support@vercel.com"
+  },
+  "plugins": [
+    {
+      "name": "agent-browser",
+      "description": "Automates browser interactions for web testing, form filling, screenshots, and data extraction",
+      "source": "./",
+      "strict": false,
+      "skills": ["./skills/agent-browser"],
+      "category": "development"
+    }
+  ]
+}

.github/workflows/ci.yml

@@ -0,0 +1,294 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  version-sync:
+    name: Version Sync Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .node-version
+
+      - name: Check version sync
+        run: node scripts/check-version-sync.js
+
+  rust:
+    name: Rust
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+
+      - name: Cache Rust build artifacts
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: cli
+
+      - name: Format check
+        run: cargo fmt --manifest-path cli/Cargo.toml -- --check
+
+      - name: Clippy check
+        run: cargo clippy --manifest-path cli/Cargo.toml -- -D warnings
+
+      - name: Run Rust tests
+        run: cargo test --profile ci --manifest-path cli/Cargo.toml
+
+  dashboard:
+    name: Dashboard
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .node-version
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Install dependencies
+        run: pnpm install --filter dashboard
+        working-directory: packages/dashboard
+
+      - name: Build dashboard
+        run: pnpm build
+        working-directory: packages/dashboard
+
+  sandbox-package:
+    name: Sandbox Package
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .node-version
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Test sandbox package
+        run: pnpm --filter @agent-browser/sandbox test
+
+  rust-cross:
+    name: Rust (${{ matrix.os }} - ${{ matrix.target }})
+    if: github.event_name != 'pull_request'
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        include:
+          - os: macos-latest
+            target: aarch64-apple-darwin
+          - os: macos-latest
+            target: x86_64-apple-darwin
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - name: Cache Rust build artifacts
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: cli
+
+      - name: Run Rust tests
+        run: cargo test --profile ci --manifest-path cli/Cargo.toml --target ${{ matrix.target }}
+
+  native-e2e:
+    name: Native E2E Tests
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    needs: rust
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Rust build artifacts
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: cli
+
+      - name: Install Chrome
+        run: |
+          cargo run --manifest-path cli/Cargo.toml -- install --with-deps
+
+      - name: Install ffmpeg
+        run: sudo apt-get update && sudo apt-get install -y ffmpeg
+
+      - name: Run e2e tests
+        run: cargo test --profile ci --manifest-path cli/Cargo.toml e2e -- --ignored --test-threads=1
+
+  windows-integration:
+    name: Windows Integration Test
+    if: github.event_name != 'pull_request'
+    runs-on: windows-latest
+    needs: rust-cross
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: x86_64-pc-windows-msvc
+
+      - name: Cache Rust build artifacts
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: cli
+
+      - name: Build Rust CLI
+        run: cargo build --release --manifest-path cli/Cargo.toml --target x86_64-pc-windows-msvc
+
+      - name: Copy CLI binary to bin directory
+        run: |
+          Copy-Item cli/target/x86_64-pc-windows-msvc/release/agent-browser.exe bin/agent-browser-win32-x64.exe
+
+      - name: Test agent-browser install command
+        run: |
+          $env:PATH = "$pwd\bin;$env:PATH"
+          for ($i = 1; $i -le 3; $i++) {
+            bin/agent-browser-win32-x64.exe install
+            if ($LASTEXITCODE -eq 0) { exit 0 }
+            Write-Host "Attempt $i failed, retrying in 10 seconds..."
+            Start-Sleep -Seconds 10
+          }
+          exit 1
+        shell: pwsh
+        timeout-minutes: 10
+
+      - name: Test daemon lifecycle (open, snapshot, close)
+        run: |
+          $env:PATH = "$pwd\bin;$env:PATH"
+          Write-Host "--- Opening page ---"
+          bin/agent-browser-win32-x64.exe open https://example.com
+          if ($LASTEXITCODE -ne 0) { Write-Error "open failed"; exit 1 }
+          Write-Host "--- Taking snapshot ---"
+          $snapshot = bin/agent-browser-win32-x64.exe snapshot
+          if ($LASTEXITCODE -ne 0) { Write-Error "snapshot failed"; exit 1 }
+          Write-Host $snapshot
+          Write-Host "--- Closing browser ---"
+          bin/agent-browser-win32-x64.exe close
+          if ($LASTEXITCODE -ne 0) { Write-Error "close failed"; exit 1 }
+          Write-Host "--- Windows daemon lifecycle test passed ---"
+        shell: pwsh
+        timeout-minutes: 5
+
+  global-install:
+    name: Global Install (${{ matrix.os }})
+    if: github.event_name != 'pull_request'
+    runs-on: ${{ matrix.os }}
+    needs: rust-cross
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+            binary: agent-browser-linux-x64
+          - os: macos-latest
+            target: aarch64-apple-darwin
+            binary: agent-browser-darwin-arm64
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+            binary: agent-browser-win32-x64.exe
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .node-version
+
+      - name: Setup Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - name: Cache Rust build artifacts
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: cli
+
+      - name: Build Rust CLI
+        run: cargo build --release --manifest-path cli/Cargo.toml --target ${{ matrix.target }}
+
+      - name: Copy CLI binary to bin directory (Unix)
+        if: runner.os != 'Windows'
+        run: cp cli/target/${{ matrix.target }}/release/agent-browser bin/${{ matrix.binary }}
+
+      - name: Copy CLI binary to bin directory (Windows)
+        if: runner.os == 'Windows'
+        run: Copy-Item cli/target/${{ matrix.target }}/release/agent-browser.exe bin/${{ matrix.binary }}
+
+      - name: Test npm global install
+        run: |
+          npm pack
+          npm install -g agent-browser-*.tgz
+          agent-browser --version
+        shell: bash
+
+      - name: Verify symlink points to native binary (Unix)
+        if: runner.os != 'Windows'
+        run: |
+          SYMLINK=$(npm prefix -g)/bin/agent-browser
+          TARGET=$(readlink "$SYMLINK")
+          echo "Symlink: $SYMLINK"
+          echo "Target: $TARGET"
+          if [[ "$TARGET" != *"${{ matrix.binary }}"* ]]; then
+            echo "ERROR: Symlink should point to native binary, not JS wrapper"
+            exit 1
+          fi
+          echo "Symlink correctly points to native binary"
+        shell: bash
+
+      - name: Verify shim points to native binary (Windows)
+        if: runner.os == 'Windows'
+        run: |
+          $shimPath = "$(npm prefix -g)\agent-browser.cmd"
+          $content = Get-Content $shimPath -Raw
+          echo "Shim path: $shimPath"
+          echo "Shim content:"
+          echo $content
+          if ($content -notmatch "agent-browser-win32-x64\.exe") {
+            echo "ERROR: Shim should point to native .exe, not JS wrapper"
+            exit 1
+          }
+          echo "Shim correctly points to native binary"
+        shell: pwsh

.github/workflows/release.yml

@@ -0,0 +1,406 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+permissions:
+  contents: read
+
+jobs:
+  check-release:
+    name: Check for new version
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    outputs:
+      should_release: ${{ steps.check.outputs.should_release }}
+      should_publish_sandbox: ${{ steps.check.outputs.should_publish_sandbox }}
+      needs_github_release: ${{ steps.check.outputs.needs_github_release }}
+      version: ${{ steps.check.outputs.version }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .node-version
+
+      - name: Compare package.json version to npm and check GitHub release
+        id: check
+        run: |
+          LOCAL_VERSION=$(node -p "require('./package.json').version")
+          SANDBOX_VERSION=$(node -p "require('./packages/@agent-browser/sandbox/package.json').version")
+          echo "Local version: $LOCAL_VERSION"
+          echo "Sandbox package version: $SANDBOX_VERSION"
+
+          NPM_VERSION=$(npm view agent-browser version 2>/dev/null || echo "0.0.0")
+          SANDBOX_NPM_VERSION=$(npm view @agent-browser/sandbox version 2>/dev/null || echo "0.0.0")
+          echo "npm version: $NPM_VERSION"
+          echo "@agent-browser/sandbox npm version: $SANDBOX_NPM_VERSION"
+
+          if [ "$LOCAL_VERSION" != "$NPM_VERSION" ]; then
+            echo "Version changed: $NPM_VERSION -> $LOCAL_VERSION"
+            echo "should_release=true" >> "$GITHUB_OUTPUT"
+            echo "needs_github_release=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "Version unchanged on npm, skipping build and publish"
+            echo "should_release=false" >> "$GITHUB_OUTPUT"
+
+            # Check if GitHub release exists; it may be missing if a prior run
+            # published to npm but failed before creating the release.
+            TAG="v$LOCAL_VERSION"
+            if gh release view "$TAG" &>/dev/null; then
+              echo "GitHub release $TAG exists"
+              echo "needs_github_release=false" >> "$GITHUB_OUTPUT"
+            else
+              echo "GitHub release $TAG is missing, will rebuild and create it"
+              echo "needs_github_release=true" >> "$GITHUB_OUTPUT"
+            fi
+          fi
+          if [ "$SANDBOX_VERSION" != "$SANDBOX_NPM_VERSION" ]; then
+            echo "Sandbox package version changed: $SANDBOX_NPM_VERSION -> $SANDBOX_VERSION"
+            echo "should_publish_sandbox=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "Sandbox package version unchanged on npm, skipping publish"
+            echo "should_publish_sandbox=false" >> "$GITHUB_OUTPUT"
+          fi
+          echo "version=$LOCAL_VERSION" >> "$GITHUB_OUTPUT"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  build-binaries:
+    name: Build ${{ matrix.name }}
+    needs: check-release
+    if: needs.check-release.outputs.should_release == 'true' || needs.check-release.outputs.needs_github_release == 'true'
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: Linux x64
+            os: ubuntu-latest
+            rust_target: x86_64-unknown-linux-gnu
+            build_target: x86_64-unknown-linux-gnu.2.28
+            binary: agent-browser-linux-x64
+            use_zigbuild: true
+          - name: Linux ARM64
+            os: ubuntu-latest
+            rust_target: aarch64-unknown-linux-gnu
+            build_target: aarch64-unknown-linux-gnu.2.28
+            binary: agent-browser-linux-arm64
+            use_zigbuild: true
+          - name: Linux musl x64
+            os: ubuntu-latest
+            rust_target: x86_64-unknown-linux-musl
+            build_target: x86_64-unknown-linux-musl
+            binary: agent-browser-linux-musl-x64
+            use_zigbuild: true
+          - name: Linux musl ARM64
+            os: ubuntu-latest
+            rust_target: aarch64-unknown-linux-musl
+            build_target: aarch64-unknown-linux-musl
+            binary: agent-browser-linux-musl-arm64
+            use_zigbuild: true
+          - name: Windows x64
+            os: ubuntu-latest
+            rust_target: x86_64-pc-windows-gnu
+            build_target: x86_64-pc-windows-gnu
+            binary: agent-browser-win32-x64.exe
+            use_zigbuild: false
+          - name: macOS x64
+            os: macos-latest
+            rust_target: x86_64-apple-darwin
+            build_target: x86_64-apple-darwin
+            binary: agent-browser-darwin-x64
+            use_zigbuild: false
+          - name: macOS ARM64
+            os: macos-latest
+            rust_target: aarch64-apple-darwin
+            build_target: aarch64-apple-darwin
+            binary: agent-browser-darwin-arm64
+            use_zigbuild: false
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .node-version
+          cache: pnpm
+
+      - name: Install npm dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Sync version
+        run: pnpm run version:sync
+
+      - name: Build dashboard
+        run: pnpm --filter dashboard build
+
+      - name: Setup Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.rust_target }}
+
+      - name: Install cross-compilation tools (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y gcc-aarch64-linux-gnu gcc-x86-64-linux-gnu mingw-w64
+
+      - name: Install cargo-zigbuild
+        if: matrix.use_zigbuild
+        run: |
+          pip3 install ziglang
+          cargo install cargo-zigbuild --version 0.22.3 --locked
+
+      - name: Configure Rust linkers
+        if: runner.os == 'Linux'
+        run: |
+          mkdir -p ~/.cargo
+          cat >> ~/.cargo/config.toml << 'EOF'
+          [target.aarch64-unknown-linux-gnu]
+          linker = "aarch64-linux-gnu-gcc"
+
+          [target.x86_64-pc-windows-gnu]
+          linker = "x86_64-w64-mingw32-gcc"
+          EOF
+
+      - name: Cache Rust build artifacts
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: cli
+
+      - name: Build with zigbuild
+        if: matrix.use_zigbuild
+        run: cargo zigbuild --release --manifest-path cli/Cargo.toml --target ${{ matrix.build_target }}
+
+      - name: Build with cargo
+        if: '!matrix.use_zigbuild'
+        run: cargo build --release --manifest-path cli/Cargo.toml --target ${{ matrix.rust_target }}
+
+      - name: Copy binary
+        run: |
+          mkdir -p artifacts
+          if [[ "${{ matrix.rust_target }}" == *"windows"* ]]; then
+            cp cli/target/${{ matrix.rust_target }}/release/agent-browser.exe artifacts/${{ matrix.binary }}
+          else
+            cp cli/target/${{ matrix.rust_target }}/release/agent-browser artifacts/${{ matrix.binary }}
+            chmod +x artifacts/${{ matrix.binary }}
+          fi
+
+      - name: Verify Linux GNU glibc floor
+        if: matrix.binary == 'agent-browser-linux-x64' || matrix.binary == 'agent-browser-linux-arm64'
+        run: |
+          set -euo pipefail
+          if objdump -p artifacts/${{ matrix.binary }} | grep -E 'GLIBC_2\.([3-9][0-9]|29)'; then
+            echo "ERROR: ${{ matrix.binary }} requires glibc newer than 2.28"
+            exit 1
+          fi
+          objdump -p artifacts/${{ matrix.binary }} | sed -n '/Version References:/,$p'
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.binary }}
+          path: artifacts/${{ matrix.binary }}
+          retention-days: 7
+
+  publish:
+    name: Publish to npm
+    needs: [check-release, build-binaries]
+    if: needs.check-release.outputs.should_release == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment: Release
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .node-version
+          cache: pnpm
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Download all binary artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: artifacts/
+
+      - name: Move binaries to bin directory
+        run: |
+          mkdir -p bin
+          find artifacts -type f -name 'agent-browser-*' -exec mv {} bin/ \;
+          rm -rf artifacts
+          chmod +x bin/agent-browser-* 2>/dev/null || true
+          echo "Binaries in bin/:"
+          ls -la bin/
+
+      - name: Verify all binaries exist
+        run: |
+          EXPECTED_BINARIES=(
+            "agent-browser-linux-x64"
+            "agent-browser-linux-arm64"
+            "agent-browser-linux-musl-x64"
+            "agent-browser-linux-musl-arm64"
+            "agent-browser-win32-x64.exe"
+            "agent-browser-darwin-x64"
+            "agent-browser-darwin-arm64"
+          )
+          MIN_SIZE=100000
+          ERRORS=0
+          for binary in "${EXPECTED_BINARIES[@]}"; do
+            if [ ! -f "bin/$binary" ]; then
+              echo "ERROR: Missing bin/$binary"
+              ERRORS=$((ERRORS + 1))
+            else
+              SIZE=$(stat -c%s "bin/$binary" 2>/dev/null || stat -f%z "bin/$binary")
+              if [ "$SIZE" -lt "$MIN_SIZE" ]; then
+                echo "ERROR: bin/$binary is too small ($SIZE bytes, expected >= $MIN_SIZE)"
+                ERRORS=$((ERRORS + 1))
+              else
+                echo "OK: bin/$binary ($SIZE bytes)"
+              fi
+            fi
+          done
+          if [ "$ERRORS" -gt 0 ]; then
+            echo "Error: $ERRORS binary issues found"
+            exit 1
+          fi
+          echo "All 7 platform binaries present and valid"
+
+      - name: Publish to npm
+        run: pnpm publish --provenance --no-git-checks
+
+  publish-sandbox:
+    name: Publish sandbox package to npm
+    needs: [check-release, publish]
+    if: >-
+      always() &&
+      needs.check-release.outputs.should_publish_sandbox == 'true' &&
+      (
+        needs.check-release.outputs.should_release != 'true' ||
+        needs.publish.result == 'success'
+      )
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: Release
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .node-version
+          cache: pnpm
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Sync version
+        run: pnpm run version:sync
+
+      - name: Publish sandbox package to npm
+        working-directory: packages/@agent-browser/sandbox
+        run: pnpm publish --provenance --access public --no-git-checks
+
+  github-release:
+    name: Create GitHub Release
+    needs: [check-release, build-binaries, publish, publish-sandbox]
+    if: >-
+      always() &&
+      needs.build-binaries.result == 'success' &&
+      needs.check-release.outputs.needs_github_release == 'true' &&
+      (needs.publish.result == 'success' || needs.publish.result == 'skipped') &&
+      (needs.publish-sandbox.result == 'success' || needs.publish-sandbox.result == 'skipped')
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: artifacts/
+
+      - name: Move binaries to bin directory
+        run: |
+          mkdir -p bin
+          find artifacts -type f -name 'agent-browser-*' -exec mv {} bin/ \;
+          rm -rf artifacts
+          chmod +x bin/agent-browser-* 2>/dev/null || true
+          ls -la bin/
+
+      - name: Verify binaries exist
+        run: |
+          BINARY_COUNT=$(ls bin/agent-browser-* 2>/dev/null | wc -l)
+          if [ "$BINARY_COUNT" -lt 7 ]; then
+            echo "Error: Expected 7 binaries, found $BINARY_COUNT"
+            ls -la bin/
+            exit 1
+          fi
+          echo "Found $BINARY_COUNT binaries"
+
+      - name: Extract changelog entry
+        run: |
+          VERSION="${{ needs.check-release.outputs.version }}"
+          awk '/<!-- release:start -->/{found=1; next} /<!-- release:end -->/{found=0} found{print}' CHANGELOG.md > /tmp/release-notes.md
+
+          LINES=$(wc -l < /tmp/release-notes.md | tr -d ' ')
+          if [ "$LINES" -lt 2 ]; then
+            echo "Error: No release notes found between <!-- release:start --> and <!-- release:end --> markers in CHANGELOG.md"
+            exit 1
+          fi
+          echo "Extracted release notes for $VERSION ($LINES lines)"
+
+      - name: Create GitHub Release
+        run: |
+          VERSION="${{ needs.check-release.outputs.version }}"
+          TAG="v$VERSION"
+
+          if gh release view "$TAG" &>/dev/null; then
+            echo "Release $TAG already exists, uploading assets..."
+            gh release upload "$TAG" bin/agent-browser-* --clobber
+          else
+            echo "Creating release $TAG..."
+            gh release create "$TAG" \
+              --title "$TAG" \
+              --notes-file /tmp/release-notes.md \
+              bin/agent-browser-*
+          fi
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1,73 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+
+# Native binaries (keep the launcher scripts)
+bin/agent-browser-*
+bin/.install-method
+!bin/agent-browser
+!bin/agent-browser.cmd
+
+# Rust build artifacts
+cli/target/
+cli/*.o
+
+# Logs
+*.log
+npm-debug.log*
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Python
+__pycache__/
+
+# Test artifacts
+*.png
+*.jpeg
+*.jpg
+*.webm
+test/e2e/.dogfood-output/
+
+# Package manager
+package-lock.json
+yarn.lock
+
+# Environment
+.env
+.env.local
+.env.*
+!.env.example
+!.env.*.example
+
+# Windows debug instance config
+scripts/windows-debug/.instance
+
+# opensrc - source code for packages
+opensrc/
+
+# Docs site
+docs/node_modules/
+docs/.next/
+docs/out/
+docs/package-lock.json
+
+# pnpm
+.pnpm-store/
+
+# TypeScript
+*.tsbuildinfo
+
+# next
+.next/
+out/
+next-env.d.ts

.husky/pre-commit

@@ -0,0 +1,2 @@
+node scripts/sync-version.js
+git add cli/Cargo.toml cli/Cargo.lock

.node-version

@@ -0,0 +1 @@
+24

.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "printWidth": 100,
+  "tabWidth": 2
+}

AGENTS.md

@@ -0,0 +1,214 @@
+# AGENTS.md
+
+Instructions for AI coding agents working with this codebase.
+
+## Package Manager
+
+This project uses **pnpm**. Always use `pnpm` instead of `npm` or `yarn` for installing dependencies, running scripts, etc. (e.g., `pnpm install`, `pnpm run build`).
+
+## Code Style
+
+- Do not use emojis in code, output, or documentation. Unicode symbols (✓, ✗, →, ⚠) are acceptable.
+- In documentation and markdown, never use double hyphens (`--`) as a dash. Use an emdash (—) sparingly when needed. Prefer rewriting the sentence to avoid dashes entirely.
+- CLI colored output uses `cli/src/color.rs`. This module respects the `NO_COLOR` environment variable. Never use hardcoded ANSI color codes.
+- CLI flags must always use kebab-case (e.g., `--auto-connect`, `--allow-file-access`). Never use camelCase for flags (e.g., `--autoConnect` is wrong).
+
+## Documentation
+
+Do not hard-wrap prose in documentation files such as Markdown, MDX, and READMEs; let the editor or renderer wrap text naturally.
+
+When adding or changing user-facing features (new flags, commands, behaviors, environment variables, etc.), update **all** of the following:
+
+1. `cli/src/output.rs` — `--help` output (flags list, examples, environment variables)
+2. `README.md` — Options table, relevant feature sections, examples
+3. `skill-data/core/SKILL.md` (and its `references/`) — so AI agents know about the feature when they load the core skill. Edit `skill-data/core/SKILL.md` for overview/workflow changes; edit `skill-data/core/references/*.md` for detailed reference content. Do **not** put feature content in `skills/agent-browser/SKILL.md` — that file is an intentionally thin discovery stub for `npx skills add` and exists only to redirect agents to `agent-browser skills get core`.
+4. `docs/src/app/` — the Next.js docs site (MDX pages)
+5. Inline doc comments in the relevant source files
+
+This applies to changes that either human users or AI agents would need to know about. Do not skip any of these locations.
+
+## CLI/MCP Parity
+
+When adding or changing any CLI command, flag, behavior, output, environment variable, or parser semantics, update the MCP server in `cli/src/mcp.rs` in the same change. MCP tools should stay in sync with canonical CLI behavior by delegating through the normal CLI parser where possible. If a CLI command has no dedicated MCP tool, add one or document why it is intentionally omitted. Add or update tests that prove the CLI and MCP surfaces remain aligned.
+
+In the `docs/src/app/` MDX files, always use HTML `<table>` syntax for tables (not markdown pipe tables). This matches the existing convention across the docs site.
+
+## Dashboard (packages/dashboard)
+
+- Never use native browser dialogs (`alert`, `confirm`, `prompt`). Use shadcn/ui components (`Dialog`, `AlertDialog`, etc.) instead.
+- Use param-case (kebab-case) for all file and folder names (e.g., `session-tree.tsx`, not `SessionTree.tsx`). The `ui/` directory follows shadcn conventions which already uses param-case.
+
+## Releasing
+
+Releases are manual, single-PR affairs. There is no changesets automation. The maintainer controls the changelog voice and format.
+
+To prepare a release:
+
+1. Create a branch (e.g. `prepare-v0.24.0`)
+2. Bump `version` in `package.json`
+3. Run `pnpm version:sync` to update `cli/Cargo.toml`, `cli/Cargo.lock`, and `packages/dashboard/package.json`
+4. Write the changelog entry in `CHANGELOG.md` at the top, under a new `## <version>` heading, wrapped in `<!-- release:start -->` and `<!-- release:end -->` markers. Remove the `<!-- release:start -->` and `<!-- release:end -->` markers from the previous release entry so only the new release has markers.
+5. Add a matching entry to `docs/src/app/changelog/page.mdx` at the top (below the `# Changelog` heading)
+6. Open a PR and merge to `main`
+
+When the PR merges, CI compares `package.json` version to what's on npm. If it differs, it builds all 7 platform binaries, publishes to npm, and creates the GitHub release automatically. The GitHub release body is extracted from the content between the `<!-- release:start -->` and `<!-- release:end -->` markers in `CHANGELOG.md`.
+
+### Writing the changelog
+
+Review the git log since the last release and write the entry in `CHANGELOG.md`. Follow the existing format and voice. Group changes under `### New Features`, `### Bug Fixes`, `### Improvements`, etc. Bold the feature/fix name, then describe it concisely. Reference PR numbers in parentheses.
+
+Wrap the release notes (everything between the `## <version>` heading and the previous version) in markers so CI can extract them for the GitHub release. Only the current release should have markers; remove the `<!-- release:start -->` and `<!-- release:end -->` markers from any previous release entry:
+
+```markdown
+## 0.24.1
+
+<!-- release:start -->
+### Bug Fixes
+
+- Fixed **baz** not working when qux is enabled (#1235)
+
+### Contributors
+
+- @ctate
+<!-- release:end -->
+
+## 0.24.0
+
+### New Features
+
+- **Foo command** - Added `foo` command for bar (#1234)
+```
+
+Include a `### Contributors` section listing the GitHub usernames (with `@` prefix) of everyone who contributed to the release. Check the git log between the previous tag and HEAD to find them.
+
+Do not prefix entries with commit hashes. Do not use the changesets `### Patch Changes` / `### Minor Changes` headings. Use descriptive section names instead.
+
+### Docs changelog
+
+The docs changelog at `docs/src/app/changelog/page.mdx` mirrors `CHANGELOG.md` but uses a slightly different format. Each entry uses:
+
+- A `v` prefix on the version (e.g. `## v0.24.0`)
+- A date line with the full date: `<p className="text-[#888] text-sm">March 30, 2026</p>`
+- A `---` separator between entries
+
+Match the existing style in that file.
+
+## Architecture
+
+This is a Rust codebase. The browser automation daemon lives in `cli/src/native/` (daemon, actions, browser, CDP client, snapshot, state). The `--engine` flag selects Chrome vs Lightpanda. The `install` command downloads Chrome from Chrome for Testing directly.
+
+## Testing
+
+### Unit Tests
+
+```bash
+cd cli && cargo test
+```
+
+Runs all unit tests (~320 tests). These are fast and don't require Chrome.
+
+### End-to-End Tests
+
+```bash
+cd cli && cargo test e2e -- --ignored --test-threads=1
+```
+
+Runs 18 e2e tests that launch real headless Chrome instances and exercise the full native daemon command pipeline. Requirements:
+
+- Chrome must be installed
+- Must run serially (`--test-threads=1`) to avoid Chrome instance contention
+- Tests are `#[ignore]`'d so they don't run during normal `cargo test`
+
+The e2e tests live in `cli/src/native/e2e_tests.rs` and cover: launch/close, navigation, snapshots, screenshots, form interaction, cookies, storage, tabs, element queries, viewport/emulation, domain filtering, diff, state management, error handling, and Phase 8 commands.
+
+### Linting and Formatting
+
+```bash
+cd cli && cargo fmt -- --check   # Check formatting
+cd cli && cargo clippy            # Lint
+```
+
+## Windows Debugging
+
+A remote Windows Server 2022 EC2 instance is available for debugging Windows-specific issues. It uses AWS Systems Manager (SSM) with no SSH or open ports. Commands run via `aws ssm send-command` and return stdout/stderr.
+
+### Prerequisites
+
+The instance must be provisioned first (one-time, by a human):
+
+```bash
+./scripts/windows-debug/provision.sh
+```
+
+Requires: AWS CLI v2 configured with `ec2:*`, `iam:CreateRole`, `iam:AttachRolePolicy`, `ssm:SendCommand`, `ssm:GetCommandInvocation` permissions and a default VPC.
+
+### Usage
+
+Start the instance (if stopped):
+
+```bash
+./scripts/windows-debug/start.sh
+```
+
+Run a command on Windows:
+
+```bash
+./scripts/windows-debug/run.sh "<powershell-command>"
+```
+
+Sync the current git branch and rebuild:
+
+```bash
+./scripts/windows-debug/sync.sh
+```
+
+Stop the instance when done (avoids cost):
+
+```bash
+./scripts/windows-debug/stop.sh
+```
+
+### Common Workflows
+
+Run unit tests on Windows:
+
+```bash
+./scripts/windows-debug/run.sh "cd C:\agent-browser && cargo test --manifest-path cli\Cargo.toml"
+```
+
+Run e2e tests on Windows:
+
+```bash
+./scripts/windows-debug/run.sh "cd C:\agent-browser && cargo test e2e --manifest-path cli\Cargo.toml -- --ignored --test-threads=1"
+```
+
+Check bootstrap progress (first boot only):
+
+```bash
+./scripts/windows-debug/run.sh "Get-Content C:\bootstrap.log"
+```
+
+The repo lives at `C:\agent-browser` on the instance. Rust, Git, and Chrome are pre-installed. The `run.sh` wrapper automatically adds cargo and git to PATH.
+
+<!-- opensrc:start -->
+
+## Source Code Reference
+
+Source code for dependencies is available in `opensrc/` for deeper understanding of implementation details.
+
+See `opensrc/sources.json` for the list of available packages and their versions.
+
+Use this source code when you need to understand how a package works internally, not just its types/interface.
+
+### Fetching Additional Source Code
+
+To fetch source code for a package or repository you need to understand, run:
+
+```bash
+npx opensrc <package>           # npm package (e.g., npx opensrc zod)
+npx opensrc pypi:<package>      # Python package (e.g., npx opensrc pypi:requests)
+npx opensrc crates:<package>    # Rust crate (e.g., npx opensrc crates:serde)
+npx opensrc <owner>/<repo>      # GitHub repo (e.g., npx opensrc vercel/ai)
+```
+
+<!-- opensrc:end -->

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1.  Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction,
+    and distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by
+    the copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all
+    other entities that control, are controlled by, or are under common
+    control with that entity. For the purposes of this definition,
+    "control" means (i) the power, direct or indirect, to cause the
+    direction or management of such entity, whether by contract or
+    otherwise, or (ii) ownership of fifty percent (50%) or more of the
+    outstanding shares, or (iii) beneficial ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity
+    exercising permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation
+    source, and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical
+    transformation or translation of a Source form, including but
+    not limited to compiled object code, generated documentation,
+    and conversions to other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or
+    Object form, made available under the License, as indicated by a
+    copyright notice that is included in or attached to the work
+    (an example is provided in the Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object
+    form, that is based on (or derived from) the Work and for which the
+    editorial revisions, annotations, elaborations, or other modifications
+    represent, as a whole, an original work of authorship. For the purposes
+    of this License, Derivative Works shall not include works that remain
+    separable from, or merely link (or bind by name) to the interfaces of,
+    the Work and Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including
+    the original version of the Work and any modifications or additions
+    to that Work or Derivative Works thereof, that is intentionally
+    submitted to Licensor for inclusion in the Work by the copyright owner
+    or by an individual or Legal Entity authorized to submit on behalf of
+    the copyright owner. For the purposes of this definition, "submitted"
+    means any form of electronic, verbal, or written communication sent
+    to the Licensor or its representatives, including but not limited to
+    communication on electronic mailing lists, source code control systems,
+    and issue tracking systems that are managed by, or on behalf of, the
+    Licensor for the purpose of discussing and improving the Work, but
+    excluding communication that is conspicuously marked or otherwise
+    designated in writing by the copyright owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity
+    on behalf of whom a Contribution has been received by Licensor and
+    subsequently incorporated within the Work.
+
+2.  Grant of Copyright License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    copyright license to reproduce, prepare Derivative Works of,
+    publicly display, publicly perform, sublicense, and distribute the
+    Work and such Derivative Works in Source or Object form.
+
+3.  Grant of Patent License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    (except as stated in this section) patent license to make, have made,
+    use, offer to sell, sell, import, and otherwise transfer the Work,
+    where such license applies only to those patent claims licensable
+    by such Contributor that are necessarily infringed by their
+    Contribution(s) alone or by combination of their Contribution(s)
+    with the Work to which such Contribution(s) was submitted. If You
+    institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work
+    or a Contribution incorporated within the Work constitutes direct
+    or contributory patent infringement, then any patent licenses
+    granted to You under this License for that Work shall terminate
+    as of the date such litigation is filed.
+
+4.  Redistribution. You may reproduce and distribute copies of the
+    Work or Derivative Works thereof in any medium, with or without
+    modifications, and in Source or Object form, provided that You
+    meet the following conditions:
+
+    (a) You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+
+    (b) You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+
+    (c) You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+
+    (d) If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and
+    may provide additional or different license terms and conditions
+    for use, reproduction, or distribution of Your modifications, or
+    for any such Derivative Works as a whole, provided Your use,
+    reproduction, and distribution of the Work otherwise complies with
+    the conditions stated in this License.
+
+5.  Submission of Contributions. Unless You explicitly state otherwise,
+    any Contribution intentionally submitted for inclusion in the Work
+    by You to the Licensor shall be under the terms and conditions of
+    this License, without any additional terms or conditions.
+    Notwithstanding the above, nothing herein shall supersede or modify
+    the terms of any separate license agreement you may have executed
+    with Licensor regarding such Contributions.
+
+6.  Trademarks. This License does not grant permission to use the trade
+    names, trademarks, service marks, or product names of the Licensor,
+    except as required for reasonable and customary use in describing the
+    origin of the Work and reproducing the content of the NOTICE file.
+
+7.  Disclaimer of Warranty. Unless required by applicable law or
+    agreed to in writing, Licensor provides the Work (and each
+    Contributor provides its Contributions) on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+    implied, including, without limitation, any warranties or conditions
+    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+    PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any
+    risks associated with Your exercise of permissions under this License.
+
+8.  Limitation of Liability. In no event and under no legal theory,
+    whether in tort (including negligence), contract, or otherwise,
+    unless required by applicable law (such as deliberate and grossly
+    negligent acts) or agreed to in writing, shall any Contributor be
+    liable to You for damages, including any direct, indirect, special,
+    incidental, or consequential damages of any character arising as a
+    result of this License or out of the use or inability to use the
+    Work (including but not limited to damages for loss of goodwill,
+    work stoppage, computer failure or malfunction, or any and all
+    other commercial damages or losses), even if such Contributor
+    has been advised of the possibility of such damages.
+
+9.  Accepting Warranty or Additional Liability. While redistributing
+    the Work or Derivative Works thereof, You may choose to offer,
+    and charge a fee for, acceptance of support, warranty, indemnity,
+    or other liability obligations and/or rights consistent with this
+    License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf
+    of any other Contributor, and only if You agree to indemnify,
+    defend, and hold each Contributor harmless for any liability
+    incurred by, or claims asserted against, such Contributor by reason
+    of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+Copyright 2025 Vercel Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

README.wehub.md

@@ -0,0 +1,7 @@
+# WeHub 来源说明
+
+- 原始项目：`vercel-labs/agent-browser`
+- 原始仓库：https://github.com/vercel-labs/agent-browser
+- 导入方式：上游默认分支的最新快照
+- 原作者、版权和许可证信息以原始仓库及本仓库 LICENSE 为准
+- 本文件仅用于记录来源，不代表 WeHub 是原项目作者

agent-browser.schema.json

@@ -0,0 +1,248 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Agent Browser Configuration",
+  "description": "Configuration file for agent-browser (e.g., agent-browser.json or ~/.agent-browser/config.json)",
+  "type": "object",
+  "properties": {
+    "headed": {
+      "type": "boolean",
+      "description": "Show browser window instead of running headless."
+    },
+    "json": {
+      "type": "boolean",
+      "description": "Output in JSON format."
+    },
+    "debug": {
+      "type": "boolean",
+      "description": "Enable debug output."
+    },
+    "session": {
+      "type": "string",
+      "description": "Session identifier."
+    },
+    "restore": {
+      "type": "string",
+      "description": "Auto-save/restore persistence key. A bare CLI --restore uses the current session; config values use this explicit key."
+    },
+    "restoreSave": {
+      "type": "string",
+      "enum": ["auto", "always", "never"],
+      "default": "auto",
+      "description": "Auto-save policy for restored state."
+    },
+    "restoreCheckUrl": {
+      "type": "string",
+      "description": "URL glob that restored state must match before auto-save."
+    },
+    "restoreCheckText": {
+      "type": "string",
+      "description": "Visible page text that restored state must expose before auto-save."
+    },
+    "restoreCheckFn": {
+      "type": "string",
+      "description": "JavaScript expression that must evaluate truthy before restored state is auto-saved."
+    },
+    "namespace": {
+      "type": "string",
+      "description": "Namespace that isolates daemon sockets and restore-state directories."
+    },
+    "sessionName": {
+      "type": "string",
+      "description": "Legacy alias for restore persistence key."
+    },
+    "executablePath": {
+      "type": "string",
+      "description": "Path to a custom browser executable."
+    },
+    "extensions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Paths to browser extensions. Extensions from user-level and project-level configs are concatenated."
+    },
+    "initScripts": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Page init script paths registered before navigation."
+    },
+    "enable": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["react-devtools"]
+      },
+      "description": "Built-in launch features to enable."
+    },
+    "profile": {
+      "type": "string",
+      "description": "Path to the browser profile data directory."
+    },
+    "state": {
+      "type": "string",
+      "description": "Path to load/save browser state."
+    },
+    "proxy": {
+      "type": "string",
+      "description": "Proxy server URL (e.g., http://localhost:8080)."
+    },
+    "proxyBypass": {
+      "type": "string",
+      "description": "Comma-separated domains to bypass the proxy (e.g., localhost,*.internal.com)."
+    },
+    "args": {
+      "type": "string",
+      "description": "Additional comma-separated launch arguments for the browser."
+    },
+    "userAgent": {
+      "type": "string",
+      "description": "Custom User-Agent string."
+    },
+    "provider": {
+      "type": "string",
+      "description": "Provider to use, such as 'ios'."
+    },
+    "device": {
+      "type": "string",
+      "description": "Device name or identifier for emulation or providers (e.g., 'iPhone 16 Pro')."
+    },
+    "hideScrollbars": {
+      "type": "boolean",
+      "description": "Hide native scrollbars in headless Chromium screenshots. Defaults to true."
+    },
+    "ignoreHttpsErrors": {
+      "type": "boolean",
+      "description": "Ignore HTTPS errors during navigation."
+    },
+    "allowFileAccess": {
+      "type": "boolean",
+      "description": "Allow file:// URLs to access local files."
+    },
+    "cdp": {
+      "type": "string",
+      "description": "Chrome DevTools Protocol endpoint URL."
+    },
+    "autoConnect": {
+      "type": "boolean",
+      "description": "Auto-discover and connect to a running Chrome instance."
+    },
+    "annotate": {
+      "type": "boolean",
+      "description": "Annotated screenshot with numbered element labels."
+    },
+    "colorScheme": {
+      "type": "string",
+      "enum": ["dark", "light", "no-preference"],
+      "description": "Color scheme preference."
+    },
+    "downloadPath": {
+      "type": "string",
+      "description": "Default directory for browser downloads."
+    },
+    "contentBoundaries": {
+      "type": "boolean",
+      "description": "Wrap page output in boundary markers for LLM safety."
+    },
+    "maxOutput": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Max characters for page output (truncates beyond limit)."
+    },
+    "allowedDomains": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Allowed domain patterns (e.g., ['example.com', '*.example.com'])."
+    },
+    "actionPolicy": {
+      "type": "string",
+      "description": "Path to action policy JSON file."
+    },
+    "confirmActions": {
+      "type": "string",
+      "description": "Comma-separated action categories requiring confirmation."
+    },
+    "confirmInteractive": {
+      "type": "boolean",
+      "description": "Enable interactive confirmation prompts (auto-denies if stdin is not a TTY)."
+    },
+    "engine": {
+      "type": "string",
+      "enum": ["chrome", "lightpanda"],
+      "default": "chrome",
+      "description": "Browser engine to use."
+    },
+    "screenshotDir": {
+      "type": "string",
+      "description": "Default screenshot output directory."
+    },
+    "screenshotQuality": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 100,
+      "description": "JPEG quality for screenshots (0-100)."
+    },
+    "screenshotFormat": {
+      "type": "string",
+      "enum": ["png", "jpeg"],
+      "description": "Screenshot format."
+    },
+    "idleTimeout": {
+      "type": "string",
+      "description": "Auto-shutdown the daemon after inactivity (e.g., '30s', '5m', '1h', or raw milliseconds like '60000')."
+    },
+    "model": {
+      "type": "string",
+      "description": "AI model for chat command (e.g., 'openai/gpt-4o')."
+    },
+    "noAutoDialog": {
+      "type": "boolean",
+      "description": "Disable automatic dismissal of alert/beforeunload dialogs."
+    },
+    "headers": {
+      "type": "string",
+      "description": "Custom HTTP headers supplied as a JSON-formatted string."
+    },
+    "plugins": {
+      "type": "array",
+      "description": "External plugin registry. Project-level entries are appended after user-level entries, and duplicate names resolve to the later entry.",
+      "items": {
+        "type": "object",
+        "required": ["name", "command"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Plugin name used by commands such as auth login --credential-provider."
+          },
+          "command": {
+            "type": "string",
+            "description": "Executable path or command name for the plugin process."
+          },
+          "args": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Optional arguments passed to the plugin process. Do not store secrets here."
+          },
+          "capabilities": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Capabilities declared by the plugin. Built-in capability names include credential.read, browser.provider, launch.mutate, and command.run; plugins may also declare custom names such as captcha.solve."
+          },
+          "source": {
+            "type": "string",
+            "description": "Optional source recorded by agent-browser plugin add, such as npm:agent-browser-plugin-example or github:owner/repo."
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}

benchmarks/.env.example

@@ -0,0 +1,4 @@
+# Vercel Sandbox credentials
+SANDBOX_VERCEL_TOKEN=
+SANDBOX_VERCEL_TEAM_ID=
+SANDBOX_VERCEL_PROJECT_ID=

benchmarks/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+results.json

benchmarks/README.md

@@ -0,0 +1,76 @@
+# agent-browser Daemon Benchmarks
+
+Compares command latency and system metrics between the **Node.js daemon** (published npm version) and the **Rust native daemon** (built from source), running inside a [Vercel Sandbox](https://vercel.com/docs/sandbox) microVM.
+
+## What it measures
+
+**Command latency** -- per-scenario timing with warmup, multiple iterations, and stddev:
+
+- `navigate` -- page load round-trip
+- `snapshot` -- accessibility tree generation
+- `screenshot` -- viewport capture
+- `evaluate` -- JavaScript execution
+- `click` -- element interaction
+- `fill` -- form input
+- `agent-loop` -- snapshot/click/snapshot cycle (typical AI agent pattern)
+- `full-workflow` -- realistic 7-command sequence
+
+**System metrics** -- collected while the daemon is running:
+
+- Cold start time (daemon spawn + browser launch)
+- Binary size and total distribution size (including browser download)
+- Daemon RSS and peak RSS (separated from browser process memory)
+- Browser RSS (Chrome processes, same for both daemons)
+- Daemon CPU time
+- Process counts
+
+## Prerequisites
+
+- Node.js 18+
+- pnpm
+- Vercel Sandbox credentials (token, team ID, project ID)
+
+## Setup
+
+```bash
+cd benchmarks
+pnpm install
+cp .env.example .env
+```
+
+Fill in your Vercel Sandbox credentials in `.env`:
+
+```
+SANDBOX_VERCEL_TOKEN=your_token
+SANDBOX_VERCEL_TEAM_ID=your_team_id
+SANDBOX_VERCEL_PROJECT_ID=your_project_id
+```
+
+## Usage
+
+```bash
+pnpm bench                             # 10 iterations, 1 warmup, 8 vCPUs
+pnpm bench -- --iterations 20          # more iterations for tighter stats
+pnpm bench -- --warmup 2               # extra warmup iterations
+pnpm bench -- --json                   # write results.json
+pnpm bench -- --branch main            # build native from a different branch
+pnpm bench -- --vcpus 16               # more vCPUs (faster Rust build)
+```
+
+## How it works
+
+1. Creates a Vercel Sandbox (Amazon Linux, configurable vCPUs)
+2. Installs Chromium system dependencies
+3. **Phase 1 -- Node.js daemon**: installs `agent-browser` from npm (last version with the Node daemon), runs all scenarios, collects metrics
+4. **Phase 2 -- Rust native daemon**: installs Rust toolchain, clones the repo, runs `cargo build --release`, replaces the binary, runs the same scenarios, collects metrics
+5. Prints comparison tables and optionally writes `results.json`
+
+## Interpreting results
+
+**Command latency** is dominated by Chrome (CDP round-trips), not the daemon. Both daemons are thin relays between the CLI and Chrome, so per-command speedups are typically small. The stddev column helps distinguish real differences from noise.
+
+**Where the native daemon wins** is in cold start (no Node.js runtime to boot), daemon memory (single Rust binary vs V8 heap), and distribution size (no Playwright dependency).
+
+The **daemon RSS** metric isolates the daemon process memory from Chrome. This is the apples-to-apples comparison -- both daemons talk to the same Chrome, but Node.js adds ~140 MB of V8 overhead while the Rust daemon uses ~7 MB.
+
+**Distribution size** includes the daemon plus its browser download. The Node version includes the npm package + Playwright's bundled Chromium. The Rust version is just the binary + Chrome for Testing.

benchmarks/bench.ts

@@ -0,0 +1,900 @@
+/**
+ * Node.js Daemon vs Rust Native Daemon benchmark.
+ *
+ * Compares the last published npm version (Node.js daemon) against the
+ * Rust-only build from a given branch, running real agent-browser commands
+ * inside a Vercel Sandbox.
+ *
+ * Captures:
+ *   - Command latency (per-scenario, with warmup + measured iterations + stddev)
+ *   - Cold start time (first launch to daemon ready)
+ *   - Daemon memory (RSS, peak RSS) separated from browser memory
+ *   - Daemon CPU time
+ *   - Process tree (daemon + browser children)
+ *   - Binary and distribution size on disk
+ *
+ * Usage:
+ *   pnpm bench                        # default: 10 iterations, 1 warmup
+ *   pnpm bench -- --iterations 20     # override iterations
+ *   pnpm bench -- --warmup 2          # override warmup count
+ *   pnpm bench -- --json              # write results.json
+ *   pnpm bench -- --branch my-branch  # override native branch (default: ctate/native-2)
+ *   pnpm bench -- --vcpus 8           # sandbox vCPUs (default: 8, higher = faster Rust build)
+ */
+
+import { Sandbox } from "@vercel/sandbox";
+import { readFileSync, writeFileSync } from "fs";
+import { scenarios, type Scenario } from "./scenarios.js";
+
+// ---------------------------------------------------------------------------
+// Env
+// ---------------------------------------------------------------------------
+
+function loadEnv() {
+  try {
+    const content = readFileSync(".env", "utf-8");
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const eq = trimmed.indexOf("=");
+      if (eq === -1) continue;
+      const key = trimmed.slice(0, eq);
+      let val = trimmed.slice(eq + 1);
+      if (
+        (val.startsWith('"') && val.endsWith('"')) ||
+        (val.startsWith("'") && val.endsWith("'"))
+      ) {
+        val = val.slice(1, -1);
+      }
+      process.env[key] = val;
+    }
+  } catch {}
+}
+loadEnv();
+
+const credentials = {
+  token: process.env.SANDBOX_VERCEL_TOKEN!,
+  teamId: process.env.SANDBOX_VERCEL_TEAM_ID!,
+  projectId: process.env.SANDBOX_VERCEL_PROJECT_ID!,
+};
+
+if (!credentials.token || !credentials.teamId || !credentials.projectId) {
+  console.error(
+    "Missing credentials. Set SANDBOX_VERCEL_TOKEN, SANDBOX_VERCEL_TEAM_ID, SANDBOX_VERCEL_PROJECT_ID in .env",
+  );
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// CLI args
+// ---------------------------------------------------------------------------
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  let iterations = 10;
+  let warmup = 1;
+  let json = false;
+  let branch = "ctate/native-2";
+  let vcpus = 8;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--iterations" && args[i + 1]) {
+      iterations = parseInt(args[++i], 10);
+    } else if (args[i] === "--warmup" && args[i + 1]) {
+      warmup = parseInt(args[++i], 10);
+    } else if (args[i] === "--json") {
+      json = true;
+    } else if (args[i] === "--branch" && args[i + 1]) {
+      branch = args[++i];
+    } else if (args[i] === "--vcpus" && args[i + 1]) {
+      vcpus = parseInt(args[++i], 10);
+    }
+  }
+
+  return { iterations, warmup, json, branch, vcpus };
+}
+
+const config = parseArgs();
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const TIMEOUT_MS = 30 * 60 * 1000;
+const REPO_URL = "https://github.com/vercel-labs/agent-browser.git";
+
+const CHROMIUM_SYSTEM_DEPS = [
+  "nss",
+  "nspr",
+  "libxkbcommon",
+  "atk",
+  "at-spi2-atk",
+  "at-spi2-core",
+  "libXcomposite",
+  "libXdamage",
+  "libXrandr",
+  "libXfixes",
+  "libXcursor",
+  "libXi",
+  "libXtst",
+  "libXScrnSaver",
+  "libXext",
+  "mesa-libgbm",
+  "libdrm",
+  "mesa-libGL",
+  "mesa-libEGL",
+  "cups-libs",
+  "alsa-lib",
+  "pango",
+  "cairo",
+  "gtk3",
+  "dbus-libs",
+];
+
+// ---------------------------------------------------------------------------
+// Sandbox helpers
+// ---------------------------------------------------------------------------
+
+type SandboxInstance = InstanceType<typeof Sandbox>;
+
+async function run(
+  sandbox: SandboxInstance,
+  cmd: string,
+  args: string[],
+): Promise<string> {
+  const result = await sandbox.runCommand(cmd, args);
+  const stdout = await result.stdout();
+  const stderr = await result.stderr();
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `Command failed (exit ${result.exitCode}): ${cmd} ${args.join(" ")}\n${stderr || stdout}`,
+    );
+  }
+  return stdout;
+}
+
+async function shell(sandbox: SandboxInstance, script: string): Promise<string> {
+  return run(sandbox, "sh", ["-c", script]);
+}
+
+async function shellSafe(sandbox: SandboxInstance, script: string): Promise<string> {
+  const result = await sandbox.runCommand("sh", ["-c", script]);
+  return (await result.stdout()).trim();
+}
+
+// ---------------------------------------------------------------------------
+// Stats
+// ---------------------------------------------------------------------------
+
+interface Stats {
+  avgMs: number;
+  stddevMs: number;
+  minMs: number;
+  maxMs: number;
+  p50Ms: number;
+  samples: number[];
+}
+
+function computeStats(samples: number[]): Stats {
+  const sorted = [...samples].sort((a, b) => a - b);
+  const sum = sorted.reduce((a, b) => a + b, 0);
+  const avg = sum / sorted.length;
+  const variance =
+    sorted.reduce((acc, v) => acc + (v - avg) ** 2, 0) / sorted.length;
+  return {
+    avgMs: Math.round(avg),
+    stddevMs: Math.round(Math.sqrt(variance)),
+    minMs: sorted[0],
+    maxMs: sorted[sorted.length - 1],
+    p50Ms: sorted[Math.floor(sorted.length / 2)],
+    samples: sorted,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Metrics collection
+// ---------------------------------------------------------------------------
+
+interface ProcessMetrics {
+  pid: number;
+  rssKb: number;
+  vszKb: number;
+  cpuPercent: number;
+  memPercent: number;
+  cpuTimeSec: number;
+  command: string;
+}
+
+interface DaemonMetrics {
+  coldStartMs: number;
+  binarySizeBytes: number;
+  distributionSizeBytes: number;
+  daemonProcesses: ProcessMetrics[];
+  browserProcesses: ProcessMetrics[];
+  daemonRssKb: number;
+  browserRssKb: number;
+  daemonPeakRssKb: number;
+  daemonCpuTimeSec: number;
+  totalCpuTimeSec: number;
+}
+
+async function findDaemonPids(
+  sandbox: SandboxInstance,
+  _session: string,
+): Promise<number[]> {
+  // The daemon process name is "agent-browser" but session/daemon flags are
+  // env vars, not command-line args, so we can't grep them from `ps`.
+  // Instead, find all agent-browser processes that look like long-running daemons
+  // (not short-lived CLI invocations -- those exit immediately).
+  const raw = await shellSafe(
+    sandbox,
+    `pgrep -x agent-browser 2>/dev/null || true`,
+  );
+  if (!raw) {
+    // Fallback: broader match on process name
+    const fallback = await shellSafe(
+      sandbox,
+      `pgrep -f 'agent-browser' 2>/dev/null | head -5 || true`,
+    );
+    if (!fallback) return [];
+    return fallback.split("\n").map(Number).filter(Boolean);
+  }
+  return raw.split("\n").map(Number).filter(Boolean);
+}
+
+async function collectProcessMetrics(
+  sandbox: SandboxInstance,
+  pid: number,
+): Promise<ProcessMetrics | null> {
+  const raw = await shellSafe(
+    sandbox,
+    `ps -p ${pid} -o pid=,rss=,vsz=,%cpu=,%mem=,cputime=,comm= 2>/dev/null || true`,
+  );
+  if (!raw) return null;
+
+  const parts = raw.trim().split(/\s+/);
+  if (parts.length < 7) return null;
+
+  // Parse cputime "HH:MM:SS" or "MM:SS" to seconds
+  const timeParts = parts[5].split(":").map(Number);
+  let cpuTimeSec = 0;
+  if (timeParts.length === 3) {
+    cpuTimeSec = timeParts[0] * 3600 + timeParts[1] * 60 + timeParts[2];
+  } else if (timeParts.length === 2) {
+    cpuTimeSec = timeParts[0] * 60 + timeParts[1];
+  }
+
+  return {
+    pid: Number(parts[0]),
+    rssKb: Number(parts[1]),
+    vszKb: Number(parts[2]),
+    cpuPercent: Number(parts[3]),
+    memPercent: Number(parts[4]),
+    cpuTimeSec,
+    command: parts.slice(6).join(" "),
+  };
+}
+
+async function getPeakRssKb(
+  sandbox: SandboxInstance,
+  pid: number,
+): Promise<number> {
+  const raw = await shellSafe(
+    sandbox,
+    `cat /proc/${pid}/status 2>/dev/null | grep VmHWM | awk '{print $2}' || echo 0`,
+  );
+  return Number(raw) || 0;
+}
+
+async function getChildPids(
+  sandbox: SandboxInstance,
+  pid: number,
+): Promise<number[]> {
+  const raw = await shellSafe(
+    sandbox,
+    `pgrep -P ${pid} 2>/dev/null || true`,
+  );
+  if (!raw) return [];
+  return raw.split("\n").map(Number).filter(Boolean);
+}
+
+async function getAllDescendantPids(
+  sandbox: SandboxInstance,
+  pid: number,
+): Promise<number[]> {
+  const all: number[] = [];
+  const queue = [pid];
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    all.push(current);
+    const children = await getChildPids(sandbox, current);
+    queue.push(...children);
+  }
+  return all;
+}
+
+async function collectDaemonMetrics(
+  sandbox: SandboxInstance,
+  session: string,
+  coldStartMs: number,
+  binarySizeBytes: number,
+  distributionSizeBytes: number,
+): Promise<DaemonMetrics> {
+  // Find daemon PIDs -- the agent-browser process itself
+  const daemonPids = await findDaemonPids(sandbox, session);
+
+  // Also find the full process tree (daemon + Chrome children)
+  let allPids: number[] = [];
+  for (const pid of daemonPids) {
+    const descendants = await getAllDescendantPids(sandbox, pid);
+    allPids.push(...descendants);
+  }
+  allPids = [...new Set(allPids)];
+
+  // If no daemon PIDs found via pgrep, fall back to grabbing all
+  // agent-browser and chrome processes for metrics
+  if (allPids.length === 0) {
+    const fallback = await shellSafe(
+      sandbox,
+      `ps -eo pid,comm | grep -E 'agent-browser|chrome' | grep -v grep | awk '{print $1}' || true`,
+    );
+    if (fallback) {
+      allPids = fallback.split("\n").map(Number).filter(Boolean);
+    }
+  }
+
+  const daemonProcs: ProcessMetrics[] = [];
+  const browserProcs: ProcessMetrics[] = [];
+  let daemonPeakRssKb = 0;
+
+  for (const pid of allPids) {
+    const metrics = await collectProcessMetrics(sandbox, pid);
+    if (!metrics) continue;
+
+    const isBrowser = /chrome|chromium/i.test(metrics.command);
+    if (isBrowser) {
+      browserProcs.push(metrics);
+    } else {
+      daemonProcs.push(metrics);
+      const peak = await getPeakRssKb(sandbox, pid);
+      daemonPeakRssKb = Math.max(daemonPeakRssKb, peak);
+    }
+  }
+
+  const daemonRssKb = daemonProcs.reduce((sum, p) => sum + p.rssKb, 0);
+  const browserRssKb = browserProcs.reduce((sum, p) => sum + p.rssKb, 0);
+  const daemonCpuTimeSec = daemonProcs.reduce((sum, p) => sum + p.cpuTimeSec, 0);
+  const allProcs = [...daemonProcs, ...browserProcs];
+  const totalCpuTimeSec = allProcs.reduce((sum, p) => sum + p.cpuTimeSec, 0);
+
+  return {
+    coldStartMs,
+    binarySizeBytes,
+    distributionSizeBytes,
+    daemonProcesses: daemonProcs,
+    browserProcesses: browserProcs,
+    daemonRssKb,
+    browserRssKb,
+    daemonPeakRssKb,
+    daemonCpuTimeSec,
+    totalCpuTimeSec,
+  };
+}
+
+async function getBinarySize(
+  sandbox: SandboxInstance,
+): Promise<number> {
+  // Follow symlinks to get the real binary/script size
+  const raw = await shellSafe(
+    sandbox,
+    `stat -L -c %s "$(readlink -f "$(which agent-browser)")" 2>/dev/null || echo 0`,
+  );
+  return Number(raw) || 0;
+}
+
+async function getDistributionSize(
+  sandbox: SandboxInstance,
+  mode: DaemonMode,
+): Promise<number> {
+  if (mode === "node") {
+    // Total size of the npm package + Playwright browser
+    const npmPkg = await shellSafe(
+      sandbox,
+      `du -sb "$(npm root -g)/agent-browser" 2>/dev/null | awk '{print $1}' || echo 0`,
+    );
+    const pwBrowser = await shellSafe(
+      sandbox,
+      `du -sb "$HOME/.cache/ms-playwright" 2>/dev/null | awk '{print $1}' || echo 0`,
+    );
+    return (Number(npmPkg) || 0) + (Number(pwBrowser) || 0);
+  } else {
+    // Rust binary + Chrome for Testing (checks multiple possible cache paths)
+    const binary = await shellSafe(
+      sandbox,
+      `stat -L -c %s "$(readlink -f "$(which agent-browser)")" 2>/dev/null || echo 0`,
+    );
+    const chrome = await shellSafe(
+      sandbox,
+      [
+        `size=0`,
+        `for d in "$HOME/.cache/agent-browser" "$HOME/.cache/ms-playwright" "$HOME/.agent-browser/chrome"; do`,
+        `  if [ -d "$d" ]; then size=$(du -sb "$d" 2>/dev/null | awk '{print $1}'); break; fi`,
+        `done`,
+        `echo $size`,
+      ].join("; "),
+    );
+    return (Number(binary) || 0) + (Number(chrome) || 0);
+  }
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes >= 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+  if (bytes >= 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${bytes} B`;
+}
+
+function formatKb(kb: number): string {
+  if (kb >= 1024) return `${(kb / 1024).toFixed(1)} MB`;
+  return `${kb} KB`;
+}
+
+// ---------------------------------------------------------------------------
+// Scenario runner
+// ---------------------------------------------------------------------------
+
+type DaemonMode = "node" | "native";
+
+function daemonEnv(mode: DaemonMode): Record<string, string> {
+  return { AGENT_BROWSER_SESSION: `bench-${mode}` };
+}
+
+async function agentBrowser(
+  sandbox: SandboxInstance,
+  args: string[],
+  mode: DaemonMode,
+): Promise<void> {
+  const result = await sandbox.runCommand({
+    cmd: "agent-browser",
+    args,
+    env: daemonEnv(mode),
+  });
+  if (result.exitCode !== 0) {
+    const stderr = await result.stderr();
+    const stdout = await result.stdout();
+    throw new Error(
+      `agent-browser ${args.join(" ")} failed (exit ${result.exitCode}): ${stderr || stdout}`,
+    );
+  }
+}
+
+async function timedAgentBrowser(
+  sandbox: SandboxInstance,
+  args: string[],
+  mode: DaemonMode,
+): Promise<number> {
+  const start = Date.now();
+  const result = await sandbox.runCommand({
+    cmd: "agent-browser",
+    args,
+    env: daemonEnv(mode),
+  });
+  const elapsed = Date.now() - start;
+  if (result.exitCode !== 0) {
+    const stderr = await result.stderr();
+    const stdout = await result.stdout();
+    throw new Error(
+      `agent-browser ${args.join(" ")} failed (exit ${result.exitCode}): ${stderr || stdout}`,
+    );
+  }
+  return elapsed;
+}
+
+interface ScenarioResult {
+  name: string;
+  description: string;
+  stats: Stats;
+  error?: string;
+}
+
+async function runScenario(
+  sandbox: SandboxInstance,
+  scenario: Scenario,
+  mode: DaemonMode,
+  iterations: number,
+  warmup: number,
+): Promise<ScenarioResult> {
+  try {
+    if (scenario.setup) {
+      for (const cmd of scenario.setup) {
+        await agentBrowser(sandbox, cmd, mode);
+      }
+    }
+
+    for (let w = 0; w < warmup; w++) {
+      for (const cmd of scenario.commands) {
+        await agentBrowser(sandbox, cmd, mode);
+      }
+    }
+
+    const samples: number[] = [];
+    for (let i = 0; i < iterations; i++) {
+      let totalMs = 0;
+      for (const cmd of scenario.commands) {
+        totalMs += await timedAgentBrowser(sandbox, cmd, mode);
+      }
+      samples.push(totalMs);
+    }
+
+    if (scenario.teardown) {
+      for (const cmd of scenario.teardown) {
+        await agentBrowser(sandbox, cmd, mode);
+      }
+    }
+
+    return {
+      name: scenario.name,
+      description: scenario.description,
+      stats: computeStats(samples),
+    };
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      name: scenario.name,
+      description: scenario.description,
+      stats: { avgMs: -1, stddevMs: -1, minMs: -1, maxMs: -1, p50Ms: -1, samples: [] },
+      error: message,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark phases
+// ---------------------------------------------------------------------------
+
+interface DaemonResults {
+  mode: DaemonMode;
+  label: string;
+  scenarios: ScenarioResult[];
+  metrics: DaemonMetrics;
+}
+
+async function benchmarkDaemon(
+  sandbox: SandboxInstance,
+  mode: DaemonMode,
+  label: string,
+): Promise<DaemonResults> {
+  console.log(`\n--- ${label} ---`);
+
+  // Measure sizes before launch
+  const binarySizeBytes = await getBinarySize(sandbox);
+  const distributionSizeBytes = await getDistributionSize(sandbox, mode);
+
+  // Cold start: time the first launch (daemon spawn + browser launch)
+  const coldStartBegin = Date.now();
+  await agentBrowser(sandbox, ["open", "about:blank"], mode);
+  const coldStartMs = Date.now() - coldStartBegin;
+  console.log(`  Cold start: ${coldStartMs}ms`);
+  console.log(`  Binary size: ${formatBytes(binarySizeBytes)}`);
+  console.log(`  Distribution size: ${formatBytes(distributionSizeBytes)}`);
+
+  // Run all scenarios
+  const results: ScenarioResult[] = [];
+  for (const scenario of scenarios) {
+    process.stdout.write(`  ${scenario.name} `);
+    const result = await runScenario(
+      sandbox,
+      scenario,
+      mode,
+      config.iterations,
+      config.warmup,
+    );
+    if (result.error) {
+      console.log(`FAILED: ${result.error.slice(0, 120)}`);
+    } else {
+      const dots = ".".repeat(Math.max(1, 30 - scenario.name.length));
+      const s = result.stats;
+      console.log(
+        `${dots} ${s.avgMs}ms avg +/-${s.stddevMs}ms (p50: ${s.p50Ms}ms, min: ${s.minMs}ms, max: ${s.maxMs}ms)`,
+      );
+    }
+    results.push(result);
+  }
+
+  // Collect system metrics after scenarios (daemon is still running)
+  const session = `bench-${mode}`;
+  const metrics = await collectDaemonMetrics(
+    sandbox,
+    session,
+    coldStartMs,
+    binarySizeBytes,
+    distributionSizeBytes,
+  );
+
+  // Also grab a full process snapshot for context
+  const psOutput = await shellSafe(
+    sandbox,
+    `ps aux --sort=-rss | head -20`,
+  );
+  console.log(`\n  Process snapshot (top by RSS):`);
+  for (const line of psOutput.split("\n").slice(0, 10)) {
+    console.log(`    ${line}`);
+  }
+
+  console.log(`\n  Daemon processes (${metrics.daemonProcesses.length}):`);
+  console.log(`    RSS: ${formatKb(metrics.daemonRssKb)} (peak: ${formatKb(metrics.daemonPeakRssKb)})`);
+  console.log(`    CPU time: ${metrics.daemonCpuTimeSec.toFixed(1)}s`);
+  for (const p of metrics.daemonProcesses) {
+    console.log(`      PID ${p.pid}: ${p.command} (RSS: ${formatKb(p.rssKb)}, CPU: ${p.cpuPercent}%)`);
+  }
+  console.log(`  Browser processes (${metrics.browserProcesses.length}):`);
+  console.log(`    RSS: ${formatKb(metrics.browserRssKb)}`);
+  for (const p of metrics.browserProcesses) {
+    console.log(`      PID ${p.pid}: ${p.command} (RSS: ${formatKb(p.rssKb)}, CPU: ${p.cpuPercent}%)`);
+  }
+
+  await agentBrowser(sandbox, ["close"], mode);
+  console.log(`  Browser closed.`);
+
+  return { mode, label, scenarios: results, metrics };
+}
+
+// ---------------------------------------------------------------------------
+// Install helpers
+// ---------------------------------------------------------------------------
+
+async function installChromiumDeps(sandbox: SandboxInstance) {
+  console.log("Installing Chromium system dependencies...");
+  await shell(
+    sandbox,
+    `sudo dnf clean all 2>&1 && sudo dnf install -y --skip-broken ${CHROMIUM_SYSTEM_DEPS.join(" ")} 2>&1 && sudo ldconfig 2>&1`,
+  );
+}
+
+async function installNodeDaemon(sandbox: SandboxInstance) {
+  console.log("Installing agent-browser from npm (Node.js daemon)...");
+  await run(sandbox, "npm", ["install", "-g", "agent-browser"]);
+  await run(sandbox, "npx", ["agent-browser", "install"]);
+  const version = await shell(sandbox, "agent-browser --version 2>&1 || true");
+  console.log(`  version: ${version.trim()}`);
+}
+
+async function installNativeDaemon(sandbox: SandboxInstance, branch: string) {
+  console.log(`\nBuilding native daemon from ${branch}...`);
+
+  console.log("  Installing build tools and Rust toolchain...");
+  const rustStart = Date.now();
+  await shell(
+    sandbox,
+    "sudo dnf install -y gcc gcc-c++ make perl-core openssl-devel 2>&1",
+  );
+  await shell(
+    sandbox,
+    "curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y 2>&1",
+  );
+  console.log(`  Rust + build tools installed (${Math.round((Date.now() - rustStart) / 1000)}s)`);
+
+  console.log(`  Cloning repo (branch: ${branch})...`);
+  const cloneStart = Date.now();
+  await shell(
+    sandbox,
+    `git clone --depth 1 --branch ${branch} ${REPO_URL} /tmp/agent-browser 2>&1`,
+  );
+  console.log(`  Cloned (${Math.round((Date.now() - cloneStart) / 1000)}s)`);
+
+  console.log("  Building release binary (cargo build --release)...");
+  const buildStart = Date.now();
+  await shell(
+    sandbox,
+    "source $HOME/.cargo/env && cd /tmp/agent-browser/cli && cargo build --release 2>&1",
+  );
+  console.log(`  Built (${Math.round((Date.now() - buildStart) / 1000)}s)`);
+
+  const npmBinPath = (await shell(sandbox, "which agent-browser")).trim();
+  console.log(`  Replacing ${npmBinPath} with native build...`);
+  await shell(
+    sandbox,
+    `sudo cp /tmp/agent-browser/cli/target/release/agent-browser ${npmBinPath}`,
+  );
+
+  const version = await shell(sandbox, "agent-browser --version 2>&1 || true");
+  console.log(`  version: ${version.trim()}`);
+}
+
+// ---------------------------------------------------------------------------
+// Output
+// ---------------------------------------------------------------------------
+
+function printResults(node: DaemonResults, native: DaemonResults) {
+  console.log("\n\n========== COMMAND LATENCY ==========\n");
+
+  const header =
+    "Scenario".padEnd(20) + "| Node avg +/-sd  | Rust avg +/-sd  | Speedup";
+  const sep = "-".repeat(20) + "|-----------------|-----------------|--------";
+  console.log(header);
+  console.log(sep);
+
+  for (let i = 0; i < node.scenarios.length; i++) {
+    const n = node.scenarios[i];
+    const r = native.scenarios[i];
+    const name = n.name.padEnd(20);
+
+    if (n.error || r.error) {
+      const nodeVal = n.error ? "FAILED".padEnd(15) : `${n.stats.avgMs}ms`.padEnd(15);
+      const rustVal = r.error ? "FAILED".padEnd(15) : `${r.stats.avgMs}ms`.padEnd(15);
+      console.log(`${name}| ${nodeVal} | ${rustVal} |    --`);
+      continue;
+    }
+
+    const nodeVal = `${n.stats.avgMs} +/-${n.stats.stddevMs}ms`.padEnd(15);
+    const rustVal = `${r.stats.avgMs} +/-${r.stats.stddevMs}ms`.padEnd(15);
+    const speedup =
+      r.stats.avgMs > 0
+        ? (n.stats.avgMs / r.stats.avgMs).toFixed(2) + "x"
+        : "--";
+    console.log(`${name}| ${nodeVal} | ${rustVal} | ${speedup.padStart(6)}`);
+  }
+
+  console.log("\n\n========== SYSTEM METRICS ==========\n");
+
+  const nm = node.metrics;
+  const rm = native.metrics;
+
+  function ratio(a: number, b: number): string {
+    if (b <= 0) return "--";
+    return (a / b).toFixed(2) + "x";
+  }
+
+  const metricRows: [string, string, string, string][] = [
+    [
+      "Cold start",
+      `${nm.coldStartMs}ms`,
+      `${rm.coldStartMs}ms`,
+      ratio(nm.coldStartMs, rm.coldStartMs),
+    ],
+    [
+      "Binary size",
+      formatBytes(nm.binarySizeBytes),
+      formatBytes(rm.binarySizeBytes),
+      ratio(nm.binarySizeBytes, rm.binarySizeBytes),
+    ],
+    [
+      "Distribution size",
+      formatBytes(nm.distributionSizeBytes),
+      formatBytes(rm.distributionSizeBytes),
+      ratio(nm.distributionSizeBytes, rm.distributionSizeBytes),
+    ],
+    [
+      "Daemon RSS",
+      formatKb(nm.daemonRssKb),
+      formatKb(rm.daemonRssKb),
+      ratio(nm.daemonRssKb, rm.daemonRssKb),
+    ],
+    [
+      "Daemon peak RSS",
+      formatKb(nm.daemonPeakRssKb),
+      formatKb(rm.daemonPeakRssKb),
+      ratio(nm.daemonPeakRssKb, rm.daemonPeakRssKb),
+    ],
+    [
+      "Browser RSS",
+      formatKb(nm.browserRssKb),
+      formatKb(rm.browserRssKb),
+      ratio(nm.browserRssKb, rm.browserRssKb),
+    ],
+    [
+      "Daemon CPU time",
+      `${nm.daemonCpuTimeSec.toFixed(1)}s`,
+      `${rm.daemonCpuTimeSec.toFixed(1)}s`,
+      ratio(nm.daemonCpuTimeSec, rm.daemonCpuTimeSec),
+    ],
+    [
+      "Daemon processes",
+      String(nm.daemonProcesses.length),
+      String(rm.daemonProcesses.length),
+      "--",
+    ],
+    [
+      "Browser processes",
+      String(nm.browserProcesses.length),
+      String(rm.browserProcesses.length),
+      "--",
+    ],
+  ];
+
+  const mHeader =
+    "Metric".padEnd(20) + "| Node".padEnd(14) + "| Rust".padEnd(14) + "| Ratio";
+  const mSep = "-".repeat(20) + "|" + "-".repeat(13) + "|" + "-".repeat(13) + "|--------";
+  console.log(mHeader);
+  console.log(mSep);
+  for (const [metric, nodeVal, rustVal, ratio] of metricRows) {
+    console.log(
+      `${metric.padEnd(20)}| ${nodeVal.padEnd(12)}| ${rustVal.padEnd(12)}| ${ratio}`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  console.log("agent-browser Daemon Benchmark (Node.js vs Rust Native)");
+  console.log(`Branch: ${config.branch}`);
+  console.log(`Iterations: ${config.iterations} (+ ${config.warmup} warmup)`);
+  console.log(`vCPUs: ${config.vcpus}\n`);
+
+  console.log("Creating sandbox...");
+  const sandbox = await Sandbox.create({
+    ...credentials,
+    timeout: TIMEOUT_MS,
+    runtime: "node22",
+    networkPolicy: "allow-all" as const,
+    resources: { vcpus: config.vcpus },
+  });
+  console.log(`Sandbox: ${sandbox.sandboxId}`);
+
+  try {
+    await installChromiumDeps(sandbox);
+
+    // Phase 1: Node.js daemon (from published npm package)
+    await installNodeDaemon(sandbox);
+    const nodeResults = await benchmarkDaemon(
+      sandbox,
+      "node",
+      "Node.js Daemon (npm)",
+    );
+
+    // Phase 2: Rust native daemon (built from branch)
+    await installNativeDaemon(sandbox, config.branch);
+    const nativeResults = await benchmarkDaemon(
+      sandbox,
+      "native",
+      `Rust Native Daemon (${config.branch})`,
+    );
+
+    printResults(nodeResults, nativeResults);
+
+    if (config.json) {
+      const output = {
+        timestamp: new Date().toISOString(),
+        branch: config.branch,
+        vcpus: config.vcpus,
+        iterations: config.iterations,
+        warmup: config.warmup,
+        node: {
+          scenarios: nodeResults.scenarios.map((s) => ({
+            name: s.name,
+            description: s.description,
+            ...s.stats,
+            error: s.error,
+          })),
+          metrics: nodeResults.metrics,
+        },
+        native: {
+          scenarios: nativeResults.scenarios.map((s) => ({
+            name: s.name,
+            description: s.description,
+            ...s.stats,
+            error: s.error,
+          })),
+          metrics: nativeResults.metrics,
+        },
+      };
+      writeFileSync("results.json", JSON.stringify(output, null, 2));
+      console.log("\nResults written to results.json");
+    }
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`\nFatal error: ${message}`);
+    process.exit(1);
+  } finally {
+    try {
+      await sandbox.stop();
+      console.log("\nSandbox stopped.");
+    } catch {
+      console.warn("Warning: failed to stop sandbox.");
+    }
+  }
+}
+
+main();

benchmarks/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "agent-browser-benchmarks",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "bench": "tsx bench.ts"
+  },
+  "dependencies": {
+    "@vercel/sandbox": "^1.8.0",
+    "tsx": "^4.19.0"
+  }
+}

benchmarks/pnpm-lock.yaml

@@ -0,0 +1,472 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      '@vercel/sandbox':
+        specifier: ^1.8.0
+        version: 1.8.1
+      tsx:
+        specifier: ^4.19.0
+        version: 4.21.0
+
+packages:
+
+  '@esbuild/aix-ppc64@0.27.4':
+    resolution: {integrity: sha512-cQPwL2mp2nSmHHJlCyoXgHGhbEPMrEEU5xhkcy3Hs/O7nGZqEpZ2sUtLaL9MORLtDfRvVl2/3PAuEkYZH0Ty8Q==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/android-arm64@0.27.4':
+    resolution: {integrity: sha512-gdLscB7v75wRfu7QSm/zg6Rx29VLdy9eTr2t44sfTW7CxwAtQghZ4ZnqHk3/ogz7xao0QAgrkradbBzcqFPasw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm@0.27.4':
+    resolution: {integrity: sha512-X9bUgvxiC8CHAGKYufLIHGXPJWnr0OCdR0anD2e21vdvgCI8lIfqFbnoeOz7lBjdrAGUhqLZLcQo6MLhTO2DKQ==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-x64@0.27.4':
+    resolution: {integrity: sha512-PzPFnBNVF292sfpfhiyiXCGSn9HZg5BcAz+ivBuSsl6Rk4ga1oEXAamhOXRFyMcjwr2DVtm40G65N3GLeH1Lvw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/darwin-arm64@0.27.4':
+    resolution: {integrity: sha512-b7xaGIwdJlht8ZFCvMkpDN6uiSmnxxK56N2GDTMYPr2/gzvfdQN8rTfBsvVKmIVY/X7EM+/hJKEIbbHs9oA4tQ==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.27.4':
+    resolution: {integrity: sha512-sR+OiKLwd15nmCdqpXMnuJ9W2kpy0KigzqScqHI3Hqwr7IXxBp3Yva+yJwoqh7rE8V77tdoheRYataNKL4QrPw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/freebsd-arm64@0.27.4':
+    resolution: {integrity: sha512-jnfpKe+p79tCnm4GVav68A7tUFeKQwQyLgESwEAUzyxk/TJr4QdGog9sqWNcUbr/bZt/O/HXouspuQDd9JxFSw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.27.4':
+    resolution: {integrity: sha512-2kb4ceA/CpfUrIcTUl1wrP/9ad9Atrp5J94Lq69w7UwOMolPIGrfLSvAKJp0RTvkPPyn6CIWrNy13kyLikZRZQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/linux-arm64@0.27.4':
+    resolution: {integrity: sha512-7nQOttdzVGth1iz57kxg9uCz57dxQLHWxopL6mYuYthohPKEK0vU0C3O21CcBK6KDlkYVcnDXY099HcCDXd9dA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.27.4':
+    resolution: {integrity: sha512-aBYgcIxX/wd5n2ys0yESGeYMGF+pv6g0DhZr3G1ZG4jMfruU9Tl1i2Z+Wnj9/KjGz1lTLCcorqE2viePZqj4Eg==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.27.4':
+    resolution: {integrity: sha512-oPtixtAIzgvzYcKBQM/qZ3R+9TEUd1aNJQu0HhGyqtx6oS7qTpvjheIWBbes4+qu1bNlo2V4cbkISr8q6gRBFA==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.27.4':
+    resolution: {integrity: sha512-8mL/vh8qeCoRcFH2nM8wm5uJP+ZcVYGGayMavi8GmRJjuI3g1v6Z7Ni0JJKAJW+m0EtUuARb6Lmp4hMjzCBWzA==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.27.4':
+    resolution: {integrity: sha512-1RdrWFFiiLIW7LQq9Q2NES+HiD4NyT8Itj9AUeCl0IVCA459WnPhREKgwrpaIfTOe+/2rdntisegiPWn/r/aAw==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.27.4':
+    resolution: {integrity: sha512-tLCwNG47l3sd9lpfyx9LAGEGItCUeRCWeAx6x2Jmbav65nAwoPXfewtAdtbtit/pJFLUWOhpv0FpS6GQAmPrHA==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.27.4':
+    resolution: {integrity: sha512-BnASypppbUWyqjd1KIpU4AUBiIhVr6YlHx/cnPgqEkNoVOhHg+YiSVxM1RLfiy4t9cAulbRGTNCKOcqHrEQLIw==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.27.4':
+    resolution: {integrity: sha512-+eUqgb/Z7vxVLezG8bVB9SfBie89gMueS+I0xYh2tJdw3vqA/0ImZJ2ROeWwVJN59ihBeZ7Tu92dF/5dy5FttA==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.27.4':
+    resolution: {integrity: sha512-S5qOXrKV8BQEzJPVxAwnryi2+Iq5pB40gTEIT69BQONqR7JH1EPIcQ/Uiv9mCnn05jff9umq/5nqzxlqTOg9NA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/netbsd-arm64@0.27.4':
+    resolution: {integrity: sha512-xHT8X4sb0GS8qTqiwzHqpY00C95DPAq7nAwX35Ie/s+LO9830hrMd3oX0ZMKLvy7vsonee73x0lmcdOVXFzd6Q==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-x64@0.27.4':
+    resolution: {integrity: sha512-RugOvOdXfdyi5Tyv40kgQnI0byv66BFgAqjdgtAKqHoZTbTF2QqfQrFwa7cHEORJf6X2ht+l9ABLMP0dnKYsgg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/openbsd-arm64@0.27.4':
+    resolution: {integrity: sha512-2MyL3IAaTX+1/qP0O1SwskwcwCoOI4kV2IBX1xYnDDqthmq5ArrW94qSIKCAuRraMgPOmG0RDTA74mzYNQA9ow==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-x64@0.27.4':
+    resolution: {integrity: sha512-u8fg/jQ5aQDfsnIV6+KwLOf1CmJnfu1ShpwqdwC0uA7ZPwFws55Ngc12vBdeUdnuWoQYx/SOQLGDcdlfXhYmXQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openharmony-arm64@0.27.4':
+    resolution: {integrity: sha512-JkTZrl6VbyO8lDQO3yv26nNr2RM2yZzNrNHEsj9bm6dOwwu9OYN28CjzZkH57bh4w0I2F7IodpQvUAEd1mbWXg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@esbuild/sunos-x64@0.27.4':
+    resolution: {integrity: sha512-/gOzgaewZJfeJTlsWhvUEmUG4tWEY2Spp5M20INYRg2ZKl9QPO3QEEgPeRtLjEWSW8FilRNacPOg8R1uaYkA6g==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/win32-arm64@0.27.4':
+    resolution: {integrity: sha512-Z9SExBg2y32smoDQdf1HRwHRt6vAHLXcxD2uGgO/v2jK7Y718Ix4ndsbNMU/+1Qiem9OiOdaqitioZwxivhXYg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.27.4':
+    resolution: {integrity: sha512-DAyGLS0Jz5G5iixEbMHi5KdiApqHBWMGzTtMiJ72ZOLhbu/bzxgAe8Ue8CTS3n3HbIUHQz/L51yMdGMeoxXNJw==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.27.4':
+    resolution: {integrity: sha512-+knoa0BDoeXgkNvvV1vvbZX4+hizelrkwmGJBdT17t8FNPwG2lKemmuMZlmaNQ3ws3DKKCxpb4zRZEIp3UxFCg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
+  '@vercel/oidc@3.2.0':
+    resolution: {integrity: sha512-UycprH3T6n3jH0k44NHMa7pnFHGu/N05MjojYr+Mc6I7obkoLIJujSWwin1pCvdy/eOxrI/l3uDLQsmcrOb4ug==}
+    engines: {node: '>= 20'}
+
+  '@vercel/sandbox@1.8.1':
+    resolution: {integrity: sha512-txohjI20aMxZiAzBL/KJi5EqTYsesBdOyIOtpTIyebPLTqYtDYfNhQ4OeYiUcPMUo0XBt8gSet/rIdLQEjj3/A==}
+
+  async-retry@1.3.3:
+    resolution: {integrity: sha512-wfr/jstw9xNi/0teMHrRW7dsz3Lt5ARhYNZ2ewpadnhaIp5mbALhOAP+EAdsC7t4Z6wqsDVv9+W6gm1Dk9mEyw==}
+
+  b4a@1.8.0:
+    resolution: {integrity: sha512-qRuSmNSkGQaHwNbM7J78Wwy+ghLEYF1zNrSeMxj4Kgw6y33O3mXcQ6Ie9fRvfU/YnxWkOchPXbaLb73TkIsfdg==}
+    peerDependencies:
+      react-native-b4a: '*'
+    peerDependenciesMeta:
+      react-native-b4a:
+        optional: true
+
+  bare-events@2.8.2:
+    resolution: {integrity: sha512-riJjyv1/mHLIPX4RwiK+oW9/4c3TEUeORHKefKAKnZ5kyslbN+HXowtbaVEqt4IMUB7OXlfixcs6gsFeo/jhiQ==}
+    peerDependencies:
+      bare-abort-controller: '*'
+    peerDependenciesMeta:
+      bare-abort-controller:
+        optional: true
+
+  esbuild@0.27.4:
+    resolution: {integrity: sha512-Rq4vbHnYkK5fws5NF7MYTU68FPRE1ajX7heQ/8QXXWqNgqqJ/GkmmyxIzUnf2Sr/bakf8l54716CcMGHYhMrrQ==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  events-universal@1.0.1:
+    resolution: {integrity: sha512-LUd5euvbMLpwOF8m6ivPCbhQeSiYVNb8Vs0fQ8QjXo0JTkEHpz8pxdQf0gStltaPpw0Cca8b39KxvK9cfKRiAw==}
+
+  fast-fifo@1.3.2:
+    resolution: {integrity: sha512-/d9sfos4yxzpwkDkuN7k2SqFKtYNmCTzgfEpz82x34IM9/zc8KGxQoXg1liNC/izpRM/MBdt44Nmx41ZWqk+FQ==}
+
+  fsevents@2.3.3:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  get-tsconfig@4.13.6:
+    resolution: {integrity: sha512-shZT/QMiSHc/YBLxxOkMtgSid5HFoauqCE3/exfsEcwg1WkeqjG+V40yBbBrsD+jW2HDXcs28xOfcbm2jI8Ddw==}
+
+  jsonlines@0.1.1:
+    resolution: {integrity: sha512-ekDrAGso79Cvf+dtm+mL8OBI2bmAOt3gssYs833De/C9NmIpWDWyUO4zPgB5x2/OhY366dkhgfPMYfwZF7yOZA==}
+
+  ms@2.1.3:
+    resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
+
+  os-paths@4.4.0:
+    resolution: {integrity: sha512-wrAwOeXp1RRMFfQY8Sy7VaGVmPocaLwSFOYCGKSyo8qmJ+/yaafCl5BCA1IQZWqFSRBrKDYFeR9d/VyQzfH/jg==}
+    engines: {node: '>= 6.0'}
+
+  picocolors@1.1.1:
+    resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
+
+  resolve-pkg-maps@1.0.0:
+    resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}
+
+  retry@0.13.1:
+    resolution: {integrity: sha512-XQBQ3I8W1Cge0Seh+6gjj03LbmRFWuoszgK9ooCpwYIrhhoO80pfq4cUkU5DkknwfOfFteRwlZ56PYOGYyFWdg==}
+    engines: {node: '>= 4'}
+
+  streamx@2.23.0:
+    resolution: {integrity: sha512-kn+e44esVfn2Fa/O0CPFcex27fjIL6MkVae0Mm6q+E6f0hWv578YCERbv+4m02cjxvDsPKLnmxral/rR6lBMAg==}
+
+  tar-stream@3.1.7:
+    resolution: {integrity: sha512-qJj60CXt7IU1Ffyc3NJMjh6EkuCFej46zUqJ4J7pqYlThyd9bO0XBTmcOIhSzZJVWfsLks0+nle/j538YAW9RQ==}
+
+  text-decoder@1.2.7:
+    resolution: {integrity: sha512-vlLytXkeP4xvEq2otHeJfSQIRyWxo/oZGEbXrtEEF9Hnmrdly59sUbzZ/QgyWuLYHctCHxFF4tRQZNQ9k60ExQ==}
+
+  tsx@4.21.0:
+    resolution: {integrity: sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==}
+    engines: {node: '>=18.0.0'}
+    hasBin: true
+
+  undici@7.24.1:
+    resolution: {integrity: sha512-5xoBibbmnjlcR3jdqtY2Lnx7WbrD/tHlT01TmvqZUFVc9Q1w4+j5hbnapTqbcXITMH1ovjq/W7BkqBilHiVAaA==}
+    engines: {node: '>=20.18.1'}
+
+  xdg-app-paths@5.1.0:
+    resolution: {integrity: sha512-RAQ3WkPf4KTU1A8RtFx3gWywzVKe00tfOPFfl2NDGqbIFENQO4kqAJp7mhQjNj/33W5x5hiWWUdyfPq/5SU3QA==}
+    engines: {node: '>=6'}
+
+  xdg-portable@7.3.0:
+    resolution: {integrity: sha512-sqMMuL1rc0FmMBOzCpd0yuy9trqF2yTTVe+E9ogwCSWQCdDEtQUwrZPT6AxqtsFGRNxycgncbP/xmOOSPw5ZUw==}
+    engines: {node: '>= 6.0'}
+
+  zod@3.24.4:
+    resolution: {integrity: sha512-OdqJE9UDRPwWsrHjLN2F8bPxvwJBK22EHLWtanu0LSYr5YqzsaaW3RMgmjwr8Rypg5k+meEJdSPXJZXE/yqOMg==}
+
+snapshots:
+
+  '@esbuild/aix-ppc64@0.27.4':
+    optional: true
+
+  '@esbuild/android-arm64@0.27.4':
+    optional: true
+
+  '@esbuild/android-arm@0.27.4':
+    optional: true
+
+  '@esbuild/android-x64@0.27.4':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.27.4':
+    optional: true
+
+  '@esbuild/darwin-x64@0.27.4':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.27.4':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.27.4':
+    optional: true
+
+  '@esbuild/linux-arm64@0.27.4':
+    optional: true
+
+  '@esbuild/linux-arm@0.27.4':
+    optional: true
+
+  '@esbuild/linux-ia32@0.27.4':
+    optional: true
+
+  '@esbuild/linux-loong64@0.27.4':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.27.4':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.27.4':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.27.4':
+    optional: true
+
+  '@esbuild/linux-s390x@0.27.4':
+    optional: true
+
+  '@esbuild/linux-x64@0.27.4':
+    optional: true
+
+  '@esbuild/netbsd-arm64@0.27.4':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.27.4':
+    optional: true
+
+  '@esbuild/openbsd-arm64@0.27.4':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.27.4':
+    optional: true
+
+  '@esbuild/openharmony-arm64@0.27.4':
+    optional: true
+
+  '@esbuild/sunos-x64@0.27.4':
+    optional: true
+
+  '@esbuild/win32-arm64@0.27.4':
+    optional: true
+
+  '@esbuild/win32-ia32@0.27.4':
+    optional: true
+
+  '@esbuild/win32-x64@0.27.4':
+    optional: true
+
+  '@vercel/oidc@3.2.0': {}
+
+  '@vercel/sandbox@1.8.1':
+    dependencies:
+      '@vercel/oidc': 3.2.0
+      async-retry: 1.3.3
+      jsonlines: 0.1.1
+      ms: 2.1.3
+      picocolors: 1.1.1
+      tar-stream: 3.1.7
+      undici: 7.24.1
+      xdg-app-paths: 5.1.0
+      zod: 3.24.4
+    transitivePeerDependencies:
+      - bare-abort-controller
+      - react-native-b4a
+
+  async-retry@1.3.3:
+    dependencies:
+      retry: 0.13.1
+
+  b4a@1.8.0: {}
+
+  bare-events@2.8.2: {}
+
+  esbuild@0.27.4:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.27.4
+      '@esbuild/android-arm': 0.27.4
+      '@esbuild/android-arm64': 0.27.4
+      '@esbuild/android-x64': 0.27.4
+      '@esbuild/darwin-arm64': 0.27.4
+      '@esbuild/darwin-x64': 0.27.4
+      '@esbuild/freebsd-arm64': 0.27.4
+      '@esbuild/freebsd-x64': 0.27.4
+      '@esbuild/linux-arm': 0.27.4
+      '@esbuild/linux-arm64': 0.27.4
+      '@esbuild/linux-ia32': 0.27.4
+      '@esbuild/linux-loong64': 0.27.4
+      '@esbuild/linux-mips64el': 0.27.4
+      '@esbuild/linux-ppc64': 0.27.4
+      '@esbuild/linux-riscv64': 0.27.4
+      '@esbuild/linux-s390x': 0.27.4
+      '@esbuild/linux-x64': 0.27.4
+      '@esbuild/netbsd-arm64': 0.27.4
+      '@esbuild/netbsd-x64': 0.27.4
+      '@esbuild/openbsd-arm64': 0.27.4
+      '@esbuild/openbsd-x64': 0.27.4
+      '@esbuild/openharmony-arm64': 0.27.4
+      '@esbuild/sunos-x64': 0.27.4
+      '@esbuild/win32-arm64': 0.27.4
+      '@esbuild/win32-ia32': 0.27.4
+      '@esbuild/win32-x64': 0.27.4
+
+  events-universal@1.0.1:
+    dependencies:
+      bare-events: 2.8.2
+    transitivePeerDependencies:
+      - bare-abort-controller
+
+  fast-fifo@1.3.2: {}
+
+  fsevents@2.3.3:
+    optional: true
+
+  get-tsconfig@4.13.6:
+    dependencies:
+      resolve-pkg-maps: 1.0.0
+
+  jsonlines@0.1.1: {}
+
+  ms@2.1.3: {}
+
+  os-paths@4.4.0: {}
+
+  picocolors@1.1.1: {}
+
+  resolve-pkg-maps@1.0.0: {}
+
+  retry@0.13.1: {}
+
+  streamx@2.23.0:
+    dependencies:
+      events-universal: 1.0.1
+      fast-fifo: 1.3.2
+      text-decoder: 1.2.7
+    transitivePeerDependencies:
+      - bare-abort-controller
+      - react-native-b4a
+
+  tar-stream@3.1.7:
+    dependencies:
+      b4a: 1.8.0
+      fast-fifo: 1.3.2
+      streamx: 2.23.0
+    transitivePeerDependencies:
+      - bare-abort-controller
+      - react-native-b4a
+
+  text-decoder@1.2.7:
+    dependencies:
+      b4a: 1.8.0
+    transitivePeerDependencies:
+      - react-native-b4a
+
+  tsx@4.21.0:
+    dependencies:
+      esbuild: 0.27.4
+      get-tsconfig: 4.13.6
+    optionalDependencies:
+      fsevents: 2.3.3
+
+  undici@7.24.1: {}
+
+  xdg-app-paths@5.1.0:
+    dependencies:
+      xdg-portable: 7.3.0
+
+  xdg-portable@7.3.0:
+    dependencies:
+      os-paths: 4.4.0
+
+  zod@3.24.4: {}

benchmarks/scenarios.ts

@@ -0,0 +1,105 @@
+/**
+ * Benchmark scenarios for comparing Node.js daemon vs Rust native daemon.
+ *
+ * Each scenario defines CLI commands run via `sandbox.runCommand("agent-browser", args)`.
+ * Setup/teardown commands run once and are not timed.
+ * The `commands` array is timed over N iterations.
+ */
+
+export interface Scenario {
+  name: string;
+  description: string;
+  setup?: string[][];
+  commands: string[][];
+  teardown?: string[][];
+}
+
+const FORM_HTML = [
+  "<html><head><title>Bench</title></head><body>",
+  "<h1>Benchmark Page</h1>",
+  "<input id='name' type='text' placeholder='Name'>",
+  "<input id='email' type='email' placeholder='Email'>",
+  "<select id='color'><option value='red'>Red</option><option value='blue'>Blue</option></select>",
+  "<input id='agree' type='checkbox'>",
+  "<textarea id='bio' placeholder='Bio'></textarea>",
+  "<button id='submit'>Submit</button>",
+  "<p id='status'>Ready</p>",
+  "<a id='link' href='javascript:void(0)' onclick=\"document.getElementById('status').textContent='Clicked'\">Click me</a>",
+  "<ul>",
+  ...Array.from({ length: 20 }, (_, i) => `<li class='item'>Item ${i + 1}</li>`),
+  "</ul>",
+  "</body></html>",
+].join("");
+
+const INJECT_FORM_SCRIPT = `document.open(); document.write(${JSON.stringify(FORM_HTML)}); document.close(); 'ok'`;
+
+const SETUP_PAGE: string[][] = [
+  ["open", "about:blank"],
+  ["eval", INJECT_FORM_SCRIPT],
+];
+
+export const scenarios: Scenario[] = [
+  {
+    name: "navigate",
+    description: "Page navigation (about:blank round-trip)",
+    commands: [["open", "about:blank"]],
+  },
+  {
+    name: "snapshot",
+    description: "DOM snapshot (accessibility tree)",
+    setup: SETUP_PAGE,
+    commands: [["snapshot"]],
+  },
+  {
+    name: "screenshot",
+    description: "Screenshot capture",
+    setup: SETUP_PAGE,
+    commands: [["screenshot"]],
+  },
+  {
+    name: "evaluate",
+    description: "JavaScript evaluation",
+    setup: SETUP_PAGE,
+    commands: [
+      [
+        "eval",
+        "document.title + ' ' + document.querySelectorAll('li').length",
+      ],
+    ],
+  },
+  {
+    name: "click",
+    description: "Element click interaction",
+    setup: SETUP_PAGE,
+    commands: [["click", "#link"]],
+  },
+  {
+    name: "fill",
+    description: "Form field fill",
+    setup: SETUP_PAGE,
+    commands: [["fill", "#name", "Benchmark User"]],
+  },
+  {
+    name: "agent-loop",
+    description: "AI agent loop: snapshot -> click -> snapshot (typical agent cycle)",
+    setup: SETUP_PAGE,
+    commands: [["snapshot"], ["click", "#link"], ["snapshot"]],
+  },
+  {
+    name: "full-workflow",
+    description:
+      "Realistic workflow: navigate, inject form, snapshot, click, fill, evaluate, screenshot",
+    commands: [
+      ["open", "about:blank"],
+      ["eval", INJECT_FORM_SCRIPT],
+      ["snapshot"],
+      ["click", "#link"],
+      ["fill", "#name", "Agent User"],
+      [
+        "eval",
+        "document.getElementById('name').value",
+      ],
+      ["screenshot"],
+    ],
+  },
+];

benchmarks/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "declaration": true
+  },
+  "include": ["*.ts"]
+}

bin/agent-browser.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+/**
+ * Cross-platform CLI wrapper for agent-browser
+ * 
+ * This wrapper enables npx support on Windows where shell scripts don't work.
+ * For global installs, postinstall.js patches the shims to invoke the native
+ * binary directly (zero overhead).
+ */
+
+import { spawn, execSync } from 'child_process';
+import { existsSync, accessSync, chmodSync, constants } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { platform, arch } from 'os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Detect if the system uses musl libc (e.g. Alpine Linux)
+function isMusl() {
+  if (platform() !== 'linux') return false;
+  try {
+    const result = execSync('ldd --version 2>&1 || true', { encoding: 'utf8' });
+    return result.toLowerCase().includes('musl');
+  } catch {
+    return existsSync('/lib/ld-musl-x86_64.so.1') || existsSync('/lib/ld-musl-aarch64.so.1');
+  }
+}
+
+// Map Node.js platform/arch to binary naming convention
+function getBinaryName() {
+  const os = platform();
+  const cpuArch = arch();
+
+  let osKey;
+  switch (os) {
+    case 'darwin':
+      osKey = 'darwin';
+      break;
+    case 'linux':
+      osKey = isMusl() ? 'linux-musl' : 'linux';
+      break;
+    case 'win32':
+      osKey = 'win32';
+      break;
+    default:
+      return null;
+  }
+
+  let archKey;
+  switch (cpuArch) {
+    case 'x64':
+    case 'x86_64':
+      archKey = 'x64';
+      break;
+    case 'arm64':
+    case 'aarch64':
+      archKey = 'arm64';
+      break;
+    default:
+      return null;
+  }
+
+  const ext = os === 'win32' ? '.exe' : '';
+  return `agent-browser-${osKey}-${archKey}${ext}`;
+}
+
+function main() {
+  const binaryName = getBinaryName();
+
+  if (!binaryName) {
+    console.error(`Error: Unsupported platform: ${platform()}-${arch()}`);
+    process.exit(1);
+  }
+
+  const binaryPath = join(__dirname, binaryName);
+
+  if (!existsSync(binaryPath)) {
+    console.error(`Error: No binary found for ${platform()}-${arch()}`);
+    console.error(`Expected: ${binaryPath}`);
+    console.error('');
+    console.error('Run "npm run build:native" to build for your platform,');
+    console.error('or reinstall the package to trigger the postinstall download.');
+    process.exit(1);
+  }
+
+  // Ensure binary is executable (fixes EACCES on macOS/Linux when postinstall didn't run,
+  // e.g., when using bun which blocks lifecycle scripts by default)
+  if (platform() !== 'win32') {
+    try {
+      accessSync(binaryPath, constants.X_OK);
+    } catch {
+      // Binary exists but isn't executable - fix it
+      try {
+        chmodSync(binaryPath, 0o755);
+      } catch (chmodErr) {
+        console.error(`Error: Cannot make binary executable: ${chmodErr.message}`);
+        console.error('Try running: chmod +x ' + binaryPath);
+        process.exit(1);
+      }
+    }
+  }
+
+  // Spawn the native binary with inherited stdio
+  const child = spawn(binaryPath, process.argv.slice(2), {
+    stdio: 'inherit',
+    windowsHide: false,
+  });
+
+  child.on('error', (err) => {
+    console.error(`Error executing binary: ${err.message}`);
+    process.exit(1);
+  });
+
+  child.on('close', (code) => {
+    process.exit(code ?? 0);
+  });
+}
+
+main();

cli/Cargo.toml

@@ -0,0 +1,61 @@
+[package]
+name = "agent-browser"
+version = "0.31.1"
+edition = "2021"
+description = "Fast browser automation CLI for AI agents"
+license = "Apache-2.0"
+repository = "https://github.com/vercel-labs/agent-browser"
+homepage = "https://agent-browser.dev"
+readme = "../README.md"
+keywords = ["browser", "automation", "ai", "cdp", "chrome"]
+categories = ["command-line-utilities", "web-programming"]
+
+[dependencies]
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+dirs = "5.0"
+base64 = "0.22"
+getrandom = "0.2"
+tokio = { version = "1", features = ["rt-multi-thread", "macros", "net", "io-util", "time", "sync", "signal", "process"] }
+tokio-tungstenite = { version = "0.24", features = ["rustls-tls-webpki-roots"] }
+futures-util = "0.3"
+url = "2"
+uuid = { version = "1", features = ["v4"] }
+image = "0.25"
+reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls-webpki-roots", "stream"] }
+sha2 = "0.10"
+aes-gcm = "0.10"
+async-trait = "0.1"
+socket2 = "0.6"
+similar = "2"
+zip = { version = "8.2.0", default-features = false, features = ["deflate"] }
+time = { version = "0.3", features = ["formatting"] }
+hmac = "0.12"
+hex = "0.4"
+chrono = "0.4"
+urlencoding = "2"
+rust-embed = "8"
+
+[target.'cfg(unix)'.dependencies]
+libc = "0.2"
+
+[target.'cfg(windows)'.dependencies]
+windows-sys = { version = "0.52", features = ["Win32_System_Threading", "Win32_Foundation"] }
+
+[dev-dependencies]
+tempfile = "3"
+
+[build-dependencies]
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+
+[profile.release]
+opt-level = 3
+lto = true
+codegen-units = 1
+strip = true
+
+[profile.ci]
+inherits = "release"
+lto = "thin"
+codegen-units = 16

cli/build.rs

@@ -0,0 +1,498 @@
+use std::collections::HashSet;
+use std::env;
+use std::fs;
+use std::path::Path;
+
+/// Ensure `packages/dashboard/out/` exists so `rust-embed` doesn't fail during
+/// Rust-only dev builds where the dashboard hasn't been built. The placeholder
+/// `index.html` is only written when the directory is completely absent.
+fn ensure_dashboard_dir() {
+    let dashboard_out = Path::new("../packages/dashboard/out");
+    println!("cargo:rerun-if-changed=../packages/dashboard/out");
+    if !dashboard_out.join("index.html").exists() {
+        let _ = fs::create_dir_all(dashboard_out);
+        let _ = fs::write(
+            dashboard_out.join("index.html"),
+            "<!DOCTYPE html><html><body><p>Dashboard not built. Run: cd packages/dashboard &amp;&amp; pnpm build</p></body></html>\n",
+        );
+    }
+}
+
+fn main() {
+    ensure_dashboard_dir();
+
+    let protocol_dir = Path::new("cdp-protocol");
+    let out_dir = env::var("OUT_DIR").unwrap();
+    let out_path = Path::new(&out_dir).join("cdp_generated.rs");
+
+    let browser_path = protocol_dir.join("browser_protocol.json");
+    let js_path = protocol_dir.join("js_protocol.json");
+
+    if !browser_path.exists() && !js_path.exists() {
+        fs::write(
+            &out_path,
+            "// No protocol JSON files found in cdp-protocol/\n",
+        )
+        .unwrap();
+        return;
+    }
+
+    let mut all_domains: Vec<Domain> = Vec::new();
+
+    for path in [&browser_path, &js_path] {
+        if !path.exists() {
+            continue;
+        }
+        println!("cargo:rerun-if-changed={}", path.display());
+        let content = fs::read_to_string(path).unwrap();
+        let protocol: ProtocolSpec = match serde_json::from_str(&content) {
+            Ok(p) => p,
+            Err(e) => {
+                eprintln!("cargo:warning=Failed to parse {}: {}", path.display(), e);
+                continue;
+            }
+        };
+        all_domains.extend(protocol.domains);
+    }
+
+    // Collect all known type IDs per domain for cross-domain resolution
+    let mut domain_types: std::collections::HashMap<String, HashSet<String>> =
+        std::collections::HashMap::new();
+    for domain in &all_domains {
+        let mut types = HashSet::new();
+        for td in &domain.types {
+            types.insert(td.id.clone());
+        }
+        domain_types.insert(domain.domain.clone(), types);
+    }
+
+    // Known recursive struct fields that need Box wrapping
+    let recursive_fields: HashSet<(&str, &str, &str)> = [
+        ("DOM", "Node", "contentDocument"),
+        ("DOM", "Node", "templateContent"),
+        ("DOM", "Node", "importedDocument"),
+        ("Accessibility", "AXNode", "sources"),
+        ("Runtime", "StackTrace", "parent"),
+    ]
+    .into_iter()
+    .collect();
+
+    let mut output = String::new();
+    output.push_str("use serde::{Deserialize, Serialize};\n\n");
+
+    for domain in &all_domains {
+        generate_domain(domain, &domain_types, &recursive_fields, &mut output);
+    }
+
+    fs::write(&out_path, &output).unwrap();
+}
+
+#[allow(dead_code)]
+#[derive(serde::Deserialize)]
+struct ProtocolSpec {
+    domains: Vec<Domain>,
+}
+
+#[allow(dead_code)]
+#[derive(serde::Deserialize, Clone)]
+struct Domain {
+    domain: String,
+    #[serde(default)]
+    types: Vec<TypeDef>,
+    #[serde(default)]
+    commands: Vec<Command>,
+    #[serde(default)]
+    events: Vec<Event>,
+}
+
+#[allow(dead_code)]
+#[derive(serde::Deserialize, Clone)]
+struct TypeDef {
+    id: String,
+    #[serde(rename = "type", default)]
+    type_kind: String,
+    #[serde(default)]
+    properties: Vec<Property>,
+    #[serde(rename = "enum", default)]
+    enum_values: Vec<String>,
+    #[serde(default)]
+    description: Option<String>,
+}
+
+#[allow(dead_code)]
+#[derive(serde::Deserialize, Clone)]
+struct Command {
+    name: String,
+    #[serde(default)]
+    parameters: Vec<Property>,
+    #[serde(default)]
+    returns: Vec<Property>,
+    #[serde(default)]
+    description: Option<String>,
+}
+
+#[allow(dead_code)]
+#[derive(serde::Deserialize, Clone)]
+struct Event {
+    name: String,
+    #[serde(default)]
+    parameters: Vec<Property>,
+    #[serde(default)]
+    description: Option<String>,
+}
+
+#[allow(dead_code)]
+#[derive(serde::Deserialize, Clone)]
+struct Property {
+    name: String,
+    #[serde(rename = "type", default)]
+    type_kind: Option<String>,
+    #[serde(rename = "$ref", default)]
+    ref_type: Option<String>,
+    #[serde(default)]
+    optional: bool,
+    #[serde(default)]
+    description: Option<String>,
+    #[serde(default)]
+    items: Option<Box<ItemType>>,
+    #[serde(rename = "enum", default)]
+    enum_values: Vec<String>,
+}
+
+#[allow(dead_code)]
+#[derive(serde::Deserialize, Clone)]
+struct ItemType {
+    #[serde(rename = "type", default)]
+    type_kind: Option<String>,
+    #[serde(rename = "$ref", default)]
+    ref_type: Option<String>,
+}
+
+fn to_pascal_case(s: &str) -> String {
+    let mut result = String::new();
+    let mut capitalize = true;
+    for c in s.chars() {
+        if c == '_' || c == '-' || c == '.' {
+            capitalize = true;
+        } else if capitalize {
+            result.push(c.to_ascii_uppercase());
+            capitalize = false;
+        } else {
+            result.push(c);
+        }
+    }
+    result
+}
+
+fn to_snake_case(s: &str) -> String {
+    let mut result = String::new();
+    let chars: Vec<char> = s.chars().collect();
+    for (i, &c) in chars.iter().enumerate() {
+        if c.is_uppercase() && i > 0 {
+            // Only insert underscore at transitions from lowercase to uppercase,
+            // or when an uppercase sequence ends (e.g. "DOM" -> "dom", not "d_o_m")
+            let prev_upper = chars[i - 1].is_uppercase();
+            let next_lower = chars.get(i + 1).is_some_and(|n| n.is_lowercase());
+            if !prev_upper || next_lower {
+                result.push('_');
+            }
+        }
+        result.push(c.to_ascii_lowercase());
+    }
+    result
+}
+
+/// Resolve a $ref type reference. Cross-domain refs like "Page.FrameId" become
+/// `super::cdp_page::FrameId`. Same-domain refs are used directly.
+fn resolve_ref(
+    r: &str,
+    current_domain: &str,
+    domain_types: &std::collections::HashMap<String, HashSet<String>>,
+) -> String {
+    let parts: Vec<&str> = r.split('.').collect();
+    if parts.len() == 2 {
+        let ref_domain = parts[0];
+        let ref_type = parts[1];
+        if ref_domain == current_domain {
+            to_pascal_case(ref_type)
+        } else {
+            // Check if this type actually exists in the referenced domain
+            if domain_types
+                .get(ref_domain)
+                .is_some_and(|t| t.contains(ref_type))
+            {
+                format!(
+                    "super::cdp_{}::{}",
+                    to_snake_case(ref_domain),
+                    to_pascal_case(ref_type)
+                )
+            } else {
+                // Fall back to serde_json::Value for unknown cross-domain refs
+                "serde_json::Value".to_string()
+            }
+        }
+    } else {
+        to_pascal_case(r)
+    }
+}
+
+fn map_type_in_domain(
+    prop: &Property,
+    current_domain: &str,
+    domain_types: &std::collections::HashMap<String, HashSet<String>>,
+) -> String {
+    if let Some(ref r) = prop.ref_type {
+        let type_name = resolve_ref(r, current_domain, domain_types);
+        if prop.optional {
+            format!("Option<{}>", type_name)
+        } else {
+            type_name
+        }
+    } else if let Some(ref t) = prop.type_kind {
+        let base = match t.as_str() {
+            "string" => "String".to_string(),
+            "integer" => "i64".to_string(),
+            "number" => "f64".to_string(),
+            "boolean" => "bool".to_string(),
+            "object" => "serde_json::Value".to_string(),
+            "any" => "serde_json::Value".to_string(),
+            "array" => {
+                if let Some(ref items) = prop.items {
+                    let inner = if let Some(ref r) = items.ref_type {
+                        resolve_ref(r, current_domain, domain_types)
+                    } else {
+                        match items.type_kind.as_deref().unwrap_or("any") {
+                            "string" => "String".to_string(),
+                            "integer" => "i64".to_string(),
+                            "number" => "f64".to_string(),
+                            "boolean" => "bool".to_string(),
+                            _ => "serde_json::Value".to_string(),
+                        }
+                    };
+                    format!("Vec<{}>", inner)
+                } else {
+                    "Vec<serde_json::Value>".to_string()
+                }
+            }
+            _ => "serde_json::Value".to_string(),
+        };
+        if prop.optional {
+            format!("Option<{}>", base)
+        } else {
+            base
+        }
+    } else if prop.optional {
+        "Option<serde_json::Value>".to_string()
+    } else {
+        "serde_json::Value".to_string()
+    }
+}
+
+fn is_rust_keyword(s: &str) -> bool {
+    matches!(
+        s,
+        "type"
+            | "self"
+            | "Self"
+            | "super"
+            | "move"
+            | "ref"
+            | "fn"
+            | "mod"
+            | "use"
+            | "pub"
+            | "let"
+            | "mut"
+            | "const"
+            | "static"
+            | "if"
+            | "else"
+            | "for"
+            | "while"
+            | "loop"
+            | "match"
+            | "return"
+            | "break"
+            | "continue"
+            | "as"
+            | "in"
+            | "impl"
+            | "trait"
+            | "struct"
+            | "enum"
+            | "where"
+            | "async"
+            | "await"
+            | "dyn"
+            | "box"
+            | "yield"
+            | "override"
+            | "crate"
+            | "extern"
+    )
+}
+
+fn generate_domain(
+    domain: &Domain,
+    domain_types: &std::collections::HashMap<String, HashSet<String>>,
+    recursive_fields: &HashSet<(&str, &str, &str)>,
+    output: &mut String,
+) {
+    let mod_name = to_snake_case(&domain.domain);
+    output.push_str(&format!(
+        "#[allow(dead_code, non_snake_case, non_camel_case_types, clippy::enum_variant_names)]\npub mod cdp_{} {{\n",
+        mod_name
+    ));
+    output.push_str("    use super::*;\n\n");
+
+    for type_def in &domain.types {
+        if !type_def.enum_values.is_empty() {
+            // Deduplicate enum variants (some CDP enums have duplicated PascalCase forms)
+            let mut seen_variants = HashSet::new();
+            output.push_str("    #[derive(Debug, Clone, Serialize, Deserialize)]\n");
+            output.push_str(&format!("    pub enum {} {{\n", type_def.id));
+            for val in &type_def.enum_values {
+                let mut variant = to_pascal_case(val);
+                if variant == "Self" {
+                    variant = "SelfValue".to_string();
+                }
+                if variant.chars().next().is_some_and(|c| c.is_ascii_digit()) {
+                    variant = format!("V{}", variant);
+                }
+                if seen_variants.insert(variant.clone()) {
+                    output.push_str(&format!(
+                        "        #[serde(rename = \"{}\")]\n        {},\n",
+                        val, variant
+                    ));
+                }
+            }
+            output.push_str("    }\n\n");
+        } else if type_def.type_kind == "object" && !type_def.properties.is_empty() {
+            output.push_str(
+                "    #[derive(Debug, Clone, Serialize, Deserialize)]\n    #[serde(rename_all = \"camelCase\")]\n",
+            );
+            output.push_str(&format!("    pub struct {} {{\n", type_def.id));
+            for prop in &type_def.properties {
+                let field_name = to_snake_case(&prop.name);
+                let field_name = if is_rust_keyword(&field_name) {
+                    format!("r#{}", field_name)
+                } else {
+                    field_name
+                };
+                let mut rust_type = map_type_in_domain(prop, &domain.domain, domain_types);
+
+                // Wrap recursive fields in Box
+                if recursive_fields.contains(&(
+                    domain.domain.as_str(),
+                    type_def.id.as_str(),
+                    prop.name.as_str(),
+                )) {
+                    if rust_type.starts_with("Option<") {
+                        let inner = &rust_type[7..rust_type.len() - 1];
+                        rust_type = format!("Option<Box<{}>>", inner);
+                    } else {
+                        rust_type = format!("Box<{}>", rust_type);
+                    }
+                }
+
+                if prop.optional {
+                    output
+                        .push_str("        #[serde(skip_serializing_if = \"Option::is_none\")]\n");
+                }
+                output.push_str(&format!("        pub {}: {},\n", field_name, rust_type));
+            }
+            output.push_str("    }\n\n");
+        } else if type_def.type_kind == "object" && type_def.properties.is_empty() {
+            output.push_str(&format!(
+                "    pub type {} = serde_json::Value;\n\n",
+                type_def.id
+            ));
+        } else if type_def.type_kind == "array" {
+            output.push_str(&format!(
+                "    pub type {} = Vec<serde_json::Value>;\n\n",
+                type_def.id
+            ));
+        } else if type_def.type_kind == "string" && type_def.enum_values.is_empty() {
+            output.push_str(&format!("    pub type {} = String;\n\n", type_def.id));
+        } else if type_def.type_kind == "integer" {
+            output.push_str(&format!("    pub type {} = i64;\n\n", type_def.id));
+        } else if type_def.type_kind == "number" {
+            output.push_str(&format!("    pub type {} = f64;\n\n", type_def.id));
+        }
+    }
+
+    for cmd in &domain.commands {
+        let pascal_name = to_pascal_case(&cmd.name);
+
+        if !cmd.parameters.is_empty() {
+            output.push_str(
+                "    #[derive(Debug, Clone, Serialize, Deserialize)]\n    #[serde(rename_all = \"camelCase\")]\n",
+            );
+            output.push_str(&format!("    pub struct {}Params {{\n", pascal_name));
+            for param in &cmd.parameters {
+                let field_name = to_snake_case(&param.name);
+                let field_name = if is_rust_keyword(&field_name) {
+                    format!("r#{}", field_name)
+                } else {
+                    field_name
+                };
+                let rust_type = map_type_in_domain(param, &domain.domain, domain_types);
+                if param.optional {
+                    output
+                        .push_str("        #[serde(skip_serializing_if = \"Option::is_none\")]\n");
+                }
+                output.push_str(&format!("        pub {}: {},\n", field_name, rust_type));
+            }
+            output.push_str("    }\n\n");
+        }
+
+        if !cmd.returns.is_empty() {
+            output.push_str(
+                "    #[derive(Debug, Clone, Serialize, Deserialize)]\n    #[serde(rename_all = \"camelCase\")]\n",
+            );
+            output.push_str(&format!("    pub struct {}Result {{\n", pascal_name));
+            for ret in &cmd.returns {
+                let field_name = to_snake_case(&ret.name);
+                let field_name = if is_rust_keyword(&field_name) {
+                    format!("r#{}", field_name)
+                } else {
+                    field_name
+                };
+                let rust_type = map_type_in_domain(ret, &domain.domain, domain_types);
+                if ret.optional {
+                    output
+                        .push_str("        #[serde(skip_serializing_if = \"Option::is_none\")]\n");
+                }
+                output.push_str(&format!("        pub {}: {},\n", field_name, rust_type));
+            }
+            output.push_str("    }\n\n");
+        }
+    }
+
+    for event in &domain.events {
+        if !event.parameters.is_empty() {
+            let pascal_name = to_pascal_case(&event.name);
+            output.push_str(
+                "    #[derive(Debug, Clone, Serialize, Deserialize)]\n    #[serde(rename_all = \"camelCase\")]\n",
+            );
+            output.push_str(&format!("    pub struct {}Event {{\n", pascal_name));
+            for param in &event.parameters {
+                let field_name = to_snake_case(&param.name);
+                let field_name = if is_rust_keyword(&field_name) {
+                    format!("r#{}", field_name)
+                } else {
+                    field_name
+                };
+                let rust_type = map_type_in_domain(param, &domain.domain, domain_types);
+                if param.optional {
+                    output
+                        .push_str("        #[serde(skip_serializing_if = \"Option::is_none\")]\n");
+                }
+                output.push_str(&format!("        pub {}: {},\n", field_name, rust_type));
+            }
+            output.push_str("    }\n\n");
+        }
+    }
+
+    output.push_str("}\n\n");
+}

cli/src/chat.rs

@@ -0,0 +1,503 @@
+use std::io::Write as _;
+use std::process::exit;
+
+use serde_json::{json, Value};
+
+use crate::color;
+use crate::flags::Flags;
+use crate::native::stream::chat;
+
+const DEFAULT_MODEL: &str = "anthropic/claude-sonnet-4.6";
+
+#[derive(Clone, Copy, PartialEq)]
+enum Verbosity {
+    Quiet,
+    Normal,
+    Verbose,
+}
+
+pub fn run_chat(flags: &Flags, message: Option<String>) {
+    if !chat::is_chat_enabled() {
+        if flags.json {
+            println!(
+                "{}",
+                json!({"success": false, "error": "AI_GATEWAY_API_KEY not set. Set the AI_GATEWAY_API_KEY environment variable to enable chat."})
+            );
+        } else {
+            eprintln!(
+                "{} AI_GATEWAY_API_KEY not set. Set the AI_GATEWAY_API_KEY environment variable to enable chat.",
+                color::error_indicator()
+            );
+        }
+        exit(1);
+    }
+
+    let verbosity = if flags.quiet {
+        Verbosity::Quiet
+    } else if flags.verbose {
+        Verbosity::Verbose
+    } else {
+        Verbosity::Normal
+    };
+
+    let model = flags
+        .model
+        .clone()
+        .unwrap_or_else(|| DEFAULT_MODEL.to_string());
+
+    let rt = tokio::runtime::Runtime::new().expect("Failed to create tokio runtime");
+
+    let is_tty = std::io::IsTerminal::is_terminal(&std::io::stdin());
+
+    match message {
+        Some(msg) => {
+            rt.block_on(run_single_turn(
+                &flags.session,
+                &model,
+                &msg,
+                verbosity,
+                flags.json,
+            ));
+        }
+        None if !is_tty => {
+            let mut input = String::new();
+            if let Err(e) = std::io::stdin().read_line(&mut input) {
+                if flags.json {
+                    println!(
+                        "{}",
+                        json!({"success": false, "error": format!("Failed to read stdin: {}", e)})
+                    );
+                } else {
+                    eprintln!("{} Failed to read stdin: {}", color::error_indicator(), e);
+                }
+                exit(1);
+            }
+            let input = input.trim();
+            if input.is_empty() {
+                if flags.json {
+                    println!(
+                        "{}",
+                        json!({"success": false, "error": "No input provided"})
+                    );
+                } else {
+                    eprintln!("{} No input provided", color::error_indicator());
+                }
+                exit(1);
+            }
+            rt.block_on(run_single_turn(
+                &flags.session,
+                &model,
+                input,
+                verbosity,
+                flags.json,
+            ));
+        }
+        None => {
+            rt.block_on(run_interactive(
+                &flags.session,
+                &model,
+                verbosity,
+                flags.json,
+            ));
+        }
+    }
+}
+
+async fn run_single_turn(
+    session: &str,
+    model: &str,
+    message: &str,
+    verbosity: Verbosity,
+    json_mode: bool,
+) {
+    let mut openai_messages: Vec<Value> =
+        vec![json!({"role": "system", "content": chat::get_system_prompt()})];
+    openai_messages.push(json!({"role": "user", "content": message}));
+
+    let result = run_chat_turn(session, model, &mut openai_messages, verbosity, json_mode).await;
+    if !result {
+        exit(1);
+    }
+}
+
+async fn run_interactive(session: &str, model: &str, verbosity: Verbosity, json_mode: bool) {
+    let mut openai_messages: Vec<Value> =
+        vec![json!({"role": "system", "content": chat::get_system_prompt()})];
+
+    let gateway_url = std::env::var("AI_GATEWAY_URL")
+        .unwrap_or_else(|_| chat::DEFAULT_AI_GATEWAY_URL.to_string())
+        .trim_end_matches('/')
+        .to_string();
+    let api_key = std::env::var("AI_GATEWAY_API_KEY").unwrap_or_default();
+    let url = format!("{}/v1/chat/completions", gateway_url);
+    let client = chat::http_client();
+
+    loop {
+        if !json_mode {
+            eprint!("{} ", color::cyan(">"));
+            let _ = std::io::stderr().flush();
+        }
+
+        let mut input = String::new();
+        match std::io::stdin().read_line(&mut input) {
+            Ok(0) => break,
+            Err(_) => break,
+            Ok(_) => {}
+        }
+
+        let input = input.trim();
+        if input.is_empty() {
+            continue;
+        }
+
+        if matches!(input, "quit" | "exit" | "q") {
+            break;
+        }
+
+        openai_messages.push(json!({"role": "user", "content": input}));
+
+        // Compaction check
+        let total_chars = chat::estimate_chars(&openai_messages);
+        if total_chars > chat::COMPACT_THRESHOLD_CHARS
+            && openai_messages.len() > chat::KEEP_RECENT_MESSAGES + 2
+        {
+            let split = chat::find_safe_split(&openai_messages, chat::KEEP_RECENT_MESSAGES);
+            let to_summarize = &openai_messages[1..split];
+            if let Some(summary) =
+                chat::summarize_for_compaction(client, &url, &api_key, model, to_summarize).await
+            {
+                let summary_msg = json!({
+                    "role": "system",
+                    "content": format!("[Conversation summary]\n{}", summary)
+                });
+                let recent = openai_messages[split..].to_vec();
+                openai_messages = vec![openai_messages[0].clone(), summary_msg];
+                openai_messages.extend(recent);
+            }
+        }
+
+        let success =
+            run_chat_turn(session, model, &mut openai_messages, verbosity, json_mode).await;
+
+        if !success && !json_mode {
+            // Continue the loop on error; don't exit interactive mode
+        }
+
+        if !json_mode {
+            eprintln!();
+        }
+    }
+}
+
+/// Runs one chat turn: sends messages to the gateway, streams text/tool calls,
+/// executes tools in a loop until the model is done. Appends assistant and tool
+/// messages to `openai_messages`. Returns true on success.
+async fn run_chat_turn(
+    session: &str,
+    model: &str,
+    openai_messages: &mut Vec<Value>,
+    verbosity: Verbosity,
+    json_mode: bool,
+) -> bool {
+    let gateway_url = std::env::var("AI_GATEWAY_URL")
+        .unwrap_or_else(|_| chat::DEFAULT_AI_GATEWAY_URL.to_string())
+        .trim_end_matches('/')
+        .to_string();
+    let api_key = match std::env::var("AI_GATEWAY_API_KEY") {
+        Ok(k) => k,
+        Err(_) => {
+            if json_mode {
+                println!(
+                    "{}",
+                    json!({"success": false, "error": "AI_GATEWAY_API_KEY not set"})
+                );
+            } else {
+                eprintln!("{} AI_GATEWAY_API_KEY not set", color::error_indicator());
+            }
+            return false;
+        }
+    };
+
+    let tools: Value = serde_json::from_str(chat::CHAT_TOOLS).unwrap();
+    let url = format!("{}/v1/chat/completions", gateway_url);
+    let client = chat::http_client();
+
+    let total_deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(300);
+    let tool_timeout = std::time::Duration::from_secs(60);
+
+    let mut all_text = String::new();
+    let mut all_tool_calls: Vec<Value> = Vec::new();
+    let mut had_text = false;
+
+    for _step in 0..50 {
+        if tokio::time::Instant::now() >= total_deadline {
+            if json_mode {
+                println!(
+                    "{}",
+                    json!({"success": false, "error": "Chat session timed out (5 minute limit)."})
+                );
+            } else {
+                eprintln!(
+                    "\n{} Chat session timed out (5 minute limit).",
+                    color::error_indicator()
+                );
+            }
+            return false;
+        }
+
+        let gateway_body = json!({
+            "model": model,
+            "messages": openai_messages,
+            "tools": tools,
+            "stream": true,
+        });
+
+        let gw_response = match client
+            .post(&url)
+            .header("Authorization", format!("Bearer {}", api_key))
+            .header("Content-Type", "application/json")
+            .body(gateway_body.to_string())
+            .send()
+            .await
+        {
+            Ok(r) => r,
+            Err(e) => {
+                if json_mode {
+                    println!(
+                        "{}",
+                        json!({"success": false, "error": format!("Gateway request failed: {}", e)})
+                    );
+                } else {
+                    eprintln!(
+                        "\n{} Gateway request failed: {}",
+                        color::error_indicator(),
+                        e
+                    );
+                }
+                return false;
+            }
+        };
+
+        if !gw_response.status().is_success() {
+            let body_text = gw_response.text().await.unwrap_or_default();
+            if json_mode {
+                println!("{}", json!({"success": false, "error": body_text}));
+            } else {
+                eprintln!("\n{} {}", color::error_indicator(), body_text);
+            }
+            return false;
+        }
+
+        let (text_chunks, tool_calls) =
+            parse_gateway_stream(gw_response, verbosity, json_mode).await;
+
+        if !text_chunks.is_empty() {
+            let text = text_chunks.join("");
+            all_text.push_str(&text);
+            if !json_mode {
+                if !had_text && verbosity != Verbosity::Quiet {
+                    // Add blank line before text if we showed tool calls
+                    if !all_tool_calls.is_empty() {
+                        println!();
+                    }
+                }
+                had_text = true;
+            }
+
+            let mut content = json!(text);
+            if let Some(last) = openai_messages.last() {
+                if last.get("role").and_then(|r| r.as_str()) == Some("assistant")
+                    && last.get("tool_calls").is_some()
+                {
+                    content = json!(text);
+                }
+            }
+            openai_messages.push(json!({"role": "assistant", "content": content}));
+        }
+
+        if tool_calls.is_empty() {
+            break;
+        }
+
+        let tc_values: Vec<Value> = tool_calls
+            .iter()
+            .map(|(id, name, args)| {
+                json!({"id": id, "type": "function", "function": {"name": name, "arguments": args}})
+            })
+            .collect();
+
+        if text_chunks.is_empty() {
+            openai_messages.push(json!({"role": "assistant", "tool_calls": tc_values}));
+        } else {
+            // If we had both text and tool calls in the same response, merge them
+            if let Some(last) = openai_messages.last_mut() {
+                if last.get("role").and_then(|r| r.as_str()) == Some("assistant")
+                    && last.get("tool_calls").is_none()
+                {
+                    last["tool_calls"] = json!(tc_values);
+                } else {
+                    openai_messages.push(json!({"role": "assistant", "tool_calls": tc_values}));
+                }
+            }
+        }
+
+        for (tc_id, _tc_name, tc_args) in &tool_calls {
+            let input: Value = serde_json::from_str(tc_args).unwrap_or(json!({}));
+            let command = input.get("command").and_then(|c| c.as_str()).unwrap_or("");
+
+            if !json_mode && verbosity != Verbosity::Quiet {
+                eprintln!("{}", color::dim(&format!("> {}", command)));
+            }
+
+            let result =
+                match tokio::time::timeout(tool_timeout, chat::execute_chat_tool(session, command))
+                    .await
+                {
+                    Ok(r) => r,
+                    Err(_) => "Tool execution timed out after 60 seconds.".to_string(),
+                };
+
+            if !json_mode && verbosity == Verbosity::Verbose {
+                for line in result.lines() {
+                    eprintln!("  {}", color::dim(line));
+                }
+            }
+
+            all_tool_calls.push(json!({
+                "command": command,
+                "output": result
+            }));
+
+            openai_messages.push(json!({
+                "role": "tool",
+                "tool_call_id": tc_id,
+                "content": result
+            }));
+        }
+    }
+
+    if json_mode {
+        println!(
+            "{}",
+            json!({
+                "success": true,
+                "text": all_text,
+                "tool_calls": all_tool_calls
+            })
+        );
+    } else if !had_text && !json_mode {
+        // Model returned only tool calls with no final text; print newline for clean output
+        println!();
+    }
+
+    true
+}
+
+/// Parses the SSE stream from the AI gateway, printing text deltas to stdout in
+/// real-time. Returns (collected_text_chunks, tool_calls).
+async fn parse_gateway_stream(
+    gw_response: reqwest::Response,
+    verbosity: Verbosity,
+    json_mode: bool,
+) -> (Vec<String>, Vec<(String, String, String)>) {
+    use futures_util::StreamExt as _;
+
+    let mut text_chunks: Vec<String> = Vec::new();
+    let mut tool_call_args: std::collections::HashMap<usize, (String, String, String)> =
+        std::collections::HashMap::new();
+    let mut byte_stream = gw_response.bytes_stream();
+    let mut buffer = String::new();
+
+    while let Some(chunk_result) = byte_stream.next().await {
+        let chunk = match chunk_result {
+            Ok(c) => c,
+            Err(_) => break,
+        };
+
+        buffer.push_str(&String::from_utf8_lossy(&chunk));
+
+        while let Some(newline_pos) = buffer.find('\n') {
+            let line = buffer[..newline_pos].trim_end_matches('\r').to_string();
+            buffer = buffer[newline_pos + 1..].to_string();
+
+            if line.is_empty() {
+                continue;
+            }
+            let Some(data) = line.strip_prefix("data: ") else {
+                continue;
+            };
+            if data == "[DONE]" {
+                let tool_calls = collect_tool_calls(&mut tool_call_args);
+                if !json_mode && !text_chunks.is_empty() {
+                    // End the streamed text line
+                    let _ = std::io::stdout().flush();
+                }
+                return (text_chunks, tool_calls);
+            }
+            let Ok(sse_json) = serde_json::from_str::<Value>(data) else {
+                continue;
+            };
+            let delta = sse_json
+                .get("choices")
+                .and_then(|c| c.get(0))
+                .and_then(|c| c.get("delta"));
+            let Some(delta) = delta else { continue };
+
+            if let Some(text) = delta.get("content").and_then(|c| c.as_str()) {
+                if !text.is_empty() {
+                    text_chunks.push(text.to_string());
+                    if !json_mode && verbosity != Verbosity::Quiet {
+                        print!("{}", text);
+                        let _ = std::io::stdout().flush();
+                    }
+                }
+            }
+
+            if let Some(tcs) = delta.get("tool_calls").and_then(|t| t.as_array()) {
+                for tc in tcs {
+                    let idx = tc.get("index").and_then(|i| i.as_u64()).unwrap_or(0) as usize;
+                    if let std::collections::hash_map::Entry::Vacant(e) = tool_call_args.entry(idx)
+                    {
+                        let id = tc
+                            .get("id")
+                            .and_then(|i| i.as_str())
+                            .unwrap_or("")
+                            .to_string();
+                        let name = tc
+                            .get("function")
+                            .and_then(|f| f.get("name"))
+                            .and_then(|n| n.as_str())
+                            .unwrap_or("")
+                            .to_string();
+                        e.insert((id, name, String::new()));
+                    }
+                    if let Some(arg_delta) = tc
+                        .get("function")
+                        .and_then(|f| f.get("arguments"))
+                        .and_then(|a| a.as_str())
+                    {
+                        let entry = tool_call_args.get_mut(&idx).unwrap();
+                        entry.2.push_str(arg_delta);
+                    }
+                }
+            }
+        }
+    }
+
+    if !json_mode && !text_chunks.is_empty() {
+        let _ = std::io::stdout().flush();
+    }
+    let tool_calls = collect_tool_calls(&mut tool_call_args);
+    (text_chunks, tool_calls)
+}
+
+fn collect_tool_calls(
+    map: &mut std::collections::HashMap<usize, (String, String, String)>,
+) -> Vec<(String, String, String)> {
+    let mut indices: Vec<usize> = map.keys().copied().collect();
+    indices.sort();
+    indices
+        .into_iter()
+        .filter_map(|idx| map.remove(&idx))
+        .collect()
+}

cli/src/color.rs

@@ -0,0 +1,173 @@
+//! Color output utilities.
+//!
+//! Colors are off by default (agent-friendly). Enable with
+//! `AGENT_BROWSER_COLOR=1`. Setting `NO_COLOR` to any value disables
+//! colors per <https://no-color.org/>.
+
+use std::env;
+use std::sync::OnceLock;
+
+fn env_is_truthy(name: &str) -> Option<bool> {
+    env::var(name)
+        .ok()
+        .map(|val| !matches!(val.to_lowercase().as_str(), "0" | "false" | "no"))
+}
+
+/// Returns true if color output is enabled.
+///
+/// Priority: `NO_COLOR` (presence disables, per spec) >
+/// `AGENT_BROWSER_COLOR` (truthy enables) > default (off).
+pub fn is_enabled() -> bool {
+    static COLORS_ENABLED: OnceLock<bool> = OnceLock::new();
+    *COLORS_ENABLED.get_or_init(|| {
+        if env::var_os("NO_COLOR").is_some() {
+            return false;
+        }
+        env_is_truthy("AGENT_BROWSER_COLOR").unwrap_or(false)
+    })
+}
+
+/// Format text in red (errors)
+pub fn red(text: &str) -> String {
+    if is_enabled() {
+        format!("\x1b[31m{}\x1b[0m", text)
+    } else {
+        text.to_string()
+    }
+}
+
+/// Format text in green (success)
+pub fn green(text: &str) -> String {
+    if is_enabled() {
+        format!("\x1b[32m{}\x1b[0m", text)
+    } else {
+        text.to_string()
+    }
+}
+
+/// Format text in yellow (warnings)
+pub fn yellow(text: &str) -> String {
+    if is_enabled() {
+        format!("\x1b[33m{}\x1b[0m", text)
+    } else {
+        text.to_string()
+    }
+}
+
+/// Format text in cyan (info/progress)
+pub fn cyan(text: &str) -> String {
+    if is_enabled() {
+        format!("\x1b[36m{}\x1b[0m", text)
+    } else {
+        text.to_string()
+    }
+}
+
+/// Format text in bold
+pub fn bold(text: &str) -> String {
+    if is_enabled() {
+        format!("\x1b[1m{}\x1b[0m", text)
+    } else {
+        text.to_string()
+    }
+}
+
+/// Format text in dim
+pub fn dim(text: &str) -> String {
+    if is_enabled() {
+        format!("\x1b[2m{}\x1b[0m", text)
+    } else {
+        text.to_string()
+    }
+}
+
+/// Red X error indicator
+pub fn error_indicator() -> &'static str {
+    static INDICATOR: OnceLock<String> = OnceLock::new();
+    INDICATOR.get_or_init(|| {
+        if is_enabled() {
+            "\x1b[31m✗\x1b[0m".to_string()
+        } else {
+            "✗".to_string()
+        }
+    })
+}
+
+/// Green checkmark success indicator
+pub fn success_indicator() -> &'static str {
+    static INDICATOR: OnceLock<String> = OnceLock::new();
+    INDICATOR.get_or_init(|| {
+        if is_enabled() {
+            "\x1b[32m✓\x1b[0m".to_string()
+        } else {
+            "✓".to_string()
+        }
+    })
+}
+
+/// Yellow warning indicator
+pub fn warning_indicator() -> &'static str {
+    static INDICATOR: OnceLock<String> = OnceLock::new();
+    INDICATOR.get_or_init(|| {
+        if is_enabled() {
+            "\x1b[33m⚠\x1b[0m".to_string()
+        } else {
+            "⚠".to_string()
+        }
+    })
+}
+
+/// Get console log color prefix by level
+pub fn console_level_prefix(level: &str) -> String {
+    if !is_enabled() {
+        return format!("[{}]", level);
+    }
+
+    let color = match level {
+        "error" => "\x1b[31m",
+        "warning" => "\x1b[33m",
+        "info" => "\x1b[36m",
+        _ => "",
+    };
+    if color.is_empty() {
+        format!("[{}]", level)
+    } else {
+        format!("{}[{}]\x1b[0m", color, level)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_red_contains_ansi_codes() {
+        // Test the format structure (actual color depends on NO_COLOR env)
+        let formatted = format!("\x1b[31m{}\x1b[0m", "error");
+        assert!(formatted.contains("\x1b[31m"));
+        assert!(formatted.contains("\x1b[0m"));
+    }
+
+    #[test]
+    fn test_green_contains_ansi_codes() {
+        let formatted = format!("\x1b[32m{}\x1b[0m", "success");
+        assert!(formatted.contains("\x1b[32m"));
+    }
+
+    #[test]
+    fn test_console_level_prefix_contains_level() {
+        // Regardless of color state, the level text should be present
+        assert!(console_level_prefix("error").contains("error"));
+        assert!(console_level_prefix("warning").contains("warning"));
+        assert!(console_level_prefix("info").contains("info"));
+        assert!(console_level_prefix("log").contains("log"));
+    }
+
+    #[test]
+    fn test_indicators_contain_symbols() {
+        // Regardless of color state, symbols should be present
+        assert!(error_indicator().contains('✗'));
+        assert!(success_indicator().contains('✓'));
+        assert!(warning_indicator().contains('⚠'));
+    }
+}

cli/src/doctor/chrome.rs

@@ -0,0 +1,156 @@
+//! Check the Chrome install: binary path, version, cache dirs, user-data
+//! dir, and the optional lightpanda engine.
+
+use std::env;
+use std::path::{Path, PathBuf};
+
+use super::helpers::which_exists;
+use super::{Check, Status};
+
+pub(super) fn check(checks: &mut Vec<Check>) {
+    let category = "Chrome";
+
+    let chrome = crate::native::cdp::chrome::find_chrome();
+    match chrome {
+        Some(path) => {
+            let label = path.display().to_string();
+            match query_chrome_version(&path) {
+                Some(version) => checks.push(Check::new(
+                    "chrome.installed",
+                    category,
+                    Status::Pass,
+                    format!("{} at {}", version, label),
+                )),
+                None => checks.push(Check::new(
+                    "chrome.installed",
+                    category,
+                    Status::Pass,
+                    format!("Chrome at {} (version unknown)", label),
+                )),
+            }
+        }
+        None => checks.push(
+            Check::new(
+                "chrome.installed",
+                category,
+                Status::Fail,
+                "No Chrome binary found",
+            )
+            .with_fix("agent-browser install"),
+        ),
+    }
+
+    let cache_dir = crate::install::get_browsers_dir();
+    if cache_dir.exists() {
+        checks.push(Check::new(
+            "chrome.cache_dir",
+            category,
+            Status::Info,
+            format!("Cache dir {}", cache_dir.display()),
+        ));
+    }
+
+    if let Some(puppeteer_dir) = puppeteer_cache_dir() {
+        if puppeteer_dir.exists() {
+            checks.push(Check::new(
+                "chrome.puppeteer_cache",
+                category,
+                Status::Info,
+                format!(
+                    "Puppeteer cache also present: {} (will be used as a fallback)",
+                    puppeteer_dir.display()
+                ),
+            ));
+        }
+    }
+
+    if let Some(user_data_dir) = crate::native::cdp::chrome::find_chrome_user_data_dir() {
+        let profiles = crate::native::cdp::chrome::list_chrome_profiles(&user_data_dir);
+        let count = profiles.len();
+        let dir_label = user_data_dir.display().to_string();
+        if count == 0 {
+            checks.push(Check::new(
+                "chrome.user_data_dir",
+                category,
+                Status::Info,
+                format!(
+                    "Chrome user data dir found ({}), no profiles parsed",
+                    dir_label
+                ),
+            ));
+        } else {
+            checks.push(Check::new(
+                "chrome.user_data_dir",
+                category,
+                Status::Info,
+                format!("{} Chrome profile(s) at {}", count, dir_label),
+            ));
+        }
+    }
+
+    if let Ok(engine) = env::var("AGENT_BROWSER_ENGINE") {
+        if engine == "lightpanda" {
+            // Best-effort PATH lookup; absence is FAIL only when the user
+            // explicitly opted into the lightpanda engine.
+            if which_exists("lightpanda") {
+                checks.push(Check::new(
+                    "chrome.engine_lightpanda",
+                    category,
+                    Status::Pass,
+                    "Lightpanda binary on PATH",
+                ));
+            } else {
+                checks.push(
+                    Check::new(
+                        "chrome.engine_lightpanda",
+                        category,
+                        Status::Fail,
+                        "AGENT_BROWSER_ENGINE=lightpanda but no lightpanda binary on PATH",
+                    )
+                    .with_fix("install lightpanda or unset AGENT_BROWSER_ENGINE"),
+                );
+            }
+        }
+    }
+}
+
+fn query_chrome_version(path: &Path) -> Option<String> {
+    let output = std::process::Command::new(path)
+        .arg("--version")
+        .output()
+        .ok()?;
+    if !output.status.success() {
+        return None;
+    }
+    let s = String::from_utf8_lossy(&output.stdout).trim().to_string();
+    if s.is_empty() {
+        None
+    } else {
+        Some(s)
+    }
+}
+
+pub(super) fn puppeteer_cache_dir() -> Option<PathBuf> {
+    if let Ok(p) = env::var("PUPPETEER_CACHE_DIR") {
+        return Some(PathBuf::from(p));
+    }
+    dirs::home_dir().map(|h| h.join(".cache").join("puppeteer"))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_puppeteer_cache_dir_returns_sensible_default() {
+        // When PUPPETEER_CACHE_DIR is unset, we fall back to
+        // ~/.cache/puppeteer. Mutating env vars here would race with other
+        // tests, so just verify the fallback path is shaped correctly.
+        if env::var("PUPPETEER_CACHE_DIR").is_err() {
+            let dir = puppeteer_cache_dir().expect("home dir should resolve in tests");
+            let s = dir.to_string_lossy();
+            assert!(s.contains(".cache"));
+            assert!(s.ends_with("puppeteer"));
+        }
+    }
+}

cli/src/doctor/config.rs

@@ -0,0 +1,90 @@
+//! Check user config files: `~/.agent-browser/config.json`,
+//! `./agent-browser.json`, and any file referenced by
+//! `AGENT_BROWSER_CONFIG`.
+
+use std::env;
+use std::path::PathBuf;
+
+use super::helpers::parse_json_file;
+use super::{Check, Status};
+
+pub(super) fn check(checks: &mut Vec<Check>) {
+    let category = "Config";
+
+    let user_path = dirs::home_dir().map(|d| d.join(".agent-browser").join("config.json"));
+    if let Some(p) = user_path {
+        if p.exists() {
+            match parse_json_file(&p) {
+                Ok(_) => checks.push(Check::new(
+                    "config.user",
+                    category,
+                    Status::Pass,
+                    format!("{} (valid JSON)", p.display()),
+                )),
+                Err(e) => checks.push(
+                    Check::new(
+                        "config.user",
+                        category,
+                        Status::Fail,
+                        format!("{}: {}", p.display(), e),
+                    )
+                    .with_fix(format!("edit {}", p.display())),
+                ),
+            }
+        }
+    }
+
+    let project_path = PathBuf::from("agent-browser.json");
+    if project_path.exists() {
+        match parse_json_file(&project_path) {
+            Ok(_) => checks.push(Check::new(
+                "config.project",
+                category,
+                Status::Pass,
+                format!("{} (valid JSON)", project_path.display()),
+            )),
+            Err(e) => checks.push(
+                Check::new(
+                    "config.project",
+                    category,
+                    Status::Fail,
+                    format!("{}: {}", project_path.display(), e),
+                )
+                .with_fix(format!("edit {}", project_path.display())),
+            ),
+        }
+    }
+
+    if let Ok(custom) = env::var("AGENT_BROWSER_CONFIG") {
+        let p = PathBuf::from(&custom);
+        if !p.exists() {
+            checks.push(
+                Check::new(
+                    "config.custom",
+                    category,
+                    Status::Fail,
+                    format!("AGENT_BROWSER_CONFIG points to missing file: {}", custom),
+                )
+                .with_fix("update or unset AGENT_BROWSER_CONFIG"),
+            );
+        } else {
+            match parse_json_file(&p) {
+                Ok(_) => checks.push(Check::new(
+                    "config.custom",
+                    category,
+                    Status::Pass,
+                    format!("AGENT_BROWSER_CONFIG: {} (valid JSON)", custom),
+                )),
+                Err(e) => checks.push(
+                    Check::new(
+                        "config.custom",
+                        category,
+                        Status::Fail,
+                        format!("AGENT_BROWSER_CONFIG: {}: {}", custom, e),
+                    )
+                    .with_fix(format!("edit {}", custom)),
+                ),
+            }
+        }
+    }
+}

cli/src/doctor/daemon.rs

@@ -0,0 +1,70 @@
+//! Check running daemons: inventory of sessions, version match with the
+//! CLI, and stale sidecar files cleaned up as a side effect of the walk.
+
+use super::{Check, Status};
+use crate::connection::{walk_daemons, CleanReason};
+
+pub(super) fn check(checks: &mut Vec<Check>) {
+    let category = "Daemons";
+    let cli_version = env!("CARGO_PKG_VERSION");
+
+    let inventory = walk_daemons();
+
+    for cleaned in &inventory.cleaned {
+        let reason = match cleaned.reason {
+            CleanReason::ProcessGone | CleanReason::DashboardGone => "process gone",
+            CleanReason::UnreadablePidFile => "unreadable pid file",
+            CleanReason::OrphanedSocket => "orphaned socket",
+        };
+        checks.push(Check::new(
+            format!("daemon.cleaned.{}", cleaned.name),
+            category,
+            Status::Warn,
+            format!("Cleaned stale files: {} ({})", cleaned.name, reason),
+        ));
+    }
+
+    if inventory.sessions.is_empty() {
+        checks.push(Check::new(
+            "daemon.active",
+            category,
+            Status::Pass,
+            "No active daemons",
+        ));
+    } else {
+        for session in &inventory.sessions {
+            let version_match = session.version.as_deref() == Some(cli_version);
+            let status = if version_match {
+                Status::Pass
+            } else {
+                Status::Warn
+            };
+            let suffix = if version_match {
+                String::new()
+            } else {
+                format!(" (version mismatch with CLI {})", cli_version)
+            };
+            let mut check = Check::new(
+                format!("daemon.session.{}", session.name),
+                category,
+                status,
+                format!("Session {} (pid {}){}", session.name, session.pid, suffix),
+            );
+            if !version_match {
+                check = check.with_fix(format!("agent-browser --session {} close", session.name));
+            }
+            checks.push(check);
+        }
+    }
+
+    if let Some(dashboard) = inventory.dashboard {
+        if dashboard.alive {
+            checks.push(Check::new(
+                "daemon.dashboard",
+                category,
+                Status::Pass,
+                format!("Dashboard server running (pid {})", dashboard.pid),
+            ));
+        }
+    }
+}

cli/src/doctor/environment.rs

@@ -0,0 +1,140 @@
+//! Check the local environment: CLI version, platform, state/socket dirs,
+//! and free disk space.
+
+use std::path::Path;
+
+use super::helpers::{disk_free_bytes, human_size, is_writable_dir};
+use super::{Check, Status};
+use crate::connection::get_socket_dir;
+use crate::native::state::get_state_dir;
+
+pub(super) fn check(checks: &mut Vec<Check>) {
+    let category = "Environment";
+
+    let version = env!("CARGO_PKG_VERSION");
+    let platform = format!("{} {}", std::env::consts::OS, std::env::consts::ARCH);
+    checks.push(Check::new(
+        "env.version",
+        category,
+        Status::Pass,
+        format!("CLI version {} ({})", version, platform),
+    ));
+
+    match dirs::home_dir() {
+        Some(home) => checks.push(Check::new(
+            "env.home",
+            category,
+            Status::Pass,
+            format!("Home directory {}", home.display()),
+        )),
+        None => checks.push(Check::new(
+            "env.home",
+            category,
+            Status::Fail,
+            "Could not determine home directory",
+        )),
+    }
+
+    let state_dir = get_state_dir();
+    let socket_dir = get_socket_dir();
+
+    // Under the default setup, state and socket dirs are the same
+    // (~/.agent-browser). Collapse to a single line when they match;
+    // split when XDG_RUNTIME_DIR or AGENT_BROWSER_SOCKET_DIR diverts
+    // sockets elsewhere.
+    if state_dir == socket_dir {
+        push_dir_check(
+            checks,
+            "env.state_dir",
+            category,
+            "State and socket directory",
+            &state_dir,
+        );
+    } else {
+        push_dir_check(
+            checks,
+            "env.state_dir",
+            category,
+            "State directory",
+            &state_dir,
+        );
+        push_dir_check(
+            checks,
+            "env.socket_dir",
+            category,
+            "Socket directory",
+            &socket_dir,
+        );
+    }
+
+    match disk_free_bytes(&state_dir) {
+        Some(bytes) => {
+            let mb = bytes / (1024 * 1024);
+            let human = human_size(bytes);
+            if mb < 500 {
+                checks.push(
+                    Check::new(
+                        "env.disk_free",
+                        category,
+                        Status::Warn,
+                        format!("Low disk space at state dir: {} free", human),
+                    )
+                    .with_fix("free up disk space; Chrome installs require ~500 MB"),
+                );
+            } else {
+                checks.push(Check::new(
+                    "env.disk_free",
+                    category,
+                    Status::Pass,
+                    format!("{} free at state dir", human),
+                ));
+            }
+        }
+        None => checks.push(Check::new(
+            "env.disk_free",
+            category,
+            Status::Info,
+            "Disk free check unavailable on this platform",
+        )),
+    }
+}
+
+fn push_dir_check(
+    checks: &mut Vec<Check>,
+    id: &'static str,
+    category: &'static str,
+    label: &str,
+    dir: &Path,
+) {
+    if dir.exists() {
+        if is_writable_dir(dir) {
+            checks.push(Check::new(
+                id,
+                category,
+                Status::Pass,
+                format!("{} {}", label, dir.display()),
+            ));
+        } else {
+            checks.push(
+                Check::new(
+                    id,
+                    category,
+                    Status::Fail,
+                    format!("{} not writable: {}", label, dir.display()),
+                )
+                .with_fix(format!("chmod u+rwx {}", dir.display())),
+            );
+        }
+    } else {
+        checks.push(Check::new(
+            id,
+            category,
+            Status::Info,
+            format!(
+                "{} does not exist yet (will be created on first use): {}",
+                label,
+                dir.display()
+            ),
+        ));
+    }
+}

cli/src/doctor/fix.rs

@@ -0,0 +1,247 @@
+//! Destructive repair actions behind `--fix`: reinstall Chrome, close
+//! version-mismatched daemons, purge expired state files, and generate a
+//! missing encryption key.
+
+use std::env;
+use std::fs;
+use std::path::Path;
+use std::time::{Duration, SystemTime};
+
+#[cfg(unix)]
+use std::os::unix::fs::PermissionsExt;
+
+use serde_json::json;
+
+use super::helpers::new_id;
+use super::{Check, Status};
+use crate::connection::{cleanup_stale_files, send_command, walk_daemons};
+use crate::native::state::{get_sessions_dir, get_state_dir};
+
+pub(super) fn run(checks: &mut [Check], fixed: &mut Vec<String>) {
+    // `close_all_sessions` is expensive and closes every session at once, so
+    // only fire it on the first daemon.session.* Warn we encounter. Subsequent
+    // daemon.session.* Warn checks piggy-back on the same result.
+    let mut daemons_closed: Option<usize> = None;
+
+    for c in checks.iter_mut() {
+        match c.id.as_str() {
+            "chrome.installed" if c.status == Status::Fail => {
+                let installed = attempt_chrome_install();
+                if installed {
+                    fixed.push("Reinstalled Chrome".to_string());
+                    c.status = Status::Pass;
+                    c.message = format!("{} (fixed by --fix)", c.message);
+                    c.fix = None;
+                }
+            }
+            id if id.starts_with("daemon.session.") && c.status == Status::Warn => {
+                let killed = *daemons_closed.get_or_insert_with(|| {
+                    let n = close_all_sessions();
+                    if n > 0 {
+                        fixed.push(format!("Closed {} version-mismatched daemon(s)", n));
+                    }
+                    n
+                });
+                if killed > 0 {
+                    c.status = Status::Pass;
+                    c.message = format!("{} (fixed by --fix)", c.message);
+                    c.fix = None;
+                }
+            }
+            "security.state_count" if c.status == Status::Warn => {
+                let removed = purge_old_state();
+                if removed > 0 {
+                    fixed.push(format!("Deleted {} expired state file(s)", removed));
+                    c.status = Status::Pass;
+                    c.message = format!("{} (fixed by --fix)", c.message);
+                    c.fix = None;
+                }
+            }
+            "security.encryption_key" if c.status == Status::Info => {
+                let generated = create_encryption_key();
+                if generated {
+                    fixed.push("Generated encryption key".to_string());
+                    c.status = Status::Pass;
+                    c.message = format!("{} (fixed by --fix)", c.message);
+                    c.fix = None;
+                }
+            }
+            _ => {}
+        }
+    }
+}
+
+fn attempt_chrome_install() -> bool {
+    // run_install() uses process::exit on failure, so we shell out to ourselves
+    // to avoid taking down the doctor process if the install fails.
+    let exe = match std::env::current_exe() {
+        Ok(p) => p,
+        Err(_) => return false,
+    };
+    std::process::Command::new(exe)
+        .arg("install")
+        .status()
+        .map(|s| s.success())
+        .unwrap_or(false)
+}
+
+fn close_all_sessions() -> usize {
+    let mut killed = 0;
+    for session in &walk_daemons().sessions {
+        let cmd = json!({ "id": new_id(), "action": "close" });
+        if send_command(cmd, &session.name).is_ok() {
+            killed += 1;
+        }
+        cleanup_stale_files(&session.name);
+    }
+    killed
+}
+
+fn purge_old_state() -> usize {
+    let dir = get_sessions_dir();
+    let expire_days = env::var("AGENT_BROWSER_STATE_EXPIRE_DAYS")
+        .ok()
+        .and_then(|s| s.parse::<u64>().ok())
+        .unwrap_or(30);
+    let cutoff = SystemTime::now()
+        .checked_sub(Duration::from_secs(expire_days * 86_400))
+        .unwrap_or(SystemTime::UNIX_EPOCH);
+    let mut removed = 0;
+    if let Ok(entries) = fs::read_dir(&dir) {
+        for entry in entries.flatten() {
+            if entry.file_type().map(|t| t.is_file()).unwrap_or(false) {
+                if let Ok(meta) = entry.metadata() {
+                    if let Ok(modified) = meta.modified() {
+                        if modified < cutoff && fs::remove_file(entry.path()).is_ok() {
+                            removed += 1;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    removed
+}
+
+fn create_encryption_key() -> bool {
+    create_encryption_key_at(&get_state_dir())
+}
+
+fn create_encryption_key_at(dir: &Path) -> bool {
+    if fs::create_dir_all(dir).is_err() {
+        return false;
+    }
+    #[cfg(unix)]
+    {
+        let _ = fs::set_permissions(dir, fs::Permissions::from_mode(0o700));
+    }
+    let path = dir.join(".encryption-key");
+    if path.exists() {
+        return false;
+    }
+    let mut buf = [0u8; 32];
+    if getrandom::getrandom(&mut buf).is_err() {
+        return false;
+    }
+    let hex: String = buf.iter().map(|b| format!("{:02x}", b)).collect();
+    if fs::write(&path, format!("{}\n", hex)).is_err() {
+        return false;
+    }
+    #[cfg(unix)]
+    {
+        let _ = fs::set_permissions(&path, fs::Permissions::from_mode(0o600));
+    }
+    true
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::TempDir;
+
+    #[test]
+    fn test_create_encryption_key_at_writes_64_char_hex_key() {
+        let tmp = TempDir::new().unwrap();
+        let dir = tmp.path().join("state");
+
+        assert!(create_encryption_key_at(&dir));
+
+        let key = dir.join(".encryption-key");
+        assert!(key.exists(), "key file should be created");
+
+        let contents = fs::read_to_string(&key).unwrap();
+        let trimmed = contents.trim();
+        assert_eq!(trimmed.len(), 64, "key should be 64 hex chars");
+        assert!(
+            trimmed.chars().all(|c| c.is_ascii_hexdigit()),
+            "key should be all hex digits"
+        );
+    }
+
+    #[test]
+    fn test_create_encryption_key_at_is_idempotent() {
+        let tmp = TempDir::new().unwrap();
+        let dir = tmp.path().join("state");
+        assert!(create_encryption_key_at(&dir));
+
+        let original = fs::read_to_string(dir.join(".encryption-key")).unwrap();
+
+        // Second call returns false and must not overwrite the existing key.
+        assert!(!create_encryption_key_at(&dir));
+        let after = fs::read_to_string(dir.join(".encryption-key")).unwrap();
+        assert_eq!(original, after);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn test_create_encryption_key_at_sets_0600_perms() {
+        let tmp = TempDir::new().unwrap();
+        let dir = tmp.path().join("state");
+
+        assert!(create_encryption_key_at(&dir));
+
+        let key = dir.join(".encryption-key");
+        let mode = fs::metadata(&key).unwrap().permissions().mode() & 0o777;
+        assert_eq!(mode, 0o600, "key file should be 0600, got {:o}", mode);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn test_run_fixes_generates_missing_encryption_key() {
+        // Reaches the Info-status arm in run_fixes that was previously
+        // unreachable due to an early-continue guard. Overrides HOME so
+        // get_state_dir() resolves under a temp dir.
+        let guard = crate::test_utils::EnvGuard::new(&["HOME"]);
+        let tmp = TempDir::new().unwrap();
+        guard.set("HOME", tmp.path().to_str().unwrap());
+
+        let mut checks = vec![Check::new(
+            "security.encryption_key",
+            "Security",
+            Status::Info,
+            "No encryption key set",
+        )
+        .with_fix("export AGENT_BROWSER_ENCRYPTION_KEY=...")];
+        let mut fixed = Vec::new();
+
+        run(&mut checks, &mut fixed);
+
+        assert_eq!(
+            checks[0].status,
+            Status::Pass,
+            "Info check should transition to Pass after --fix"
+        );
+        assert!(
+            checks[0].fix.is_none(),
+            "fix hint should be cleared after repair"
+        );
+        assert!(
+            fixed.iter().any(|s| s.contains("encryption key")),
+            "fixed summary should mention the key generation"
+        );
+        assert!(
+            tmp.path().join(".agent-browser/.encryption-key").exists(),
+            "key file should exist at ~/.agent-browser/.encryption-key"
+        );
+    }
+}

cli/src/doctor/helpers.rs

@@ -0,0 +1,185 @@
+//! Stateless helpers shared across doctor submodules.
+
+use std::fs;
+use std::path::Path;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::SystemTime;
+
+use serde_json::Value;
+
+pub(super) fn is_writable_dir(path: &Path) -> bool {
+    fs::metadata(path)
+        .map(|m| !m.permissions().readonly())
+        .unwrap_or(false)
+}
+
+pub(super) fn human_size(bytes: u64) -> String {
+    const UNITS: &[&str] = &["B", "KB", "MB", "GB", "TB"];
+    let mut value = bytes as f64;
+    let mut unit = 0;
+    while value >= 1024.0 && unit < UNITS.len() - 1 {
+        value /= 1024.0;
+        unit += 1;
+    }
+    if unit == 0 {
+        format!("{} {}", bytes, UNITS[0])
+    } else {
+        format!("{:.1} {}", value, UNITS[unit])
+    }
+}
+
+#[cfg(unix)]
+pub(super) fn disk_free_bytes(path: &Path) -> Option<u64> {
+    use std::ffi::CString;
+    use std::os::unix::ffi::OsStrExt;
+    use std::path::PathBuf;
+
+    // Walk up to the first existing ancestor (for fresh installs where the
+    // state dir hasn't been created yet).
+    let mut probe: PathBuf = path.to_path_buf();
+    while !probe.exists() {
+        match probe.parent() {
+            Some(p) => probe = p.to_path_buf(),
+            None => return None,
+        }
+    }
+    let c_path = CString::new(probe.as_os_str().as_bytes()).ok()?;
+    let mut stat: libc::statvfs = unsafe { std::mem::zeroed() };
+    if unsafe { libc::statvfs(c_path.as_ptr(), &mut stat) } != 0 {
+        return None;
+    }
+    Some(stat.f_bavail as u64 * stat.f_frsize)
+}
+
+#[cfg(windows)]
+pub(super) fn disk_free_bytes(_path: &Path) -> Option<u64> {
+    None
+}
+
+#[cfg(not(any(unix, windows)))]
+pub(super) fn disk_free_bytes(_path: &Path) -> Option<u64> {
+    None
+}
+
+pub(super) fn which_exists(name: &str) -> bool {
+    let probe = if cfg!(target_os = "windows") {
+        "where"
+    } else {
+        "which"
+    };
+    std::process::Command::new(probe)
+        .arg(name)
+        .stdout(std::process::Stdio::null())
+        .stderr(std::process::Stdio::null())
+        .status()
+        .map(|s| s.success())
+        .unwrap_or(false)
+}
+
+pub(super) fn parse_json_file(path: &Path) -> Result<(), String> {
+    let content = fs::read_to_string(path).map_err(|e| format!("read failed: {}", e))?;
+    serde_json::from_str::<Value>(&content).map_err(|e| format!("invalid JSON: {}", e))?;
+    Ok(())
+}
+
+/// Generate a unique `doctor-<pid>-<micros>-<sequence>` id for JSON command envelopes.
+pub(super) fn new_id() -> String {
+    static NEXT_ID: AtomicU64 = AtomicU64::new(0);
+    let sequence = NEXT_ID.fetch_add(1, Ordering::Relaxed);
+
+    format!(
+        "doctor-{}-{}-{}",
+        std::process::id(),
+        SystemTime::now()
+            .duration_since(SystemTime::UNIX_EPOCH)
+            .map(|d| d.as_micros())
+            .unwrap_or(0),
+        sequence
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::TempDir;
+
+    #[test]
+    fn test_human_size_units() {
+        assert_eq!(human_size(0), "0 B");
+        assert_eq!(human_size(512), "512 B");
+        assert_eq!(human_size(1024), "1.0 KB");
+        assert_eq!(human_size(1024 * 1024), "1.0 MB");
+        assert_eq!(human_size(1024 * 1024 * 1024), "1.0 GB");
+        assert_eq!(human_size(1_500_000), "1.4 MB");
+    }
+
+    #[test]
+    fn test_disk_free_walks_up_to_existing_ancestor() {
+        let dir = TempDir::new().unwrap();
+        let nested = dir.path().join("a/b/c/d");
+        let bytes = disk_free_bytes(&nested);
+        if cfg!(unix) {
+            assert!(bytes.is_some());
+            assert!(bytes.unwrap() > 0);
+        }
+    }
+
+    #[test]
+    fn test_is_writable_dir_matches_metadata() {
+        let dir = TempDir::new().unwrap();
+        assert!(is_writable_dir(dir.path()));
+
+        let missing = dir.path().join("does-not-exist");
+        assert!(!is_writable_dir(&missing));
+    }
+
+    #[test]
+    fn test_which_exists_matches_common_binaries() {
+        // `sh` exists on every unix; `cmd` exists on windows.
+        let probe = if cfg!(target_os = "windows") {
+            "cmd"
+        } else {
+            "sh"
+        };
+        assert!(which_exists(probe));
+        assert!(!which_exists(
+            "agent-browser-this-does-not-exist-please-dont-install-it"
+        ));
+    }
+
+    #[test]
+    fn test_parse_json_file_valid_and_invalid() {
+        let dir = TempDir::new().unwrap();
+        let valid = dir.path().join("ok.json");
+        fs::write(&valid, r#"{"k": 1}"#).unwrap();
+        assert!(parse_json_file(&valid).is_ok());
+
+        let invalid = dir.path().join("bad.json");
+        fs::write(&invalid, "{not json}").unwrap();
+        let err = parse_json_file(&invalid).unwrap_err();
+        assert!(err.contains("invalid JSON"));
+
+        let missing = dir.path().join("nope.json");
+        let err = parse_json_file(&missing).unwrap_err();
+        assert!(err.contains("read failed"));
+    }
+
+    #[test]
+    fn test_parse_json_file_accepts_arrays() {
+        // The config parser rejects arrays at the Config type level, but
+        // doctor only checks syntactic JSON validity so it should accept
+        // both arrays and objects.
+        let dir = TempDir::new().unwrap();
+        let path = dir.path().join("arr.json");
+        fs::write(&path, r#"[1, 2, 3]"#).unwrap();
+        assert!(parse_json_file(&path).is_ok());
+    }
+
+    #[test]
+    fn test_new_id_is_unique_per_call() {
+        let a = new_id();
+        let b = new_id();
+        assert_ne!(a, b);
+        assert!(a.starts_with("doctor-"));
+    }
+}

cli/src/doctor/launch.rs

@@ -0,0 +1,192 @@
+//! Live launch test: spawn a scratch daemon session, launch headless
+//! Chrome, navigate to `about:blank`, then close. Skipped under `--quick`.
+//!
+//! A `LaunchGuard` Drop impl ensures the scratch session is closed and its
+//! sidecar files cleaned even on panic or early return.
+
+use std::env;
+use std::time::{Duration, Instant, SystemTime};
+
+use serde_json::{json, Value};
+
+use super::helpers::new_id;
+use super::{Check, Status};
+use crate::connection::{cleanup_stale_files, ensure_daemon, send_command, DaemonOptions};
+
+pub(super) fn check(checks: &mut Vec<Check>) {
+    let category = "Launch test";
+
+    if env::var("AGENT_BROWSER_PROVIDER").is_ok() {
+        checks.push(Check::new(
+            "launch.skipped.provider",
+            category,
+            Status::Info,
+            "Skipped (AGENT_BROWSER_PROVIDER is set; would consume cloud quota)",
+        ));
+        return;
+    }
+    if env::var("AGENT_BROWSER_CDP").is_ok() {
+        checks.push(Check::new(
+            "launch.skipped.cdp",
+            category,
+            Status::Info,
+            "Skipped (AGENT_BROWSER_CDP is set; would attach to a real browser)",
+        ));
+        return;
+    }
+
+    let session = format!(
+        "doctor-{}-{}",
+        std::process::id(),
+        SystemTime::now()
+            .duration_since(SystemTime::UNIX_EPOCH)
+            .map(|d| d.as_millis())
+            .unwrap_or(0)
+    );
+
+    // Armed after `ensure_daemon` succeeds so we don't send a stray `close`
+    // or delete sidecar files for a daemon that never started. On every early
+    // return past the `Some(...)` assignment below, Drop runs one close and
+    // one `cleanup_stale_files`.
+    let mut _guard: Option<LaunchGuard> = None;
+
+    let opts = DaemonOptions {
+        headed: false,
+        debug: false,
+        executable_path: None,
+        extensions: &[],
+        init_scripts: &[],
+        enable: &[],
+        args: None,
+        user_agent: None,
+        proxy: None,
+        proxy_bypass: None,
+        proxy_username: None,
+        proxy_password: None,
+        ignore_https_errors: false,
+        allow_file_access: false,
+        hide_scrollbars: true,
+        profile: None,
+        state: None,
+        provider: None,
+        device: None,
+        session_name: None,
+        restore_save: None,
+        restore_check_url: None,
+        restore_check_text: None,
+        restore_check_fn: None,
+        download_path: None,
+        allowed_domains: None,
+        action_policy: None,
+        confirm_actions: None,
+        engine: None,
+        auto_connect: false,
+        idle_timeout: None,
+        default_timeout: None,
+        cdp: None,
+        no_auto_dialog: false,
+        plugins: None,
+    };
+
+    let started = Instant::now();
+    if let Err(e) = ensure_daemon(&session, &opts) {
+        checks.push(
+            Check::new(
+                "launch.daemon",
+                category,
+                Status::Fail,
+                format!("Could not start daemon: {}", e),
+            )
+            .with_fix("check Chrome install and re-run with --debug"),
+        );
+        return;
+    }
+    _guard = Some(LaunchGuard {
+        session: session.clone(),
+    });
+
+    let launch_cmd = json!({
+        "id": new_id(),
+        "action": "launch",
+        "headless": true,
+    });
+    if let Err(e) = send_json(launch_cmd, &session) {
+        checks.push(
+            Check::new(
+                "launch.launch",
+                category,
+                Status::Fail,
+                format!("Browser launch failed: {}", e),
+            )
+            .with_fix("agent-browser install   # or check --debug output"),
+        );
+        return;
+    }
+
+    let open_cmd = json!({
+        "id": new_id(),
+        "action": "navigate",
+        "url": "about:blank",
+    });
+    if let Err(e) = send_json(open_cmd, &session) {
+        checks.push(
+            Check::new(
+                "launch.navigate",
+                category,
+                Status::Fail,
+                format!("Navigation to about:blank failed: {}", e),
+            )
+            .with_fix("re-run with --debug for full launch logs"),
+        );
+        return;
+    }
+
+    // Close + stale-file cleanup happen exactly once via LaunchGuard::drop at
+    // end of scope; no explicit close here.
+    let elapsed = started.elapsed();
+    let secs = elapsed.as_secs_f64();
+    if elapsed > Duration::from_secs(5) {
+        checks.push(Check::new(
+            "launch.elapsed",
+            category,
+            Status::Warn,
+            format!(
+                "Headless launch + about:blank in {:.2}s (slow; expected < 5s)",
+                secs
+            ),
+        ));
+    } else {
+        checks.push(Check::new(
+            "launch.elapsed",
+            category,
+            Status::Pass,
+            format!("Headless launch + about:blank in {:.2}s", secs),
+        ));
+    }
+}
+
+fn send_json(cmd: Value, session: &str) -> Result<(), String> {
+    match send_command(cmd, session) {
+        Ok(resp) => {
+            if resp.success {
+                Ok(())
+            } else {
+                Err(resp.error.unwrap_or_else(|| "unknown error".to_string()))
+            }
+        }
+        Err(e) => Err(e),
+    }
+}
+
+/// Best-effort cleanup when the launch test panics or returns early.
+struct LaunchGuard {
+    session: String,
+}
+
+impl Drop for LaunchGuard {
+    fn drop(&mut self) {
+        let close_cmd = json!({ "id": new_id(), "action": "close" });
+        let _ = send_command(close_cmd, &self.session);
+        cleanup_stale_files(&self.session);
+    }
+}

cli/src/doctor/mod.rs

@@ -0,0 +1,289 @@
+//! Diagnose an agent-browser installation.
+//!
+//! Runs a battery of checks across environment, Chrome install, daemon
+//! state, config files, encryption, providers, network reachability, and
+//! a live headless browser launch test.
+//!
+//! Auto-cleans stale daemon socket/pid/version sidecar files. Destructive
+//! repairs (reinstalling Chrome, purging old state files, generating a
+//! missing encryption key) are gated behind `--fix`.
+
+mod chrome;
+mod config;
+mod daemon;
+mod environment;
+mod fix;
+mod helpers;
+mod launch;
+mod network;
+mod providers;
+mod security;
+
+use serde_json::{json, Value};
+
+use crate::color;
+
+#[derive(Default, Clone, Copy)]
+pub struct DoctorOptions {
+    pub offline: bool,
+    pub quick: bool,
+    pub fix: bool,
+    pub json: bool,
+}
+
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+#[repr(u8)]
+pub(crate) enum Status {
+    Pass,
+    Warn,
+    Fail,
+    Info,
+}
+
+impl Status {
+    fn as_str(&self) -> &'static str {
+        match self {
+            Status::Pass => "pass",
+            Status::Warn => "warn",
+            Status::Fail => "fail",
+            Status::Info => "info",
+        }
+    }
+
+    fn label(&self) -> String {
+        match self {
+            Status::Pass => color::green("pass"),
+            Status::Warn => color::yellow("warn"),
+            Status::Fail => color::red("fail"),
+            Status::Info => color::dim("info"),
+        }
+    }
+}
+
+#[derive(Clone)]
+pub(crate) struct Check {
+    pub id: String,
+    pub category: &'static str,
+    pub status: Status,
+    pub message: String,
+    pub fix: Option<String>,
+}
+
+impl Check {
+    fn new(
+        id: impl Into<String>,
+        category: &'static str,
+        status: Status,
+        message: impl Into<String>,
+    ) -> Self {
+        Self {
+            id: id.into(),
+            category,
+            status,
+            message: message.into(),
+            fix: None,
+        }
+    }
+
+    fn with_fix(mut self, fix: impl Into<String>) -> Self {
+        self.fix = Some(fix.into());
+        self
+    }
+}
+
+/// Run the doctor command. Returns the process exit code.
+pub fn run_doctor(opts: DoctorOptions) -> i32 {
+    let mut checks: Vec<Check> = Vec::new();
+    let mut fixed: Vec<String> = Vec::new();
+
+    environment::check(&mut checks);
+    chrome::check(&mut checks);
+    daemon::check(&mut checks);
+    config::check(&mut checks);
+    security::check(&mut checks);
+    providers::check(&mut checks);
+
+    if !opts.offline {
+        network::check(&mut checks);
+    }
+
+    if !opts.quick {
+        launch::check(&mut checks);
+    }
+
+    if opts.fix {
+        fix::run(&mut checks, &mut fixed);
+    }
+
+    let summary = summarize(&checks);
+    let exit_code = if summary.fail > 0 { 1 } else { 0 };
+
+    if opts.json {
+        print_json(&checks, &summary, &fixed, exit_code == 0);
+    } else {
+        print_text(&checks, &summary, &fixed, opts.fix);
+    }
+
+    exit_code
+}
+
+struct Summary {
+    pass: usize,
+    warn: usize,
+    fail: usize,
+}
+
+fn summarize(checks: &[Check]) -> Summary {
+    let mut s = Summary {
+        pass: 0,
+        warn: 0,
+        fail: 0,
+    };
+    for c in checks {
+        match c.status {
+            Status::Pass => s.pass += 1,
+            Status::Warn => s.warn += 1,
+            Status::Fail => s.fail += 1,
+            Status::Info => {}
+        }
+    }
+    s
+}
+
+fn print_text(checks: &[Check], summary: &Summary, fixed: &[String], fix_ran: bool) {
+    println!("{}", color::bold("agent-browser doctor"));
+
+    let mut current_category = "";
+    for c in checks {
+        if c.category != current_category {
+            current_category = c.category;
+            println!();
+            println!("{}", color::bold(current_category));
+        }
+        println!("  {}  {}", c.status.label(), c.message);
+        if let Some(fix) = &c.fix {
+            println!("        {} {}", color::dim("fix:"), fix);
+        }
+    }
+
+    if !fixed.is_empty() {
+        println!();
+        println!("{}", color::bold("Fixed"));
+        for line in fixed {
+            println!("  {}  {}", color::green("done"), line);
+        }
+    }
+
+    println!();
+    let line = format!(
+        "Summary: {} pass, {} warn, {} fail",
+        summary.pass, summary.warn, summary.fail
+    );
+    if summary.fail > 0 {
+        println!("{}", color::red(&line));
+    } else if summary.warn > 0 {
+        println!("{}", color::yellow(&line));
+    } else {
+        println!("{}", color::green(&line));
+    }
+
+    if !fix_ran && checks.iter().any(|c| c.fix.is_some()) {
+        println!();
+        println!(
+            "{} Run with {} to attempt repairs.",
+            color::dim("tip:"),
+            color::bold("--fix")
+        );
+    }
+}
+
+fn print_json(checks: &[Check], summary: &Summary, fixed: &[String], success: bool) {
+    let checks_json: Vec<Value> = checks
+        .iter()
+        .map(|c| {
+            let mut obj = json!({
+                "id": c.id,
+                "category": c.category,
+                "status": c.status.as_str(),
+                "message": c.message,
+            });
+            if let Some(fix) = &c.fix {
+                obj["fix"] = json!(fix);
+            }
+            obj
+        })
+        .collect();
+
+    let payload = json!({
+        "success": success,
+        "summary": {
+            "pass": summary.pass,
+            "warn": summary.warn,
+            "fail": summary.fail,
+        },
+        "checks": checks_json,
+        "fixed": fixed,
+    });
+    println!("{}", payload);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_summary_counts_each_status() {
+        let checks = vec![
+            Check::new("a", "Cat", Status::Pass, "ok"),
+            Check::new("b", "Cat", Status::Pass, "ok"),
+            Check::new("c", "Cat", Status::Warn, "meh"),
+            Check::new("d", "Cat", Status::Fail, "no"),
+            Check::new("e", "Cat", Status::Info, "fyi"),
+        ];
+        let s = summarize(&checks);
+        assert_eq!(s.pass, 2);
+        assert_eq!(s.warn, 1);
+        assert_eq!(s.fail, 1);
+    }
+
+    #[test]
+    fn test_summary_zeroes_when_only_info() {
+        let checks = vec![Check::new("a", "Cat", Status::Info, "ignored")];
+        let s = summarize(&checks);
+        assert_eq!(s.pass, 0);
+        assert_eq!(s.warn, 0);
+        assert_eq!(s.fail, 0);
+    }
+
+    #[test]
+    fn test_status_label_does_not_panic() {
+        for s in &[Status::Pass, Status::Warn, Status::Fail, Status::Info] {
+            assert!(!s.label().is_empty());
+            assert!(!s.as_str().is_empty());
+        }
+    }
+
+    #[test]
+    fn test_status_as_str_values() {
+        assert_eq!(Status::Pass.as_str(), "pass");
+        assert_eq!(Status::Warn.as_str(), "warn");
+        assert_eq!(Status::Fail.as_str(), "fail");
+        assert_eq!(Status::Info.as_str(), "info");
+    }
+
+    #[test]
+    fn test_check_new_and_with_fix() {
+        let c = Check::new("id", "cat", Status::Warn, "msg").with_fix("do thing");
+        assert_eq!(c.id, "id");
+        assert_eq!(c.category, "cat");
+        assert_eq!(c.status, Status::Warn);
+        assert_eq!(c.message, "msg");
+        assert_eq!(c.fix.as_deref(), Some("do thing"));
+    }
+
+    #[test]
+    fn test_check_new_no_fix_by_default() {
+        let c = Check::new("id", "cat", Status::Pass, "msg");
+        assert!(c.fix.is_none());
+    }
+}

cli/src/doctor/network.rs

@@ -0,0 +1,154 @@
+//! Probe reachability of the Chrome for Testing CDN, AI Gateway (if
+//! configured), and the currently-selected provider endpoint. Each probe
+//! has a 3-second timeout.
+
+use std::env;
+use std::time::{Duration, Instant};
+
+use super::{Check, Status};
+
+pub(super) fn check(checks: &mut Vec<Check>) {
+    let category = "Network";
+
+    let rt = match tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+    {
+        Ok(r) => r,
+        Err(e) => {
+            checks.push(Check::new(
+                "net.runtime",
+                category,
+                Status::Fail,
+                format!("Could not start tokio runtime for probes: {}", e),
+            ));
+            return;
+        }
+    };
+
+    let client = match reqwest::Client::builder()
+        .user_agent(format!("agent-browser/{}", env!("CARGO_PKG_VERSION")))
+        .timeout(Duration::from_secs(3))
+        .connect_timeout(Duration::from_secs(3))
+        .build()
+    {
+        Ok(c) => c,
+        Err(e) => {
+            checks.push(Check::new(
+                "net.client",
+                category,
+                Status::Fail,
+                format!("Could not build HTTP client: {}", e),
+            ));
+            return;
+        }
+    };
+
+    let chrome_url =
+        "https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json";
+    probe_url(
+        &rt,
+        &client,
+        checks,
+        category,
+        "net.chrome_cdn",
+        chrome_url,
+        "Chrome for Testing CDN",
+    );
+
+    if env::var("AI_GATEWAY_API_KEY").is_ok() {
+        let url = env::var("AI_GATEWAY_URL")
+            .unwrap_or_else(|_| "https://ai-gateway.vercel.sh".to_string());
+        probe_url(
+            &rt,
+            &client,
+            checks,
+            category,
+            "net.ai_gateway",
+            &url,
+            "AI Gateway",
+        );
+    }
+
+    if let Ok(provider) = env::var("AGENT_BROWSER_PROVIDER") {
+        let url: Option<String> = match provider.to_lowercase().as_str() {
+            "browserbase" => Some("https://api.browserbase.com".to_string()),
+            "browserless" => Some(
+                env::var("BROWSERLESS_API_URL")
+                    .unwrap_or_else(|_| "https://production-sfo.browserless.io".to_string()),
+            ),
+            "browseruse" | "browser-use" => Some("https://api.browser-use.com".to_string()),
+            "kernel" => Some(
+                env::var("KERNEL_ENDPOINT")
+                    .unwrap_or_else(|_| "https://api.onkernel.com".to_string()),
+            ),
+            _ => None,
+        };
+        if let Some(url) = url {
+            probe_url(
+                &rt,
+                &client,
+                checks,
+                category,
+                "net.provider",
+                &url,
+                &format!("Provider {}", provider),
+            );
+        }
+    }
+}
+
+fn probe_url(
+    rt: &tokio::runtime::Runtime,
+    client: &reqwest::Client,
+    checks: &mut Vec<Check>,
+    category: &'static str,
+    id: &'static str,
+    url: &str,
+    label: &str,
+) {
+    let started = Instant::now();
+    let result = rt.block_on(async { client.head(url).send().await });
+    let elapsed_ms = started.elapsed().as_millis();
+    match result {
+        Ok(resp) => {
+            let status = resp.status();
+            if status.is_success() || status.is_redirection() || status.as_u16() == 405 {
+                checks.push(Check::new(
+                    id,
+                    category,
+                    Status::Pass,
+                    format!(
+                        "{} reachable ({}ms, HTTP {})",
+                        label,
+                        elapsed_ms,
+                        status.as_u16()
+                    ),
+                ));
+            } else {
+                checks.push(Check::new(
+                    id,
+                    category,
+                    Status::Warn,
+                    format!(
+                        "{} returned HTTP {} after {}ms",
+                        label,
+                        status.as_u16(),
+                        elapsed_ms
+                    ),
+                ));
+            }
+        }
+        Err(e) => {
+            checks.push(
+                Check::new(
+                    id,
+                    category,
+                    Status::Fail,
+                    format!("{} unreachable after {}ms: {}", label, elapsed_ms, e),
+                )
+                .with_fix("check network connectivity / firewall / proxy settings"),
+            );
+        }
+    }
+}

cli/src/doctor/providers.rs

@@ -0,0 +1,128 @@
+//! Check remote browser providers: API key presence for Browserless,
+//! Browserbase, Browser Use, Kernel, AgentCore (AWS), Appium for iOS, and
+//! the AI Gateway chat key. Info-level unless the provider is selected
+//! via `AGENT_BROWSER_PROVIDER`.
+
+use std::env;
+
+use super::helpers::which_exists;
+use super::{Check, Status};
+
+pub(super) fn check(checks: &mut Vec<Check>) {
+    let category = "Providers";
+
+    let active = env::var("AGENT_BROWSER_PROVIDER").ok();
+    let normalized = active
+        .as_ref()
+        .map(|s| s.to_lowercase())
+        .unwrap_or_default();
+
+    let active_status = |provider: &str, ok: bool| -> Status {
+        if normalized == provider {
+            if ok {
+                Status::Pass
+            } else {
+                Status::Fail
+            }
+        } else {
+            Status::Info
+        }
+    };
+
+    let providers: &[(&str, &[&str], &str)] = &[
+        ("browserless", &["BROWSERLESS_API_KEY"], "Browserless"),
+        ("browserbase", &["BROWSERBASE_API_KEY"], "Browserbase"),
+        ("browseruse", &["BROWSER_USE_API_KEY"], "Browser Use"),
+        ("kernel", &["KERNEL_API_KEY"], "Kernel"),
+    ];
+
+    for (id, env_keys, label) in providers {
+        let present = env_keys.iter().any(|k| env::var(k).is_ok());
+        let provider_id = *id;
+        let status = active_status(provider_id, present);
+        let msg = if present {
+            format!("{}: API key present", label)
+        } else {
+            format!("{}: {} not set", label, env_keys.join(" / "))
+        };
+        let mut check = Check::new(format!("providers.{}", provider_id), category, status, msg);
+        if status == Status::Fail {
+            check = check.with_fix(format!(
+                "set {} (or unset AGENT_BROWSER_PROVIDER={})",
+                env_keys.first().copied().unwrap_or(""),
+                provider_id
+            ));
+        }
+        checks.push(check);
+    }
+
+    let aws_present = env::var("AWS_ACCESS_KEY_ID").is_ok()
+        || env::var("AWS_PROFILE").is_ok()
+        || env::var("AWS_SESSION_TOKEN").is_ok();
+    let agentcore_status = active_status("agentcore", aws_present);
+    let mut agentcore_check = Check::new(
+        "providers.agentcore",
+        category,
+        agentcore_status,
+        if aws_present {
+            "AgentCore: AWS credentials resolvable".to_string()
+        } else {
+            "AgentCore: no AWS credentials in env (AWS_ACCESS_KEY_ID / AWS_PROFILE)".to_string()
+        },
+    );
+    if agentcore_status == Status::Fail {
+        agentcore_check = agentcore_check
+            .with_fix("export AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY or AWS_PROFILE");
+    }
+    checks.push(agentcore_check);
+
+    if normalized == "ios" {
+        if which_exists("appium") {
+            checks.push(Check::new(
+                "providers.ios",
+                category,
+                Status::Pass,
+                "iOS: appium binary on PATH",
+            ));
+        } else {
+            checks.push(
+                Check::new(
+                    "providers.ios",
+                    category,
+                    Status::Fail,
+                    "iOS: appium binary not found on PATH",
+                )
+                .with_fix("npm install -g appium && appium driver install xcuitest"),
+            );
+        }
+    }
+
+    let chat_key_present = env::var("AI_GATEWAY_API_KEY").is_ok();
+    if chat_key_present {
+        checks.push(Check::new(
+            "providers.chat",
+            category,
+            Status::Info,
+            "AI_GATEWAY_API_KEY present (chat enabled)",
+        ));
+    } else {
+        checks.push(
+            Check::new(
+                "providers.chat",
+                category,
+                Status::Info,
+                "AI_GATEWAY_API_KEY not set (chat command disabled)",
+            )
+            .with_fix("export AI_GATEWAY_API_KEY=gw_..."),
+        );
+    }
+
+    if let Some(active) = active {
+        checks.push(Check::new(
+            "providers.active",
+            category,
+            Status::Info,
+            format!("AGENT_BROWSER_PROVIDER = {}", active),
+        ));
+    }
+}

cli/src/doctor/security.rs

@@ -0,0 +1,167 @@
+//! Check security posture: encryption key presence / permissions, saved
+//! state file age, and the optional action policy file.
+
+use std::env;
+use std::fs;
+use std::path::PathBuf;
+use std::time::{Duration, SystemTime};
+
+#[cfg(unix)]
+use std::os::unix::fs::PermissionsExt;
+
+use super::helpers::parse_json_file;
+use super::{Check, Status};
+use crate::native::state::{get_sessions_dir, get_state_dir};
+
+pub(super) fn check(checks: &mut Vec<Check>) {
+    let category = "Security";
+
+    let key_env = env::var("AGENT_BROWSER_ENCRYPTION_KEY").ok();
+    let key_file = get_state_dir().join(".encryption-key");
+    if let Some(hex) = &key_env {
+        if hex.len() == 64 && hex.chars().all(|c| c.is_ascii_hexdigit()) {
+            checks.push(Check::new(
+                "security.encryption_key",
+                category,
+                Status::Pass,
+                "AGENT_BROWSER_ENCRYPTION_KEY set (64-char hex)",
+            ));
+        } else {
+            checks.push(
+                Check::new(
+                    "security.encryption_key",
+                    category,
+                    Status::Fail,
+                    "AGENT_BROWSER_ENCRYPTION_KEY is not a 64-char hex string",
+                )
+                .with_fix("export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)"),
+            );
+        }
+    } else if key_file.exists() {
+        let mut msg = format!("Encryption key file present: {}", key_file.display());
+        let mut status = Status::Pass;
+        let mut fix: Option<String> = None;
+        #[cfg(unix)]
+        if let Ok(meta) = fs::metadata(&key_file) {
+            let mode = meta.permissions().mode() & 0o777;
+            if mode & 0o077 != 0 {
+                status = Status::Warn;
+                msg = format!(
+                    "Encryption key file is too permissive ({:o}): {}",
+                    mode,
+                    key_file.display()
+                );
+                fix = Some(format!("chmod 600 {}", key_file.display()));
+            }
+        }
+        let mut check = Check::new("security.encryption_key", category, status, msg);
+        if let Some(f) = fix {
+            check = check.with_fix(f);
+        }
+        checks.push(check);
+    } else {
+        checks.push(
+            Check::new(
+                "security.encryption_key",
+                category,
+                Status::Info,
+                "No encryption key set (will be auto-generated on first auth save)",
+            )
+            .with_fix("export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)"),
+        );
+    }
+
+    let sessions_dir = get_sessions_dir();
+    if sessions_dir.exists() {
+        let expire_days = env::var("AGENT_BROWSER_STATE_EXPIRE_DAYS")
+            .ok()
+            .and_then(|s| s.parse::<u64>().ok())
+            .unwrap_or(30);
+        let cutoff = SystemTime::now()
+            .checked_sub(Duration::from_secs(expire_days * 86_400))
+            .unwrap_or(SystemTime::UNIX_EPOCH);
+        let mut total = 0usize;
+        let mut old = 0usize;
+        if let Ok(entries) = fs::read_dir(&sessions_dir) {
+            for entry in entries.flatten() {
+                if entry.file_type().map(|t| t.is_file()).unwrap_or(false) {
+                    total += 1;
+                    if let Ok(meta) = entry.metadata() {
+                        if let Ok(modified) = meta.modified() {
+                            if modified < cutoff {
+                                old += 1;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        if total == 0 {
+            checks.push(Check::new(
+                "security.state_count",
+                category,
+                Status::Info,
+                "No saved state files",
+            ));
+        } else if old > 0 {
+            checks.push(
+                Check::new(
+                    "security.state_count",
+                    category,
+                    Status::Warn,
+                    format!(
+                        "{} state file(s) older than {} days ({} total)",
+                        old, expire_days, total
+                    ),
+                )
+                .with_fix(format!(
+                    "agent-browser state clean --older-than {}",
+                    expire_days
+                )),
+            );
+        } else {
+            checks.push(Check::new(
+                "security.state_count",
+                category,
+                Status::Pass,
+                format!("{} saved state file(s)", total),
+            ));
+        }
+    }
+
+    if let Ok(policy_path) = env::var("AGENT_BROWSER_ACTION_POLICY") {
+        let p = PathBuf::from(&policy_path);
+        if !p.exists() {
+            checks.push(
+                Check::new(
+                    "security.action_policy",
+                    category,
+                    Status::Fail,
+                    format!(
+                        "AGENT_BROWSER_ACTION_POLICY points to missing file: {}",
+                        policy_path
+                    ),
+                )
+                .with_fix("update or unset AGENT_BROWSER_ACTION_POLICY"),
+            );
+        } else {
+            match parse_json_file(&p) {
+                Ok(_) => checks.push(Check::new(
+                    "security.action_policy",
+                    category,
+                    Status::Pass,
+                    format!("Action policy: {}", policy_path),
+                )),
+                Err(e) => checks.push(
+                    Check::new(
+                        "security.action_policy",
+                        category,
+                        Status::Fail,
+                        format!("Action policy: {}: {}", policy_path, e),
+                    )
+                    .with_fix(format!("edit {}", policy_path)),
+                ),
+            }
+        }
+    }
+}

cli/src/native/auth.rs

@@ -0,0 +1,556 @@
+use aes_gcm::{aead::Aead, aead::KeyInit, Aes256Gcm};
+use base64::{engine::general_purpose::STANDARD, Engine};
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
+use std::fs;
+use std::io::Write;
+use std::path::PathBuf;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AuthProfile {
+    pub name: String,
+    pub url: String,
+    pub username: String,
+    pub password: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub username_selector: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub password_selector: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub submit_selector: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub created_at: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub last_login_at: Option<String>,
+}
+
+// Keep legacy Credential alias for backward compatibility
+pub type Credential = AuthProfile;
+
+fn validate_profile_name(name: &str) -> Result<(), String> {
+    if name.is_empty()
+        || !name
+            .chars()
+            .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
+    {
+        return Err(format!(
+            "Invalid profile name '{}'. Must match /^[a-zA-Z0-9_-]+$/",
+            name
+        ));
+    }
+    Ok(())
+}
+
+fn get_auth_dir() -> PathBuf {
+    if let Some(home) = dirs::home_dir() {
+        home.join(".agent-browser").join("auth")
+    } else {
+        std::env::temp_dir().join("agent-browser").join("auth")
+    }
+}
+
+fn get_profile_path(name: &str) -> PathBuf {
+    get_auth_dir().join(format!("{}.json", name))
+}
+
+const ENCRYPTION_KEY_ENV: &str = "AGENT_BROWSER_ENCRYPTION_KEY";
+const KEY_FILE_NAME: &str = ".encryption-key";
+
+fn get_agent_browser_dir() -> PathBuf {
+    if let Some(home) = dirs::home_dir() {
+        home.join(".agent-browser")
+    } else {
+        std::env::temp_dir().join("agent-browser")
+    }
+}
+
+fn get_key_file_path() -> PathBuf {
+    get_agent_browser_dir().join(KEY_FILE_NAME)
+}
+
+fn parse_key_hex(hex_str: &str) -> Option<Vec<u8>> {
+    let hex_str = hex_str.trim();
+    if hex_str.len() != 64 || !hex_str.chars().all(|c| c.is_ascii_hexdigit()) {
+        return None;
+    }
+    let bytes: Vec<u8> = (0..32)
+        .map(|i| u8::from_str_radix(&hex_str[i * 2..i * 2 + 2], 16).unwrap())
+        .collect();
+    Some(bytes)
+}
+
+/// Read the encryption key from AGENT_BROWSER_ENCRYPTION_KEY env var or
+/// ~/.agent-browser/.encryption-key file (matching the Node.js implementation).
+fn get_encryption_key() -> Result<Vec<u8>, String> {
+    if let Ok(key_hex) = std::env::var(ENCRYPTION_KEY_ENV) {
+        return parse_key_hex(&key_hex).ok_or_else(|| {
+            format!(
+                "{} should be a 64-character hex string (256 bits). Generate one with: openssl rand -hex 32",
+                ENCRYPTION_KEY_ENV
+            )
+        });
+    }
+
+    let key_file = get_key_file_path();
+    if key_file.exists() {
+        let hex = fs::read_to_string(&key_file)
+            .map_err(|e| format!("Failed to read encryption key file: {}", e))?;
+        return parse_key_hex(&hex).ok_or_else(|| {
+            format!(
+                "Invalid encryption key in {}. Expected 64-character hex string.",
+                key_file.display()
+            )
+        });
+    }
+
+    Err(format!(
+        "Encryption key required. Set {} or ensure {} exists.",
+        ENCRYPTION_KEY_ENV,
+        key_file.display()
+    ))
+}
+
+/// Ensure an encryption key exists, auto-generating one if needed.
+fn ensure_encryption_key() -> Result<Vec<u8>, String> {
+    if let Ok(key) = get_encryption_key() {
+        return Ok(key);
+    }
+
+    let mut key = [0u8; 32];
+    getrandom::getrandom(&mut key).map_err(|e| format!("Failed to generate key: {}", e))?;
+    let key_hex = key.iter().map(|b| format!("{:02x}", b)).collect::<String>();
+
+    let dir = get_agent_browser_dir();
+    fs::create_dir_all(&dir).map_err(|e| format!("Failed to create directory: {}", e))?;
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let _ = fs::set_permissions(&dir, fs::Permissions::from_mode(0o700));
+    }
+
+    let key_file = get_key_file_path();
+    fs::write(&key_file, format!("{}\n", key_hex))
+        .map_err(|e| format!("Failed to write encryption key: {}", e))?;
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let _ = fs::set_permissions(&key_file, fs::Permissions::from_mode(0o600));
+    }
+
+    let _ = writeln!(
+        std::io::stderr(),
+        "[agent-browser] Auto-generated encryption key at {} -- back up this file or set {}",
+        key_file.display(),
+        ENCRYPTION_KEY_ENV
+    );
+
+    Ok(key.to_vec())
+}
+
+/// Encrypt a profile to the JSON+base64 format compatible with Node.js.
+fn encrypt_profile(profile: &AuthProfile) -> Result<String, String> {
+    let key = ensure_encryption_key()?;
+    let cipher =
+        Aes256Gcm::new_from_slice(&key).map_err(|e| format!("Encryption key error: {}", e))?;
+
+    let plaintext = serde_json::to_string(profile)
+        .map_err(|e| format!("Failed to serialize profile: {}", e))?;
+
+    let mut iv = [0u8; 12];
+    getrandom::getrandom(&mut iv).map_err(|e| format!("Failed to generate IV: {}", e))?;
+
+    // aes_gcm appends the 16-byte auth tag to the ciphertext
+    let encrypted = cipher
+        .encrypt(aes_gcm::Nonce::from_slice(&iv), plaintext.as_bytes())
+        .map_err(|e| format!("Encryption failed: {}", e))?;
+
+    let tag_offset = encrypted.len() - 16;
+    let ciphertext = &encrypted[..tag_offset];
+    let auth_tag = &encrypted[tag_offset..];
+
+    let payload = json!({
+        "version": 1,
+        "encrypted": true,
+        "iv": STANDARD.encode(iv),
+        "authTag": STANDARD.encode(auth_tag),
+        "data": STANDARD.encode(ciphertext),
+    });
+
+    serde_json::to_string_pretty(&payload)
+        .map_err(|e| format!("Failed to serialize payload: {}", e))
+}
+
+/// JSON envelope written by Node.js encryption (src/encryption.ts).
+#[derive(Deserialize)]
+struct EncryptedPayload {
+    #[allow(dead_code)]
+    version: u32,
+    #[allow(dead_code)]
+    encrypted: bool,
+    iv: String,
+    #[serde(rename = "authTag")]
+    auth_tag: String,
+    data: String,
+}
+
+fn decrypt_profile(data: &[u8]) -> Result<AuthProfile, String> {
+    let text = std::str::from_utf8(data).map_err(|_| {
+        "Profile is not valid UTF-8 -- it may use an older incompatible binary format".to_string()
+    })?;
+
+    if let Ok(payload) = serde_json::from_str::<EncryptedPayload>(text) {
+        let key = get_encryption_key()?;
+
+        let iv = STANDARD
+            .decode(&payload.iv)
+            .map_err(|e| format!("Invalid base64 iv: {}", e))?;
+        let auth_tag = STANDARD
+            .decode(&payload.auth_tag)
+            .map_err(|e| format!("Invalid base64 authTag: {}", e))?;
+        let ciphertext = STANDARD
+            .decode(&payload.data)
+            .map_err(|e| format!("Invalid base64 data: {}", e))?;
+
+        // aes_gcm expects ciphertext || auth_tag as input to decrypt
+        let mut combined = Vec::with_capacity(ciphertext.len() + auth_tag.len());
+        combined.extend_from_slice(&ciphertext);
+        combined.extend_from_slice(&auth_tag);
+
+        let cipher =
+            Aes256Gcm::new_from_slice(&key).map_err(|e| format!("Decryption key error: {}", e))?;
+        let plaintext = cipher
+            .decrypt(aes_gcm::Nonce::from_slice(&iv), combined.as_slice())
+            .map_err(|e| format!("Decryption failed: {}", e))?;
+
+        let json_str = String::from_utf8(plaintext)
+            .map_err(|e| format!("Decrypted data is not valid UTF-8: {}", e))?;
+        return serde_json::from_str(&json_str).map_err(|e| format!("Invalid profile data: {}", e));
+    }
+
+    // Fallback: try as plain unencrypted JSON profile
+    serde_json::from_str::<AuthProfile>(text)
+        .map_err(|_| "Profile is not a valid encrypted or unencrypted payload".to_string())
+}
+
+fn save_profile(profile: &AuthProfile) -> Result<(), String> {
+    let dir = get_auth_dir();
+    fs::create_dir_all(&dir).map_err(|e| format!("Failed to create auth dir: {}", e))?;
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let _ = fs::set_permissions(&dir, fs::Permissions::from_mode(0o700));
+    }
+
+    let encrypted_json = encrypt_profile(profile)?;
+    let path = get_profile_path(&profile.name);
+    fs::write(&path, &encrypted_json).map_err(|e| format!("Failed to write profile: {}", e))?;
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let _ = fs::set_permissions(&path, fs::Permissions::from_mode(0o600));
+    }
+    Ok(())
+}
+
+fn load_profile(name: &str) -> Result<AuthProfile, String> {
+    let path = get_profile_path(name);
+    if !path.exists() {
+        return Err(format!("Auth profile '{}' not found", name));
+    }
+    let data = fs::read(&path).map_err(|e| format!("Failed to read profile: {}", e))?;
+    decrypt_profile(&data)
+}
+
+pub fn credentials_set(
+    name: &str,
+    username: &str,
+    password: &str,
+    url: Option<&str>,
+) -> Result<Value, String> {
+    validate_profile_name(name)?;
+    let profile = AuthProfile {
+        name: name.to_string(),
+        url: url.unwrap_or("").to_string(),
+        username: username.to_string(),
+        password: password.to_string(),
+        username_selector: None,
+        password_selector: None,
+        submit_selector: None,
+        created_at: None,
+        last_login_at: None,
+    };
+    save_profile(&profile)?;
+    Ok(json!({ "saved": name }))
+}
+
+pub fn auth_save(
+    name: &str,
+    url: &str,
+    username: &str,
+    password: &str,
+    username_selector: Option<&str>,
+    password_selector: Option<&str>,
+    submit_selector: Option<&str>,
+) -> Result<Value, String> {
+    validate_profile_name(name)?;
+    let profile = AuthProfile {
+        name: name.to_string(),
+        url: url.to_string(),
+        username: username.to_string(),
+        password: password.to_string(),
+        username_selector: username_selector.map(String::from),
+        password_selector: password_selector.map(String::from),
+        submit_selector: submit_selector.map(String::from),
+        created_at: None,
+        last_login_at: None,
+    };
+    save_profile(&profile)?;
+    Ok(json!({ "saved": name }))
+}
+
+pub fn credentials_get(name: &str) -> Result<Value, String> {
+    let profile = load_profile(name)?;
+    Ok(json!({
+        "name": profile.name,
+        "username": profile.username,
+        "url": profile.url,
+        "hasPassword": true,
+    }))
+}
+
+pub fn credentials_get_full(name: &str) -> Result<AuthProfile, String> {
+    load_profile(name)
+}
+
+pub fn credentials_delete(name: &str) -> Result<Value, String> {
+    validate_profile_name(name)?;
+    let path = get_profile_path(name);
+    if !path.exists() {
+        return Err(format!("Auth profile '{}' not found", name));
+    }
+    fs::remove_file(&path).map_err(|e| format!("Failed to delete profile: {}", e))?;
+    Ok(json!({ "deleted": name }))
+}
+
+pub fn credentials_list() -> Result<Value, String> {
+    let dir = get_auth_dir();
+    if !dir.exists() {
+        return Ok(json!({ "profiles": [] }));
+    }
+
+    let mut profiles = Vec::new();
+    if let Ok(entries) = fs::read_dir(&dir) {
+        for entry in entries.flatten() {
+            let path = entry.path();
+            if path.extension().and_then(|e| e.to_str()) != Some("json") {
+                continue;
+            }
+            let name = path
+                .file_stem()
+                .unwrap_or_default()
+                .to_string_lossy()
+                .to_string();
+            match load_profile(&name) {
+                Ok(profile) => {
+                    profiles.push(json!({
+                        "name": profile.name,
+                        "username": profile.username,
+                        "url": profile.url,
+                    }));
+                }
+                Err(_) => {
+                    profiles.push(json!({
+                        "name": name,
+                        "error": "Failed to decrypt",
+                    }));
+                }
+            }
+        }
+    }
+    Ok(json!({ "profiles": profiles }))
+}
+
+pub fn auth_show(name: &str) -> Result<Value, String> {
+    validate_profile_name(name)?;
+    let profile = load_profile(name)?;
+    Ok(json!({
+        "profile": {
+            "name": profile.name,
+            "url": profile.url,
+            "username": profile.username,
+            "usernameSelector": profile.username_selector,
+            "passwordSelector": profile.password_selector,
+            "submitSelector": profile.submit_selector,
+        }
+    }))
+}
+
+#[cfg(test)]
+pub(crate) static AUTH_TEST_MUTEX: std::sync::Mutex<()> = std::sync::Mutex::new(());
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn with_test_key<F: FnOnce()>(f: F) {
+        let _lock = AUTH_TEST_MUTEX.lock().unwrap();
+        let original = std::env::var(ENCRYPTION_KEY_ENV).ok();
+        let test_key = "a".repeat(64);
+        // SAFETY: TEST_MUTEX serializes all test access so no concurrent mutation.
+        unsafe { std::env::set_var(ENCRYPTION_KEY_ENV, &test_key) };
+        f();
+        // SAFETY: TEST_MUTEX serializes all test access so no concurrent mutation.
+        match original {
+            Some(val) => unsafe { std::env::set_var(ENCRYPTION_KEY_ENV, val) },
+            None => unsafe { std::env::remove_var(ENCRYPTION_KEY_ENV) },
+        }
+    }
+
+    #[test]
+    fn test_validate_profile_name() {
+        assert!(validate_profile_name("github").is_ok());
+        assert!(validate_profile_name("my-app").is_ok());
+        assert!(validate_profile_name("test_123").is_ok());
+        assert!(validate_profile_name("").is_err());
+        assert!(validate_profile_name("has space").is_err());
+        assert!(validate_profile_name("../evil").is_err());
+        assert!(validate_profile_name("foo/bar").is_err());
+    }
+
+    #[test]
+    fn test_auth_profile_serialization() {
+        let profile = AuthProfile {
+            name: "test".to_string(),
+            url: "https://example.com".to_string(),
+            username: "user".to_string(),
+            password: "pass".to_string(),
+            username_selector: None,
+            password_selector: None,
+            submit_selector: Some("button[type=submit]".to_string()),
+            created_at: None,
+            last_login_at: None,
+        };
+        let json = serde_json::to_string(&profile).unwrap();
+        let parsed: AuthProfile = serde_json::from_str(&json).unwrap();
+        assert_eq!(parsed.name, "test");
+        assert_eq!(
+            parsed.submit_selector,
+            Some("button[type=submit]".to_string())
+        );
+        assert!(parsed.username_selector.is_none());
+    }
+
+    #[test]
+    fn test_encrypt_decrypt_roundtrip() {
+        with_test_key(|| {
+            let profile = AuthProfile {
+                name: "roundtrip".to_string(),
+                url: "https://example.com".to_string(),
+                username: "user".to_string(),
+                password: "s3cret!".to_string(),
+                username_selector: None,
+                password_selector: None,
+                submit_selector: None,
+                created_at: None,
+                last_login_at: None,
+            };
+            let encrypted_json = encrypt_profile(&profile).unwrap();
+            let decrypted = decrypt_profile(encrypted_json.as_bytes()).unwrap();
+            assert_eq!(decrypted.name, "roundtrip");
+            assert_eq!(decrypted.password, "s3cret!");
+        });
+    }
+
+    #[test]
+    fn test_get_encryption_key_from_env() {
+        with_test_key(|| {
+            let key = get_encryption_key().unwrap();
+            assert_eq!(key.len(), 32);
+            assert!(key.iter().all(|&b| b == 0xaa));
+        });
+    }
+
+    #[test]
+    fn test_parse_key_hex_valid() {
+        let hex = "ab".repeat(32);
+        let key = parse_key_hex(&hex).unwrap();
+        assert_eq!(key.len(), 32);
+        assert!(key.iter().all(|&b| b == 0xab));
+    }
+
+    #[test]
+    fn test_parse_key_hex_invalid() {
+        assert!(parse_key_hex("too_short").is_none());
+        assert!(parse_key_hex(&"g".repeat(64)).is_none());
+        assert!(parse_key_hex("").is_none());
+    }
+
+    #[test]
+    fn test_decrypt_json_payload_format() {
+        with_test_key(|| {
+            let key = get_encryption_key().unwrap();
+            let profile = AuthProfile {
+                name: "json-test".to_string(),
+                url: "https://example.com/login".to_string(),
+                username: "admin".to_string(),
+                password: "hunter2".to_string(),
+                username_selector: Some("#email".to_string()),
+                password_selector: None,
+                submit_selector: None,
+                created_at: None,
+                last_login_at: None,
+            };
+
+            // Encrypt with aes_gcm, then manually build the JSON payload
+            // to simulate what Node.js would produce
+            let cipher = Aes256Gcm::new_from_slice(&key).unwrap();
+            let mut iv = [0u8; 12];
+            getrandom::getrandom(&mut iv).unwrap();
+            let plaintext = serde_json::to_string(&profile).unwrap();
+            let encrypted = cipher
+                .encrypt(aes_gcm::Nonce::from_slice(&iv), plaintext.as_bytes())
+                .unwrap();
+
+            let tag_offset = encrypted.len() - 16;
+            let ciphertext = &encrypted[..tag_offset];
+            let auth_tag = &encrypted[tag_offset..];
+
+            let payload = format!(
+                r#"{{"version":1,"encrypted":true,"iv":"{}","authTag":"{}","data":"{}"}}"#,
+                STANDARD.encode(iv),
+                STANDARD.encode(auth_tag),
+                STANDARD.encode(ciphertext),
+            );
+
+            let decrypted = decrypt_profile(payload.as_bytes()).unwrap();
+            assert_eq!(decrypted.name, "json-test");
+            assert_eq!(decrypted.password, "hunter2");
+            assert_eq!(decrypted.username_selector, Some("#email".to_string()));
+        });
+    }
+
+    #[test]
+    fn test_encrypted_output_is_json_format() {
+        with_test_key(|| {
+            let profile = AuthProfile {
+                name: "format-check".to_string(),
+                url: "https://example.com".to_string(),
+                username: "user".to_string(),
+                password: "pass".to_string(),
+                username_selector: None,
+                password_selector: None,
+                submit_selector: None,
+                created_at: None,
+                last_login_at: None,
+            };
+            let encrypted = encrypt_profile(&profile).unwrap();
+            let parsed: Value = serde_json::from_str(&encrypted).unwrap();
+            assert_eq!(parsed["version"], 1);
+            assert_eq!(parsed["encrypted"], true);
+            assert!(parsed["iv"].is_string());
+            assert!(parsed["authTag"].is_string());
+            assert!(parsed["data"].is_string());
+        });
+    }
+}

cli/src/native/cdp/client.rs

@@ -0,0 +1,361 @@
+use std::collections::HashMap;
+use std::io::Write;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Arc;
+
+use futures_util::{SinkExt, StreamExt};
+use serde_json::Value;
+use tokio::sync::{broadcast, oneshot, Mutex};
+use tokio_tungstenite::tungstenite::client::IntoClientRequest;
+use tokio_tungstenite::tungstenite::protocol::WebSocketConfig;
+use tokio_tungstenite::tungstenite::Message;
+
+use super::types::{CdpCommand, CdpEvent, CdpMessage};
+
+type PendingMap = Arc<Mutex<HashMap<u64, oneshot::Sender<CdpMessage>>>>;
+
+/// Interval between WebSocket ping frames sent to keep the connection alive
+/// through intermediate proxies (reverse proxies, load balancers, service meshes).
+const WS_KEEPALIVE_INTERVAL_SECS: u64 = 30;
+
+/// Raw incoming CDP message (text) broadcast to all subscribers.
+/// Used by the inspect proxy to forward responses and events to DevTools.
+#[derive(Debug, Clone)]
+pub struct RawCdpMessage {
+    pub text: String,
+    pub session_id: Option<String>,
+}
+
+pub struct CdpClient {
+    ws_tx: Arc<
+        Mutex<
+            futures_util::stream::SplitSink<
+                tokio_tungstenite::WebSocketStream<
+                    tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>,
+                >,
+                Message,
+            >,
+        >,
+    >,
+    next_id: AtomicU64,
+    pending: PendingMap,
+    event_tx: broadcast::Sender<CdpEvent>,
+    raw_tx: broadcast::Sender<RawCdpMessage>,
+    _reader_handle: tokio::task::JoinHandle<()>,
+    _keepalive_handle: tokio::task::JoinHandle<()>,
+}
+
+impl CdpClient {
+    pub async fn connect(url: &str) -> Result<Self, String> {
+        Self::connect_with_headers(url, None).await
+    }
+
+    pub async fn connect_with_headers(
+        url: &str,
+        headers: Option<Vec<(String, String)>>,
+    ) -> Result<Self, String> {
+        let mut request = url
+            .into_client_request()
+            .map_err(|e| format!("Invalid WebSocket URL: {}", e))?;
+
+        if let Some(hdrs) = headers {
+            let req_headers = request.headers_mut();
+            for (key, value) in hdrs {
+                if let (Ok(name), Ok(val)) = (
+                    key.parse::<tokio_tungstenite::tungstenite::http::header::HeaderName>(),
+                    value.parse::<tokio_tungstenite::tungstenite::http::header::HeaderValue>(),
+                ) {
+                    req_headers.insert(name, val);
+                }
+            }
+        }
+
+        let ws_config = WebSocketConfig {
+            max_message_size: None,
+            max_frame_size: None,
+            ..Default::default()
+        };
+
+        let (ws_stream, _) =
+            tokio_tungstenite::connect_async_with_config(request, Some(ws_config), false)
+                .await
+                .map_err(|e| format!("CDP WebSocket connect failed: {}", e))?;
+
+        enable_tcp_keepalive(ws_stream.get_ref());
+
+        let (ws_tx, mut ws_rx) = ws_stream.split();
+        let ws_tx = Arc::new(Mutex::new(ws_tx));
+
+        let pending: PendingMap = Arc::new(Mutex::new(HashMap::new()));
+        let (event_tx, _) = broadcast::channel(4096);
+        let (raw_tx, _) = broadcast::channel(4096);
+
+        let pending_clone = pending.clone();
+        let event_tx_clone = event_tx.clone();
+        let raw_tx_clone = raw_tx.clone();
+
+        // Notify used to stop the keepalive task when the reader loop exits.
+        let (cancel_tx, mut cancel_rx) = tokio::sync::watch::channel(false);
+
+        let reader_handle = tokio::spawn(async move {
+            while let Some(msg) = ws_rx.next().await {
+                // Accept both Text and Binary frames — remote CDP proxies
+                // (e.g. Browserless) may send responses as Binary frames.
+                let msg = match msg {
+                    Ok(Message::Text(text)) => text,
+                    Ok(Message::Binary(data)) => match String::from_utf8(data) {
+                        Ok(text) => text,
+                        Err(_) => continue,
+                    },
+                    Ok(Message::Close(frame)) => {
+                        if std::env::var("AGENT_BROWSER_DEBUG").is_ok() {
+                            let reason = frame
+                                .as_ref()
+                                .map(|f| format!("code={}, reason={}", f.code, f.reason))
+                                .unwrap_or_else(|| "no frame".to_string());
+                            let _ =
+                                writeln!(std::io::stderr(), "[cdp] WebSocket Close: {}", reason);
+                        }
+                        break;
+                    }
+                    Ok(Message::Pong(_)) => continue,
+                    Ok(_) => continue,
+                    Err(e) => {
+                        if std::env::var("AGENT_BROWSER_DEBUG").is_ok() {
+                            let _ = writeln!(std::io::stderr(), "[cdp] WebSocket Error: {}", e);
+                        }
+                        break;
+                    }
+                };
+
+                // Broadcast raw message for inspect proxy subscribers before typed parse,
+                // so messages with negative IDs (used by the inspect proxy) are still delivered.
+                if raw_tx_clone.receiver_count() > 0 {
+                    let session_id = serde_json::from_str::<serde_json::Value>(&msg)
+                        .ok()
+                        .and_then(|v| v.get("sessionId")?.as_str().map(String::from));
+                    let _ = raw_tx_clone.send(RawCdpMessage {
+                        text: msg.clone(),
+                        session_id,
+                    });
+                }
+
+                let parsed: CdpMessage = match serde_json::from_str(&msg) {
+                    Ok(m) => m,
+                    // Expected for inspect proxy messages with negative IDs
+                    // (CdpMessage.id is u64); handled via raw broadcast above.
+                    Err(_) => continue,
+                };
+
+                if let Some(id) = parsed.id {
+                    // Response to a command
+                    let mut pending = pending_clone.lock().await;
+                    if let Some(tx) = pending.remove(&id) {
+                        let _ = tx.send(parsed);
+                    }
+                } else if let Some(ref method) = parsed.method {
+                    // Event
+                    let event = CdpEvent {
+                        method: method.clone(),
+                        params: parsed.params.clone().unwrap_or(Value::Null),
+                        session_id: parsed.session_id.clone(),
+                    };
+                    let _ = event_tx_clone.send(event);
+                }
+            }
+
+            // Reader loop exited (connection closed or error). Drop all pending
+            // command senders so callers get an immediate channel-closed error
+            // instead of waiting for the 30-second timeout.
+            pending_clone.lock().await.clear();
+
+            // Stop the keepalive task — the connection is gone.
+            let _ = cancel_tx.send(true);
+        });
+
+        // Spawn a keepalive task that sends WebSocket Ping frames at a regular
+        // interval. This prevents intermediate proxies (Envoy, nginx, OpenResty,
+        // cloud load balancers) from closing idle WebSocket connections. If the
+        // send fails, the connection is dead and we stop pinging.
+        let keepalive_tx = ws_tx.clone();
+        let keepalive_handle = tokio::spawn(async move {
+            let interval = std::time::Duration::from_secs(WS_KEEPALIVE_INTERVAL_SECS);
+            loop {
+                tokio::select! {
+                    _ = tokio::time::sleep(interval) => {}
+                    _ = cancel_rx.changed() => break,
+                }
+                let mut tx = keepalive_tx.lock().await;
+                if tx.send(Message::Ping(Vec::new())).await.is_err() {
+                    break;
+                }
+            }
+        });
+
+        Ok(Self {
+            ws_tx,
+            next_id: AtomicU64::new(1),
+            pending,
+            event_tx,
+            raw_tx,
+            _reader_handle: reader_handle,
+            _keepalive_handle: keepalive_handle,
+        })
+    }
+
+    pub async fn send_command(
+        &self,
+        method: &str,
+        params: Option<Value>,
+        session_id: Option<&str>,
+    ) -> Result<Value, String> {
+        let id = self.next_id.fetch_add(1, Ordering::SeqCst);
+
+        let cmd = CdpCommand {
+            id,
+            method: method.to_string(),
+            params,
+            session_id: session_id.filter(|s| !s.is_empty()).map(|s| s.to_string()),
+        };
+
+        let json = serde_json::to_string(&cmd)
+            .map_err(|e| format!("Failed to serialize CDP command: {}", e))?;
+
+        let (tx, rx) = oneshot::channel();
+
+        {
+            let mut pending = self.pending.lock().await;
+            pending.insert(id, tx);
+        }
+
+        {
+            let mut ws_tx = self.ws_tx.lock().await;
+            ws_tx
+                .send(Message::Text(json))
+                .await
+                .map_err(|e| format!("Failed to send CDP command: {}", e))?;
+        }
+
+        let response = match tokio::time::timeout(std::time::Duration::from_secs(30), rx).await {
+            Ok(Ok(resp)) => resp,
+            Ok(Err(_)) => return Err("CDP response channel closed".to_string()),
+            Err(_) => {
+                self.pending.lock().await.remove(&id);
+                return Err(format!("CDP command timed out: {}", method));
+            }
+        };
+
+        if let Some(error) = response.error {
+            return Err(format!("CDP error ({}): {}", method, error));
+        }
+
+        Ok(response.result.unwrap_or(Value::Null))
+    }
+
+    pub fn subscribe(&self) -> broadcast::Receiver<CdpEvent> {
+        self.event_tx.subscribe()
+    }
+
+    /// Subscribe to all raw incoming CDP messages (responses + events).
+    /// Used by the inspect proxy to forward traffic to the DevTools frontend.
+    pub fn subscribe_raw(&self) -> broadcast::Receiver<RawCdpMessage> {
+        self.raw_tx.subscribe()
+    }
+
+    /// Create a lightweight handle for the inspect WebSocket proxy.
+    /// Contains only what's needed to forward messages bidirectionally.
+    pub fn inspect_handle(&self) -> InspectProxyHandle {
+        InspectProxyHandle {
+            ws_tx: self.ws_tx.clone(),
+            raw_tx: self.raw_tx.clone(),
+        }
+    }
+
+    pub async fn send_command_typed<P: serde::Serialize, R: serde::de::DeserializeOwned>(
+        &self,
+        method: &str,
+        params: &P,
+        session_id: Option<&str>,
+    ) -> Result<R, String> {
+        let params_value = serde_json::to_value(params)
+            .map_err(|e| format!("Failed to serialize params: {}", e))?;
+        let result = self
+            .send_command(method, Some(params_value), session_id)
+            .await?;
+        serde_json::from_value(result)
+            .map_err(|e| format!("Failed to deserialize CDP response for {}: {}", method, e))
+    }
+
+    pub async fn send_command_no_params(
+        &self,
+        method: &str,
+        session_id: Option<&str>,
+    ) -> Result<Value, String> {
+        self.send_command(method, None, session_id).await
+    }
+
+    /// Send raw JSON through the WebSocket without tracking a response.
+    /// Used by the inspect proxy to forward DevTools frontend messages.
+    pub async fn send_raw(&self, json: String) -> Result<(), String> {
+        let mut ws_tx = self.ws_tx.lock().await;
+        ws_tx
+            .send(Message::Text(json))
+            .await
+            .map_err(|e| format!("Failed to send raw CDP message: {}", e))
+    }
+}
+
+type WsTx = Arc<
+    Mutex<
+        futures_util::stream::SplitSink<
+            tokio_tungstenite::WebSocketStream<
+                tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>,
+            >,
+            Message,
+        >,
+    >,
+>;
+
+/// Lightweight handle for the inspect WebSocket proxy, holding only
+/// the cloneable parts of CdpClient needed for bidirectional message forwarding.
+pub struct InspectProxyHandle {
+    ws_tx: WsTx,
+    raw_tx: broadcast::Sender<RawCdpMessage>,
+}
+
+impl InspectProxyHandle {
+    pub async fn send_raw(&self, json: String) -> Result<(), String> {
+        let mut ws_tx = self.ws_tx.lock().await;
+        ws_tx
+            .send(Message::Text(json))
+            .await
+            .map_err(|e| format!("Failed to send raw CDP message: {}", e))
+    }
+
+    pub fn subscribe_raw(&self) -> broadcast::Receiver<RawCdpMessage> {
+        self.raw_tx.subscribe()
+    }
+}
+
+/// Enable TCP SO_KEEPALIVE on the underlying socket of a WebSocket connection.
+/// This is best-effort: failures are silently ignored since the WebSocket-level
+/// Ping keepalive provides the primary connection liveness mechanism.
+fn enable_tcp_keepalive(stream: &tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>) {
+    let tcp_stream = match stream {
+        tokio_tungstenite::MaybeTlsStream::Plain(s) => s,
+        tokio_tungstenite::MaybeTlsStream::Rustls(s) => s.get_ref().0,
+        _ => return,
+    };
+
+    // SockRef borrows the fd without taking ownership.
+    let sock = socket2::SockRef::from(tcp_stream);
+    let keepalive = socket2::TcpKeepalive::new().with_time(std::time::Duration::from_secs(30));
+
+    // with_interval sets TCP_KEEPINTVL — the time between probes after the
+    // first keepalive probe goes unanswered. Available on most platforms
+    // (Linux, macOS, Windows, FreeBSD, etc.) but not OpenBSD or Haiku.
+    #[cfg(not(any(target_os = "openbsd", target_os = "haiku")))]
+    let keepalive = keepalive.with_interval(std::time::Duration::from_secs(10));
+
+    let _ = sock.set_tcp_keepalive(&keepalive);
+}

cli/src/native/cdp/discovery.rs

@@ -0,0 +1,387 @@
+use std::time::Duration;
+
+use futures_util::{SinkExt, StreamExt};
+use tokio_tungstenite::tungstenite::Message;
+
+use super::types::BrowserVersionInfo;
+
+/// Default timeout for CDP discovery HTTP requests.
+const DEFAULT_DISCOVERY_TIMEOUT: Duration = Duration::from_secs(2);
+
+/// Discover the CDP WebSocket URL for the given host and port.
+///
+/// Tries three methods in order: `/json/version`, `/json/list`, and a direct
+/// WebSocket connection to `/devtools/browser`. The returned URL has its
+/// host/port rewritten to match the requested target.
+///
+/// An optional `query` string (without the leading `?`) is appended to the
+/// final WebSocket URL so that user-supplied URL parameters (e.g.
+/// `?mode=Hello`) are forwarded to the remote endpoint.
+pub async fn discover_cdp_url(
+    host: &str,
+    port: u16,
+    query: Option<&str>,
+) -> Result<String, String> {
+    discover_cdp_url_with_timeout(host, port, query, DEFAULT_DISCOVERY_TIMEOUT).await
+}
+
+/// Like [`discover_cdp_url`] but with a custom request timeout.
+pub async fn discover_cdp_url_with_timeout(
+    host: &str,
+    port: u16,
+    query: Option<&str>,
+    timeout: Duration,
+) -> Result<String, String> {
+    // Primary: /json/version (standard path)
+    let version_err = match fetch_cdp_info(host, port, timeout).await {
+        Ok(info) => {
+            if let Some(ws_url) = info.web_socket_debugger_url {
+                return Ok(append_query(&rewrite_ws_host(&ws_url, host, port), query));
+            }
+            format!(
+                "No webSocketDebuggerUrl in /json/version at {}:{}",
+                host, port
+            )
+        }
+        Err(e) => e,
+    };
+
+    // Fallback: /json/list (returns target list; look for the browser target)
+    let list_err = match fetch_cdp_list(host, port, timeout).await {
+        Ok(ws_url) => return Ok(append_query(&rewrite_ws_host(&ws_url, host, port), query)),
+        Err(e) => e,
+    };
+
+    // Final fallback: direct WebSocket at /devtools/browser.
+    // Chrome 136+ with UI-based remote debugging (chrome://inspect) exposes
+    // CDP over WebSocket but does not serve HTTP discovery endpoints.
+    match discover_cdp_ws(host, port, timeout).await {
+        Ok(ws_url) => Ok(append_query(&ws_url, query)),
+        Err(ws_err) => Err(format!(
+            "All CDP discovery methods failed for {}:{}: /json/version: {}; /json/list: {}; WebSocket: {}",
+            host, port, version_err, list_err, ws_err
+        )),
+    }
+}
+
+/// Bracket an IPv6 address for use in URLs. No-op for IPv4 or already-bracketed addresses.
+fn bracket_ipv6(host: &str) -> String {
+    if host.contains(':') && !host.starts_with('[') {
+        format!("[{}]", host)
+    } else {
+        host.to_string()
+    }
+}
+
+/// Fetch `/json/version` from the given host:port and parse the response.
+async fn fetch_cdp_info(
+    host: &str,
+    port: u16,
+    timeout: Duration,
+) -> Result<BrowserVersionInfo, String> {
+    let url = format!("http://{}:{}/json/version", bracket_ipv6(host), port);
+
+    let body = tokio::time::timeout(timeout, reqwest_get_string(&url))
+        .await
+        .map_err(|_| format!("Timeout connecting to CDP at {}:{}", host, port))?
+        .map_err(|e| format!("Failed to connect to CDP at {}:{}: {}", host, port, e))?;
+
+    serde_json::from_str(&body).map_err(|e| format!("Invalid /json/version response: {}", e))
+}
+
+/// Rewrite the host and port in a WebSocket URL to match the target we
+/// actually connected to. Chrome's `/json/version` always returns
+/// `ws://127.0.0.1:<local-port>/...` which is unreachable when the
+/// browser is on a remote machine or behind a port-forward.
+fn rewrite_ws_host(ws_url: &str, host: &str, port: u16) -> String {
+    if let Ok(mut parsed) = url::Url::parse(ws_url) {
+        let _ = parsed.set_host(Some(&bracket_ipv6(host)));
+        let _ = parsed.set_port(Some(port));
+        parsed.to_string()
+    } else {
+        ws_url.to_string()
+    }
+}
+
+/// Append a query string to a URL, preserving any existing query parameters.
+fn append_query(url: &str, query: Option<&str>) -> String {
+    match query {
+        Some(q) if !q.is_empty() => {
+            if let Ok(mut parsed) = url::Url::parse(url) {
+                {
+                    let mut pairs = parsed.query_pairs_mut();
+                    pairs.extend_pairs(url::form_urlencoded::parse(q.as_bytes()));
+                }
+                parsed.to_string()
+            } else {
+                // Fallback: raw string append
+                if url.contains('?') {
+                    format!("{}&{}", url, q)
+                } else {
+                    format!("{}?{}", url, q)
+                }
+            }
+        }
+        _ => url.to_string(),
+    }
+}
+
+/// Fetch `/json/list` and extract the `webSocketDebuggerUrl` from the first
+/// target with `type == "browser"`, or the first target if none has that type.
+async fn fetch_cdp_list(host: &str, port: u16, timeout: Duration) -> Result<String, String> {
+    let url = format!("http://{}:{}/json/list", bracket_ipv6(host), port);
+
+    let body = tokio::time::timeout(timeout, reqwest_get_string(&url))
+        .await
+        .map_err(|_| format!("Timeout connecting to /json/list at {}:{}", host, port))?
+        .map_err(|e| {
+            format!(
+                "Failed to connect to /json/list at {}:{}: {}",
+                host, port, e
+            )
+        })?;
+
+    let targets: Vec<serde_json::Value> =
+        serde_json::from_str(&body).map_err(|e| format!("Invalid /json/list response: {}", e))?;
+
+    // Prefer targets with type "browser", fall back to first target with a ws URL
+    let browser_target = targets
+        .iter()
+        .find(|t| t.get("type").and_then(|v| v.as_str()) == Some("browser"));
+
+    let target = browser_target.or_else(|| targets.first());
+
+    target
+        .and_then(|t| t.get("webSocketDebuggerUrl"))
+        .and_then(|v| v.as_str())
+        .map(|s| s.to_string())
+        .ok_or_else(|| "No webSocketDebuggerUrl found in /json/list targets".to_string())
+}
+
+/// Discover a CDP endpoint by connecting directly to `ws://host:port/devtools/browser`
+/// and verifying it responds to `Browser.getVersion`.
+/// Returns the WebSocket URL on success.
+async fn discover_cdp_ws(host: &str, port: u16, timeout: Duration) -> Result<String, String> {
+    let ws_url = format!("ws://{}:{}/devtools/browser", bracket_ipv6(host), port);
+
+    tokio::time::timeout(timeout, async {
+        let (mut ws_stream, _) = tokio_tungstenite::connect_async(&ws_url)
+            .await
+            .map_err(|e| format!("WebSocket connect failed at {}: {}", ws_url, e))?;
+
+        let cmd = r#"{"id":1,"method":"Browser.getVersion"}"#;
+        ws_stream
+            .send(Message::Text(cmd.into()))
+            .await
+            .map_err(|e| format!("Failed to send command: {}", e))?;
+
+        #[derive(serde::Deserialize)]
+        struct CdpReply {
+            id: u64,
+        }
+
+        let mut result: Result<(), String> = Err("No valid CDP response received".to_string());
+        while let Some(msg) = ws_stream.next().await {
+            match msg {
+                Ok(Message::Text(text)) => {
+                    if serde_json::from_str::<CdpReply>(&text).is_ok_and(|r| r.id == 1) {
+                        result = Ok(());
+                        break;
+                    }
+                }
+                Ok(Message::Close(_)) | Err(_) => break,
+                _ => continue,
+            }
+        }
+
+        let _ = ws_stream.close(None).await;
+        result
+    })
+    .await
+    .map_err(|_| format!("Timeout connecting to WebSocket at {}", ws_url))?
+    .map(|()| ws_url)
+}
+
+async fn reqwest_get_string(url: &str) -> Result<String, String> {
+    let resp = reqwest::get(url).await.map_err(|e| e.to_string())?;
+    resp.text().await.map_err(|e| e.to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tokio::io::{AsyncReadExt, AsyncWriteExt};
+    use tokio::net::TcpListener;
+
+    const HTTP_404: &str =
+        "HTTP/1.1 404 Not Found\r\nContent-Length: 0\r\nConnection: close\r\n\r\n";
+
+    fn http_200(body: &str) -> String {
+        format!(
+            "HTTP/1.1 200 OK\r\nContent-Length: {}\r\nConnection: close\r\nContent-Type: application/json\r\n\r\n{}",
+            body.len(), body
+        )
+    }
+
+    async fn accept_http(listener: &TcpListener, response: &str) {
+        let (mut s, _) = listener.accept().await.unwrap();
+        let mut buf = [0u8; 1024];
+        let _ = s.read(&mut buf).await;
+        s.write_all(response.as_bytes()).await.unwrap();
+    }
+
+    #[tokio::test]
+    async fn discovers_ws_url_from_json_version() {
+        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let port = listener.local_addr().unwrap().port();
+        let server = tokio::spawn(async move {
+            accept_http(
+                &listener,
+                &http_200(r#"{"webSocketDebuggerUrl":"ws://127.0.0.1:1234/"}"#),
+            )
+            .await;
+        });
+
+        let ws_url = discover_cdp_url("127.0.0.1", port, None).await.unwrap();
+        assert_eq!(ws_url, format!("ws://127.0.0.1:{}/", port));
+        server.await.unwrap();
+    }
+
+    #[tokio::test]
+    async fn returns_error_when_version_returns_invalid_json() {
+        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let port = listener.local_addr().unwrap().port();
+        let server = tokio::spawn(async move {
+            accept_http(&listener, &http_200("not-json")).await;
+            // /json/list and ws fallback both fail (server closes)
+        });
+
+        let err = discover_cdp_url("127.0.0.1", port, None).await.unwrap_err();
+        assert!(err.contains("Invalid /json/version response"));
+        server.await.unwrap();
+    }
+
+    #[tokio::test]
+    async fn falls_back_to_json_list_on_version_404() {
+        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let port = listener.local_addr().unwrap().port();
+        let server = tokio::spawn(async move {
+            accept_http(&listener, HTTP_404).await;
+            accept_http(
+                &listener,
+                &http_200(r#"[{"type":"browser","webSocketDebuggerUrl":"ws://127.0.0.1:1234/devtools/browser/abc"}]"#),
+            ).await;
+        });
+
+        let ws_url = discover_cdp_url("127.0.0.1", port, None).await.unwrap();
+        assert!(ws_url.contains("/devtools/browser/abc"));
+        assert!(ws_url.contains(&port.to_string()));
+        server.await.unwrap();
+    }
+
+    #[tokio::test]
+    async fn falls_back_to_ws_when_http_returns_404() {
+        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let port = listener.local_addr().unwrap().port();
+        let server = tokio::spawn(async move {
+            // /json/version -> 404, /json/list -> 404
+            accept_http(&listener, HTTP_404).await;
+            accept_http(&listener, HTTP_404).await;
+
+            // WebSocket handshake + respond to Browser.getVersion
+            let (stream, _) = listener.accept().await.unwrap();
+            let mut ws = tokio_tungstenite::accept_async(stream).await.unwrap();
+            if let Some(Ok(Message::Text(text))) = ws.next().await {
+                let req: serde_json::Value = serde_json::from_str(&text).unwrap();
+                let id = req.get("id").unwrap();
+                let reply = format!(
+                    r#"{{"id":{},"result":{{"protocolVersion":"1.3","product":"Chrome/136"}}}}"#,
+                    id
+                );
+                ws.send(Message::Text(reply)).await.unwrap();
+            }
+            let _ = ws.close(None).await;
+        });
+
+        let ws_url = discover_cdp_url("127.0.0.1", port, None).await.unwrap();
+        assert_eq!(ws_url, format!("ws://127.0.0.1:{}/devtools/browser", port));
+        server.await.unwrap();
+    }
+
+    #[test]
+    fn rewrite_ws_host_replaces_host_and_port() {
+        let original = "ws://127.0.0.1:9222/devtools/browser/abc";
+        let rewritten = rewrite_ws_host(original, "10.211.55.12", 9223);
+        assert_eq!(rewritten, "ws://10.211.55.12:9223/devtools/browser/abc");
+    }
+
+    #[test]
+    fn rewrite_ws_host_handles_ipv6() {
+        let original = "ws://127.0.0.1:9222/devtools/browser/abc";
+        let rewritten = rewrite_ws_host(original, "::1", 9222);
+        assert_eq!(rewritten, "ws://[::1]:9222/devtools/browser/abc");
+    }
+
+    #[test]
+    fn append_query_adds_params_to_url_without_query() {
+        let url = "ws://127.0.0.1:9222/devtools/browser/abc";
+        let result = append_query(url, Some("mode=Hello"));
+        assert_eq!(
+            result,
+            "ws://127.0.0.1:9222/devtools/browser/abc?mode=Hello"
+        );
+    }
+
+    #[test]
+    fn append_query_merges_with_existing_query() {
+        let url = "ws://127.0.0.1:9222/devtools/browser/abc?token=xyz";
+        let result = append_query(url, Some("mode=Hello"));
+        assert_eq!(
+            result,
+            "ws://127.0.0.1:9222/devtools/browser/abc?token=xyz&mode=Hello"
+        );
+    }
+
+    #[test]
+    fn append_query_noop_for_none() {
+        let url = "ws://127.0.0.1:9222/devtools/browser/abc";
+        let result = append_query(url, None);
+        assert_eq!(result, url);
+    }
+
+    #[test]
+    fn append_query_noop_for_empty() {
+        let url = "ws://127.0.0.1:9222/devtools/browser/abc";
+        let result = append_query(url, Some(""));
+        assert_eq!(result, url);
+    }
+
+    #[test]
+    fn append_query_handles_multiple_params() {
+        let url = "ws://127.0.0.1:9222/devtools/browser/abc";
+        let result = append_query(url, Some("mode=Hello&token=abc"));
+        assert_eq!(
+            result,
+            "ws://127.0.0.1:9222/devtools/browser/abc?mode=Hello&token=abc"
+        );
+    }
+
+    #[tokio::test]
+    async fn discover_preserves_query_params() {
+        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let port = listener.local_addr().unwrap().port();
+        let server = tokio::spawn(async move {
+            accept_http(
+                &listener,
+                &http_200(r#"{"webSocketDebuggerUrl":"ws://127.0.0.1:1234/"}"#),
+            )
+            .await;
+        });
+
+        let ws_url = discover_cdp_url("127.0.0.1", port, Some("mode=Hello"))
+            .await
+            .unwrap();
+        assert_eq!(ws_url, format!("ws://127.0.0.1:{}/?mode=Hello", port));
+        server.await.unwrap();
+    }
+}

cli/src/native/cdp/lightpanda.rs

@@ -0,0 +1,495 @@
+use std::collections::VecDeque;
+use std::io::{BufRead, BufReader};
+use std::net::TcpListener;
+use std::path::PathBuf;
+use std::process::{Child, Command, Stdio};
+use std::sync::{Arc, Mutex};
+use std::time::Duration;
+
+use super::discovery::discover_cdp_url_with_timeout;
+
+const LIGHTPANDA_STARTUP_TIMEOUT: Duration = Duration::from_secs(10);
+const LIGHTPANDA_POLL_INTERVAL: Duration = Duration::from_millis(100);
+const LIGHTPANDA_DISCOVERY_TIMEOUT: Duration = Duration::from_millis(500);
+const LIGHTPANDA_SESSION_TIMEOUT_SECS: u64 = 604800; // 1 week, the documented maximum
+const MAX_LOG_LINES: usize = 40;
+
+pub struct LightpandaProcess {
+    child: Child,
+    pub ws_url: String,
+    _log_drainers: Vec<std::thread::JoinHandle<()>>,
+}
+
+impl LightpandaProcess {
+    pub fn kill(&mut self) {
+        let _ = self.child.kill();
+        let _ = self.child.wait();
+    }
+}
+
+impl Drop for LightpandaProcess {
+    fn drop(&mut self) {
+        self.kill();
+    }
+}
+
+#[derive(Default)]
+pub struct LightpandaLaunchOptions {
+    pub executable_path: Option<String>,
+    pub proxy: Option<String>,
+    pub port: Option<u16>,
+}
+
+fn build_lightpanda_serve_args(port: u16, proxy: Option<&str>) -> Vec<String> {
+    let mut args = vec![
+        "serve".to_string(),
+        "--host".to_string(),
+        "127.0.0.1".to_string(),
+        "--port".to_string(),
+        port.to_string(),
+        "--timeout".to_string(),
+        LIGHTPANDA_SESSION_TIMEOUT_SECS.to_string(),
+    ];
+
+    if let Some(proxy) = proxy {
+        args.push("--http_proxy".to_string());
+        args.push(proxy.to_string());
+    }
+
+    args
+}
+
+#[derive(Clone, Default)]
+struct LaunchLogBuffer {
+    stdout: Arc<Mutex<VecDeque<String>>>,
+    stderr: Arc<Mutex<VecDeque<String>>>,
+}
+
+impl LaunchLogBuffer {
+    fn push_stdout(&self, line: String) {
+        push_bounded(&self.stdout, line);
+    }
+
+    fn push_stderr(&self, line: String) {
+        push_bounded(&self.stderr, line);
+    }
+
+    fn snapshot_stdout(&self) -> Vec<String> {
+        self.stdout
+            .lock()
+            .expect("stdout log buffer poisoned")
+            .iter()
+            .cloned()
+            .collect()
+    }
+
+    fn snapshot_stderr(&self) -> Vec<String> {
+        self.stderr
+            .lock()
+            .expect("stderr log buffer poisoned")
+            .iter()
+            .cloned()
+            .collect()
+    }
+}
+
+fn push_bounded(buffer: &Mutex<VecDeque<String>>, line: String) {
+    let mut guard = buffer.lock().expect("log buffer poisoned");
+    if guard.len() >= MAX_LOG_LINES {
+        guard.pop_front();
+    }
+    guard.push_back(line);
+}
+
+pub fn find_lightpanda() -> Option<PathBuf> {
+    #[cfg(unix)]
+    {
+        if let Ok(output) = Command::new("which").arg("lightpanda").output() {
+            if output.status.success() {
+                let path = String::from_utf8_lossy(&output.stdout).trim().to_string();
+                if !path.is_empty() {
+                    return Some(PathBuf::from(path));
+                }
+            }
+        }
+    }
+
+    #[cfg(windows)]
+    {
+        if let Ok(output) = Command::new("where").arg("lightpanda").output() {
+            if output.status.success() {
+                let path = String::from_utf8_lossy(&output.stdout)
+                    .lines()
+                    .next()
+                    .unwrap_or("")
+                    .trim()
+                    .to_string();
+                if !path.is_empty() {
+                    return Some(PathBuf::from(path));
+                }
+            }
+        }
+    }
+
+    if let Some(home) = dirs::home_dir() {
+        let candidates = [
+            home.join(".lightpanda/lightpanda"),
+            home.join(".local/bin/lightpanda"),
+        ];
+        for c in &candidates {
+            if c.exists() {
+                return Some(c.clone());
+            }
+        }
+    }
+
+    None
+}
+
+pub async fn launch_lightpanda(
+    options: &LightpandaLaunchOptions,
+) -> Result<LightpandaProcess, String> {
+    let binary_path = match &options.executable_path {
+        Some(p) => PathBuf::from(p),
+        None => find_lightpanda().ok_or(
+            "Lightpanda not found. Install it from https://lightpanda.io/docs/open-source/installation or use --executable-path.",
+        )?,
+    };
+
+    let port = match options.port {
+        Some(p) => p,
+        None => TcpListener::bind("127.0.0.1:0")
+            .and_then(|l| l.local_addr())
+            .map(|a| a.port())
+            .map_err(|e| format!("Failed to find an available port for Lightpanda: {}", e))?,
+    };
+    let args = build_lightpanda_serve_args(port, options.proxy.as_deref());
+
+    let mut child = Command::new(&binary_path)
+        .args(&args)
+        .stdin(Stdio::null())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()
+        .map_err(|e| format!("Failed to launch Lightpanda at {:?}: {}", binary_path, e))?;
+
+    let (log_buffer, log_drainers) = start_log_drainers(&mut child)?;
+
+    let ws_url =
+        match wait_for_lightpanda_ready(&mut child, port, &log_buffer, LIGHTPANDA_STARTUP_TIMEOUT)
+            .await
+        {
+            Ok(url) => url,
+            Err(e) => {
+                let _ = child.kill();
+                let _ = child.wait();
+                return Err(e);
+            }
+        };
+
+    Ok(LightpandaProcess {
+        child,
+        ws_url,
+        _log_drainers: log_drainers,
+    })
+}
+
+fn start_log_drainers(
+    child: &mut Child,
+) -> Result<(LaunchLogBuffer, Vec<std::thread::JoinHandle<()>>), String> {
+    let stdout = child.stdout.take().ok_or_else(|| {
+        let _ = child.kill();
+        "Failed to capture Lightpanda stdout".to_string()
+    })?;
+    let stderr = child.stderr.take().ok_or_else(|| {
+        let _ = child.kill();
+        "Failed to capture Lightpanda stderr".to_string()
+    })?;
+
+    let logs = LaunchLogBuffer::default();
+    let stdout_logs = logs.clone();
+    let stderr_logs = logs.clone();
+
+    let stdout_handle =
+        std::thread::spawn(move || drain_reader(stdout, move |line| stdout_logs.push_stdout(line)));
+    let stderr_handle =
+        std::thread::spawn(move || drain_reader(stderr, move |line| stderr_logs.push_stderr(line)));
+
+    Ok((logs, vec![stdout_handle, stderr_handle]))
+}
+
+fn drain_reader<R, F>(reader: R, mut push: F)
+where
+    R: std::io::Read,
+    F: FnMut(String),
+{
+    for line in BufReader::new(reader).lines() {
+        match line {
+            Ok(line) => push(line),
+            Err(_) => break,
+        }
+    }
+}
+
+async fn wait_for_lightpanda_ready(
+    child: &mut Child,
+    port: u16,
+    logs: &LaunchLogBuffer,
+    startup_timeout: Duration,
+) -> Result<String, String> {
+    let deadline = std::time::Instant::now() + startup_timeout;
+    let mut last_probe_error = None;
+
+    loop {
+        if let Ok(Some(status)) = child.try_wait() {
+            // Give the drainer threads a brief window to flush the last log lines
+            // before we snapshot them.  This is best-effort: lines written just
+            // before exit may still be missing, but the most useful output (early
+            // startup errors) will already be in the buffer.
+            tokio::time::sleep(Duration::from_millis(25)).await;
+            return Err(lightpanda_launch_error(
+                &format!(
+                    "Lightpanda exited before CDP became ready (status: {})",
+                    status
+                ),
+                logs,
+                last_probe_error.as_deref(),
+            ));
+        }
+
+        match discover_cdp_url_with_timeout("127.0.0.1", port, None, LIGHTPANDA_DISCOVERY_TIMEOUT)
+            .await
+        {
+            Ok(ws_url) => return Ok(ws_url),
+            Err(err) => last_probe_error = Some(err),
+        }
+
+        if std::time::Instant::now() >= deadline {
+            return Err(lightpanda_launch_error(
+                &format!(
+                    "Timed out after {}ms waiting for Lightpanda CDP endpoint on port {}",
+                    startup_timeout.as_millis(),
+                    port
+                ),
+                logs,
+                last_probe_error.as_deref(),
+            ));
+        }
+
+        tokio::time::sleep(LIGHTPANDA_POLL_INTERVAL).await;
+    }
+}
+
+fn lightpanda_launch_error(
+    message: &str,
+    logs: &LaunchLogBuffer,
+    last_probe_error: Option<&str>,
+) -> String {
+    let stdout_lines = logs.snapshot_stdout();
+    let stderr_lines = logs.snapshot_stderr();
+    let mut details = Vec::new();
+
+    if let Some(err) = last_probe_error {
+        details.push(format!("Last probe error: {}", err));
+    }
+
+    if !stderr_lines.is_empty() {
+        details.push(format!(
+            "Lightpanda stderr (last {} lines):\n  {}",
+            stderr_lines.len(),
+            stderr_lines.join("\n  ")
+        ));
+    }
+
+    if !stdout_lines.is_empty() {
+        details.push(format!(
+            "Lightpanda stdout (last {} lines):\n  {}",
+            stdout_lines.len(),
+            stdout_lines.join("\n  ")
+        ));
+    }
+
+    if details.is_empty() {
+        format!("{} (no stdout/stderr output from Lightpanda)", message)
+    } else {
+        format!("{}\n{}", message, details.join("\n"))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tokio::io::{AsyncReadExt, AsyncWriteExt};
+    use tokio::net::TcpListener as TokioTcpListener;
+
+    fn unused_port() -> u16 {
+        std::net::TcpListener::bind("127.0.0.1:0")
+            .unwrap()
+            .local_addr()
+            .unwrap()
+            .port()
+    }
+
+    async fn serve_json_version_once_after_delay(port: u16, delay_ms: u64, body: &'static str) {
+        tokio::time::sleep(Duration::from_millis(delay_ms)).await;
+        let listener = TokioTcpListener::bind(("127.0.0.1", port)).await.unwrap();
+        let (mut socket, _) = listener.accept().await.unwrap();
+        let mut buf = [0u8; 1024];
+        let _ = socket.read(&mut buf).await;
+        let response = format!(
+            "HTTP/1.1 200 OK\r\nContent-Length: {}\r\nConnection: close\r\nContent-Type: application/json\r\n\r\n{}",
+            body.len(),
+            body
+        );
+        socket.write_all(response.as_bytes()).await.unwrap();
+    }
+
+    #[cfg(unix)]
+    #[tokio::test]
+    async fn waits_for_ready_without_logs() {
+        let port = unused_port();
+        tokio::spawn(serve_json_version_once_after_delay(
+            port,
+            150,
+            r#"{"webSocketDebuggerUrl":"ws://127.0.0.1:9222/"}"#,
+        ));
+
+        let mut child = Command::new("/bin/sh")
+            .args(["-c", "sleep 5"])
+            .stdin(Stdio::null())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped())
+            .spawn()
+            .unwrap();
+
+        let (logs, _drainers) = start_log_drainers(&mut child).unwrap();
+        let ws_url = wait_for_lightpanda_ready(&mut child, port, &logs, LIGHTPANDA_STARTUP_TIMEOUT)
+            .await
+            .unwrap();
+
+        assert_eq!(ws_url, format!("ws://127.0.0.1:{}/", port));
+        let _ = child.kill();
+        let _ = child.wait();
+    }
+
+    #[cfg(unix)]
+    #[tokio::test]
+    async fn child_exit_surfaces_logs() {
+        let port = unused_port();
+        let mut child = Command::new("/bin/sh")
+            .args(["-c", "echo boom >&2; sleep 0.1; exit 23"])
+            .stdin(Stdio::null())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped())
+            .spawn()
+            .unwrap();
+
+        let (logs, _drainers) = start_log_drainers(&mut child).unwrap();
+        let err = wait_for_lightpanda_ready(&mut child, port, &logs, LIGHTPANDA_STARTUP_TIMEOUT)
+            .await
+            .unwrap_err();
+
+        assert!(err.contains("Lightpanda exited before CDP became ready"));
+        assert!(err.contains("boom"));
+    }
+
+    #[cfg(unix)]
+    #[tokio::test]
+    async fn timeout_reports_last_probe_error() {
+        let port = unused_port();
+        let mut child = Command::new("/bin/sh")
+            .args(["-c", "sleep 30"])
+            .stdin(Stdio::null())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped())
+            .spawn()
+            .unwrap();
+
+        let timeout = Duration::from_millis(300);
+        let (logs, _drainers) = start_log_drainers(&mut child).unwrap();
+        let err = tokio::time::timeout(
+            Duration::from_secs(2),
+            wait_for_lightpanda_ready(&mut child, port, &logs, timeout),
+        )
+        .await
+        .expect("ready wait should return before outer timeout")
+        .unwrap_err();
+
+        assert!(err.contains("Timed out after 300ms waiting for Lightpanda CDP endpoint"));
+        assert!(
+            err.contains("Failed to connect to CDP") || err.contains("Timeout connecting to CDP")
+        );
+
+        let _ = child.kill();
+        let _ = child.wait();
+    }
+
+    #[test]
+    fn test_find_lightpanda_returns_none_when_missing() {
+        let _ = find_lightpanda();
+    }
+
+    #[test]
+    fn test_lightpanda_launch_error_no_logs() {
+        let logs = LaunchLogBuffer::default();
+        let msg = lightpanda_launch_error("Lightpanda exited", &logs, None);
+        assert!(msg.contains("no stdout/stderr output"));
+    }
+
+    #[test]
+    fn test_lightpanda_launch_error_with_lines() {
+        let logs = LaunchLogBuffer::default();
+        logs.push_stdout("stdout line".to_string());
+        logs.push_stderr("stderr line".to_string());
+        let msg = lightpanda_launch_error("Lightpanda exited", &logs, Some("connect failed"));
+        assert!(msg.contains("stdout line"));
+        assert!(msg.contains("stderr line"));
+        assert!(msg.contains("Last probe error: connect failed"));
+    }
+
+    #[test]
+    fn test_default_options() {
+        let opts = LightpandaLaunchOptions::default();
+        assert!(opts.executable_path.is_none());
+        assert!(opts.proxy.is_none());
+        assert!(opts.port.is_none());
+    }
+
+    #[test]
+    fn test_build_lightpanda_serve_args_sets_explicit_session_timeout() {
+        let args = build_lightpanda_serve_args(9222, None);
+
+        assert_eq!(
+            args,
+            vec![
+                "serve".to_string(),
+                "--host".to_string(),
+                "127.0.0.1".to_string(),
+                "--port".to_string(),
+                "9222".to_string(),
+                "--timeout".to_string(),
+                "604800".to_string(),
+            ]
+        );
+    }
+
+    #[test]
+    fn test_build_lightpanda_serve_args_with_proxy() {
+        let args = build_lightpanda_serve_args(9333, Some("http://127.0.0.1:8080"));
+
+        assert_eq!(
+            args,
+            vec![
+                "serve".to_string(),
+                "--host".to_string(),
+                "127.0.0.1".to_string(),
+                "--port".to_string(),
+                "9333".to_string(),
+                "--timeout".to_string(),
+                "604800".to_string(),
+                "--http_proxy".to_string(),
+                "http://127.0.0.1:8080".to_string(),
+            ]
+        );
+    }
+}

cli/src/native/cdp/mod.rs

@@ -0,0 +1,5 @@
+pub mod chrome;
+pub mod client;
+pub mod discovery;
+pub mod lightpanda;
+pub mod types;

cli/src/native/cdp/types.rs

@@ -0,0 +1,586 @@
+use serde::{Deserialize, Deserializer, Serialize};
+use serde_json::Value;
+
+/// Deserialize a value that may be either a string or an integer into a String.
+/// Lightpanda sends numeric nodeIds/childIds in AX tree responses, while Chrome
+/// sends strings. This accepts both.
+fn string_or_int<'de, D>(deserializer: D) -> Result<String, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    let v = Value::deserialize(deserializer)?;
+    match v {
+        Value::String(s) => Ok(s),
+        Value::Number(n) => Ok(n.to_string()),
+        other => Err(serde::de::Error::custom(format!(
+            "expected string or integer, got {}",
+            other
+        ))),
+    }
+}
+
+/// Deserialize an optional Vec where each element may be a string or integer.
+fn opt_vec_string_or_int<'de, D>(deserializer: D) -> Result<Option<Vec<String>>, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    let opt: Option<Vec<Value>> = Option::deserialize(deserializer)?;
+    match opt {
+        None => Ok(None),
+        Some(vec) => {
+            let mut result = Vec::with_capacity(vec.len());
+            for v in vec {
+                match v {
+                    Value::String(s) => result.push(s),
+                    Value::Number(n) => result.push(n.to_string()),
+                    other => {
+                        return Err(serde::de::Error::custom(format!(
+                            "expected string or integer in array, got {}",
+                            other
+                        )))
+                    }
+                }
+            }
+            Ok(Some(result))
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// CDP message envelope
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CdpCommand {
+    pub id: u64,
+    pub method: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub params: Option<Value>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub session_id: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CdpMessage {
+    pub id: Option<u64>,
+    pub result: Option<Value>,
+    pub error: Option<CdpError>,
+    pub method: Option<String>,
+    pub params: Option<Value>,
+    pub session_id: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct CdpError {
+    pub code: Option<i64>,
+    pub message: String,
+    pub data: Option<String>,
+}
+
+impl std::fmt::Display for CdpError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.message)
+    }
+}
+
+// ---------------------------------------------------------------------------
+// CDP events (broadcast to subscribers)
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Clone)]
+pub struct CdpEvent {
+    pub method: String,
+    pub params: Value,
+    pub session_id: Option<String>,
+}
+
+// ---------------------------------------------------------------------------
+// Target domain
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TargetInfo {
+    pub target_id: String,
+    #[serde(rename = "type")]
+    pub target_type: String,
+    pub title: String,
+    pub url: String,
+    pub attached: Option<bool>,
+    pub browser_context_id: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GetTargetsResult {
+    pub target_infos: Vec<TargetInfo>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AttachToTargetParams {
+    pub target_id: String,
+    pub flatten: bool,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AttachToTargetResult {
+    pub session_id: String,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SetDiscoverTargetsParams {
+    pub discover: bool,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CreateTargetParams {
+    pub url: String,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CreateTargetResult {
+    pub target_id: String,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CloseTargetParams {
+    pub target_id: String,
+}
+
+// Target events
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TargetCreatedEvent {
+    pub target_info: TargetInfo,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TargetDestroyedEvent {
+    pub target_id: String,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TargetInfoChangedEvent {
+    pub target_info: TargetInfo,
+}
+
+// ---------------------------------------------------------------------------
+// Page domain
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PageNavigateParams {
+    pub url: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub referrer: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PageNavigateResult {
+    pub frame_id: String,
+    pub loader_id: Option<String>,
+    pub error_text: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct FrameNavigatedEvent {
+    pub frame: FrameInfo,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct FrameInfo {
+    pub id: String,
+    pub url: String,
+    pub parent_id: Option<String>,
+    pub name: Option<String>,
+}
+
+// Page.javascriptDialogOpening
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct JavascriptDialogOpeningEvent {
+    pub url: String,
+    pub message: String,
+    #[serde(rename = "type")]
+    pub dialog_type: String,
+    pub default_prompt: Option<String>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct HandleJavaScriptDialogParams {
+    pub accept: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub prompt_text: Option<String>,
+}
+
+// ---------------------------------------------------------------------------
+// Runtime domain
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EvaluateParams {
+    pub expression: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub return_by_value: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub await_promise: Option<bool>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EvaluateResult {
+    pub result: RemoteObject,
+    pub exception_details: Option<ExceptionDetails>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RemoteObject {
+    #[serde(rename = "type")]
+    pub object_type: String,
+    pub subtype: Option<String>,
+    pub value: Option<Value>,
+    pub description: Option<String>,
+    pub object_id: Option<String>,
+    pub class_name: Option<String>,
+    pub unserializable_value: Option<String>,
+    pub preview: Option<Value>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExceptionDetails {
+    pub text: String,
+    pub exception: Option<RemoteObject>,
+    pub line_number: Option<i64>,
+    pub column_number: Option<i64>,
+}
+
+// Runtime.consoleAPICalled
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ConsoleApiCalledEvent {
+    #[serde(rename = "type")]
+    pub call_type: String,
+    pub args: Vec<RemoteObject>,
+    pub timestamp: Option<f64>,
+}
+
+// Runtime.exceptionThrown
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExceptionThrownEvent {
+    pub timestamp: f64,
+    pub exception_details: ExceptionDetails,
+}
+
+// ---------------------------------------------------------------------------
+// Accessibility domain
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GetFullAXTreeResult {
+    pub nodes: Vec<AXNode>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AXNode {
+    #[serde(deserialize_with = "string_or_int")]
+    pub node_id: String,
+    pub role: Option<AXValue>,
+    pub name: Option<AXValue>,
+    pub value: Option<AXValue>,
+    pub description: Option<AXValue>,
+    pub properties: Option<Vec<AXProperty>>,
+    #[serde(default, deserialize_with = "opt_vec_string_or_int")]
+    pub child_ids: Option<Vec<String>>,
+    pub backend_d_o_m_node_id: Option<i64>,
+    pub ignored: Option<bool>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AXValue {
+    #[serde(rename = "type")]
+    pub value_type: String,
+    pub value: Option<Value>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AXProperty {
+    pub name: String,
+    pub value: AXValue,
+}
+
+// ---------------------------------------------------------------------------
+// Network domain (minimal for Phase 1)
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RequestWillBeSentEvent {
+    pub request_id: String,
+    pub request: NetworkRequest,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct NetworkRequest {
+    pub url: String,
+    pub method: String,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct LoadingFinishedEvent {
+    pub request_id: String,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct LoadingFailedEvent {
+    pub request_id: String,
+}
+
+// ---------------------------------------------------------------------------
+// DOM domain
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DomResolveNodeParams {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub backend_node_id: Option<i64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub node_id: Option<i64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub object_group: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DomResolveNodeResult {
+    pub object: RemoteObject,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DomGetBoxModelParams {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub backend_node_id: Option<i64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub node_id: Option<i64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub object_id: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DomGetBoxModelResult {
+    pub model: BoxModel,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BoxModel {
+    pub content: Vec<f64>,
+    pub padding: Vec<f64>,
+    pub border: Vec<f64>,
+    pub margin: Vec<f64>,
+    pub width: i64,
+    pub height: i64,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DomQuerySelectorParams {
+    pub node_id: i64,
+    pub selector: String,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DomQuerySelectorResult {
+    pub node_id: i64,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DomGetDocumentParams {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub depth: Option<i32>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DomGetDocumentResult {
+    pub root: DomNode,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DomNode {
+    pub node_id: i64,
+    pub backend_node_id: Option<i64>,
+    pub node_type: Option<i64>,
+    pub node_name: Option<String>,
+    pub children: Option<Vec<DomNode>>,
+}
+
+// ---------------------------------------------------------------------------
+// Input domain
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DispatchMouseEventParams {
+    #[serde(rename = "type")]
+    pub event_type: String,
+    pub x: f64,
+    pub y: f64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub button: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub buttons: Option<i32>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub click_count: Option<i32>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub delta_x: Option<f64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub delta_y: Option<f64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub modifiers: Option<i32>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DispatchKeyEventParams {
+    #[serde(rename = "type")]
+    pub event_type: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub key: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub code: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub text: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub unmodified_text: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub windows_virtual_key_code: Option<i32>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub native_virtual_key_code: Option<i32>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub modifiers: Option<i32>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct InsertTextParams {
+    pub text: String,
+}
+
+// ---------------------------------------------------------------------------
+// Page.captureScreenshot
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CaptureScreenshotParams {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub format: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub quality: Option<i32>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub clip: Option<Viewport>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub from_surface: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub capture_beyond_viewport: Option<bool>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Viewport {
+    pub x: f64,
+    pub y: f64,
+    pub width: f64,
+    pub height: f64,
+    pub scale: f64,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CaptureScreenshotResult {
+    pub data: String,
+}
+
+// ---------------------------------------------------------------------------
+// Runtime.callFunctionOn
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CallFunctionOnParams {
+    pub function_declaration: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub object_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub arguments: Option<Vec<CallArgument>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub return_by_value: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub await_promise: Option<bool>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CallArgument {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub value: Option<Value>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub object_id: Option<String>,
+}
+
+// ---------------------------------------------------------------------------
+// Version info (from /json/version)
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BrowserVersionInfo {
+    #[serde(rename = "webSocketDebuggerUrl")]
+    pub web_socket_debugger_url: Option<String>,
+    #[serde(rename = "Browser")]
+    pub browser: Option<String>,
+}
+
+/// Auto-generated CDP types from protocol JSON files in `cdp-protocol/`.
+///
+/// To populate: download `browser_protocol.json` and `js_protocol.json` from
+/// <https://github.com/nicolo-ribaudo/nicolo-ribaudo.github.io/> (or any
+/// Chromium source) into `cli/cdp-protocol/` and rebuild.
+///
+/// Usage: `use super::cdp::types::generated::cdp_page::*;`
+#[allow(clippy::upper_case_acronyms)]
+pub mod generated {
+    include!(concat!(env!("OUT_DIR"), "/cdp_generated.rs"));
+}

cli/src/native/cookies.rs

@@ -0,0 +1,100 @@
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
+
+use super::cdp::client::CdpClient;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Cookie {
+    pub name: String,
+    pub value: String,
+    pub domain: String,
+    pub path: String,
+    #[serde(default)]
+    pub expires: f64,
+    #[serde(default)]
+    pub size: i64,
+    #[serde(default)]
+    pub http_only: bool,
+    #[serde(default)]
+    pub secure: bool,
+    #[serde(default)]
+    pub session: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub same_site: Option<String>,
+}
+
+pub async fn get_all_cookies(client: &CdpClient, session_id: &str) -> Result<Vec<Cookie>, String> {
+    let result = client
+        .send_command_no_params("Network.getAllCookies", Some(session_id))
+        .await?;
+
+    let cookies: Vec<Cookie> = result
+        .get("cookies")
+        .and_then(|v| serde_json::from_value(v.clone()).ok())
+        .unwrap_or_default();
+
+    Ok(cookies)
+}
+
+pub async fn get_cookies(
+    client: &CdpClient,
+    session_id: &str,
+    urls: Option<Vec<String>>,
+) -> Result<Vec<Cookie>, String> {
+    let params = match urls {
+        Some(ref u) if !u.is_empty() => json!({ "urls": u }),
+        _ => json!({}),
+    };
+
+    let result = client
+        .send_command("Network.getCookies", Some(params), Some(session_id))
+        .await?;
+
+    let cookies: Vec<Cookie> = result
+        .get("cookies")
+        .and_then(|v| serde_json::from_value(v.clone()).ok())
+        .unwrap_or_default();
+
+    Ok(cookies)
+}
+
+pub async fn set_cookies(
+    client: &CdpClient,
+    session_id: &str,
+    cookies: Vec<Value>,
+    current_url: Option<&str>,
+) -> Result<(), String> {
+    let cookies: Vec<Value> = cookies
+        .into_iter()
+        .map(|mut c| {
+            // Auto-fill url if no domain/path/url provided
+            if c.get("url").is_none() && c.get("domain").is_none() && current_url.is_some() {
+                c.as_object_mut().map(|m| {
+                    m.insert(
+                        "url".to_string(),
+                        Value::String(current_url.unwrap().to_string()),
+                    )
+                });
+            }
+            c
+        })
+        .collect();
+
+    client
+        .send_command(
+            "Network.setCookies",
+            Some(json!({ "cookies": cookies })),
+            Some(session_id),
+        )
+        .await?;
+
+    Ok(())
+}
+
+pub async fn clear_cookies(client: &CdpClient, session_id: &str) -> Result<(), String> {
+    client
+        .send_command_no_params("Network.clearBrowserCookies", Some(session_id))
+        .await?;
+    Ok(())
+}

cli/src/native/daemon.rs

@@ -0,0 +1,792 @@
+use serde_json::Value;
+use std::env;
+use std::fs;
+use std::io::Write;
+use std::path::PathBuf;
+use std::process;
+use std::sync::Arc;
+use std::time::Duration;
+
+use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
+use tokio::signal;
+use tokio::sync::{mpsc, Notify, RwLock};
+
+use super::actions::{
+    auto_save_restore_state, close_current_browser, execute_command, maybe_autosave_restore_state,
+    DaemonState,
+};
+use super::cdp::client::CdpClient;
+use super::state;
+use super::stream::StreamServer;
+use crate::connection::INTERNAL_DAEMON_SHUTDOWN_ACTION;
+
+pub async fn run_daemon(session: &str) {
+    let socket_dir = get_daemon_socket_dir();
+    if !socket_dir.exists() {
+        let _ = fs::create_dir_all(&socket_dir);
+    }
+
+    // When debug mode is on, redirect stderr to a log file so daemon
+    // output can be inspected (the daemon normally has stderr piped to its
+    // parent which drops the read end after startup).
+    #[cfg(unix)]
+    if env::var("AGENT_BROWSER_DEBUG").is_ok() {
+        let log_path = socket_dir.join(format!("{}.log", session));
+        if let Ok(file) = fs::File::create(&log_path) {
+            use std::os::unix::io::IntoRawFd;
+            let fd = file.into_raw_fd();
+            unsafe {
+                libc::dup2(fd, 2);
+                libc::close(fd);
+            }
+            let _ = writeln!(
+                std::io::stderr(),
+                "[daemon] Debug logging started for session: {}",
+                session
+            );
+        }
+    } else {
+        // Redirect stderr to /dev/null to prevent daemon crash when the
+        // parent CLI drops the piped stderr handle after startup.  Cloud
+        // providers (AgentCore, Browserbase, etc.) may write to stderr
+        // during connection setup; a broken pipe would kill the daemon.
+        #[cfg(unix)]
+        {
+            use std::os::unix::io::IntoRawFd;
+            if let Ok(devnull) = fs::File::create("/dev/null") {
+                let fd = devnull.into_raw_fd();
+                unsafe {
+                    libc::dup2(fd, 2);
+                    libc::close(fd);
+                }
+            }
+        }
+    }
+
+    let pid_path = socket_dir.join(format!("{}.pid", session));
+    let _ = fs::write(&pid_path, process::id().to_string());
+
+    let version_path = socket_dir.join(format!("{}.version", session));
+    let _ = fs::write(&version_path, env!("CARGO_PKG_VERSION"));
+
+    // On Unix the daemon listens on a Unix domain socket; on Windows it uses
+    // TCP, so there is no .sock file — only a .port file written by the server.
+    let socket_path = socket_dir.join(format!("{}.sock", session));
+
+    #[cfg(unix)]
+    if socket_path.exists() {
+        let _ = fs::remove_file(&socket_path);
+    }
+
+    #[cfg(windows)]
+    {
+        let _ = fs::remove_file(socket_dir.join(format!("{}.port", session)));
+    }
+
+    let stream_path = socket_dir.join(format!("{}.stream", session));
+    let _ = fs::remove_file(&stream_path);
+    let _ = fs::remove_file(socket_dir.join(format!("{}.engine", session)));
+    let _ = fs::remove_file(socket_dir.join(format!("{}.provider", session)));
+    let _ = fs::remove_file(socket_dir.join(format!("{}.extensions", session)));
+
+    if let Ok(days_str) = env::var("AGENT_BROWSER_STATE_EXPIRE_DAYS") {
+        if let Ok(days) = days_str.parse::<u64>() {
+            if days > 0 {
+                let _ = state::state_clean(days);
+            }
+        }
+    }
+
+    let mut stream_client: Option<Arc<RwLock<Option<Arc<CdpClient>>>>> = None;
+    let mut stream_server_instance: Option<Arc<StreamServer>> = None;
+    let preferred_port = env::var("AGENT_BROWSER_STREAM_PORT")
+        .ok()
+        .and_then(|s| s.parse::<u16>().ok())
+        .unwrap_or(0);
+    match StreamServer::start_without_client(preferred_port, session.to_string(), true).await {
+        Ok((stream_server, client_slot)) => {
+            stream_client = Some(client_slot.clone());
+            if let Err(e) = fs::write(&stream_path, stream_server.port().to_string()) {
+                let _ = writeln!(std::io::stderr(), "Failed to write .stream file: {}", e);
+            }
+            stream_server_instance = Some(Arc::new(stream_server));
+        }
+        Err(e) => {
+            let _ = writeln!(std::io::stderr(), "Stream server failed to start: {}", e);
+        }
+    }
+
+    // Auto-shutdown the daemon after this many ms of inactivity (no commands received).
+    // Disabled when unset or 0.
+    let idle_timeout_ms = env::var("AGENT_BROWSER_IDLE_TIMEOUT_MS")
+        .ok()
+        .and_then(|s| s.parse::<u64>().ok())
+        .filter(|&ms| ms > 0);
+
+    let autosave_interval_ms = autosave_interval_ms_from_env();
+
+    let result = run_socket_server(
+        &socket_path,
+        session,
+        stream_client,
+        stream_server_instance,
+        idle_timeout_ms,
+        autosave_interval_ms,
+    )
+    .await;
+
+    #[cfg(unix)]
+    {
+        let _ = fs::remove_file(&socket_path);
+    }
+    #[cfg(windows)]
+    {
+        let _ = fs::remove_file(socket_dir.join(format!("{}.port", session)));
+    }
+    let _ = fs::remove_file(&pid_path);
+    let _ = fs::remove_file(&version_path);
+    let _ = fs::remove_file(&stream_path);
+    let _ = fs::remove_file(socket_dir.join(format!("{}.engine", session)));
+    let _ = fs::remove_file(socket_dir.join(format!("{}.provider", session)));
+    let _ = fs::remove_file(socket_dir.join(format!("{}.extensions", session)));
+
+    if let Err(e) = result {
+        let _ = writeln!(std::io::stderr(), "Daemon error: {}", e);
+        process::exit(1);
+    }
+}
+
+/// Minimum ms between periodic session autosaves while the browser is open.
+/// Defaults to 30s; 0 disables periodic autosave (save-on-close still runs).
+fn autosave_interval_ms_from_env() -> u64 {
+    env::var("AGENT_BROWSER_AUTOSAVE_INTERVAL_MS")
+        .ok()
+        .and_then(|s| s.parse::<u64>().ok())
+        .unwrap_or(30_000)
+}
+
+#[cfg(unix)]
+async fn run_socket_server(
+    socket_path: &PathBuf,
+    session: &str,
+    stream_client: Option<Arc<RwLock<Option<Arc<CdpClient>>>>>,
+    stream_server: Option<Arc<StreamServer>>,
+    idle_timeout_ms: Option<u64>,
+    autosave_interval_ms: u64,
+) -> Result<(), String> {
+    use tokio::net::UnixListener;
+
+    let listener =
+        UnixListener::bind(socket_path).map_err(|e| format!("Failed to bind socket: {}", e))?;
+
+    let stream_file: Option<PathBuf> = if stream_server.is_some() {
+        let dir = socket_path.parent().unwrap_or(std::path::Path::new("."));
+        Some(dir.join(format!("{}.stream", session)))
+    } else {
+        None
+    };
+
+    let state: std::sync::Arc<tokio::sync::Mutex<DaemonState>> = std::sync::Arc::new(
+        tokio::sync::Mutex::new(DaemonState::new_with_stream(stream_client, stream_server)),
+    );
+
+    let (reset_tx, mut reset_rx) = mpsc::channel::<()>(64);
+    let reset_tx = idle_timeout_ms.map(|_| Arc::new(reset_tx));
+
+    // Notifier used by handle_connection to signal the daemon loop to exit
+    // after a "close" command, instead of calling process::exit() which skips
+    // destructors and can leave Chrome processes orphaned (issue #1113).
+    let close_notify = Arc::new(Notify::new());
+
+    let mut drain_interval = tokio::time::interval(Duration::from_millis(100));
+    drain_interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+
+    let idle_sleep = idle_timeout_ms.map(|ms| tokio::time::sleep(Duration::from_millis(ms)));
+    let mut idle_sleep_pin = idle_sleep.map(Box::pin);
+
+    loop {
+        tokio::select! {
+            accept_result = listener.accept() => {
+                match accept_result {
+                    Ok((stream, _)) => {
+                        let state = state.clone();
+                        let reset_tx = reset_tx.clone();
+                        let sf = stream_file.clone();
+                        let cn = close_notify.clone();
+                        tokio::spawn(async move {
+                            handle_connection(stream, state, reset_tx, sf, cn).await;
+                        });
+                    }
+                    Err(e) => {
+                        let _ = writeln!(std::io::stderr(), "Accept error: {}", e);
+                    }
+                }
+            }
+            _ = drain_interval.tick() => {
+                let mut s = state.lock().await;
+                let process_exited = s
+                    .browser
+                    .as_mut()
+                    .map(|mgr| mgr.has_process_exited())
+                    .unwrap_or(false);
+                if process_exited {
+                    let _ = close_current_browser(&mut s).await;
+                } else if s.browser.is_some() {
+                    s.drain_cdp_events_background().await;
+                    maybe_autosave_restore_state(&mut s, autosave_interval_ms).await;
+                }
+            }
+            _ = async {
+                match idle_sleep_pin {
+                    Some(ref mut s) => s.as_mut().await,
+                    None => std::future::pending::<()>().await,
+                }
+            }, if idle_timeout_ms.is_some() => {
+                let mut s = state.lock().await;
+                let _ = auto_save_restore_state(&mut s).await;
+                let _ = close_current_browser(&mut s).await;
+                break;
+            }
+            _ = reset_rx.recv(), if idle_timeout_ms.is_some() => {
+                idle_sleep_pin = idle_timeout_ms
+                    .map(|ms| Box::pin(tokio::time::sleep(Duration::from_millis(ms))));
+                continue;
+            }
+            _ = close_notify.notified() => {
+                // "close" command was handled; browser already closed by
+                // handle_close(). Break to run cleanup and exit gracefully
+                // so destructors fire.
+                break;
+            }
+            _ = shutdown_signal() => {
+                let mut s = state.lock().await;
+                let _ = auto_save_restore_state(&mut s).await;
+                let _ = close_current_browser(&mut s).await;
+                break;
+            }
+        }
+    }
+
+    Ok(())
+}
+
+#[cfg(windows)]
+async fn run_socket_server(
+    socket_path: &PathBuf,
+    session: &str,
+    stream_client: Option<Arc<RwLock<Option<Arc<CdpClient>>>>>,
+    stream_server: Option<Arc<StreamServer>>,
+    idle_timeout_ms: Option<u64>,
+    autosave_interval_ms: u64,
+) -> Result<(), String> {
+    use tokio::net::TcpListener;
+
+    let preferred_port = get_port_for_session(session);
+    // Try the hash-derived port first; if it is blocked (e.g. Windows Hyper-V
+    // excluded port range), fall back to an OS-assigned ephemeral port.
+    let listener = match TcpListener::bind(format!("127.0.0.1:{}", preferred_port)).await {
+        Ok(l) => l,
+        Err(_) => TcpListener::bind("127.0.0.1:0")
+            .await
+            .map_err(|e| format!("Failed to bind TCP: {}", e))?,
+    };
+    let actual_port = listener
+        .local_addr()
+        .map_err(|e| format!("Failed to get local address: {}", e))?
+        .port();
+
+    let socket_dir = socket_path.parent().unwrap_or(std::path::Path::new("."));
+    let port_path = socket_dir.join(format!("{}.port", session));
+    let _ = fs::write(&port_path, actual_port.to_string());
+
+    let stream_file: Option<PathBuf> = if stream_server.is_some() {
+        Some(socket_dir.join(format!("{}.stream", session)))
+    } else {
+        None
+    };
+
+    let state: std::sync::Arc<tokio::sync::Mutex<DaemonState>> = std::sync::Arc::new(
+        tokio::sync::Mutex::new(DaemonState::new_with_stream(stream_client, stream_server)),
+    );
+
+    let (reset_tx, mut reset_rx) = mpsc::channel::<()>(64);
+    let reset_tx = idle_timeout_ms.map(|_| Arc::new(reset_tx));
+
+    let close_notify = Arc::new(Notify::new());
+
+    let idle_sleep = idle_timeout_ms.map(|ms| tokio::time::sleep(Duration::from_millis(ms)));
+    let mut idle_sleep_pin = idle_sleep.map(Box::pin);
+
+    // Mirror the unix loop's background tick: reap a browser the user closed
+    // by hand, and drain CDP events (dialog state in particular) before
+    // autosave so a save never runs against a dialog-blocked renderer.
+    let mut drain_interval = tokio::time::interval(Duration::from_millis(100));
+    drain_interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+
+    loop {
+        tokio::select! {
+            accept_result = listener.accept() => {
+                match accept_result {
+                    Ok((stream, _)) => {
+                        let state = state.clone();
+                        let reset_tx = reset_tx.clone();
+                        let sf = stream_file.clone();
+                        let cn = close_notify.clone();
+                        tokio::spawn(async move {
+                            handle_connection(stream, state, reset_tx, sf, cn).await;
+                        });
+                    }
+                    Err(e) => {
+                        let _ = writeln!(std::io::stderr(), "Accept error: {}", e);
+                    }
+                }
+            }
+            _ = drain_interval.tick() => {
+                let mut s = state.lock().await;
+                let process_exited = s
+                    .browser
+                    .as_mut()
+                    .map(|mgr| mgr.has_process_exited())
+                    .unwrap_or(false);
+                if process_exited {
+                    let _ = close_current_browser(&mut s).await;
+                } else if s.browser.is_some() {
+                    s.drain_cdp_events_background().await;
+                    maybe_autosave_restore_state(&mut s, autosave_interval_ms).await;
+                }
+            }
+            _ = async {
+                match idle_sleep_pin {
+                    Some(ref mut s) => s.as_mut().await,
+                    None => std::future::pending::<()>().await,
+                }
+            }, if idle_timeout_ms.is_some() => {
+                let mut s = state.lock().await;
+                let _ = auto_save_restore_state(&mut s).await;
+                let _ = close_current_browser(&mut s).await;
+                let _ = fs::remove_file(&port_path);
+                break;
+            }
+            _ = reset_rx.recv(), if idle_timeout_ms.is_some() => {
+                idle_sleep_pin = idle_timeout_ms
+                    .map(|ms| Box::pin(tokio::time::sleep(Duration::from_millis(ms))));
+                continue;
+            }
+            _ = close_notify.notified() => {
+                let _ = fs::remove_file(&port_path);
+                break;
+            }
+            _ = shutdown_signal() => {
+                let mut s = state.lock().await;
+                let _ = auto_save_restore_state(&mut s).await;
+                let _ = close_current_browser(&mut s).await;
+                let _ = fs::remove_file(&port_path);
+                break;
+            }
+        }
+    }
+
+    Ok(())
+}
+
+async fn handle_connection<S>(
+    stream: S,
+    state: std::sync::Arc<tokio::sync::Mutex<DaemonState>>,
+    idle_reset_tx: Option<Arc<mpsc::Sender<()>>>,
+    stream_file_cleanup: Option<PathBuf>,
+    close_notify: Arc<Notify>,
+) where
+    S: tokio::io::AsyncRead + tokio::io::AsyncWrite + Unpin,
+{
+    let (reader, mut writer) = tokio::io::split(stream);
+    let mut buf_reader = BufReader::new(reader);
+    let mut line = String::new();
+
+    loop {
+        line.clear();
+        match buf_reader.read_line(&mut line).await {
+            Ok(0) => break,
+            Ok(_) => {
+                let trimmed = line.trim();
+                if trimmed.is_empty() {
+                    continue;
+                }
+
+                if looks_like_http(trimmed) {
+                    break;
+                }
+
+                let cmd: Value = match serde_json::from_str(trimmed) {
+                    Ok(v) => v,
+                    Err(e) => {
+                        let err = serde_json::json!({
+                            "success": false,
+                            "error": format!("Invalid JSON: {}", e),
+                        });
+                        let mut resp = serde_json::to_string(&err).unwrap_or_default();
+                        resp.push('\n');
+                        let _ = writer.write_all(resp.as_bytes()).await;
+                        continue;
+                    }
+                };
+
+                if let Some(ref tx) = idle_reset_tx {
+                    let _ = tx.try_send(());
+                }
+
+                let action = cmd
+                    .get("action")
+                    .and_then(|v| v.as_str())
+                    .unwrap_or_default()
+                    .to_string();
+
+                let response = {
+                    let mut s = state.lock().await;
+                    execute_command(&cmd, &mut s).await
+                };
+
+                let mut resp = serde_json::to_string(&response).unwrap_or_default();
+                resp.push('\n');
+                if writer.write_all(resp.as_bytes()).await.is_err() {
+                    break;
+                }
+
+                if close_completed_response(&action, &response) {
+                    if let Some(ref path) = stream_file_cleanup {
+                        let _ = fs::remove_file(path);
+                    }
+                    // Signal the daemon loop to exit gracefully instead of
+                    // calling process::exit(), which skips destructors and
+                    // can leave Chrome processes orphaned (issue #1113).
+                    tokio::time::sleep(tokio::time::Duration::from_millis(100)).await;
+                    close_notify.notify_one();
+                    return;
+                }
+            }
+            Err(_) => break,
+        }
+    }
+}
+
+fn looks_like_http(line: &str) -> bool {
+    let prefixes = [
+        "GET ", "POST ", "PUT ", "DELETE ", "PATCH ", "HEAD ", "OPTIONS ", "CONNECT ", "TRACE ",
+    ];
+    prefixes.iter().any(|p| line.starts_with(p))
+}
+
+fn close_completed_response(action: &str, response: &Value) -> bool {
+    if !matches!(
+        action,
+        "close" | "confirm" | INTERNAL_DAEMON_SHUTDOWN_ACTION
+    ) {
+        return false;
+    }
+
+    fn data_closed(data: &Value) -> bool {
+        data.get("closed").and_then(|v| v.as_bool()) == Some(true)
+    }
+
+    if response.get("success").and_then(|v| v.as_bool()) != Some(true) {
+        return false;
+    }
+
+    let Some(data) = response.get("data") else {
+        return false;
+    };
+    if data_closed(data) {
+        return true;
+    }
+
+    data.get("result").is_some_and(|result| {
+        result.get("success").and_then(|v| v.as_bool()) == Some(true)
+            && result.get("data").is_some_and(data_closed)
+    })
+}
+
+async fn shutdown_signal() {
+    #[cfg(unix)]
+    {
+        let mut sigint = match signal::unix::signal(signal::unix::SignalKind::interrupt()) {
+            Ok(s) => s,
+            Err(e) => {
+                let _ = writeln!(std::io::stderr(), "Failed to install SIGINT handler: {}", e);
+                process::exit(1);
+            }
+        };
+        let mut sigterm = match signal::unix::signal(signal::unix::SignalKind::terminate()) {
+            Ok(s) => s,
+            Err(e) => {
+                let _ = writeln!(
+                    std::io::stderr(),
+                    "Failed to install SIGTERM handler: {}",
+                    e
+                );
+                process::exit(1);
+            }
+        };
+        let mut sighup = match signal::unix::signal(signal::unix::SignalKind::hangup()) {
+            Ok(s) => s,
+            Err(e) => {
+                let _ = writeln!(std::io::stderr(), "Failed to install SIGHUP handler: {}", e);
+                process::exit(1);
+            }
+        };
+
+        tokio::select! {
+            _ = sigint.recv() => {}
+            _ = sigterm.recv() => {}
+            _ = sighup.recv() => {}
+        }
+    }
+
+    #[cfg(windows)]
+    {
+        if let Err(e) = signal::ctrl_c().await {
+            let _ = writeln!(std::io::stderr(), "Failed to install Ctrl+C handler: {}", e);
+            process::exit(1);
+        }
+    }
+}
+
+fn get_daemon_socket_dir() -> PathBuf {
+    crate::connection::get_socket_dir()
+}
+
+#[cfg(windows)]
+fn get_port_for_session(session: &str) -> u16 {
+    crate::connection::get_port_for_session(session)
+}
+
+#[cfg(test)]
+mod tests {
+    #[allow(unused_imports)]
+    use super::*;
+
+    #[test]
+    fn test_daemon_socket_dir_matches_client_namespace() {
+        let guard = crate::test_utils::EnvGuard::new(&[
+            "AGENT_BROWSER_SOCKET_DIR",
+            "XDG_RUNTIME_DIR",
+            "AGENT_BROWSER_NAMESPACE",
+        ]);
+        let dir = tempfile::tempdir().unwrap();
+        guard.set("AGENT_BROWSER_SOCKET_DIR", dir.path().to_str().unwrap());
+        guard.remove("XDG_RUNTIME_DIR");
+        guard.set("AGENT_BROWSER_NAMESPACE", "Worktree: One");
+
+        let socket_dir = get_daemon_socket_dir();
+
+        assert_eq!(socket_dir, crate::connection::get_socket_dir());
+        assert!(socket_dir.ends_with(
+            std::path::PathBuf::from("namespaces")
+                .join("worktree-one")
+                .join("run")
+        ));
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn test_port_matches_client_algorithm() {
+        let guard = crate::test_utils::EnvGuard::new(&["AGENT_BROWSER_NAMESPACE"]);
+        guard.remove("AGENT_BROWSER_NAMESPACE");
+
+        assert_eq!(get_port_for_session("default"), 50838);
+        assert_eq!(get_port_for_session("my-session"), 63105);
+        assert_eq!(get_port_for_session("work"), 51184);
+        assert_eq!(get_port_for_session(""), 49152);
+    }
+
+    #[test]
+    fn test_close_completed_response_requires_actual_close_result() {
+        let confirmation_response = serde_json::json!({
+            "success": true,
+            "data": {
+                "confirmation_required": true,
+                "confirmation_id": "close-1",
+                "action": "close"
+            }
+        });
+
+        assert!(!close_completed_response("close", &confirmation_response));
+    }
+
+    #[test]
+    fn test_close_completed_response_accepts_direct_and_confirmed_close() {
+        let direct = serde_json::json!({
+            "success": true,
+            "data": { "closed": true }
+        });
+        let confirmed = serde_json::json!({
+            "success": true,
+            "data": {
+                "confirmed": true,
+                "action": "close",
+                "result": {
+                    "success": true,
+                    "data": { "closed": true }
+                }
+            }
+        });
+
+        assert!(close_completed_response("close", &direct));
+        assert!(close_completed_response(
+            crate::connection::INTERNAL_DAEMON_SHUTDOWN_ACTION,
+            &direct
+        ));
+        assert!(close_completed_response("confirm", &confirmed));
+    }
+
+    /// Guard against re-introducing `waitpid(-1)` in daemon code.
+    ///
+    /// Issue #1035: a SIGCHLD handler that called `waitpid(-1, WNOHANG)` was
+    /// added in v0.22.3 to reap zombie Chrome processes. This races with
+    /// Rust's `Child::try_wait()` / `Child::wait()` because `waitpid(-1)`
+    /// reaps *any* child, stealing the exit status before Rust can collect
+    /// it. The result is ECHILD errors in `BrowserManager::has_process_exited()`
+    /// and `ChromeProcess::kill()`, which can leave the daemon in a broken
+    /// state or cause hangs on certain Linux configurations.
+    ///
+    /// The fix uses the existing 500ms drain interval to call
+    /// `has_process_exited()` (which delegates to `Child::try_wait()`)
+    /// for targeted, race-free zombie detection.
+    #[test]
+    fn test_no_waitpid_minus_one_in_daemon() {
+        let source = include_str!("daemon.rs");
+        // Only check production code (everything before `#[cfg(test)]`)
+        let production_code = source.split("#[cfg(test)]").next().unwrap_or(source);
+        assert!(
+            !production_code.contains("waitpid(-1"),
+            "daemon.rs production code must not call waitpid(-1, ...). \
+             Use Child::try_wait() via has_process_exited() instead. \
+             See issue #1035."
+        );
+    }
+
+    /// Verify that `Child::try_wait()` correctly detects a crashed child
+    /// without needing a global SIGCHLD handler or `waitpid(-1)`.
+    /// This is what `has_process_exited()` uses in the fixed code.
+    #[cfg(unix)]
+    #[test]
+    fn test_child_try_wait_detects_exit_without_sigchld_handler() {
+        use std::process::{Command, Stdio};
+
+        let mut child = Command::new("/bin/sh")
+            .args(["-c", "exit 42"])
+            .stdin(Stdio::null())
+            .stdout(Stdio::null())
+            .stderr(Stdio::null())
+            .spawn()
+            .expect("failed to spawn child");
+
+        std::thread::sleep(std::time::Duration::from_millis(200));
+
+        match child.try_wait() {
+            Ok(Some(status)) => {
+                assert!(
+                    !status.success(),
+                    "child exited with code 42, should not be success"
+                );
+            }
+            Ok(None) => panic!("try_wait() returned None but child should have exited"),
+            Err(e) => panic!("try_wait() should succeed without waitpid(-1): {}", e),
+        }
+    }
+
+    /// Regression test for #1101: idle timeout must fire even while the
+    /// drain interval ticks every 500 ms.  The bug was that `sleep_future`
+    /// was created **inside** the loop, so each drain tick dropped the
+    /// in-progress sleep and replaced it with a fresh one – the timer
+    /// could never reach its deadline.
+    #[tokio::test]
+    async fn test_idle_timeout_fires_despite_drain_interval() {
+        use tokio::sync::mpsc;
+
+        let idle_timeout_ms: u64 = 1000;
+        let mut drain_interval = tokio::time::interval(Duration::from_millis(500));
+        drain_interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+
+        let (_reset_tx, mut reset_rx) = mpsc::channel::<()>(64);
+
+        let start = tokio::time::Instant::now();
+
+        let exited = tokio::time::timeout(Duration::from_secs(5), async {
+            let mut idle_sleep_pin = Some(Box::pin(tokio::time::sleep(Duration::from_millis(
+                idle_timeout_ms,
+            ))));
+
+            loop {
+                tokio::select! {
+                    _ = drain_interval.tick() => {}
+                    _ = async {
+                        match idle_sleep_pin {
+                            Some(ref mut s) => s.as_mut().await,
+                            None => std::future::pending::<()>().await,
+                        }
+                    } => {
+                        break;
+                    }
+                    _ = reset_rx.recv() => {
+                        idle_sleep_pin = Some(Box::pin(
+                            tokio::time::sleep(Duration::from_millis(idle_timeout_ms)),
+                        ));
+                        continue;
+                    }
+                }
+            }
+        })
+        .await;
+
+        let elapsed = start.elapsed();
+
+        assert!(
+            exited.is_ok(),
+            "idle timeout never fired – loop ran for >5 s (bug #1101)"
+        );
+        assert!(
+            elapsed < Duration::from_millis(idle_timeout_ms + 500),
+            "idle timeout took too long: {:?} (expected ~{} ms)",
+            elapsed,
+            idle_timeout_ms,
+        );
+    }
+
+    /// Verify that `ChromeProcess::has_exited()` (which uses `Child::try_wait()`)
+    /// correctly detects a killed child, the same way the drain interval does
+    /// in the fixed daemon code. This ensures crash detection works without
+    /// a SIGCHLD handler.
+    #[cfg(unix)]
+    #[test]
+    fn test_has_exited_detects_killed_process() {
+        use std::process::{Command, Stdio};
+
+        let mut child = Command::new("/bin/sh")
+            .args(["-c", "sleep 60"])
+            .stdin(Stdio::null())
+            .stdout(Stdio::null())
+            .stderr(Stdio::null())
+            .spawn()
+            .expect("failed to spawn child");
+
+        // Process should be running
+        match child.try_wait() {
+            Ok(None) => {} // expected
+            other => panic!("expected Ok(None) for running process, got {:?}", other),
+        }
+
+        // Kill it (simulates Chrome crash)
+        child.kill().expect("failed to kill child");
+        std::thread::sleep(std::time::Duration::from_millis(100));
+
+        // try_wait should detect the exit
+        match child.try_wait() {
+            Ok(Some(_)) => {} // expected: detected the crash
+            other => panic!(
+                "expected Ok(Some(_)) after kill, got {:?}. \
+                 Crash detection via try_wait() must work for the drain \
+                 interval fix (issue #1035) to function correctly.",
+                other
+            ),
+        }
+    }
+}

cli/src/native/diff.rs

@@ -0,0 +1,274 @@
+use serde_json::{json, Value};
+use similar::{ChangeTag, TextDiff};
+
+pub struct ScreenshotDiffResult {
+    pub total_pixels: u64,
+    pub different_pixels: u64,
+    pub mismatch_percentage: f64,
+    pub matched: bool,
+    pub diff_image: Option<Vec<u8>>,
+    pub dimension_mismatch: Option<Value>,
+}
+
+pub struct SnapshotDiffResult {
+    pub diff: String,
+    pub additions: usize,
+    pub removals: usize,
+    pub unchanged: usize,
+    pub changed: bool,
+}
+
+pub fn diff_screenshot(
+    baseline: &[u8],
+    current: &[u8],
+    threshold: f64,
+) -> Result<ScreenshotDiffResult, String> {
+    let img_a = image::load_from_memory(baseline)
+        .map_err(|e| format!("Failed to decode baseline image: {}", e))?;
+    let img_b = image::load_from_memory(current)
+        .map_err(|e| format!("Failed to decode current image: {}", e))?;
+
+    let (wa, ha) = (img_a.width(), img_a.height());
+    let (wb, hb) = (img_b.width(), img_b.height());
+
+    if wa != wb || ha != hb {
+        return Ok(ScreenshotDiffResult {
+            total_pixels: (wa as u64) * (ha as u64),
+            different_pixels: (wa as u64) * (ha as u64),
+            mismatch_percentage: 100.0,
+            matched: false,
+            diff_image: None,
+            dimension_mismatch: Some(json!({
+                "expected": { "width": wa, "height": ha },
+                "actual": { "width": wb, "height": hb },
+            })),
+        });
+    }
+
+    let rgba_a = img_a.to_rgba8();
+    let rgba_b = img_b.to_rgba8();
+    let total = (wa as u64) * (ha as u64);
+    let max_color_distance = threshold * 255.0 * (3.0_f64).sqrt();
+    let mut different = 0u64;
+
+    let mut diff_img = image::RgbaImage::new(wa, ha);
+
+    for y in 0..ha {
+        for x in 0..wa {
+            let pa = rgba_a.get_pixel(x, y);
+            let pb = rgba_b.get_pixel(x, y);
+            let dr = (pa[0] as f64) - (pb[0] as f64);
+            let dg = (pa[1] as f64) - (pb[1] as f64);
+            let db = (pa[2] as f64) - (pb[2] as f64);
+            let dist = (dr * dr + dg * dg + db * db).sqrt();
+
+            if dist > max_color_distance {
+                different += 1;
+                diff_img.put_pixel(x, y, image::Rgba([255, 0, 0, 255]));
+            } else {
+                let gray = ((pa[0] as u16 + pa[1] as u16 + pa[2] as u16) / 3) as u8;
+                let dimmed = (gray as f64 * 0.3) as u8;
+                diff_img.put_pixel(x, y, image::Rgba([dimmed, dimmed, dimmed, 255]));
+            }
+        }
+    }
+
+    let mismatch = if total > 0 {
+        (different as f64 / total as f64) * 100.0
+    } else {
+        0.0
+    };
+
+    let diff_bytes = if different > 0 {
+        let mut buf = std::io::Cursor::new(Vec::new());
+        diff_img
+            .write_to(&mut buf, image::ImageFormat::Png)
+            .map_err(|e| format!("Failed to encode diff image: {}", e))?;
+        Some(buf.into_inner())
+    } else {
+        None
+    };
+
+    Ok(ScreenshotDiffResult {
+        total_pixels: total,
+        different_pixels: different,
+        mismatch_percentage: mismatch,
+        matched: different == 0,
+        diff_image: diff_bytes,
+        dimension_mismatch: None,
+    })
+}
+
+/// Compute a snapshot diff using the Myers algorithm via the `similar` crate.
+pub fn diff_snapshots(before: &str, after: &str) -> SnapshotDiffResult {
+    // Fast path: identical inputs.
+    // This avoids constructing the `similar` TextDiff object and running the diff
+    // iteration when agents compare a snapshot to itself (common in retry/loop
+    // workloads).
+    if before == after {
+        let unchanged = before.lines().count();
+        return SnapshotDiffResult {
+            diff: String::new(),
+            additions: 0,
+            removals: 0,
+            unchanged,
+            changed: false,
+        };
+    }
+
+    let text_diff = TextDiff::from_lines(before, after);
+
+    let mut additions = 0usize;
+    let mut removals = 0usize;
+    let mut unchanged = 0usize;
+
+    for change in text_diff.iter_all_changes() {
+        match change.tag() {
+            ChangeTag::Insert => additions += 1,
+            ChangeTag::Delete => removals += 1,
+            ChangeTag::Equal => unchanged += 1,
+        }
+    }
+
+    let changed = additions > 0 || removals > 0;
+
+    let diff = text_diff
+        .unified_diff()
+        .context_radius(3)
+        .header("before", "after")
+        .to_string();
+
+    SnapshotDiffResult {
+        diff,
+        additions,
+        removals,
+        unchanged,
+        changed,
+    }
+}
+
+/// Legacy JSON diff output for backwards compatibility.
+pub fn diff_text(a: &str, b: &str) -> Value {
+    let result = diff_snapshots(a, b);
+    json!({
+        "identical": !result.changed,
+        "additions": result.additions,
+        "removals": result.removals,
+        "deletions": result.removals,
+        "unchanged": result.unchanged,
+        "changed": result.changed,
+    })
+}
+
+pub fn diff_unified(a: &str, b: &str) -> String {
+    diff_snapshots(a, b).diff
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_diff_identical() {
+        let result = diff_text("hello\nworld", "hello\nworld");
+        assert_eq!(result.get("identical").unwrap(), true);
+        assert_eq!(result.get("changed").unwrap(), false);
+        assert_eq!(result.get("unchanged").unwrap(), 2);
+    }
+
+    #[test]
+    fn test_diff_additions() {
+        let result = diff_text("hello\n", "hello\nworld\n");
+        assert_eq!(result.get("identical").unwrap(), false);
+        assert_eq!(result.get("changed").unwrap(), true);
+        assert!(result.get("additions").unwrap().as_i64().unwrap() > 0);
+    }
+
+    #[test]
+    fn test_diff_deletions() {
+        let result = diff_text("hello\nworld\n", "hello\n");
+        assert_eq!(result.get("identical").unwrap(), false);
+        assert!(result.get("removals").unwrap().as_i64().unwrap() > 0);
+    }
+
+    #[test]
+    fn test_diff_unified_output() {
+        let output = diff_unified("a\nb\nc\n", "a\nx\nc\n");
+        assert!(output.contains("---"));
+        assert!(output.contains("+++"));
+    }
+
+    #[test]
+    fn test_snapshot_diff_struct() {
+        let result = diff_snapshots("line1\nline2\n", "line1\nline3\n");
+        assert!(result.changed);
+        assert_eq!(result.additions, 1);
+        assert_eq!(result.removals, 1);
+        assert_eq!(result.unchanged, 1);
+        assert!(!result.diff.is_empty());
+    }
+
+    #[test]
+    fn test_diff_snapshots_identical_fast_path() {
+        let input = "hello\nworld\n";
+        let result = diff_snapshots(input, input);
+        assert!(!result.changed);
+        assert_eq!(result.additions, 0);
+        assert_eq!(result.removals, 0);
+        assert_eq!(result.unchanged, input.lines().count());
+        assert!(result.diff.is_empty());
+    }
+
+    #[test]
+    #[ignore]
+    fn bench_diff_snapshots_identical_and_changed() {
+        use std::hint::black_box;
+        use std::time::Instant;
+
+        let identical_a = (0..200)
+            .map(|i| format!("line {i}"))
+            .collect::<Vec<_>>()
+            .join("\n");
+        let identical_b = identical_a.clone();
+
+        let changed_a = identical_a.clone();
+        let changed_b = (0..200)
+            .map(|i| {
+                if i == 123 {
+                    format!("line {i} changed")
+                } else {
+                    format!("line {i}")
+                }
+            })
+            .collect::<Vec<_>>()
+            .join("\n");
+
+        // Keep the iteration count high enough to measure, but low enough
+        // to avoid long CI times when someone runs `--ignored`.
+        let iters = 50_000usize;
+
+        let start = Instant::now();
+        let mut acc_changed = 0usize;
+        for _ in 0..iters {
+            let r = diff_snapshots(black_box(&identical_a), black_box(&identical_b));
+            acc_changed ^= r.unchanged;
+        }
+        let identical_ms = start.elapsed().as_secs_f64() * 1000.0;
+
+        let start = Instant::now();
+        let mut acc_changed2 = 0usize;
+        for _ in 0..iters {
+            let r = diff_snapshots(black_box(&changed_a), black_box(&changed_b));
+            acc_changed2 ^= r.additions;
+        }
+        let changed_ms = start.elapsed().as_secs_f64() * 1000.0;
+
+        // Prevent the compiler from optimizing everything away.
+        black_box(acc_changed);
+        black_box(acc_changed2);
+
+        println!(
+            "bench_diff_snapshots_identical_and_changed: iters={iters} identical_ms={identical_ms:.2} changed_ms={changed_ms:.2}"
+        );
+    }
+}

cli/src/native/inspect_server.rs

@@ -0,0 +1,362 @@
+use std::io::Write;
+use std::sync::atomic::{AtomicI64, Ordering};
+use std::sync::Arc;
+
+use futures_util::{SinkExt, StreamExt};
+use tokio::io::{AsyncBufReadExt, AsyncReadExt, AsyncWriteExt, BufReader};
+use tokio::net::TcpListener;
+use tokio::sync::Mutex;
+use tokio_tungstenite::tungstenite::Message;
+
+use super::cdp::client::InspectProxyHandle;
+
+/// Counter for unique attach IDs so concurrent connections don't collide.
+static ATTACH_ID: AtomicI64 = AtomicI64::new(-1000);
+
+/// Lightweight HTTP + WebSocket server for `agent-browser inspect`.
+///
+/// Serves two purposes:
+/// - `GET /` redirects to Chrome's built-in DevTools frontend with `ws=` pointing to this server
+/// - WebSocket connections create a dedicated CDP session via `Target.attachToTarget` and proxy
+///   CDP messages through the daemon's existing browser-level connection, injecting/stripping
+///   `sessionId` so the DevTools frontend sees a page-level view
+pub struct InspectServer {
+    port: u16,
+    _handle: tokio::task::JoinHandle<()>,
+}
+
+impl InspectServer {
+    /// Start the inspect proxy server.
+    ///
+    /// - `proxy_handle`: lightweight handle for sending/receiving raw CDP messages
+    /// - `target_id`: the CDP target ID of the page to inspect
+    /// - `chrome_host_port`: the Chrome debug server address (e.g. "127.0.0.1:9222")
+    pub async fn start(
+        proxy_handle: InspectProxyHandle,
+        target_id: String,
+        chrome_host_port: String,
+    ) -> Result<Self, String> {
+        let listener = TcpListener::bind("127.0.0.1:0")
+            .await
+            .map_err(|e| format!("Failed to bind inspect server: {}", e))?;
+        let port = listener
+            .local_addr()
+            .map_err(|e| format!("Failed to get local addr: {}", e))?
+            .port();
+
+        let proxy = Arc::new(proxy_handle);
+
+        let handle = tokio::spawn(accept_loop(
+            listener,
+            proxy,
+            target_id,
+            chrome_host_port,
+            port,
+        ));
+
+        Ok(Self {
+            port,
+            _handle: handle,
+        })
+    }
+
+    pub fn port(&self) -> u16 {
+        self.port
+    }
+
+    pub fn shutdown(self) {
+        self._handle.abort();
+    }
+}
+
+async fn accept_loop(
+    listener: TcpListener,
+    proxy: Arc<InspectProxyHandle>,
+    target_id: String,
+    chrome_host_port: String,
+    proxy_port: u16,
+) {
+    loop {
+        let (stream, _) = match listener.accept().await {
+            Ok(s) => s,
+            Err(_) => continue,
+        };
+
+        let proxy = proxy.clone();
+        let tid = target_id.clone();
+        let chp = chrome_host_port.clone();
+
+        tokio::spawn(async move {
+            if let Err(e) = handle_connection(stream, proxy, tid, chp, proxy_port).await {
+                let _ = writeln!(std::io::stderr(), "[inspect] connection error: {}", e);
+            }
+        });
+    }
+}
+
+async fn handle_connection(
+    stream: tokio::net::TcpStream,
+    proxy: Arc<InspectProxyHandle>,
+    target_id: String,
+    chrome_host_port: String,
+    proxy_port: u16,
+) -> Result<(), String> {
+    // Peek at the request line to determine routing WITHOUT consuming bytes.
+    // This is critical: tokio_tungstenite::accept_async needs to read the full
+    // HTTP upgrade request itself, so we must not consume anything for WS paths.
+    let mut peek_buf = [0u8; 32];
+    let n = stream
+        .peek(&mut peek_buf)
+        .await
+        .map_err(|e| e.to_string())?;
+    let peek = String::from_utf8_lossy(&peek_buf[..n]);
+
+    if peek.starts_with("GET /ws") {
+        return handle_ws_proxy(stream, proxy, target_id).await;
+    }
+
+    if peek.starts_with("GET / ") {
+        let buf_reader = BufReader::new(stream);
+        return handle_http_redirect(buf_reader, chrome_host_port, proxy_port).await;
+    }
+
+    // Unknown request -- consume and respond 404
+    let mut stream = stream;
+    let mut discard = [0u8; 4096];
+    let _ = stream.read(&mut discard).await;
+    let resp = "HTTP/1.1 404 Not Found\r\nContent-Length: 0\r\nConnection: close\r\n\r\n";
+    stream
+        .write_all(resp.as_bytes())
+        .await
+        .map_err(|e| e.to_string())?;
+    Ok(())
+}
+
+const MAX_HEADER_BYTES: usize = 8192;
+
+async fn handle_http_redirect(
+    buf_reader: BufReader<tokio::net::TcpStream>,
+    chrome_host_port: String,
+    proxy_port: u16,
+) -> Result<(), String> {
+    let mut br = buf_reader;
+    let mut total_bytes = 0usize;
+    loop {
+        let mut line = String::new();
+        let n = br.read_line(&mut line).await.map_err(|e| e.to_string())?;
+        total_bytes += n;
+        if line == "\r\n" || line == "\n" || line.is_empty() || total_bytes > MAX_HEADER_BYTES {
+            break;
+        }
+    }
+
+    let location = format!(
+        "http://{}/devtools/devtools_app.html?ws=127.0.0.1:{}/ws",
+        chrome_host_port, proxy_port
+    );
+    let body = format!(
+        "<html><body>Redirecting to <a href=\"{url}\">{url}</a></body></html>",
+        url = location
+    );
+    let resp = format!(
+        "HTTP/1.1 302 Found\r\nLocation: {}\r\nContent-Type: text/html\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
+        location,
+        body.len(),
+        body
+    );
+    let mut stream = br.into_inner();
+    stream
+        .write_all(resp.as_bytes())
+        .await
+        .map_err(|e| e.to_string())?;
+    Ok(())
+}
+
+async fn handle_ws_proxy(
+    stream: tokio::net::TcpStream,
+    proxy: Arc<InspectProxyHandle>,
+    target_id: String,
+) -> Result<(), String> {
+    let ws_stream = tokio_tungstenite::accept_async(stream)
+        .await
+        .map_err(|e| format!("WebSocket handshake failed: {}", e))?;
+
+    // Create a dedicated CDP session for this DevTools connection.
+    // Each connection gets its own session so domain enablements (DOM.enable, etc.)
+    // always trigger fresh initial state dumps from Chrome.
+    let attach_id = ATTACH_ID.fetch_sub(1, Ordering::SeqCst);
+    let attach_cmd = format!(
+        r#"{{"id":{},"method":"Target.attachToTarget","params":{{"targetId":"{}","flatten":true}}}}"#,
+        attach_id, target_id
+    );
+
+    // Subscribe BEFORE sending so we don't miss the response (tokio broadcast
+    // receivers only deliver messages to receivers that already exist).
+    let mut raw_rx = proxy.subscribe_raw();
+
+    proxy
+        .send_raw(attach_cmd)
+        .await
+        .map_err(|e| format!("Failed to send attachToTarget: {}", e))?;
+
+    // Wait for the attachToTarget response to extract the session ID
+    let session_id = tokio::time::timeout(std::time::Duration::from_secs(5), async {
+        while let Ok(raw_msg) = raw_rx.recv().await {
+            if let Ok(val) = serde_json::from_str::<serde_json::Value>(&raw_msg.text) {
+                if val.get("id").and_then(|v| v.as_i64()) == Some(attach_id) {
+                    if let Some(sid) = val
+                        .get("result")
+                        .and_then(|r| r.get("sessionId"))
+                        .and_then(|s| s.as_str())
+                    {
+                        return Ok(sid.to_string());
+                    }
+                    return Err("attachToTarget failed".to_string());
+                }
+            }
+        }
+        Err("raw message channel closed".to_string())
+    })
+    .await
+    .map_err(|_| "Timed out waiting for attachToTarget response".to_string())?
+    .map_err(|e| format!("Failed to create DevTools session: {}", e))?;
+
+    let (ws_tx, mut ws_rx) = ws_stream.split();
+    let ws_tx = Arc::new(Mutex::new(ws_tx));
+
+    let mut raw_rx = proxy.subscribe_raw();
+    let ws_tx_clone = ws_tx.clone();
+    let session_id_clone = session_id.clone();
+
+    // Chrome -> DevTools: forward messages matching our session, strip sessionId
+    let mut chrome_to_devtools = tokio::spawn(async move {
+        loop {
+            let raw_msg = match raw_rx.recv().await {
+                Ok(msg) => msg,
+                Err(tokio::sync::broadcast::error::RecvError::Lagged(n)) => {
+                    let _ = writeln!(
+                        std::io::stderr(),
+                        "[inspect] warning: dropped {} CDP messages (channel lag)",
+                        n
+                    );
+                    continue;
+                }
+                Err(_) => break,
+            };
+
+            if raw_msg.session_id.as_deref() != Some(&session_id_clone) {
+                continue;
+            }
+
+            let stripped = strip_session_id(&raw_msg.text);
+
+            let mut tx = ws_tx_clone.lock().await;
+            if tx.send(Message::Text(stripped)).await.is_err() {
+                break;
+            }
+        }
+    });
+
+    // DevTools -> Chrome: inject sessionId and forward
+    let proxy_for_send = proxy.clone();
+    let session_id_for_send = session_id.clone();
+    let mut devtools_to_chrome = tokio::spawn(async move {
+        while let Some(Ok(msg)) = ws_rx.next().await {
+            let text = match msg {
+                Message::Text(t) => t,
+                Message::Close(_) => break,
+                _ => continue,
+            };
+
+            let injected = inject_session_id(&text, &session_id_for_send);
+            if proxy_for_send.send_raw(injected).await.is_err() {
+                break;
+            }
+        }
+    });
+
+    tokio::select! {
+        _ = &mut chrome_to_devtools => {
+            devtools_to_chrome.abort();
+        },
+        _ = &mut devtools_to_chrome => {
+            chrome_to_devtools.abort();
+        },
+    }
+
+    // Clean up the CDP session so Chrome doesn't leak attached targets
+    let detach_cmd = format!(
+        r#"{{"id":{},"method":"Target.detachFromTarget","params":{{"sessionId":"{}"}}}}"#,
+        ATTACH_ID.fetch_sub(1, Ordering::SeqCst),
+        session_id
+    );
+    let _ = proxy.send_raw(detach_cmd).await;
+
+    Ok(())
+}
+
+fn inject_session_id(json: &str, session_id: &str) -> String {
+    if let Ok(mut val) = serde_json::from_str::<serde_json::Value>(json) {
+        if let Some(obj) = val.as_object_mut() {
+            obj.insert(
+                "sessionId".to_string(),
+                serde_json::Value::String(session_id.to_string()),
+            );
+        }
+        serde_json::to_string(&val).unwrap_or_else(|_| json.to_string())
+    } else {
+        json.to_string()
+    }
+}
+
+fn strip_session_id(json: &str) -> String {
+    if let Ok(mut val) = serde_json::from_str::<serde_json::Value>(json) {
+        if let Some(obj) = val.as_object_mut() {
+            obj.remove("sessionId");
+        }
+        serde_json::to_string(&val).unwrap_or_else(|_| json.to_string())
+    } else {
+        json.to_string()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_inject_session_id() {
+        let input = r#"{"id":1,"method":"DOM.getDocument"}"#;
+        let result = inject_session_id(input, "abc123");
+        let parsed: serde_json::Value = serde_json::from_str(&result).expect("valid JSON");
+        assert_eq!(parsed["sessionId"], "abc123");
+        assert_eq!(parsed["method"], "DOM.getDocument");
+        assert_eq!(parsed["id"], 1);
+    }
+
+    #[test]
+    fn test_inject_session_id_empty_object() {
+        let result = inject_session_id("{}", "abc");
+        let parsed: serde_json::Value = serde_json::from_str(&result).expect("valid JSON");
+        assert_eq!(parsed["sessionId"], "abc");
+    }
+
+    #[test]
+    fn test_strip_session_id() {
+        let input = r#"{"id":1,"result":{},"sessionId":"abc123"}"#;
+        let result = strip_session_id(input);
+        let parsed: serde_json::Value = serde_json::from_str(&result).expect("valid JSON");
+        assert!(parsed.get("sessionId").is_none());
+        assert_eq!(parsed["id"], 1);
+    }
+
+    #[test]
+    fn test_inject_then_strip_roundtrip() {
+        let input = r#"{"id":42,"method":"Runtime.evaluate"}"#;
+        let injected = inject_session_id(input, "sess1");
+        let stripped = strip_session_id(&injected);
+        let original: serde_json::Value = serde_json::from_str(input).unwrap();
+        let result: serde_json::Value = serde_json::from_str(&stripped).unwrap();
+        assert_eq!(original, result);
+    }
+}

cli/src/native/mod.rs

@@ -0,0 +1,49 @@
+#[allow(dead_code)]
+pub mod actions;
+#[allow(dead_code)]
+pub mod auth;
+#[allow(dead_code)]
+pub mod browser;
+#[allow(dead_code)]
+pub mod cdp;
+#[allow(dead_code)]
+pub mod cookies;
+#[allow(dead_code)]
+pub mod daemon;
+#[allow(dead_code)]
+pub mod diff;
+#[allow(dead_code)]
+pub mod element;
+#[allow(dead_code)]
+pub mod inspect_server;
+#[allow(dead_code)]
+pub mod interaction;
+#[allow(dead_code)]
+pub mod network;
+#[allow(dead_code)]
+pub mod policy;
+#[allow(dead_code)]
+pub mod providers;
+#[allow(dead_code)]
+pub mod react;
+#[allow(dead_code)]
+pub mod recording;
+#[allow(dead_code)]
+pub mod screenshot;
+#[allow(dead_code)]
+pub mod snapshot;
+#[allow(dead_code)]
+pub mod state;
+#[allow(dead_code)]
+pub mod storage;
+#[allow(dead_code)]
+pub mod stream;
+#[allow(dead_code)]
+pub mod tracing;
+#[allow(dead_code)]
+pub mod webdriver;
+
+#[cfg(test)]
+mod e2e_tests;
+#[cfg(test)]
+mod parity_tests;

cli/src/native/network.rs

@@ -0,0 +1,672 @@
+use serde_json::{json, Value};
+use std::collections::HashMap;
+
+use super::cdp::client::CdpClient;
+
+pub async fn set_extra_headers(
+    client: &CdpClient,
+    session_id: &str,
+    headers: &HashMap<String, String>,
+) -> Result<(), String> {
+    let headers_value: Value = headers
+        .iter()
+        .map(|(k, v)| (k.clone(), Value::String(v.clone())))
+        .collect::<serde_json::Map<String, Value>>()
+        .into();
+
+    client
+        .send_command(
+            "Network.setExtraHTTPHeaders",
+            Some(json!({ "headers": headers_value })),
+            Some(session_id),
+        )
+        .await?;
+
+    Ok(())
+}
+
+pub async fn set_offline(
+    client: &CdpClient,
+    session_id: &str,
+    offline: bool,
+) -> Result<(), String> {
+    client
+        .send_command(
+            "Network.emulateNetworkConditions",
+            Some(json!({
+                "offline": offline,
+                "latency": 0,
+                "downloadThroughput": -1,
+                "uploadThroughput": -1,
+            })),
+            Some(session_id),
+        )
+        .await?;
+    Ok(())
+}
+
+pub async fn set_content(client: &CdpClient, session_id: &str, html: &str) -> Result<(), String> {
+    // Get current frame ID
+    let tree_result = client
+        .send_command_no_params("Page.getFrameTree", Some(session_id))
+        .await?;
+
+    let frame_id = tree_result
+        .get("frameTree")
+        .and_then(|t| t.get("frame"))
+        .and_then(|f| f.get("id"))
+        .and_then(|id| id.as_str())
+        .ok_or("Could not determine frame ID")?;
+
+    client
+        .send_command(
+            "Page.setDocumentContent",
+            Some(json!({
+                "frameId": frame_id,
+                "html": html,
+            })),
+            Some(session_id),
+        )
+        .await?;
+
+    Ok(())
+}
+
+// ---------------------------------------------------------------------------
+// Domain filter
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Clone)]
+pub struct DomainFilter {
+    pub allowed_domains: Vec<String>,
+}
+
+impl DomainFilter {
+    pub fn new(domains: &str) -> Self {
+        let allowed = parse_domain_list(domains);
+        Self {
+            allowed_domains: allowed,
+        }
+    }
+
+    pub fn is_allowed(&self, hostname: &str) -> bool {
+        if self.allowed_domains.is_empty() {
+            return true;
+        }
+        let hostname = hostname.to_lowercase();
+        for pattern in &self.allowed_domains {
+            if let Some(suffix) = pattern.strip_prefix("*.") {
+                if hostname == suffix || hostname.ends_with(&format!(".{}", suffix)) {
+                    return true;
+                }
+            } else if hostname == *pattern {
+                return true;
+            }
+        }
+        false
+    }
+
+    pub fn check_url(&self, url: &str) -> Result<(), String> {
+        if self.allowed_domains.is_empty() {
+            return Ok(());
+        }
+        let parsed = url::Url::parse(url).map_err(|_| format!("Invalid URL: {}", url))?;
+        let hostname = parsed
+            .host_str()
+            .ok_or_else(|| format!("No hostname in URL: {}", url))?;
+        if self.is_allowed(hostname) {
+            Ok(())
+        } else {
+            Err(format!(
+                "Domain '{}' is not in the allowed domains list",
+                hostname
+            ))
+        }
+    }
+}
+
+fn parse_domain_list(input: &str) -> Vec<String> {
+    input
+        .split(',')
+        .map(|s| s.trim().to_lowercase())
+        .filter(|s| !s.is_empty())
+        .collect()
+}
+
+pub async fn sanitize_existing_pages(
+    client: &CdpClient,
+    pages: &[super::browser::PageInfo],
+    filter: &DomainFilter,
+) {
+    for page in pages {
+        if page.url.is_empty() || page.url == "about:blank" {
+            continue;
+        }
+        if let Ok(parsed) = url::Url::parse(&page.url) {
+            if let Some(hostname) = parsed.host_str() {
+                if !filter.is_allowed(hostname) {
+                    let _ = client
+                        .send_command(
+                            "Page.navigate",
+                            Some(json!({ "url": "about:blank" })),
+                            Some(&page.session_id),
+                        )
+                        .await;
+                }
+            }
+        }
+    }
+}
+
+pub async fn install_domain_filter_script(
+    client: &CdpClient,
+    session_id: &str,
+    allowed_domains: &[String],
+) -> Result<(), String> {
+    if allowed_domains.is_empty() {
+        return Ok(());
+    }
+
+    let domains_json = serde_json::to_string(allowed_domains).unwrap_or("[]".to_string());
+    let script = format!(
+        r#"(() => {{
+            const _allowed = {};
+            function _isDomainAllowed(hostname) {{
+                hostname = hostname.toLowerCase();
+                for (const p of _allowed) {{
+                    if (p.startsWith('*.')) {{
+                        const suffix = p.slice(2);
+                        if (hostname === suffix || hostname.endsWith('.' + suffix)) return true;
+                    }} else if (hostname === p) return true;
+                }}
+                return false;
+            }}
+            const OrigWS = window.WebSocket;
+            window.WebSocket = function(url, protocols) {{
+                try {{
+                    const u = new URL(url, location.href);
+                    if (!_isDomainAllowed(u.hostname)) throw new DOMException('WebSocket blocked: ' + u.hostname, 'SecurityError');
+                }} catch(e) {{ if (e instanceof DOMException) throw e; }}
+                return new OrigWS(url, protocols);
+            }};
+            window.WebSocket.prototype = OrigWS.prototype;
+            const OrigES = window.EventSource;
+            if (OrigES) {{
+                window.EventSource = function(url, opts) {{
+                    try {{
+                        const u = new URL(url, location.href);
+                        if (!_isDomainAllowed(u.hostname)) throw new DOMException('EventSource blocked: ' + u.hostname, 'SecurityError');
+                    }} catch(e) {{ if (e instanceof DOMException) throw e; }}
+                    return new OrigES(url, opts);
+                }};
+                window.EventSource.prototype = OrigES.prototype;
+            }}
+            const origBeacon = navigator.sendBeacon;
+            if (origBeacon) {{
+                navigator.sendBeacon = function(url, data) {{
+                    try {{
+                        const u = new URL(url, location.href);
+                        if (!_isDomainAllowed(u.hostname)) return false;
+                    }} catch(e) {{ return false; }}
+                    return origBeacon.call(navigator, url, data);
+                }};
+            }}
+        }})()"#,
+        domains_json,
+    );
+
+    client
+        .send_command(
+            "Page.addScriptToEvaluateOnNewDocument",
+            Some(json!({ "source": script })),
+            Some(session_id),
+        )
+        .await?;
+
+    Ok(())
+}
+
+/// Enable Fetch-based network interception for domain filtering.
+/// This intercepts all requests and checks them against the allowed domains list.
+/// The actual handling of `Fetch.requestPaused` events happens in
+/// `resolve_fetch_paused` in the actions module.
+pub async fn install_domain_filter_fetch(
+    client: &CdpClient,
+    session_id: &str,
+    handle_auth_requests: bool,
+) -> Result<(), String> {
+    let mut params = json!({
+        "patterns": [{ "urlPattern": "*" }]
+    });
+    if handle_auth_requests {
+        params["handleAuthRequests"] = json!(true);
+    }
+    client
+        .send_command("Fetch.enable", Some(params), Some(session_id))
+        .await?;
+    Ok(())
+}
+
+/// Install both layers of domain filtering on a session:
+/// 1. JS patching (WebSocket, EventSource, sendBeacon)
+/// 2. Fetch-based network interception
+pub async fn install_domain_filter(
+    client: &CdpClient,
+    session_id: &str,
+    allowed_domains: &[String],
+    handle_auth_requests: bool,
+) -> Result<(), String> {
+    install_domain_filter_script(client, session_id, allowed_domains).await?;
+    install_domain_filter_fetch(client, session_id, handle_auth_requests).await?;
+    Ok(())
+}
+
+// ---------------------------------------------------------------------------
+// Console arg formatting (CDP RemoteObject → human-readable string)
+// ---------------------------------------------------------------------------
+
+/// Format a single CDP RemoteObject arg into a human-readable string.
+/// Priority: value → preview → description.
+pub fn format_console_arg(arg: &Value) -> Option<String> {
+    let obj_type = arg.get("type").and_then(|v| v.as_str()).unwrap_or("");
+    let subtype = arg.get("subtype").and_then(|v| v.as_str());
+
+    if obj_type == "undefined" {
+        return Some("undefined".to_string());
+    }
+
+    if subtype == Some("null") {
+        return Some("null".to_string());
+    }
+
+    // Primitive value
+    if let Some(v) = arg.get("value") {
+        return Some(match v {
+            Value::String(s) => s.clone(),
+            Value::Null => "null".to_string(),
+            other => other.to_string(),
+        });
+    }
+
+    // Skip preview for Map/Set — their description ("Map(1)", "Set(3)") is more useful
+    // than their preview properties (which only show "size")
+    if let Some(preview) = arg.get("preview") {
+        let preview_subtype = preview.get("subtype").and_then(|v| v.as_str());
+        if matches!(preview_subtype, Some("map" | "set" | "weakmap" | "weakset")) {
+            return arg
+                .get("description")
+                .and_then(|v| v.as_str())
+                .map(|s| s.to_string());
+        }
+        let is_array = subtype == Some("array") || preview_subtype == Some("array");
+        if let Some(props) = preview.get("properties").and_then(|v| v.as_array()) {
+            let overflow = preview
+                .get("overflow")
+                .and_then(|v| v.as_bool())
+                .unwrap_or(false);
+            let formatted_props: Vec<String> = props
+                .iter()
+                .filter_map(|p| {
+                    let value_str = p.get("value").and_then(|v| v.as_str())?;
+                    let prop_type = p.get("type").and_then(|v| v.as_str()).unwrap_or("");
+                    let formatted_value = if prop_type == "string" {
+                        format!("\"{}\"", value_str)
+                    } else {
+                        value_str.to_string()
+                    };
+                    if is_array {
+                        Some(formatted_value)
+                    } else {
+                        let name = p.get("name").and_then(|v| v.as_str()).unwrap_or("?");
+                        Some(format!("{}: {}", name, formatted_value))
+                    }
+                })
+                .collect();
+
+            let inner = if overflow {
+                format!("{}, ...", formatted_props.join(", "))
+            } else {
+                formatted_props.join(", ")
+            };
+
+            return if is_array {
+                Some(format!("[{}]", inner))
+            } else {
+                Some(format!("{{{}}}", inner))
+            };
+        }
+    }
+
+    // Fallback to description
+    arg.get("description")
+        .and_then(|v| v.as_str())
+        .map(|s| s.to_string())
+}
+
+/// Format an array of CDP RemoteObject args into a single space-separated string.
+pub fn format_console_args(args: &[Value]) -> String {
+    args.iter()
+        .filter_map(format_console_arg)
+        .collect::<Vec<_>>()
+        .join(" ")
+}
+
+// ---------------------------------------------------------------------------
+// Console and error tracking
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Clone)]
+pub struct ConsoleEntry {
+    pub level: String,
+    pub text: String,
+    pub args: Vec<Value>,
+}
+
+#[derive(Debug, Clone)]
+pub struct ErrorEntry {
+    pub text: String,
+    pub url: Option<String>,
+    pub line: Option<i64>,
+    pub column: Option<i64>,
+}
+
+pub struct EventTracker {
+    pub console_entries: Vec<ConsoleEntry>,
+    pub error_entries: Vec<ErrorEntry>,
+    pub max_entries: usize,
+}
+
+impl EventTracker {
+    pub fn new() -> Self {
+        Self {
+            console_entries: Vec::new(),
+            error_entries: Vec::new(),
+            max_entries: 1000,
+        }
+    }
+
+    pub fn add_console(&mut self, level: &str, text: &str, args: Vec<Value>) {
+        if self.console_entries.len() >= self.max_entries {
+            self.console_entries.remove(0);
+        }
+        self.console_entries.push(ConsoleEntry {
+            level: level.to_string(),
+            text: text.to_string(),
+            args,
+        });
+    }
+
+    pub fn add_error(
+        &mut self,
+        text: &str,
+        url: Option<&str>,
+        line: Option<i64>,
+        col: Option<i64>,
+    ) {
+        if self.error_entries.len() >= self.max_entries {
+            self.error_entries.remove(0);
+        }
+        self.error_entries.push(ErrorEntry {
+            text: text.to_string(),
+            url: url.map(String::from),
+            line,
+            column: col,
+        });
+    }
+
+    pub fn clear_console(&mut self) {
+        self.console_entries.clear();
+    }
+
+    pub fn get_console_json(&self) -> Value {
+        let messages: Vec<Value> = self
+            .console_entries
+            .iter()
+            .map(|e| {
+                let mut msg = json!({ "type": e.level, "text": e.text });
+                if !e.args.is_empty() {
+                    msg.as_object_mut()
+                        .unwrap()
+                        .insert("args".to_string(), Value::Array(e.args.clone()));
+                }
+                msg
+            })
+            .collect();
+        json!({ "messages": messages })
+    }
+
+    pub fn get_errors_json(&self) -> Value {
+        let entries: Vec<Value> = self
+            .error_entries
+            .iter()
+            .map(|e| {
+                json!({
+                    "text": e.text,
+                    "url": e.url,
+                    "line": e.line,
+                    "column": e.column,
+                })
+            })
+            .collect();
+        json!({ "errors": entries })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_domain_filter_exact() {
+        let filter = DomainFilter::new("example.com");
+        assert!(filter.is_allowed("example.com"));
+        assert!(!filter.is_allowed("other.com"));
+    }
+
+    #[test]
+    fn test_domain_filter_wildcard() {
+        let filter = DomainFilter::new("*.example.com");
+        assert!(filter.is_allowed("example.com"));
+        assert!(filter.is_allowed("api.example.com"));
+        assert!(filter.is_allowed("sub.api.example.com"));
+        assert!(!filter.is_allowed("other.com"));
+    }
+
+    #[test]
+    fn test_domain_filter_empty() {
+        let filter = DomainFilter::new("");
+        assert!(filter.is_allowed("anything.com"));
+    }
+
+    #[test]
+    fn test_domain_filter_multiple() {
+        let filter = DomainFilter::new("example.com, *.api.io");
+        assert!(filter.is_allowed("example.com"));
+        assert!(filter.is_allowed("api.io"));
+        assert!(filter.is_allowed("v1.api.io"));
+        assert!(!filter.is_allowed("other.com"));
+    }
+
+    #[test]
+    fn test_parse_domain_list() {
+        let domains = parse_domain_list("A.com, B.com , *.C.com");
+        assert_eq!(domains, vec!["a.com", "b.com", "*.c.com"]);
+    }
+
+    #[test]
+    fn test_event_tracker() {
+        let mut tracker = EventTracker::new();
+        tracker.add_console("log", "hello", vec![]);
+        tracker.add_error("oops", Some("test.js"), Some(1), Some(5));
+
+        assert_eq!(tracker.console_entries.len(), 1);
+        assert_eq!(tracker.error_entries.len(), 1);
+    }
+
+    #[test]
+    fn test_console_json_includes_args() {
+        let mut tracker = EventTracker::new();
+        let raw_args = vec![
+            json!({"type": "string", "value": "hello"}),
+            json!({"type": "number", "value": 42}),
+        ];
+        tracker.add_console("log", "hello 42", raw_args);
+
+        let result = tracker.get_console_json();
+        let messages = result.get("messages").unwrap().as_array().unwrap();
+        assert_eq!(messages.len(), 1);
+        assert_eq!(messages[0].get("text").unwrap(), "hello 42");
+        let args = messages[0].get("args").unwrap().as_array().unwrap();
+        assert_eq!(args.len(), 2);
+        assert_eq!(args[0], json!({"type": "string", "value": "hello"}));
+        assert_eq!(args[1], json!({"type": "number", "value": 42}));
+    }
+
+    #[test]
+    fn test_console_json_empty_args_omits_field() {
+        let mut tracker = EventTracker::new();
+        tracker.add_console("log", "text only", vec![]);
+
+        let result = tracker.get_console_json();
+        let messages = result.get("messages").unwrap().as_array().unwrap();
+        assert!(messages[0].get("args").is_none());
+    }
+
+    // -- format_console_arg: primitives --
+
+    #[test]
+    fn test_format_arg_string() {
+        let arg = json!({"type": "string", "value": "hello"});
+        assert_eq!(format_console_arg(&arg), Some("hello".to_string()));
+    }
+
+    #[test]
+    fn test_format_arg_number() {
+        let arg = json!({"type": "number", "value": 42});
+        assert_eq!(format_console_arg(&arg), Some("42".to_string()));
+    }
+
+    #[test]
+    fn test_format_arg_null() {
+        let arg = json!({"type": "object", "subtype": "null", "value": null});
+        assert_eq!(format_console_arg(&arg), Some("null".to_string()));
+    }
+
+    #[test]
+    fn test_format_arg_undefined() {
+        let arg = json!({"type": "undefined"});
+        assert_eq!(format_console_arg(&arg), Some("undefined".to_string()));
+    }
+
+    // -- format_console_arg: objects with preview --
+
+    #[test]
+    fn test_format_arg_object_preview() {
+        let arg = json!({
+            "type": "object",
+            "preview": {
+                "properties": [
+                    {"name": "userId", "type": "string", "value": "abc123"},
+                    {"name": "count", "type": "number", "value": "42"}
+                ],
+                "overflow": false
+            }
+        });
+        assert_eq!(
+            format_console_arg(&arg),
+            Some("{userId: \"abc123\", count: 42}".to_string())
+        );
+    }
+
+    #[test]
+    fn test_format_arg_object_preview_overflow() {
+        let arg = json!({
+            "type": "object",
+            "preview": {
+                "properties": [
+                    {"name": "a", "type": "number", "value": "1"}
+                ],
+                "overflow": true
+            }
+        });
+        assert_eq!(format_console_arg(&arg), Some("{a: 1, ...}".to_string()));
+    }
+
+    // -- format_console_arg: arrays with preview --
+
+    #[test]
+    fn test_format_arg_array_preview() {
+        let arg = json!({
+            "type": "object",
+            "subtype": "array",
+            "preview": {
+                "subtype": "array",
+                "properties": [
+                    {"name": "0", "type": "number", "value": "1"},
+                    {"name": "1", "type": "number", "value": "2"},
+                    {"name": "2", "type": "number", "value": "3"}
+                ],
+                "overflow": false
+            }
+        });
+        assert_eq!(format_console_arg(&arg), Some("[1, 2, 3]".to_string()));
+    }
+
+    // -- format_console_arg: map/set use description --
+
+    #[test]
+    fn test_format_arg_map_uses_description() {
+        let arg = json!({
+            "type": "object",
+            "subtype": "map",
+            "description": "Map(1)",
+            "preview": {
+                "subtype": "map",
+                "properties": [{"name": "size", "type": "number", "value": "1"}]
+            }
+        });
+        assert_eq!(format_console_arg(&arg), Some("Map(1)".to_string()));
+    }
+
+    // -- format_console_arg: fallback --
+
+    #[test]
+    fn test_format_arg_description_fallback() {
+        let arg = json!({"type": "object", "description": "RegExp"});
+        assert_eq!(format_console_arg(&arg), Some("RegExp".to_string()));
+    }
+
+    #[test]
+    fn test_format_arg_no_value_no_preview_no_description() {
+        let arg = json!({"type": "object"});
+        assert_eq!(format_console_arg(&arg), None);
+    }
+
+    // -- format_console_args --
+
+    #[test]
+    fn test_format_console_args_join() {
+        let args = vec![
+            json!({"type": "string", "value": "user"}),
+            json!({
+                "type": "object",
+                "preview": {
+                    "properties": [{"name": "id", "type": "number", "value": "1"}],
+                    "overflow": false
+                }
+            }),
+        ];
+        assert_eq!(format_console_args(&args), "user {id: 1}");
+    }
+
+    #[test]
+    fn test_format_console_args_filters_none() {
+        // An arg that returns None should be skipped, not produce empty string
+        let args = vec![
+            json!({"type": "string", "value": "before"}),
+            json!({"type": "object"}), // no value, preview, or description → None
+            json!({"type": "string", "value": "after"}),
+        ];
+        assert_eq!(format_console_args(&args), "before after");
+    }
+}

cli/src/native/parity_tests.rs

@@ -0,0 +1,721 @@
+//! Parity tests for the native daemon's command interface.
+//!
+//! These unit tests verify:
+//! - All documented actions are handled (not returning "Not yet implemented")
+//! - Response format consistency (success/error structure)
+//! - Credential and state actions work without a browser
+
+use serde_json::{json, Value};
+
+use super::actions::{execute_command, DaemonState};
+
+const ENCRYPTION_KEY_ENV: &str = "AGENT_BROWSER_ENCRYPTION_KEY";
+
+struct TestKeyGuard {
+    _lock: std::sync::MutexGuard<'static, ()>,
+    original: Option<String>,
+}
+
+impl TestKeyGuard {
+    fn new() -> Self {
+        let lock = super::auth::AUTH_TEST_MUTEX
+            .lock()
+            .unwrap_or_else(|e| e.into_inner());
+        let original = std::env::var(ENCRYPTION_KEY_ENV).ok();
+        // SAFETY: AUTH_TEST_MUTEX serializes all test access so no concurrent mutation.
+        unsafe { std::env::set_var(ENCRYPTION_KEY_ENV, "a".repeat(64)) };
+        Self {
+            _lock: lock,
+            original,
+        }
+    }
+}
+
+impl Drop for TestKeyGuard {
+    fn drop(&mut self) {
+        // SAFETY: AUTH_TEST_MUTEX is held via _lock.
+        match &self.original {
+            Some(val) => unsafe { std::env::set_var(ENCRYPTION_KEY_ENV, val) },
+            None => unsafe { std::env::remove_var(ENCRYPTION_KEY_ENV) },
+        }
+    }
+}
+
+/// All documented action names that should be implemented.
+const DOCUMENTED_ACTIONS: &[&str] = &[
+    "launch",
+    "navigate",
+    "read",
+    "url",
+    "title",
+    "content",
+    "evaluate",
+    "close",
+    "snapshot",
+    "screenshot",
+    "click",
+    "dblclick",
+    "fill",
+    "type",
+    "press",
+    "hover",
+    "scroll",
+    "select",
+    "check",
+    "uncheck",
+    "wait",
+    "gettext",
+    "getattribute",
+    "isvisible",
+    "isenabled",
+    "ischecked",
+    "back",
+    "forward",
+    "reload",
+    "cookies_get",
+    "cookies_set",
+    "cookies_clear",
+    "storage_get",
+    "storage_set",
+    "storage_clear",
+    "setcontent",
+    "headers",
+    "offline",
+    "console",
+    "errors",
+    "state_save",
+    "state_load",
+    "state_list",
+    "state_show",
+    "state_clear",
+    "state_clean",
+    "state_rename",
+    "trace_start",
+    "trace_stop",
+    "profiler_start",
+    "profiler_stop",
+    "recording_start",
+    "recording_stop",
+    "recording_restart",
+    "pdf",
+    "tab_list",
+    "tab_new",
+    "tab_switch",
+    "tab_close",
+    "viewport",
+    "user_agent",
+    "set_media",
+    "download",
+    "diff_snapshot",
+    "diff_url",
+    "credentials_set",
+    "credentials_get",
+    "credentials_delete",
+    "credentials_list",
+    "mouse",
+    "keyboard",
+    "focus",
+    "clear",
+    "selectall",
+    "scrollintoview",
+    "dispatch",
+    "highlight",
+    "tap",
+    "boundingbox",
+    "innertext",
+    "innerhtml",
+    "inputvalue",
+    "setvalue",
+    "count",
+    "styles",
+    "bringtofront",
+    "timezone",
+    "locale",
+    "geolocation",
+    "permissions",
+    "dialog",
+    "upload",
+    "addscript",
+    "addinitscript",
+    "addstyle",
+    "clipboard",
+    "wheel",
+    "device",
+    "screencast_start",
+    "screencast_stop",
+    "waitforurl",
+    "waitforloadstate",
+    "waitforfunction",
+    "frame",
+    "mainframe",
+    "getbyrole",
+    "getbytext",
+    "getbylabel",
+    "getbyplaceholder",
+    "getbyalttext",
+    "getbytitle",
+    "getbytestid",
+    "nth",
+    "find",
+    "evalhandle",
+    "drag",
+    "expose",
+    "pause",
+    "multiselect",
+    "responsebody",
+    "waitfordownload",
+    "window_new",
+    "diff_screenshot",
+    "video_start",
+    "video_stop",
+    "har_start",
+    "har_stop",
+    "route",
+    "unroute",
+    "requests",
+    "request_detail",
+    "credentials",
+    "auth_save",
+    "auth_login",
+    "auth_list",
+    "auth_delete",
+    "auth_show",
+    "confirm",
+    "deny",
+    "swipe",
+    "device_list",
+    "input_mouse",
+    "input_keyboard",
+    "input_touch",
+    "keydown",
+    "keyup",
+    "inserttext",
+    "mousemove",
+    "mousedown",
+    "mouseup",
+];
+
+fn minimal_command(action: &str, id: &str) -> Value {
+    let mut cmd = json!({ "action": action, "id": id });
+    let obj = cmd.as_object_mut().unwrap();
+
+    match action {
+        "navigate" | "diff_url" => {
+            obj.insert("url".to_string(), json!("https://example.com"));
+        }
+        "waitforurl" => {
+            obj.insert("url".to_string(), json!("*"));
+        }
+        "evaluate" | "expose" => {
+            obj.insert("script".to_string(), json!("1"));
+        }
+        "click" | "dblclick" | "fill" | "type" | "press" | "hover" | "scroll" | "select"
+        | "check" | "uncheck" | "gettext" | "getattribute" | "isvisible" | "isenabled"
+        | "ischecked" | "focus" | "clear" | "selectall" | "scrollintoview" | "dispatch"
+        | "highlight" | "tap" | "boundingbox" | "innertext" | "innerhtml" | "inputvalue"
+        | "setvalue" | "count" | "find" | "nth" | "getbytext" | "getbylabel"
+        | "getbyplaceholder" | "getbyalttext" | "getbytitle" | "getbytestid" => {
+            obj.insert("selector".to_string(), json!("body"));
+        }
+        "getbyrole" => {
+            obj.insert("role".to_string(), json!("button"));
+            obj.insert("selector".to_string(), json!("body"));
+        }
+        "setcontent" => {
+            obj.insert("html".to_string(), json!("<html></html>"));
+        }
+        "cookies_set" => {
+            obj.insert("name".to_string(), json!("test"));
+            obj.insert("value".to_string(), json!("val"));
+        }
+        "storage_get" | "storage_set" | "storage_clear" => {
+            obj.insert("origin".to_string(), json!("https://example.com"));
+        }
+        "state_save" | "state_load" | "state_show" | "state_clear" => {
+            obj.insert("path".to_string(), json!("test-parity-state.json"));
+        }
+        "state_rename" => {
+            obj.insert("path".to_string(), json!("test-parity-state.json"));
+            obj.insert("name".to_string(), json!("renamed"));
+        }
+        "state_clean" => {
+            obj.insert("days".to_string(), json!(7));
+        }
+        "credentials_set" => {
+            obj.insert("name".to_string(), json!("parity-test-cred"));
+            obj.insert("username".to_string(), json!("u"));
+            obj.insert("password".to_string(), json!("p"));
+        }
+        "auth_save" => {
+            obj.insert("name".to_string(), json!("parity-test-cred"));
+            obj.insert(
+                "url".to_string(),
+                json!("data:text/html,%3Cinput%20id%3Du%3E%3Cinput%20id%3Dp%20type%3Dpassword%3E%3Cbutton%20id%3Ds%20onclick%3D%22location.href%3D'data%3Atext%2Fhtml%2Cdone'%22%3Ego%3C%2Fbutton%3E"),
+            );
+            obj.insert("username".to_string(), json!("u"));
+            obj.insert("password".to_string(), json!("p"));
+            obj.insert("usernameSelector".to_string(), json!("#u"));
+            obj.insert("passwordSelector".to_string(), json!("#p"));
+            obj.insert("submitSelector".to_string(), json!("#s"));
+        }
+        "credentials_get" | "credentials_delete" | "auth_show" | "auth_delete" => {
+            obj.insert("name".to_string(), json!("parity-test-cred"));
+        }
+        "tab_switch" | "tab_close" => {
+            obj.insert("index".to_string(), json!(0));
+        }
+        "viewport" | "user_agent" | "set_media" | "timezone" | "locale" | "geolocation"
+        | "permissions" | "device" => {
+            obj.insert("value".to_string(), json!(null));
+        }
+        "headers" => {
+            obj.insert("headers".to_string(), json!({}));
+        }
+        "offline" => {
+            obj.insert("offline".to_string(), json!(false));
+        }
+        "wait" => {
+            obj.insert("timeout".to_string(), json!(100));
+        }
+        "waitforloadstate" => {
+            obj.insert("state".to_string(), json!("load"));
+            obj.insert("timeout".to_string(), json!(100));
+        }
+        "waitforfunction" => {
+            obj.insert("expression".to_string(), json!("true"));
+            obj.insert("timeout".to_string(), json!(100));
+        }
+        "frame" => {
+            obj.insert("selector".to_string(), json!("iframe"));
+        }
+        "addscript" => {
+            obj.insert("content".to_string(), json!("console.log('test')"));
+        }
+        "addinitscript" => {
+            obj.insert("script".to_string(), json!("console.log('init')"));
+        }
+        "addstyle" => {
+            obj.insert("content".to_string(), json!("body { color: red }"));
+        }
+        "wheel" => {
+            obj.insert("deltaX".to_string(), json!(0));
+            obj.insert("deltaY".to_string(), json!(0));
+        }
+        "upload" => {
+            obj.insert("selector".to_string(), json!("input[type=file]"));
+            obj.insert("files".to_string(), json!([]));
+        }
+        "dialog" => {
+            obj.insert("accept".to_string(), json!(true));
+        }
+        "credentials" => {
+            obj.insert("username".to_string(), json!("u"));
+            obj.insert("password".to_string(), json!("p"));
+        }
+        "auth_login" => {
+            obj.insert("name".to_string(), json!("parity-test-cred"));
+            obj.insert("credentialProvider".to_string(), json!("missing-provider"));
+        }
+        "route" => {
+            obj.insert("url".to_string(), json!("*"));
+            obj.insert("handler".to_string(), json!("continue"));
+        }
+        "diff_snapshot" | "diff_screenshot" => {
+            obj.insert("selector".to_string(), json!("body"));
+        }
+        "recording_start" | "recording_restart" => {
+            obj.insert("path".to_string(), json!("/tmp/parity-recording.webm"));
+        }
+        "video_start" => {
+            obj.insert("path".to_string(), json!("/tmp/parity-video.webm"));
+        }
+        "profiler_start" => {
+            obj.insert("path".to_string(), json!("/tmp/parity-profile"));
+        }
+        "trace_stop" | "har_stop" => {
+            obj.insert("path".to_string(), json!("/tmp/parity-trace"));
+        }
+        "download" => {
+            obj.insert("path".to_string(), json!("/tmp/parity-download"));
+        }
+        "multiselect" => {
+            obj.insert("selector".to_string(), json!("select"));
+            obj.insert("values".to_string(), json!([]));
+        }
+        "responsebody" => {
+            obj.insert("url".to_string(), json!("https://example.com"));
+            obj.insert("timeout".to_string(), json!(100));
+        }
+        "waitfordownload" => {
+            obj.insert("path".to_string(), json!("/tmp/parity-download"));
+            obj.insert("timeout".to_string(), json!(100));
+        }
+        "styles" => {
+            obj.insert("selector".to_string(), json!("body"));
+            obj.insert("names".to_string(), json!([]));
+        }
+        "evalhandle" => {
+            obj.insert("handle".to_string(), json!(""));
+            obj.insert("script".to_string(), json!("h => h"));
+        }
+        "drag" => {
+            obj.insert("source".to_string(), json!("body"));
+            obj.insert("target".to_string(), json!("body"));
+        }
+        "swipe" => {
+            obj.insert("selector".to_string(), json!("body"));
+            obj.insert("direction".to_string(), json!("left"));
+        }
+        "input_mouse" | "mousemove" | "mousedown" | "mouseup" => {
+            obj.insert("x".to_string(), json!(100));
+            obj.insert("y".to_string(), json!(100));
+        }
+        "input_keyboard" | "keydown" | "keyup" => {
+            obj.insert("key".to_string(), json!("a"));
+        }
+        "input_touch" => {
+            obj.insert("type".to_string(), json!("touchStart"));
+            obj.insert("touchPoints".to_string(), json!([]));
+        }
+        "inserttext" => {
+            obj.insert("text".to_string(), json!("test"));
+        }
+        _ => {}
+    }
+    cmd
+}
+
+// ---------------------------------------------------------------------------
+// 1. Action dispatch coverage
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn test_all_documented_actions_are_handled() {
+    let mut state = DaemonState::new();
+    state.default_timeout_ms = 100;
+
+    for (i, action) in DOCUMENTED_ACTIONS.iter().enumerate() {
+        let id = format!("parity-{}", i);
+        let cmd = minimal_command(action, &id);
+        let result = tokio::time::timeout(
+            std::time::Duration::from_secs(10),
+            execute_command(&cmd, &mut state),
+        )
+        .await
+        .unwrap_or_else(|_| panic!("Action '{}' timed out", action));
+
+        assert!(
+            result.get("id").is_some(),
+            "Action '{}': response missing 'id'",
+            action
+        );
+
+        let error = result.get("error").and_then(|v| v.as_str()).unwrap_or("");
+
+        assert!(
+            !error.contains("Not yet implemented"),
+            "Action '{}' returned 'Not yet implemented')",
+            action
+        );
+    }
+}
+
+// ---------------------------------------------------------------------------
+// 2. Response format consistency
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn test_success_response_format() {
+    let mut state = DaemonState::new();
+    let cmd = json!({ "action": "state_list", "id": "fmt-1" });
+    let result = execute_command(&cmd, &mut state).await;
+
+    assert_eq!(result["success"], true);
+    assert!(result.get("id").is_some());
+    assert!(result.get("data").is_some());
+    assert!(result.get("error").is_none());
+}
+
+#[tokio::test]
+async fn test_error_response_format() {
+    let mut state = DaemonState::new();
+    let cmd = json!({ "action": "nonexistent_action_xyz", "id": "fmt-2" });
+    let result = execute_command(&cmd, &mut state).await;
+
+    assert_eq!(result["success"], false);
+    assert!(result.get("id").is_some());
+    assert!(result.get("error").is_some());
+}
+
+// ---------------------------------------------------------------------------
+// 3. Credential/state actions work without a browser
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn test_state_list_without_browser() {
+    let mut state = DaemonState::new();
+    let cmd = json!({ "action": "state_list", "id": "nb-1" });
+    let result = execute_command(&cmd, &mut state).await;
+
+    assert_eq!(result["success"], true);
+    assert!(result["data"]["files"].is_array());
+}
+
+#[tokio::test]
+async fn test_credentials_list_without_browser() {
+    let mut state = DaemonState::new();
+    let cmd = json!({ "action": "credentials_list", "id": "nb-2" });
+    let result = execute_command(&cmd, &mut state).await;
+
+    assert_eq!(result["success"], true);
+    assert!(result["data"]["credentials"].is_array() || result["data"]["profiles"].is_array());
+}
+
+// ---------------------------------------------------------------------------
+// 4. New feature parity tests
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn test_auth_profile_name_validation() {
+    use super::auth;
+    let _key_guard = TestKeyGuard::new();
+    let valid = auth::credentials_set("valid-name_123", "u", "p", None);
+    assert!(valid.is_ok());
+    let invalid = auth::credentials_set("invalid/name", "u", "p", None);
+    assert!(invalid.is_err());
+    let invalid2 = auth::credentials_set("", "u", "p", None);
+    assert!(invalid2.is_err());
+    let invalid3 = auth::credentials_set("has space", "u", "p", None);
+    assert!(invalid3.is_err());
+    // Cleanup
+    let _ = auth::credentials_delete("valid-name_123");
+}
+
+#[tokio::test]
+async fn test_auth_save_and_show() {
+    use super::auth;
+    let _key_guard = TestKeyGuard::new();
+    let result = auth::auth_save(
+        "parity-roundtrip",
+        "https://example.com",
+        "user",
+        "pass",
+        Some("input#user"),
+        None,
+        None,
+    );
+    assert!(result.is_ok());
+
+    let show = auth::auth_show("parity-roundtrip");
+    assert!(show.is_ok());
+    let data = show.unwrap();
+    assert_eq!(data["profile"]["username"], "user");
+    assert_eq!(data["profile"]["usernameSelector"], "input#user");
+
+    let full = auth::credentials_get_full("parity-roundtrip");
+    assert!(full.is_ok());
+    assert_eq!(full.unwrap().password, "pass");
+
+    // Cleanup
+    let _ = auth::credentials_delete("parity-roundtrip");
+}
+
+#[tokio::test]
+async fn test_har_start_stop_without_browser() {
+    let mut state = DaemonState::new();
+    // har_start requires a browser. Because execute_command auto-launches when
+    // no browser is present, the result depends on Chrome availability: success
+    // if Chrome is found (CI), failure if not. Both outcomes are valid.
+    let cmd = json!({ "action": "har_start", "id": "har-1" });
+    let result = execute_command(&cmd, &mut state).await;
+    let success = result["success"].as_bool().unwrap_or(false);
+    if success {
+        assert!(state.har_recording);
+    } else {
+        assert!(result["error"].as_str().is_some());
+    }
+}
+
+#[tokio::test]
+async fn test_state_clean_action() {
+    let mut state = DaemonState::new();
+    let cmd = json!({ "action": "state_clean", "id": "clean-1", "days": 30 });
+    let result = execute_command(&cmd, &mut state).await;
+    assert_eq!(result["success"], true);
+}
+
+#[tokio::test]
+async fn test_daemon_state_new_defaults() {
+    let state = DaemonState::new();
+    assert!(state.browser.is_none());
+    assert!(!state.har_recording);
+    assert!(state.har_entries.is_empty());
+    assert!(state.pending_confirmation.is_none());
+    assert!(!state.request_tracking);
+    assert!(state.tracked_requests.is_empty());
+    assert!(state.active_frame_id.is_none());
+    assert!(state.webdriver_backend.is_none());
+    assert!(state.stream_client.is_none());
+}
+
+#[tokio::test]
+async fn test_tracked_request_struct() {
+    use super::actions::TrackedRequest;
+    let tr = TrackedRequest {
+        url: "https://example.com/api".to_string(),
+        method: "GET".to_string(),
+        headers: json!({"Accept": "text/html"}),
+        timestamp: 12345,
+        resource_type: "Document".to_string(),
+        request_id: "1.1".to_string(),
+        post_data: None,
+        status: Some(200),
+        response_headers: None,
+        mime_type: Some("text/html".to_string()),
+    };
+    let serialized = serde_json::to_value(&tr).unwrap();
+    assert_eq!(serialized["url"], "https://example.com/api");
+    assert_eq!(serialized["method"], "GET");
+    assert_eq!(serialized["resourceType"], "Document");
+    assert_eq!(serialized["timestamp"], 12345);
+}
+
+#[tokio::test]
+async fn test_request_tracking_state() {
+    let mut state = DaemonState::new();
+    assert!(!state.request_tracking);
+    assert!(state.tracked_requests.is_empty());
+
+    state.tracked_requests.push(super::actions::TrackedRequest {
+        url: "https://example.com".to_string(),
+        method: "GET".to_string(),
+        headers: json!({}),
+        timestamp: 1,
+        resource_type: "Document".to_string(),
+        request_id: "1.1".to_string(),
+        post_data: None,
+        status: None,
+        response_headers: None,
+        mime_type: None,
+    });
+    state.tracked_requests.push(super::actions::TrackedRequest {
+        url: "https://other.com".to_string(),
+        method: "POST".to_string(),
+        headers: json!({}),
+        timestamp: 2,
+        resource_type: "XHR".to_string(),
+        request_id: "1.2".to_string(),
+        post_data: None,
+        status: None,
+        response_headers: None,
+        mime_type: None,
+    });
+    assert_eq!(state.tracked_requests.len(), 2);
+
+    // Filter
+    let filtered: Vec<_> = state
+        .tracked_requests
+        .iter()
+        .filter(|r| r.url.contains("example"))
+        .collect();
+    assert_eq!(filtered.len(), 1);
+    assert_eq!(filtered[0].url, "https://example.com");
+
+    // Clear
+    state.tracked_requests.clear();
+    assert!(state.tracked_requests.is_empty());
+}
+
+#[test]
+fn test_matches_status_filter() {
+    use super::actions::matches_status_filter;
+
+    // Exact match
+    assert!(matches_status_filter(Some(200), "200"));
+    assert!(!matches_status_filter(Some(201), "200"));
+
+    // Class match (Nxx)
+    assert!(matches_status_filter(Some(200), "2xx"));
+    assert!(matches_status_filter(Some(299), "2xx"));
+    assert!(!matches_status_filter(Some(301), "2xx"));
+    assert!(matches_status_filter(Some(404), "4xx"));
+
+    // Range match
+    assert!(matches_status_filter(Some(400), "400-499"));
+    assert!(matches_status_filter(Some(499), "400-499"));
+    assert!(!matches_status_filter(Some(500), "400-499"));
+
+    // None status
+    assert!(!matches_status_filter(None, "200"));
+    assert!(!matches_status_filter(None, "2xx"));
+}
+
+#[tokio::test]
+async fn test_addscript_and_addinitscript_separate_dispatch() {
+    let mut state = DaemonState::new();
+
+    // Both should be handled (not "Not yet implemented") even without a browser
+    let cmd1 = json!({ "action": "addscript", "id": "as-1", "content": "console.log(1)" });
+    let result1 = execute_command(&cmd1, &mut state).await;
+    let err1 = result1["error"].as_str().unwrap_or("");
+    assert!(
+        !err1.contains("Not yet implemented"),
+        "addscript should be handled"
+    );
+
+    let cmd2 = json!({ "action": "addinitscript", "id": "ais-1", "script": "console.log(2)" });
+    let result2 = execute_command(&cmd2, &mut state).await;
+    let err2 = result2["error"].as_str().unwrap_or("");
+    assert!(
+        !err2.contains("Not yet implemented"),
+        "addinitscript should be handled"
+    );
+}
+
+#[tokio::test]
+async fn test_frame_context_management() {
+    let mut state = DaemonState::new();
+    assert!(state.active_frame_id.is_none());
+
+    // Set a frame ID and verify it persists
+    state.active_frame_id = Some("child-frame-123".to_string());
+    assert_eq!(state.active_frame_id.as_deref(), Some("child-frame-123"));
+
+    // Clearing the frame ID (what mainframe does)
+    state.active_frame_id = None;
+    assert!(state.active_frame_id.is_none());
+}
+
+#[tokio::test]
+async fn test_addstyle_supports_content_and_url() {
+    let mut state = DaemonState::new();
+
+    // Both content-based and url-based addstyle should be recognized
+    let cmd1 = json!({ "action": "addstyle", "id": "style-1", "content": "body { color: red }" });
+    let result1 = execute_command(&cmd1, &mut state).await;
+    let err1 = result1["error"].as_str().unwrap_or("");
+    assert!(!err1.contains("Not yet implemented"));
+
+    let cmd2 =
+        json!({ "action": "addstyle", "id": "style-2", "url": "https://example.com/style.css" });
+    let result2 = execute_command(&cmd2, &mut state).await;
+    let err2 = result2["error"].as_str().unwrap_or("");
+    assert!(!err2.contains("Not yet implemented"));
+}
+
+#[tokio::test]
+async fn test_domain_filter_sanitize() {
+    use super::network::DomainFilter;
+    let filter = DomainFilter::new("example.com");
+    assert!(filter.is_allowed("example.com"));
+    assert!(!filter.is_allowed("evil.com"));
+    filter.check_url("https://example.com/path").unwrap();
+    assert!(filter.check_url("https://evil.com").is_err());
+}
+
+#[tokio::test]
+async fn test_state_find_auto_returns_none_for_nonexistent() {
+    use super::state;
+    let result = state::find_auto_state_file("nonexistent-session-xyz");
+    assert!(result.is_none());
+}

cli/src/native/policy.rs

@@ -0,0 +1,217 @@
+use serde::{Deserialize, Serialize};
+use std::collections::HashSet;
+use std::env;
+use std::fs;
+use std::path::PathBuf;
+
+/// Result of a policy check for an action.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum PolicyResult {
+    /// Action is allowed.
+    Allow,
+    /// Action is blocked with the given reason.
+    Deny(String),
+    /// Action requires confirmation before proceeding.
+    RequiresConfirmation,
+}
+
+/// Policy configuration loaded from a JSON file.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ActionPolicy {
+    #[serde(skip)]
+    path: PathBuf,
+    #[serde(default)]
+    default: Option<String>,
+    #[serde(default)]
+    allow: Option<Vec<String>>,
+    #[serde(default)]
+    deny: Option<Vec<String>>,
+    #[serde(default)]
+    confirm: Option<Vec<String>>,
+}
+
+/// Confirmation categories parsed from AGENT_BROWSER_CONFIRM_ACTIONS.
+#[derive(Debug, Clone)]
+pub struct ConfirmActions {
+    pub categories: HashSet<String>,
+}
+
+impl ConfirmActions {
+    pub fn from_env() -> Option<Self> {
+        let val = env::var("AGENT_BROWSER_CONFIRM_ACTIONS").ok()?;
+        if val.is_empty() {
+            return None;
+        }
+        let categories: HashSet<String> = val
+            .split(',')
+            .map(|s| s.trim().to_lowercase())
+            .filter(|s| !s.is_empty())
+            .collect();
+        if categories.is_empty() {
+            None
+        } else {
+            Some(Self { categories })
+        }
+    }
+
+    pub fn requires_confirmation(&self, action: &str) -> bool {
+        self.categories.contains(action)
+    }
+}
+
+impl ActionPolicy {
+    /// Load policy from a JSON file at the given path.
+    pub fn load(path: &str) -> Result<Self, String> {
+        let path_buf = PathBuf::from(path);
+        let contents = fs::read_to_string(&path_buf)
+            .map_err(|e| format!("Failed to read policy file: {}", e))?;
+        let mut policy: ActionPolicy =
+            serde_json::from_str(&contents).map_err(|e| format!("Invalid policy JSON: {}", e))?;
+        policy.path = path_buf;
+        Ok(policy)
+    }
+
+    /// Load policy if AGENT_BROWSER_ACTION_POLICY env var is set.
+    /// Falls back to AGENT_BROWSER_POLICY for backwards compatibility.
+    pub fn load_if_exists() -> Option<Self> {
+        let path = env::var("AGENT_BROWSER_ACTION_POLICY")
+            .or_else(|_| env::var("AGENT_BROWSER_POLICY"))
+            .ok()?;
+        Self::load(&path).ok()
+    }
+
+    /// Check whether an action is allowed, denied, or requires confirmation.
+    pub fn check(&self, action: &str) -> PolicyResult {
+        if let Some(deny) = &self.deny {
+            if deny.iter().any(|a| a == action) {
+                return PolicyResult::Deny(format!("Action '{}' is denied by policy", action));
+            }
+        }
+
+        if let Some(confirm) = &self.confirm {
+            if confirm.iter().any(|a| a == action) {
+                return PolicyResult::RequiresConfirmation;
+            }
+        }
+
+        if let Some(allow) = &self.allow {
+            if !allow.is_empty() && !allow.iter().any(|a| a == action) {
+                let is_default_deny = self
+                    .default
+                    .as_deref()
+                    .map(|d| d.eq_ignore_ascii_case("deny"))
+                    .unwrap_or(true);
+                if is_default_deny {
+                    return PolicyResult::Deny(format!(
+                        "Action '{}' is not in the allow list",
+                        action
+                    ));
+                }
+            }
+        } else if let Some(ref default) = self.default {
+            if default.eq_ignore_ascii_case("deny") {
+                return PolicyResult::Deny(format!(
+                    "Action '{}' denied: default policy is deny",
+                    action
+                ));
+            }
+        }
+
+        PolicyResult::Allow
+    }
+
+    /// Reload policy from the file. Re-reads the JSON and updates the policy.
+    pub fn reload(&mut self) -> Result<(), String> {
+        let contents = fs::read_to_string(&self.path)
+            .map_err(|e| format!("Failed to read policy file: {}", e))?;
+        let mut policy: ActionPolicy =
+            serde_json::from_str(&contents).map_err(|e| format!("Invalid policy JSON: {}", e))?;
+        policy.path = self.path.clone();
+        *self = policy;
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::test_utils::EnvGuard;
+
+    #[test]
+    fn test_policy_allow_whitelist() {
+        let json = r#"{"allow": ["click", "type"], "deny": [], "confirm": []}"#;
+        let policy: ActionPolicy = serde_json::from_str(json).unwrap();
+        assert_eq!(policy.check("click"), PolicyResult::Allow);
+        assert_eq!(policy.check("type"), PolicyResult::Allow);
+        assert!(matches!(policy.check("navigate"), PolicyResult::Deny(_)));
+    }
+
+    #[test]
+    fn test_policy_deny() {
+        let json = r#"{"allow": [], "deny": ["delete"], "confirm": []}"#;
+        let policy: ActionPolicy = serde_json::from_str(json).unwrap();
+        assert!(matches!(policy.check("delete"), PolicyResult::Deny(_)));
+    }
+
+    #[test]
+    fn test_policy_confirm() {
+        let json = r#"{"allow": [], "deny": [], "confirm": ["submit"]}"#;
+        let policy: ActionPolicy = serde_json::from_str(json).unwrap();
+        assert_eq!(policy.check("submit"), PolicyResult::RequiresConfirmation);
+    }
+
+    #[test]
+    fn test_policy_deny_takes_precedence() {
+        let json = r#"{"allow": ["danger"], "deny": ["danger"], "confirm": []}"#;
+        let policy: ActionPolicy = serde_json::from_str(json).unwrap();
+        assert!(matches!(policy.check("danger"), PolicyResult::Deny(_)));
+    }
+
+    #[test]
+    fn test_policy_confirm_takes_precedence_over_allow() {
+        let json = r#"{"allow": ["submit"], "deny": [], "confirm": ["submit"]}"#;
+        let policy: ActionPolicy = serde_json::from_str(json).unwrap();
+        assert_eq!(policy.check("submit"), PolicyResult::RequiresConfirmation);
+    }
+
+    #[test]
+    fn test_policy_empty_allow_allows_all() {
+        let json = r#"{"allow": [], "deny": [], "confirm": []}"#;
+        let policy: ActionPolicy = serde_json::from_str(json).unwrap();
+        assert_eq!(policy.check("anything"), PolicyResult::Allow);
+    }
+
+    #[test]
+    fn test_policy_missing_allow_allows_all() {
+        let json = r#"{"deny": []}"#;
+        let policy: ActionPolicy = serde_json::from_str(json).unwrap();
+        assert_eq!(policy.check("anything"), PolicyResult::Allow);
+    }
+
+    #[test]
+    fn test_policy_default_allow() {
+        let json = r#"{"default": "allow", "deny": ["navigate"]}"#;
+        let policy: ActionPolicy = serde_json::from_str(json).unwrap();
+        assert_eq!(policy.check("click"), PolicyResult::Allow);
+        assert!(matches!(policy.check("navigate"), PolicyResult::Deny(_)));
+    }
+
+    #[test]
+    fn test_policy_default_deny() {
+        let json = r#"{"default": "deny", "allow": ["click"]}"#;
+        let policy: ActionPolicy = serde_json::from_str(json).unwrap();
+        assert_eq!(policy.check("click"), PolicyResult::Allow);
+        assert!(matches!(policy.check("navigate"), PolicyResult::Deny(_)));
+    }
+
+    #[test]
+    fn test_confirm_actions_from_env() {
+        let _guard = EnvGuard::new(&["AGENT_BROWSER_CONFIRM_ACTIONS"]);
+        _guard.set("AGENT_BROWSER_CONFIRM_ACTIONS", "navigate,click,fill");
+        let ca = ConfirmActions::from_env().unwrap();
+        assert!(ca.requires_confirmation("navigate"));
+        assert!(ca.requires_confirmation("click"));
+        assert!(ca.requires_confirmation("fill"));
+        assert!(!ca.requires_confirmation("screenshot"));
+    }
+}

cli/src/native/react/mod.rs

@@ -0,0 +1,29 @@
+//! React/web introspection primitives.
+//!
+//! Scripts and handlers for the `react` subcommands (tree, inspect, renders,
+//! suspense) plus the universal `vitals` verb and the generic `pushstate`
+//! SPA-navigation action. These primitives are framework-agnostic: React-side
+//! commands only require the `__REACT_DEVTOOLS_GLOBAL_HOOK__` to be installed,
+//! and `vitals` / `pushstate` are pure web-standard APIs.
+//!
+//! The React DevTools `installHook.js` is vendored from the React DevTools
+//! Chrome extension (MIT, facebook/react). It's registered via
+//! `addScriptToEvaluateOnNewDocument` before any page JS runs when the user
+//! passes `--enable react-devtools` at launch.
+
+pub mod scripts;
+
+mod renders;
+mod suspense;
+mod tree;
+
+pub use renders::{format_renders_report, RendersData};
+pub use suspense::{format_suspense_report, Boundary};
+pub use tree::{format_tree, TreeNode};
+
+/// React DevTools hook script (MIT, from facebook/react).
+/// Registered via `addScriptToEvaluateOnNewDocument` to install
+/// `window.__REACT_DEVTOOLS_GLOBAL_HOOK__` before any page JS runs. React
+/// detects the hook on boot and registers its renderers against it, which
+/// enables every `react …` command.
+pub const INSTALL_HOOK_JS: &str = include_str!("installHook.js");

cli/src/native/react/renders.rs

@@ -0,0 +1,169 @@
+//! React fiber render profiler report formatter.
+//!
+//! Default output is the
+//! full agent-readable report (summary, FPS, component table, per-component
+//! "change details (prev -> next)"). `--json` emits the raw structured data
+//! instead.
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Deserialize, Serialize)]
+pub struct RendersData {
+    pub elapsed: f64,
+    pub fps: FpsStats,
+    #[serde(rename = "totalRenders")]
+    pub total_renders: i64,
+    #[serde(rename = "totalMounts")]
+    pub total_mounts: i64,
+    #[serde(rename = "totalReRenders")]
+    pub total_re_renders: i64,
+    #[serde(rename = "totalComponents")]
+    pub total_components: i64,
+    pub components: Vec<Component>,
+}
+
+#[derive(Debug, Deserialize, Serialize)]
+pub struct FpsStats {
+    pub avg: i64,
+    pub min: i64,
+    pub max: i64,
+    pub drops: i64,
+}
+
+#[derive(Debug, Deserialize, Serialize)]
+pub struct Component {
+    pub name: String,
+    pub count: i64,
+    pub mounts: i64,
+    #[serde(rename = "reRenders")]
+    pub re_renders: i64,
+    #[serde(rename = "instanceCount")]
+    pub instance_count: i64,
+    #[serde(rename = "totalTime")]
+    pub total_time: f64,
+    #[serde(rename = "selfTime")]
+    pub self_time: f64,
+    #[serde(rename = "domMutations")]
+    pub dom_mutations: i64,
+    pub changes: Vec<Change>,
+    #[serde(rename = "changeSummary")]
+    pub change_summary: std::collections::HashMap<String, i64>,
+}
+
+#[derive(Debug, Deserialize, Serialize)]
+pub struct Change {
+    #[serde(rename = "type")]
+    pub change_type: String,
+    pub name: Option<String>,
+    pub prev: Option<String>,
+    pub next: Option<String>,
+}
+
+pub fn format_renders_report(d: &RendersData) -> String {
+    if d.components.is_empty() {
+        return "(no renders captured)".to_string();
+    }
+
+    let mut lines: Vec<String> = Vec::new();
+    lines.push(format!("# Render Profile - {}s recording", d.elapsed));
+    lines.push(format!(
+        "# {} renders ({} mounts + {} re-renders) across {} components",
+        d.total_renders, d.total_mounts, d.total_re_renders, d.total_components
+    ));
+    lines.push(format!(
+        "# FPS: avg {}, min {}, max {}, drops (<30fps): {}",
+        d.fps.avg, d.fps.min, d.fps.max, d.fps.drops
+    ));
+    lines.push(String::new());
+    lines.push("## Components by total render time".to_string());
+
+    let top: Vec<&Component> = d.components.iter().take(50).collect();
+    let name_w = top.iter().map(|c| c.name.len()).max().unwrap_or(9).max(9);
+
+    lines.push(format!(
+        "| {:<name_w$} | Insts | Mounts | Re-renders | Total    | Self     | DOM   | Top change reason          |",
+        "Component",
+        name_w = name_w
+    ));
+    lines.push(format!(
+        "| {:-<name_w$} | ----- | ------ | ---------- | -------- | -------- | ----- | -------------------------- |",
+        "",
+        name_w = name_w
+    ));
+    for c in &top {
+        let total = if c.total_time > 0.0 {
+            format!("{}ms", c.total_time)
+        } else {
+            "-".to_string()
+        };
+        let self_time = if c.self_time > 0.0 {
+            format!("{}ms", c.self_time)
+        } else {
+            "-".to_string()
+        };
+        let dom = format!("{}/{}", c.dom_mutations, c.count);
+        let top_change = c
+            .change_summary
+            .iter()
+            .max_by_key(|(_, v)| *v)
+            .map(|(k, _)| k.as_str())
+            .unwrap_or("-");
+        lines.push(format!(
+            "| {:<name_w$} | {:>5} | {:>6} | {:>10} | {:>8} | {:>8} | {:>5} | {:<26} |",
+            c.name,
+            c.instance_count,
+            c.mounts,
+            c.re_renders,
+            total,
+            self_time,
+            dom,
+            top_change,
+            name_w = name_w
+        ));
+    }
+    if d.components.len() > 50 {
+        lines.push(format!("... and {} more", d.components.len() - 50));
+    }
+
+    let detailed: Vec<&Component> = d
+        .components
+        .iter()
+        .filter(|c| {
+            c.changes
+                .iter()
+                .any(|ch| ch.change_type != "mount" && ch.change_type != "parent")
+        })
+        .take(15)
+        .collect();
+    if !detailed.is_empty() {
+        lines.push(String::new());
+        lines.push("## Change details (prev -> next)".to_string());
+        for c in &detailed {
+            lines.push(format!("  {}", c.name));
+            let mut seen = std::collections::HashSet::new();
+            for ch in &c.changes {
+                if ch.change_type == "mount" || ch.change_type == "parent" {
+                    continue;
+                }
+                let name = ch.name.clone().unwrap_or_default();
+                let key = format!("{}:{}", ch.change_type, name);
+                if !seen.insert(key) {
+                    continue;
+                }
+                let label = match ch.change_type.as_str() {
+                    "props" => format!("props.{}", name),
+                    "state" => format!("state ({})", name),
+                    _ => format!("context ({})", name),
+                };
+                lines.push(format!(
+                    "    {}: {} -> {}",
+                    label,
+                    ch.prev.clone().unwrap_or_else(|| "?".into()),
+                    ch.next.clone().unwrap_or_else(|| "?".into())
+                ));
+            }
+        }
+    }
+
+    lines.join("\n")
+}

cli/src/native/react/scripts.rs

@@ -0,0 +1,842 @@
+//! Browser-side evaluation scripts for React/web introspection.
+//!
+//! These are JavaScript strings evaluated in the page context via
+//! `Runtime.evaluate`. They assume the React DevTools hook is already
+//! installed (via `--enable react-devtools`) except for `VITALS_INIT` and
+//! `PUSHSTATE`, which only use standard Web APIs.
+//!
+//! Kept as raw strings rather than TS/JS files because the daemon is a single
+//! Rust binary with no filesystem vendor step at runtime.
+
+/// JS helper injected into every renderer-reading script via the `{{PICK_RI}}`
+/// placeholder. Defines `__abPickReactRendererId(hook)`, which returns the id of
+/// the renderer interface that actually holds the app's DOM tree.
+///
+/// We used to hardcode `rendererInterfaces.get(1)`, assuming the first renderer
+/// to call `hook.inject()` is react-dom. In Turbopack RSC apps (e.g. Next.js
+/// 16.3+) the `react-server-dom-*` Flight client registers first as id 1 with
+/// zero fiber roots, so `get(1)` read an empty tree and every `react` command
+/// silently reported nothing. Instead, pick the first non-Flight renderer that
+/// has mounted fiber roots, falling back to any renderer with roots, then any
+/// renderer at all.
+pub const PICK_REACT_RENDERER: &str = r#"
+  function __abPickReactRendererId(hook) {
+    const ris = hook && hook.rendererInterfaces;
+    if (!ris || !ris.get || !ris.keys) return null;
+    const rootsOf = (id) => {
+      try { return hook.getFiberRoots ? hook.getFiberRoots(id).size : 0; } catch (e) { return 0; }
+    };
+    const isFlight = (id) => {
+      const r = hook.renderers && hook.renderers.get && hook.renderers.get(id);
+      return /react-server-dom/.test((r && r.rendererPackageName) || "");
+    };
+    let firstWithRoots = null, firstAny = null;
+    for (const id of ris.keys()) {
+      if (!ris.get(id)) continue;
+      if (firstAny === null) firstAny = id;
+      if (rootsOf(id) > 0) {
+        if (firstWithRoots === null) firstWithRoots = id;
+        if (!isFlight(id)) return id;
+      }
+    }
+    return firstWithRoots !== null ? firstWithRoots : firstAny;
+  }
+"#;
+
+/// Build a no-argument async IIFE page-eval that returns the component tree as
+/// JSON.
+pub const TREE_SNAPSHOT: &str = r#"
+(async () => {
+  const hook = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+  if (!hook) throw new Error("React DevTools hook not installed - relaunch with --enable react-devtools");
+{{PICK_RI}}
+  const __abRiId = __abPickReactRendererId(hook);
+  const ri = (__abRiId != null && hook.rendererInterfaces && hook.rendererInterfaces.get) ? hook.rendererInterfaces.get(__abRiId) : null;
+  if (!ri) throw new Error("No React renderer attached - the page has not booted React yet");
+
+  const batches = await new Promise((resolve) => {
+    const out = [];
+    const origEmit = hook.emit;
+    hook.emit = function (event, payload) {
+      if (event === "operations") out.push(Array.from(payload));
+      return origEmit.apply(hook, arguments);
+    };
+    ri.flushInitialOperations();
+    setTimeout(() => {
+      hook.emit = origEmit;
+      resolve(out);
+    }, 50);
+  });
+
+  const nodes = batches.flatMap((ops) => {
+    let i = 2;
+    const strings = [null];
+    const tableEnd = ++i + ops[i - 1];
+    while (i < tableEnd) {
+      const len = ops[i++];
+      strings.push(String.fromCodePoint(...ops.slice(i, i + len)));
+      i += len;
+    }
+    const out = [];
+    while (i < ops.length) {
+      const op = ops[i];
+      if (op === 1) {
+        const id = ops[i + 1];
+        const type = ops[i + 2];
+        i += 3;
+        if (type === 11) {
+          out.push({ id, type, name: null, key: null, parent: 0 });
+          i += 4;
+        } else {
+          out.push({
+            id,
+            type,
+            name: strings[ops[i + 2]] || null,
+            key: strings[ops[i + 3]] || null,
+            parent: ops[i],
+          });
+          i += 5;
+        }
+      } else {
+        i += skip(op, ops, i);
+      }
+    }
+    return out;
+
+    function skip(op, ops, i) {
+      if (op === 2) return 2 + ops[i + 1];
+      if (op === 3) return 3 + ops[i + 2];
+      if (op === 4) return 3;
+      if (op === 5) return 4;
+      if (op === 6) return 1;
+      if (op === 7) return 3;
+      if (op === 8) return 6 + rects(ops[i + 5]);
+      if (op === 9) return 2 + ops[i + 1];
+      if (op === 10) return 3 + ops[i + 2];
+      if (op === 11) return 3 + rects(ops[i + 2]);
+      if (op === 12) return suspenders(ops, i);
+      if (op === 13) return 2;
+      return 1;
+    }
+    function rects(n) {
+      return n === -1 ? 0 : n * 4;
+    }
+    function suspenders(ops, i) {
+      let j = i + 2;
+      for (let c = 0; c < ops[i + 1]; c++) j += 5 + ops[j + 4];
+      return j - i;
+    }
+  });
+
+  return JSON.stringify(nodes);
+})()
+"#;
+
+/// Template for `inspect` — replace {{ID}} with the numeric fiber id.
+pub const TREE_INSPECT: &str = r#"
+(() => {
+  const id = {{ID}};
+  const hook = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+{{PICK_RI}}
+  const __abRiId = __abPickReactRendererId(hook);
+  const ri = (__abRiId != null && hook.rendererInterfaces && hook.rendererInterfaces.get) ? hook.rendererInterfaces.get(__abRiId) : null;
+  if (!ri) throw new Error("No React renderer attached");
+  if (!ri.hasElementWithId(id)) throw new Error("element " + id + " not found (page reloaded?)");
+  const result = ri.inspectElement(__abRiId, id, null, true);
+  if (!result || result.type !== "full-data") {
+    throw new Error("inspect failed: " + (result && result.type));
+  }
+  const v = result.value;
+  const name = ri.getDisplayNameForElementID(id);
+  const lines = [name + " #" + id];
+  if (v.key != null) lines.push("key: " + JSON.stringify(v.key));
+  section("props", v.props);
+  section("hooks", v.hooks);
+  section("state", v.state);
+  section("context", v.context);
+  if (v.owners && v.owners.length) {
+    lines.push("rendered by: " + v.owners.map((o) => o.displayName).join(" > "));
+  }
+  const source = Array.isArray(v.source)
+    ? [v.source[1], v.source[2], v.source[3]]
+    : null;
+  return JSON.stringify({ text: lines.join("\n"), source });
+
+  function section(label, payload) {
+    const data = (payload && payload.data) || payload;
+    if (data == null) return;
+    if (Array.isArray(data)) {
+      if (data.length === 0) return;
+      lines.push(label + ":");
+      for (const h of data) lines.push("  " + hookLine(h));
+    } else if (typeof data === "object") {
+      const entries = Object.entries(data);
+      if (entries.length === 0) return;
+      lines.push(label + ":");
+      for (const [k, val] of entries) lines.push("  " + k + ": " + preview(val));
+    }
+  }
+  function hookLine(h) {
+    const idx = h.id != null ? "[" + h.id + "] " : "";
+    const sub = h.subHooks && h.subHooks.length ? " (" + h.subHooks.length + " sub)" : "";
+    return idx + h.name + ": " + preview(h.value) + sub;
+  }
+  function preview(v) {
+    if (v == null) return String(v);
+    if (typeof v !== "object") return JSON.stringify(v);
+    if (v.type === "undefined") return "undefined";
+    if (v.preview_long) return v.preview_long;
+    if (v.preview_short) return v.preview_short;
+    if (Array.isArray(v)) return "[" + v.map(preview).join(", ") + "]";
+    const entries = Object.entries(v).map((e) => e[0] + ": " + preview(e[1]));
+    return "{" + entries.join(", ") + "}";
+  }
+})()
+"#;
+
+/// Fiber profiler init script. Registered via `addScriptToEvaluateOnNewDocument`
+/// so it survives navigations; also evaluated immediately on the current page
+/// by `react renders start`.
+pub const RENDERS_INIT: &str = r#"
+(() => {
+  const hook = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+  if (!hook || window.__AB_RENDERS_ACTIVE__) return;
+
+  const MAX_COMPONENTS = 200;
+  const data = {};
+  const fps = { frames: [], last: 0, rafId: 0 };
+
+  window.__AB_RENDERS__ = data;
+  window.__AB_RENDERS_FPS__ = fps;
+  window.__AB_RENDERS_START__ = performance.now();
+  window.__AB_RENDERS_ACTIVE__ = true;
+
+  function fpsLoop(now) {
+    if (fps.last > 0) fps.frames.push(now - fps.last);
+    fps.last = now;
+    fps.rafId = requestAnimationFrame(fpsLoop);
+  }
+  fps.rafId = requestAnimationFrame(fpsLoop);
+
+  const origOnCommit = hook.onCommitFiberRoot;
+  window.__AB_RENDERS_ORIG_COMMIT__ = origOnCommit;
+
+  hook.onCommitFiberRoot = function (rendererID, root) {
+    try { walkFiber(root.current); } catch {}
+    if (typeof origOnCommit === "function") {
+      return origOnCommit.apply(hook, arguments);
+    }
+  };
+
+  function getName(fiber) {
+    if (!fiber.type || typeof fiber.type === "string") return null;
+    return fiber.type.displayName || fiber.type.name || null;
+  }
+
+  function brief(val) {
+    if (val === undefined) return "undefined";
+    if (val === null) return "null";
+    if (typeof val === "function") return "fn()";
+    if (typeof val === "string") return val.length > 60 ? '"' + val.slice(0, 57) + '..."' : '"' + val + '"';
+    if (typeof val === "number" || typeof val === "boolean") return String(val);
+    if (Array.isArray(val)) return "Array(" + val.length + ")";
+    if (typeof val === "object") {
+      try {
+        const keys = Object.keys(val);
+        return keys.length <= 3 ? "{" + keys.join(", ") + "}" : "{" + keys.slice(0, 3).join(", ") + ", ...}";
+      } catch { return "{...}"; }
+    }
+    return String(val).slice(0, 40);
+  }
+
+  function getChanges(fiber) {
+    const changes = [];
+    const alt = fiber.alternate;
+    if (!alt) { changes.push({ type: "mount" }); return changes; }
+    if (fiber.memoizedProps !== alt.memoizedProps) {
+      const curr = fiber.memoizedProps || {};
+      const prev = alt.memoizedProps || {};
+      const allKeys = new Set([...Object.keys(curr), ...Object.keys(prev)]);
+      for (const k of allKeys) {
+        if (k !== "children" && curr[k] !== prev[k]) {
+          changes.push({ type: "props", name: k, prev: brief(prev[k]), next: brief(curr[k]) });
+        }
+      }
+    }
+    if (fiber.memoizedState !== alt.memoizedState) {
+      let curr = fiber.memoizedState;
+      let prev = alt.memoizedState;
+      let hookIdx = 0;
+      while (curr || prev) {
+        if ((curr && curr.memoizedState) !== (prev && prev.memoizedState)) {
+          changes.push({
+            type: "state",
+            name: "hook #" + hookIdx,
+            prev: brief(prev && prev.memoizedState),
+            next: brief(curr && curr.memoizedState),
+          });
+        }
+        curr = curr && curr.next;
+        prev = prev && prev.next;
+        hookIdx++;
+      }
+    }
+    if (fiber.dependencies && fiber.dependencies.firstContext) {
+      let ctx = fiber.dependencies.firstContext;
+      let altCtx = alt.dependencies && alt.dependencies.firstContext;
+      while (ctx) {
+        if (!altCtx || ctx.memoizedValue !== (altCtx && altCtx.memoizedValue)) {
+          const ctxName =
+            (ctx.context && ctx.context.displayName) ||
+            (ctx.context && ctx.context.Provider && ctx.context.Provider.displayName) ||
+            "unknown";
+          changes.push({
+            type: "context",
+            name: ctxName,
+            prev: brief(altCtx && altCtx.memoizedValue),
+            next: brief(ctx.memoizedValue),
+          });
+        }
+        ctx = ctx.next;
+        altCtx = altCtx && altCtx.next;
+      }
+    }
+    if (changes.length === 0) {
+      let parent = fiber.return;
+      while (parent) {
+        const pName = getName(parent);
+        if (pName) {
+          const suffix = !parent.alternate ? " (mount)" : "";
+          changes.push({ type: "parent", name: pName + suffix });
+          break;
+        }
+        parent = parent.return;
+      }
+      if (changes.length === 0) changes.push({ type: "parent", name: "unknown" });
+    }
+    return changes;
+  }
+
+  function childrenTime(fiber) {
+    let t = 0;
+    let child = fiber.child;
+    while (child) {
+      if (typeof child.actualDuration === "number") t += child.actualDuration;
+      child = child.sibling;
+    }
+    return t;
+  }
+
+  function hasDomMutation(fiber) {
+    if (!fiber.alternate) return true;
+    let child = fiber.child;
+    while (child) {
+      if (typeof child.type === "string" && (child.flags & 6) > 0) return true;
+      child = child.sibling;
+    }
+    return false;
+  }
+
+  function walkFiber(fiber) {
+    if (!fiber) return;
+    const tag = fiber.tag;
+    if (tag === 0 || tag === 1 || tag === 2 || tag === 11 || tag === 15) {
+      const didRender =
+        fiber.alternate === null ||
+        fiber.flags > 0 ||
+        fiber.memoizedProps !== (fiber.alternate && fiber.alternate.memoizedProps) ||
+        fiber.memoizedState !== (fiber.alternate && fiber.alternate.memoizedState);
+      if (didRender) {
+        const name = getName(fiber);
+        if (name) {
+          if (!(name in data) && Object.keys(data).length >= MAX_COMPONENTS) {
+            // at cap - skip
+          } else {
+            if (!data[name]) {
+              data[name] = {
+                count: 0, mounts: 0, totalTime: 0, selfTime: 0,
+                domMutations: 0, changes: [], _instances: new Set(),
+              };
+            }
+            data[name].count++;
+            if (!fiber.alternate) data[name].mounts++;
+            if (!data[name]._instances.has(fiber)) {
+              data[name]._instances.add(fiber);
+              if (fiber.alternate) data[name]._instances.add(fiber.alternate);
+            }
+            if (typeof fiber.actualDuration === "number") {
+              data[name].totalTime += fiber.actualDuration;
+              data[name].selfTime += Math.max(0, fiber.actualDuration - childrenTime(fiber));
+            }
+            if (hasDomMutation(fiber)) data[name].domMutations++;
+            const ch = getChanges(fiber);
+            for (const c of ch) {
+              if (data[name].changes.length < 50) data[name].changes.push(c);
+            }
+          }
+        }
+      }
+    }
+    walkFiber(fiber.child);
+    walkFiber(fiber.sibling);
+  }
+})()
+"#;
+
+/// Stop script for fiber profiler. Returns the collected profile as JSON.
+pub const RENDERS_STOP: &str = r#"
+(() => {
+  const active = window.__AB_RENDERS_ACTIVE__;
+  if (!active) throw new Error("renders recording not active - run `react renders start` first");
+
+  const data = window.__AB_RENDERS__;
+  const startTime = window.__AB_RENDERS_START__;
+  const elapsed = performance.now() - startTime;
+
+  const fpsData = window.__AB_RENDERS_FPS__;
+  let fpsStats = { avg: 0, min: 0, max: 0, drops: 0 };
+  if (fpsData) {
+    cancelAnimationFrame(fpsData.rafId);
+    if (fpsData.frames.length > 0) {
+      const fpsSamples = fpsData.frames.map((dt) => (dt > 0 ? 1000 / dt : 0));
+      const sum = fpsSamples.reduce((a, b) => a + b, 0);
+      fpsStats = {
+        avg: Math.round(sum / fpsSamples.length),
+        min: Math.round(Math.min(...fpsSamples)),
+        max: Math.round(Math.max(...fpsSamples)),
+        drops: fpsSamples.filter((f) => f < 30).length,
+      };
+    }
+  }
+
+  const hook = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+  const orig = window.__AB_RENDERS_ORIG_COMMIT__;
+  if (hook) hook.onCommitFiberRoot = orig || undefined;
+
+  delete window.__AB_RENDERS__;
+  delete window.__AB_RENDERS_START__;
+  delete window.__AB_RENDERS_ACTIVE__;
+  delete window.__AB_RENDERS_ORIG_COMMIT__;
+  delete window.__AB_RENDERS_FPS__;
+
+  if (!data) {
+    return JSON.stringify({
+      elapsed: 0, fps: fpsStats, totalRenders: 0, totalMounts: 0,
+      totalReRenders: 0, totalComponents: 0, components: [],
+    });
+  }
+
+  const round = (n) => Math.round(n * 100) / 100;
+  const components = Object.entries(data)
+    .map(([name, entry]) => {
+      const summary = {};
+      for (const c of entry.changes) {
+        const key = c.type === "props" ? "props." + c.name
+          : c.type === "state" ? "state (" + c.name + ")"
+          : c.type === "context" ? "context (" + c.name + ")"
+          : c.type === "parent" ? "parent (" + c.name + ")"
+          : c.type;
+        summary[key] = (summary[key] || 0) + 1;
+      }
+      return {
+        name,
+        count: entry.count,
+        mounts: entry.mounts,
+        reRenders: entry.count - entry.mounts,
+        instanceCount: entry._instances.size,
+        totalTime: round(entry.totalTime),
+        selfTime: round(entry.selfTime),
+        domMutations: entry.domMutations,
+        changes: entry.changes,
+        changeSummary: summary,
+      };
+    })
+    .sort((a, b) => b.totalTime - a.totalTime || b.count - a.count);
+
+  return JSON.stringify({
+    elapsed: round(elapsed / 1000),
+    fps: fpsStats,
+    totalRenders: components.reduce((s, c) => s + c.count, 0),
+    totalMounts: components.reduce((s, c) => s + c.mounts, 0),
+    totalReRenders: components.reduce((s, c) => s + c.reRenders, 0),
+    totalComponents: components.length,
+    components,
+  });
+})()
+"#;
+
+/// Suspense boundary walker. Returns boundaries with suspendedBy metadata as JSON.
+pub const SUSPENSE_WALK: &str = r#"
+(async () => {
+  const hook = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+  if (!hook) throw new Error("React DevTools hook not installed - relaunch with --enable react-devtools");
+{{PICK_RI}}
+  const __abRiId = __abPickReactRendererId(hook);
+  const ri = (__abRiId != null && hook.rendererInterfaces && hook.rendererInterfaces.get) ? hook.rendererInterfaces.get(__abRiId) : null;
+  if (!ri) throw new Error("No React renderer attached");
+
+  const batches = await new Promise((resolve) => {
+    const out = [];
+    const origEmit = hook.emit;
+    hook.emit = function (event, payload) {
+      if (event === "operations") out.push(payload);
+      return origEmit.apply(this, arguments);
+    };
+    ri.flushInitialOperations();
+    setTimeout(() => {
+      hook.emit = origEmit;
+      resolve(out);
+    }, 50);
+  });
+
+  const boundaryMap = new Map();
+  for (const ops of batches) decodeSuspenseOps(ops, boundaryMap);
+
+  const results = [];
+  for (const b of boundaryMap.values()) {
+    if (b.parentID === 0) continue;
+    const boundary = {
+      id: b.id,
+      parentID: b.parentID,
+      name: b.name,
+      isSuspended: b.isSuspended,
+      environments: b.environments,
+      suspendedBy: [],
+      unknownSuspenders: null,
+      owners: [],
+      jsxSource: null,
+    };
+    if (ri.hasElementWithId(b.id)) {
+      const displayName = ri.getDisplayNameForElementID(b.id);
+      if (displayName) boundary.name = displayName;
+      const result = ri.inspectElement(__abRiId, b.id, null, true);
+      if (result && result.type === "full-data") {
+        parseInspection(boundary, result.value);
+      }
+    }
+    results.push(boundary);
+  }
+  return JSON.stringify(results);
+
+  function decodeSuspenseOps(ops, map) {
+    let i = 2;
+    const strings = [null];
+    const tableEnd = ++i + ops[i - 1];
+    while (i < tableEnd) {
+      const len = ops[i++];
+      strings.push(String.fromCodePoint(...ops.slice(i, i + len)));
+      i += len;
+    }
+    while (i < ops.length) {
+      const op = ops[i];
+      if (op === 1) {
+        const type = ops[i + 2];
+        i += 3 + (type === 11 ? 4 : 5);
+      } else if (op === 2) {
+        i += 2 + ops[i + 1];
+      } else if (op === 3) {
+        i += 3 + ops[i + 2];
+      } else if (op === 4) {
+        i += 3;
+      } else if (op === 5) {
+        i += 4;
+      } else if (op === 6) {
+        i++;
+      } else if (op === 7) {
+        i += 3;
+      } else if (op === 8) {
+        const id = ops[i + 1];
+        const parentID = ops[i + 2];
+        const nameStrID = ops[i + 3];
+        const isSuspended = ops[i + 4] === 1;
+        const numRects = ops[i + 5];
+        i += 6;
+        if (numRects !== -1) i += numRects * 4;
+        map.set(id, { id, parentID, name: strings[nameStrID] || null, isSuspended, environments: [] });
+      } else if (op === 9) {
+        i += 2 + ops[i + 1];
+      } else if (op === 10) {
+        i += 3 + ops[i + 2];
+      } else if (op === 11) {
+        const numRects = ops[i + 2];
+        i += 3;
+        if (numRects !== -1) i += numRects * 4;
+      } else if (op === 12) {
+        i++;
+        const changeLen = ops[i++];
+        for (let c = 0; c < changeLen; c++) {
+          const id = ops[i++];
+          i++;
+          i++;
+          const isSuspended = ops[i++] === 1;
+          const envLen = ops[i++];
+          const envs = [];
+          for (let e = 0; e < envLen; e++) {
+            const n = strings[ops[i++]];
+            if (n != null) envs.push(n);
+          }
+          const node = map.get(id);
+          if (node) {
+            node.isSuspended = isSuspended;
+            for (const env of envs) {
+              if (!node.environments.includes(env)) node.environments.push(env);
+            }
+          }
+        }
+      } else if (op === 13) {
+        i += 2;
+      } else {
+        i++;
+      }
+    }
+  }
+
+  function parseInspection(boundary, data) {
+    const rawSuspendedBy = data.suspendedBy;
+    const rawSuspenders = Array.isArray(rawSuspendedBy)
+      ? rawSuspendedBy
+      : rawSuspendedBy && Array.isArray(rawSuspendedBy.data) ? rawSuspendedBy.data : null;
+    if (rawSuspenders) {
+      for (const entry of rawSuspenders) {
+        const awaited = entry && entry.awaited;
+        if (!awaited) continue;
+        const desc = preview(awaited.description) || preview(awaited.value);
+        boundary.suspendedBy.push({
+          name: awaited.name || "unknown",
+          description: desc,
+          duration: awaited.end && awaited.start ? Math.round(awaited.end - awaited.start) : 0,
+          env: awaited.env || (entry && entry.env) || null,
+          ownerName: (awaited.owner && awaited.owner.displayName) || null,
+          ownerStack: parseStack((awaited.owner && awaited.owner.stack) || awaited.stack),
+          awaiterName: (entry && entry.owner && entry.owner.displayName) || null,
+          awaiterStack: parseStack((entry && entry.owner && entry.owner.stack) || (entry && entry.stack)),
+        });
+      }
+    }
+    if (data.unknownSuspenders && data.unknownSuspenders !== 0) {
+      const reasons = {
+        1: "production build (no debug info)",
+        2: "old React version (missing tracking)",
+        3: "thrown Promise (library using throw instead of use())",
+      };
+      boundary.unknownSuspenders = reasons[data.unknownSuspenders] || "unknown reason";
+    }
+    if (Array.isArray(data.owners)) {
+      for (const o of data.owners) {
+        if (o && o.displayName) {
+          const src = Array.isArray(o.stack) && o.stack.length > 0 && Array.isArray(o.stack[0])
+            ? [o.stack[0][1] || "(unknown)", o.stack[0][2], o.stack[0][3]]
+            : null;
+          boundary.owners.push({ name: o.displayName, env: o.env || null, source: src });
+        }
+      }
+    }
+    if (Array.isArray(data.stack) && data.stack.length > 0) {
+      const frame = data.stack[0];
+      if (Array.isArray(frame) && frame.length >= 4) {
+        boundary.jsxSource = [frame[1] || "(unknown)", frame[2], frame[3]];
+      }
+    }
+  }
+
+  function parseStack(raw) {
+    if (!Array.isArray(raw) || raw.length === 0) return null;
+    return raw
+      .filter((f) => Array.isArray(f) && f.length >= 4)
+      .map((f) => [f[0] || "", f[1] || "", f[2] || 0, f[3] || 0]);
+  }
+
+  function preview(v) {
+    if (v == null) return "";
+    if (typeof v === "string") return v;
+    if (typeof v !== "object") return String(v);
+    if (typeof v.preview_long === "string") return v.preview_long;
+    if (typeof v.preview_short === "string") return v.preview_short;
+    if (typeof v.value === "string") return v.value;
+    try {
+      const s = JSON.stringify(v);
+      return s.length > 80 ? s.slice(0, 77) + "..." : s;
+    } catch {
+      return "";
+    }
+  }
+})()
+"#;
+
+/// Init script for Core Web Vitals + React hydration timing capture. Installs
+/// PerformanceObservers for LCP/CLS and intercepts `console.timeStamp` to
+/// capture React's profiling reconciler timings. Idempotent.
+pub const VITALS_INIT: &str = r#"
+(() => {
+  if (window.__AB_VITALS_INSTALLED__) return;
+  window.__AB_VITALS_INSTALLED__ = true;
+
+  const cwv = { lcp: null, cls: 0, clsEntries: [], fcp: null, inp: null };
+  window.__AB_VITALS__ = cwv;
+
+  try {
+    new PerformanceObserver((list) => {
+      const entries = list.getEntries();
+      if (entries.length > 0) {
+        const last = entries[entries.length - 1];
+        cwv.lcp = {
+          startTime: Math.round(last.startTime * 100) / 100,
+          size: last.size,
+          element: last.element && last.element.tagName ? last.element.tagName.toLowerCase() : null,
+          url: last.url || null,
+        };
+      }
+    }).observe({ type: "largest-contentful-paint", buffered: true });
+  } catch {}
+
+  try {
+    new PerformanceObserver((list) => {
+      for (const entry of list.getEntries()) {
+        if (!entry.hadRecentInput) {
+          cwv.cls += entry.value;
+          cwv.clsEntries.push({
+            value: Math.round(entry.value * 10000) / 10000,
+            startTime: Math.round(entry.startTime * 100) / 100,
+          });
+        }
+      }
+    }).observe({ type: "layout-shift", buffered: true });
+  } catch {}
+
+  try {
+    new PerformanceObserver((list) => {
+      for (const entry of list.getEntries()) {
+        if (entry.name === "first-contentful-paint") {
+          cwv.fcp = Math.round(entry.startTime * 100) / 100;
+        }
+      }
+    }).observe({ type: "paint", buffered: true });
+  } catch {}
+
+  try {
+    new PerformanceObserver((list) => {
+      let worst = cwv.inp || 0;
+      for (const entry of list.getEntries()) {
+        if (entry.duration > worst) worst = entry.duration;
+      }
+      if (worst > 0) cwv.inp = Math.round(worst * 100) / 100;
+    }).observe({ type: "event", buffered: true, durationThreshold: 40 });
+  } catch {}
+
+  // React profiling build emits console.timeStamp(label, start, end, track, trackGroup, color)
+  // for reconciler phases and per-component hydration timing. Intercept and collect.
+  const timing = [];
+  window.__AB_REACT_TIMING__ = timing;
+  const orig = console.timeStamp;
+  console.timeStamp = function (label) {
+    const args = arguments;
+    if (typeof label === "string" && args.length >= 3 && typeof args[1] === "number") {
+      timing.push({
+        label,
+        startTime: args[1],
+        endTime: args[2],
+        track: args[3] || "",
+        trackGroup: args[4] || "",
+        color: args[5] || "",
+      });
+    }
+    return orig.apply(console, args);
+  };
+})()
+"#;
+
+/// Read script for vitals — collects observed metrics plus Navigation Timing
+/// TTFB and any React hydration phases. Returns JSON.
+pub const VITALS_READ: &str = r#"
+(() => {
+  const cwv = window.__AB_VITALS__ || {};
+  const timing = window.__AB_REACT_TIMING__ || [];
+  const nav = performance.getEntriesByType("navigation")[0];
+  const ttfb = nav
+    ? Math.round((nav.responseStart - nav.requestStart) * 100) / 100
+    : null;
+  return JSON.stringify({ cwv, timing, ttfb });
+})()
+"#;
+
+/// SPA client-side navigation. Tries the framework router first so Next.js
+/// app/pages router triggers an RSC fetch (pure `history.pushState` would
+/// be shallow routing and bypass data loading). Falls back to
+/// `history.pushState` + popstate/navigate events for vanilla pages and
+/// routers that listen to history events (React Router, TanStack Router,
+/// Solid Router, Vue Router).
+pub const PUSHSTATE: &str = r#"
+((url) => {
+  const before = location.href;
+  const absolute = new URL(url, before).href;
+  if (absolute === before) return before;
+
+  // Next.js pages + app router expose window.next.router with a `push`
+  // method that triggers the RSC fetch and re-render pipeline.
+  const r = typeof window.next === "object" && window.next && window.next.router;
+  if (r && typeof r.push === "function") {
+    try { r.push(url); return location.href; } catch {}
+  }
+
+  history.pushState(null, "", absolute);
+  try { dispatchEvent(new PopStateEvent("popstate", { state: null })); } catch {}
+  try { dispatchEvent(new Event("navigate")); } catch {}
+  return location.href;
+})({{URL}})
+"#;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Every renderer-reading script must select its renderer via the injected
+    /// `__abPickReactRendererId` helper rather than the old hardcoded
+    /// `rendererInterfaces.get(1)`. On Turbopack RSC apps (Next.js 16.3+) the
+    /// Flight renderer registers first as id 1 with no fiber roots, so the
+    /// hardcoded id made `react tree`/`inspect`/`suspense` read an empty tree.
+    #[test]
+    fn renderer_scripts_use_picker_not_hardcoded_id_1() {
+        for (name, script) in [
+            ("TREE_SNAPSHOT", TREE_SNAPSHOT),
+            ("TREE_INSPECT", TREE_INSPECT),
+            ("SUSPENSE_WALK", SUSPENSE_WALK),
+        ] {
+            assert!(
+                script.contains("{{PICK_RI}}"),
+                "{name} must inject the renderer picker via the {{{{PICK_RI}}}} placeholder"
+            );
+
+            let full = script.replace("{{PICK_RI}}", PICK_REACT_RENDERER);
+            assert!(
+                !full.contains("{{PICK_RI}}"),
+                "{name} still has an unresolved {{{{PICK_RI}}}} placeholder after injection"
+            );
+            assert!(
+                full.contains("function __abPickReactRendererId"),
+                "{name} is missing the picker definition after injection"
+            );
+            assert!(
+                full.contains("__abPickReactRendererId(hook)"),
+                "{name} does not call the picker to choose a renderer"
+            );
+            assert!(
+                !full.contains(".get(1)"),
+                "{name} still hardcodes rendererInterfaces.get(1)"
+            );
+            assert!(
+                !full.contains("inspectElement(1,"),
+                "{name} still hardcodes inspectElement with renderer id 1"
+            );
+        }
+    }
+
+    /// The picker prefers a non-Flight renderer with mounted fiber roots and
+    /// falls back gracefully, never assuming a fixed renderer id.
+    #[test]
+    fn picker_skips_flight_and_falls_back() {
+        assert!(PICK_REACT_RENDERER.contains("react-server-dom"));
+        assert!(PICK_REACT_RENDERER.contains("getFiberRoots"));
+        assert!(PICK_REACT_RENDERER.contains("firstWithRoots"));
+        assert!(PICK_REACT_RENDERER.contains("firstAny"));
+    }
+}

cli/src/native/react/suspense.rs

@@ -0,0 +1,633 @@
+//! React Suspense boundary introspection: walker data types, classifier, and
+//! human-readable report.
+//!
+//! The classifier labels and recommendations are React-Suspense-general —
+//! they describe what kind of thing is making a boundary suspend (`client-hook`,
+//! `request-api`, `server-fetch`, `cache`, `stream`, `framework`, `unknown`)
+//! and a high-level direction for fixing it. Framework-specific reasoning
+//! (e.g. Next.js PPR push vs goto semantics) is left to the caller.
+
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+
+pub type StackFrame = (String, String, i64, i64);
+
+#[derive(Debug, Deserialize, Serialize, Clone)]
+pub struct Boundary {
+    pub id: i64,
+    #[serde(rename = "parentID")]
+    pub parent_id: i64,
+    pub name: Option<String>,
+    #[serde(rename = "isSuspended")]
+    pub is_suspended: bool,
+    pub environments: Vec<String>,
+    #[serde(rename = "suspendedBy")]
+    pub suspended_by: Vec<Suspender>,
+    #[serde(rename = "unknownSuspenders")]
+    pub unknown_suspenders: Option<String>,
+    pub owners: Vec<Owner>,
+    #[serde(rename = "jsxSource")]
+    pub jsx_source: Option<(String, i64, i64)>,
+}
+
+#[derive(Debug, Deserialize, Serialize, Clone)]
+pub struct Owner {
+    pub name: String,
+    pub env: Option<String>,
+    pub source: Option<(String, i64, i64)>,
+}
+
+#[derive(Debug, Deserialize, Serialize, Clone)]
+pub struct Suspender {
+    pub name: String,
+    pub description: String,
+    pub duration: i64,
+    pub env: Option<String>,
+    #[serde(rename = "ownerName")]
+    pub owner_name: Option<String>,
+    #[serde(rename = "ownerStack")]
+    pub owner_stack: Option<Vec<StackFrame>>,
+    #[serde(rename = "awaiterName")]
+    pub awaiter_name: Option<String>,
+    #[serde(rename = "awaiterStack")]
+    pub awaiter_stack: Option<Vec<StackFrame>>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum BlockerKind {
+    ClientHook,
+    RequestApi,
+    ServerFetch,
+    Stream,
+    Cache,
+    Framework,
+    Unknown,
+}
+
+impl BlockerKind {
+    fn label(self) -> &'static str {
+        match self {
+            Self::ClientHook => "client-hook",
+            Self::RequestApi => "request-api",
+            Self::ServerFetch => "server-fetch",
+            Self::Stream => "stream",
+            Self::Cache => "cache",
+            Self::Framework => "framework",
+            Self::Unknown => "unknown",
+        }
+    }
+
+    fn weight(self) -> i32 {
+        match self {
+            Self::ClientHook => 7,
+            Self::RequestApi => 6,
+            Self::ServerFetch => 5,
+            Self::Cache => 4,
+            Self::Stream => 3,
+            Self::Unknown => 2,
+            Self::Framework => 1,
+        }
+    }
+
+    fn actionability(self) -> i32 {
+        match self {
+            Self::ClientHook => 90,
+            Self::RequestApi => 88,
+            Self::ServerFetch => 82,
+            Self::Cache => 74,
+            Self::Stream => 60,
+            Self::Unknown => 35,
+            Self::Framework => 18,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum BoundaryKind {
+    RouteSegment,
+    ExplicitSuspense,
+    Component,
+}
+
+impl BoundaryKind {
+    fn label(self) -> &'static str {
+        match self {
+            Self::RouteSegment => "route-segment",
+            Self::ExplicitSuspense => "explicit-suspense",
+            Self::Component => "component",
+        }
+    }
+
+    fn weight(self) -> i32 {
+        match self {
+            Self::RouteSegment => 3,
+            Self::ExplicitSuspense => 2,
+            Self::Component => 1,
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct ActionableBlocker {
+    pub key: String,
+    pub name: String,
+    pub kind: BlockerKind,
+    pub env: Option<String>,
+    pub description: String,
+    pub owner_name: Option<String>,
+    pub awaiter_name: Option<String>,
+    pub source_frame: Option<StackFrame>,
+    pub owner_frame: Option<StackFrame>,
+    pub awaiter_frame: Option<StackFrame>,
+    pub actionability: i32,
+    pub suggestion: String,
+}
+
+#[derive(Debug, Clone)]
+pub struct BoundaryInsight {
+    pub id: i64,
+    pub name: Option<String>,
+    pub boundary_kind: BoundaryKind,
+    pub environments: Vec<String>,
+    pub source: Option<(String, i64, i64)>,
+    pub rendered_by: Vec<Owner>,
+    pub primary_blocker: Option<ActionableBlocker>,
+    pub blockers: Vec<ActionableBlocker>,
+    pub unknown_suspenders: Option<String>,
+    pub actionability: i32,
+    pub recommendation: String,
+}
+
+#[derive(Debug, Clone)]
+pub struct RootCauseGroup {
+    pub kind: BlockerKind,
+    pub name: String,
+    pub source_frame: Option<StackFrame>,
+    pub boundary_names: Vec<String>,
+    pub count: usize,
+    pub actionability: i32,
+    pub suggestion: String,
+}
+
+pub struct AnalysisReport {
+    pub total_boundaries: usize,
+    pub dynamic_hole_count: usize,
+    pub static_count: usize,
+    pub holes: Vec<BoundaryInsight>,
+    pub statics: Vec<StaticBoundarySummary>,
+    pub root_causes: Vec<RootCauseGroup>,
+    pub files_to_read: Vec<String>,
+}
+
+#[derive(Debug, Clone)]
+pub struct StaticBoundarySummary {
+    pub name: Option<String>,
+    pub source: Option<(String, i64, i64)>,
+    pub rendered_by: Vec<Owner>,
+}
+
+pub fn format_suspense_report(boundaries: &[Boundary], only_dynamic: bool) -> String {
+    let report = analyze_boundaries(boundaries);
+    format_report(&report, only_dynamic)
+}
+
+fn analyze_boundaries(boundaries: &[Boundary]) -> AnalysisReport {
+    let mut holes: Vec<&Boundary> = Vec::new();
+    let mut statics_raw: Vec<&Boundary> = Vec::new();
+
+    for b in boundaries {
+        if b.parent_id == 0 {
+            continue;
+        }
+        let has_blocker = !b.suspended_by.is_empty() || b.unknown_suspenders.is_some();
+        if b.is_suspended || has_blocker {
+            holes.push(b);
+        } else {
+            statics_raw.push(b);
+        }
+    }
+
+    let mut hole_insights: Vec<BoundaryInsight> = holes.iter().map(|b| build_insight(b)).collect();
+    hole_insights.sort_by(|a, b| {
+        b.actionability.cmp(&a.actionability).then_with(|| {
+            b.boundary_kind
+                .weight()
+                .cmp(&a.boundary_kind.weight())
+                .then_with(|| b.blockers.len().cmp(&a.blockers.len()))
+                .then_with(|| {
+                    a.name
+                        .as_deref()
+                        .unwrap_or("")
+                        .cmp(b.name.as_deref().unwrap_or(""))
+                })
+        })
+    });
+
+    let static_summaries: Vec<StaticBoundarySummary> = statics_raw
+        .iter()
+        .map(|b| StaticBoundarySummary {
+            name: b.name.clone(),
+            source: b.jsx_source.clone(),
+            rendered_by: b.owners.clone(),
+        })
+        .collect();
+
+    let root_causes = build_root_causes(&hole_insights);
+    let files_to_read = collect_files_to_read(&hole_insights, &root_causes);
+
+    AnalysisReport {
+        total_boundaries: hole_insights.len() + static_summaries.len(),
+        dynamic_hole_count: hole_insights.len(),
+        static_count: static_summaries.len(),
+        holes: hole_insights,
+        statics: static_summaries,
+        root_causes,
+        files_to_read,
+    }
+}
+
+fn build_insight(b: &Boundary) -> BoundaryInsight {
+    let boundary_kind = infer_boundary_kind(b);
+    let mut blockers: Vec<ActionableBlocker> = b
+        .suspended_by
+        .iter()
+        .map(build_actionable_blocker)
+        .collect();
+    blockers.sort_by(|a, b| {
+        b.actionability.cmp(&a.actionability).then_with(|| {
+            b.kind
+                .weight()
+                .cmp(&a.kind.weight())
+                .then_with(|| a.name.cmp(&b.name))
+        })
+    });
+    let primary = blockers.first().cloned();
+    let recommendation = recommend_fix(
+        boundary_kind,
+        primary.as_ref(),
+        b.unknown_suspenders.as_deref(),
+    );
+    let primary_action = primary.as_ref().map(|p| p.actionability).unwrap_or(0);
+    let base_action = if boundary_kind == BoundaryKind::RouteSegment {
+        55
+    } else {
+        0
+    };
+
+    BoundaryInsight {
+        id: b.id,
+        name: b.name.clone(),
+        boundary_kind,
+        environments: b.environments.clone(),
+        source: b.jsx_source.clone(),
+        rendered_by: b.owners.clone(),
+        primary_blocker: primary,
+        blockers,
+        unknown_suspenders: b.unknown_suspenders.clone(),
+        actionability: primary_action.max(base_action),
+        recommendation,
+    }
+}
+
+fn build_actionable_blocker(s: &Suspender) -> ActionableBlocker {
+    let owner_frame = pick_preferred_frame(s.owner_stack.as_deref());
+    let awaiter_frame = pick_preferred_frame(s.awaiter_stack.as_deref());
+    let source_frame = owner_frame.clone().or_else(|| awaiter_frame.clone());
+    let kind = classify_blocker(s, source_frame.as_ref());
+    let suggestion = suggest_blocker_fix(kind);
+    let mut actionability = kind.actionability();
+    if let Some(ref frame) = source_frame {
+        if !is_frameworkish_path(&frame.1) {
+            actionability += 8;
+        }
+    }
+    if s.owner_name.is_some() || s.awaiter_name.is_some() {
+        actionability += 4;
+    }
+    if actionability > 100 {
+        actionability = 100;
+    }
+    let key = build_blocker_key(&s.name, kind, source_frame.as_ref());
+
+    ActionableBlocker {
+        key,
+        name: s.name.clone(),
+        kind,
+        env: s.env.clone(),
+        description: s.description.clone(),
+        owner_name: s.owner_name.clone(),
+        awaiter_name: s.awaiter_name.clone(),
+        source_frame,
+        owner_frame,
+        awaiter_frame,
+        actionability,
+        suggestion,
+    }
+}
+
+fn infer_boundary_kind(b: &Boundary) -> BoundaryKind {
+    let owner_names: Vec<&str> = b.owners.iter().map(|o| o.name.as_str()).collect();
+    let name_ends_slash = b.name.as_ref().is_some_and(|n| n.ends_with('/'));
+    if name_ends_slash
+        || owner_names.contains(&"LoadingBoundary")
+        || owner_names.contains(&"OuterLayoutRouter")
+    {
+        return BoundaryKind::RouteSegment;
+    }
+    let name_has_suspense = b.name.as_ref().is_some_and(|n| n.contains("Suspense"));
+    if name_has_suspense || owner_names.iter().any(|n| n.contains("Suspense")) {
+        return BoundaryKind::ExplicitSuspense;
+    }
+    BoundaryKind::Component
+}
+
+fn classify_blocker(s: &Suspender, source_frame: Option<&StackFrame>) -> BlockerKind {
+    let name = s.name.to_lowercase();
+    match name.as_str() {
+        "usepathname"
+        | "useparams"
+        | "usesearchparams"
+        | "useselectedlayoutsegments"
+        | "useselectedlayoutsegment"
+        | "userouter" => return BlockerKind::ClientHook,
+        "cookies" | "headers" | "connection" | "params" | "searchparams" | "draftmode" => {
+            return BlockerKind::RequestApi
+        }
+        _ => {}
+    }
+    if name == "rsc stream" {
+        return BlockerKind::Stream;
+    }
+    if name.contains("fetch") {
+        return BlockerKind::ServerFetch;
+    }
+    if name.contains("cache") || s.description.to_lowercase().contains("cache") {
+        return BlockerKind::Cache;
+    }
+    if name.starts_with("use") {
+        return BlockerKind::ClientHook;
+    }
+    if let Some(frame) = source_frame {
+        if is_frameworkish_path(&frame.1) {
+            return BlockerKind::Framework;
+        }
+    }
+    BlockerKind::Unknown
+}
+
+fn suggest_blocker_fix(kind: BlockerKind) -> String {
+    match kind {
+        BlockerKind::ClientHook => "Move route hooks behind a smaller client Suspense or provide a real non-null loading fallback for this segment.",
+        BlockerKind::RequestApi => "Push request-bound reads to a smaller server leaf, or cache around them so the parent shell can stay static.",
+        BlockerKind::ServerFetch => "Split static shell content from data widgets, then push the fetch into smaller Suspense leaves or cache it.",
+        BlockerKind::Cache => "This looks cache-related; check whether \"use cache\" or runtime prefetch can eliminate the suspension.",
+        BlockerKind::Stream => "A stream is still pending here; extract static siblings outside the boundary and push the stream consumer deeper.",
+        BlockerKind::Framework => "This currently looks framework-driven; find the nearest user-owned caller above it before changing code.",
+        BlockerKind::Unknown => "Inspect the nearest user-owned owner/awaiter frame and verify whether this suspender really belongs at this boundary.",
+    }.to_string()
+}
+
+fn recommend_fix(
+    boundary_kind: BoundaryKind,
+    primary: Option<&ActionableBlocker>,
+    unknown_suspenders: Option<&str>,
+) -> String {
+    if boundary_kind == BoundaryKind::RouteSegment
+        && primary.is_some_and(|p| p.kind == BlockerKind::ClientHook)
+    {
+        return "This route segment is suspending on client hooks. Check loading.tsx first; if it is null or visually empty, fix the fallback before chasing deeper push-down work.".to_string();
+    }
+    if let Some(p) = primary {
+        match p.kind {
+            BlockerKind::ClientHook => {
+                return "Push the hook-using client UI behind a smaller local Suspense boundary so the parent shell can prerender.".to_string();
+            }
+            BlockerKind::RequestApi | BlockerKind::ServerFetch => {
+                return "Push the request-bound async work into a smaller leaf or split static siblings out of this boundary.".to_string();
+            }
+            BlockerKind::Cache => {
+                return "Check whether caching or runtime prefetch can move this personalized content into the shell.".to_string();
+            }
+            BlockerKind::Stream => {
+                return "Keep the stream behind Suspense, but extract any static shell content outside the boundary.".to_string();
+            }
+            BlockerKind::Framework => {
+                return "The top blocker still looks framework-heavy. Find the nearest user-owned caller before changing boundary placement.".to_string();
+            }
+            _ => {}
+        }
+    }
+    if let Some(reason) = unknown_suspenders {
+        return format!(
+            "React could not identify the suspender ({}). Investigate the nearest user-owned owner or awaiter frame.",
+            reason
+        );
+    }
+    "No primary blocker was identified. Inspect the boundary source and owner chain directly."
+        .to_string()
+}
+
+fn pick_preferred_frame(stack: Option<&[StackFrame]>) -> Option<StackFrame> {
+    let s = stack?;
+    if s.is_empty() {
+        return None;
+    }
+    s.iter()
+        .find(|f| !is_frameworkish_path(&f.1))
+        .cloned()
+        .or_else(|| s.first().cloned())
+}
+
+fn is_frameworkish_path(file: &str) -> bool {
+    file.contains("/node_modules/")
+}
+
+fn build_blocker_key(name: &str, kind: BlockerKind, source_frame: Option<&StackFrame>) -> String {
+    match source_frame {
+        None => format!("{}:{}:unknown", kind.label(), name),
+        Some(f) => format!("{}:{}:{}:{}", kind.label(), name, f.1, f.2),
+    }
+}
+
+fn build_root_causes(holes: &[BoundaryInsight]) -> Vec<RootCauseGroup> {
+    let mut groups: HashMap<String, RootCauseGroup> = HashMap::new();
+    for hole in holes {
+        let Some(blocker) = &hole.primary_blocker else {
+            continue;
+        };
+        let display_name = hole
+            .name
+            .clone()
+            .unwrap_or_else(|| format!("boundary-{}", hole.id));
+        groups
+            .entry(blocker.key.clone())
+            .and_modify(|existing| {
+                existing.boundary_names.push(display_name.clone());
+                existing.count += 1;
+                if blocker.actionability > existing.actionability {
+                    existing.actionability = blocker.actionability;
+                }
+            })
+            .or_insert_with(|| RootCauseGroup {
+                kind: blocker.kind,
+                name: blocker.name.clone(),
+                source_frame: blocker.source_frame.clone(),
+                boundary_names: vec![display_name],
+                count: 1,
+                actionability: blocker.actionability,
+                suggestion: blocker.suggestion.clone(),
+            });
+    }
+    let mut out: Vec<RootCauseGroup> = groups.into_values().collect();
+    out.sort_by(|a, b| {
+        let score_a = (a.count as i32) * a.actionability;
+        let score_b = (b.count as i32) * b.actionability;
+        score_b.cmp(&score_a).then_with(|| a.name.cmp(&b.name))
+    });
+    out
+}
+
+fn collect_files_to_read(holes: &[BoundaryInsight], root_causes: &[RootCauseGroup]) -> Vec<String> {
+    let mut counts: HashMap<String, i32> = HashMap::new();
+    let mut add = |f: Option<&str>| {
+        if let Some(path) = f {
+            if !path.is_empty() {
+                *counts.entry(path.to_string()).or_insert(0) += 1;
+            }
+        }
+    };
+    for hole in holes {
+        add(hole.source.as_ref().map(|s| s.0.as_str()));
+        if let Some(pb) = &hole.primary_blocker {
+            add(pb.source_frame.as_ref().map(|f| f.1.as_str()));
+        }
+        for owner in &hole.rendered_by {
+            add(owner.source.as_ref().map(|s| s.0.as_str()));
+        }
+    }
+    for cause in root_causes {
+        add(cause.source_frame.as_ref().map(|f| f.1.as_str()));
+    }
+
+    let mut entries: Vec<(String, i32)> = counts.into_iter().collect();
+    entries.sort_by(|a, b| b.1.cmp(&a.1).then_with(|| a.0.cmp(&b.0)));
+    entries.into_iter().take(12).map(|(f, _)| f).collect()
+}
+
+fn escape_cell(s: &str) -> String {
+    s.replace('|', "\\|")
+}
+
+fn format_report(report: &AnalysisReport, only_dynamic: bool) -> String {
+    let mut lines: Vec<String> = Vec::new();
+    lines.push("# Suspense Boundary Analysis".to_string());
+    if only_dynamic {
+        lines.push(format!(
+            "# {} dynamic holes (static boundaries hidden; pass without --only-dynamic to see them)",
+            report.dynamic_hole_count
+        ));
+    } else {
+        lines.push(format!(
+            "# {} boundaries: {} dynamic holes, {} static",
+            report.total_boundaries, report.dynamic_hole_count, report.static_count
+        ));
+    }
+    lines.push(String::new());
+
+    if !report.holes.is_empty() {
+        lines.push("## Summary".to_string());
+        if let Some(top) = report.holes.first() {
+            if let Some(blocker) = &top.primary_blocker {
+                lines.push(format!(
+                    "- Top actionable hole: {} - {} ({})",
+                    top.name.clone().unwrap_or_else(|| "(unnamed)".into()),
+                    blocker.name,
+                    blocker.kind.label()
+                ));
+                lines.push(format!("- Suggested next step: {}", top.recommendation));
+            }
+        }
+        if let Some(root) = report.root_causes.first() {
+            lines.push(format!(
+                "- Most common root cause: {} ({}) affecting {} boundar{}",
+                root.name,
+                root.kind.label(),
+                root.count,
+                if root.count == 1 { "y" } else { "ies" }
+            ));
+        }
+        lines.push(String::new());
+
+        lines.push("## Quick Reference".to_string());
+        lines.push(
+            "| Boundary | Type | Primary blocker | Source | Suggested next step |".to_string(),
+        );
+        lines.push("| --- | --- | --- | --- | --- |".to_string());
+        for hole in &report.holes {
+            let blocker = &hole.primary_blocker;
+            let source = match blocker.as_ref().and_then(|b| b.source_frame.as_ref()) {
+                Some(f) => format!("{}:{}", f.1, f.2),
+                None => match &hole.source {
+                    Some((f, l, _)) => format!("{}:{}", f, l),
+                    None => "unknown".to_string(),
+                },
+            };
+            let blocker_text = match blocker {
+                Some(b) => format!("{} ({})", b.name, b.kind.label()),
+                None => "unknown".to_string(),
+            };
+            lines.push(format!(
+                "| {} | {} | {} | {} | {} |",
+                escape_cell(hole.name.as_deref().unwrap_or("(unnamed)")),
+                hole.boundary_kind.label(),
+                escape_cell(&blocker_text),
+                escape_cell(&source),
+                escape_cell(&hole.recommendation),
+            ));
+        }
+        lines.push(String::new());
+
+        if !report.files_to_read.is_empty() {
+            lines.push("## Files to Read".to_string());
+            for file in &report.files_to_read {
+                lines.push(format!("- {}", file));
+            }
+            lines.push(String::new());
+        }
+
+        if !report.root_causes.is_empty() {
+            lines.push("## Root Causes".to_string());
+            for cause in &report.root_causes {
+                let source = match &cause.source_frame {
+                    Some(f) => format!("{}:{}", f.1, f.2),
+                    None => "unknown".to_string(),
+                };
+                lines.push(format!(
+                    "- {} ({}) at {} - affects {} boundar{}",
+                    cause.name,
+                    cause.kind.label(),
+                    source,
+                    cause.count,
+                    if cause.count == 1 { "y" } else { "ies" }
+                ));
+                lines.push(format!("  next step: {}", cause.suggestion));
+                lines.push(format!("  boundaries: {}", cause.boundary_names.join(", ")));
+            }
+            lines.push(String::new());
+        }
+    }
+
+    if !only_dynamic && !report.statics.is_empty() {
+        lines.push("## Static (not suspended)".to_string());
+        for b in &report.statics {
+            let name = b.name.clone().unwrap_or_else(|| "(unnamed)".into());
+            let src = match &b.source {
+                Some(s) => format!(" at {}:{}:{}", s.0, s.1, s.2),
+                None => String::new(),
+            };
+            lines.push(format!("  {}{}", name, src));
+        }
+    }
+
+    lines.join("\n")
+}

cli/src/native/react/tree.rs

@@ -0,0 +1,67 @@
+//! React component tree snapshot and formatter.
+
+use serde::Deserialize;
+
+#[derive(Debug, Deserialize)]
+pub struct TreeNode {
+    pub id: i64,
+    #[serde(rename = "type")]
+    pub node_type: i64,
+    pub name: Option<String>,
+    pub key: Option<String>,
+    pub parent: i64,
+}
+
+const HEADER: &str = "# React component tree\n# Columns: depth id parent name [key=...]\n# Use `react inspect <id>` for props/hooks/state. IDs valid until next navigation.";
+
+pub fn format_tree(nodes: &[TreeNode]) -> String {
+    use std::collections::HashMap;
+    let mut children: HashMap<i64, Vec<&TreeNode>> = HashMap::new();
+    for n in nodes {
+        children.entry(n.parent).or_default().push(n);
+    }
+
+    let mut lines: Vec<String> = vec![HEADER.to_string()];
+    if let Some(roots) = children.get(&0) {
+        for root in roots {
+            walk(root, 0, &children, &mut lines);
+        }
+    }
+    lines.join("\n")
+}
+
+fn walk<'a>(
+    node: &'a TreeNode,
+    depth: usize,
+    children: &std::collections::HashMap<i64, Vec<&'a TreeNode>>,
+    lines: &mut Vec<String>,
+) {
+    let name = node
+        .name
+        .clone()
+        .unwrap_or_else(|| type_name(node.node_type));
+    let key = match &node.key {
+        Some(k) => format!(" key={:?}", k),
+        None => String::new(),
+    };
+    let parent = if node.parent == 0 {
+        "-".to_string()
+    } else {
+        node.parent.to_string()
+    };
+    lines.push(format!("{} {} {} {}{}", depth, node.id, parent, name, key));
+    if let Some(cs) = children.get(&node.id) {
+        for c in cs {
+            walk(c, depth + 1, children, lines);
+        }
+    }
+}
+
+fn type_name(t: i64) -> String {
+    match t {
+        11 => "Root".to_string(),
+        12 => "Suspense".to_string(),
+        13 => "SuspenseList".to_string(),
+        _ => format!("({})", t),
+    }
+}

cli/src/native/recording.rs

@@ -0,0 +1,323 @@
+use serde_json::{json, Value};
+use std::process::Stdio;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Arc;
+use std::time::Duration;
+use tokio::io::AsyncWriteExt;
+use tokio::sync::oneshot;
+
+use super::cdp::client::CdpClient;
+use super::cdp::types::{CaptureScreenshotParams, CaptureScreenshotResult};
+
+const CAPTURE_INTERVAL_MS: u64 = 100;
+const CAPTURE_FPS: u32 = 10;
+
+pub struct RecordingState {
+    pub active: bool,
+    pub output_path: String,
+    pub frame_count: u64,
+    pub capture_task: Option<tokio::task::JoinHandle<Result<(), String>>>,
+    pub shared_frame_count: Option<Arc<AtomicU64>>,
+    pub cancel_tx: Option<oneshot::Sender<()>>,
+}
+
+impl RecordingState {
+    pub fn new() -> Self {
+        Self {
+            active: false,
+            output_path: String::new(),
+            frame_count: 0,
+            capture_task: None,
+            shared_frame_count: None,
+            cancel_tx: None,
+        }
+    }
+}
+
+pub fn recording_start(state: &mut RecordingState, path: &str) -> Result<Value, String> {
+    if state.active {
+        return Err("Recording already active".to_string());
+    }
+
+    state.active = true;
+    state.output_path = path.to_string();
+    state.frame_count = 0;
+
+    Ok(json!({ "started": true, "path": path }))
+}
+
+pub fn recording_stop(state: &mut RecordingState) -> Result<Value, String> {
+    if !state.active {
+        return Err("No recording in progress".to_string());
+    }
+
+    state.active = false;
+
+    if state.frame_count == 0 {
+        return Err("No frames captured".to_string());
+    }
+
+    Ok(json!({ "path": &state.output_path, "frames": state.frame_count }))
+}
+
+pub fn recording_restart(state: &mut RecordingState, path: &str) -> Result<Value, String> {
+    let previous = if state.active {
+        let stop_result = recording_stop(state);
+        stop_result
+            .ok()
+            .and_then(|v| v.get("path").and_then(|p| p.as_str()).map(String::from))
+    } else {
+        None
+    };
+
+    recording_start(state, path)?;
+
+    Ok(json!({
+        "restarted": true,
+        "previousPath": previous,
+        "path": path,
+    }))
+}
+
+fn build_ffmpeg_command(output_path: &str) -> tokio::process::Command {
+    let mut cmd = tokio::process::Command::new("ffmpeg");
+
+    cmd.args(["-y"])
+        .args(["-avioflags", "direct"])
+        .args([
+            "-fpsprobesize",
+            "0",
+            "-probesize",
+            "32",
+            "-analyzeduration",
+            "0",
+        ])
+        .args([
+            "-f",
+            "image2pipe",
+            "-c:v",
+            "mjpeg",
+            "-framerate",
+            &CAPTURE_FPS.to_string(),
+            "-i",
+            "pipe:0",
+        ])
+        .args(["-vf", "pad=ceil(iw/2)*2:ceil(ih/2)*2"]);
+
+    if output_path.ends_with(".webm") {
+        cmd.args(["-c:v", "libvpx", "-crf", "30", "-b:v", "1M"]);
+    } else {
+        cmd.args(["-c:v", "libx264", "-preset", "ultrafast"]);
+    }
+
+    cmd.args(["-pix_fmt", "yuv420p", "-threads", "1"])
+        .arg(output_path)
+        .stdin(Stdio::piped())
+        .stdout(Stdio::null())
+        .stderr(Stdio::piped())
+        .kill_on_drop(true);
+
+    cmd
+}
+
+/// Spawn a background task that captures screenshots at a fixed interval
+/// and pipes them to ffmpeg in real-time.
+pub fn spawn_recording_task(
+    client: Arc<CdpClient>,
+    session_id: String,
+    output_path: String,
+    shared_count: Arc<AtomicU64>,
+    cancel_rx: oneshot::Receiver<()>,
+) -> tokio::task::JoinHandle<Result<(), String>> {
+    tokio::spawn(async move {
+        let mut cancel_rx = std::pin::pin!(cancel_rx);
+
+        let mut ffmpeg = build_ffmpeg_command(&output_path).spawn().map_err(|e| {
+            format!(
+                "ffmpeg not found or failed to execute: {}. Install ffmpeg to enable recording.",
+                e
+            )
+        })?;
+
+        let mut stdin = ffmpeg
+            .stdin
+            .take()
+            .ok_or_else(|| "Failed to open ffmpeg stdin".to_string())?;
+
+        let mut interval = tokio::time::interval(Duration::from_millis(CAPTURE_INTERVAL_MS));
+        interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+
+        let params = CaptureScreenshotParams {
+            format: Some("jpeg".to_string()),
+            quality: Some(80),
+            clip: None,
+            from_surface: Some(true),
+            capture_beyond_viewport: None,
+        };
+
+        loop {
+            tokio::select! {
+                _ = &mut cancel_rx => break,
+                _ = interval.tick() => {}
+            }
+
+            let result: Result<CaptureScreenshotResult, _> = client
+                .send_command_typed("Page.captureScreenshot", &params, Some(&session_id))
+                .await;
+
+            let screenshot = match result {
+                Ok(s) => s,
+                Err(e) => {
+                    if e.contains("Target closed") || e.contains("not found") {
+                        break;
+                    }
+                    continue;
+                }
+            };
+
+            let bytes = match base64::Engine::decode(
+                &base64::engine::general_purpose::STANDARD,
+                &screenshot.data,
+            ) {
+                Ok(b) => b,
+                Err(_) => continue,
+            };
+
+            if stdin.write_all(&bytes).await.is_err() {
+                break;
+            }
+            shared_count.fetch_add(1, Ordering::Relaxed);
+        }
+
+        drop(stdin);
+
+        let output = ffmpeg
+            .wait_with_output()
+            .await
+            .map_err(|e| format!("ffmpeg wait failed: {}", e))?;
+
+        if !output.status.success() {
+            let stderr = String::from_utf8_lossy(&output.stderr);
+            return Err(format!(
+                "ffmpeg failed: {}",
+                stderr.chars().take(300).collect::<String>()
+            ));
+        }
+
+        Ok(())
+    })
+}
+
+pub async fn stop_recording_task(state: &mut RecordingState) -> Result<(), String> {
+    if let Some(tx) = state.cancel_tx.take() {
+        let _ = tx.send(());
+    }
+
+    let counter = state.shared_frame_count.take();
+    let handle = state.capture_task.take();
+
+    let result = if let Some(h) = handle {
+        match h.await {
+            Ok(Ok(())) => Ok(()),
+            Ok(Err(e)) => Err(e),
+            Err(e) => Err(format!("Recording task panicked: {}", e)),
+        }
+    } else {
+        Ok(())
+    };
+
+    if let Some(c) = counter {
+        state.frame_count = c.load(Ordering::Relaxed);
+    }
+
+    result
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_recording_state_new() {
+        let state = RecordingState::new();
+        assert!(!state.active);
+        assert!(state.output_path.is_empty());
+        assert_eq!(state.frame_count, 0);
+    }
+
+    #[test]
+    fn test_recording_start_sets_active() {
+        let mut state = RecordingState::new();
+        let result = recording_start(&mut state, "/tmp/test.mp4");
+        assert!(result.is_ok());
+        assert!(state.active);
+        assert_eq!(state.output_path, "/tmp/test.mp4");
+        assert_eq!(state.frame_count, 0);
+    }
+
+    #[test]
+    fn test_recording_start_while_active() {
+        let mut state = RecordingState::new();
+        recording_start(&mut state, "/tmp/test1.mp4").unwrap();
+        let result = recording_start(&mut state, "/tmp/test2.mp4");
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("already active"));
+    }
+
+    #[test]
+    fn test_recording_stop_not_active() {
+        let mut state = RecordingState::new();
+        let result = recording_stop(&mut state);
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("No recording"));
+    }
+
+    #[test]
+    fn test_recording_stop_no_frames() {
+        let mut state = RecordingState::new();
+        recording_start(&mut state, "/tmp/test.mp4").unwrap();
+        let result = recording_stop(&mut state);
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("No frames"));
+        assert!(!state.active);
+    }
+
+    #[test]
+    fn test_recording_restart_while_inactive() {
+        let mut state = RecordingState::new();
+        let result = recording_restart(&mut state, "/tmp/new.webm");
+        assert!(result.is_ok());
+        assert!(state.active);
+        assert_eq!(state.output_path, "/tmp/new.webm");
+    }
+
+    #[test]
+    fn test_recording_restart_while_active() {
+        let mut state = RecordingState::new();
+        recording_start(&mut state, "/tmp/old.webm").unwrap();
+        state.frame_count = 10;
+        let result = recording_restart(&mut state, "/tmp/new.webm").unwrap();
+        assert!(state.active);
+        assert_eq!(state.output_path, "/tmp/new.webm");
+        assert_eq!(state.frame_count, 0);
+        assert_eq!(result["previousPath"], "/tmp/old.webm");
+    }
+
+    #[test]
+    fn test_build_ffmpeg_command_webm() {
+        let cmd = build_ffmpeg_command("/tmp/out.webm");
+        let args: Vec<&std::ffi::OsStr> = cmd.as_std().get_args().collect();
+        let args_str: Vec<&str> = args.iter().filter_map(|a| a.to_str()).collect();
+        assert!(args_str.contains(&"libvpx"));
+        assert!(args_str.contains(&"/tmp/out.webm"));
+    }
+
+    #[test]
+    fn test_build_ffmpeg_command_mp4() {
+        let cmd = build_ffmpeg_command("/tmp/out.mp4");
+        let args: Vec<&std::ffi::OsStr> = cmd.as_std().get_args().collect();
+        let args_str: Vec<&str> = args.iter().filter_map(|a| a.to_str()).collect();
+        assert!(args_str.contains(&"libx264"));
+        assert!(args_str.contains(&"/tmp/out.mp4"));
+    }
+}

cli/src/native/screenshot.rs

@@ -0,0 +1,691 @@
+use serde::Serialize;
+use serde_json::Value;
+use std::path::PathBuf;
+
+use std::collections::HashMap;
+
+use super::cdp::client::CdpClient;
+use super::cdp::types::*;
+use super::element::RefMap;
+
+const ANNOTATION_OVERLAY_ID: &str = "__agent_browser_annotations__";
+
+#[derive(Debug, Clone)]
+struct Rect {
+    x: f64,
+    y: f64,
+    width: f64,
+    height: f64,
+}
+
+#[derive(Debug, Clone)]
+struct RawAnnotation {
+    ref_id: String,
+    number: u64,
+    role: String,
+    name: Option<String>,
+    rect: Rect,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct AnnotationBox {
+    pub x: i64,
+    pub y: i64,
+    pub width: i64,
+    pub height: i64,
+}
+
+#[derive(Debug, Clone)]
+pub struct ScreenshotAnnotation {
+    pub ref_id: String,
+    pub number: u64,
+    pub role: String,
+    pub name: Option<String>,
+    pub box_: AnnotationBox,
+}
+
+#[derive(Debug, Clone)]
+pub struct ScreenshotResult {
+    pub path: String,
+    pub base64: String,
+    pub annotations: Vec<ScreenshotAnnotation>,
+}
+
+#[derive(Debug, Clone)]
+pub struct ScreenshotOptions {
+    pub selector: Option<String>,
+    pub path: Option<String>,
+    pub full_page: bool,
+    pub format: String,
+    pub quality: Option<i32>,
+    pub annotate: bool,
+    pub output_dir: Option<String>,
+}
+
+impl Default for ScreenshotOptions {
+    fn default() -> Self {
+        Self {
+            selector: None,
+            path: None,
+            full_page: false,
+            format: "png".to_string(),
+            quality: None,
+            annotate: false,
+            output_dir: None,
+        }
+    }
+}
+
+impl Serialize for ScreenshotAnnotation {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        use serde::ser::SerializeStruct;
+
+        let mut state = serializer.serialize_struct("ScreenshotAnnotation", 5)?;
+        state.serialize_field("ref", &self.ref_id)?;
+        state.serialize_field("number", &self.number)?;
+        state.serialize_field("role", &self.role)?;
+        if let Some(name) = &self.name {
+            state.serialize_field("name", name)?;
+        }
+        state.serialize_field("box", &self.box_)?;
+        state.end()
+    }
+}
+
+/// Captures a screenshot via CDP and optionally overlays numbered annotations
+/// that mirror the Node.js screenshot `annotate` mode.
+pub async fn take_screenshot(
+    client: &CdpClient,
+    session_id: &str,
+    ref_map: &RefMap,
+    options: &ScreenshotOptions,
+    iframe_sessions: &HashMap<String, String>,
+) -> Result<ScreenshotResult, String> {
+    let target_rect = if options.annotate {
+        match options.selector.as_deref() {
+            Some(selector) => {
+                get_rect_for_selector(client, session_id, ref_map, selector, iframe_sessions)
+                    .await?
+            }
+            None => None,
+        }
+    } else {
+        None
+    };
+
+    let raw_annotations = if options.annotate {
+        collect_annotations(client, session_id, ref_map).await?
+    } else {
+        Vec::new()
+    };
+
+    let overlay_items = filter_annotations(raw_annotations, target_rect.as_ref());
+    let overlay_injected = if options.annotate && !overlay_items.is_empty() {
+        inject_annotation_overlay(client, session_id, &overlay_items).await?;
+        true
+    } else {
+        false
+    };
+
+    let base64 =
+        capture_screenshot_base64(client, session_id, ref_map, options, iframe_sessions).await;
+
+    if overlay_injected {
+        let _ = remove_annotation_overlay(client, session_id).await;
+    }
+
+    let base64 = base64?;
+    let annotations = if options.annotate {
+        let scroll = if options.full_page {
+            Some(get_scroll_offsets(client, session_id).await?)
+        } else {
+            None
+        };
+        project_annotations(&overlay_items, target_rect.as_ref(), scroll)
+    } else {
+        Vec::new()
+    };
+
+    let ext = if options.format == "jpeg" {
+        "jpg"
+    } else {
+        "png"
+    };
+    let path = save_screenshot(
+        &base64,
+        options.path.as_deref(),
+        ext,
+        options.output_dir.as_deref(),
+    )?;
+
+    Ok(ScreenshotResult {
+        path,
+        base64,
+        annotations,
+    })
+}
+
+async fn capture_screenshot_base64(
+    client: &CdpClient,
+    session_id: &str,
+    ref_map: &RefMap,
+    options: &ScreenshotOptions,
+    iframe_sessions: &HashMap<String, String>,
+) -> Result<String, String> {
+    let mut params = CaptureScreenshotParams {
+        format: Some(options.format.clone()),
+        quality: if options.format == "jpeg" {
+            options.quality.or(Some(80))
+        } else {
+            None
+        },
+        clip: None,
+        from_surface: Some(true),
+        capture_beyond_viewport: if options.full_page { Some(true) } else { None },
+    };
+
+    if options.full_page {
+        let metrics: Value = client
+            .send_command_no_params("Page.getLayoutMetrics", Some(session_id))
+            .await?;
+
+        let content_size = metrics
+            .get("contentSize")
+            .or_else(|| metrics.get("cssContentSize"));
+        if let Some(size) = content_size {
+            let width = size.get("width").and_then(|v| v.as_f64()).unwrap_or(1280.0);
+            let height = size.get("height").and_then(|v| v.as_f64()).unwrap_or(720.0);
+
+            params.clip = Some(Viewport {
+                x: 0.0,
+                y: 0.0,
+                width,
+                height,
+                scale: 1.0,
+            });
+        }
+    } else if let Some(ref selector) = options.selector {
+        if let Some(rect) =
+            get_rect_for_selector(client, session_id, ref_map, selector, iframe_sessions).await?
+        {
+            params.clip = Some(Viewport {
+                x: rect.x,
+                y: rect.y,
+                width: rect.width,
+                height: rect.height,
+                scale: 1.0,
+            });
+        }
+    }
+
+    let result: CaptureScreenshotResult = client
+        .send_command_typed("Page.captureScreenshot", &params, Some(session_id))
+        .await?;
+
+    Ok(result.data)
+}
+
+async fn collect_annotations(
+    client: &CdpClient,
+    session_id: &str,
+    ref_map: &RefMap,
+) -> Result<Vec<RawAnnotation>, String> {
+    let entries = ref_map.entries_sorted();
+    if entries.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    // Collect entries that have backend_node_ids for batch resolution.
+    let with_backend_ids: Vec<(String, super::element::RefEntry, i64)> = entries
+        .iter()
+        .filter_map(|(ref_id, entry)| {
+            entry
+                .backend_node_id
+                .map(|bid| (ref_id.clone(), entry.clone(), bid))
+        })
+        .collect();
+
+    if with_backend_ids.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    // Batch-resolve all backend_node_ids to object IDs using concurrent CDP calls.
+    let resolve_futures: Vec<_> = with_backend_ids
+        .iter()
+        .map(|(_, _, backend_node_id)| {
+            client.send_command(
+                "DOM.resolveNode",
+                Some(serde_json::json!({
+                    "backendNodeId": backend_node_id,
+                    "objectGroup": "agent-browser-annotate"
+                })),
+                Some(session_id),
+            )
+        })
+        .collect();
+
+    let resolve_results = futures_util::future::join_all(resolve_futures).await;
+
+    // Collect resolved object IDs paired with their ref info.
+    let mut resolved: Vec<(String, super::element::RefEntry, String)> = Vec::new();
+    for (i, result) in resolve_results.into_iter().enumerate() {
+        if let Ok(val) = result {
+            if let Some(oid) = val
+                .get("object")
+                .and_then(|o| o.get("objectId"))
+                .and_then(|v| v.as_str())
+            {
+                let (ref_id, entry, _) = &with_backend_ids[i];
+                resolved.push((ref_id.clone(), entry.clone(), oid.to_string()));
+            }
+        }
+    }
+
+    if resolved.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    // Batch-get bounding rects for all resolved elements using concurrent CDP calls.
+    let rect_futures: Vec<_> = resolved
+        .iter()
+        .map(|(_, _, object_id)| get_rect_for_object(client, session_id, object_id))
+        .collect();
+
+    let rect_results = futures_util::future::join_all(rect_futures).await;
+
+    let mut annotations = Vec::new();
+    for (i, rect_result) in rect_results.into_iter().enumerate() {
+        let rect = match rect_result {
+            Ok(Some(r)) if r.width > 0.0 && r.height > 0.0 => r,
+            _ => continue,
+        };
+
+        let (ref_id, entry, _) = &resolved[i];
+        let number = ref_id
+            .strip_prefix('e')
+            .and_then(|n| n.parse::<u64>().ok())
+            .unwrap_or(0);
+
+        annotations.push(RawAnnotation {
+            ref_id: ref_id.clone(),
+            number,
+            role: entry.role.clone(),
+            name: (!entry.name.is_empty()).then_some(entry.name.clone()),
+            rect,
+        });
+    }
+
+    Ok(annotations)
+}
+
+async fn get_rect_for_selector(
+    client: &CdpClient,
+    session_id: &str,
+    ref_map: &RefMap,
+    selector: &str,
+    iframe_sessions: &HashMap<String, String>,
+) -> Result<Option<Rect>, String> {
+    let (object_id, effective_session_id) = super::element::resolve_element_object_id(
+        client,
+        session_id,
+        ref_map,
+        selector,
+        iframe_sessions,
+    )
+    .await?;
+    get_rect_for_object(client, &effective_session_id, &object_id).await
+}
+
+async fn get_rect_for_object(
+    client: &CdpClient,
+    session_id: &str,
+    object_id: &str,
+) -> Result<Option<Rect>, String> {
+    let result: EvaluateResult = client
+        .send_command_typed(
+            "Runtime.callFunctionOn",
+            &CallFunctionOnParams {
+                function_declaration: r#"function() {
+                    const rect = this.getBoundingClientRect();
+                    return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+                }"#
+                .to_string(),
+                object_id: Some(object_id.to_string()),
+                arguments: None,
+                return_by_value: Some(true),
+                await_promise: Some(false),
+            },
+            Some(session_id),
+        )
+        .await?;
+
+    Ok(result.result.value.as_ref().and_then(parse_rect))
+}
+
+fn parse_rect(value: &Value) -> Option<Rect> {
+    Some(Rect {
+        x: value.get("x")?.as_f64()?,
+        y: value.get("y")?.as_f64()?,
+        width: value.get("width")?.as_f64()?,
+        height: value.get("height")?.as_f64()?,
+    })
+}
+
+fn filter_annotations(
+    annotations: Vec<RawAnnotation>,
+    target_rect: Option<&Rect>,
+) -> Vec<RawAnnotation> {
+    let mut items = annotations
+        .into_iter()
+        .filter(|annotation| match target_rect {
+            Some(target) => overlaps(&annotation.rect, target),
+            None => true,
+        })
+        .collect::<Vec<_>>();
+
+    items.sort_by_key(|annotation| annotation.number);
+    items
+}
+
+fn overlaps(left: &Rect, right: &Rect) -> bool {
+    let left_x2 = left.x + left.width;
+    let left_y2 = left.y + left.height;
+    let right_x2 = right.x + right.width;
+    let right_y2 = right.y + right.height;
+
+    left.x < right_x2 && left_x2 > right.x && left.y < right_y2 && left_y2 > right.y
+}
+
+async fn inject_annotation_overlay(
+    client: &CdpClient,
+    session_id: &str,
+    annotations: &[RawAnnotation],
+) -> Result<(), String> {
+    let overlay_data = annotations
+        .iter()
+        .map(|annotation| {
+            serde_json::json!({
+                "number": annotation.number,
+                "x": round(annotation.rect.x),
+                "y": round(annotation.rect.y),
+                "width": round(annotation.rect.width),
+                "height": round(annotation.rect.height),
+            })
+        })
+        .collect::<Vec<_>>();
+
+    let expression = format!(
+        r#"(() => {{
+            var items = {items};
+            var id = {overlay_id};
+            var existing = document.getElementById(id);
+            if (existing) existing.remove();
+            var sx = window.scrollX || 0;
+            var sy = window.scrollY || 0;
+            var c = document.createElement('div');
+            c.id = id;
+            c.style.cssText = 'position:absolute;top:0;left:0;width:0;height:0;pointer-events:none;z-index:2147483647;';
+            for (var i = 0; i < items.length; i++) {{
+                var it = items[i];
+                var dx = it.x + sx;
+                var dy = it.y + sy;
+                var b = document.createElement('div');
+                b.style.cssText = 'position:absolute;left:' + dx + 'px;top:' + dy + 'px;width:' + it.width + 'px;height:' + it.height + 'px;border:2px solid rgba(255,0,0,0.8);box-sizing:border-box;pointer-events:none;';
+                var l = document.createElement('div');
+                l.textContent = String(it.number);
+                var labelTop = dy < 14 ? '2px' : '-14px';
+                l.style.cssText = 'position:absolute;top:' + labelTop + ';left:-2px;background:rgba(255,0,0,0.9);color:#fff;font:bold 11px/14px monospace;padding:0 4px;border-radius:2px;white-space:nowrap;';
+                b.appendChild(l);
+                c.appendChild(b);
+            }}
+            document.documentElement.appendChild(c);
+            return true;
+        }})()"#,
+        items = serde_json::to_string(&overlay_data).unwrap_or_else(|_| "[]".to_string()),
+        overlay_id =
+            serde_json::to_string(ANNOTATION_OVERLAY_ID).unwrap_or_else(|_| "\"\"".to_string()),
+    );
+
+    let _: EvaluateResult = client
+        .send_command_typed(
+            "Runtime.evaluate",
+            &EvaluateParams {
+                expression,
+                return_by_value: Some(true),
+                await_promise: Some(false),
+            },
+            Some(session_id),
+        )
+        .await?;
+
+    Ok(())
+}
+
+async fn remove_annotation_overlay(client: &CdpClient, session_id: &str) -> Result<(), String> {
+    let expression = format!(
+        r#"(() => {{
+            var el = document.getElementById({overlay_id});
+            if (el) el.remove();
+            return true;
+        }})()"#,
+        overlay_id =
+            serde_json::to_string(ANNOTATION_OVERLAY_ID).unwrap_or_else(|_| "\"\"".to_string()),
+    );
+
+    let _: EvaluateResult = client
+        .send_command_typed(
+            "Runtime.evaluate",
+            &EvaluateParams {
+                expression,
+                return_by_value: Some(true),
+                await_promise: Some(false),
+            },
+            Some(session_id),
+        )
+        .await?;
+
+    Ok(())
+}
+
+async fn get_scroll_offsets(client: &CdpClient, session_id: &str) -> Result<(f64, f64), String> {
+    let result: EvaluateResult = client
+        .send_command_typed(
+            "Runtime.evaluate",
+            &EvaluateParams {
+                expression: "({x: window.scrollX || 0, y: window.scrollY || 0})".to_string(),
+                return_by_value: Some(true),
+                await_promise: Some(false),
+            },
+            Some(session_id),
+        )
+        .await?;
+
+    let value = result.result.value.unwrap_or(Value::Null);
+    let x = value.get("x").and_then(|v| v.as_f64()).unwrap_or(0.0);
+    let y = value.get("y").and_then(|v| v.as_f64()).unwrap_or(0.0);
+    Ok((x, y))
+}
+
+fn project_annotations(
+    annotations: &[RawAnnotation],
+    target_rect: Option<&Rect>,
+    scroll: Option<(f64, f64)>,
+) -> Vec<ScreenshotAnnotation> {
+    annotations
+        .iter()
+        .map(|annotation| {
+            let rect = if let Some(target) = target_rect {
+                Rect {
+                    x: annotation.rect.x - target.x,
+                    y: annotation.rect.y - target.y,
+                    width: annotation.rect.width,
+                    height: annotation.rect.height,
+                }
+            } else if let Some((scroll_x, scroll_y)) = scroll {
+                Rect {
+                    x: annotation.rect.x + scroll_x,
+                    y: annotation.rect.y + scroll_y,
+                    width: annotation.rect.width,
+                    height: annotation.rect.height,
+                }
+            } else {
+                annotation.rect.clone()
+            };
+
+            ScreenshotAnnotation {
+                ref_id: annotation.ref_id.clone(),
+                number: annotation.number,
+                role: annotation.role.clone(),
+                name: annotation.name.clone(),
+                box_: AnnotationBox {
+                    x: round(rect.x),
+                    y: round(rect.y),
+                    width: round(rect.width),
+                    height: round(rect.height),
+                },
+            }
+        })
+        .collect()
+}
+
+fn save_screenshot(
+    base64_data: &str,
+    explicit_path: Option<&str>,
+    ext: &str,
+    output_dir: Option<&str>,
+) -> Result<String, String> {
+    let save_path = match explicit_path {
+        Some(path) => path.to_string(),
+        None => {
+            let dir = match output_dir {
+                Some(d) => PathBuf::from(d),
+                None => get_screenshot_dir(),
+            };
+            let _ = std::fs::create_dir_all(&dir);
+            let timestamp = std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap_or_default()
+                .as_millis();
+            let name = format!("screenshot-{}.{}", timestamp, ext);
+            dir.join(name).to_string_lossy().to_string()
+        }
+    };
+
+    let bytes = base64::Engine::decode(&base64::engine::general_purpose::STANDARD, base64_data)
+        .map_err(|e| format!("Failed to decode screenshot: {}", e))?;
+
+    std::fs::write(&save_path, &bytes)
+        .map_err(|e| format!("Failed to save screenshot to {}: {}", save_path, e))?;
+
+    Ok(save_path)
+}
+
+fn round(value: f64) -> i64 {
+    value.round() as i64
+}
+
+fn get_screenshot_dir() -> PathBuf {
+    if let Some(home) = dirs::home_dir() {
+        home.join(".agent-browser").join("tmp").join("screenshots")
+    } else {
+        std::env::temp_dir()
+            .join("agent-browser")
+            .join("screenshots")
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn filters_annotations_to_target_overlap() {
+        let annotations = vec![
+            RawAnnotation {
+                ref_id: "e1".to_string(),
+                number: 1,
+                role: "button".to_string(),
+                name: Some("Inside".to_string()),
+                rect: Rect {
+                    x: 10.0,
+                    y: 10.0,
+                    width: 50.0,
+                    height: 20.0,
+                },
+            },
+            RawAnnotation {
+                ref_id: "e2".to_string(),
+                number: 2,
+                role: "button".to_string(),
+                name: Some("Outside".to_string()),
+                rect: Rect {
+                    x: 200.0,
+                    y: 200.0,
+                    width: 40.0,
+                    height: 20.0,
+                },
+            },
+        ];
+
+        let target = Rect {
+            x: 0.0,
+            y: 0.0,
+            width: 100.0,
+            height: 100.0,
+        };
+
+        let filtered = filter_annotations(annotations, Some(&target));
+        assert_eq!(filtered.len(), 1);
+        assert_eq!(filtered[0].ref_id, "e1");
+    }
+
+    #[test]
+    fn projects_selector_annotations_relative_to_target() {
+        let annotations = vec![RawAnnotation {
+            ref_id: "e1".to_string(),
+            number: 1,
+            role: "button".to_string(),
+            name: Some("Inside".to_string()),
+            rect: Rect {
+                x: 25.0,
+                y: 35.0,
+                width: 40.0,
+                height: 20.0,
+            },
+        }];
+
+        let target = Rect {
+            x: 10.0,
+            y: 15.0,
+            width: 100.0,
+            height: 100.0,
+        };
+
+        let projected = project_annotations(&annotations, Some(&target), None);
+        assert_eq!(projected[0].box_.x, 15);
+        assert_eq!(projected[0].box_.y, 20);
+    }
+
+    #[test]
+    fn projects_full_page_annotations_to_document_space() {
+        let annotations = vec![RawAnnotation {
+            ref_id: "e1".to_string(),
+            number: 1,
+            role: "button".to_string(),
+            name: Some("Bottom".to_string()),
+            rect: Rect {
+                x: 5.0,
+                y: 12.0,
+                width: 40.0,
+                height: 20.0,
+            },
+        }];
+
+        let projected = project_annotations(&annotations, None, Some((10.0, 1000.0)));
+        assert_eq!(projected[0].box_.x, 15);
+        assert_eq!(projected[0].box_.y, 1012);
+    }
+}

cli/src/native/storage.rs

@@ -0,0 +1,94 @@
+use serde_json::{json, Value};
+
+use super::cdp::client::CdpClient;
+use super::cdp::types::EvaluateParams;
+
+pub async fn storage_get(
+    client: &CdpClient,
+    session_id: &str,
+    storage_type: &str,
+    key: Option<&str>,
+) -> Result<Value, String> {
+    let st = storage_js_name(storage_type);
+
+    if let Some(k) = key {
+        let js = format!(
+            "{}.getItem({})",
+            st,
+            serde_json::to_string(k).unwrap_or_default()
+        );
+        let result = eval_simple(client, session_id, &js).await?;
+        Ok(json!({ "key": k, "value": result }))
+    } else {
+        let js = format!(
+            r#"(() => {{
+                const s = {};
+                const data = {{}};
+                for (let i = 0; i < s.length; i++) {{
+                    const key = s.key(i);
+                    data[key] = s.getItem(key);
+                }}
+                return data;
+            }})()"#,
+            st
+        );
+        let result = eval_simple(client, session_id, &js).await?;
+        Ok(json!({ "data": result }))
+    }
+}
+
+pub async fn storage_set(
+    client: &CdpClient,
+    session_id: &str,
+    storage_type: &str,
+    key: &str,
+    value: &str,
+) -> Result<(), String> {
+    let st = storage_js_name(storage_type);
+    let js = format!(
+        "{}.setItem({}, {})",
+        st,
+        serde_json::to_string(key).unwrap_or_default(),
+        serde_json::to_string(value).unwrap_or_default(),
+    );
+    eval_simple(client, session_id, &js).await?;
+    Ok(())
+}
+
+pub async fn storage_clear(
+    client: &CdpClient,
+    session_id: &str,
+    storage_type: &str,
+) -> Result<(), String> {
+    let st = storage_js_name(storage_type);
+    let js = format!("{}.clear()", st);
+    eval_simple(client, session_id, &js).await?;
+    Ok(())
+}
+
+fn storage_js_name(storage_type: &str) -> &str {
+    match storage_type {
+        "session" => "sessionStorage",
+        _ => "localStorage",
+    }
+}
+
+async fn eval_simple(client: &CdpClient, session_id: &str, js: &str) -> Result<Value, String> {
+    let result: super::cdp::types::EvaluateResult = client
+        .send_command_typed(
+            "Runtime.evaluate",
+            &EvaluateParams {
+                expression: js.to_string(),
+                return_by_value: Some(true),
+                await_promise: Some(false),
+            },
+            Some(session_id),
+        )
+        .await?;
+
+    if let Some(ref details) = result.exception_details {
+        return Err(format!("Storage error: {}", details.text));
+    }
+
+    Ok(result.result.value.unwrap_or(Value::Null))
+}

cli/src/native/stream/cdp_loop.rs

@@ -0,0 +1,325 @@
+use serde_json::{json, Value};
+use std::sync::Arc;
+
+use tokio::sync::{broadcast, watch, Mutex, RwLock};
+
+use crate::native::cdp::client::CdpClient;
+use crate::native::network;
+
+use super::timestamp_ms;
+
+/// Background task that subscribes to CDP events and broadcasts screencast frames in real-time.
+/// Also handles auto-start/stop of screencast based on WebSocket client count.
+#[allow(clippy::too_many_arguments)]
+pub(super) async fn cdp_event_loop(
+    frame_tx: broadcast::Sender<String>,
+    client_slot: Arc<RwLock<Option<Arc<CdpClient>>>>,
+    client_notify: Arc<tokio::sync::Notify>,
+    screencasting: Arc<Mutex<bool>>,
+    client_count: Arc<Mutex<usize>>,
+    cdp_session_id: Arc<RwLock<Option<String>>>,
+    viewport_width: Arc<Mutex<u32>>,
+    viewport_height: Arc<Mutex<u32>>,
+    last_frame: Arc<RwLock<Option<String>>>,
+    last_tabs: Arc<RwLock<Vec<Value>>>,
+    last_engine: Arc<RwLock<String>>,
+    recording: Arc<Mutex<bool>>,
+    mut shutdown_rx: watch::Receiver<bool>,
+) {
+    loop {
+        tokio::select! {
+            changed = shutdown_rx.changed() => {
+                if changed.is_err() || *shutdown_rx.borrow() {
+                    let session_id = cdp_session_id.read().await.clone();
+                    if *screencasting.lock().await {
+                        if let Some(ref client) = *client_slot.read().await {
+                            let _ = client
+                                .send_command_no_params("Page.stopScreencast", session_id.as_deref())
+                                .await;
+                        }
+                        let mut sc = screencasting.lock().await;
+                        *sc = false;
+                    }
+                    return;
+                }
+            }
+            _ = client_notify.notified() => {}
+        }
+
+        let count = *client_count.lock().await;
+        let guard = client_slot.read().await;
+
+        if count > 0 {
+            if let Some(ref client) = *guard {
+                let mut event_rx = client.subscribe();
+                let client_arc = Arc::clone(client);
+                drop(guard);
+
+                let session_id = cdp_session_id.read().await.clone();
+
+                let vw = *viewport_width.lock().await;
+                let vh = *viewport_height.lock().await;
+
+                let eng = last_engine.read().await.clone();
+                let supports_screencast = eng == "chrome";
+
+                if supports_screencast {
+                    let _ = client_arc
+                        .send_command(
+                            "Page.startScreencast",
+                            Some(json!({
+                                "format": "jpeg",
+                                "quality": 80,
+                                "maxWidth": vw,
+                                "maxHeight": vh,
+                                "everyNthFrame": 1,
+                            })),
+                            session_id.as_deref(),
+                        )
+                        .await;
+                }
+
+                {
+                    let mut sc = screencasting.lock().await;
+                    *sc = supports_screencast;
+                }
+
+                let rec = *recording.lock().await;
+                let status = json!({
+                    "type": "status",
+                    "connected": true,
+                    "screencasting": supports_screencast,
+                    "viewportWidth": vw,
+                    "viewportHeight": vh,
+                    "engine": eng,
+                    "recording": rec,
+                });
+                let _ = frame_tx.send(status.to_string());
+
+                loop {
+                    tokio::select! {
+                        changed = shutdown_rx.changed() => {
+                            if changed.is_err() || *shutdown_rx.borrow() {
+                                if supports_screencast {
+                                    let session_id = cdp_session_id.read().await.clone();
+                                    let _ = client_arc
+                                        .send_command_no_params("Page.stopScreencast", session_id.as_deref())
+                                        .await;
+                                }
+                                let mut sc = screencasting.lock().await;
+                                *sc = false;
+                                return;
+                            }
+                        }
+                        event = event_rx.recv() => {
+                            match event {
+                                Ok(evt) => {
+                                    if evt.method == "Page.frameNavigated" {
+                                        if let Some(frame) = evt.params.get("frame") {
+                                            let is_main = frame
+                                                .get("parentId")
+                                                .and_then(|v| v.as_str())
+                                                .is_none_or(|s| s.is_empty());
+                                            if is_main {
+                                                if let Some(url) = frame.get("url").and_then(|v| v.as_str()) {
+                                                    {
+                                                        let mut tabs = last_tabs.write().await;
+                                                        for tab in tabs.iter_mut() {
+                                                            if tab.get("active").and_then(|v| v.as_bool()).unwrap_or(false) {
+                                                                tab.as_object_mut().map(|o| o.insert("url".to_string(), json!(url)));
+                                                            }
+                                                        }
+                                                    }
+                                                    let msg = json!({
+                                                        "type": "url",
+                                                        "url": url,
+                                                        "timestamp": timestamp_ms(),
+                                                    });
+                                                    let _ = frame_tx.send(msg.to_string());
+                                                }
+                                            }
+                                        }
+                                    } else if evt.method == "Page.screencastFrame" {
+                                        if let Some(sid) = evt.params.get("sessionId").and_then(|v| v.as_i64()) {
+                                            let _ = client_arc.send_command(
+                                                "Page.screencastFrameAck",
+                                                Some(json!({ "sessionId": sid })),
+                                                evt.session_id.as_deref(),
+                                            ).await;
+                                        }
+
+                                        if let Some(data) = evt.params.get("data").and_then(|v| v.as_str()) {
+                                            let meta = evt.params.get("metadata");
+                                            let msg = json!({
+                                                "type": "frame",
+                                                "data": data,
+                                                "metadata": {
+                                                    "offsetTop": meta.and_then(|m| m.get("offsetTop")).and_then(|v| v.as_f64()).unwrap_or(0.0),
+                                                    "pageScaleFactor": meta.and_then(|m| m.get("pageScaleFactor")).and_then(|v| v.as_f64()).unwrap_or(1.0),
+                                                    "deviceWidth": vw,
+                                                    "deviceHeight": vh,
+                                                    "scrollOffsetX": meta.and_then(|m| m.get("scrollOffsetX")).and_then(|v| v.as_f64()).unwrap_or(0.0),
+                                                    "scrollOffsetY": meta.and_then(|m| m.get("scrollOffsetY")).and_then(|v| v.as_f64()).unwrap_or(0.0),
+                                                    "timestamp": meta.and_then(|m| m.get("timestamp")).and_then(|v| v.as_u64()).unwrap_or(0),
+                                                }
+                                            });
+                                            let msg_str = msg.to_string();
+                                            {
+                                                let mut lf = last_frame.write().await;
+                                                *lf = Some(msg_str.clone());
+                                            }
+                                            let _ = frame_tx.send(msg_str);
+                                        }
+                                    } else if evt.method == "Runtime.consoleAPICalled" {
+                                        let level = evt.params.get("type")
+                                            .and_then(|v| v.as_str())
+                                            .unwrap_or("log");
+                                        let raw_args = evt.params.get("args")
+                                            .and_then(|v| v.as_array())
+                                            .cloned()
+                                            .unwrap_or_default();
+                                        let text = network::format_console_args(&raw_args);
+                                        if !text.is_empty() {
+                                            let mut msg = json!({
+                                                "type": "console",
+                                                "level": level,
+                                                "text": text,
+                                                "timestamp": timestamp_ms(),
+                                            });
+                                            if !raw_args.is_empty() {
+                                                msg.as_object_mut().unwrap().insert(
+                                                    "args".to_string(),
+                                                    Value::Array(raw_args),
+                                                );
+                                            }
+                                            let _ = frame_tx.send(msg.to_string());
+                                        }
+                                    } else if evt.method == "Runtime.exceptionThrown" {
+                                        let text = evt.params.get("exceptionDetails")
+                                            .and_then(|d| {
+                                                d.get("exception")
+                                                    .and_then(|e| e.get("description").and_then(|v| v.as_str()))
+                                                    .or_else(|| d.get("text").and_then(|v| v.as_str()))
+                                            })
+                                            .unwrap_or("Unknown error");
+                                        let line = evt.params.get("exceptionDetails")
+                                            .and_then(|d| d.get("lineNumber").and_then(|v| v.as_i64()));
+                                        let column = evt.params.get("exceptionDetails")
+                                            .and_then(|d| d.get("columnNumber").and_then(|v| v.as_i64()));
+                                        let msg = json!({
+                                            "type": "page_error",
+                                            "text": text,
+                                            "line": line,
+                                            "column": column,
+                                            "timestamp": timestamp_ms(),
+                                        });
+                                        let _ = frame_tx.send(msg.to_string());
+                                    }
+                                }
+                                Err(broadcast::error::RecvError::Lagged(_)) => continue,
+                                Err(broadcast::error::RecvError::Closed) => break,
+                            }
+                        }
+                        _ = client_notify.notified() => {
+                            let count = *client_count.lock().await;
+                            let new_session_id = cdp_session_id.read().await.clone();
+                            if count == 0 {
+                                if supports_screencast {
+                                    let _ = client_arc
+                                        .send_command_no_params("Page.stopScreencast", session_id.as_deref())
+                                        .await;
+                                }
+                                let mut sc = screencasting.lock().await;
+                                *sc = false;
+                                break;
+                            }
+                            let client_changed = {
+                                let guard = client_slot.read().await;
+                                let same = guard
+                                    .as_ref()
+                                    .is_some_and(|c| Arc::ptr_eq(c, &client_arc));
+                                !same
+                            };
+                            let session_changed = new_session_id != session_id;
+                            let new_vw = *viewport_width.lock().await;
+                            let new_vh = *viewport_height.lock().await;
+                            let viewport_changed = new_vw != vw || new_vh != vh;
+                            if client_changed || session_changed || viewport_changed {
+                                if supports_screencast {
+                                    let _ = client_arc
+                                        .send_command_no_params("Page.stopScreencast", session_id.as_deref())
+                                        .await;
+                                }
+                                let mut sc = screencasting.lock().await;
+                                *sc = false;
+                                client_notify.notify_one();
+                                break;
+                            }
+                        }
+                    }
+                }
+            } else {
+                drop(guard);
+            }
+        } else {
+            let was_screencasting = *screencasting.lock().await;
+            if was_screencasting {
+                if let Some(ref client) = *guard {
+                    let session_id = cdp_session_id.read().await.clone();
+                    let _ = client
+                        .send_command_no_params("Page.stopScreencast", session_id.as_deref())
+                        .await;
+                }
+                let mut sc = screencasting.lock().await;
+                *sc = false;
+            }
+            drop(guard);
+        }
+    }
+}
+
+pub async fn start_screencast(
+    client: &CdpClient,
+    session_id: &str,
+    format: &str,
+    quality: i32,
+    max_width: i32,
+    max_height: i32,
+) -> Result<(), String> {
+    client
+        .send_command(
+            "Page.startScreencast",
+            Some(json!({
+                "format": format,
+                "quality": quality,
+                "maxWidth": max_width,
+                "maxHeight": max_height,
+                "everyNthFrame": 1,
+            })),
+            Some(session_id),
+        )
+        .await?;
+    Ok(())
+}
+
+pub async fn stop_screencast(client: &CdpClient, session_id: &str) -> Result<(), String> {
+    client
+        .send_command_no_params("Page.stopScreencast", Some(session_id))
+        .await?;
+    Ok(())
+}
+
+pub async fn ack_screencast_frame(
+    client: &CdpClient,
+    session_id: &str,
+    screencast_session_id: i64,
+) -> Result<(), String> {
+    client
+        .send_command(
+            "Page.screencastFrameAck",
+            Some(json!({ "sessionId": screencast_session_id })),
+            Some(session_id),
+        )
+        .await?;
+    Ok(())
+}

cli/src/native/stream/chat.rs

@@ -0,0 +1,970 @@
+use std::sync::OnceLock;
+
+use serde_json::{json, Value};
+
+use tokio::io::AsyncWriteExt;
+
+use super::http::cors_headers_for_origin;
+
+pub(crate) const DEFAULT_AI_GATEWAY_URL: &str = "https://ai-gateway.vercel.sh";
+
+static HTTP_CLIENT: OnceLock<reqwest::Client> = OnceLock::new();
+
+pub(crate) fn http_client() -> &'static reqwest::Client {
+    HTTP_CLIENT.get_or_init(reqwest::Client::new)
+}
+
+pub(crate) fn is_chat_enabled() -> bool {
+    std::env::var("AI_GATEWAY_API_KEY").is_ok()
+}
+
+pub(super) fn chat_status_json() -> String {
+    let enabled = is_chat_enabled();
+    let mut obj = json!({ "enabled": enabled });
+    if enabled {
+        if let Ok(model) = std::env::var("AI_GATEWAY_MODEL") {
+            obj["model"] = Value::String(model);
+        }
+    }
+    obj.to_string()
+}
+
+pub(super) async fn handle_models_request(
+    stream: &mut tokio::net::TcpStream,
+    origin: Option<&str>,
+) {
+    let cors = cors_headers_for_origin(origin);
+    let gateway_url = std::env::var("AI_GATEWAY_URL")
+        .unwrap_or_else(|_| DEFAULT_AI_GATEWAY_URL.to_string())
+        .trim_end_matches('/')
+        .to_string();
+    let api_key = match std::env::var("AI_GATEWAY_API_KEY") {
+        Ok(k) => k,
+        Err(_) => {
+            let body = r#"{"data":[]}"#;
+            let resp = format!(
+                "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n{cors}\r\n",
+                body.len()
+            );
+            let _ = stream.write_all(resp.as_bytes()).await;
+            let _ = stream.write_all(body.as_bytes()).await;
+            return;
+        }
+    };
+
+    let url = format!("{}/v1/models", gateway_url);
+    let client = http_client();
+    let result = client
+        .get(&url)
+        .header("Authorization", format!("Bearer {}", api_key))
+        .send()
+        .await;
+
+    let body = match result {
+        Ok(r) if r.status().is_success() => r
+            .text()
+            .await
+            .unwrap_or_else(|_| r#"{"data":[]}"#.to_string()),
+        _ => r#"{"data":[]}"#.to_string(),
+    };
+
+    let resp = format!(
+        "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n{cors}\r\n",
+        body.len()
+    );
+    let _ = stream.write_all(resp.as_bytes()).await;
+    let _ = stream.write_all(body.as_bytes()).await;
+}
+
+const SKILL_NAMES: &[&str] = &["agent-browser", "slack", "electron", "dogfood", "agentcore"];
+
+/// Locate the `skills/` directory by walking up from the executable.
+/// Works for npm installs (binary in `bin/`, skills at `../skills/`) and
+/// dev builds (binary deep in `cli/target/`, skills at repo root).
+fn find_skills_dir() -> Option<std::path::PathBuf> {
+    let exe = std::env::current_exe().ok()?;
+    let real = exe.canonicalize().unwrap_or(exe);
+    let mut dir = real.parent();
+    while let Some(d) = dir {
+        let candidate = d.join("skills");
+        if candidate.join("agent-browser").join("SKILL.md").exists() {
+            return Some(candidate);
+        }
+        dir = d.parent();
+    }
+    None
+}
+
+fn load_skills() -> Vec<(String, String)> {
+    let Some(skills_dir) = find_skills_dir() else {
+        return Vec::new();
+    };
+    SKILL_NAMES
+        .iter()
+        .filter_map(|name| {
+            let path = skills_dir.join(name).join("SKILL.md");
+            let content = std::fs::read_to_string(&path).ok()?;
+            Some((name.to_string(), content))
+        })
+        .collect()
+}
+
+fn strip_frontmatter(s: &str) -> &str {
+    if !s.starts_with("---") {
+        return s;
+    }
+    if let Some(end) = s[3..].find("---") {
+        let after = &s[3 + end + 3..];
+        after.trim_start_matches(['\n', '\r'])
+    } else {
+        s
+    }
+}
+
+pub(crate) fn get_system_prompt() -> &'static str {
+    static PROMPT: OnceLock<String> = OnceLock::new();
+    PROMPT.get_or_init(|| {
+        let skills = load_skills();
+
+        let mut sections = String::new();
+        for (name, content) in &skills {
+            let body = strip_frontmatter(content);
+            sections.push_str(&format!("\n\n<skill name=\"{}\">\n{}\n</skill>", name, body.trim()));
+        }
+
+        format!(
+            r#"You are an AI assistant that controls a browser through agent-browser. You have an active browser session, but you can also create new sessions.
+
+RULES:
+- You MUST use the agent_browser tool for every browser action. NEVER claim you performed an action without calling the tool.
+- If the user asks you to do something, call the tool first, then describe the result.
+- If a request is outside your capabilities (e.g. system operations), say so honestly. Do not improvise or pretend.
+- One tool call per command. Do not chain with `&&` or `;`.
+- Do not add `--json`.
+- Do not run non-agent-browser programs.
+- Keep responses concise.
+- For screenshots, omit the path argument so they save to the default location (which will be displayed inline). Screenshots from tool calls are ALREADY shown to the user. Do NOT re-display them with markdown image syntax in your text response. Never use `![...]()` to reference screenshots.
+- To create a new session: add `--session <name>` to any command (e.g. `agent-browser --session my-session open https://example.com`). If the session does not exist, it will be created automatically.
+- To use a different browser engine: add `--engine <engine>` (e.g. `agent-browser --session lp-session --engine lightpanda open https://example.com`). Supported engines: chrome (default), lightpanda.
+
+The following skill references describe agent-browser capabilities in detail. Use them when deciding which commands to run and how to approach tasks.
+{sections}"#,
+        )
+    })
+}
+
+pub(crate) const CHAT_TOOLS: &str = r#"[{"type":"function","function":{"name":"agent_browser","description":"Execute an agent-browser command. Runs against the active session by default. Add --session <name> to target or create a different session, and --engine <engine> to choose a browser engine.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The command to execute, e.g. 'agent-browser open https://google.com' or 'agent-browser --session new-session open https://example.com' or 'agent-browser snapshot -i' or 'agent-browser click @e3'"}},"required":["command"]}}}]"#;
+
+pub(crate) const COMPACT_THRESHOLD_CHARS: usize = 200_000;
+pub(crate) const KEEP_RECENT_MESSAGES: usize = 6;
+
+pub(crate) fn estimate_chars(messages: &[Value]) -> usize {
+    messages
+        .iter()
+        .map(|m| {
+            let content_len = m
+                .get("content")
+                .map(|c| {
+                    if let Some(s) = c.as_str() {
+                        s.len()
+                    } else {
+                        c.to_string().len()
+                    }
+                })
+                .unwrap_or(0);
+            let tc_len = m
+                .get("tool_calls")
+                .map(|t| t.to_string().len())
+                .unwrap_or(0);
+            content_len + tc_len
+        })
+        .sum()
+}
+
+pub(crate) fn find_safe_split(messages: &[Value], keep_recent: usize) -> usize {
+    if messages.len() <= keep_recent + 1 {
+        return 1;
+    }
+    let desired = messages.len() - keep_recent;
+    for i in (1..=desired).rev() {
+        if messages[i].get("role").and_then(|r| r.as_str()) == Some("user") {
+            return i;
+        }
+    }
+    desired.max(1)
+}
+
+fn build_summary_text(messages: &[Value]) -> String {
+    let mut text = String::new();
+    for msg in messages {
+        let role = msg
+            .get("role")
+            .and_then(|r| r.as_str())
+            .unwrap_or("unknown");
+        if let Some(content) = msg.get("content").and_then(|c| c.as_str()) {
+            if !content.is_empty() {
+                let truncated = if content.len() > 2000 {
+                    format!("{}...[truncated]", &content[..2000])
+                } else {
+                    content.to_string()
+                };
+                text.push_str(&format!("[{}] {}\n\n", role, truncated));
+            }
+        }
+        if let Some(tcs) = msg.get("tool_calls").and_then(|t| t.as_array()) {
+            for tc in tcs {
+                let name = tc
+                    .get("function")
+                    .and_then(|f| f.get("name"))
+                    .and_then(|n| n.as_str())
+                    .unwrap_or("");
+                let args = tc
+                    .get("function")
+                    .and_then(|f| f.get("arguments"))
+                    .and_then(|a| a.as_str())
+                    .unwrap_or("");
+                text.push_str(&format!("[assistant tool:{}] {}\n", name, args));
+            }
+        }
+    }
+    text
+}
+
+pub(crate) async fn summarize_for_compaction(
+    client: &reqwest::Client,
+    url: &str,
+    api_key: &str,
+    model: &str,
+    messages: &[Value],
+) -> Option<String> {
+    let conversation = build_summary_text(messages);
+    if conversation.is_empty() {
+        return None;
+    }
+
+    let body = json!({
+        "model": model,
+        "messages": [
+            {
+                "role": "system",
+                "content": "Summarize this browser automation conversation concisely. Preserve: URLs visited, actions performed, current page state, errors encountered, and user goals. Output only the summary."
+            },
+            {
+                "role": "user",
+                "content": conversation
+            }
+        ],
+        "max_tokens": 1024,
+        "stream": false,
+    });
+
+    let resp = client
+        .post(url)
+        .header("Authorization", format!("Bearer {}", api_key))
+        .header("Content-Type", "application/json")
+        .body(body.to_string())
+        .send()
+        .await
+        .ok()?;
+
+    if !resp.status().is_success() {
+        return None;
+    }
+
+    let result: Value = resp.json().await.ok()?;
+    result
+        .get("choices")
+        .and_then(|c| c.get(0))
+        .and_then(|c| c.get("message"))
+        .and_then(|m| m.get("content"))
+        .and_then(|c| c.as_str())
+        .map(|s| s.to_string())
+}
+
+const SCREENSHOT_MAX_WIDTH: u32 = 1024;
+const SCREENSHOT_JPEG_QUALITY: u8 = 40;
+
+fn compress_image_to_jpeg(raw_bytes: &[u8]) -> Option<Vec<u8>> {
+    let img = image::load_from_memory(raw_bytes).ok()?;
+    let img = if img.width() > SCREENSHOT_MAX_WIDTH {
+        img.resize(
+            SCREENSHOT_MAX_WIDTH,
+            u32::MAX,
+            image::imageops::FilterType::Triangle,
+        )
+    } else {
+        img
+    };
+    let mut buf = std::io::Cursor::new(Vec::new());
+    let encoder =
+        image::codecs::jpeg::JpegEncoder::new_with_quality(&mut buf, SCREENSHOT_JPEG_QUALITY);
+    img.write_with_encoder(encoder).ok()?;
+    Some(buf.into_inner())
+}
+
+fn has_image_extension(s: &str) -> bool {
+    let lower = s.to_lowercase();
+    lower.ends_with(".png") || lower.ends_with(".jpg") || lower.ends_with(".jpeg")
+}
+
+fn extract_image_path(text: &str) -> Option<String> {
+    for line in text.lines() {
+        let trimmed = line.trim();
+        // Whole line is a path (handles paths with spaces)
+        if has_image_extension(trimmed) && std::path::Path::new(trimmed).exists() {
+            return Some(trimmed.to_string());
+        }
+        for suffix in [".png", ".jpg", ".jpeg"] {
+            if let Some(pos) = trimmed.to_lowercase().rfind(suffix) {
+                let end = pos + suffix.len();
+                let candidate = &trimmed[..end];
+                let start = candidate
+                    .rfind(|c: char| c.is_whitespace())
+                    .map(|i| i + 1)
+                    .unwrap_or(0);
+                let path = &candidate[start..];
+                if !path.is_empty() && std::path::Path::new(path).exists() {
+                    return Some(path.to_string());
+                }
+            }
+        }
+    }
+    None
+}
+
+fn enrich_tool_output(result: &str) -> String {
+    let Some(path) = extract_image_path(result) else {
+        return result.to_string();
+    };
+
+    let Ok(raw_bytes) = std::fs::read(&path) else {
+        return result.to_string();
+    };
+
+    let (jpeg_bytes, mime) = match compress_image_to_jpeg(&raw_bytes) {
+        Some(compressed) => (compressed, "image/jpeg"),
+        None => {
+            let lower = path.to_lowercase();
+            (
+                raw_bytes,
+                if lower.ends_with(".png") {
+                    "image/png"
+                } else {
+                    "image/jpeg"
+                },
+            )
+        }
+    };
+
+    let b64 = base64::Engine::encode(&base64::engine::general_purpose::STANDARD, &jpeg_bytes);
+    let data_url = format!("data:{};base64,{}", mime, b64);
+
+    json!({
+        "text": result,
+        "image": data_url
+    })
+    .to_string()
+}
+
+const ALLOWED_COMMANDS: &[&str] = &[
+    "open",
+    "goto",
+    "navigate",
+    "back",
+    "forward",
+    "reload",
+    "click",
+    "dblclick",
+    "fill",
+    "type",
+    "hover",
+    "focus",
+    "check",
+    "uncheck",
+    "select",
+    "drag",
+    "upload",
+    "download",
+    "press",
+    "key",
+    "keydown",
+    "keyup",
+    "keyboard",
+    "scroll",
+    "scrollintoview",
+    "scrollinto",
+    "wait",
+    "screenshot",
+    "pdf",
+    "snapshot",
+    "eval",
+    "close",
+    "quit",
+    "exit",
+    "inspect",
+    "auth",
+    "confirm",
+    "deny",
+    "connect",
+    "cookies",
+    "storage",
+    "window",
+    "frame",
+    "dialog",
+    "trace",
+    "profiler",
+    "record",
+    "har",
+    "network",
+    "title",
+    "url",
+    "console",
+    "errors",
+    "highlight",
+    "state",
+    "emulate",
+    "video",
+    "tap",
+    "swipe",
+    "device",
+    "batch",
+    "diff",
+    "find",
+    "role",
+    "text",
+    "label",
+    "placeholder",
+    "alt",
+    "testid",
+    "first",
+    "last",
+    "nth",
+    "mouse",
+    "touchscreen",
+    "attribute",
+    "property",
+    "set",
+    "get",
+    "is",
+    "stream",
+    "tab",
+    "clipboard",
+    "session",
+];
+
+const ALLOWED_GLOBAL_FLAGS: &[&str] = &["--session", "--engine"];
+
+pub(crate) async fn execute_chat_tool(session: &str, command: &str) -> String {
+    let exe = match std::env::current_exe() {
+        Ok(p) => p,
+        Err(e) => return format!("Failed to resolve executable: {}", e),
+    };
+
+    let single = command.split("&&").next().unwrap_or(command);
+    let single = single.split(';').next().unwrap_or(single).trim();
+    let stripped = single.strip_prefix("agent-browser ").unwrap_or(single);
+    let words = crate::commands::shell_words_split(stripped);
+
+    let mut global_flags: Vec<String> = Vec::new();
+    let mut cmd_words: Vec<String> = Vec::new();
+    let mut has_session_flag = false;
+    let mut i = 0;
+    while i < words.len() {
+        if ALLOWED_GLOBAL_FLAGS.contains(&words[i].as_str()) {
+            if words[i] == "--session" {
+                has_session_flag = true;
+            }
+            global_flags.push(words[i].clone());
+            if i + 1 < words.len() {
+                global_flags.push(words[i + 1].clone());
+                i += 2;
+            } else {
+                i += 1;
+            }
+        } else {
+            cmd_words.push(words[i].clone());
+            i += 1;
+        }
+    }
+
+    let first_cmd = cmd_words.first().map(|s| s.as_str()).unwrap_or("");
+    if !ALLOWED_COMMANDS.contains(&first_cmd) {
+        return format!(
+            "Blocked: '{}' is not a valid agent-browser command.",
+            first_cmd
+        );
+    }
+
+    let mut args: Vec<String> = Vec::new();
+    if !has_session_flag {
+        args.push("--session".into());
+        args.push(session.into());
+    }
+    args.extend(global_flags);
+    args.extend(cmd_words);
+
+    let mut cmd = tokio::process::Command::new(&exe);
+    cmd.args(&args)
+        .env_remove("AGENT_BROWSER_DASHBOARD")
+        .env_remove("AGENT_BROWSER_DASHBOARD_PORT")
+        .env_remove("AGENT_BROWSER_STREAM_PORT");
+
+    match cmd.output().await {
+        Ok(output) => {
+            let stdout = String::from_utf8_lossy(&output.stdout).trim().to_string();
+            let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
+            if stdout.is_empty() && !stderr.is_empty() {
+                stderr
+            } else if stdout.is_empty() {
+                "Command completed with no output.".to_string()
+            } else {
+                stdout
+            }
+        }
+        Err(e) => format!("Failed to execute command: {}", e),
+    }
+}
+
+async fn stream_gateway_response(
+    stream: &mut tokio::net::TcpStream,
+    gw_response: reqwest::Response,
+) -> Vec<(String, String, String)> {
+    use futures_util::StreamExt as _;
+
+    let mut text_part_id = uuid::Uuid::new_v4().to_string();
+    let mut text_started = false;
+    let mut tool_calls: Vec<(String, String, String)> = Vec::new();
+    let mut tool_call_args: std::collections::HashMap<usize, (String, String, String)> =
+        std::collections::HashMap::new();
+    let mut byte_stream = gw_response.bytes_stream();
+    let mut buffer = String::new();
+
+    while let Some(chunk_result) = byte_stream.next().await {
+        let chunk = match chunk_result {
+            Ok(c) => c,
+            Err(_) => break,
+        };
+
+        buffer.push_str(&String::from_utf8_lossy(&chunk));
+
+        while let Some(newline_pos) = buffer.find('\n') {
+            let line = buffer[..newline_pos].trim_end_matches('\r').to_string();
+            buffer = buffer[newline_pos + 1..].to_string();
+
+            if line.is_empty() {
+                continue;
+            }
+            let Some(data) = line.strip_prefix("data: ") else {
+                continue;
+            };
+            if data == "[DONE]" {
+                if text_started {
+                    let ev = format!("data: {}\n\n", json!({"type":"text-end","id":text_part_id}));
+                    let _ = stream.write_all(ev.as_bytes()).await;
+                }
+                let mut indices: Vec<usize> = tool_call_args.keys().copied().collect();
+                indices.sort();
+                for idx in indices {
+                    if let Some(tc) = tool_call_args.remove(&idx) {
+                        tool_calls.push(tc);
+                    }
+                }
+                return tool_calls;
+            }
+            let Ok(sse_json) = serde_json::from_str::<Value>(data) else {
+                continue;
+            };
+            let delta = sse_json
+                .get("choices")
+                .and_then(|c| c.get(0))
+                .and_then(|c| c.get("delta"));
+            let Some(delta) = delta else { continue };
+
+            if let Some(text) = delta.get("content").and_then(|c| c.as_str()) {
+                if !text.is_empty() {
+                    if !text_started {
+                        let ev = format!(
+                            "data: {}\n\n",
+                            json!({"type":"text-start","id":text_part_id})
+                        );
+                        if stream.write_all(ev.as_bytes()).await.is_err() {
+                            return tool_calls;
+                        }
+                        text_started = true;
+                    }
+                    let ev = format!(
+                        "data: {}\n\n",
+                        json!({"type":"text-delta","id":text_part_id,"delta":text})
+                    );
+                    if stream.write_all(ev.as_bytes()).await.is_err() {
+                        return tool_calls;
+                    }
+                }
+            }
+
+            if let Some(tcs) = delta.get("tool_calls").and_then(|t| t.as_array()) {
+                if text_started {
+                    let ev = format!("data: {}\n\n", json!({"type":"text-end","id":text_part_id}));
+                    let _ = stream.write_all(ev.as_bytes()).await;
+                    text_started = false;
+                    text_part_id = uuid::Uuid::new_v4().to_string();
+                }
+
+                for tc in tcs {
+                    let idx = tc.get("index").and_then(|i| i.as_u64()).unwrap_or(0) as usize;
+                    if let std::collections::hash_map::Entry::Vacant(e) = tool_call_args.entry(idx)
+                    {
+                        let id = tc
+                            .get("id")
+                            .and_then(|i| i.as_str())
+                            .unwrap_or("")
+                            .to_string();
+                        let name = tc
+                            .get("function")
+                            .and_then(|f| f.get("name"))
+                            .and_then(|n| n.as_str())
+                            .unwrap_or("")
+                            .to_string();
+                        let ev = format!(
+                            "data: {}\n\n",
+                            json!({"type":"tool-input-start","toolCallId":id,"toolName":name})
+                        );
+                        let _ = stream.write_all(ev.as_bytes()).await;
+                        e.insert((id, name, String::new()));
+                    }
+                    if let Some(arg_delta) = tc
+                        .get("function")
+                        .and_then(|f| f.get("arguments"))
+                        .and_then(|a| a.as_str())
+                    {
+                        let entry = tool_call_args.get_mut(&idx).unwrap();
+                        entry.2.push_str(arg_delta);
+                        let ev = format!(
+                            "data: {}\n\n",
+                            json!({"type":"tool-input-delta","toolCallId":entry.0,"inputTextDelta":arg_delta})
+                        );
+                        let _ = stream.write_all(ev.as_bytes()).await;
+                    }
+                }
+            }
+        }
+    }
+
+    if text_started {
+        let ev = format!("data: {}\n\n", json!({"type":"text-end","id":text_part_id}));
+        let _ = stream.write_all(ev.as_bytes()).await;
+    }
+    let mut indices: Vec<usize> = tool_call_args.keys().copied().collect();
+    indices.sort();
+    for idx in indices {
+        if let Some(tc) = tool_call_args.remove(&idx) {
+            tool_calls.push(tc);
+        }
+    }
+    tool_calls
+}
+
+pub(super) async fn handle_chat_request(
+    stream: &mut tokio::net::TcpStream,
+    body: &str,
+    origin: Option<&str>,
+) {
+    let cors = cors_headers_for_origin(origin);
+    let gateway_url = std::env::var("AI_GATEWAY_URL")
+        .unwrap_or_else(|_| DEFAULT_AI_GATEWAY_URL.to_string())
+        .trim_end_matches('/')
+        .to_string();
+    let api_key = match std::env::var("AI_GATEWAY_API_KEY") {
+        Ok(k) => k,
+        Err(_) => {
+            let err = r#"{"error":"AI_GATEWAY_API_KEY not set. Set the AI_GATEWAY_API_KEY environment variable to enable AI chat."}"#;
+            let resp = format!(
+                "HTTP/1.1 500 Internal Server Error\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n{cors}\r\n",
+                err.len()
+            );
+            let _ = stream.write_all(resp.as_bytes()).await;
+            let _ = stream.write_all(err.as_bytes()).await;
+            return;
+        }
+    };
+
+    let default_model = std::env::var("AI_GATEWAY_MODEL")
+        .unwrap_or_else(|_| "anthropic/claude-sonnet-4.6".to_string());
+
+    let parsed: Value = match serde_json::from_str(body) {
+        Ok(v) => v,
+        Err(e) => {
+            let err = format!(r#"{{"error":"Invalid JSON: {}"}}"#, e);
+            let resp = format!(
+                "HTTP/1.1 400 Bad Request\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n{cors}\r\n",
+                err.len()
+            );
+            let _ = stream.write_all(resp.as_bytes()).await;
+            let _ = stream.write_all(err.as_bytes()).await;
+            return;
+        }
+    };
+
+    let messages = parsed.get("messages").cloned().unwrap_or(json!([]));
+    let model = parsed
+        .get("model")
+        .and_then(|v| v.as_str())
+        .unwrap_or(&default_model)
+        .to_string();
+    let session = parsed
+        .get("session")
+        .and_then(|v| v.as_str())
+        .unwrap_or("default")
+        .to_string();
+
+    let mut openai_messages: Vec<Value> =
+        vec![json!({"role": "system", "content": get_system_prompt()})];
+    let mut frontend_boundaries: Vec<usize> = Vec::new();
+    let frontend_arr = messages.as_array();
+    let frontend_count = frontend_arr.map(|a| a.len()).unwrap_or(0);
+    if let Some(arr) = frontend_arr {
+        for msg in arr {
+            frontend_boundaries.push(openai_messages.len());
+            let Some(role) = msg.get("role").and_then(|r| r.as_str()) else {
+                continue;
+            };
+            if let Some(parts) = msg.get("parts").and_then(|p| p.as_array()) {
+                let mut content_parts: Vec<Value> = Vec::new();
+                for part in parts {
+                    match part.get("type").and_then(|t| t.as_str()) {
+                        Some("text") => {
+                            if let Some(text) = part.get("text").and_then(|t| t.as_str()) {
+                                if !text.is_empty() {
+                                    content_parts.push(json!({"type": "text", "text": text}));
+                                }
+                            }
+                        }
+                        Some("file") => {
+                            if let (Some(url), Some(media_type)) = (
+                                part.get("url").and_then(|u| u.as_str()),
+                                part.get("mediaType").and_then(|m| m.as_str()),
+                            ) {
+                                if media_type.starts_with("image/") {
+                                    content_parts.push(json!({
+                                        "type": "image_url",
+                                        "image_url": { "url": url }
+                                    }));
+                                }
+                            }
+                        }
+                        _ => {}
+                    }
+                }
+                if !content_parts.is_empty() {
+                    let content = if content_parts.len() == 1
+                        && content_parts[0].get("type").and_then(|t| t.as_str()) == Some("text")
+                    {
+                        content_parts[0]["text"].clone()
+                    } else {
+                        json!(content_parts)
+                    };
+                    openai_messages.push(json!({"role": role, "content": content}));
+                }
+            } else if let Some(content) = msg.get("content").and_then(|c| c.as_str()) {
+                openai_messages.push(json!({"role": role, "content": content}));
+            }
+        }
+    }
+
+    let tools: Value = serde_json::from_str(CHAT_TOOLS).unwrap();
+    let url = format!("{}/v1/chat/completions", gateway_url);
+    let client = http_client();
+
+    let total_chars = estimate_chars(&openai_messages);
+    let mut compaction_summary: Option<String> = None;
+    let mut compaction_failed = false;
+    let mut keep_last_n: usize = frontend_count;
+
+    if total_chars > COMPACT_THRESHOLD_CHARS && openai_messages.len() > KEEP_RECENT_MESSAGES + 2 {
+        let split = find_safe_split(&openai_messages, KEEP_RECENT_MESSAGES);
+        let to_summarize = &openai_messages[1..split];
+
+        if let Some(summary) =
+            summarize_for_compaction(client, &url, &api_key, &model, to_summarize).await
+        {
+            let summary_msg = json!({
+                "role": "system",
+                "content": format!("[Conversation summary]\n{}", summary)
+            });
+            let recent = openai_messages[split..].to_vec();
+            openai_messages = vec![openai_messages[0].clone(), summary_msg];
+            openai_messages.extend(recent);
+
+            let kept_frontend = frontend_boundaries
+                .iter()
+                .filter(|&&boundary| boundary >= split)
+                .count();
+            keep_last_n = kept_frontend;
+            compaction_summary = Some(summary);
+        } else {
+            compaction_failed = true;
+        }
+    }
+
+    let headers = format!(
+        "HTTP/1.1 200 OK\r\nContent-Type: text/event-stream\r\nCache-Control: no-cache\r\nConnection: keep-alive\r\nx-vercel-ai-ui-message-stream: v1\r\n{cors}\r\n"
+    );
+    if stream.write_all(headers.as_bytes()).await.is_err() {
+        return;
+    }
+
+    let message_id = uuid::Uuid::new_v4().to_string();
+    let start_ev = format!(
+        "data: {}\n\n",
+        json!({"type":"start","messageId":message_id})
+    );
+    if stream.write_all(start_ev.as_bytes()).await.is_err() {
+        return;
+    }
+
+    if let Some(ref summary) = compaction_summary {
+        let ev = format!(
+            "data: {}\n\n",
+            json!({
+                "type": "message-metadata",
+                "messageMetadata": {
+                    "compacted": true,
+                    "summary": summary,
+                    "keepLastN": keep_last_n
+                }
+            })
+        );
+        let _ = stream.write_all(ev.as_bytes()).await;
+    } else if compaction_failed {
+        let ev = format!(
+            "data: {}\n\n",
+            json!({
+                "type": "message-metadata",
+                "messageMetadata": {
+                    "compacted": false,
+                    "warning": "Conversation is large but compaction failed. Responses may be degraded."
+                }
+            })
+        );
+        let _ = stream.write_all(ev.as_bytes()).await;
+    }
+
+    let total_deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(300);
+    const TOOL_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(60);
+
+    for _step in 0..50 {
+        if tokio::time::Instant::now() >= total_deadline {
+            let ev = format!(
+                "data: {}\n\n",
+                json!({"type":"error","errorText":"Chat session timed out (5 minute limit)."})
+            );
+            let _ = stream.write_all(ev.as_bytes()).await;
+            break;
+        }
+
+        let step_ev = "data: {\"type\":\"start-step\"}\n\n";
+        if stream.write_all(step_ev.as_bytes()).await.is_err() {
+            return;
+        }
+
+        let gateway_body = json!({
+            "model": model,
+            "messages": openai_messages,
+            "tools": tools,
+            "stream": true,
+        });
+
+        let gw_response = match client
+            .post(&url)
+            .header("Authorization", format!("Bearer {}", api_key))
+            .header("Content-Type", "application/json")
+            .body(gateway_body.to_string())
+            .send()
+            .await
+        {
+            Ok(r) => r,
+            Err(e) => {
+                let ev = format!(
+                    "data: {}\n\n",
+                    json!({"type":"error","errorText":format!("Gateway request failed: {}", e)})
+                );
+                let _ = stream.write_all(ev.as_bytes()).await;
+                break;
+            }
+        };
+
+        if !gw_response.status().is_success() {
+            let body_text = gw_response.text().await.unwrap_or_default();
+            let ev = format!(
+                "data: {}\n\n",
+                json!({"type":"error","errorText":body_text})
+            );
+            let _ = stream.write_all(ev.as_bytes()).await;
+            break;
+        }
+
+        let tool_calls = stream_gateway_response(stream, gw_response).await;
+
+        if tool_calls.is_empty() {
+            let finish_step_ev = "data: {\"type\":\"finish-step\"}\n\n";
+            let _ = stream.write_all(finish_step_ev.as_bytes()).await;
+            break;
+        }
+
+        let tc_values: Vec<Value> = tool_calls.iter().map(|(id, name, args)| {
+            json!({"id": id, "type": "function", "function": {"name": name, "arguments": args}})
+        }).collect();
+        openai_messages.push(json!({"role": "assistant", "tool_calls": tc_values}));
+
+        for (tc_id, tc_name, tc_args) in &tool_calls {
+            let input: Value = serde_json::from_str(tc_args).unwrap_or(json!({}));
+            let command = input.get("command").and_then(|c| c.as_str()).unwrap_or("");
+
+            let ev = format!(
+                "data: {}\n\n",
+                json!({
+                    "type": "tool-input-available",
+                    "toolCallId": tc_id,
+                    "toolName": tc_name,
+                    "input": input
+                })
+            );
+            let _ = stream.write_all(ev.as_bytes()).await;
+
+            let result = match tokio::time::timeout(
+                TOOL_TIMEOUT,
+                execute_chat_tool(&session, command),
+            )
+            .await
+            {
+                Ok(r) => r,
+                Err(_) => "Tool execution timed out after 60 seconds.".to_string(),
+            };
+
+            let frontend_output = enrich_tool_output(&result);
+            let ev = format!(
+                "data: {}\n\n",
+                json!({
+                    "type": "tool-output-available",
+                    "toolCallId": tc_id,
+                    "output": frontend_output
+                })
+            );
+            let _ = stream.write_all(ev.as_bytes()).await;
+
+            openai_messages.push(json!({
+                "role": "tool",
+                "tool_call_id": tc_id,
+                "content": result
+            }));
+        }
+
+        let finish_step_ev = "data: {\"type\":\"finish-step\"}\n\n";
+        let _ = stream.write_all(finish_step_ev.as_bytes()).await;
+    }
+
+    let finish_ev = "data: {\"type\":\"finish\"}\n\n";
+    let _ = stream.write_all(finish_ev.as_bytes()).await;
+    let done_ev = "data: [DONE]\n\n";
+    let _ = stream.write_all(done_ev.as_bytes()).await;
+}

cli/src/native/stream/dashboard.rs

@@ -0,0 +1,960 @@
+use futures_util::{SinkExt, StreamExt};
+use serde_json::{json, Value};
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::TcpListener;
+use tokio_tungstenite::tungstenite::Message;
+
+use crate::connection::get_socket_dir;
+
+use super::chat::{chat_status_json, handle_chat_request, handle_models_request};
+use super::discovery::discover_sessions;
+use super::http::{serve_embedded_file, CORS_HEADERS};
+
+/// Dashboard same-origin proxy endpoints for session metadata and streams.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum SessionProxyEndpoint {
+    Tabs,
+    Status,
+    Stream,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct DashboardProxyError {
+    status: &'static str,
+    message: String,
+}
+
+impl DashboardProxyError {
+    fn not_found(message: impl Into<String>) -> Self {
+        Self {
+            status: "404 Not Found",
+            message: message.into(),
+        }
+    }
+
+    fn bad_gateway(message: impl Into<String>) -> Self {
+        Self {
+            status: "502 Bad Gateway",
+            message: message.into(),
+        }
+    }
+}
+
+const PROXY_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30);
+const PROXY_MAX_RESPONSE_SIZE: u64 = 16 * 1024 * 1024;
+
+fn build_json_error_body(error: &str) -> String {
+    let escaped = serde_json::to_string(error).unwrap_or_else(|_| format!("\"{}\"", error));
+    format!(r#"{{"success":false,"error":{escaped}}}"#)
+}
+
+async fn write_http_response_inner(
+    stream: &mut tokio::net::TcpStream,
+    status: &str,
+    content_type: &str,
+    body: &[u8],
+    include_cors: bool,
+) {
+    let cors_headers = if include_cors { CORS_HEADERS } else { "" };
+    let response = format!(
+        "HTTP/1.1 {status}\r\nContent-Type: {content_type}\r\nContent-Length: {}\r\nConnection: close\r\n{cors_headers}\r\n",
+        body.len()
+    );
+    let _ = stream.write_all(response.as_bytes()).await;
+    let _ = stream.write_all(body).await;
+}
+
+async fn write_http_response(
+    stream: &mut tokio::net::TcpStream,
+    status: &str,
+    content_type: &str,
+    body: &[u8],
+) {
+    write_http_response_inner(stream, status, content_type, body, true).await;
+}
+
+async fn write_http_response_no_cors(
+    stream: &mut tokio::net::TcpStream,
+    status: &str,
+    content_type: &str,
+    body: &[u8],
+) {
+    write_http_response_inner(stream, status, content_type, body, false).await;
+}
+
+async fn write_json_error_response_no_cors(
+    stream: &mut tokio::net::TcpStream,
+    status: &'static str,
+    error: &str,
+) {
+    let body = build_json_error_body(error);
+    write_http_response_no_cors(
+        stream,
+        status,
+        "application/json; charset=utf-8",
+        body.as_bytes(),
+    )
+    .await;
+}
+
+fn parse_request_method_and_path(request: &str) -> (&str, &str) {
+    let first_line = request.lines().next().unwrap_or("");
+    let method = first_line.split_whitespace().next().unwrap_or("GET");
+    let path = first_line.split_whitespace().nth(1).unwrap_or("/");
+    (method, path)
+}
+
+fn is_websocket_upgrade(request: &str) -> bool {
+    request.lines().any(|line| {
+        if let Some((name, value)) = line.split_once(':') {
+            name.trim().eq_ignore_ascii_case("upgrade")
+                && value.trim().eq_ignore_ascii_case("websocket")
+        } else {
+            false
+        }
+    })
+}
+
+fn request_header_value<'a>(request: &'a str, name: &str) -> Option<&'a str> {
+    request.lines().find_map(|line| {
+        let (header_name, value) = line.split_once(':')?;
+        if header_name.trim().eq_ignore_ascii_case(name) {
+            Some(value.trim())
+        } else {
+            None
+        }
+    })
+}
+
+fn normalize_origin_authority(origin: &str) -> Option<String> {
+    let url = url::Url::parse(origin).ok()?;
+    let host = url.host_str()?.to_ascii_lowercase();
+    let host = if host.contains(':') {
+        format!("[{host}]")
+    } else {
+        host
+    };
+    Some(match url.port() {
+        Some(port) => format!("{host}:{port}"),
+        None => host,
+    })
+}
+
+fn normalize_host_authority(host: &str) -> String {
+    let host = host.trim().to_ascii_lowercase();
+
+    if let Some(bracket_end) = host.rfind(']') {
+        if bracket_end == host.len() - 1 {
+            return host;
+        }
+
+        if host.as_bytes().get(bracket_end + 1) == Some(&b':') {
+            let port = &host[bracket_end + 2..];
+            if port == "80" || port == "443" {
+                return host[..=bracket_end].to_string();
+            }
+        }
+
+        return host;
+    }
+
+    if let Some((name, port)) = host.rsplit_once(':') {
+        if !name.contains(':') && (port == "80" || port == "443") {
+            return name.to_string();
+        }
+    }
+
+    host
+}
+
+fn header_matches_host(request: &str, header_name: &str) -> Option<bool> {
+    let authority =
+        request_header_value(request, header_name).and_then(normalize_origin_authority)?;
+    let host = request_header_value(request, "host").map(normalize_host_authority)?;
+    Some(authority == host)
+}
+
+/// Validates that a proxied WebSocket request either has no Origin header or
+/// presents an Origin whose authority matches the request Host header.
+fn is_same_origin_ws_request(request: &str) -> bool {
+    match header_matches_host(request, "origin") {
+        Some(matches) => matches,
+        None => request_header_value(request, "origin").is_none(),
+    }
+}
+
+/// Validates that an HTTP session-proxy request came from a same-origin page.
+///
+/// For GET requests we require either a same-origin `Origin` or a same-origin
+/// `Referer` so browsers cannot hit the proxy routes via side-channel tags or
+/// arbitrary cross-origin fetches.
+fn is_same_origin_http_request(request: &str) -> bool {
+    matches!(header_matches_host(request, "origin"), Some(true))
+        || matches!(header_matches_host(request, "referer"), Some(true))
+}
+
+/// Parse a dashboard route of the form `/api/session/<port>/<endpoint>`.
+fn parse_session_proxy_route(path: &str) -> Result<(u16, SessionProxyEndpoint), &'static str> {
+    if !path.starts_with("/api/session/") {
+        return Err("Invalid session proxy route.");
+    }
+
+    let mut parts = path.split('/');
+    if parts.next() != Some("") || parts.next() != Some("api") || parts.next() != Some("session") {
+        return Err("Invalid session proxy route.");
+    }
+
+    let port_str = parts.next().ok_or("Missing session proxy port.")?;
+    if port_str.is_empty() {
+        return Err("Missing session proxy port.");
+    }
+
+    let endpoint = match parts.next().ok_or("Missing session proxy endpoint.")? {
+        "tabs" => SessionProxyEndpoint::Tabs,
+        "status" => SessionProxyEndpoint::Status,
+        "stream" => SessionProxyEndpoint::Stream,
+        _ => return Err("Unknown session proxy endpoint."),
+    };
+
+    if parts.next().is_some() {
+        return Err("Unexpected path segments in session proxy route.");
+    }
+
+    let port = port_str
+        .parse::<u16>()
+        .map_err(|_| "Session proxy port must be a valid TCP port.")?;
+    if port == 0 {
+        return Err("Session proxy port must be a valid TCP port.");
+    }
+
+    Ok((port, endpoint))
+}
+
+fn sessions_json_has_active_port(sessions_json: &str, port: u16) -> Result<bool, String> {
+    let sessions: Vec<Value> = serde_json::from_str(sessions_json)
+        .map_err(|e| format!("Failed to parse active sessions: {e}"))?;
+    Ok(sessions.iter().any(|session| {
+        session
+            .get("port")
+            .and_then(|value| value.as_u64())
+            .map(|value| value == u64::from(port))
+            .unwrap_or(false)
+    }))
+}
+
+fn require_active_session_port(port: u16) -> Result<(), DashboardProxyError> {
+    let sessions_json = discover_sessions();
+    let is_active = sessions_json_has_active_port(&sessions_json, port)
+        .map_err(DashboardProxyError::bad_gateway)?;
+    if is_active {
+        Ok(())
+    } else {
+        Err(DashboardProxyError::not_found(format!(
+            "No active session is listening on port {port}."
+        )))
+    }
+}
+
+fn split_http_response(response: &[u8]) -> Result<(&[u8], &[u8]), String> {
+    if let Some(header_end) = response.windows(4).position(|window| window == b"\r\n\r\n") {
+        let body_start = header_end + 4;
+        return Ok((&response[..header_end], &response[body_start..]));
+    }
+
+    if let Some(header_end) = response.windows(2).position(|window| window == b"\n\n") {
+        let body_start = header_end + 2;
+        return Ok((&response[..header_end], &response[body_start..]));
+    }
+
+    Err("Upstream response was missing an HTTP header terminator.".to_string())
+}
+
+fn parse_upstream_http_response(response: &[u8]) -> Result<(String, String, Vec<u8>), String> {
+    let (header_bytes, body) = split_http_response(response)?;
+    let header_str = std::str::from_utf8(header_bytes)
+        .map_err(|e| format!("Upstream response headers were not valid UTF-8: {e}"))?;
+
+    let mut lines = header_str.lines();
+    let status_line = lines
+        .next()
+        .ok_or_else(|| "Upstream response was missing a status line.".to_string())?;
+    let status = status_line
+        .split_once(' ')
+        .map(|(_, status)| status.trim().to_string())
+        .filter(|status| !status.is_empty())
+        .ok_or_else(|| "Upstream response status line was malformed.".to_string())?;
+    let content_type = lines
+        .find_map(|line| {
+            let (name, value) = line.split_once(':')?;
+            if name.trim().eq_ignore_ascii_case("content-type") {
+                Some(value.trim().to_string())
+            } else {
+                None
+            }
+        })
+        .unwrap_or_else(|| "application/json; charset=utf-8".to_string());
+
+    Ok((status, content_type, body.to_vec()))
+}
+
+/// Proxy dashboard-origin HTTP requests for session tabs or status to the loopback session server.
+async fn proxy_session_http_route(
+    port: u16,
+    endpoint: SessionProxyEndpoint,
+) -> Result<(String, String, Vec<u8>), DashboardProxyError> {
+    debug_assert!(matches!(
+        endpoint,
+        SessionProxyEndpoint::Tabs | SessionProxyEndpoint::Status
+    ));
+
+    require_active_session_port(port)?;
+
+    let upstream_path = match endpoint {
+        SessionProxyEndpoint::Tabs => "/api/tabs",
+        SessionProxyEndpoint::Status => "/api/status",
+        SessionProxyEndpoint::Stream => unreachable!("stream routes use the WebSocket proxy"),
+    };
+    let request = format!(
+        "GET {upstream_path} HTTP/1.1\r\nHost: 127.0.0.1:{port}\r\nConnection: close\r\n\r\n"
+    );
+
+    tokio::time::timeout(PROXY_TIMEOUT, async {
+        let mut upstream = tokio::net::TcpStream::connect(("127.0.0.1", port))
+            .await
+            .map_err(|e| {
+                DashboardProxyError::bad_gateway(format!(
+                    "Failed to connect to session {port}: {e}"
+                ))
+            })?;
+        upstream.write_all(request.as_bytes()).await.map_err(|e| {
+            DashboardProxyError::bad_gateway(format!(
+                "Failed to proxy request to session {port}: {e}"
+            ))
+        })?;
+
+        let mut response = Vec::new();
+        (&mut upstream)
+            .take(PROXY_MAX_RESPONSE_SIZE + 1)
+            .read_to_end(&mut response)
+            .await
+            .map_err(|e| {
+                DashboardProxyError::bad_gateway(format!(
+                    "Failed to read session {port} response: {e}"
+                ))
+            })?;
+        if response.len() as u64 > PROXY_MAX_RESPONSE_SIZE {
+            return Err(DashboardProxyError::bad_gateway(format!(
+                "Session {port} response exceeded {PROXY_MAX_RESPONSE_SIZE} bytes."
+            )));
+        }
+
+        parse_upstream_http_response(&response).map_err(DashboardProxyError::bad_gateway)
+    })
+    .await
+    .map_err(|_| {
+        DashboardProxyError::bad_gateway(format!(
+            "Session {port} proxy request timed out after {}s.",
+            PROXY_TIMEOUT.as_secs()
+        ))
+    })?
+}
+
+/// Bridge a dashboard-origin WebSocket upgrade to the loopback session stream.
+async fn proxy_session_stream(mut stream: tokio::net::TcpStream, port: u16) {
+    let upstream_url = format!("ws://127.0.0.1:{port}");
+    let (upstream_ws, _) = match tokio_tungstenite::connect_async(&upstream_url).await {
+        Ok(ws) => ws,
+        Err(error) => {
+            write_json_error_response_no_cors(
+                &mut stream,
+                "502 Bad Gateway",
+                &format!("Failed to connect to session {port}: {error}"),
+            )
+            .await;
+            return;
+        }
+    };
+    let client_ws = match tokio_tungstenite::accept_async(stream).await {
+        Ok(ws) => ws,
+        Err(_) => return,
+    };
+
+    let (mut client_tx, mut client_rx) = client_ws.split();
+    let (mut upstream_tx, mut upstream_rx) = upstream_ws.split();
+
+    loop {
+        tokio::select! {
+            message = client_rx.next() => {
+                match message {
+                    Some(Ok(message)) => {
+                        let is_close = matches!(message, Message::Close(_));
+                        if upstream_tx.send(message).await.is_err() {
+                            break;
+                        }
+                        if is_close {
+                            break;
+                        }
+                    }
+                    Some(Err(_)) | None => {
+                        let _ = upstream_tx.send(Message::Close(None)).await;
+                        break;
+                    }
+                }
+            }
+            message = upstream_rx.next() => {
+                match message {
+                    Some(Ok(message)) => {
+                        let is_close = matches!(message, Message::Close(_));
+                        if client_tx.send(message).await.is_err() {
+                            break;
+                        }
+                        if is_close {
+                            break;
+                        }
+                    }
+                    Some(Err(_)) | None => {
+                        let _ = client_tx.send(Message::Close(None)).await;
+                        break;
+                    }
+                }
+            }
+        }
+    }
+}
+
+pub async fn run_dashboard_server(port: u16) {
+    let addr = format!("127.0.0.1:{}", port);
+    let listener = match TcpListener::bind(&addr).await {
+        Ok(l) => l,
+        Err(e) => {
+            eprintln!("Failed to bind dashboard server on {}: {}", addr, e);
+            return;
+        }
+    };
+
+    loop {
+        let Ok((stream, _addr)) = listener.accept().await else {
+            break;
+        };
+        tokio::spawn(async move {
+            handle_dashboard_connection(stream).await;
+        });
+    }
+}
+
+async fn handle_dashboard_connection(mut stream: tokio::net::TcpStream) {
+    let mut buf = vec![0u8; 8192];
+    let peeked_len = match stream.peek(&mut buf).await {
+        Ok(n) if n > 0 => n,
+        _ => return,
+    };
+    let peeked_request = String::from_utf8_lossy(&buf[..peeked_len]);
+    let (peeked_method, peeked_path) = parse_request_method_and_path(&peeked_request);
+
+    if peeked_path.starts_with("/api/session/") {
+        let (port, endpoint) = match parse_session_proxy_route(peeked_path) {
+            Ok(route) => route,
+            Err(error) => {
+                write_json_error_response_no_cors(&mut stream, "400 Bad Request", error).await;
+                return;
+            }
+        };
+
+        match endpoint {
+            SessionProxyEndpoint::Stream => {
+                if peeked_method != "GET" {
+                    write_json_error_response_no_cors(
+                        &mut stream,
+                        "400 Bad Request",
+                        "Session stream proxy only supports GET WebSocket upgrades.",
+                    )
+                    .await;
+                    return;
+                }
+                if !is_websocket_upgrade(&peeked_request) {
+                    write_json_error_response_no_cors(
+                        &mut stream,
+                        "400 Bad Request",
+                        "Session stream proxy requires a WebSocket upgrade request.",
+                    )
+                    .await;
+                    return;
+                }
+                if !is_same_origin_ws_request(&peeked_request) {
+                    write_json_error_response_no_cors(
+                        &mut stream,
+                        "403 Forbidden",
+                        "Origin does not match Host header.",
+                    )
+                    .await;
+                    return;
+                }
+                if let Err(error) = require_active_session_port(port) {
+                    write_json_error_response_no_cors(&mut stream, error.status, &error.message)
+                        .await;
+                    return;
+                }
+                proxy_session_stream(stream, port).await;
+                return;
+            }
+            SessionProxyEndpoint::Tabs | SessionProxyEndpoint::Status => {
+                if peeked_method != "GET" {
+                    write_json_error_response_no_cors(
+                        &mut stream,
+                        "400 Bad Request",
+                        "Session proxy routes only support GET requests.",
+                    )
+                    .await;
+                    return;
+                }
+            }
+        }
+    }
+
+    let n = match stream.read(&mut buf).await {
+        Ok(n) if n > 0 => n,
+        _ => return,
+    };
+
+    let request = String::from_utf8_lossy(&buf[..n]).to_string();
+    let (method, path) = parse_request_method_and_path(&request);
+    let origin = request_header_value(&request, "origin").map(|value| value.to_string());
+
+    if method == "OPTIONS" {
+        let response = format!(
+            "HTTP/1.1 204 No Content\r\n{CORS_HEADERS}Access-Control-Max-Age: 86400\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
+        );
+        let _ = stream.write_all(response.as_bytes()).await;
+        return;
+    }
+
+    if method == "POST" && path == "/api/chat" {
+        let body_str = read_post_body(&mut stream, &buf, n).await;
+        handle_chat_request(&mut stream, &body_str, origin.as_deref()).await;
+        return;
+    }
+
+    if method == "GET" && path == "/api/models" {
+        handle_models_request(&mut stream, origin.as_deref()).await;
+        return;
+    }
+
+    if method == "POST" && (path == "/api/sessions" || path == "/api/exec" || path == "/api/kill") {
+        let body_str = read_post_body(&mut stream, &buf, n).await;
+        let result = if path == "/api/exec" {
+            exec_cli(&body_str).await
+        } else if path == "/api/kill" {
+            kill_session(&body_str).await
+        } else {
+            spawn_session(&body_str).await
+        };
+        let (status, resp_body) = match result {
+            Ok(msg) => ("200 OK", msg),
+            Err(e) => ("400 Bad Request", build_json_error_body(&e)),
+        };
+        write_http_response(
+            &mut stream,
+            status,
+            "application/json; charset=utf-8",
+            resp_body.as_bytes(),
+        )
+        .await;
+        return;
+    }
+
+    if path.starts_with("/api/session/") {
+        let (port, endpoint) = match parse_session_proxy_route(path) {
+            Ok(route) => route,
+            Err(error) => {
+                write_json_error_response_no_cors(&mut stream, "400 Bad Request", error).await;
+                return;
+            }
+        };
+
+        match endpoint {
+            SessionProxyEndpoint::Tabs | SessionProxyEndpoint::Status => {
+                if !is_same_origin_http_request(&request) {
+                    write_json_error_response_no_cors(
+                        &mut stream,
+                        "403 Forbidden",
+                        "Origin or Referer does not match Host header.",
+                    )
+                    .await;
+                    return;
+                }
+
+                match proxy_session_http_route(port, endpoint).await {
+                    Ok((status, content_type, body)) => {
+                        write_http_response_no_cors(&mut stream, &status, &content_type, &body)
+                            .await;
+                    }
+                    Err(error) => {
+                        write_json_error_response_no_cors(
+                            &mut stream,
+                            error.status,
+                            &error.message,
+                        )
+                        .await;
+                    }
+                }
+                return;
+            }
+            SessionProxyEndpoint::Stream => {
+                write_json_error_response_no_cors(
+                    &mut stream,
+                    "400 Bad Request",
+                    "Session stream proxy requires a WebSocket upgrade request.",
+                )
+                .await;
+                return;
+            }
+        }
+    }
+
+    let (status, content_type, body): (&str, &str, Vec<u8>) = if path == "/api/sessions" {
+        (
+            "200 OK",
+            "application/json; charset=utf-8",
+            discover_sessions().into_bytes(),
+        )
+    } else if path == "/api/chat/status" {
+        (
+            "200 OK",
+            "application/json; charset=utf-8",
+            chat_status_json().into_bytes(),
+        )
+    } else {
+        serve_embedded_file(path)
+    };
+
+    write_http_response(&mut stream, status, content_type, &body).await;
+}
+
+async fn read_post_body(stream: &mut tokio::net::TcpStream, initial: &[u8], n: usize) -> String {
+    let header_end = initial[..n]
+        .windows(4)
+        .position(|w| w == b"\r\n\r\n")
+        .map(|p| p + 4)
+        .or_else(|| {
+            initial[..n]
+                .windows(2)
+                .position(|w| w == b"\n\n")
+                .map(|p| p + 2)
+        });
+    let Some(header_end) = header_end else {
+        return String::new();
+    };
+
+    let header_str = String::from_utf8_lossy(&initial[..header_end]);
+    let content_length: usize = header_str
+        .lines()
+        .find_map(|l| {
+            if l.len() > 16 && l[..16].eq_ignore_ascii_case("content-length: ") {
+                l[16..].trim().parse::<usize>().ok()
+            } else {
+                let lower = l.to_lowercase();
+                lower
+                    .strip_prefix("content-length:")
+                    .and_then(|v| v.trim().parse::<usize>().ok())
+            }
+        })
+        .unwrap_or(0);
+
+    if content_length == 0 {
+        return String::new();
+    }
+
+    let read_body = &initial[header_end..n];
+    let already_read = read_body.len().min(content_length);
+
+    let mut body = Vec::with_capacity(content_length);
+    body.extend_from_slice(&read_body[..already_read]);
+
+    let remaining = content_length - already_read;
+    if remaining > 0 {
+        let mut rest = vec![0u8; remaining];
+        if stream.read_exact(&mut rest).await.is_ok() {
+            body.extend_from_slice(&rest);
+        }
+    }
+
+    String::from_utf8(body).unwrap_or_default()
+}
+
+async fn exec_cli(body: &str) -> Result<String, String> {
+    let parsed: Value = serde_json::from_str(body).map_err(|e| format!("Invalid JSON: {}", e))?;
+    let args: Vec<String> = parsed
+        .get("args")
+        .and_then(|v| v.as_array())
+        .ok_or("Missing \"args\" array")?
+        .iter()
+        .filter_map(|v| v.as_str().map(|s| s.to_string()))
+        .collect();
+
+    if args.is_empty() {
+        return Err("Empty args array".to_string());
+    }
+
+    let exe = std::env::current_exe().map_err(|e| format!("Cannot resolve executable: {}", e))?;
+
+    let mut cmd = tokio::process::Command::new(&exe);
+    cmd.args(&args)
+        .arg("--json")
+        .env_remove("AGENT_BROWSER_DASHBOARD")
+        .env_remove("AGENT_BROWSER_DASHBOARD_PORT")
+        .env_remove("AGENT_BROWSER_STREAM_PORT");
+
+    let output = cmd
+        .output()
+        .await
+        .map_err(|e| format!("Failed to execute: {}", e))?;
+
+    let stdout = String::from_utf8_lossy(&output.stdout).trim().to_string();
+    let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
+
+    Ok(json!({
+        "success": output.status.success(),
+        "exit_code": output.status.code(),
+        "stdout": stdout,
+        "stderr": stderr,
+    })
+    .to_string())
+}
+
+async fn kill_session(body: &str) -> Result<String, String> {
+    let parsed: Value = serde_json::from_str(body).map_err(|e| format!("Invalid JSON: {}", e))?;
+    let session = parsed
+        .get("session")
+        .and_then(|v| v.as_str())
+        .ok_or("Missing \"session\" field")?;
+
+    if session.is_empty() || session.len() > 64 {
+        return Err("Session name must be 1-64 characters".to_string());
+    }
+
+    let dir = get_socket_dir();
+    let pid_path = dir.join(format!("{}.pid", session));
+
+    let pid_str = std::fs::read_to_string(&pid_path)
+        .map_err(|_| format!("No PID file for session '{}'", session))?;
+    let pid: u32 = pid_str
+        .trim()
+        .parse()
+        .map_err(|_| format!("Invalid PID in file: {}", pid_str.trim()))?;
+
+    #[cfg(unix)]
+    {
+        // SAFETY: The PID came from the daemon-managed pidfile and is only used
+        // to send standard termination signals to that process.
+        unsafe {
+            libc::kill(pid as i32, libc::SIGTERM);
+        }
+        tokio::time::sleep(std::time::Duration::from_millis(500)).await;
+        // SAFETY: A signal value of 0 performs an existence check on the same pid.
+        if unsafe { libc::kill(pid as i32, 0) } == 0 {
+            // SAFETY: The process still exists after SIGTERM, so escalate to SIGKILL.
+            unsafe {
+                libc::kill(pid as i32, libc::SIGKILL);
+            }
+        }
+    }
+
+    for ext in &["pid", "sock", "stream", "engine", "extensions"] {
+        let _ = std::fs::remove_file(dir.join(format!("{}.{}", session, ext)));
+    }
+
+    Ok(json!({ "success": true, "killed_pid": pid }).to_string())
+}
+
+pub(super) async fn spawn_session(body: &str) -> Result<String, String> {
+    let parsed: Value = serde_json::from_str(body).map_err(|e| format!("Invalid JSON: {}", e))?;
+    let session = parsed
+        .get("session")
+        .and_then(|v| v.as_str())
+        .ok_or("Missing \"session\" field")?;
+
+    if session.is_empty() || session.len() > 64 {
+        return Err("Session name must be 1-64 characters".to_string());
+    }
+
+    let exe = std::env::current_exe().map_err(|e| format!("Cannot resolve executable: {}", e))?;
+
+    let mut cmd = tokio::process::Command::new(&exe);
+    cmd.arg("open")
+        .arg("about:blank")
+        .arg("--session")
+        .arg(session);
+
+    cmd.stdout(std::process::Stdio::null());
+    cmd.stderr(std::process::Stdio::null());
+
+    let status = cmd
+        .status()
+        .await
+        .map_err(|e| format!("Failed to spawn session: {}", e))?;
+
+    if status.success() {
+        Ok(format!(
+            r#"{{"success":true,"session":{}}}"#,
+            serde_json::to_string(session).unwrap_or_default()
+        ))
+    } else {
+        Err(format!("Session process exited with {}", status))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_same_origin_ws_request_matching() {
+        let req = "GET /api/session/9222/stream HTTP/1.1\r\nHost: localhost:4848\r\nOrigin: http://localhost:4848\r\nUpgrade: websocket\r\n\r\n";
+        assert!(is_same_origin_ws_request(req));
+    }
+
+    #[test]
+    fn test_same_origin_ws_request_proxied() {
+        let req = "GET /api/session/9222/stream HTTP/1.1\r\nHost: dashboard.agent-browser.localhost\r\nOrigin: https://dashboard.agent-browser.localhost\r\nUpgrade: websocket\r\n\r\n";
+        assert!(is_same_origin_ws_request(req));
+    }
+
+    #[test]
+    fn test_normalize_origin_authority_https_without_port() {
+        assert_eq!(
+            normalize_origin_authority("https://dashboard.agent-browser.localhost"),
+            Some("dashboard.agent-browser.localhost".to_string())
+        );
+    }
+
+    #[test]
+    fn test_same_origin_ws_request_default_https_port() {
+        let req = "GET /api/session/9222/stream HTTP/1.1\r\nHost: dashboard.agent-browser.localhost:443\r\nOrigin: https://dashboard.agent-browser.localhost\r\nUpgrade: websocket\r\n\r\n";
+        assert!(is_same_origin_ws_request(req));
+    }
+
+    #[test]
+    fn test_same_origin_http_request_matching_origin() {
+        let req = "GET /api/session/9222/tabs HTTP/1.1\r\nHost: localhost:4848\r\nOrigin: http://localhost:4848\r\n\r\n";
+        assert!(is_same_origin_http_request(req));
+    }
+
+    #[test]
+    fn test_same_origin_http_request_matching_referer() {
+        let req = "GET /api/session/9222/tabs HTTP/1.1\r\nHost: dashboard.agent-browser.localhost:443\r\nReferer: https://dashboard.agent-browser.localhost/sessions\r\n\r\n";
+        assert!(is_same_origin_http_request(req));
+    }
+
+    #[test]
+    fn test_same_origin_http_request_rejects_missing_origin_and_referer() {
+        let req = "GET /api/session/9222/tabs HTTP/1.1\r\nHost: localhost:4848\r\n\r\n";
+        assert!(!is_same_origin_http_request(req));
+    }
+
+    #[test]
+    fn test_same_origin_http_request_rejects_cross_origin_referer() {
+        let req = "GET /api/session/9222/tabs HTTP/1.1\r\nHost: localhost:4848\r\nReferer: https://evil.com/path\r\n\r\n";
+        assert!(!is_same_origin_http_request(req));
+    }
+
+    #[test]
+    fn test_same_origin_ws_request_coder() {
+        let req = "GET /api/session/9222/stream HTTP/1.1\r\nHost: workspace.coder.com\r\nOrigin: https://workspace.coder.com\r\nUpgrade: websocket\r\n\r\n";
+        assert!(is_same_origin_ws_request(req));
+    }
+
+    #[test]
+    fn test_cross_origin_ws_request_rejected() {
+        let req = "GET /api/session/9222/stream HTTP/1.1\r\nHost: localhost:4848\r\nOrigin: https://evil.com\r\nUpgrade: websocket\r\n\r\n";
+        assert!(!is_same_origin_ws_request(req));
+    }
+
+    #[test]
+    fn test_no_origin_header_allowed() {
+        let req = "GET /api/session/9222/stream HTTP/1.1\r\nHost: localhost:4848\r\nUpgrade: websocket\r\n\r\n";
+        assert!(is_same_origin_ws_request(req));
+    }
+
+    #[test]
+    fn test_parse_session_proxy_route_valid() {
+        assert_eq!(
+            parse_session_proxy_route("/api/session/9222/tabs"),
+            Ok((9222, SessionProxyEndpoint::Tabs))
+        );
+        assert_eq!(
+            parse_session_proxy_route("/api/session/1337/status"),
+            Ok((1337, SessionProxyEndpoint::Status))
+        );
+        assert_eq!(
+            parse_session_proxy_route("/api/session/65535/stream"),
+            Ok((65535, SessionProxyEndpoint::Stream))
+        );
+    }
+
+    #[test]
+    fn test_parse_session_proxy_route_invalid() {
+        assert!(parse_session_proxy_route("/api/session/0/tabs").is_err());
+        assert!(parse_session_proxy_route("/api/session/not-a-port/tabs").is_err());
+        assert!(parse_session_proxy_route("/api/session/70000/tabs").is_err());
+        assert!(parse_session_proxy_route("/api/session/9222").is_err());
+        assert!(parse_session_proxy_route("/api/session/9222/unknown").is_err());
+        assert!(parse_session_proxy_route("/api/session/9222/tabs/extra").is_err());
+    }
+
+    #[test]
+    fn test_parse_session_proxy_route_path_traversal() {
+        assert!(parse_session_proxy_route("/api/session/9222/tabs/..").is_err());
+        assert!(parse_session_proxy_route("/api/session/9222/tabs/../status").is_err());
+        assert!(parse_session_proxy_route("/api/session/9222/../../etc/passwd").is_err());
+        assert!(parse_session_proxy_route("/api/session/../session/9222/tabs").is_err());
+    }
+
+    #[test]
+    fn test_parse_session_proxy_route_double_slashes() {
+        assert!(parse_session_proxy_route("/api/session//9222/tabs").is_err());
+        assert!(parse_session_proxy_route("/api//session/9222/tabs").is_err());
+        assert!(parse_session_proxy_route("//api/session/9222/tabs").is_err());
+    }
+
+    #[test]
+    fn test_parse_session_proxy_route_trailing_slash() {
+        assert!(parse_session_proxy_route("/api/session/9222/tabs/").is_err());
+        assert!(parse_session_proxy_route("/api/session/9222/status/").is_err());
+        assert!(parse_session_proxy_route("/api/session/9222/stream/").is_err());
+    }
+
+    #[test]
+    fn test_parse_session_proxy_route_encoded_paths() {
+        assert!(parse_session_proxy_route("/api/session/9222/tabs%20extra").is_err());
+        assert!(parse_session_proxy_route("/api/session/%39%32%32%32/tabs").is_err());
+    }
+
+    #[test]
+    fn test_sessions_json_has_active_port() {
+        let sessions_json = r#"[
+            {"session":"alpha","port":9222,"engine":"chrome"},
+            {"session":"beta","port":9333,"engine":"chrome"}
+        ]"#;
+
+        assert_eq!(sessions_json_has_active_port(sessions_json, 9222), Ok(true));
+        assert_eq!(
+            sessions_json_has_active_port(sessions_json, 9444),
+            Ok(false)
+        );
+    }
+
+    #[test]
+    fn test_sessions_json_has_active_port_invalid_json() {
+        assert!(sessions_json_has_active_port("{", 9222).is_err());
+    }
+
+    #[test]
+    fn test_parse_upstream_http_response() {
+        let response = b"HTTP/1.1 200 OK\r\nContent-Type: application/json; charset=utf-8\r\nConnection: close\r\n\r\n{\"ok\":true}";
+        let parsed = parse_upstream_http_response(response).expect("response should parse");
+
+        assert_eq!(parsed.0, "200 OK");
+        assert_eq!(parsed.1, "application/json; charset=utf-8");
+        assert_eq!(parsed.2, b"{\"ok\":true}".to_vec());
+    }
+}

cli/src/native/stream/discovery.rs

@@ -0,0 +1,118 @@
+use serde_json::{json, Value};
+use std::path::Path;
+
+use crate::connection::get_socket_dir;
+
+pub(super) fn discover_sessions() -> String {
+    let dir = get_socket_dir();
+    let mut sessions = Vec::new();
+
+    if let Ok(entries) = std::fs::read_dir(&dir) {
+        for entry in entries.flatten() {
+            let name = entry.file_name();
+            let name_str = name.to_string_lossy();
+            if let Some(session) = name_str.strip_suffix(".stream") {
+                if let Ok(port_str) = std::fs::read_to_string(entry.path()) {
+                    if let Ok(port) = port_str.trim().parse::<u16>() {
+                        let pid_path = dir.join(format!("{}.pid", session));
+                        if is_process_alive(&pid_path) {
+                            let engine_path = dir.join(format!("{}.engine", session));
+                            let engine = std::fs::read_to_string(&engine_path)
+                                .ok()
+                                .filter(|s| !s.trim().is_empty())
+                                .unwrap_or_else(|| "chrome".to_string());
+
+                            let provider_path = dir.join(format!("{}.provider", session));
+                            let provider = std::fs::read_to_string(&provider_path)
+                                .ok()
+                                .filter(|s| !s.trim().is_empty());
+
+                            let extensions = read_extensions_metadata(&dir, session);
+
+                            let mut entry = json!({
+                                "session": session,
+                                "port": port,
+                                "engine": engine.trim(),
+                            });
+                            if let Some(ref p) = provider {
+                                entry["provider"] = json!(p.trim());
+                            }
+                            if !extensions.is_empty() {
+                                entry["extensions"] = json!(extensions);
+                            }
+                            sessions.push(entry);
+                        } else {
+                            let _ = std::fs::remove_file(entry.path());
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    serde_json::to_string(&sessions).unwrap_or_else(|_| "[]".to_string())
+}
+
+fn read_extensions_metadata(dir: &std::path::Path, session: &str) -> Vec<Value> {
+    let ext_path = dir.join(format!("{}.extensions", session));
+    let ext_str = match std::fs::read_to_string(&ext_path) {
+        Ok(s) => s,
+        Err(_) => return Vec::new(),
+    };
+
+    ext_str
+        .split(',')
+        .map(|p| p.trim())
+        .filter(|p| !p.is_empty())
+        .filter_map(|path| {
+            let manifest_path = std::path::Path::new(path).join("manifest.json");
+            let manifest_str = std::fs::read_to_string(&manifest_path).ok()?;
+            let manifest: Value = serde_json::from_str(&manifest_str).ok()?;
+
+            let name = manifest
+                .get("name")
+                .and_then(|v| v.as_str())
+                .unwrap_or("Unknown")
+                .to_string();
+            let version = manifest
+                .get("version")
+                .and_then(|v| v.as_str())
+                .unwrap_or("")
+                .to_string();
+            let description = manifest
+                .get("description")
+                .and_then(|v| v.as_str())
+                .map(|s| s.to_string());
+
+            let mut ext = json!({
+                "name": name,
+                "version": version,
+                "path": path,
+            });
+            if let Some(desc) = description {
+                ext["description"] = json!(desc);
+            }
+            Some(ext)
+        })
+        .collect()
+}
+
+fn is_process_alive(pid_path: &Path) -> bool {
+    let pid_str = match std::fs::read_to_string(pid_path) {
+        Ok(s) => s,
+        Err(_) => return false,
+    };
+    let pid: u32 = match pid_str.trim().parse() {
+        Ok(p) => p,
+        Err(_) => return false,
+    };
+    #[cfg(unix)]
+    {
+        unsafe { libc::kill(pid as i32, 0) == 0 }
+    }
+    #[cfg(not(unix))]
+    {
+        let _ = pid;
+        true
+    }
+}

cli/src/native/stream/http.rs

@@ -0,0 +1,715 @@
+use rust_embed::Embed;
+use serde_json::{json, Value};
+use std::sync::Arc;
+
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::sync::RwLock;
+
+use crate::connection::get_socket_dir;
+#[cfg(windows)]
+use crate::connection::resolve_port;
+
+use super::chat::{chat_status_json, handle_chat_request, handle_models_request};
+use super::dashboard::spawn_session;
+use super::discovery::discover_sessions;
+
+#[derive(Embed)]
+#[folder = "../packages/dashboard/out/"]
+struct DashboardAssets;
+
+pub(super) const CORS_HEADERS: &str = "Access-Control-Allow-Origin: *\r\nAccess-Control-Allow-Methods: GET, POST, OPTIONS\r\nAccess-Control-Allow-Headers: Content-Type\r\n";
+
+/// Build CORS headers that reflect the request origin only when it passes
+/// `is_allowed_origin`. Used for sensitive endpoints (chat, models) so the
+/// API key is not accessible from arbitrary web pages.
+pub(super) fn cors_headers_for_origin(origin: Option<&str>) -> String {
+    let allowed_origin = match origin {
+        Some(o) if super::is_allowed_origin(Some(o)) => o,
+        _ => "http://localhost",
+    };
+    format!(
+        "Access-Control-Allow-Origin: {}\r\nAccess-Control-Allow-Methods: GET, POST, OPTIONS\r\nAccess-Control-Allow-Headers: Content-Type\r\n",
+        allowed_origin
+    )
+}
+
+fn request_headers(request: &str) -> &str {
+    request
+        .find("\r\n\r\n")
+        .or_else(|| request.find("\n\n"))
+        .map(|header_end| &request[..header_end])
+        .unwrap_or(request)
+}
+
+fn request_header_value<'a>(request: &'a str, name: &str) -> Option<&'a str> {
+    request_headers(request).lines().find_map(|line| {
+        let (header_name, value) = line.split_once(':')?;
+        if header_name.trim().eq_ignore_ascii_case(name) {
+            Some(value.trim())
+        } else {
+            None
+        }
+    })
+}
+
+fn parse_origin(peeked: &[u8]) -> Option<String> {
+    let header_str = std::str::from_utf8(peeked).ok()?;
+    request_header_value(header_str, "origin").map(ToString::to_string)
+}
+
+fn normalize_origin_authority(origin: &str) -> Option<String> {
+    let url = url::Url::parse(origin).ok()?;
+    let host = url.host_str()?.to_ascii_lowercase();
+    let host = if host.contains(':') {
+        format!("[{host}]")
+    } else {
+        host
+    };
+    let default_port = (url.scheme() == "http" && url.port() == Some(80))
+        || (url.scheme() == "https" && url.port() == Some(443));
+    Some(match url.port() {
+        Some(port) if !default_port => format!("{host}:{port}"),
+        _ => host,
+    })
+}
+
+fn normalize_host_authority(host: &str) -> String {
+    let host = host.trim().to_ascii_lowercase();
+
+    if let Some(bracket_end) = host.rfind(']') {
+        if bracket_end == host.len() - 1 {
+            return host;
+        }
+
+        if host.as_bytes().get(bracket_end + 1) == Some(&b':') {
+            let port = &host[bracket_end + 2..];
+            if port == "80" || port == "443" {
+                return host[..=bracket_end].to_string();
+            }
+        }
+
+        return host;
+    }
+
+    if let Some((name, port)) = host.rsplit_once(':') {
+        if !name.contains(':') && (port == "80" || port == "443") {
+            return name.to_string();
+        }
+    }
+
+    host
+}
+
+fn authority_host(authority: &str) -> &str {
+    if let Some(stripped) = authority.strip_prefix('[') {
+        if let Some(bracket_end) = stripped.find(']') {
+            return &authority[..=bracket_end + 1];
+        }
+    }
+
+    if let Some((host, _port)) = authority.rsplit_once(':') {
+        if !host.contains(':') {
+            return host;
+        }
+    }
+
+    authority
+}
+
+fn is_loopback_authority(authority: &str) -> bool {
+    matches!(
+        authority_host(authority),
+        "localhost" | "127.0.0.1" | "::1" | "[::1]"
+    )
+}
+
+fn header_authority_matches_host(request: &str, header_name: &str) -> bool {
+    let Some(authority) =
+        request_header_value(request, header_name).and_then(normalize_origin_authority)
+    else {
+        return false;
+    };
+    let Some(host) = request_header_value(request, "host").map(normalize_host_authority) else {
+        return false;
+    };
+    authority == host && is_loopback_authority(&authority) && is_loopback_authority(&host)
+}
+
+/// Protects the command relay by requiring same-origin browser metadata.
+fn is_same_origin_command_request(request: &str) -> bool {
+    if request_header_value(request, "origin").is_some() {
+        header_authority_matches_host(request, "origin")
+    } else {
+        header_authority_matches_host(request, "referer")
+    }
+}
+
+fn command_cors_headers(request: &str) -> String {
+    match request_header_value(request, "origin") {
+        Some(origin) if is_same_origin_command_request(request) => format!(
+            "Access-Control-Allow-Origin: {origin}\r\nAccess-Control-Allow-Methods: POST, OPTIONS\r\nAccess-Control-Allow-Headers: Content-Type\r\nVary: Origin\r\n"
+        ),
+        _ => String::new(),
+    }
+}
+
+async fn write_json_error_response_no_cors(
+    stream: &mut tokio::net::TcpStream,
+    status: &str,
+    error: &str,
+) {
+    let body = format!(
+        r#"{{"success":false,"error":{}}}"#,
+        serde_json::to_string(error).unwrap_or_else(|_| format!("\"{}\"", error))
+    );
+    let response = format!(
+        "HTTP/1.1 {status}\r\nContent-Type: application/json; charset=utf-8\r\nContent-Length: {}\r\nConnection: close\r\n\r\n",
+        body.len()
+    );
+    let _ = stream.write_all(response.as_bytes()).await;
+    let _ = stream.write_all(body.as_bytes()).await;
+}
+
+pub(super) async fn handle_http_request(
+    mut stream: tokio::net::TcpStream,
+    peeked: &[u8],
+    last_tabs: &Arc<RwLock<Vec<Value>>>,
+    last_engine: &Arc<RwLock<String>>,
+    session_name: &str,
+) {
+    let peeked_len = peeked.len();
+    let mut discard = vec![0u8; peeked_len];
+    let _ = stream.read_exact(&mut discard).await;
+
+    let request = String::from_utf8_lossy(peeked);
+    let first_line = request.lines().next().unwrap_or("");
+    let method = first_line.split_whitespace().next().unwrap_or("GET");
+    let path = first_line.split_whitespace().nth(1).unwrap_or("/");
+    let origin = parse_origin(peeked);
+
+    if method == "OPTIONS" {
+        if path == "/api/command" {
+            if !is_same_origin_command_request(&request) {
+                write_json_error_response_no_cors(
+                    &mut stream,
+                    "403 Forbidden",
+                    "Origin or Referer does not match Host header.",
+                )
+                .await;
+                return;
+            }
+
+            let cors_headers = command_cors_headers(&request);
+            let response = format!(
+                "HTTP/1.1 204 No Content\r\n{cors_headers}Access-Control-Max-Age: 86400\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
+            );
+            let _ = stream.write_all(response.as_bytes()).await;
+            return;
+        }
+
+        let response = format!(
+            "HTTP/1.1 204 No Content\r\n{CORS_HEADERS}Access-Control-Max-Age: 86400\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
+        );
+        let _ = stream.write_all(response.as_bytes()).await;
+        return;
+    }
+
+    if method == "POST" {
+        if path == "/api/command" && !is_same_origin_command_request(&request) {
+            write_json_error_response_no_cors(
+                &mut stream,
+                "403 Forbidden",
+                "Origin or Referer does not match Host header.",
+            )
+            .await;
+            return;
+        }
+
+        let full_body = read_full_body(&mut stream, peeked).await;
+        if full_body.is_none()
+            && (path == "/api/chat" || path == "/api/sessions" || path == "/api/command")
+        {
+            let body = r#"{"error":"Request body too large"}"#;
+            let cors_headers = if path == "/api/command" {
+                command_cors_headers(&request)
+            } else {
+                CORS_HEADERS.to_string()
+            };
+            let response = format!(
+                "HTTP/1.1 413 Payload Too Large\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n{cors_headers}\r\n",
+                body.len()
+            );
+            let _ = stream.write_all(response.as_bytes()).await;
+            let _ = stream.write_all(body.as_bytes()).await;
+            return;
+        }
+        let body_str = full_body.as_deref().unwrap_or("");
+
+        if path == "/api/sessions" {
+            let result = spawn_session(body_str).await;
+            let (status, resp_body) = match result {
+                Ok(msg) => ("200 OK", msg),
+                Err(e) => (
+                    "400 Bad Request",
+                    format!(
+                        r#"{{"success":false,"error":{}}}"#,
+                        serde_json::to_string(&e).unwrap_or_else(|_| format!("\"{}\"", e))
+                    ),
+                ),
+            };
+            let response = format!(
+                "HTTP/1.1 {status}\r\nContent-Type: application/json; charset=utf-8\r\nContent-Length: {}\r\nConnection: close\r\n{CORS_HEADERS}\r\n",
+                resp_body.len()
+            );
+            let _ = stream.write_all(response.as_bytes()).await;
+            let _ = stream.write_all(resp_body.as_bytes()).await;
+            return;
+        }
+
+        if path == "/api/command" {
+            let result = relay_command_to_daemon(session_name, body_str).await;
+            let (status, resp_body) = match result {
+                Ok(resp) => ("200 OK", resp),
+                Err(e) => (
+                    "502 Bad Gateway",
+                    format!(
+                        r#"{{"success":false,"error":{}}}"#,
+                        serde_json::to_string(&e).unwrap_or_else(|_| format!("\"{}\"", e))
+                    ),
+                ),
+            };
+            let cors_headers = command_cors_headers(&request);
+            let response = format!(
+                "HTTP/1.1 {status}\r\nContent-Type: application/json; charset=utf-8\r\nContent-Length: {}\r\nConnection: close\r\n{cors_headers}\r\n",
+                resp_body.len()
+            );
+            let _ = stream.write_all(response.as_bytes()).await;
+            let _ = stream.write_all(resp_body.as_bytes()).await;
+            return;
+        }
+
+        if path == "/api/chat" {
+            handle_chat_request(&mut stream, body_str, origin.as_deref()).await;
+            return;
+        }
+    }
+
+    if method == "GET" && path == "/api/models" {
+        handle_models_request(&mut stream, origin.as_deref()).await;
+        return;
+    }
+
+    let (status, content_type, body): (&str, &str, Vec<u8>) = if path == "/api/sessions" {
+        (
+            "200 OK",
+            "application/json; charset=utf-8",
+            discover_sessions().into_bytes(),
+        )
+    } else if path == "/api/tabs" {
+        let tabs = last_tabs.read().await;
+        (
+            "200 OK",
+            "application/json; charset=utf-8",
+            serde_json::to_string(&*tabs)
+                .unwrap_or_else(|_| "[]".to_string())
+                .into_bytes(),
+        )
+    } else if path == "/api/status" {
+        let engine = last_engine.read().await;
+        (
+            "200 OK",
+            "application/json; charset=utf-8",
+            format!(r#"{{"engine":"{}"}}"#, *engine).into_bytes(),
+        )
+    } else if path == "/api/chat/status" {
+        (
+            "200 OK",
+            "application/json; charset=utf-8",
+            chat_status_json().into_bytes(),
+        )
+    } else {
+        serve_embedded_file(path)
+    };
+
+    let response = format!(
+        "HTTP/1.1 {}\r\nContent-Type: {}\r\nContent-Length: {}\r\nConnection: close\r\n{CORS_HEADERS}\r\n",
+        status,
+        content_type,
+        body.len()
+    );
+    let _ = stream.write_all(response.as_bytes()).await;
+    let _ = stream.write_all(&body).await;
+}
+
+fn find_header_end(buf: &[u8]) -> Option<usize> {
+    buf.windows(4)
+        .position(|w| w == b"\r\n\r\n")
+        .map(|p| p + 4)
+        .or_else(|| buf.windows(2).position(|w| w == b"\n\n").map(|p| p + 2))
+}
+
+fn parse_content_length_bytes(headers: &[u8]) -> Option<usize> {
+    let header_str = std::str::from_utf8(headers).ok()?;
+    for line in header_str.lines() {
+        if line.len() > 16 && line[..16].eq_ignore_ascii_case("content-length: ") {
+            return line[16..].trim().parse().ok();
+        }
+    }
+    None
+}
+
+const MAX_BODY_SIZE: usize = 10 * 1024 * 1024;
+
+async fn read_full_body(stream: &mut tokio::net::TcpStream, peeked: &[u8]) -> Option<String> {
+    let body_offset = find_header_end(peeked)?;
+    let content_length = parse_content_length_bytes(&peeked[..body_offset])?;
+    if content_length == 0 {
+        return Some(String::new());
+    }
+    if content_length > MAX_BODY_SIZE {
+        return None;
+    }
+
+    let peeked_body = &peeked[body_offset..];
+    let peeked_body_len = peeked_body.len().min(content_length);
+
+    let mut body = Vec::with_capacity(content_length);
+    body.extend_from_slice(&peeked_body[..peeked_body_len]);
+
+    let remaining = content_length - peeked_body_len;
+    if remaining > 0 {
+        let mut rest = vec![0u8; remaining];
+        if stream.read_exact(&mut rest).await.is_err() {
+            return String::from_utf8(body).ok();
+        }
+        body.extend_from_slice(&rest);
+    }
+
+    String::from_utf8(body).ok()
+}
+
+pub(super) async fn relay_command_to_daemon(
+    session_name: &str,
+    body: &str,
+) -> Result<String, String> {
+    let mut cmd: Value = serde_json::from_str(body).map_err(|e| format!("Invalid JSON: {}", e))?;
+
+    if cmd.get("id").is_none() {
+        let id = format!(
+            "dash-{}",
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap_or_default()
+                .as_millis()
+        );
+        cmd["id"] = json!(id);
+    }
+
+    let mut json_str = serde_json::to_string(&cmd).map_err(|e| e.to_string())?;
+    json_str.push('\n');
+
+    #[cfg(unix)]
+    let stream = {
+        let socket_path = get_socket_dir().join(format!("{}.sock", session_name));
+        tokio::net::UnixStream::connect(&socket_path)
+            .await
+            .map_err(|e| format!("Failed to connect to daemon: {}", e))?
+    };
+
+    #[cfg(windows)]
+    let stream = {
+        let port = resolve_port(session_name);
+        tokio::net::TcpStream::connect(format!("127.0.0.1:{}", port))
+            .await
+            .map_err(|e| format!("Failed to connect to daemon: {}", e))?
+    };
+
+    let (reader, mut writer) = tokio::io::split(stream);
+
+    writer
+        .write_all(json_str.as_bytes())
+        .await
+        .map_err(|e| format!("Failed to send command: {}", e))?;
+
+    let mut buf_reader = tokio::io::BufReader::new(reader);
+    let mut response_line = String::new();
+    tokio::io::AsyncBufReadExt::read_line(&mut buf_reader, &mut response_line)
+        .await
+        .map_err(|e| format!("Failed to read response: {}", e))?;
+
+    Ok(response_line.trim().to_string())
+}
+
+pub(super) fn serve_embedded_file(url_path: &str) -> (&'static str, &'static str, Vec<u8>) {
+    let clean = url_path.trim_start_matches('/');
+    let key = if clean.is_empty() {
+        "index.html"
+    } else {
+        clean
+    };
+
+    let file = DashboardAssets::get(key).or_else(|| DashboardAssets::get("index.html"));
+
+    match file {
+        Some(content) => {
+            let ext = key.rsplit('.').next().unwrap_or("");
+            let ct = match ext {
+                "html" => "text/html; charset=utf-8",
+                "js" => "application/javascript; charset=utf-8",
+                "css" => "text/css; charset=utf-8",
+                "json" => "application/json; charset=utf-8",
+                "svg" => "image/svg+xml",
+                "png" => "image/png",
+                "ico" => "image/x-icon",
+                "woff2" => "font/woff2",
+                "woff" => "font/woff",
+                "txt" => "text/plain; charset=utf-8",
+                _ => "application/octet-stream",
+            };
+            ("200 OK", ct, content.data.to_vec())
+        }
+        None => (
+            "404 Not Found",
+            "text/html; charset=utf-8",
+            b"<html><body><p>404 Not Found</p></body></html>".to_vec(),
+        ),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::test_utils::EnvGuard;
+    use std::sync::Arc;
+    use tokio::io::{AsyncBufReadExt, AsyncReadExt, AsyncWriteExt};
+    use tokio::net::TcpListener;
+    use tokio::sync::oneshot;
+
+    async fn send_request_to_handler(request: &str, session_name: &str) -> String {
+        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let addr = listener.local_addr().unwrap();
+        let peeked = request.as_bytes().to_vec();
+        let last_tabs = Arc::new(RwLock::new(Vec::new()));
+        let last_engine = Arc::new(RwLock::new("chrome".to_string()));
+        let session_name = session_name.to_string();
+
+        let server = tokio::spawn(async move {
+            let (stream, _) = listener.accept().await.unwrap();
+            handle_http_request(stream, &peeked, &last_tabs, &last_engine, &session_name).await;
+        });
+
+        let mut client = tokio::net::TcpStream::connect(addr).await.unwrap();
+        client.write_all(request.as_bytes()).await.unwrap();
+        client.shutdown().await.unwrap();
+
+        let mut response = Vec::new();
+        client.read_to_end(&mut response).await.unwrap();
+        server.await.unwrap();
+
+        String::from_utf8(response).unwrap()
+    }
+
+    #[cfg(unix)]
+    async fn spawn_fake_daemon(
+        socket_dir: &std::path::Path,
+        session_name: &str,
+    ) -> oneshot::Receiver<String> {
+        let socket_path = socket_dir.join(format!("{session_name}.sock"));
+        let _ = std::fs::remove_file(&socket_path);
+        let listener = tokio::net::UnixListener::bind(&socket_path).unwrap();
+        let (tx, rx) = oneshot::channel();
+
+        tokio::spawn(async move {
+            let (stream, _) = listener.accept().await.unwrap();
+            let mut reader = tokio::io::BufReader::new(stream);
+            let mut line = String::new();
+            reader.read_line(&mut line).await.unwrap();
+
+            let mut stream = reader.into_inner();
+            stream
+                .write_all(br#"{"success":true,"data":{"ok":true}}"#)
+                .await
+                .unwrap();
+            stream.write_all(b"\n").await.unwrap();
+            let _ = tx.send(line);
+        });
+
+        rx
+    }
+
+    #[cfg(unix)]
+    #[tokio::test(flavor = "current_thread")]
+    async fn cross_origin_command_post_is_rejected_without_relaying_to_daemon() {
+        let temp_parent = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+            .join("target")
+            .join("t");
+        std::fs::create_dir_all(&temp_parent).unwrap();
+        let socket_dir = tempfile::Builder::new()
+            .prefix("ab-")
+            .tempdir_in(temp_parent)
+            .unwrap();
+        let guard = EnvGuard::new(&["AGENT_BROWSER_SOCKET_DIR", "XDG_RUNTIME_DIR"]);
+        guard.set(
+            "AGENT_BROWSER_SOCKET_DIR",
+            socket_dir.path().to_str().unwrap(),
+        );
+        guard.remove("XDG_RUNTIME_DIR");
+
+        let session_name = "x";
+        let daemon_command = spawn_fake_daemon(socket_dir.path(), session_name).await;
+        let body = r#"{"action":"tabs"}"#;
+        let request = format!(
+            "POST /api/command HTTP/1.1\r\nHost: localhost:7777\r\nOrigin: https://evil.example\r\nContent-Type: application/json\r\nContent-Length: {}\r\n\r\n{}",
+            body.len(),
+            body
+        );
+
+        let response = send_request_to_handler(&request, session_name).await;
+
+        assert!(
+            response.starts_with("HTTP/1.1 403 Forbidden"),
+            "unexpected response: {response}"
+        );
+        assert!(
+            tokio::time::timeout(std::time::Duration::from_millis(50), daemon_command)
+                .await
+                .is_err(),
+            "cross-origin request reached daemon command relay"
+        );
+    }
+
+    #[tokio::test(flavor = "current_thread")]
+    async fn cross_origin_command_preflight_is_rejected_without_wildcard_cors() {
+        let request = concat!(
+            "OPTIONS /api/command HTTP/1.1\r\n",
+            "Host: localhost:7777\r\n",
+            "Origin: https://evil.example\r\n",
+            "Access-Control-Request-Method: POST\r\n",
+            "Access-Control-Request-Headers: content-type\r\n",
+            "\r\n"
+        );
+
+        let response = send_request_to_handler(request, "x").await;
+
+        assert!(
+            response.starts_with("HTTP/1.1 403 Forbidden"),
+            "unexpected response: {response}"
+        );
+        assert!(
+            !response.contains("Access-Control-Allow-Origin: *"),
+            "forbidden command preflight exposed wildcard CORS: {response}"
+        );
+    }
+
+    #[tokio::test(flavor = "current_thread")]
+    async fn command_post_without_origin_or_referer_is_rejected() {
+        let body = r#"{"action":"tabs"}"#;
+        let request = format!(
+            "POST /api/command HTTP/1.1\r\nHost: localhost:7777\r\nContent-Type: application/json\r\nContent-Length: {}\r\n\r\n{}",
+            body.len(),
+            body
+        );
+
+        let response = send_request_to_handler(&request, "x").await;
+
+        assert!(
+            response.starts_with("HTTP/1.1 403 Forbidden"),
+            "unexpected response: {response}"
+        );
+        assert!(
+            !response.contains("Access-Control-Allow-Origin: *"),
+            "forbidden command response exposed wildcard CORS: {response}"
+        );
+    }
+
+    #[tokio::test(flavor = "current_thread")]
+    async fn command_post_with_dns_rebinding_host_is_rejected() {
+        let body = r#"{"action":"tabs"}"#;
+        let request = format!(
+            "POST /api/command HTTP/1.1\r\nHost: attacker.example:7777\r\nOrigin: http://attacker.example:7777\r\nContent-Type: application/json\r\nContent-Length: {}\r\n\r\n{}",
+            body.len(),
+            body
+        );
+
+        let response = send_request_to_handler(&request, "x").await;
+
+        assert!(
+            response.starts_with("HTTP/1.1 403 Forbidden"),
+            "unexpected response: {response}"
+        );
+        assert!(
+            !response.contains("Access-Control-Allow-Origin: *"),
+            "forbidden command response exposed wildcard CORS: {response}"
+        );
+    }
+
+    #[tokio::test(flavor = "current_thread")]
+    async fn command_post_ignores_header_like_body_lines() {
+        let body = "Referer: http://localhost:7777\r\n{\"action\":\"tabs\"}";
+        let request = format!(
+            "POST /api/command HTTP/1.1\r\nHost: localhost:7777\r\nContent-Type: application/json\r\nContent-Length: {}\r\n\r\n{}",
+            body.len(),
+            body
+        );
+
+        let response = send_request_to_handler(&request, "x").await;
+
+        assert!(
+            response.starts_with("HTTP/1.1 403 Forbidden"),
+            "unexpected response: {response}"
+        );
+        assert!(
+            !response.contains("Access-Control-Allow-Origin: *"),
+            "forbidden command response exposed wildcard CORS: {response}"
+        );
+    }
+
+    #[cfg(unix)]
+    #[tokio::test(flavor = "current_thread")]
+    async fn same_origin_command_post_relays_without_wildcard_cors() {
+        let temp_parent = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+            .join("target")
+            .join("t");
+        std::fs::create_dir_all(&temp_parent).unwrap();
+        let socket_dir = tempfile::Builder::new()
+            .prefix("ab-")
+            .tempdir_in(temp_parent)
+            .unwrap();
+        let guard = EnvGuard::new(&["AGENT_BROWSER_SOCKET_DIR", "XDG_RUNTIME_DIR"]);
+        guard.set(
+            "AGENT_BROWSER_SOCKET_DIR",
+            socket_dir.path().to_str().unwrap(),
+        );
+        guard.remove("XDG_RUNTIME_DIR");
+
+        let session_name = "x";
+        let daemon_command = spawn_fake_daemon(socket_dir.path(), session_name).await;
+        let body = r#"{"action":"tabs"}"#;
+        let request = format!(
+            "POST /api/command HTTP/1.1\r\nHost: localhost:7777\r\nOrigin: http://localhost:7777\r\nContent-Type: application/json\r\nContent-Length: {}\r\n\r\n{}",
+            body.len(),
+            body
+        );
+
+        let response = send_request_to_handler(&request, session_name).await;
+
+        assert!(
+            response.starts_with("HTTP/1.1 200 OK"),
+            "unexpected response: {response}"
+        );
+        assert!(
+            response.contains("Access-Control-Allow-Origin: http://localhost:7777"),
+            "same-origin command response did not reflect origin: {response}"
+        );
+        assert!(
+            !response.contains("Access-Control-Allow-Origin: *"),
+            "same-origin command response exposed wildcard CORS: {response}"
+        );
+
+        let relayed = tokio::time::timeout(std::time::Duration::from_secs(1), daemon_command)
+            .await
+            .unwrap()
+            .unwrap();
+        assert!(relayed.contains(r#""action":"tabs""#), "{relayed}");
+    }
+}

cli/src/native/stream/mod.rs

@@ -0,0 +1,486 @@
+mod cdp_loop;
+pub(crate) mod chat;
+mod dashboard;
+mod discovery;
+mod http;
+mod websocket;
+
+pub use cdp_loop::{ack_screencast_frame, start_screencast, stop_screencast};
+pub use dashboard::run_dashboard_server;
+
+use serde_json::{json, Value};
+use std::sync::Arc;
+
+use tokio::net::TcpListener;
+use tokio::sync::{broadcast, watch, Mutex, Notify, RwLock};
+
+use super::cdp::client::CdpClient;
+
+/// Frame metadata from CDP Page.screencastFrame events.
+#[derive(Debug, Clone)]
+pub struct FrameMetadata {
+    pub offset_top: f64,
+    pub page_scale_factor: f64,
+    pub device_width: u32,
+    pub device_height: u32,
+    pub scroll_offset_x: f64,
+    pub scroll_offset_y: f64,
+    pub timestamp: u64,
+}
+
+impl Default for FrameMetadata {
+    fn default() -> Self {
+        Self {
+            offset_top: 0.0,
+            page_scale_factor: 1.0,
+            device_width: 1280,
+            device_height: 720,
+            scroll_offset_x: 0.0,
+            scroll_offset_y: 0.0,
+            timestamp: 0,
+        }
+    }
+}
+
+pub struct StreamServer {
+    port: u16,
+    session_name: String,
+    frame_tx: broadcast::Sender<String>,
+    client_count: Arc<Mutex<usize>>,
+    client_slot: Arc<RwLock<Option<Arc<CdpClient>>>>,
+    /// The active CDP page session ID (from Target.attachToTarget).
+    cdp_session_id: Arc<RwLock<Option<String>>>,
+    client_notify: Arc<Notify>,
+    screencasting: Arc<Mutex<bool>>,
+    viewport_width: Arc<Mutex<u32>>,
+    viewport_height: Arc<Mutex<u32>>,
+    last_tabs: Arc<RwLock<Vec<Value>>>,
+    last_engine: Arc<RwLock<String>>,
+    last_frame: Arc<RwLock<Option<String>>>,
+    recording: Arc<Mutex<bool>>,
+    shutdown_tx: watch::Sender<bool>,
+    accept_task: Mutex<Option<tokio::task::JoinHandle<()>>>,
+    cdp_task: Mutex<Option<tokio::task::JoinHandle<()>>>,
+}
+
+impl StreamServer {
+    pub async fn start(
+        preferred_port: u16,
+        client: Arc<CdpClient>,
+        session_id: String,
+    ) -> Result<Self, String> {
+        let client_slot = Arc::new(RwLock::new(Some(client)));
+        let (server, _) = Self::start_inner(preferred_port, client_slot, session_id, true).await?;
+        Ok(server)
+    }
+
+    /// Start the stream server without a CDP client.
+    /// Returns the server and a shared slot to set the client when the browser launches.
+    /// Input messages are ignored until the client is set.
+    /// When `allow_port_fallback` is true, binding to an occupied port falls back to an
+    /// OS-assigned port (used by daemon startup). When false, the error propagates
+    /// (used by the runtime `stream_enable` command).
+    pub async fn start_without_client(
+        preferred_port: u16,
+        session_id: String,
+        allow_port_fallback: bool,
+    ) -> Result<(Self, Arc<RwLock<Option<Arc<CdpClient>>>>), String> {
+        let client_slot = Arc::new(RwLock::new(None::<Arc<CdpClient>>));
+        Self::start_inner(preferred_port, client_slot, session_id, allow_port_fallback).await
+    }
+
+    /// Notify the background CDP listener that the client has changed (browser launched/closed).
+    pub fn notify_client_changed(&self) {
+        self.client_notify.notify_one();
+    }
+
+    /// Update the active CDP page session ID used for screencast commands.
+    pub async fn set_cdp_session_id(&self, session_id: Option<String>) {
+        let mut guard = self.cdp_session_id.write().await;
+        *guard = session_id;
+    }
+
+    /// Check whether the server currently has active screencast running.
+    pub async fn is_screencasting(&self) -> bool {
+        *self.screencasting.lock().await
+    }
+
+    /// Update the stored viewport dimensions and restart the active screencast (if any)
+    /// so frames are captured at the new size.
+    pub async fn set_viewport(&self, width: u32, height: u32) {
+        let mut vw = self.viewport_width.lock().await;
+        let mut vh = self.viewport_height.lock().await;
+        if *vw == width && *vh == height {
+            return;
+        }
+        *vw = width;
+        *vh = height;
+        drop(vw);
+        drop(vh);
+        self.client_notify.notify_one();
+    }
+
+    /// Get the current viewport dimensions.
+    pub async fn viewport(&self) -> (u32, u32) {
+        let w = *self.viewport_width.lock().await;
+        let h = *self.viewport_height.lock().await;
+        (w, h)
+    }
+
+    /// Override the cached screencast state for explicit CLI start/stop commands.
+    pub async fn set_screencasting(&self, active: bool) {
+        let mut guard = self.screencasting.lock().await;
+        *guard = active;
+    }
+
+    /// Update and broadcast the recording state.
+    pub async fn set_recording(&self, active: bool, engine: &str) {
+        *self.recording.lock().await = active;
+        let connected = self.client_slot.read().await.is_some();
+        let sc = *self.screencasting.lock().await;
+        let (vw, vh) = self.viewport().await;
+        self.broadcast_status(connected, sc, vw, vh, engine).await;
+    }
+
+    /// Shut down the accept loop and background CDP listener, releasing the bound port.
+    pub async fn shutdown(&self) {
+        let _ = self.shutdown_tx.send(true);
+
+        if let Some(task) = self.accept_task.lock().await.take() {
+            let _ = task.await;
+        }
+        if let Some(task) = self.cdp_task.lock().await.take() {
+            let _ = task.await;
+        }
+    }
+
+    async fn start_inner(
+        preferred_port: u16,
+        client_slot: Arc<RwLock<Option<Arc<CdpClient>>>>,
+        session_id: String,
+        allow_port_fallback: bool,
+    ) -> Result<(Self, Arc<RwLock<Option<Arc<CdpClient>>>>), String> {
+        let addr = format!("127.0.0.1:{}", preferred_port);
+        let listener = match TcpListener::bind(&addr).await {
+            Ok(l) => l,
+            Err(_) if allow_port_fallback && preferred_port != 0 => {
+                TcpListener::bind("127.0.0.1:0")
+                    .await
+                    .map_err(|e| format!("Failed to bind stream server: {}", e))?
+            }
+            Err(e) => return Err(format!("Failed to bind stream server: {}", e)),
+        };
+
+        let actual_addr = listener
+            .local_addr()
+            .map_err(|e| format!("Failed to get stream address: {}", e))?;
+        let port = actual_addr.port();
+
+        let (frame_tx, _) = broadcast::channel::<String>(64);
+        let client_count = Arc::new(Mutex::new(0usize));
+        let client_notify = Arc::new(Notify::new());
+        let screencasting = Arc::new(Mutex::new(false));
+        let cdp_session_id = Arc::new(RwLock::new(None::<String>));
+        let viewport_width = Arc::new(Mutex::new(1280u32));
+        let viewport_height = Arc::new(Mutex::new(720u32));
+        let last_tabs = Arc::new(RwLock::new(Vec::<Value>::new()));
+        let last_engine = Arc::new(RwLock::new("chrome".to_string()));
+        let last_frame = Arc::new(RwLock::new(None::<String>));
+        let recording = Arc::new(Mutex::new(false));
+        let (shutdown_tx, shutdown_rx) = watch::channel(false);
+
+        let frame_tx_clone = frame_tx.clone();
+        let client_count_clone = client_count.clone();
+        let client_slot_clone = client_slot.clone();
+        let notify_clone = client_notify.clone();
+        let screencasting_clone = screencasting.clone();
+        let cdp_session_clone = cdp_session_id.clone();
+
+        let vw_clone = viewport_width.clone();
+        let vh_clone = viewport_height.clone();
+        let last_tabs_clone = last_tabs.clone();
+        let last_engine_clone = last_engine.clone();
+        let last_frame_clone = last_frame.clone();
+        let recording_clone = recording.clone();
+        let accept_shutdown_rx = shutdown_rx.clone();
+        let session_name_clone = session_id.clone();
+        let accept_task = tokio::spawn(async move {
+            websocket::accept_loop(
+                listener,
+                frame_tx_clone,
+                client_count_clone,
+                client_slot_clone,
+                notify_clone,
+                screencasting_clone,
+                cdp_session_clone,
+                vw_clone,
+                vh_clone,
+                last_tabs_clone,
+                last_engine_clone,
+                last_frame_clone,
+                recording_clone,
+                accept_shutdown_rx,
+                session_name_clone,
+            )
+            .await;
+        });
+
+        let frame_tx_bg = frame_tx.clone();
+        let client_slot_bg = client_slot.clone();
+        let client_notify_bg = client_notify.clone();
+        let screencasting_bg = screencasting.clone();
+        let client_count_bg = client_count.clone();
+        let cdp_session_bg = cdp_session_id.clone();
+        let vw_bg = viewport_width.clone();
+        let vh_bg = viewport_height.clone();
+        let last_frame_bg = last_frame.clone();
+        let last_tabs_bg = last_tabs.clone();
+        let last_engine_bg = last_engine.clone();
+        let recording_bg = recording.clone();
+        let cdp_task = tokio::spawn(async move {
+            cdp_loop::cdp_event_loop(
+                frame_tx_bg,
+                client_slot_bg,
+                client_notify_bg,
+                screencasting_bg,
+                client_count_bg,
+                cdp_session_bg,
+                vw_bg,
+                vh_bg,
+                last_frame_bg,
+                last_tabs_bg,
+                last_engine_bg,
+                recording_bg,
+                shutdown_rx,
+            )
+            .await;
+        });
+
+        Ok((
+            Self {
+                port,
+                session_name: session_id,
+                frame_tx,
+                client_count,
+                client_slot: client_slot.clone(),
+                cdp_session_id,
+                client_notify,
+                screencasting,
+                viewport_width,
+                viewport_height,
+                last_tabs,
+                last_engine,
+                last_frame,
+                recording,
+                shutdown_tx,
+                accept_task: Mutex::new(Some(accept_task)),
+                cdp_task: Mutex::new(Some(cdp_task)),
+            },
+            client_slot,
+        ))
+    }
+
+    pub fn port(&self) -> u16 {
+        self.port
+    }
+
+    /// Broadcast a raw frame string (legacy).
+    pub fn broadcast_frame(&self, frame_json: &str) {
+        let s = frame_json.to_string();
+        if let Ok(mut lf) = self.last_frame.try_write() {
+            *lf = Some(s.clone());
+        }
+        let _ = self.frame_tx.send(s);
+    }
+
+    /// Broadcast a screencast frame with structured metadata.
+    pub fn broadcast_screencast_frame(&self, base64_data: &str, metadata: &FrameMetadata) {
+        let msg = json!({
+            "type": "frame",
+            "data": base64_data,
+            "metadata": {
+                "offsetTop": metadata.offset_top,
+                "pageScaleFactor": metadata.page_scale_factor,
+                "deviceWidth": metadata.device_width,
+                "deviceHeight": metadata.device_height,
+                "scrollOffsetX": metadata.scroll_offset_x,
+                "scrollOffsetY": metadata.scroll_offset_y,
+                "timestamp": metadata.timestamp,
+            }
+        });
+        let s = msg.to_string();
+        if let Ok(mut lf) = self.last_frame.try_write() {
+            *lf = Some(s.clone());
+        }
+        let _ = self.frame_tx.send(s);
+    }
+
+    /// Broadcast a status message to all connected clients.
+    pub async fn broadcast_status(
+        &self,
+        connected: bool,
+        screencasting: bool,
+        viewport_width: u32,
+        viewport_height: u32,
+        engine: &str,
+    ) {
+        {
+            let mut guard = self.last_engine.write().await;
+            *guard = engine.to_string();
+        }
+        let rec = *self.recording.lock().await;
+        let msg = json!({
+            "type": "status",
+            "connected": connected,
+            "screencasting": screencasting,
+            "viewportWidth": viewport_width,
+            "viewportHeight": viewport_height,
+            "engine": engine,
+            "recording": rec,
+        });
+        let _ = self.frame_tx.send(msg.to_string());
+    }
+
+    /// Broadcast an error message to all connected clients.
+    pub fn broadcast_error(&self, message: &str) {
+        let msg = json!({
+            "type": "error",
+            "message": message,
+        });
+        let _ = self.frame_tx.send(msg.to_string());
+    }
+
+    /// Broadcast a command event when a command begins executing.
+    pub fn broadcast_command(&self, action: &str, id: &str, params: &Value) {
+        let msg = json!({
+            "type": "command",
+            "action": action,
+            "id": id,
+            "params": params,
+            "timestamp": timestamp_ms(),
+        });
+        let _ = self.frame_tx.send(msg.to_string());
+    }
+
+    /// Broadcast a result event after a command finishes executing.
+    pub fn broadcast_result(
+        &self,
+        id: &str,
+        action: &str,
+        success: bool,
+        data: &Value,
+        duration_ms: u64,
+    ) {
+        let msg = json!({
+            "type": "result",
+            "id": id,
+            "action": action,
+            "success": success,
+            "data": data,
+            "duration_ms": duration_ms,
+            "timestamp": timestamp_ms(),
+        });
+        let _ = self.frame_tx.send(msg.to_string());
+    }
+
+    /// Broadcast a console event from the browser.
+    pub fn broadcast_console(&self, level: &str, text: &str, args: &[Value]) {
+        let mut msg = json!({
+            "type": "console",
+            "level": level,
+            "text": text,
+            "timestamp": timestamp_ms(),
+        });
+        if !args.is_empty() {
+            msg.as_object_mut()
+                .unwrap()
+                .insert("args".to_string(), Value::Array(args.to_vec()));
+        }
+        let _ = self.frame_tx.send(msg.to_string());
+    }
+
+    /// Broadcast a page error (uncaught exception) from the browser.
+    pub fn broadcast_page_error(&self, text: &str, line: Option<i64>, column: Option<i64>) {
+        let msg = json!({
+            "type": "page_error",
+            "text": text,
+            "line": line,
+            "column": column,
+            "timestamp": timestamp_ms(),
+        });
+        let _ = self.frame_tx.send(msg.to_string());
+    }
+
+    /// Broadcast the current tab list so the dashboard can render a tab bar.
+    /// Also caches the list so newly connected WebSocket clients receive it immediately.
+    pub async fn broadcast_tabs(&self, tabs: &[Value]) {
+        {
+            let mut guard = self.last_tabs.write().await;
+            *guard = tabs.to_vec();
+        }
+        let msg = json!({
+            "type": "tabs",
+            "tabs": tabs,
+            "timestamp": timestamp_ms(),
+        });
+        let _ = self.frame_tx.send(msg.to_string());
+    }
+}
+
+pub(crate) fn timestamp_ms() -> u64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_millis() as u64)
+        .unwrap_or(0)
+}
+
+pub fn is_allowed_origin(origin: Option<&str>) -> bool {
+    match origin {
+        None => true,
+        Some(o) => {
+            if o.starts_with("file://") {
+                return true;
+            }
+            if let Ok(url) = url::Url::parse(o) {
+                let host = url.host_str().unwrap_or("");
+                host == "localhost" || host == "127.0.0.1" || host == "::1" || host == "[::1]"
+            } else {
+                false
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_allowed_origin_none() {
+        assert!(is_allowed_origin(None));
+    }
+
+    #[test]
+    fn test_allowed_origin_file() {
+        assert!(is_allowed_origin(Some("file:///path/to/file")));
+    }
+
+    #[test]
+    fn test_allowed_origin_localhost() {
+        assert!(is_allowed_origin(Some("http://localhost:3000")));
+        assert!(is_allowed_origin(Some("http://127.0.0.1:8080")));
+    }
+
+    #[test]
+    fn test_disallowed_origin() {
+        assert!(!is_allowed_origin(Some("http://evil.com")));
+    }
+
+    #[test]
+    fn test_frame_metadata_default() {
+        let meta = FrameMetadata::default();
+        assert_eq!(meta.device_width, 1280);
+        assert_eq!(meta.device_height, 720);
+        assert_eq!(meta.page_scale_factor, 1.0);
+    }
+}

cli/src/native/stream/websocket.rs

@@ -0,0 +1,338 @@
+use serde_json::{json, Value};
+use std::net::SocketAddr;
+use std::sync::Arc;
+
+use futures_util::{SinkExt, StreamExt};
+use tokio::net::TcpListener;
+use tokio::sync::{broadcast, watch, Mutex, Notify, RwLock};
+use tokio_tungstenite::tungstenite::Message;
+
+use crate::native::cdp::client::CdpClient;
+
+use super::http::handle_http_request;
+use super::{is_allowed_origin, timestamp_ms};
+
+#[allow(clippy::too_many_arguments)]
+pub(super) async fn accept_loop(
+    listener: TcpListener,
+    frame_tx: broadcast::Sender<String>,
+    client_count: Arc<Mutex<usize>>,
+    client_slot: Arc<RwLock<Option<Arc<CdpClient>>>>,
+    client_notify: Arc<Notify>,
+    screencasting: Arc<Mutex<bool>>,
+    cdp_session_id: Arc<RwLock<Option<String>>>,
+    viewport_width: Arc<Mutex<u32>>,
+    viewport_height: Arc<Mutex<u32>>,
+    last_tabs: Arc<RwLock<Vec<Value>>>,
+    last_engine: Arc<RwLock<String>>,
+    last_frame: Arc<RwLock<Option<String>>>,
+    recording: Arc<Mutex<bool>>,
+    mut shutdown_rx: watch::Receiver<bool>,
+    session_name: String,
+) {
+    let session_name: Arc<str> = Arc::from(session_name);
+    loop {
+        tokio::select! {
+            changed = shutdown_rx.changed() => {
+                if changed.is_err() || *shutdown_rx.borrow() {
+                    break;
+                }
+            }
+            accept_result = listener.accept() => {
+                let Ok((stream, addr)) = accept_result else {
+                    break;
+                };
+                let frame_tx = frame_tx.clone();
+                let client_count = client_count.clone();
+                let client_slot = client_slot.clone();
+                let client_notify = client_notify.clone();
+                let screencasting = screencasting.clone();
+                let cdp_session_id = cdp_session_id.clone();
+                let vw = viewport_width.clone();
+                let vh = viewport_height.clone();
+                let lt = last_tabs.clone();
+                let le = last_engine.clone();
+                let lf = last_frame.clone();
+                let rec = recording.clone();
+                let shutdown_rx = shutdown_rx.clone();
+                let sn = session_name.clone();
+
+                tokio::spawn(async move {
+                    handle_connection(
+                        stream,
+                        addr,
+                        frame_tx,
+                        client_count,
+                        client_slot,
+                        client_notify,
+                        screencasting,
+                        cdp_session_id,
+                        vw,
+                        vh,
+                        lt,
+                        le,
+                        lf,
+                        rec,
+                        shutdown_rx,
+                        sn,
+                    )
+                    .await;
+                });
+            }
+        }
+    }
+}
+
+fn is_websocket_upgrade(request: &str) -> bool {
+    request.lines().any(|line| {
+        if let Some((name, value)) = line.split_once(':') {
+            name.trim().eq_ignore_ascii_case("upgrade")
+                && value.trim().eq_ignore_ascii_case("websocket")
+        } else {
+            false
+        }
+    })
+}
+
+/// Peek at the TCP stream to dispatch between WebSocket upgrade and plain HTTP.
+#[allow(clippy::too_many_arguments)]
+async fn handle_connection(
+    stream: tokio::net::TcpStream,
+    addr: SocketAddr,
+    frame_tx: broadcast::Sender<String>,
+    client_count: Arc<Mutex<usize>>,
+    client_slot: Arc<RwLock<Option<Arc<CdpClient>>>>,
+    client_notify: Arc<Notify>,
+    screencasting: Arc<Mutex<bool>>,
+    cdp_session_id: Arc<RwLock<Option<String>>>,
+    viewport_width: Arc<Mutex<u32>>,
+    viewport_height: Arc<Mutex<u32>>,
+    last_tabs: Arc<RwLock<Vec<Value>>>,
+    last_engine: Arc<RwLock<String>>,
+    last_frame: Arc<RwLock<Option<String>>>,
+    recording: Arc<Mutex<bool>>,
+    shutdown_rx: watch::Receiver<bool>,
+    session_name: Arc<str>,
+) {
+    let mut buf = [0u8; 4096];
+    let n = match stream.peek(&mut buf).await {
+        Ok(n) => n,
+        Err(_) => return,
+    };
+    let request = String::from_utf8_lossy(&buf[..n]);
+
+    if is_websocket_upgrade(&request) {
+        let frame_rx = frame_tx.subscribe();
+        handle_ws_client(
+            stream,
+            addr,
+            frame_rx,
+            client_count,
+            client_slot,
+            client_notify,
+            screencasting,
+            cdp_session_id,
+            viewport_width,
+            viewport_height,
+            last_tabs,
+            last_engine,
+            last_frame,
+            recording,
+            shutdown_rx,
+        )
+        .await;
+    } else {
+        handle_http_request(stream, &buf[..n], &last_tabs, &last_engine, &session_name).await;
+    }
+}
+
+#[allow(clippy::result_large_err, clippy::too_many_arguments)]
+async fn handle_ws_client(
+    stream: tokio::net::TcpStream,
+    _addr: SocketAddr,
+    mut frame_rx: broadcast::Receiver<String>,
+    client_count: Arc<Mutex<usize>>,
+    client_slot: Arc<RwLock<Option<Arc<CdpClient>>>>,
+    client_notify: Arc<Notify>,
+    screencasting: Arc<Mutex<bool>>,
+    cdp_session_id: Arc<RwLock<Option<String>>>,
+    viewport_width: Arc<Mutex<u32>>,
+    viewport_height: Arc<Mutex<u32>>,
+    last_tabs: Arc<RwLock<Vec<Value>>>,
+    last_engine: Arc<RwLock<String>>,
+    last_frame: Arc<RwLock<Option<String>>>,
+    recording: Arc<Mutex<bool>>,
+    mut shutdown_rx: watch::Receiver<bool>,
+) {
+    let callback =
+        |req: &tokio_tungstenite::tungstenite::handshake::server::Request,
+         resp: tokio_tungstenite::tungstenite::handshake::server::Response| {
+            let origin = req
+                .headers()
+                .get("origin")
+                .and_then(|v| v.to_str().ok())
+                .map(|s| s.to_string());
+            if !is_allowed_origin(origin.as_deref()) {
+                let mut reject =
+                    tokio_tungstenite::tungstenite::handshake::server::ErrorResponse::new(Some(
+                        "Origin not allowed".to_string(),
+                    ));
+                *reject.status_mut() = tokio_tungstenite::tungstenite::http::StatusCode::FORBIDDEN;
+                return Err(reject);
+            }
+            Ok(resp)
+        };
+
+    let ws_stream = match tokio_tungstenite::accept_hdr_async(stream, callback).await {
+        Ok(ws) => ws,
+        Err(_) => return,
+    };
+
+    {
+        let mut count = client_count.lock().await;
+        *count += 1;
+    }
+
+    let (mut ws_tx, mut ws_rx) = ws_stream.split();
+
+    {
+        let guard = client_slot.read().await;
+        let connected = guard.is_some();
+        let sc = *screencasting.lock().await;
+        let vw = *viewport_width.lock().await;
+        let vh = *viewport_height.lock().await;
+        let eng = last_engine.read().await.clone();
+        let rec = *recording.lock().await;
+        let status = json!({
+            "type": "status",
+            "connected": connected,
+            "screencasting": sc,
+            "viewportWidth": vw,
+            "viewportHeight": vh,
+            "engine": eng,
+            "recording": rec,
+        });
+        let _ = ws_tx.send(Message::Text(status.to_string())).await;
+
+        let tabs = last_tabs.read().await;
+        if !tabs.is_empty() {
+            let tabs_msg = json!({
+                "type": "tabs",
+                "tabs": *tabs,
+                "timestamp": timestamp_ms(),
+            });
+            let _ = ws_tx.send(Message::Text(tabs_msg.to_string())).await;
+        }
+
+        if let Some(ref cached) = *last_frame.read().await {
+            let _ = ws_tx.send(Message::Text(cached.clone())).await;
+        }
+    }
+
+    client_notify.notify_one();
+
+    loop {
+        tokio::select! {
+            changed = shutdown_rx.changed() => {
+                if changed.is_err() || *shutdown_rx.borrow() {
+                    let _ = ws_tx.send(Message::Close(None)).await;
+                    break;
+                }
+            }
+            frame = frame_rx.recv() => {
+                match frame {
+                    Ok(data) => {
+                        if ws_tx.send(Message::Text(data)).await.is_err() {
+                            break;
+                        }
+                    }
+                    Err(broadcast::error::RecvError::Lagged(_)) => {
+                        continue;
+                    }
+                    Err(broadcast::error::RecvError::Closed) => break,
+                }
+            }
+            msg = ws_rx.next() => {
+                match msg {
+                    Some(Ok(Message::Text(text))) => {
+                        let guard = client_slot.read().await;
+                        if let Some(ref client) = *guard {
+                            let sid = cdp_session_id.read().await;
+                            handle_client_message(&text, client.as_ref(), sid.as_deref()).await;
+                        }
+                    }
+                    Some(Ok(Message::Close(_))) | None => break,
+                    _ => {}
+                }
+            }
+        }
+    }
+
+    {
+        let mut count = client_count.lock().await;
+        *count = count.saturating_sub(1);
+    }
+
+    client_notify.notify_one();
+}
+
+async fn handle_client_message(msg: &str, client: &CdpClient, session_id: Option<&str>) {
+    let parsed: Value = match serde_json::from_str(msg) {
+        Ok(v) => v,
+        Err(_) => return,
+    };
+
+    let msg_type = parsed.get("type").and_then(|v| v.as_str()).unwrap_or("");
+
+    match msg_type {
+        "input_mouse" => {
+            let _ = client
+                .send_command(
+                    "Input.dispatchMouseEvent",
+                    Some(json!({
+                        "type": parsed.get("eventType").and_then(|v| v.as_str()).unwrap_or("mouseMoved"),
+                        "x": parsed.get("x").and_then(|v| v.as_f64()).unwrap_or(0.0),
+                        "y": parsed.get("y").and_then(|v| v.as_f64()).unwrap_or(0.0),
+                        "button": parsed.get("button").and_then(|v| v.as_str()).unwrap_or("none"),
+                        "clickCount": parsed.get("clickCount").and_then(|v| v.as_i64()).unwrap_or(0),
+                        "deltaX": parsed.get("deltaX").and_then(|v| v.as_f64()).unwrap_or(0.0),
+                        "deltaY": parsed.get("deltaY").and_then(|v| v.as_f64()).unwrap_or(0.0),
+                        "modifiers": parsed.get("modifiers").and_then(|v| v.as_i64()).unwrap_or(0),
+                    })),
+                    session_id,
+                )
+                .await;
+        }
+        "input_keyboard" => {
+            let _ = client
+                .send_command(
+                    "Input.dispatchKeyEvent",
+                    Some(json!({
+                        "type": parsed.get("eventType").and_then(|v| v.as_str()).unwrap_or("keyDown"),
+                        "key": parsed.get("key"),
+                        "code": parsed.get("code"),
+                        "text": parsed.get("text"),
+                        "windowsVirtualKeyCode": parsed.get("windowsVirtualKeyCode").and_then(|v| v.as_i64()).unwrap_or(0),
+                        "modifiers": parsed.get("modifiers").and_then(|v| v.as_i64()).unwrap_or(0),
+                    })),
+                    session_id,
+                )
+                .await;
+        }
+        "input_touch" => {
+            let _ = client
+                .send_command(
+                    "Input.dispatchTouchEvent",
+                    Some(json!({
+                        "type": parsed.get("eventType").and_then(|v| v.as_str()).unwrap_or("touchStart"),
+                        "touchPoints": parsed.get("touchPoints").unwrap_or(&json!([])),
+                        "modifiers": parsed.get("modifiers").and_then(|v| v.as_i64()).unwrap_or(0),
+                    })),
+                    session_id,
+                )
+                .await;
+        }
+        "status" => {}
+        _ => {}
+    }
+}

cli/src/native/test_fixtures/drag_probe.html

@@ -0,0 +1,135 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Drag Probe</title>
+  <style>
+    body {
+      margin: 0;
+      font: 14px/1.4 sans-serif;
+      background: #f4f4f4;
+    }
+
+    #pad {
+      position: relative;
+      width: 800px;
+      height: 500px;
+      margin: 24px;
+      border: 1px solid #999;
+      background: white;
+      overflow: hidden;
+    }
+
+    #target {
+      position: absolute;
+      left: 320px;
+      top: 40px;
+      width: 100px;
+      height: 40px;
+      background: #e34c26;
+      color: white;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      user-select: none;
+      cursor: grab;
+    }
+
+    #target.dragging {
+      cursor: grabbing;
+      background: #0d9488;
+    }
+
+    #log {
+      margin: 24px;
+      white-space: pre-wrap;
+      font-family: ui-monospace, monospace;
+    }
+  </style>
+</head>
+<body>
+  <div id="pad">
+    <div id="target">drag me</div>
+  </div>
+  <pre id="log"></pre>
+  <script>
+    const target = document.getElementById("target");
+    const logEl = document.getElementById("log");
+
+    window.__dragProbe = {
+      dragging: false,
+      events: [],
+      finalLeft: 320,
+      finalTop: 40,
+    };
+
+    let offsetX = 0;
+    let offsetY = 0;
+
+    function pushEvent(event, extra = {}) {
+      window.__dragProbe.events.push({
+        type: event.type,
+        button: event.button,
+        buttons: event.buttons,
+        x: event.clientX,
+        y: event.clientY,
+        target: event.target.id || event.target.tagName,
+        ...extra,
+      });
+      logEl.textContent = JSON.stringify(window.__dragProbe, null, 2);
+    }
+
+    function onPointerLikeStart(event) {
+      if (event.type === "mousedown") {
+        const rect = target.getBoundingClientRect();
+        offsetX = event.clientX - rect.left;
+        offsetY = event.clientY - rect.top;
+        window.__dragProbe.dragging = true;
+        target.classList.add("dragging");
+        event.preventDefault();
+      }
+      pushEvent(event, { phase: "start" });
+    }
+
+    target.addEventListener("mousedown", (event) => {
+      const rect = target.getBoundingClientRect();
+      offsetX = event.clientX - rect.left;
+      offsetY = event.clientY - rect.top;
+      window.__dragProbe.dragging = true;
+      target.classList.add("dragging");
+      event.preventDefault();
+      pushEvent(event, { phase: "start" });
+    });
+    target.addEventListener("pointerdown", onPointerLikeStart);
+
+    document.addEventListener("mousemove", (event) => {
+      if (window.__dragProbe.dragging) {
+        const left = event.clientX - offsetX;
+        const top = event.clientY - offsetY;
+        target.style.left = `${left}px`;
+        target.style.top = `${top}px`;
+        window.__dragProbe.finalLeft = left;
+        window.__dragProbe.finalTop = top;
+      }
+      pushEvent(event);
+    });
+    document.addEventListener("pointermove", (event) => {
+      pushEvent(event);
+    });
+
+    document.addEventListener("mouseup", (event) => {
+      if (window.__dragProbe.dragging) {
+        window.__dragProbe.dragging = false;
+        target.classList.remove("dragging");
+      }
+      pushEvent(event, { phase: "end" });
+    });
+    document.addEventListener("pointerup", (event) => {
+      pushEvent(event, { phase: "end" });
+    });
+    target.addEventListener("dragstart", (event) => {
+      pushEvent(event, { phase: "dragstart" });
+    });
+  </script>
+</body>
+</html>

cli/src/native/test_fixtures/html5_drag_probe.html

@@ -0,0 +1,91 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>HTML5 Drag Probe</title>
+  <style>
+    body {
+      margin: 24px;
+      font: 14px/1.4 sans-serif;
+    }
+
+    #source, #dest {
+      width: 120px;
+      height: 80px;
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      border: 1px solid #666;
+      user-select: none;
+      margin-right: 40px;
+    }
+
+    #source {
+      background: #f97316;
+      color: white;
+    }
+
+    #dest {
+      background: #e5e7eb;
+    }
+
+    pre {
+      margin-top: 24px;
+      white-space: pre-wrap;
+      font-family: ui-monospace, monospace;
+    }
+  </style>
+</head>
+<body>
+  <div id="source" draggable="true">drag source</div>
+  <div id="dest">drop zone</div>
+  <pre id="log"></pre>
+  <script>
+    const source = document.getElementById("source");
+    const dest = document.getElementById("dest");
+    const logEl = document.getElementById("log");
+
+    window.__html5DragProbe = { events: [] };
+
+    function pushEvent(event, extra = {}) {
+      window.__html5DragProbe.events.push({
+        type: event.type,
+        target: event.target.id || event.target.tagName,
+        x: event.clientX,
+        y: event.clientY,
+        button: event.button,
+        buttons: event.buttons,
+        ...extra,
+      });
+      logEl.textContent = JSON.stringify(window.__html5DragProbe, null, 2);
+    }
+
+    for (const type of ["pointerdown", "mousedown", "dragstart", "drag", "dragend"]) {
+      source.addEventListener(type, (event) => {
+        if (type === "dragstart") {
+          event.dataTransfer.setData("text/plain", "probe");
+        }
+        pushEvent(event);
+      });
+    }
+
+    for (const type of ["pointermove", "mousemove", "dragenter", "dragover", "drop", "pointerup", "mouseup"]) {
+      document.addEventListener(type, (event) => {
+        if (type === "dragover") {
+          event.preventDefault();
+        }
+        if (type === "drop") {
+          pushEvent(event, { dropped: event.dataTransfer.getData("text/plain") });
+          return;
+        }
+        pushEvent(event);
+      });
+    }
+
+    dest.addEventListener("dragover", (event) => event.preventDefault());
+    dest.addEventListener("drop", (event) => {
+      pushEvent(event, { dropped: event.dataTransfer.getData("text/plain") });
+    });
+  </script>
+</body>
+</html>

cli/src/native/test_fixtures/pointer_capture_probe.html

@@ -0,0 +1,113 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Pointer Capture Probe</title>
+  <style>
+    body {
+      margin: 24px;
+      font: 14px/1.4 sans-serif;
+    }
+    #crop {
+      position: relative;
+      width: 240px;
+      height: 180px;
+      border: 2px solid #fff;
+      outline: 1px solid #555;
+      background: rgba(0, 0, 0, 0.2);
+    }
+    #handle {
+      position: absolute;
+      width: 20px;
+      height: 20px;
+      top: -16px;
+      left: -16px;
+      padding-top: 13px;
+      padding-left: 13px;
+      box-sizing: content-box;
+      background: rgba(255, 0, 0, 0.25);
+    }
+    #handle::after {
+      content: "";
+      display: block;
+      width: 20px;
+      height: 20px;
+      border-top: 2px solid white;
+      border-left: 2px solid white;
+    }
+    pre {
+      margin-top: 24px;
+      white-space: pre-wrap;
+      font-family: ui-monospace, monospace;
+    }
+  </style>
+</head>
+<body>
+  <div id="crop" aria-label="crop area">
+    <div id="handle" aria-label="crop handle topLeft" data-anchor="topLeft"></div>
+  </div>
+  <pre id="log"></pre>
+  <script>
+    const crop = document.getElementById("crop");
+    const handle = document.getElementById("handle");
+    const logEl = document.getElementById("log");
+
+    const state = {
+      targetAnchor: null,
+      dragging: false,
+      moved: false,
+      events: [],
+    };
+    window.__pointerCaptureProbe = state;
+
+    function sync() {
+      logEl.textContent = JSON.stringify(state, null, 2);
+    }
+
+    function push(event, extra = {}) {
+      state.events.push({
+        type: event.type,
+        target: event.target.id || event.target.tagName,
+        currentTarget: event.currentTarget.id || event.currentTarget.tagName,
+        pointerId: event.pointerId,
+        button: event.button,
+        buttons: event.buttons,
+        hasCapture: event.currentTarget.hasPointerCapture?.(event.pointerId) ?? false,
+        x: event.clientX,
+        y: event.clientY,
+        ...extra,
+      });
+      sync();
+    }
+
+    crop.addEventListener("pointerdown", (event) => {
+      state.targetAnchor = event.target.getAttribute("data-anchor");
+      crop.setPointerCapture(event.pointerId);
+      event.preventDefault();
+      push(event, { phase: "down", targetAnchor: state.targetAnchor });
+    });
+
+    crop.addEventListener("pointermove", (event) => {
+      const hasCapture = crop.hasPointerCapture(event.pointerId);
+      if (hasCapture && state.targetAnchor) {
+        state.dragging = true;
+        state.moved = true;
+      }
+      push(event, { phase: hasCapture ? "drag" : "hover", targetAnchor: state.targetAnchor });
+    });
+
+    crop.addEventListener("pointerup", (event) => {
+      const hadCapture = crop.hasPointerCapture(event.pointerId);
+      state.dragging = false;
+      push(event, { phase: "up", targetAnchor: state.targetAnchor, hadCapture });
+      state.targetAnchor = null;
+    });
+
+    handle.addEventListener("pointerdown", (event) => push(event, { listener: "handle" }));
+    handle.addEventListener("pointermove", (event) => push(event, { listener: "handle" }));
+    handle.addEventListener("pointerup", (event) => push(event, { listener: "handle" }));
+
+    sync();
+  </script>
+</body>
+</html>

cli/src/native/test_fixtures/upload_probe.html

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html>
+<head><title>Upload Test</title></head>
+<body>
+  <h1>Upload Test</h1>
+  <label for="fileInput">Choose file:</label>
+  <input type="file" id="fileInput" name="fileInput">
+  <div id="result"></div>
+  <script>
+    document.getElementById('fileInput').addEventListener('change', function(e) {
+      var file = e.target.files[0];
+      if (file) {
+        document.getElementById('result').textContent = 'uploaded:' + file.name;
+      }
+    });
+  </script>
+</body>
+</html>

cli/src/native/tracing.rs

@@ -0,0 +1,373 @@
+use serde_json::{json, Value};
+use std::path::PathBuf;
+
+use super::cdp::client::CdpClient;
+
+const MAX_PROFILE_EVENTS: usize = 5_000_000;
+
+const DEFAULT_PROFILER_CATEGORIES: &[&str] = &[
+    "devtools.timeline",
+    "disabled-by-default-devtools.timeline",
+    "disabled-by-default-devtools.timeline.frame",
+    "disabled-by-default-devtools.timeline.stack",
+    "v8.execute",
+    "disabled-by-default-v8.cpu_profiler",
+    "disabled-by-default-v8.cpu_profiler.hires",
+    "v8",
+    "disabled-by-default-v8.runtime_stats",
+    "blink",
+    "blink.user_timing",
+    "latencyInfo",
+    "renderer.scheduler",
+    "sequence_manager",
+    "toplevel",
+];
+
+pub struct TracingState {
+    pub active: bool,
+    pub events: Vec<Value>,
+    pub events_dropped: bool,
+}
+
+impl TracingState {
+    pub fn new() -> Self {
+        Self {
+            active: false,
+            events: Vec::new(),
+            events_dropped: false,
+        }
+    }
+}
+
+pub async fn trace_start(
+    client: &CdpClient,
+    session_id: &str,
+    tracing_state: &mut TracingState,
+) -> Result<Value, String> {
+    if tracing_state.active {
+        return Err("Tracing already active".to_string());
+    }
+
+    client
+        .send_command(
+            "Tracing.start",
+            Some(json!({
+                "traceConfig": {
+                    "recordMode": "recordContinuously",
+                },
+                "transferMode": "ReturnAsStream",
+            })),
+            Some(session_id),
+        )
+        .await?;
+
+    tracing_state.active = true;
+    tracing_state.events.clear();
+    tracing_state.events_dropped = false;
+
+    Ok(json!({ "started": true }))
+}
+
+pub async fn trace_stop(
+    client: &CdpClient,
+    session_id: &str,
+    tracing_state: &mut TracingState,
+    path: Option<&str>,
+) -> Result<Value, String> {
+    if !tracing_state.active {
+        return Err("No tracing in progress".to_string());
+    }
+
+    // Subscribe to events before stopping
+    let mut rx = client.subscribe();
+
+    client
+        .send_command_no_params("Tracing.end", Some(session_id))
+        .await?;
+
+    // Collect trace data with timeout
+    let mut trace_events: Vec<Value> = Vec::new();
+    let mut stream_handle: Option<String> = None;
+
+    let deadline = tokio::time::Instant::now() + tokio::time::Duration::from_secs(30);
+
+    loop {
+        let result = tokio::time::timeout_at(deadline, rx.recv()).await;
+
+        match result {
+            Ok(Ok(event)) => {
+                if event.session_id.as_deref() != Some(session_id) {
+                    continue;
+                }
+                match event.method.as_str() {
+                    "Tracing.dataCollected" => {
+                        if let Some(arr) = event.params.get("value").and_then(|v| v.as_array()) {
+                            trace_events.extend(arr.iter().cloned());
+                        }
+                    }
+                    "Tracing.tracingComplete" => {
+                        stream_handle = event
+                            .params
+                            .get("stream")
+                            .and_then(|v| v.as_str())
+                            .map(String::from);
+                        break;
+                    }
+                    _ => {}
+                }
+            }
+            Ok(Err(_)) => break,
+            Err(_) => {
+                return Err("Tracing stop timed out after 30s".to_string());
+            }
+        }
+    }
+
+    // If ReturnAsStream mode was used, read trace data from the IO stream
+    if let Some(handle) = stream_handle {
+        if trace_events.is_empty() {
+            let stream_data = read_io_stream(client, session_id, &handle).await?;
+            if let Ok(parsed) = serde_json::from_str::<Value>(&stream_data) {
+                if let Some(events) = parsed.get("traceEvents").and_then(|v| v.as_array()) {
+                    trace_events.extend(events.iter().cloned());
+                }
+            } else {
+                // Try parsing as newline-delimited JSON
+                for line in stream_data.lines() {
+                    if let Ok(val) = serde_json::from_str::<Value>(line) {
+                        if let Some(events) = val.get("traceEvents").and_then(|v| v.as_array()) {
+                            trace_events.extend(events.iter().cloned());
+                        } else {
+                            trace_events.push(val);
+                        }
+                    }
+                }
+            }
+        }
+        // Close the IO stream
+        let _ = client
+            .send_command(
+                "IO.close",
+                Some(json!({ "handle": handle })),
+                Some(session_id),
+            )
+            .await;
+    }
+
+    tracing_state.active = false;
+
+    let save_path = match path {
+        Some(p) => p.to_string(),
+        None => {
+            let dir = get_traces_dir();
+            let _ = std::fs::create_dir_all(&dir);
+            let timestamp = std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap_or_default()
+                .as_millis();
+            dir.join(format!("trace-{}.json", timestamp))
+                .to_string_lossy()
+                .to_string()
+        }
+    };
+
+    let trace_json = json!({ "traceEvents": trace_events });
+    let json_str = serde_json::to_string(&trace_json)
+        .map_err(|e| format!("Failed to serialize trace: {}", e))?;
+    std::fs::write(&save_path, json_str)
+        .map_err(|e| format!("Failed to write trace to {}: {}", save_path, e))?;
+
+    Ok(json!({ "path": save_path, "eventCount": trace_events.len() }))
+}
+
+pub async fn profiler_start(
+    client: &CdpClient,
+    session_id: &str,
+    tracing_state: &mut TracingState,
+    categories: Option<Vec<String>>,
+) -> Result<Value, String> {
+    if tracing_state.active {
+        return Err("Profiling/tracing already active".to_string());
+    }
+
+    let cats: Vec<String> = categories.unwrap_or_else(|| {
+        DEFAULT_PROFILER_CATEGORIES
+            .iter()
+            .map(|s| s.to_string())
+            .collect()
+    });
+
+    client
+        .send_command(
+            "Tracing.start",
+            Some(json!({
+                "traceConfig": {
+                    "includedCategories": cats,
+                    "enableSampling": true,
+                },
+                "transferMode": "ReportEvents",
+            })),
+            Some(session_id),
+        )
+        .await?;
+
+    tracing_state.active = true;
+    tracing_state.events.clear();
+    tracing_state.events_dropped = false;
+
+    Ok(json!({ "started": true }))
+}
+
+pub async fn profiler_stop(
+    client: &CdpClient,
+    session_id: &str,
+    tracing_state: &mut TracingState,
+    path: Option<&str>,
+) -> Result<Value, String> {
+    if !tracing_state.active {
+        return Err("No profiling in progress".to_string());
+    }
+
+    let mut rx = client.subscribe();
+
+    client
+        .send_command_no_params("Tracing.end", Some(session_id))
+        .await?;
+
+    let mut events: Vec<Value> = Vec::new();
+    let mut dropped = false;
+    let deadline = tokio::time::Instant::now() + tokio::time::Duration::from_secs(30);
+
+    loop {
+        let result = tokio::time::timeout_at(deadline, rx.recv()).await;
+
+        match result {
+            Ok(Ok(event)) => {
+                if event.session_id.as_deref() != Some(session_id) {
+                    continue;
+                }
+                match event.method.as_str() {
+                    "Tracing.dataCollected" => {
+                        if let Some(arr) = event.params.get("value").and_then(|v| v.as_array()) {
+                            if events.len() + arr.len() > MAX_PROFILE_EVENTS {
+                                dropped = true;
+                            } else {
+                                events.extend(arr.iter().cloned());
+                            }
+                        }
+                    }
+                    "Tracing.tracingComplete" => {
+                        break;
+                    }
+                    _ => {}
+                }
+            }
+            Ok(Err(_)) => break,
+            Err(_) => {
+                return Err("Profiler stop timed out after 30s".to_string());
+            }
+        }
+    }
+
+    tracing_state.active = false;
+
+    let save_path = match path {
+        Some(p) => p.to_string(),
+        None => {
+            let dir = get_profiles_dir();
+            let _ = std::fs::create_dir_all(&dir);
+            let timestamp = std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap_or_default()
+                .as_millis();
+            dir.join(format!("profile-{}.json", timestamp))
+                .to_string_lossy()
+                .to_string()
+        }
+    };
+
+    let clock_domain = get_clock_domain();
+    let mut profile = json!({ "traceEvents": events });
+    if let Some(cd) = clock_domain {
+        profile
+            .as_object_mut()
+            .unwrap()
+            .insert("metadata".to_string(), json!({ "clock-domain": cd }));
+    }
+
+    let json_str = serde_json::to_string(&profile)
+        .map_err(|e| format!("Failed to serialize profile: {}", e))?;
+    std::fs::write(&save_path, json_str)
+        .map_err(|e| format!("Failed to write profile to {}: {}", save_path, e))?;
+
+    let event_count = events.len();
+    let mut result = json!({ "path": save_path, "eventCount": event_count });
+    if dropped {
+        result.as_object_mut().unwrap().insert(
+            "warning".to_string(),
+            Value::String(format!(
+                "Events exceeded {} limit; some dropped",
+                MAX_PROFILE_EVENTS
+            )),
+        );
+    }
+
+    Ok(result)
+}
+
+/// Read all data from a CDP IO stream handle.
+async fn read_io_stream(
+    client: &CdpClient,
+    session_id: &str,
+    handle: &str,
+) -> Result<String, String> {
+    let mut data = String::new();
+    loop {
+        let result = client
+            .send_command(
+                "IO.read",
+                Some(json!({
+                    "handle": handle,
+                    "size": 1024 * 1024,
+                })),
+                Some(session_id),
+            )
+            .await?;
+
+        if let Some(chunk) = result.get("data").and_then(|v| v.as_str()) {
+            data.push_str(chunk);
+        }
+
+        let eof = result.get("eof").and_then(|v| v.as_bool()).unwrap_or(true);
+        if eof {
+            break;
+        }
+    }
+    Ok(data)
+}
+
+fn get_clock_domain() -> Option<&'static str> {
+    if cfg!(target_os = "linux") {
+        Some("LINUX_CLOCK_MONOTONIC")
+    } else if cfg!(target_os = "macos") {
+        Some("MAC_MACH_ABSOLUTE_TIME")
+    } else {
+        None
+    }
+}
+
+fn get_traces_dir() -> PathBuf {
+    if let Some(home) = dirs::home_dir() {
+        home.join(".agent-browser").join("tmp").join("traces")
+    } else {
+        std::env::temp_dir().join("agent-browser").join("traces")
+    }
+}
+
+fn get_profiles_dir() -> PathBuf {
+    if let Some(home) = dirs::home_dir() {
+        home.join(".agent-browser").join("tmp").join("profiles")
+    } else {
+        std::env::temp_dir().join("agent-browser").join("profiles")
+    }
+}

cli/src/native/webdriver/appium.rs

@@ -0,0 +1,240 @@
+use serde_json::{json, Value};
+use std::process::{Child, Command, Stdio};
+use std::time::Duration;
+
+use super::client::WebDriverClient;
+
+const APPIUM_DEFAULT_PORT: u16 = 4723;
+const APPIUM_STARTUP_TIMEOUT_SECS: u64 = 30;
+
+pub struct AppiumManager {
+    pub client: WebDriverClient,
+    appium_process: Option<Child>,
+    pub device_udid: Option<String>,
+}
+
+impl AppiumManager {
+    pub async fn connect_or_launch(device_udid: Option<&str>) -> Result<Self, String> {
+        let port = APPIUM_DEFAULT_PORT;
+        let client = WebDriverClient::new(port);
+
+        // Check if Appium is already running
+        if is_appium_running(port).await {
+            return Ok(Self {
+                client,
+                appium_process: None,
+                device_udid: device_udid.map(String::from),
+            });
+        }
+
+        // Try to launch Appium
+        let appium_process = launch_appium(port)?;
+
+        // Wait for Appium to be ready
+        wait_for_appium(port, APPIUM_STARTUP_TIMEOUT_SECS).await?;
+
+        Ok(Self {
+            client,
+            appium_process: Some(appium_process),
+            device_udid: device_udid.map(String::from),
+        })
+    }
+
+    pub fn build_ios_capabilities(
+        device_udid: Option<&str>,
+        device_name: Option<&str>,
+        platform_version: Option<&str>,
+    ) -> Value {
+        let mut caps = json!({
+            "platformName": "iOS",
+            "appium:automationName": "XCUITest",
+            "browserName": "Safari",
+            "appium:noReset": true,
+        });
+
+        if let Some(name) = device_name {
+            caps["appium:deviceName"] = json!(name);
+        } else {
+            caps["appium:deviceName"] = json!("iPhone");
+        }
+
+        if let Some(ver) = platform_version {
+            caps["appium:platformVersion"] = json!(ver);
+        }
+
+        if let Some(udid) = device_udid {
+            caps["appium:udid"] = json!(udid);
+        }
+
+        caps
+    }
+
+    pub async fn create_ios_session(
+        &mut self,
+        device_name: Option<&str>,
+        platform_version: Option<&str>,
+    ) -> Result<Value, String> {
+        let caps = Self::build_ios_capabilities(
+            self.device_udid.as_deref(),
+            device_name,
+            platform_version,
+        );
+        self.client.create_session(caps).await
+    }
+
+    pub async fn tap(&self, x: f64, y: f64) -> Result<(), String> {
+        let sid = self
+            .client
+            .session_id_pub()
+            .ok_or("No active session")?
+            .to_string();
+        let actions = json!({
+            "actions": [{
+                "type": "pointer",
+                "id": "finger1",
+                "parameters": { "pointerType": "touch" },
+                "actions": [
+                    { "type": "pointerMove", "duration": 0, "x": x as i64, "y": y as i64 },
+                    { "type": "pointerDown", "button": 0 },
+                    { "type": "pause", "duration": 100 },
+                    { "type": "pointerUp", "button": 0 },
+                ]
+            }]
+        });
+        self.client.execute_actions(&sid, &actions).await
+    }
+
+    pub async fn swipe(
+        &self,
+        start_x: f64,
+        start_y: f64,
+        end_x: f64,
+        end_y: f64,
+        duration_ms: u64,
+    ) -> Result<(), String> {
+        let sid = self
+            .client
+            .session_id_pub()
+            .ok_or("No active session")?
+            .to_string();
+        let actions = json!({
+            "actions": [{
+                "type": "pointer",
+                "id": "finger1",
+                "parameters": { "pointerType": "touch" },
+                "actions": [
+                    { "type": "pointerMove", "duration": 0, "x": start_x as i64, "y": start_y as i64 },
+                    { "type": "pointerDown", "button": 0 },
+                    { "type": "pointerMove", "duration": duration_ms, "x": end_x as i64, "y": end_y as i64 },
+                    { "type": "pointerUp", "button": 0 },
+                ]
+            }]
+        });
+        self.client.execute_actions(&sid, &actions).await
+    }
+
+    pub async fn close(&mut self) -> Result<(), String> {
+        let _ = self.client.delete_session().await;
+        if let Some(ref mut child) = self.appium_process {
+            let _ = child.kill();
+            let _ = child.wait();
+        }
+        Ok(())
+    }
+}
+
+impl Drop for AppiumManager {
+    fn drop(&mut self) {
+        if let Some(ref mut child) = self.appium_process {
+            let _ = child.kill();
+            let _ = child.wait();
+        }
+    }
+}
+
+async fn is_appium_running(port: u16) -> bool {
+    let addr = format!("127.0.0.1:{}", port);
+    tokio::time::timeout(
+        Duration::from_secs(2),
+        tokio::net::TcpStream::connect(&addr),
+    )
+    .await
+    .map(|r| r.is_ok())
+    .unwrap_or(false)
+}
+
+fn launch_appium(port: u16) -> Result<Child, String> {
+    // Try npx appium first, then direct appium
+    let result = Command::new("npx")
+        .args(["appium", "--relaxed-security", "--port", &port.to_string()])
+        .stdin(Stdio::null())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn();
+
+    match result {
+        Ok(child) => Ok(child),
+        Err(_) => Command::new("appium")
+            .args(["--relaxed-security", "--port", &port.to_string()])
+            .stdin(Stdio::null())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped())
+            .spawn()
+            .map_err(|e| {
+                format!(
+                    "Failed to launch Appium. Install it with: npm install -g appium. Error: {}",
+                    e
+                )
+            }),
+    }
+}
+
+async fn wait_for_appium(port: u16, timeout_secs: u64) -> Result<(), String> {
+    let deadline = tokio::time::Instant::now() + Duration::from_secs(timeout_secs);
+    loop {
+        if tokio::time::Instant::now() > deadline {
+            return Err("Timeout waiting for Appium to start".to_string());
+        }
+        if is_appium_running(port).await {
+            return Ok(());
+        }
+        tokio::time::sleep(Duration::from_millis(500)).await;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_appium_constants() {
+        assert_eq!(APPIUM_DEFAULT_PORT, 4723);
+        assert_eq!(APPIUM_STARTUP_TIMEOUT_SECS, 30);
+    }
+
+    #[test]
+    fn test_ios_capabilities_use_vendor_prefix() {
+        let caps = AppiumManager::build_ios_capabilities(
+            Some("TEST-UDID-123"),
+            Some("iPhone 16 Pro"),
+            Some("18.5"),
+        );
+
+        // W3C standard capabilities must NOT have vendor prefix
+        assert!(caps.get("platformName").is_some());
+        assert!(caps.get("browserName").is_some());
+
+        // Non-standard capabilities MUST have appium: vendor prefix
+        assert!(caps.get("appium:automationName").is_some());
+        assert!(caps.get("appium:noReset").is_some());
+        assert!(caps.get("appium:deviceName").is_some());
+        assert!(caps.get("appium:platformVersion").is_some());
+        assert!(caps.get("appium:udid").is_some());
+
+        // Must NOT have unprefixed non-standard capabilities
+        assert!(caps.get("automationName").is_none());
+        assert!(caps.get("noReset").is_none());
+        assert!(caps.get("deviceName").is_none());
+        assert!(caps.get("udid").is_none());
+    }
+}

cli/src/native/webdriver/backend.rs

@@ -0,0 +1,142 @@
+use async_trait::async_trait;
+use serde_json::Value;
+
+/// Abstract backend for browser automation. CDP (Chromium) and WebDriver
+/// (Safari/iOS) share this interface so actions.rs can remain backend-agnostic
+/// in the future.
+#[async_trait]
+pub trait BrowserBackend: Send + Sync {
+    async fn navigate(&self, url: &str) -> Result<(), String>;
+    async fn get_url(&self) -> Result<String, String>;
+    async fn get_title(&self) -> Result<String, String>;
+    async fn get_content(&self) -> Result<String, String>;
+    async fn evaluate(&self, script: &str) -> Result<Value, String>;
+    async fn screenshot(&self) -> Result<String, String>;
+    async fn click(&self, selector: &str) -> Result<(), String>;
+    async fn fill(&self, selector: &str, value: &str) -> Result<(), String>;
+    async fn close(&mut self) -> Result<(), String>;
+    async fn back(&self) -> Result<(), String>;
+    async fn forward(&self) -> Result<(), String>;
+    async fn reload(&self) -> Result<(), String>;
+    async fn get_cookies(&self) -> Result<Value, String>;
+    fn backend_type(&self) -> &str;
+
+    fn supports(&self, feature: &str) -> bool {
+        match feature {
+            "navigate" | "evaluate" | "screenshot" | "click" | "fill" => true,
+            "screencast" | "tracing" | "network_intercept" | "cdp" => self.backend_type() == "cdp",
+            _ => false,
+        }
+    }
+
+    fn unsupported_error(&self, action: &str) -> String {
+        format!(
+            "Action '{}' is not supported on the {} backend",
+            action,
+            self.backend_type()
+        )
+    }
+}
+
+/// WebDriver implementation of BrowserBackend
+pub struct WebDriverBackend {
+    client: super::client::WebDriverClient,
+}
+
+impl WebDriverBackend {
+    pub fn new(client: super::client::WebDriverClient) -> Self {
+        Self { client }
+    }
+}
+
+#[async_trait]
+impl BrowserBackend for WebDriverBackend {
+    async fn navigate(&self, url: &str) -> Result<(), String> {
+        self.client.navigate(url).await
+    }
+
+    async fn get_url(&self) -> Result<String, String> {
+        self.client.get_url().await
+    }
+
+    async fn get_title(&self) -> Result<String, String> {
+        self.client.get_title().await
+    }
+
+    async fn get_content(&self) -> Result<String, String> {
+        self.client.get_page_source().await
+    }
+
+    async fn evaluate(&self, script: &str) -> Result<Value, String> {
+        self.client.execute_script(script, vec![]).await
+    }
+
+    async fn screenshot(&self) -> Result<String, String> {
+        self.client.screenshot().await
+    }
+
+    async fn click(&self, selector: &str) -> Result<(), String> {
+        let element_id = self.client.find_element("css selector", selector).await?;
+        self.client.click_element(&element_id).await
+    }
+
+    async fn fill(&self, selector: &str, value: &str) -> Result<(), String> {
+        let element_id = self.client.find_element("css selector", selector).await?;
+        self.client.clear_element(&element_id).await?;
+        self.client.send_keys(&element_id, value).await
+    }
+
+    async fn close(&mut self) -> Result<(), String> {
+        self.client.delete_session().await
+    }
+
+    async fn back(&self) -> Result<(), String> {
+        self.client.back().await
+    }
+
+    async fn forward(&self) -> Result<(), String> {
+        self.client.forward().await
+    }
+
+    async fn reload(&self) -> Result<(), String> {
+        self.client.refresh().await
+    }
+
+    async fn get_cookies(&self) -> Result<Value, String> {
+        self.client.get_cookies().await
+    }
+
+    fn backend_type(&self) -> &str {
+        "webdriver"
+    }
+}
+
+/// CDP-backed backend constants for unsupported actions on WebDriver
+pub const WEBDRIVER_UNSUPPORTED_ACTIONS: &[&str] = &[
+    "screencast_start",
+    "screencast_stop",
+    "trace_start",
+    "trace_stop",
+    "profiler_start",
+    "profiler_stop",
+    "route",
+    "unroute",
+    "expose",
+    "addscript",
+    "addinitscript",
+    "network",
+    "har_start",
+    "har_stop",
+];
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_unsupported_actions() {
+        assert!(WEBDRIVER_UNSUPPORTED_ACTIONS.contains(&"screencast_start"));
+        assert!(WEBDRIVER_UNSUPPORTED_ACTIONS.contains(&"trace_start"));
+        assert!(!WEBDRIVER_UNSUPPORTED_ACTIONS.contains(&"navigate"));
+    }
+}

cli/src/native/webdriver/client.rs

@@ -0,0 +1,318 @@
+use serde_json::{json, Value};
+use std::time::Duration;
+
+pub struct WebDriverClient {
+    base_url: String,
+    session_id: Option<String>,
+}
+
+impl WebDriverClient {
+    pub fn new(port: u16) -> Self {
+        Self {
+            base_url: format!("http://127.0.0.1:{}", port),
+            session_id: None,
+        }
+    }
+
+    pub async fn create_session(&mut self, capabilities: Value) -> Result<Value, String> {
+        let body = json!({
+            "capabilities": {
+                "alwaysMatch": capabilities,
+            }
+        });
+
+        let response = self.post("/session", &body).await?;
+
+        let session_id = response
+            .get("value")
+            .and_then(|v| v.get("sessionId"))
+            .and_then(|v| v.as_str())
+            .ok_or("No sessionId in response")?
+            .to_string();
+
+        self.session_id = Some(session_id);
+        Ok(response)
+    }
+
+    pub async fn delete_session(&mut self) -> Result<(), String> {
+        if let Some(ref sid) = self.session_id.clone() {
+            let _ = self.delete(&format!("/session/{}", sid)).await;
+            self.session_id = None;
+        }
+        Ok(())
+    }
+
+    pub async fn navigate(&self, url: &str) -> Result<(), String> {
+        let sid = self.session_id()?.to_string();
+        self.post(&format!("/session/{}/url", sid), &json!({ "url": url }))
+            .await?;
+        Ok(())
+    }
+
+    pub async fn get_url(&self) -> Result<String, String> {
+        let sid = self.session_id()?.to_string();
+        let response = self.get(&format!("/session/{}/url", sid)).await?;
+        Ok(response
+            .get("value")
+            .and_then(|v| v.as_str())
+            .unwrap_or("")
+            .to_string())
+    }
+
+    pub async fn get_title(&self) -> Result<String, String> {
+        let sid = self.session_id()?.to_string();
+        let response = self.get(&format!("/session/{}/title", sid)).await?;
+        Ok(response
+            .get("value")
+            .and_then(|v| v.as_str())
+            .unwrap_or("")
+            .to_string())
+    }
+
+    pub async fn find_element(&self, using: &str, value: &str) -> Result<String, String> {
+        let sid = self.session_id()?.to_string();
+        let response = self
+            .post(
+                &format!("/session/{}/element", sid),
+                &json!({ "using": using, "value": value }),
+            )
+            .await?;
+
+        let element_value = response.get("value").ok_or("No element in response")?;
+
+        element_value
+            .get("element-6066-11e4-a52e-4f735466cecf")
+            .or_else(|| element_value.get("ELEMENT"))
+            .and_then(|v| v.as_str())
+            .map(String::from)
+            .ok_or("No element ID in response".to_string())
+    }
+
+    pub async fn click_element(&self, element_id: &str) -> Result<(), String> {
+        let sid = self.session_id()?.to_string();
+        self.post(
+            &format!("/session/{}/element/{}/click", sid, element_id),
+            &json!({}),
+        )
+        .await?;
+        Ok(())
+    }
+
+    pub async fn send_keys(&self, element_id: &str, text: &str) -> Result<(), String> {
+        let sid = self.session_id()?.to_string();
+        self.post(
+            &format!("/session/{}/element/{}/value", sid, element_id),
+            &json!({ "text": text }),
+        )
+        .await?;
+        Ok(())
+    }
+
+    pub async fn clear_element(&self, element_id: &str) -> Result<(), String> {
+        let sid = self.session_id()?.to_string();
+        self.post(
+            &format!("/session/{}/element/{}/clear", sid, element_id),
+            &json!({}),
+        )
+        .await?;
+        Ok(())
+    }
+
+    pub async fn execute_script(&self, script: &str, args: Vec<Value>) -> Result<Value, String> {
+        let sid = self.session_id()?.to_string();
+        let response = self
+            .post(
+                &format!("/session/{}/execute/sync", sid),
+                &json!({ "script": script, "args": args }),
+            )
+            .await?;
+        Ok(response.get("value").cloned().unwrap_or(Value::Null))
+    }
+
+    pub async fn screenshot(&self) -> Result<String, String> {
+        let sid = self.session_id()?.to_string();
+        let response = self.get(&format!("/session/{}/screenshot", sid)).await?;
+        Ok(response
+            .get("value")
+            .and_then(|v| v.as_str())
+            .unwrap_or("")
+            .to_string())
+    }
+
+    pub async fn get_cookies(&self) -> Result<Value, String> {
+        let sid = self.session_id()?.to_string();
+        let response = self.get(&format!("/session/{}/cookie", sid)).await?;
+        Ok(response.get("value").cloned().unwrap_or(Value::Null))
+    }
+
+    pub async fn get_page_source(&self) -> Result<String, String> {
+        let sid = self.session_id()?.to_string();
+        let response = self.get(&format!("/session/{}/source", sid)).await?;
+        Ok(response
+            .get("value")
+            .and_then(|v| v.as_str())
+            .unwrap_or("")
+            .to_string())
+    }
+
+    pub async fn back(&self) -> Result<(), String> {
+        let sid = self.session_id()?.to_string();
+        self.post(&format!("/session/{}/back", sid), &json!({}))
+            .await?;
+        Ok(())
+    }
+
+    pub async fn forward(&self) -> Result<(), String> {
+        let sid = self.session_id()?.to_string();
+        self.post(&format!("/session/{}/forward", sid), &json!({}))
+            .await?;
+        Ok(())
+    }
+
+    pub async fn refresh(&self) -> Result<(), String> {
+        let sid = self.session_id()?.to_string();
+        self.post(&format!("/session/{}/refresh", sid), &json!({}))
+            .await?;
+        Ok(())
+    }
+
+    pub fn session_id_pub(&self) -> Option<&str> {
+        self.session_id.as_deref()
+    }
+
+    pub fn new_with_session(port: u16, session_id: String) -> Self {
+        Self {
+            base_url: format!("http://127.0.0.1:{}", port),
+            session_id: Some(session_id),
+        }
+    }
+
+    pub async fn execute_actions(&self, session_id: &str, actions: &Value) -> Result<(), String> {
+        self.post(&format!("/session/{}/actions", session_id), actions)
+            .await?;
+        Ok(())
+    }
+
+    fn session_id(&self) -> Result<&str, String> {
+        self.session_id
+            .as_deref()
+            .ok_or("No active WebDriver session".to_string())
+    }
+
+    async fn get(&self, path: &str) -> Result<Value, String> {
+        http_request("GET", &format!("{}{}", self.base_url, path), None).await
+    }
+
+    async fn post(&self, path: &str, body: &Value) -> Result<Value, String> {
+        http_request("POST", &format!("{}{}", self.base_url, path), Some(body)).await
+    }
+
+    async fn delete(&self, path: &str) -> Result<Value, String> {
+        http_request("DELETE", &format!("{}{}", self.base_url, path), None).await
+    }
+}
+
+async fn http_request(method: &str, url: &str, body: Option<&Value>) -> Result<Value, String> {
+    let parsed = url::Url::parse(url).map_err(|e| format!("Invalid URL: {}", e))?;
+    let host = parsed.host_str().unwrap_or("127.0.0.1");
+    let port = parsed.port().unwrap_or(80);
+    let path = parsed.path();
+
+    let addr = format!("{}:{}", host, port);
+    let stream = tokio::time::timeout(
+        Duration::from_secs(10),
+        tokio::net::TcpStream::connect(&addr),
+    )
+    .await
+    .map_err(|_| format!("Connection timeout: {}", addr))?
+    .map_err(|e| format!("Connection failed: {}", e))?;
+
+    use tokio::io::{AsyncReadExt, AsyncWriteExt};
+
+    let body_str = body
+        .map(|b| serde_json::to_string(b).unwrap_or_default())
+        .unwrap_or_default();
+
+    let request = if body.is_some() {
+        format!(
+            "{} {} HTTP/1.1\r\nHost: {}\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
+            method, path, addr, body_str.len(), body_str
+        )
+    } else {
+        format!(
+            "{} {} HTTP/1.1\r\nHost: {}\r\nConnection: close\r\n\r\n",
+            method, path, addr
+        )
+    };
+
+    let mut stream = stream;
+    stream
+        .write_all(request.as_bytes())
+        .await
+        .map_err(|e| format!("Write failed: {}", e))?;
+
+    let mut response = Vec::new();
+    stream
+        .read_to_end(&mut response)
+        .await
+        .map_err(|e| format!("Read failed: {}", e))?;
+
+    let response_str = String::from_utf8_lossy(&response);
+    let body_part = response_str.split("\r\n\r\n").nth(1).unwrap_or("").trim();
+
+    // Handle chunked encoding
+    let json_body = if body_part.contains('\n')
+        && body_part
+            .chars()
+            .next()
+            .map(|c| c.is_ascii_hexdigit())
+            .unwrap_or(false)
+    {
+        // Chunked: skip chunk size lines
+        body_part
+            .lines()
+            .filter(|l| !l.chars().all(|c| c.is_ascii_hexdigit() || c == '\r'))
+            .collect::<Vec<&str>>()
+            .join("")
+    } else {
+        body_part.to_string()
+    };
+
+    if json_body.is_empty() {
+        return Ok(json!({}));
+    }
+
+    serde_json::from_str(&json_body).map_err(|e| {
+        format!(
+            "Invalid JSON response: {} (body: {})",
+            e,
+            json_body.chars().take(100).collect::<String>()
+        )
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_client_new() {
+        let client = WebDriverClient::new(4444);
+        assert_eq!(client.base_url, "http://127.0.0.1:4444");
+        assert!(client.session_id.is_none());
+    }
+
+    #[test]
+    fn test_session_id_none() {
+        let client = WebDriverClient::new(4444);
+        let result = client.session_id();
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("No active WebDriver session"));
+    }
+
+    #[test]
+    fn test_client_custom_port() {
+        let client = WebDriverClient::new(9515);
+        assert_eq!(client.base_url, "http://127.0.0.1:9515");
+    }
+}

cli/src/native/webdriver/ios.rs

@@ -0,0 +1,235 @@
+use serde_json::{json, Value};
+use std::process::Command;
+
+#[derive(Debug, Clone)]
+pub struct IosDevice {
+    pub name: String,
+    pub udid: String,
+    pub state: String,
+    pub runtime: String,
+    pub is_real: bool,
+}
+
+pub fn list_simulators() -> Result<Vec<IosDevice>, String> {
+    let output = Command::new("xcrun")
+        .args(["simctl", "list", "devices", "--json"])
+        .output()
+        .map_err(|e| format!("Failed to run xcrun simctl: {}", e))?;
+
+    if !output.status.success() {
+        return Err("xcrun simctl failed. Xcode may not be installed.".to_string());
+    }
+
+    let json_str = String::from_utf8_lossy(&output.stdout);
+    let parsed: Value =
+        serde_json::from_str(&json_str).map_err(|e| format!("Failed to parse simctl: {}", e))?;
+
+    let mut devices = Vec::new();
+    if let Some(device_map) = parsed.get("devices").and_then(|v| v.as_object()) {
+        for (runtime, device_list) in device_map {
+            if let Some(arr) = device_list.as_array() {
+                for device in arr {
+                    let name = device
+                        .get("name")
+                        .and_then(|v| v.as_str())
+                        .unwrap_or("")
+                        .to_string();
+                    let udid = device
+                        .get("udid")
+                        .and_then(|v| v.as_str())
+                        .unwrap_or("")
+                        .to_string();
+                    let state = device
+                        .get("state")
+                        .and_then(|v| v.as_str())
+                        .unwrap_or("")
+                        .to_string();
+                    devices.push(IosDevice {
+                        name,
+                        udid,
+                        state,
+                        runtime: runtime.clone(),
+                        is_real: false,
+                    });
+                }
+            }
+        }
+    }
+    Ok(devices)
+}
+
+pub fn list_real_devices() -> Result<Vec<IosDevice>, String> {
+    let output = Command::new("xcrun")
+        .args(["xctrace", "list", "devices"])
+        .output()
+        .map_err(|e| format!("Failed to run xcrun xctrace: {}", e))?;
+
+    if !output.status.success() {
+        return Ok(Vec::new());
+    }
+
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    let mut devices = Vec::new();
+    let mut in_devices = false;
+
+    for line in stdout.lines() {
+        let trimmed = line.trim();
+        if trimmed.starts_with("== Devices ==") {
+            in_devices = true;
+            continue;
+        }
+        if trimmed.starts_with("== Simulators ==") {
+            break;
+        }
+        if !in_devices || trimmed.is_empty() {
+            continue;
+        }
+        // Format: "Device Name (OS Version) (UDID)"
+        if let Some(udid_start) = trimmed.rfind('(') {
+            let udid_end = trimmed.len() - 1;
+            let udid = &trimmed[udid_start + 1..udid_end];
+            // Validate it looks like a UDID (contains hyphens)
+            if udid.contains('-') && udid.len() > 20 {
+                let name_part = trimmed[..udid_start].trim();
+                let name = if let Some(paren_pos) = name_part.rfind('(') {
+                    name_part[..paren_pos].trim().to_string()
+                } else {
+                    name_part.to_string()
+                };
+                devices.push(IosDevice {
+                    name,
+                    udid: udid.to_string(),
+                    state: "Connected".to_string(),
+                    runtime: String::new(),
+                    is_real: true,
+                });
+            }
+        }
+    }
+
+    Ok(devices)
+}
+
+pub fn list_all_devices() -> Result<Vec<IosDevice>, String> {
+    let mut all = list_simulators().unwrap_or_default();
+    all.extend(list_real_devices().unwrap_or_default());
+    Ok(all)
+}
+
+pub fn boot_simulator(udid: &str) -> Result<(), String> {
+    let output = Command::new("xcrun")
+        .args(["simctl", "boot", udid])
+        .output()
+        .map_err(|e| format!("Failed to boot simulator: {}", e))?;
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        if stderr.contains("current state: Booted") {
+            return Ok(());
+        }
+        return Err(format!("Failed to boot simulator {}: {}", udid, stderr));
+    }
+    Ok(())
+}
+
+pub fn shutdown_simulator(udid: &str) -> Result<(), String> {
+    let output = Command::new("xcrun")
+        .args(["simctl", "shutdown", udid])
+        .output()
+        .map_err(|e| format!("Failed to shutdown simulator: {}", e))?;
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        if stderr.contains("current state: Shutdown") {
+            return Ok(());
+        }
+        return Err(format!("Failed to shutdown simulator {}: {}", udid, stderr));
+    }
+    Ok(())
+}
+
+pub fn select_device(device_name: Option<&str>, udid: Option<&str>) -> Result<IosDevice, String> {
+    if let Some(u) = udid {
+        let devices = list_all_devices()?;
+        return devices
+            .into_iter()
+            .find(|d| d.udid == u)
+            .ok_or_else(|| format!("Device with UDID '{}' not found", u));
+    }
+
+    if let Some(name) = device_name {
+        let devices = list_all_devices()?;
+        return devices
+            .into_iter()
+            .find(|d| d.name.to_lowercase().contains(&name.to_lowercase()))
+            .ok_or_else(|| format!("Device '{}' not found", name));
+    }
+
+    // Default: prefer most recent iPhone, prefer Pro
+    let devices = list_simulators()?;
+    let iphone_devices: Vec<&IosDevice> = devices
+        .iter()
+        .filter(|d| d.name.starts_with("iPhone"))
+        .collect();
+
+    if iphone_devices.is_empty() {
+        return devices
+            .into_iter()
+            .next()
+            .ok_or("No iOS simulators found".to_string());
+    }
+
+    // Prefer Pro models
+    if let Some(pro) = iphone_devices.iter().find(|d| d.name.contains("Pro")) {
+        return Ok((*pro).clone());
+    }
+
+    Ok((*iphone_devices.last().unwrap()).clone())
+}
+
+pub fn to_device_json(devices: &[IosDevice]) -> Value {
+    let list: Vec<Value> = devices
+        .iter()
+        .map(|d| {
+            json!({
+                "name": d.name,
+                "udid": d.udid,
+                "state": d.state,
+                "runtime": d.runtime,
+                "isReal": d.is_real,
+            })
+        })
+        .collect();
+    json!({ "devices": list })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_ios_device_struct() {
+        let device = IosDevice {
+            name: "iPhone 15 Pro".to_string(),
+            udid: "ABC-123".to_string(),
+            state: "Booted".to_string(),
+            runtime: "iOS-17-0".to_string(),
+            is_real: false,
+        };
+        assert_eq!(device.name, "iPhone 15 Pro");
+        assert!(!device.is_real);
+    }
+
+    #[test]
+    fn test_to_device_json() {
+        let devices = vec![IosDevice {
+            name: "Test".to_string(),
+            udid: "123".to_string(),
+            state: "Shutdown".to_string(),
+            runtime: "iOS-17".to_string(),
+            is_real: false,
+        }];
+        let json = to_device_json(&devices);
+        assert!(json.get("devices").unwrap().as_array().unwrap().len() == 1);
+    }
+}

cli/src/native/webdriver/mod.rs

@@ -0,0 +1,6 @@
+pub mod appium;
+pub mod backend;
+pub mod client;
+pub mod ios;
+pub mod safari;
+pub mod types;

cli/src/native/webdriver/safari.rs

@@ -0,0 +1,80 @@
+use std::path::PathBuf;
+use std::process::{Child, Command, Stdio};
+use std::time::Duration;
+
+pub struct SafariDriverProcess {
+    child: Child,
+    pub port: u16,
+}
+
+impl SafariDriverProcess {
+    pub fn kill(&mut self) {
+        let _ = self.child.kill();
+        let _ = self.child.wait();
+    }
+}
+
+impl Drop for SafariDriverProcess {
+    fn drop(&mut self) {
+        self.kill();
+    }
+}
+
+pub fn find_safaridriver() -> Option<PathBuf> {
+    let candidates = ["/usr/bin/safaridriver"];
+
+    for c in &candidates {
+        let p = PathBuf::from(c);
+        if p.exists() {
+            return Some(p);
+        }
+    }
+
+    // Try PATH
+    if let Ok(output) = Command::new("which").arg("safaridriver").output() {
+        if output.status.success() {
+            let path = String::from_utf8_lossy(&output.stdout).trim().to_string();
+            if !path.is_empty() {
+                return Some(PathBuf::from(path));
+            }
+        }
+    }
+
+    None
+}
+
+pub fn launch_safaridriver(port: u16) -> Result<SafariDriverProcess, String> {
+    let driver_path = find_safaridriver()
+        .ok_or("safaridriver not found. Safari WebDriver requires macOS with Safari.")?;
+
+    let child = Command::new(&driver_path)
+        .arg("--port")
+        .arg(port.to_string())
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .spawn()
+        .map_err(|e| format!("Failed to launch safaridriver: {}", e))?;
+
+    // Wait for driver to be ready
+    std::thread::sleep(Duration::from_millis(500));
+
+    Ok(SafariDriverProcess { child, port })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_find_safaridriver() {
+        // Only check on macOS
+        if cfg!(target_os = "macos") {
+            let result = find_safaridriver();
+            // Don't assert Some since it may not be enabled
+            if let Some(path) = result {
+                assert!(path.exists());
+            }
+        }
+    }
+}

cli/src/native/webdriver/types.rs

@@ -0,0 +1,97 @@
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct NewSessionRequest {
+    pub capabilities: Capabilities,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Capabilities {
+    pub always_match: Value,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SessionResponse {
+    pub value: SessionValue,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SessionValue {
+    pub session_id: String,
+    pub capabilities: Value,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct WebDriverResponse {
+    pub value: Value,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct WebDriverError {
+    pub error: String,
+    pub message: String,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ElementResponse {
+    pub value: ElementValue,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct ElementValue {
+    #[serde(rename = "element-6066-11e4-a52e-4f735466cecf")]
+    pub element_id: Option<String>,
+    #[serde(rename = "ELEMENT")]
+    pub element_legacy: Option<String>,
+}
+
+impl ElementValue {
+    pub fn id(&self) -> Option<&str> {
+        self.element_id
+            .as_deref()
+            .or(self.element_legacy.as_deref())
+    }
+}
+
+#[derive(Debug, Serialize)]
+pub struct FindElementRequest {
+    pub using: String,
+    pub value: String,
+}
+
+#[derive(Debug, Serialize)]
+pub struct ExecuteScriptRequest {
+    pub script: String,
+    pub args: Vec<Value>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CookieRequest {
+    pub cookie: CookieData,
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CookieData {
+    pub name: String,
+    pub value: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub domain: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub path: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub secure: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub http_only: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub expiry: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub same_site: Option<String>,
+}