@kritchoff/agent-browser 0.9.52 → 1.0.0

package/bin/agent-browser.js

@@ -57,7 +57,8 @@ async function main() {
       default:
         // Pass through arbitrary commands to the agent daemon
         // e.g. "agent-browser open https://google.com"
-        await agent.command(...filteredArgs);
+        const result = await agent.command(...filteredArgs);
+        console.log(result);
         break;
     }
   } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kritchoff/agent-browser",
-  "version": "0.9.52",
+  "version": "1.0.0",
   "description": "Headless browser automation CLI for AI agents",
   "type": "module",
   "main": "dist/index.js",
@@ -10,8 +10,6 @@
     "bin",
     "scripts",
     "skills",
-    "sdk.sh",
-    "start.sh",
     "docker-compose.sdk.yml"
   ],
   "bin": {

package/README.sdk.md

@@ -1,129 +0,0 @@
-# @wootzapp/agent-browser SDK
-
-The official Node.js SDK for controlling the WootzApp Agent Browser environment. 
-
-This SDK provides a **Real Android Browser** (WootzApp) wrapped in a Docker container, controlled by a high-speed Playwright daemon. It is specifically designed for AI Agents to navigate the mobile web, bypassing bot detection, and generating LLM-friendly semantic trees (AXTree).
-
-## Features
-
-- **Real Mobile Environment**: Full Android 14 OS with Touch Events and Mobile Viewports.
-- **Zero-Config Setup**: The SDK automatically downloads and orchestrates the required Docker containers.
-- **Hyper-Speed Warm Boots**: Uses advanced VDI Volume Mounting to boot the environment in **< 5 seconds** after the first run.
-- **Fast Resets**: Cleans the browser state via Android userspace reboot in **~15 seconds**.
-- **Playwright Parity**: Control the mobile browser using standard Playwright commands (`click`, `type`, `waitForSelector`).
-- **Semantic AXTree**: Built-in `snapshot()` method generates a clean, text-based UI tree optimized for LLM reasoning.
-
----
-
-## Prerequisites
-
-1.  **Docker Engine**: Must be installed and running.
-    - *Linux Users*: Ensure your user is in the `docker` group (`sudo usermod -aG docker $USER`).
-2.  **Node.js**: v18+ is required.
-
----
-
-## Installation
-
-Install the SDK in your project:
-
-```bash
-npm install @kritchoff/agent-browser
-```
-
-*(Optional but recommended)* Install `tsx` to run TypeScript files natively:
-```bash
-npm install -D tsx
-```
-
----
-
-## Quick Start Guide
-
-Create a file named `agent.ts`:
-
-```typescript
-import { WootzAgent } from '@kritchoff/agent-browser';
-
-async function main() {
-  // 1. Initialize the controller
-  const agent = new WootzAgent();
-
-  console.log('🚀 Booting Environment...');
-  // First run: Downloads 3GB image and cold boots (~90s).
-  // Next run: Instant Hyper-Speed Warm Boot (~5s).
-  await agent.start();
-
-  console.log('🌐 Navigating to Google...');
-  await agent.navigate('https://google.com');
-
-  console.log('📸 Capturing Semantic Tree for LLM...');
-  const uiTree = await agent.snapshot();
-  console.log(uiTree); 
-
-  console.log('⌨️ Typing and Searching...');
-  await agent.type('textarea[name="q"]', 'WootzApp AI');
-  await agent.press('Enter');
-
-  console.log('🧹 Fast Reset for next task...');
-  // Wipes all tabs, cookies, and cache in ~15s
-  await agent.reset(); 
-
-  console.log('🛑 Shutting down...');
-  // Completely destroys containers and releases ports
-  await agent.stop();
-}
-
-main().catch(console.error);
-```
-
-Run your agent:
-```bash
-npx tsx agent.ts
-```
-
----
-
-## CLI Usage (Global Install)
-
-You can also use the SDK directly from your terminal to debug or control the browser manually.
-
-```bash
-npm install -g @kritchoff/agent-browser
-
-# Start the environment
-agent-browser start
-
-# Run commands
-agent-browser navigate https://news.ycombinator.com
-agent-browser click ".titleline a"
-agent-browser snapshot
-
-# Clean the browser
-agent-browser reset
-
-# Stop
-agent-browser stop
-```
-
----
-
-## Troubleshooting
-
-### `Error: Failed to connect to agent daemon (ECONNREFUSED)`
-- **Cause**: The container failed to bind port `32001` to your host machine.
-- **Fix**: Run `agent.stop()` or `docker rm -f $(docker ps -aq)` to clear old/stuck containers, then run `agent.start()` again. The SDK has built-in self-healing, but a manual hard reset always works.
-
-### `net::ERR_NAME_NOT_RESOLVED`
-- **Cause**: The Android Emulator temporarily lost its internet connection after a Warm Boot.
-- **Fix**: The SDK automatically toggles Airplane Mode to fix this, but if it persists, ensure your host machine has a stable internet connection before starting the agent.
-
-### `Selector "..." matched X elements (Strict Mode Violation)`
-- **Cause**: Playwright requires selectors to point to exactly one element.
-- **Fix**: Use more specific selectors, or use Playwright's `>> nth=0` pseudo-selector to pick the first match (e.g., `agent.click('a >> nth=0')`).
-
----
-
-## Next Steps
-
-For a complete list of all available commands (clicking, typing, tabbing, network interception), please read the [COMMANDS.md](./COMMANDS.md) file.

package/scripts/fast_reset.sh

@@ -1,117 +0,0 @@
-#!/bin/bash
-# Fast Android environment reset using userspace reboot.
-#
-# This script resets the Android emulator state much faster (~15s) than
-# a full container restart (~60s). It uses 'adb reboot userspace' to
-# restart the Android framework while keeping the kernel running.
-#
-# Usage:
-#   ./scripts/fast_reset.sh
-
-set -e
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
-
-cd "$PROJECT_DIR"
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-NC='\033[0m' # No Color
-
-log_info() {
-    echo -e "${BLUE}[INFO]${NC} $1"
-}
-
-log_success() {
-    echo -e "${GREEN}[OK]${NC} $1"
-}
-
-log_warn() {
-    echo -e "${YELLOW}[WARN]${NC} $1"
-}
-
-log_error() {
-    echo -e "${RED}[ERROR]${NC} $1"
-}
-
-# Respect COMPOSE_FILE from environment, or auto-detect
-if [ -z "$COMPOSE_FILE" ]; then
-    if [ -f "$PROJECT_DIR/docker-compose.sdk.yml" ]; then
-        COMPOSE_FILE="$PROJECT_DIR/docker-compose.sdk.yml"
-    else
-        COMPOSE_FILE="$PROJECT_DIR/docker-compose.prod.yml"
-    fi
-fi
-
-# Detect container
-CONTAINER=$(docker compose -f "$COMPOSE_FILE" ps -q android-service)
-if [ -z "$CONTAINER" ]; then
-    log_error "android-service container not running."
-    exit 1
-fi
-
-ADB_CMD="docker exec $CONTAINER adb"
-
-log_info "Initiating fast reset (userspace reboot)..."
-
-# 1. Trigger userspace reboot
-# This command returns immediately and the device goes offline
-$ADB_CMD shell reboot userspace || true
-
-# 2. Wait for device to come back online
-log_info "Waiting for device to come online..."
-start_time=$(date +%s)
-timeout=30
-
-while true; do
-    current_time=$(date +%s)
-    elapsed=$((current_time - start_time))
-    
-    if [ $elapsed -gt $timeout ]; then
-        log_error "Timeout waiting for device after ${timeout}s"
-        exit 1
-    fi
-
-    # Check if device is visible to ADB and state is 'device'
-    if $ADB_CMD get-state 2>/dev/null | grep -q "device"; then
-        # Verify shell is responsive
-        if $ADB_CMD shell echo ok 2>/dev/null | grep -q "ok"; then
-            break
-        fi
-    fi
-    
-    sleep 1
-done
-
-log_success "Device online (${elapsed}s)"
-
-# 3. Wait for CDP (Chrome DevTools Protocol)
-log_info "Waiting for browser CDP..."
-cdp_timeout=30
-cdp_start_time=$(date +%s)
-
-while true; do
-    current_time=$(date +%s)
-    elapsed=$((current_time - cdp_start_time))
-    
-    if [ $elapsed -gt $cdp_timeout ]; then
-        log_warn "Timeout waiting for CDP. Browser might not have autostarted."
-        log_info "Attempting to start browser manually..."
-        $ADB_CMD shell am start -n com.wootzapp.web/com.aspect.chromium.ChromiumMain -a android.intent.action.VIEW -d 'about:blank'
-        sleep 2
-    fi
-
-    # Check CDP version endpoint
-    if docker exec $CONTAINER curl -s --connect-timeout 2 http://localhost:9224/json/version >/dev/null; then
-        break
-    fi
-    
-    sleep 1
-done
-
-log_success "Browser CDP ready"
-log_success "Fast reset complete!"

package/scripts/snapshot_manager.sh

@@ -1,293 +0,0 @@
-#!/bin/bash
-# Emulator snapshot import/export utility
-#
-# Manages Android emulator snapshots for agent-browser.
-# Snapshots are stored in the emulator's AVD directory and can be
-# exported as compressed tar.gz files for sharing or backup.
-#
-# Usage:
-#   ./scripts/snapshot_manager.sh export <name> <output.tar.gz>
-#   ./scripts/snapshot_manager.sh import <input.tar.gz> [name]
-#   ./scripts/snapshot_manager.sh list
-#   ./scripts/snapshot_manager.sh validate <name>
-#
-# Examples:
-#   # Export current snapshot for sharing
-#   ./scripts/snapshot_manager.sh export w8rl_clean ./my_snapshot.tar.gz
-#
-#   # Import a snapshot from a file
-#   ./scripts/snapshot_manager.sh import ./my_snapshot.tar.gz
-#
-#   # Import with a different name
-#   ./scripts/snapshot_manager.sh import ./my_snapshot.tar.gz imported_snapshot
-#
-#   # List all available snapshots
-#   ./scripts/snapshot_manager.sh list
-#
-#   # Validate a snapshot is not corrupt
-#   ./scripts/snapshot_manager.sh validate w8rl_clean
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
-
-cd "$PROJECT_DIR"
-
-# Respect COMPOSE_FILE from environment
-COMPOSE_FILE="${COMPOSE_FILE:-docker-compose.prod.yml}"
-
-# Detect container name using docker compose
-CONTAINER=$(docker compose -f "$COMPOSE_FILE" ps -q android-service)
-if [ -z "$CONTAINER" ]; then
-    echo "Error: android-service container not running."
-    exit 1
-fi
-
-AVD_NAME="${EMULATOR_NAME:-Pixel_6_API_34}"
-SNAPSHOT_BASE="/root/.android/avd/${AVD_NAME}.avd/snapshots"
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-NC='\033[0m' # No Color
-
-log_info() {
-    echo -e "${BLUE}[INFO]${NC} $1"
-}
-
-log_success() {
-    echo -e "${GREEN}[OK]${NC} $1"
-}
-
-log_warn() {
-    echo -e "${YELLOW}[WARN]${NC} $1"
-}
-
-log_error() {
-    echo -e "${RED}[ERROR]${NC} $1"
-}
-
-# Check if container is running
-check_container() {
-    # Use docker inspect for reliable status check (avoids SIGPIPE with grep -q)
-    if [ "$(docker inspect -f '{{.State.Running}}' "$CONTAINER" 2>/dev/null)" != "true" ]; then
-        log_error "Container '${CONTAINER}' is not running"
-        log_info "Start it with: docker compose -f ${COMPOSE_FILE} up -d android-service"
-        exit 1
-    fi
-}
-
-# Validate a snapshot has all required files and is not corrupt
-validate_snapshot_internal() {
-    local name="$1"
-    local snapshot_dir="${SNAPSHOT_BASE}/${name}"
-    local valid=true
-
-    log_info "Validating snapshot '${name}'..."
-
-    for file in ram.bin snapshot.pb hardware.ini; do
-        if docker exec "$CONTAINER" test -f "${snapshot_dir}/${file}"; then
-            local size
-            size=$(docker exec "$CONTAINER" stat -c%s "${snapshot_dir}/${file}")
-            echo -e "  ${GREEN}✓${NC} ${file}: ${size} bytes"
-        else
-            echo -e "  ${RED}✗${NC} ${file}: MISSING"
-            valid=false
-        fi
-    done
-
-    # Check ram.bin size (must be >= 1MB)
-    if docker exec "$CONTAINER" test -f "${snapshot_dir}/ram.bin"; then
-        local ram_size
-        ram_size=$(docker exec "$CONTAINER" stat -c%s "${snapshot_dir}/ram.bin")
-        if [ "$ram_size" -lt 1000000 ]; then
-            echo -e "  ${RED}✗${NC} ram.bin too small (${ram_size} bytes, expected >= 1MB)"
-            valid=false
-        fi
-    fi
-
-    if [ "$valid" = true ]; then
-        log_success "Snapshot validation passed"
-        return 0
-    else
-        log_error "Snapshot validation failed"
-        return 1
-    fi
-}
-
-# Export a snapshot to a tar.gz file
-cmd_export() {
-    local name="${1:?Usage: $0 export <name> <output.tar.gz>}"
-    local output="${2:?Usage: $0 export <name> <output.tar.gz>}"
-
-    check_container
-
-    # Validate snapshot exists
-    if ! docker exec "$CONTAINER" test -d "${SNAPSHOT_BASE}/${name}"; then
-        log_error "Snapshot '${name}' does not exist"
-        exit 1
-    fi
-
-    log_info "Exporting snapshot '${name}' to ${output}..."
-
-    # Validate before export
-    if ! validate_snapshot_internal "$name"; then
-        log_error "Cannot export invalid snapshot"
-        exit 1
-    fi
-
-    # Create tar.gz from snapshot directory
-    docker exec "$CONTAINER" tar -czf - -C "$SNAPSHOT_BASE" "$name" > "$output"
-
-    local size
-    size=$(ls -lh "$output" | awk '{print $5}')
-    log_success "Exported: ${output} (${size})"
-}
-
-# Import a snapshot from a tar.gz file
-cmd_import() {
-    local input="${1:?Usage: $0 import <input.tar.gz> [name]}"
-
-    # Extract original name from tar
-    # Disable pipefail to avoid SIGPIPE from tar | head
-    set +o pipefail
-    local original_name
-    original_name=$(tar -tzf "$input" 2>/dev/null | head -1 | cut -d'/' -f1)
-    set -o pipefail
-
-    local name="${2:-$original_name}"
-
-    if [ -z "$name" ]; then
-        log_error "Could not determine snapshot name from archive"
-        exit 1
-    fi
-
-    check_container
-
-    log_info "Importing snapshot from ${input} as '${name}'..."
-
-    # Ensure snapshot directory exists
-    docker exec "$CONTAINER" mkdir -p "$SNAPSHOT_BASE"
-
-    # Remove existing snapshot if present
-    if docker exec "$CONTAINER" test -d "${SNAPSHOT_BASE}/${name}"; then
-        log_warn "Removing existing snapshot '${name}'..."
-        docker exec "$CONTAINER" rm -rf "${SNAPSHOT_BASE}/${name}"
-    fi
-
-    # Extract snapshot into container
-    # Use 'docker cp' to avoid stdin pipe issues
-    log_info "Copying archive to container..."
-    docker cp "$input" "$CONTAINER:/tmp/import_snapshot.tar.gz"
-
-    log_info "Extracting archive..."
-    if ! docker exec "$CONTAINER" tar -xzf /tmp/import_snapshot.tar.gz -C "$SNAPSHOT_BASE"; then
-        log_error "Failed to extract snapshot archive"
-        docker exec "$CONTAINER" rm -f /tmp/import_snapshot.tar.gz
-        exit 1
-    fi
-
-    # Clean up
-    docker exec "$CONTAINER" rm -f /tmp/import_snapshot.tar.gz
-
-    # If renaming, move the extracted directory
-    if [ "$name" != "$original_name" ]; then
-        docker exec "$CONTAINER" mv "${SNAPSHOT_BASE}/${original_name}" "${SNAPSHOT_BASE}/${name}"
-    fi
-
-    # Validate after import
-    if validate_snapshot_internal "$name"; then
-        log_success "Import completed successfully"
-        docker exec "$CONTAINER" ls -lh "${SNAPSHOT_BASE}/${name}/"
-    else
-        log_error "Import failed - snapshot validation failed"
-        exit 1
-    fi
-}
-
-# List all snapshots
-cmd_list() {
-    check_container
-
-    log_info "Available snapshots in ${CONTAINER}:"
-    echo ""
-
-    if docker exec "$CONTAINER" test -d "$SNAPSHOT_BASE"; then
-        docker exec "$CONTAINER" ls -la "$SNAPSHOT_BASE" 2>/dev/null | tail -n +2 || echo "  (none)"
-
-        echo ""
-        log_info "Snapshot details:"
-        for snapshot in $(docker exec "$CONTAINER" ls "$SNAPSHOT_BASE" 2>/dev/null); do
-            local snapshot_dir="${SNAPSHOT_BASE}/${snapshot}"
-            if docker exec "$CONTAINER" test -d "$snapshot_dir"; then
-                local ram_size
-                ram_size=$(docker exec "$CONTAINER" stat -c%s "${snapshot_dir}/ram.bin" 2>/dev/null || echo "0")
-                local ram_mb=$((ram_size / 1024 / 1024))
-                echo "  ${snapshot}: ${ram_mb}MB RAM"
-            fi
-        done
-    else
-        echo "  No snapshots found (snapshot directory does not exist)"
-    fi
-}
-
-# Validate a snapshot
-cmd_validate() {
-    local name="${1:?Usage: $0 validate <name>}"
-
-    check_container
-
-    if ! docker exec "$CONTAINER" test -d "${SNAPSHOT_BASE}/${name}"; then
-        log_error "Snapshot '${name}' does not exist"
-        exit 1
-    fi
-
-    validate_snapshot_internal "$name"
-}
-
-# Show usage
-usage() {
-    echo "Usage: $0 {export|import|list|validate} [args...]"
-    echo ""
-    echo "Commands:"
-    echo "  export <name> <output.tar.gz>  Export a snapshot to a file"
-    echo "  import <input.tar.gz> [name]   Import a snapshot from a file"
-    echo "  list                           List all available snapshots"
-    echo "  validate <name>                Validate a snapshot is not corrupt"
-    echo ""
-    echo "Examples:"
-    echo "  $0 export w8rl_clean ./my_snapshot.tar.gz"
-    echo "  $0 import ./my_snapshot.tar.gz"
-    echo "  $0 import ./my_snapshot.tar.gz custom_name"
-    echo "  $0 list"
-    echo "  $0 validate w8rl_clean"
-}
-
-# Main command dispatch
-case "${1:-}" in
-    export)
-        shift
-        cmd_export "$@"
-        ;;
-    import)
-        shift
-        cmd_import "$@"
-        ;;
-    list)
-        cmd_list
-        ;;
-    validate)
-        shift
-        cmd_validate "$@"
-        ;;
-    -h|--help|help)
-        usage
-        ;;
-    *)
-        usage
-        exit 1
-        ;;
-esac

