human-browser 4.2.0 → 4.2.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "human-browser",
-  "version": "4.2.0",
-  "description": "Stealth browser for AI agents. Bypasses Cloudflare, DataDome, PerimeterX. Residential IPs from 10+ countries. iPhone 15 Pro fingerprint. Drop-in Playwright replacement \u2014 launchHuman() just works.",
+  "version": "4.2.1",
+  "description": "Stealth browser for AI agents. Bypasses Cloudflare, DataDome, PerimeterX. Residential IPs from 10+ countries. iPhone 15 Pro fingerprint. Drop-in Playwright replacement — launchHuman() just works.",
   "keywords": [
     "browser-automation",
     "stealth-browser",
@@ -52,4 +52,4 @@
   "dependencies": {
     "dotenv": "^17.3.1"
   }
-}
+}

package/scripts/browser-agent.js

@@ -0,0 +1,616 @@
+/**
+ * browser-agent.js — AI Agent Layer for Human Browser v1.0.0
+ *
+ * Give a task in natural language → agent drives the browser autonomously.
+ * Built on top of launchHuman() stealth browser with residential proxies.
+ *
+ * Usage:
+ *   const { runAgent } = require('./browser-agent');
+ *   const result = await runAgent({
+ *     task: 'Go to reddit.com and find the top post on r/programming',
+ *     model: 'claude-sonnet-4-6',     // any OpenRouter/Anthropic/OpenAI model
+ *     apiKey: process.env.ANTHROPIC_API_KEY,
+ *     provider: 'anthropic',          // 'anthropic' | 'openai' | 'openrouter'
+ *   });
+ *   console.log(result.output);
+ *
+ * Env vars:
+ *   AGENT_LLM_PROVIDER   — anthropic | openai | openrouter (default: anthropic)
+ *   AGENT_LLM_MODEL      — model name (default: claude-sonnet-4-6)
+ *   AGENT_LLM_API_KEY    — API key for the LLM provider
+ *   AGENT_MAX_STEPS      — max agent loop iterations (default: 30)
+ *   AGENT_VERBOSE        — set to '1' for detailed logging
+ */
+
+const { launchHuman, getTrial, humanClick, humanType, humanScroll, humanRead, sleep, rand } = require('./browser-human');
+
+// ─── LLM PROVIDERS ───────────────────────────────────────────────────────────
+
+const PROVIDERS = {
+  anthropic: {
+    url: 'https://api.anthropic.com/v1/messages',
+    headers: (key) => ({
+      'x-api-key': key,
+      'anthropic-version': '2023-06-01',
+      'content-type': 'application/json',
+    }),
+    buildBody: (model, messages, systemPrompt) => ({
+      model,
+      max_tokens: 4096,
+      system: systemPrompt,
+      messages,
+    }),
+    parseResponse: (data) => {
+      const block = data.content?.find(b => b.type === 'text');
+      return block?.text || '';
+    },
+  },
+  openai: {
+    url: 'https://api.openai.com/v1/chat/completions',
+    headers: (key) => ({
+      'Authorization': `Bearer ${key}`,
+      'content-type': 'application/json',
+    }),
+    buildBody: (model, messages, systemPrompt) => ({
+      model,
+      max_tokens: 4096,
+      messages: [{ role: 'system', content: systemPrompt }, ...messages],
+    }),
+    parseResponse: (data) => data.choices?.[0]?.message?.content || '',
+  },
+  openrouter: {
+    url: 'https://openrouter.ai/api/v1/chat/completions',
+    headers: (key) => ({
+      'Authorization': `Bearer ${key}`,
+      'content-type': 'application/json',
+    }),
+    buildBody: (model, messages, systemPrompt) => ({
+      model,
+      max_tokens: 4096,
+      messages: [{ role: 'system', content: systemPrompt }, ...messages],
+    }),
+    parseResponse: (data) => data.choices?.[0]?.message?.content || '',
+  },
+};
+
+async function callLLM(provider, apiKey, model, messages, systemPrompt) {
+  const p = PROVIDERS[provider];
+  if (!p) throw new Error(`Unknown provider: ${provider}. Use: anthropic, openai, openrouter`);
+
+  const resp = await fetch(p.url, {
+    method: 'POST',
+    headers: p.headers(apiKey),
+    body: JSON.stringify(p.buildBody(model, messages, systemPrompt)),
+  });
+
+  if (!resp.ok) {
+    const errText = await resp.text();
+    throw new Error(`LLM API error ${resp.status}: ${errText.slice(0, 500)}`);
+  }
+
+  const data = await resp.json();
+  return p.parseResponse(data);
+}
+
+// ─── PAGE SNAPSHOT ────────────────────────────────────────────────────────────
+
+/**
+ * Extract a compact, LLM-friendly representation of the visible page.
+ * Returns interactive elements with ref IDs for the agent to use.
+ */
+async function getPageSnapshot(page) {
+  const snapshot = await page.evaluate(() => {
+    const result = {
+      url: location.href,
+      title: document.title || '',
+      viewport: { width: window.innerWidth || 0, height: window.innerHeight || 0 },
+      scrollY: window.scrollY || 0,
+      scrollHeight: (document.documentElement || {}).scrollHeight || 0,
+      elements: [],
+      visibleText: '',
+    };
+
+    const body = document.body || document.documentElement;
+    if (!body) return result;
+
+    const elements = [];
+    let refId = 0;
+
+    function isVisible(el) {
+      try {
+        const style = window.getComputedStyle(el);
+        if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') return false;
+        const rect = el.getBoundingClientRect();
+        return rect.width > 0 && rect.height > 0 && rect.top < window.innerHeight && rect.bottom > 0;
+      } catch { return false; }
+    }
+
+    function getLabel(el) {
+      return (
+        el.getAttribute('aria-label') ||
+        el.getAttribute('placeholder') ||
+        el.getAttribute('title') ||
+        el.getAttribute('alt') ||
+        el.getAttribute('name') ||
+        ''
+      );
+    }
+
+    function collect(root) {
+      try {
+        const selectors = 'a, button, input, textarea, select, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [contenteditable="true"], [onclick]';
+        for (const el of root.querySelectorAll(selectors)) {
+          if (!isVisible(el)) continue;
+          const rect = el.getBoundingClientRect();
+          const tag = el.tagName.toLowerCase();
+          const text = (el.textContent || '').trim().slice(0, 80);
+          const label = getLabel(el);
+          const type = el.getAttribute('type') || '';
+          const href = el.getAttribute('href') || '';
+          const value = el.value || '';
+          const ref = `e${refId++}`;
+
+          const info = { ref, tag, x: Math.round(rect.x + rect.width / 2), y: Math.round(rect.y + rect.height / 2) };
+          if (text) info.text = text;
+          if (label) info.label = label;
+          if (type) info.type = type;
+          if (href) info.href = href.slice(0, 120);
+          if (value) info.value = value.slice(0, 60);
+          if (el.disabled) info.disabled = true;
+          if (el.checked) info.checked = true;
+
+          elements.push(info);
+        }
+
+        // Recurse into shadow DOMs
+        for (const n of root.querySelectorAll('*')) {
+          if (n.shadowRoot) collect(n.shadowRoot);
+        }
+      } catch {}
+    }
+
+    collect(body);
+    result.elements = elements;
+
+    // Get visible text blocks
+    try {
+      const textBlocks = [];
+      const walker = document.createTreeWalker(body, NodeFilter.SHOW_TEXT, {
+        acceptNode: (node) => {
+          const t = node.textContent.trim();
+          if (t.length < 10) return NodeFilter.FILTER_REJECT;
+          const parent = node.parentElement;
+          if (!parent) return NodeFilter.FILTER_REJECT;
+          const tag = parent.tagName.toLowerCase();
+          if (['script', 'style', 'noscript'].includes(tag)) return NodeFilter.FILTER_REJECT;
+          const rect = parent.getBoundingClientRect();
+          if (rect.width === 0 || rect.height === 0) return NodeFilter.FILTER_REJECT;
+          if (rect.top > window.innerHeight * 2) return NodeFilter.FILTER_REJECT;
+          return NodeFilter.FILTER_ACCEPT;
+        }
+      });
+
+      let node;
+      let charBudget = 3000;
+      while ((node = walker.nextNode()) && charBudget > 0) {
+        const t = node.textContent.trim().slice(0, 200);
+        textBlocks.push(t);
+        charBudget -= t.length;
+      }
+      result.visibleText = textBlocks.join('\n');
+    } catch {}
+
+    return result;
+  });
+
+  return snapshot;
+}
+
+/**
+ * Format snapshot into a concise string for the LLM
+ */
+function formatSnapshot(snap) {
+  const lines = [];
+  lines.push(`## Page: ${snap.title}`);
+  lines.push(`URL: ${snap.url}`);
+  lines.push(`Scroll: ${snap.scrollY}/${snap.scrollHeight - snap.viewport.height}px`);
+  lines.push('');
+
+  if (snap.visibleText) {
+    lines.push('### Visible text:');
+    lines.push(snap.visibleText.slice(0, 2000));
+    lines.push('');
+  }
+
+  if (snap.elements.length > 0) {
+    lines.push(`### Interactive elements (${snap.elements.length}):`);
+    for (const el of snap.elements) {
+      let desc = `[${el.ref}] <${el.tag}>`;
+      if (el.type) desc += ` type="${el.type}"`;
+      if (el.text) desc += ` "${el.text}"`;
+      if (el.label) desc += ` label="${el.label}"`;
+      if (el.href) desc += ` href="${el.href}"`;
+      if (el.value) desc += ` value="${el.value}"`;
+      if (el.disabled) desc += ' [disabled]';
+      if (el.checked) desc += ' [checked]';
+      desc += ` @(${el.x},${el.y})`;
+      lines.push(desc);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// ─── AGENT ACTIONS ────────────────────────────────────────────────────────────
+
+/**
+ * Parse the LLM response into structured actions.
+ * The LLM outputs JSON actions in a ```json block.
+ */
+function parseActions(llmOutput) {
+  // Extract JSON block
+  const jsonMatch = llmOutput.match(/```json\s*([\s\S]*?)```/);
+  if (!jsonMatch) {
+    // Try to parse the whole output as JSON
+    try {
+      const parsed = JSON.parse(llmOutput.trim());
+      return Array.isArray(parsed) ? parsed : [parsed];
+    } catch {
+      return null;
+    }
+  }
+
+  try {
+    const parsed = JSON.parse(jsonMatch[1].trim());
+    return Array.isArray(parsed) ? parsed : [parsed];
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Execute a single action on the page
+ */
+async function executeAction(page, action, elements) {
+  const log = (...a) => console.log('[agent]', ...a);
+
+  switch (action.action) {
+    case 'click': {
+      const el = elements.find(e => e.ref === action.ref);
+      if (!el) throw new Error(`Element ${action.ref} not found`);
+      log(`click ${action.ref} "${el.text || el.label || ''}" @(${el.x},${el.y})`);
+      await humanClick(page, el.x, el.y);
+      await sleep(rand(500, 1500));
+      break;
+    }
+
+    case 'type': {
+      const el = elements.find(e => e.ref === action.ref);
+      if (!el) throw new Error(`Element ${action.ref} not found`);
+      log(`type into ${action.ref} "${action.text?.slice(0, 30)}..."`);
+      // Click first, clear, then type
+      await humanClick(page, el.x, el.y);
+      await sleep(200);
+      if (action.clear !== false) {
+        await page.keyboard.press('Control+a');
+        await sleep(100);
+      }
+      await humanType(page, `[data-agent-ref="${action.ref}"]`, action.text || '').catch(async () => {
+        // Fallback: type character by character at coordinates
+        for (const char of (action.text || '')) {
+          await page.keyboard.type(char);
+          await sleep(rand(60, 180));
+        }
+      });
+      await sleep(rand(300, 600));
+      break;
+    }
+
+    case 'press': {
+      log(`press key: ${action.key}`);
+      await page.keyboard.press(action.key);
+      await sleep(rand(200, 500));
+      break;
+    }
+
+    case 'scroll': {
+      const dir = action.direction || 'down';
+      const amount = action.amount || rand(300, 600);
+      log(`scroll ${dir} ${amount}px`);
+      await humanScroll(page, dir, amount);
+      break;
+    }
+
+    case 'navigate': {
+      log(`navigate to: ${action.url}`);
+      try {
+        await page.goto(action.url, { waitUntil: 'domcontentloaded', timeout: 60000 });
+      } catch (e) {
+        // If domcontentloaded times out, page may still be usable
+        if (e.message.includes('Timeout')) {
+          log(`Navigation timeout, page may still be usable`);
+        } else {
+          throw e;
+        }
+      }
+      await sleep(rand(1000, 2000));
+      break;
+    }
+
+    case 'wait': {
+      const ms = action.ms || 2000;
+      log(`wait ${ms}ms`);
+      await sleep(ms);
+      break;
+    }
+
+    case 'screenshot': {
+      log('taking screenshot');
+      // Screenshot is handled by the caller if vision is supported
+      break;
+    }
+
+    case 'extract': {
+      log(`extract: ${action.selector || 'page text'}`);
+      if (action.selector) {
+        const el = await page.$(action.selector);
+        return el ? await el.textContent() : null;
+      }
+      return await page.evaluate(() => (document.body || document.documentElement)?.innerText?.slice(0, 5000) || '');
+    }
+
+    case 'done': {
+      log(`task complete: ${action.result?.slice(0, 100)}`);
+      return { done: true, result: action.result || '' };
+    }
+
+    case 'fail': {
+      log(`task failed: ${action.reason}`);
+      return { done: true, failed: true, result: action.reason || 'Unknown error' };
+    }
+
+    default:
+      log(`unknown action: ${action.action}`);
+  }
+
+  return null;
+}
+
+// ─── SYSTEM PROMPT ────────────────────────────────────────────────────────────
+
+const SYSTEM_PROMPT = `You are a browser automation agent. You control a real browser with a residential IP and stealth fingerprint. You see a snapshot of the current page and must decide what actions to take.
+
+## Output format
+
+Respond with a brief thought (1-2 sentences), then a JSON action block:
+
+\`\`\`json
+[{"action": "click", "ref": "e5"}]
+\`\`\`
+
+## Available actions
+
+- **click** — Click an element: \`{"action": "click", "ref": "e12"}\`
+- **type** — Type text into an input: \`{"action": "type", "ref": "e3", "text": "hello"}\`
+  - Add \`"clear": false\` to append instead of replacing
+- **press** — Press a key: \`{"action": "press", "key": "Enter"}\`
+  - Keys: Enter, Tab, Escape, ArrowDown, ArrowUp, Backspace, etc.
+- **scroll** — Scroll the page: \`{"action": "scroll", "direction": "down"}\`
+  - direction: "down" or "up", optional "amount": pixels
+- **navigate** — Go to a URL: \`{"action": "navigate", "url": "https://..."}\`
+- **wait** — Wait for content to load: \`{"action": "wait", "ms": 2000}\`
+- **extract** — Extract text: \`{"action": "extract"}\` or \`{"action": "extract", "selector": ".content"}\`
+- **done** — Task complete: \`{"action": "done", "result": "The answer is..."}\`
+- **fail** — Cannot complete: \`{"action": "fail", "reason": "Why it failed"}\`
+
+## Rules
+
+1. Use element refs like "e5" from the snapshot — they correspond to interactive elements.
+2. You can chain multiple actions: \`[{"action": "click", "ref": "e3"}, {"action": "type", "ref": "e3", "text": "query"}]\`
+3. After clicking a link or button, the page may change. Wait for the next snapshot.
+4. If a page requires scrolling to find content, scroll down first.
+5. When the task is complete, ALWAYS use the "done" action with the result.
+6. If stuck after 3+ attempts, use "fail" with a clear reason.
+7. Keep thoughts SHORT. Focus on actions.
+8. Don't hallucinate elements — only use refs from the current snapshot.
+9. For search: navigate to the search engine, type the query, press Enter.
+10. Cookie banners and popups: dismiss them (click accept/close) and continue.`;
+
+// ─── MAIN AGENT LOOP ─────────────────────────────────────────────────────────
+
+/**
+ * Run an AI agent that controls the browser to complete a task.
+ *
+ * @param {Object} opts
+ * @param {string} opts.task          — Natural language task description
+ * @param {string} opts.provider      — LLM provider: anthropic|openai|openrouter (default: env or anthropic)
+ * @param {string} opts.model         — Model name (default: env or claude-sonnet-4-6)
+ * @param {string} opts.apiKey        — LLM API key (default: env)
+ * @param {string} opts.startUrl      — Starting URL (default: about:blank)
+ * @param {number} opts.maxSteps      — Max agent loop iterations (default: 30)
+ * @param {boolean} opts.verbose      — Detailed logging (default: env or false)
+ * @param {string} opts.country       — Proxy country (default: ro)
+ * @param {boolean} opts.mobile       — Mobile device (default: true)
+ * @param {boolean} opts.useProxy     — Use residential proxy (default: true)
+ * @param {boolean} opts.headless     — Headless mode (default: true)
+ * @param {Function} opts.onStep      — Callback after each step: (stepNum, action, snapshot) => void
+ * @param {Object} opts.browserOpts   — Extra options for launchHuman()
+ *
+ * @returns {{ output: string, steps: number, success: boolean, history: Array }}
+ */
+async function runAgent(opts = {}) {
+  const {
+    task,
+    provider = process.env.AGENT_LLM_PROVIDER || 'anthropic',
+    model    = process.env.AGENT_LLM_MODEL || 'claude-sonnet-4-6',
+    apiKey   = process.env.AGENT_LLM_API_KEY || process.env.ANTHROPIC_API_KEY || process.env.OPENAI_API_KEY,
+    startUrl = null,
+    maxSteps = parseInt(process.env.AGENT_MAX_STEPS || '30'),
+    verbose  = process.env.AGENT_VERBOSE === '1',
+    country  = 'ro',
+    mobile   = true,
+    useProxy = true,
+    headless = true,
+    onStep   = null,
+    browserOpts = {},
+  } = opts;
+
+  if (!task) throw new Error('task is required');
+  if (!apiKey) throw new Error('API key is required. Set AGENT_LLM_API_KEY or pass opts.apiKey');
+
+  const log = (...a) => console.log('[browser-agent]', ...a);
+  const vlog = verbose ? log : () => {};
+
+  log(`Task: "${task.slice(0, 100)}"`);
+  log(`Model: ${provider}/${model} | Max steps: ${maxSteps}`);
+
+  // Launch browser
+  const { browser, page, ctx } = await launchHuman({
+    country,
+    mobile,
+    useProxy,
+    headless,
+    ...browserOpts,
+  });
+
+  const messages = [];
+  const history = [];
+  let result = { output: '', steps: 0, success: false, history };
+
+  try {
+    // Navigate to start URL if provided
+    if (startUrl) {
+      try {
+        await page.goto(startUrl, { waitUntil: 'domcontentloaded', timeout: 60000 });
+      } catch (e) {
+        if (!e.message.includes('Timeout')) throw e;
+        log('Start URL navigation timeout, continuing...');
+      }
+      await sleep(rand(1000, 2000));
+    }
+
+    for (let step = 0; step < maxSteps; step++) {
+      vlog(`--- Step ${step + 1}/${maxSteps} ---`);
+
+      // Get page snapshot
+      let snapshot;
+      try {
+        snapshot = await getPageSnapshot(page);
+      } catch (e) {
+        vlog(`Snapshot error: ${e.message}`);
+        await sleep(1000);
+        try { snapshot = await getPageSnapshot(page); } catch { snapshot = { url: page.url(), title: '', elements: [], visibleText: '', scrollY: 0, scrollHeight: 0, viewport: { width: 0, height: 0 } }; }
+      }
+
+      const snapshotStr = formatSnapshot(snapshot);
+      vlog(`Page: ${snapshot.url} | Elements: ${snapshot.elements.length}`);
+
+      // Build user message
+      const userMsg = step === 0
+        ? `Task: ${task}\n\nCurrent page:\n${snapshotStr}`
+        : `Page after action:\n${snapshotStr}`;
+
+      messages.push({ role: 'user', content: userMsg });
+
+      // Call LLM
+      let llmResponse;
+      try {
+        llmResponse = await callLLM(provider, apiKey, model, messages, SYSTEM_PROMPT);
+      } catch (e) {
+        log(`LLM error: ${e.message}`);
+        result.output = `LLM error: ${e.message}`;
+        break;
+      }
+
+      vlog(`LLM response: ${llmResponse.slice(0, 200)}...`);
+      messages.push({ role: 'assistant', content: llmResponse });
+
+      // Parse and execute actions
+      const actions = parseActions(llmResponse);
+      if (!actions || actions.length === 0) {
+        log(`No valid actions in LLM response, retrying...`);
+        messages.push({ role: 'user', content: 'Your response did not contain valid JSON actions. Please respond with actions in ```json [...] ``` format.' });
+        continue;
+      }
+
+      let stepDone = false;
+      for (const action of actions) {
+        try {
+          const actionResult = await executeAction(page, action, snapshot.elements);
+          history.push({ step: step + 1, action, success: true });
+
+          if (actionResult?.done) {
+            result.output = actionResult.result;
+            result.success = !actionResult.failed;
+            result.steps = step + 1;
+            stepDone = true;
+            break;
+          }
+        } catch (e) {
+          log(`Action error: ${e.message}`);
+          history.push({ step: step + 1, action, success: false, error: e.message });
+          messages.push({ role: 'user', content: `Action "${action.action}" failed: ${e.message}. Try a different approach.` });
+        }
+      }
+
+      if (stepDone) break;
+      if (onStep) onStep(step + 1, actions, snapshot);
+
+      // Small delay between steps
+      await sleep(rand(500, 1000));
+      result.steps = step + 1;
+    }
+
+    if (!result.output && result.steps >= maxSteps) {
+      result.output = 'Max steps reached without completing the task.';
+      result.success = false;
+    }
+
+  } finally {
+    await browser.close().catch(() => {});
+  }
+
+  log(`Done in ${result.steps} steps. Success: ${result.success}`);
+  return result;
+}
+
+// ─── EXPORTS ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  runAgent,
+  getPageSnapshot,
+  formatSnapshot,
+  callLLM,
+  PROVIDERS,
+  SYSTEM_PROMPT,
+};
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+
+if (require.main === module) {
+  const task = process.argv.slice(2).join(' ');
+  if (!task) {
+    console.log('Usage: node browser-agent.js <task>');
+    console.log('  Example: node browser-agent.js "Search Google for OpenAI news and give me the top 3 results"');
+    console.log('');
+    console.log('Env vars:');
+    console.log('  AGENT_LLM_API_KEY    — API key (required)');
+    console.log('  AGENT_LLM_PROVIDER   — anthropic | openai | openrouter');
+    console.log('  AGENT_LLM_MODEL      — model name');
+    console.log('  AGENT_MAX_STEPS      — max iterations (default: 30)');
+    console.log('  AGENT_VERBOSE        — 1 for detailed logs');
+    process.exit(1);
+  }
+
+  (async () => {
+    try {
+      const result = await runAgent({ task, verbose: true });
+      console.log('\n═══════════════════════════════════════');
+      console.log(`Result (${result.steps} steps, success=${result.success}):`);
+      console.log(result.output);
+    } catch (e) {
+      console.error('Agent error:', e.message);
+      process.exit(1);
+    }
+  })();
+}