@kritchoff/agent-browser 0.9.46 → 0.9.49

package/README.sdk.md

@@ -1,77 +1,129 @@
 # @wootzapp/agent-browser SDK
 
-The official SDK for controlling the WootzApp Agent Browser environment. This package provides a seamless, Docker-based Android browser for AI agents with instant startup times.
+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
 
-- **Zero-Config Setup**: Automatically pulls and runs the Docker environment.
-- **Instant Boot**: Uses VDI Snapshots to start the browser in ~20s.
-- **Fast Reset**: Clears browser state in ~15s for high-speed agent loops.
-- **Headless Control**: Full programmatic access via Node.js.
+- **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
 
-- **Docker**: Must be installed and running.
-- **Node.js**: v18+.
+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
 ```
 
-## Quick Start
+*(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('Starting environment...');
-  // First run: ~90s (Cold Boot + Snapshot Creation)
-  // Subsequent runs: ~20s (Warm Boot)
+  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('Opening Google...');
-  await agent.command('open', 'https://google.com');
+  console.log('🌐 Navigating to Google...');
+  await agent.navigate('https://google.com');
 
-  // ... perform agent tasks ...
+  console.log('📸 Capturing Semantic Tree for LLM...');
+  const uiTree = await agent.snapshot();
+  console.log(uiTree); 
 
-  console.log('Resetting browser for next task...');
-  // Fast Reset: ~15s (Clears tabs/cookies/cache)
-  await agent.reset();
+  console.log('⌨️ Typing and Searching...');
+  await agent.type('textarea[name="q"]', 'WootzApp AI');
+  await agent.press('Enter');
 
-  console.log('Stopping environment...');
+  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);
 ```
 
-## How It Works
+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
+```
+
+---
 
-1.  **First Run**: The SDK pulls the heavy Docker image (~3GB) and performs a "Cold Boot". Once the emulator is ready, it automatically saves a "Baseline Snapshot" to your local cache.
-2.  **Subsequent Runs**: The SDK detects the snapshot and performs a "Warm Boot", injecting the saved state directly into memory. This bypasses the Android boot sequence.
-3.  **Reset**: Instead of restarting the container, `agent.reset()` triggers an Android userspace reboot, which is significantly faster than a full system restart.
+## Troubleshooting
 
-## API Reference
+### `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.
 
-### `new WootzAgent(options?)`
-Creates a new agent instance.
-- `options.dist` (boolean): Whether to pull pre-built images (default: `true`).
+### `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.
 
-### `agent.start()`
-Starts the Android Emulator and Agent Service. Handles snapshot creation automatically.
+### `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')`).
 
-### `agent.stop()`
-Stops the Docker containers gracefully.
+---
 
-### `agent.reset()`
-Performs a fast reset of the browser environment without stopping the container. Use this between agent tasks to ensure a clean state.
+## Next Steps
 
-### `agent.command(action, ...args)`
-Executes a raw agent command.
-- `agent.command('open', 'url')`
-- `agent.command('click', '@e1')`
-- `agent.command('type', '@e2', 'hello')`
+For a complete list of all available commands (clicking, typing, tabbing, network interception), please read the [COMMANDS.md](./COMMANDS.md) file.

package/dist/orchestrator.d.ts

@@ -0,0 +1,14 @@
+export declare class Orchestrator {
+    private composeFile;
+    constructor(distMode: boolean);
+    private log;
+    private runCommand;
+    private getContainerId;
+    private isPortMapped;
+    private pullImagesWithRetry;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    reset(): Promise<void>;
+    private waitForLog;
+}
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../src/orchestrator.ts"],"names":[],"mappings":"AAUA,qBAAa,YAAY;IACvB,OAAO,CAAC,WAAW,CAAS;gBAEhB,QAAQ,EAAE,OAAO;IAS7B,OAAO,CAAC,GAAG;IAWX,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,YAAY;YASN,mBAAmB;IAkBpB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoFtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAMrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA4DnC,OAAO,CAAC,UAAU;CAmBnB"}

package/dist/orchestrator.js