package/scripts/vaccine-run

@@ -1,26 +0,0 @@
-#!/bin/bash
-exec 2>&1
-
-echo "[vaccine] Waiting for emulator..."
-adb wait-for-device
-
-echo "[vaccine] Waiting for boot completion..."
-while [[ -z $(adb shell getprop sys.boot_completed) ]]; do sleep 1; done
-
-echo "[vaccine] Waiting for Package Manager..."
-while ! adb shell pm list packages > /dev/null 2>&1; do sleep 1; done
-
-echo "[vaccine] Applying permissions to org.chromium.chrome (WootzApp)..."
-adb shell pm grant org.chromium.chrome android.permission.ACCESS_FINE_LOCATION || true
-adb shell pm grant org.chromium.chrome android.permission.CAMERA || true
-adb shell pm grant org.chromium.chrome android.permission.RECORD_AUDIO || true
-
-# Fallback for standard Chrome if present
-adb shell pm grant com.android.chrome android.permission.ACCESS_FINE_LOCATION || true
-adb shell pm grant com.android.chrome android.permission.CAMERA || true
-adb shell pm grant com.android.chrome android.permission.RECORD_AUDIO || true
-
-echo "[vaccine] Permissions granted."
-
-# Prevent restart
-touch /etc/services.d/vaccine/down