@kritchoff/agent-browser 0.9.2

package/README.sdk.md

@@ -0,0 +1,77 @@
+# @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.
+
+## 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.
+
+## Prerequisites
+
+- **Docker**: Must be installed and running.
+- **Node.js**: v18+.
+
+## Installation
+
+```bash
+npm install @wootzapp/agent-browser
+```
+
+## Quick Start
+
+```typescript
+import { WootzAgent } from '@wootzapp/agent-browser';
+
+async function main() {
+  const agent = new WootzAgent();
+
+  console.log('Starting environment...');
+  // First run: ~90s (Cold Boot + Snapshot Creation)
+  // Subsequent runs: ~20s (Warm Boot)
+  await agent.start();
+
+  console.log('Opening Google...');
+  await agent.command('open', 'https://google.com');
+
+  // ... perform agent tasks ...
+
+  console.log('Resetting browser for next task...');
+  // Fast Reset: ~15s (Clears tabs/cookies/cache)
+  await agent.reset();
+
+  console.log('Stopping environment...');
+  await agent.stop();
+}
+
+main().catch(console.error);
+```
+
+## How It Works
+
+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.
+
+## API Reference
+
+### `new WootzAgent(options?)`
+Creates a new agent instance.
+- `options.dist` (boolean): Whether to pull pre-built images (default: `true`).
+
+### `agent.start()`
+Starts the Android Emulator and Agent Service. Handles snapshot creation automatically.
+
+### `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.
+
+### `agent.command(action, ...args)`
+Executes a raw agent command.
+- `agent.command('open', 'url')`
+- `agent.command('click', '@e1')`
+- `agent.command('type', '@e2', 'hello')`

package/bin/agent-browser.js

@@ -0,0 +1,109 @@
+#!/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 } 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));
+
+// 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 = '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();

package/dist/actions.d.ts

@@ -0,0 +1,17 @@
+import type { BrowserManager, ScreencastFrame } from './browser.js';
+import type { Command, Response } from './types.js';
+/**
+ * Set the callback for screencast frames
+ * This is called by the daemon to set up frame streaming
+ */
+export declare function setScreencastFrameCallback(callback: ((frame: ScreencastFrame) => void) | null): void;
+/**
+ * Convert Playwright errors to AI-friendly messages
+ * @internal Exported for testing
+ */
+export declare function toAIFriendlyError(error: unknown, selector: string): Error;
+/**
+ * Execute a command and return a response
+ */
+export declare function executeCommand(command: Command, browser: BrowserManager): Promise<Response>;
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpE,OAAO,KAAK,EACV,OAAO,EACP,QAAQ,EAqHT,MAAM,YAAY,CAAC;AAMpB;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,CAAC,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC,GAAG,IAAI,GAClD,IAAI,CAEN;AAQD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,CAqDzE;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CAmQjG"}