browser-autopilot 0.1.0

package/README.md

@@ -0,0 +1,251 @@
+# browser-autopilot
+
+A general-purpose autonomous browser agent that can log into any website and perform complex tasks — even on sites with aggressive bot detection (Twitter/X, TikTok, LinkedIn, etc.).
+
+Built in TypeScript. No Playwright. No Puppeteer. Raw CDP + xdotool + LLM.
+
+## The Problem
+
+Modern websites detect browser automation at the login gate. Twitter's `LoginJsInstrumentationSubtask`, Cloudflare's challenge pages, DataDome — they all fingerprint the browser and block if they detect CDP (Chrome DevTools Protocol) domains being enabled. Every existing automation tool (Playwright, Puppeteer, Selenium, browser-use) gets caught because they attach CDP before the page loads.
+
+## The Solution
+
+Automatic mode selection — tries the fast path first, falls back to stealth when blocked:
+
+```
+orchestrate({ credentials, task })
+  │
+  ├─ Cached session (cookies)? ──────────────→ CDP Agent (instant)
+  │
+  ├─ Try CDP login (fast, 15 steps)
+  │   ├─ Works? ─────────────────────────────→ CDP Agent
+  │   └─ Bot detected? ("could not log you in")
+  │       │
+  │       └─ Relaunch Chrome, X11 login ─────→ CDP Agent
+  │          (xdotool keyboard, no CDP,
+  │           undetectable by any JS)
+  │
+  └─ Returns: { result, success, loginMethod: "cached"|"cdp"|"x11" }
+```
+
+**CDP mode** (default): Raw Chrome DevTools Protocol. Fast, full DOM indexing with `[1] [2] [3]` element refs, screenshot + accessibility tree per step, 25+ tools.
+
+**X11 mode** (fallback): `xdotool` keyboard input through the X Window System — identical to a physical keyboard. LLM sees X11 screenshots via ImageMagick. No CDP client attached. Completely undetectable by any in-page JavaScript. Used only when bot detection blocks CDP.
+
+**The user never chooses.** The orchestrator tries CDP, detects failure signals, and switches automatically.
+
+## Features
+
+| | |
+|---|---|
+| **Stealth login** | X11 keyboard input (xdotool) — undetectable by any in-page JavaScript |
+| **LLM-driven** | Claude sees screenshots and decides actions — adapts to any UI change |
+| **Index-based DOM** | Elements indexed as `[1] button "Next"` — LLM references by number |
+| **25+ browser tools** | navigate, click, input, scroll, search, extract, tabs, dialogs, file I/O, JS eval |
+| **Step-based agent** | Each step: screenshot + DOM → LLM reasoning → tool execution → history |
+| **Error recovery** | Consecutive failure tracking, max_failures threshold, graceful degradation |
+| **Loop detection** | Action hash comparison across sliding window, escalating nudges |
+| **History management** | Truncation (first + last N steps), formatted context for LLM |
+| **Prompt caching** | System prompt + tool definitions cached via Anthropic's `cache_control` |
+| **Captcha solving** | Capsolver + 2Captcha (reCAPTCHA v2/v3, hCaptcha, Turnstile, DataDome) |
+| **Proxy support** | SOCKS5 chaining via gost (handles auth that Chromium can't) |
+| **Session persistence** | Browser profile + cookies survive across runs |
+| **Sensitive data masking** | Passwords/secrets replaced with `<secret:key>` in LLM context |
+| **Dockerized** | Runs headful Chrome in Docker via Xvfb — designed for containers/TEEs |
+
+## Quick Start
+
+### As a library
+
+```typescript
+import { orchestrate } from "browser-autopilot";
+
+// One call — handles login (auto CDP/X11) + task
+const { result, success, loginMethod } = await orchestrate({
+  credentials: {
+    username: "myuser",
+    password: "mypass",
+    email: "me@example.com",
+    totpKey: "ABCDEF123456",
+  },
+  loginUrl: "https://x.com/login",
+  successUrlContains: "/home",
+  task: "Go to settings and export my data as CSV",
+});
+
+console.log(`${loginMethod} login → ${result}`);
+```
+
+### CDP agent only (already logged in or no auth needed)
+
+```typescript
+import { CDPBrowser, runAgent } from "browser-autopilot";
+
+const browser = new CDPBrowser();
+await browser.connect();
+
+const { result } = await runAgent({
+  task: "Go to wikipedia.org and find the population of Tokyo",
+  browser,
+});
+```
+
+### As Docker (for servers/TEEs)
+
+```bash
+docker build -f docker/Dockerfile -t browser-autopilot .
+
+docker run --rm \
+  -e ANTHROPIC_API_KEY=sk-ant-... \
+  -e TWITTER_USER=myuser \
+  -e TWITTER_PASS=mypass \
+  -e TWITTER_EMAIL=me@example.com \
+  -e TWITTER_TOTP_KEY=ABCDEF123456 \
+  -e PROXY_HOST=1.2.3.4 \
+  -e PROXY_PORT=45001 \
+  -e PROXY_USER=proxyuser \
+  -e PROXY_PASS=proxypass \
+  -v mydata:/data \
+  browser-autopilot
+```
+
+### Login to any site
+
+```typescript
+import { X11Agent } from "browser-autopilot";
+import * as chrome from "browser-autopilot/x11/chrome";
+
+chrome.launch("https://tiktok.com/login", "tiktok-profile");
+
+const agent = new X11Agent();
+await agent.run({
+  systemPrompt: `Login to TikTok. Username: foo, Password: bar.
+    TYPE the username, KEY Return, TYPE the password, KEY Return.
+    When you see the For You page, say ACTION: DONE.`,
+  successCheck: () => chrome.pageUrlContains("/foryou"),
+});
+```
+
+### Custom tools
+
+```typescript
+import { z } from "zod";
+import { tool } from "ai";
+import { runAgent, CDPBrowser } from "browser-autopilot";
+
+const browser = new CDPBrowser();
+await browser.connect();
+
+await runAgent({
+  task: "Login and download my invoice",
+  browser,
+  extraTools: {
+    get_2fa: tool({
+      description: "Get 2FA code from authenticator",
+      parameters: z.object({}),
+      execute: async () => "123456",
+    }),
+  },
+});
+```
+
+## How It Works (Per Step)
+
+Each step of the CDP agent:
+
+1. **Capture state** — screenshot (CDP `Page.captureScreenshot`) + accessibility tree (`Accessibility.getFullAXTree`) + URL + title + tabs + scroll position + pending dialogs
+2. **Index DOM** — interactive elements get sequential numbers: `[1] button "Submit"`, `[2] textbox "Email"`. The LLM references elements by these numbers.
+3. **Build context** — format state as text, append action history (truncated), add loop detection nudges if needed
+4. **Send to LLM** — screenshot as vision input + state text + tool definitions (all prompt-cached)
+5. **Parse response** — extract reasoning (evaluation, memory, next goal) + tool calls
+6. **Execute tools** — up to `maxActionsPerStep` tool calls per step (click, type, navigate, etc.)
+7. **Record history** — step added to history with all actions + results + errors
+8. **Check termination** — done tool called? max steps? max failures?
+
+## Project Structure
+
+```
+browser-autopilot/
+├── src/
+│   ├── config.ts                 # All env vars
+│   ├── index.ts                  # CLI entrypoint + library exports
+│   ├── orchestrator.ts           # Auto mode selection (cached → CDP → X11)
+│   ├── x11/
+│   │   ├── agent.ts              # Generic X11Agent (works for any site)
+│   │   ├── chrome.ts             # Chrome launch, focus, status check
+│   │   ├── input.ts              # xdotool: type, key, click, screenshot
+│   │   └── login.ts              # Twitter login built on X11Agent
+│   ├── browser/
+│   │   ├── cdp.ts                # Raw CDP client (nav, click, type, tabs, cookies, dialogs)
+│   │   ├── dom.ts                # DOM indexer — [1] [2] [3] element refs
+│   │   └── snapshot.ts           # AX tree serialization utilities
+│   ├── agent/
+│   │   ├── loop.ts               # Step-based agent loop (the core)
+│   │   ├── tools.ts              # 25+ browser tools for the agent
+│   │   ├── state.ts              # Per-step browser state capture
+│   │   ├── history.ts            # History tracking, loop detection, truncation
+│   │   └── run.ts                # CLI entrypoint (Twitter dev portal example)
+│   └── captcha/
+│       └── solver.ts             # Capsolver + 2Captcha unified solver
+├── docker/
+│   ├── Dockerfile                # Production image (amd64, Google Chrome, gost, xdotool)
+│   └── entrypoint.sh             # dbus → Xvfb → openbox → gost → login → agent
+├── tests/
+│   ├── dom.test.ts               # DOM indexer tests
+│   ├── history.test.ts           # History + loop detection tests
+│   ├── state.test.ts             # Browser state formatting tests
+│   └── config.test.ts            # Config tests
+├── package.json
+└── tsconfig.json
+
+```
+
+## Key Constraints
+
+| Constraint | Why |
+|---|---|
+| **Must use headful Chrome** | Headless Chrome sets `HeadlessChrome` user-agent — instantly blocked |
+| **No CDP during login** | Twitter's JS instrumentation detects `Runtime.enable` and friends |
+| **xdotool for login input** | X11 keyboard events are identical to physical keyboard — undetectable |
+| **Timezone must match proxy geo** | `Intl.DateTimeFormat` timezone vs IP geolocation mismatch = flagged |
+| **SOCKS5 auth needs gost** | Chromium doesn't support SOCKS5 username/password natively |
+| **TOTP must be on-demand** | Codes expire in 30s — never bake into prompts, always generate fresh |
+| **Clean profile locks** | Stale `SingletonLock` files from previous runs prevent Chrome startup |
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `ANTHROPIC_API_KEY` | Yes | Claude API key |
+| `TWITTER_USER` | For Twitter | Username |
+| `TWITTER_PASS` | For Twitter | Password |
+| `TWITTER_EMAIL` | For Twitter | Email for identity verification |
+| `TWITTER_TOTP_KEY` | For Twitter | TOTP secret key |
+| `PROXY_HOST` | No | SOCKS5 proxy host |
+| `PROXY_PORT` | No | SOCKS5 proxy port |
+| `PROXY_USER` | No | SOCKS5 proxy username |
+| `PROXY_PASS` | No | SOCKS5 proxy password |
+| `CAPSOLVER_KEY` | No | Capsolver API key |
+| `TWOCAPTCHA_KEY` | No | 2Captcha API key |
+| `CDP_PORT` | No | Chrome debugging port (default: 9222) |
+| `PROFILE_DIR` | No | Browser profile directory |
+| `DATA_DIR` | No | Data output directory |
+| `AGENT_TASK` | No | Custom task for the CDP agent |
+| `MAX_STEPS` | No | Max agent steps (default: 80) |
+
+## Stack
+
+| Component | Purpose |
+|---|---|
+| TypeScript + Node.js | Runtime |
+| Anthropic SDK | LLM (Claude claude-sonnet-4-6) with prompt caching |
+| chrome-remote-interface | Raw CDP — no Playwright/Puppeteer |
+| xdotool | X11 keyboard simulation |
+| ImageMagick | X11 screenshot capture |
+| Google Chrome | Real browser (not Chromium) |
+| Xvfb | Virtual X11 display |
+| openbox | Minimal window manager |
+| gost | SOCKS5 proxy chaining |
+| zod | Tool parameter validation |
+| otplib | TOTP generation |
+| vitest | Testing |

package/dist/agent/history.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Agent history — tracks steps, manages conversation, detects loops.
+ */
+export interface StepRecord {
+    step: number;
+    url: string;
+    evaluation: string;
+    memory: string;
+    nextGoal: string;
+    actions: Array<{
+        name: string;
+        params: Record<string, any>;
+        result?: string;
+        error?: string;
+    }>;
+    timestamp: number;
+}
+export declare class AgentHistory {
+    private steps;
+    private maxHistory;
+    private actionHashes;
+    constructor(maxHistory?: number);
+    add(record: StepRecord): void;
+    /**
+     * Format history for LLM context.
+     * Keeps first step + last N steps, omits middle with summary.
+     */
+    formatForLLM(): string;
+    /**
+     * Detect behavioral loops — same actions on same page state.
+     */
+    detectLoop(windowSize?: number): {
+        isLoop: boolean;
+        loopCount: number;
+    };
+    get consecutiveFailures(): number;
+    get lastStep(): StepRecord | undefined;
+    get totalSteps(): number;
+    get allUrls(): string[];
+    get finalResult(): string | null;
+}

package/dist/agent/history.js

@@ -0,0 +1,98 @@
+/**
+ * Agent history — tracks steps, manages conversation, detects loops.
+ */
+export class AgentHistory {
+    steps = [];
+    maxHistory;
+    actionHashes = [];
+    constructor(maxHistory = 20) {
+        this.maxHistory = maxHistory;
+    }
+    add(record) {
+        this.steps.push(record);
+        for (const a of record.actions) {
+            this.actionHashes.push(`${a.name}:${JSON.stringify(a.params)}:${record.url}`);
+        }
+    }
+    /**
+     * Format history for LLM context.
+     * Keeps first step + last N steps, omits middle with summary.
+     */
+    formatForLLM() {
+        if (this.steps.length === 0)
+            return "";
+        const lines = ["Previous steps:"];
+        const keep = this.steps.length <= this.maxHistory
+            ? this.steps
+            : [this.steps[0], ...this.steps.slice(-this.maxHistory + 1)];
+        if (this.steps.length > this.maxHistory) {
+            lines.push(`[... ${this.steps.length - this.maxHistory} steps omitted ...]`);
+        }
+        for (const s of keep) {
+            const actionStrs = s.actions.map((a) => {
+                const call = `${a.name}(${JSON.stringify(a.params).slice(0, 80)})`;
+                if (a.error)
+                    return `${call} → FAILED: ${a.error.slice(0, 150)}`;
+                if (a.result)
+                    return `${call} → ${a.result.slice(0, 300)}`;
+                return call;
+            });
+            lines.push(`  Step ${s.step}: ${s.evaluation}`);
+            for (const a of actionStrs)
+                lines.push(`    ${a}`);
+            if (s.memory)
+                lines.push(`    Memory: ${s.memory}`);
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Detect behavioral loops — same actions on same page state.
+     */
+    detectLoop(windowSize = 4) {
+        if (this.actionHashes.length < windowSize * 2)
+            return { isLoop: false, loopCount: 0 };
+        const recent = this.actionHashes.slice(-windowSize);
+        const prev = this.actionHashes.slice(-windowSize * 2, -windowSize);
+        const matches = recent.filter((h, i) => h === prev[i]).length;
+        const isLoop = matches >= windowSize - 1;
+        let loopCount = 0;
+        if (isLoop) {
+            for (let i = this.actionHashes.length - windowSize; i >= 0; i -= windowSize) {
+                const window = this.actionHashes.slice(i, i + windowSize);
+                if (window.every((h, j) => h === recent[j]))
+                    loopCount++;
+                else
+                    break;
+            }
+        }
+        return { isLoop, loopCount };
+    }
+    get consecutiveFailures() {
+        let count = 0;
+        for (let i = this.steps.length - 1; i >= 0; i--) {
+            const actions = this.steps[i].actions;
+            const hasSuccess = actions.some((a) => a.result && !a.error);
+            // Only count as failure if no action succeeded
+            if (!hasSuccess)
+                count++;
+            else
+                break;
+        }
+        return count;
+    }
+    get lastStep() {
+        return this.steps[this.steps.length - 1];
+    }
+    get totalSteps() { return this.steps.length; }
+    get allUrls() {
+        return [...new Set(this.steps.map((s) => s.url))];
+    }
+    get finalResult() {
+        const last = this.lastStep;
+        if (!last)
+            return null;
+        const doneAction = last.actions.find((a) => a.name === "done");
+        return doneAction?.result ?? null;
+    }
+}
+//# sourceMappingURL=history.js.map

package/dist/agent/history.js.map

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

package/dist/agent/loop.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Step-based LLM agent loop with multi-turn tool use.
+ *
+ * Each step:
+ *   1. Capture browser state (screenshot + indexed DOM + URL + tabs)
+ *   2. Send to LLM with history + state + screenshot
+ *   3. LLM returns tool calls
+ *   4. Execute tools, feed results back to LLM
+ *   5. LLM can chain more tool calls (seeing previous results)
+ *   6. Repeat tool loop until LLM emits end_turn or hits maxActionsPerStep
+ *   7. Record step in history, advance to next step
+ *
+ * The inner tool loop means the LLM can call get_buyer_profile,
+ * see the result, then call input(text="Marcus") — all within one step.
+ */
+import { CDPBrowser } from "../browser/cdp.js";
+import { AgentHistory, type StepRecord } from "./history.js";
+export interface AgentOptions {
+    task: string;
+    browser: CDPBrowser;
+    model?: string;
+    maxSteps?: number;
+    maxFailures?: number;
+    maxActionsPerStep?: number;
+    extraTools?: Record<string, any>;
+    systemPrompt?: string;
+    onStep?: (step: StepRecord) => void;
+    sensitiveData?: Record<string, string>;
+}
+export declare function runAgent(opts: AgentOptions): Promise<{
+    result: string | null;
+    success: boolean;
+    history: AgentHistory;
+}>;