@@ -0,0 +1,225 @@
+import { spawn, execSync } from 'child_process';
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = path.resolve(__dirname, '..');
+const CACHE_DIR = path.join(PROJECT_ROOT, 'cache');
+const SNAPSHOT_DIR = path.join(CACHE_DIR, 'snapshots', 'quickboot');
+export class Orchestrator {
+    composeFile;
+    constructor(distMode) {
+        this.composeFile = path.join(PROJECT_ROOT, distMode ? 'docker-compose.sdk.yml' : 'docker-compose.prod.yml');
+        // Ensure cache dir exists
+        if (!fs.existsSync(path.join(CACHE_DIR, 'snapshots'))) {
+            fs.mkdirSync(path.join(CACHE_DIR, 'snapshots'), { recursive: true });
+        }
+    }
+    log(msg, level = 'info') {
+        const colors = {
+            info: '\x1b[34m', // Blue
+            success: '\x1b[32m', // Green
+            warn: '\x1b[33m', // Yellow
+            error: '\x1b[31m', // Red
+            reset: '\x1b[0m'
+        };
+        console.log(`${colors[level]}[SDK]${colors.reset} ${msg}`);
+    }
+    runCommand(cmd, env = {}) {
+        try {
+            execSync(cmd, {
+                stdio: 'inherit',
+                env: { ...process.env, ...env }
+            });
+            return true;
+        }
+        catch (e) {
+            return false;
+        }
+    }
+    getContainerId(serviceName) {
+        try {
+            const output = execSync(`docker compose -f "${this.composeFile}" ps -q ${serviceName}`, { encoding: 'utf-8' });
+            return output.trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    isPortMapped(containerId, port) {
+        try {
+            execSync(`docker port "${containerId}" ${port}`, { stdio: 'ignore' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async pullImagesWithRetry() {
+        if (!this.composeFile.endsWith('docker-compose.sdk.yml'))
+            return;
+        this.log("Please wait while we get things ready...", 'info');
+        const maxRetries = 10;
+        for (let count = 0; count < maxRetries; count++) {
+            if (this.runCommand(`docker compose -f "${this.composeFile}" pull`)) {
+                return;
+            }
+            this.log(`Download failed/interrupted. Retrying (${count + 1}/${maxRetries}) in 10s...`, 'warn');
+            await new Promise(r => setTimeout(r, 10000));
+        }
+        this.log(`Failed to download images after ${maxRetries} attempts. Check internet connection.`, 'error');
+        process.exit(1);
+    }
+    async start() {
+        this.log(`Initializing Agent Environment...`, 'info');
+        // 1. Pull Images (Robustness)
+        await this.pullImagesWithRetry();
+        // 2. Clean previous state to prevent network namespace corruption
+        this.log("Cleaning up previous container state...", 'info');
+        this.runCommand(`docker compose -f "${this.composeFile}" down -v --remove-orphans`);
+        const hasSnapshot = fs.existsSync(SNAPSHOT_DIR);
+        if (hasSnapshot) {
+            // === WARM START ===
+            this.log("Found cached baseline snapshot. Performing HYPER-SPEED WARM BOOT...", 'success');
+            const success = this.runCommand(`docker compose -f "${this.composeFile}" up -d`, {
+                EMULATOR_SNAPSHOT_NAME: 'quickboot'
+            });
+            if (!success)
+                throw new Error("Startup failed during docker compose up.");
+            // Verify Port Mapping
+            const agentCont = this.getContainerId('agent-service');
+            if (agentCont && !this.isPortMapped(agentCont, 3000)) {
+                this.log("Port 3000 (Host 32001) is not mapped! Container config is stale.", 'warn');
+                this.log("Forcing full restart to apply network settings...", 'info');
+                this.runCommand(`docker compose -f "${this.composeFile}" down -v --remove-orphans`);
+                await new Promise(r => setTimeout(r, 5000)); // Wait for OS port release
+                this.runCommand(`docker compose -f "${this.composeFile}" up -d`, {
+                    EMULATOR_SNAPSHOT_NAME: 'quickboot'
+                });
+            }
+        }
+        else {
+            // === COLD START ===
+            this.log("No baseline found. Performing FIRST RUN SETUP (Cold Boot)...", 'warn');
+            this.log("This will take ~60-90 seconds, but only once.", 'warn');
+            const success = this.runCommand(`docker compose -f "${this.composeFile}" up -d`, {
+                EMULATOR_SNAPSHOT_NAME: ''
+            });
+            if (!success)
+                throw new Error("Startup failed during docker compose up.");
+            let androidCont = this.getContainerId('android-service');
+            const agentCont = this.getContainerId('agent-service');
+            if (!androidCont)
+                throw new Error("Error: Android container not found.");
+            // Verify Port Mapping
+            if (agentCont && !this.isPortMapped(agentCont, 3000)) {
+                this.log("Port 3000 (Host 32001) is not mapped! Container config is stale.", 'warn');
+                this.log("Forcing full restart to apply network settings...", 'info');
+                this.runCommand(`docker compose -f "${this.composeFile}" down -v --remove-orphans`);
+                await new Promise(r => setTimeout(r, 5000));
+                this.runCommand(`docker compose -f "${this.composeFile}" up -d`, {
+                    EMULATOR_SNAPSHOT_NAME: ''
+                });
+                androidCont = this.getContainerId('android-service') || androidCont;
+            }
+            // Wait for Android to boot fully
+            this.log("Waiting for Android OS to boot (this takes a moment)...", 'info');
+            await this.waitForLog(androidCont, "Emulator boot complete");
+            this.log("Waiting for Browser Installation...", 'info');
+            await this.waitForLog(androidCont, "APK installation complete");
+            this.log("Waiting for CDP Bridge...", 'info');
+            await this.waitForLog(androidCont, "CDP Bridge ready");
+            // Save Snapshot
+            this.log("Saving emulator state (quickboot)...", 'info');
+            const saved = this.runCommand(`docker exec "${androidCont}" adb emu avd snapshot save quickboot`);
+            if (saved) {
+                this.log("Snapshot saved to host volume.", 'success');
+                this.log("Setup Complete! Future runs will launch instantly.", 'success');
+            }
+            else {
+                throw new Error("Failed to save snapshot inside emulator.");
+            }
+        }
+    }
+    async stop() {
+        this.log("Stopping environment...", 'info');
+        this.runCommand(`docker compose -f "${this.composeFile}" down -v --remove-orphans`);
+        this.log("Environment cleaned and stopped.", 'success');
+    }
+    async reset() {
+        this.log("Performing Fast Browser Reset...", 'info');
+        const androidCont = this.getContainerId('android-service');
+        if (!androidCont) {
+            this.log("Android container not running.", 'error');
+            return;
+        }
+        this.log("Initiating fast reset (userspace reboot)...", 'info');
+        try {
+            execSync(`docker exec "${androidCont}" adb shell reboot userspace`, { stdio: 'ignore' });
+        }
+        catch {
+            // Ignored, command drops connection
+        }
+        this.log("Waiting for device to come online...", 'info');
+        const start = Date.now();
+        let online = false;
+        while (Date.now() - start < 30000) {
+            try {
+                const state = execSync(`docker exec "${androidCont}" adb get-state`, { encoding: 'utf-8' }).trim();
+                if (state === 'device') {
+                    execSync(`docker exec "${androidCont}" adb shell echo ok`, { stdio: 'ignore' });
+                    online = true;
+                    break;
+                }
+            }
+            catch {
+                // Still offline
+            }
+            await new Promise(r => setTimeout(r, 1000));
+        }
+        if (!online)
+            throw new Error("Timeout waiting for device after reboot");
+        this.log("Device online", 'success');
+        this.log("Waiting for browser CDP...", 'info');
+        const cdpStart = Date.now();
+        let cdpReady = false;
+        while (Date.now() - cdpStart < 30000) {
+            try {
+                execSync(`docker exec "${androidCont}" curl -s --connect-timeout 2 http://localhost:9224/json/version`, { stdio: 'ignore' });
+                cdpReady = true;
+                break;
+            }
+            catch {
+                // If it takes too long, try forcing the browser to open
+                if (Date.now() - cdpStart > 15000) {
+                    try {
+                        execSync(`docker exec "${androidCont}" adb shell am start -n com.wootzapp.web/com.aspect.chromium.ChromiumMain -a android.intent.action.VIEW -d 'about:blank'`, { stdio: 'ignore' });
+                    }
+                    catch { }
+                }
+            }
+            await new Promise(r => setTimeout(r, 1000));
+        }
+        if (!cdpReady)
+            throw new Error("Timeout waiting for CDP");
+        this.log("Fast reset complete!", 'success');
+    }
+    waitForLog(container, pattern) {
+        return new Promise((resolve) => {
+            const tail = spawn('docker', ['logs', '-f', container]);
+            tail.stdout.on('data', (data) => {
+                if (data.toString().includes(pattern)) {
+                    tail.kill();
+                    resolve();
+                }
+            });
+            tail.stderr.on('data', (data) => {
+                if (data.toString().includes(pattern)) {
+                    tail.kill();
+                    resolve();
+                }
+            });
+        });
+    }
+}
+//# sourceMappingURL=orchestrator.js.map

package/dist/orchestrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.js","sourceRoot":"","sources":["../src/orchestrator.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kritchoff/agent-browser",
-  "version": "0.9.46",
+  "version": "0.9.49",
   "description": "Headless browser automation CLI for AI agents",
   "type": "module",
   "main": "dist/index.js",

package/sdk.sh

@@ -89,16 +89,6 @@ cmd_start() {
         log_success "Found cached baseline snapshot. Performing HYPER-SPEED WARM BOOT..."
         export EMULATOR_SNAPSHOT_NAME="quickboot"
         "$SDK_ROOT/start.sh"
-        
-        cd "$SDK_ROOT"
-        AGENT_CONT=$(docker compose ps -q agent-service)
-        if [ -n "$AGENT_CONT" ] && ! docker port "$AGENT_CONT" 3000 >/dev/null 2>&1; then
-            log_warn "Port 3000 (Host 32001) is not mapped! Container config is stale."
-            log_info "Forcing full restart to apply network settings..."
-            docker compose -f "$COMPOSE_FILE" down -v --remove-orphans
-            sleep 5
-            "$SDK_ROOT/start.sh"
-        fi
     else
         # === COLD START & FREEZE ===
         log_warn "No baseline found. Performing FIRST RUN SETUP (Cold Boot)..."
@@ -117,22 +107,12 @@ cmd_start() {
 
         cd "$SDK_ROOT"
         CONTAINER=$(docker compose ps -q android-service)
-        AGENT_CONT=$(docker compose ps -q agent-service)
         
         if [ -z "$CONTAINER" ]; then
             log_error "Error: Android container not found."
             exit 1
         fi
 
-        if ! docker port "$AGENT_CONT" 3000 >/dev/null 2>&1; then
-            log_warn "Port 3000 (Host 32001) is not mapped! Container config is stale."
-            log_info "Forcing full restart to apply network settings..."
-            docker compose -f "$COMPOSE_FILE" down -v --remove-orphans
-            sleep 5
-            "$SDK_ROOT/start.sh"
-            CONTAINER=$(docker compose ps -q android-service)
-        fi
-
         log_info "Saving emulator state (quickboot)..."
         if docker exec "$CONTAINER" adb emu avd snapshot save quickboot; then
              log_success "Snapshot saved to host volume."

package/start.sh

@@ -64,19 +64,28 @@ wait_for_log() {
     
     echo -n "      Waiting for $label... "
     until docker logs "$container" 2>&1 | grep -q "$pattern"; do
-        sleep 2
+        sleep 1 # Faster polling
     done
     echo -e "${GREEN}Done!${NC}"
 }
 
-wait_for_log "$ANDROID_CONTAINER" "Emulator boot complete" "Android Emulator Boot"
-wait_for_log "$ANDROID_CONTAINER" "APK installation complete" "WootzApp Installation"
-wait_for_log "$ANDROID_CONTAINER" "CDP Bridge ready" "CDP Bridge"
-# Daemon logs "Daemon listening on TCP 0.0.0.0:3000" in direct mode
+if [ -z "$SNAPSHOT_PATH" ] && [ -z "$EMULATOR_SNAPSHOT_NAME" ]; then
+    # --- COLD BOOT PATH (Wait for everything) ---
+    wait_for_log "$ANDROID_CONTAINER" "Emulator boot complete" "Android Emulator Boot"
+    wait_for_log "$ANDROID_CONTAINER" "APK installation complete" "WootzApp Installation"
+    wait_for_log "$ANDROID_CONTAINER" "CDP Bridge ready" "CDP Bridge"
+else
+    # --- WARM BOOT PATH (Hyper-Speed) ---
+    # We skip Boot and APK installation because they are inside the snapshot.
+    # We only wait for the Daemon to reconnect to the resumed emulator.
+    echo -e "${GREEN}      Snapshot detected. Skipping OS boot and APK install waits.${NC}"
+fi
+
+# We always wait for the Daemon because it's the final bridge to the SDK
 wait_for_log "$AGENT_CONTAINER" "Daemon listening on TCP" "Agent Daemon Connection"
 
 # 3.5 Network Rehydration (Warm Boot Only)
-if [ -n "$SNAPSHOT_PATH" ]; then
+if [ -n "$SNAPSHOT_PATH" ] || [ -n "$EMULATOR_SNAPSHOT_NAME" ]; then
     echo "      Rehydrating Android network connection..."
     # Toggle airplane mode to force DHCP lease renewal
     docker exec "$ANDROID_CONTAINER" adb shell cmd connectivity airplane-mode enable