surfagent 1.0.4 → 1.0.6

package/README.md

@@ -1,8 +1,17 @@
 # surfagent
 
-A local API that gives AI agents structured page data from your Chrome browser. Instead of guessing selectors or taking screenshots, your agent gets a complete map of every element, form, and link on the page — then acts on it precisely.
+**Browser automation API for AI agents.** Give any AI agent the ability to see, navigate, and interact with real web pages through Chrome.
 
-**One recon call replaces dozens of trial-and-error clicks.**
+`npm install -g surfagent` — two commands to give your agent a browser.
+
+[![npm version](https://img.shields.io/npm/v/surfagent.svg)](https://www.npmjs.com/package/surfagent)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+**surfagent** connects to a local Chrome browser via CDP and exposes a simple HTTP API that returns structured page data — every interactive element, form field, link, and CSS selector — so AI agents can navigate websites fast and precisely without screenshots or trial-and-error.
+
+**Works with any AI agent framework:** LangChain, CrewAI, AutoGPT, Claude Code, OpenAI Agents, custom agents — anything that can make HTTP calls.
 
 ## Quick Start
 
@@ -11,153 +20,104 @@ npm install -g surfagent
 surfagent start
 ```
 
-That's it. A **new Chrome window** opens with debug mode — your personal Chrome is not affected. The API starts on `http://localhost:3456` and your agent can start calling it immediately.
+A **new Chrome window** opens with debug mode — your personal Chrome is not affected. The API starts on `http://localhost:3456`.
 
-### Other commands
+## Why surfagent?
 
-```bash
-surfagent start     # Start Chrome + API (one command)
-surfagent chrome    # Start Chrome debug session only
-surfagent api       # Start API only (Chrome must be running)
-surfagent health    # Check if everything is running
-surfagent help      # Show all options
-```
+| Without surfagent | With surfagent |
+|---|---|
+| Agent takes screenshots, sends to vision model | Agent calls `/recon`, gets structured JSON in 30ms |
+| Guesses CSS selectors, fails, retries | Gets exact selectors from recon response |
+| Can't read forms, dropdowns, or modals | Gets form schemas with labels, types, required flags |
+| Breaks on SPAs, iframes, shadow DOM | Handles all of them out of the box |
+| Slow (2-5s per screenshot round-trip) | Fast (20-60ms per API call on existing tabs) |
 
-## Your First Recon
+## How Agents Use It
 
-Open any website in Chrome, then:
+The workflow is: **recon → act → read**.
 
-```bash
-curl -s -X POST localhost:3456/recon -d '{"tab":"0"}' -H 'Content-Type: application/json'
+```
+1. POST /recon   → get the page map (selectors, forms, elements)
+2. POST /click   → click something using a selector from step 1
+   POST /fill    → fill a form using selectors from step 1
+3. POST /read    → check what happened (success? error? new content?)
+4. POST /recon   → if the page changed, map it again
 ```
 
-You get back:
-- Every clickable element with a CSS selector
-- Every form with field labels, types, and required flags
-- Page headings, navigation links, metadata
-- Overlay/modal detection
-
-Your agent uses those selectors to interact — no guessing.
-
-## What Can It Do?
+### Example: search on any website
 
-### Map a page
 ```bash
-# Get full page structure
+# 1. Recon the page — find the search input
 curl -X POST localhost:3456/recon -H 'Content-Type: application/json' \
   -d '{"tab":"0"}'
+# Response includes: { "selector": "input[name='search']", "text": "Search..." }
 
-# Open a URL and map it
-curl -X POST localhost:3456/recon -H 'Content-Type: application/json' \
-  -d '{"url":"https://example.com", "keepTab": true}'
-```
+# 2. Type and submit
+curl -X POST localhost:3456/fill -H 'Content-Type: application/json' \
+  -d '{"tab":"0", "fields":[{"selector":"input[name=\"search\"]","value":"AI agents"}], "submit":"enter"}'
 
-### Read page content
-```bash
-# Structured text — headings, tables, notifications
+# 3. Read the results
 curl -X POST localhost:3456/read -H 'Content-Type: application/json' \
   -d '{"tab":"0"}'
-
-# Read a specific element
-curl -X POST localhost:3456/read -H 'Content-Type: application/json' \
-  -d '{"tab":"0", "selector":".results"}'
 ```
 
-### Fill forms
-```bash
-curl -X POST localhost:3456/fill -H 'Content-Type: application/json' \
-  -d '{"tab":"0", "fields":[
-    {"selector":"#email", "value":"me@example.com"},
-    {"selector":"#password", "value":"secret"}
-  ], "submit":"enter"}'
-```
+## All Endpoints
 
-### Click elements
-```bash
-# By text
-curl -X POST localhost:3456/click -H 'Content-Type: application/json' \
-  -d '{"tab":"0", "text":"Sign In"}'
+| Endpoint | Method | Description |
+|---|---|---|
+| `/recon` | POST | Full page map — every element, form, selector, heading, nav link, metadata, captcha detection |
+| `/read` | POST | Structured page content — headings, tables, code blocks, notifications, result areas |
+| `/fill` | POST | Fill form fields with real CDP keystrokes (works with React, Vue, SPAs) |
+| `/click` | POST | Click by CSS selector or text match (handles `target="_blank"` automatically) |
+| `/scroll` | POST | Scroll page, returns visible content preview and scroll position |
+| `/navigate` | POST | Go to URL, back, or forward in the same tab |
+| `/eval` | POST | Run JavaScript in any tab or cross-origin iframe |
+| `/captcha` | POST | Detect and interact with captchas — Arkose, reCAPTCHA, hCaptcha (experimental) |
+| `/focus` | POST | Bring a tab to the front in Chrome |
+| `/tabs` | GET | List all open Chrome tabs |
+| `/health` | GET | Check if Chrome and API are connected |
 
-# By selector (from recon)
-curl -X POST localhost:3456/click -H 'Content-Type: application/json' \
-  -d '{"tab":"0", "selector":"#submit-btn"}'
-```
+Full API reference with request/response schemas: **[API.md](./API.md)**
 
-### Navigate
-```bash
-# Go to URL (same tab)
-curl -X POST localhost:3456/navigate -H 'Content-Type: application/json' \
-  -d '{"tab":"0", "url":"https://example.com"}'
+## Key Features
 
-# Go back
-curl -X POST localhost:3456/navigate -H 'Content-Type: application/json' \
-  -d '{"tab":"0", "back":true}'
-```
+**Page reconnaissance** — one call returns every interactive element with stable CSS selectors, form schemas with field labels and validation, navigation structure, metadata, and content summary.
 
-### Scroll
-```bash
-curl -X POST localhost:3456/scroll -H 'Content-Type: application/json' \
-  -d '{"tab":"0", "direction":"down", "amount":1000}'
-```
+**Real keyboard input** — fills forms using CDP `Input.dispatchKeyEvent`, not JavaScript value injection. Works with React, Vue, Angular, and any framework-controlled inputs.
 
-### Run JavaScript
-```bash
-curl -X POST localhost:3456/eval -H 'Content-Type: application/json' \
-  -d '{"tab":"0", "expression":"document.title"}'
-```
+**Cross-origin iframe support** — target iframes by domain (`"tab": "stripe.com"`). CDP connects to them as separate targets, bypassing same-origin restrictions.
 
-## All Endpoints
+**SPA navigation** — handles single-page apps (YouTube, Gmail, Google Flights). Enter key submission, client-side routing, dynamic content — all work.
 
-| Endpoint | Method | What it does |
-|---|---|---|
-| `/recon` | POST | Full page map — elements, forms, selectors, metadata |
-| `/read` | POST | Structured page content — headings, tables, notifications |
-| `/fill` | POST | Fill form fields with real keystrokes |
-| `/click` | POST | Click by selector or text |
-| `/scroll` | POST | Scroll with content preview |
-| `/navigate` | POST | Go to URL, back, or forward (same tab) |
-| `/eval` | POST | Run JavaScript in any tab or iframe |
-| `/captcha` | POST | Detect captchas, basic interaction (experimental) |
-| `/focus` | POST | Bring a tab to the front |
-| `/tabs` | GET | List open tabs |
-| `/health` | GET | Check Chrome connection |
-
-Full API reference with response schemas: [API.md](./API.md)
+**Captcha detection** — `/recon` automatically detects captcha iframes (Arkose, reCAPTCHA, hCaptcha) and flags them. `/captcha` endpoint provides basic interaction.
+
+**Overlay detection** — modals, cookie banners, and blocking overlays are detected and reported so agents can dismiss them before interacting.
+
+**Same-tab navigation** — links with `target="_blank"` are automatically opened in the same tab instead of spawning new ones.
 
 ## Tab Targeting
 
-Every endpoint takes a `tab` field. You can target tabs three ways:
+Every endpoint accepts a `tab` field:
 
 ```json
 {"tab": "0"}           // by index
-{"tab": "github"}      // by URL or title (partial match)
-{"tab": "cdpn.io"}     // cross-origin iframes work too
+{"tab": "github"}      // partial match on URL or title
+{"tab": "stripe.com"}  // matches cross-origin iframes too
 ```
 
-## How Agents Should Use This
-
-The workflow is: **recon → act → read**.
+## Commands
 
-```
-1. /recon   → get the page map (selectors, forms, elements)
-2. /click   → click something using a selector from step 1
-   /fill    → fill a form using selectors from step 1
-3. /read    → check what happened (success message? error? new content?)
-4. /recon   → if the page changed, map it again
+```bash
+surfagent start     # Start Chrome + API (one command)
+surfagent chrome    # Start Chrome debug session only
+surfagent api       # Start API only (Chrome must be running)
+surfagent health    # Check if everything is running
+surfagent help      # Show all options
 ```
 
-Agents never need to guess selectors or parse screenshots. The recon response has everything.
-
 ## Tested On
 
-- Google Flights (autocomplete dropdowns, date pickers, complex forms)
-- YouTube (SPA navigation, search, video selection)
-- GitHub (login forms, repository pages)
-- Supabase (dashboard navigation, SQL editor)
-- Hacker News (link following, content reading)
-- Reddit (thread navigation, comments)
-- CodePen (cross-origin iframe interaction)
-- Polymarket (market data extraction)
+Google Flights, YouTube, GitHub, Supabase, Hacker News, Reddit, CodePen, Polymarket, npm — including autocomplete dropdowns, date pickers, complex forms, SPA navigation, cross-origin iframes, and captchas.
 
 ## Platform Support
 
@@ -173,6 +133,10 @@ Agents never need to guess selectors or parse screenshots. The recon response ha
 - Chrome (any recent version)
 - Node.js 18+
 
+## Contributing
+
+Issues and PRs welcome at [github.com/AllAboutAI-YT/surfagent](https://github.com/AllAboutAI-YT/surfagent).
+
 ## License
 
 MIT

package/dist/api/server.js

@@ -16,6 +16,11 @@ function json(res, status, data) {
     res.writeHead(status, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*' });
     res.end(JSON.stringify(data));
 }
+function parseBody(raw) {
+    if (!raw || !raw.trim())
+        throw new SyntaxError('Empty request body');
+    return JSON.parse(raw);
+}
 function cors(res) {
     res.writeHead(204, {
         'Access-Control-Allow-Origin': '*',
@@ -32,7 +37,7 @@ const server = http.createServer(async (req, res) => {
     try {
         // POST /recon — full page reconnaissance
         if (path === '/recon' && req.method === 'POST') {
-            const body = JSON.parse(await readBody(req));
+            const body = parseBody(await readBody(req));
             if (!body.url && !body.tab) {
                 return json(res, 400, { error: 'Provide "url" (to open new page) or "tab" (to recon existing tab)' });
             }
@@ -56,17 +61,20 @@ const server = http.createServer(async (req, res) => {
         }
         // POST /fill — fill form fields via CDP keystrokes
         if (path === '/fill' && req.method === 'POST') {
-            const body = JSON.parse(await readBody(req));
+            const body = parseBody(await readBody(req));
             if (!body.tab || !body.fields) {
                 return json(res, 400, { error: 'Provide "tab" and "fields" [{ selector, value }]' });
             }
+            if (!Array.isArray(body.fields)) {
+                return json(res, 400, { error: '"fields" must be an array of { selector, value }' });
+            }
             const start = Date.now();
             const result = await fillFields(body, { port: CDP_PORT, host: CDP_HOST });
             return json(res, 200, { ...result, _fillMs: Date.now() - start });
         }
         // POST /click — click an element
         if (path === '/click' && req.method === 'POST') {
-            const body = JSON.parse(await readBody(req));
+            const body = parseBody(await readBody(req));
             if (!body.tab || (!body.selector && !body.text)) {
                 return json(res, 400, { error: 'Provide "tab" and "selector" or "text"' });
             }
@@ -75,7 +83,7 @@ const server = http.createServer(async (req, res) => {
         }
         // POST /scroll — scroll a page
         if (path === '/scroll' && req.method === 'POST') {
-            const body = JSON.parse(await readBody(req));
+            const body = parseBody(await readBody(req));
             if (!body.tab) {
                 return json(res, 400, { error: 'Provide "tab", optional "direction" (down/up), "amount" (pixels)' });
             }
@@ -84,7 +92,7 @@ const server = http.createServer(async (req, res) => {
         }
         // POST /captcha — detect and interact with captchas
         if (path === '/captcha' && req.method === 'POST') {
-            const body = JSON.parse(await readBody(req));
+            const body = parseBody(await readBody(req));
             if (!body.action) {
                 return json(res, 400, { error: 'Provide "action": detect, read, next, prev, submit, audio, restart' });
             }
@@ -96,7 +104,7 @@ const server = http.createServer(async (req, res) => {
         }
         // POST /read — get structured readable content from a page
         if (path === '/read' && req.method === 'POST') {
-            const body = JSON.parse(await readBody(req));
+            const body = parseBody(await readBody(req));
             if (!body.tab) {
                 return json(res, 400, { error: 'Provide "tab", optional "selector"' });
             }
@@ -105,7 +113,7 @@ const server = http.createServer(async (req, res) => {
         }
         // POST /focus — bring a tab to front
         if (path === '/focus' && req.method === 'POST') {
-            const body = JSON.parse(await readBody(req));
+            const body = parseBody(await readBody(req));
             if (!body.tab) {
                 return json(res, 400, { error: 'Provide "tab"' });
             }
@@ -114,7 +122,7 @@ const server = http.createServer(async (req, res) => {
         }
         // POST /eval — run JavaScript in a tab or iframe
         if (path === '/eval' && req.method === 'POST') {
-            const body = JSON.parse(await readBody(req));
+            const body = parseBody(await readBody(req));
             if (!body.tab || !body.expression) {
                 return json(res, 400, { error: 'Provide "tab" and "expression"' });
             }
@@ -123,7 +131,7 @@ const server = http.createServer(async (req, res) => {
         }
         // POST /navigate — go to url, back, or forward in same tab
         if (path === '/navigate' && req.method === 'POST') {
-            const body = JSON.parse(await readBody(req));
+            const body = parseBody(await readBody(req));
             if (!body.tab) {
                 return json(res, 400, { error: 'Provide "tab" and one of: "url", "back":true, "forward":true' });
             }
@@ -150,6 +158,15 @@ const server = http.createServer(async (req, res) => {
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         console.error(`[${new Date().toISOString()}] Error:`, message);
+        if (error instanceof SyntaxError) {
+            return json(res, 400, { error: 'Invalid JSON: ' + message });
+        }
+        if (message.includes('Tab not found')) {
+            return json(res, 404, { error: message });
+        }
+        if (message.includes('Cannot connect to Chrome') || message.includes('ECONNREFUSED')) {
+            return json(res, 503, { error: 'Chrome not running. Start with: surfagent start' });
+        }
         json(res, 500, { error: message });
     }
 });

package/package.json

@@ -1,7 +1,29 @@
 {
   "name": "surfagent",
-  "version": "1.0.4",
-  "description": "Local API that gives AI agents structured page data from Chrome for fast, precise web navigation",
+  "version": "1.0.6",
+  "description": "Browser automation API for AI agents — structured page recon, form filling, clicking, and navigation via Chrome CDP",
+  "keywords": [
+    "ai-agent",
+    "browser-automation",
+    "chrome-devtools",
+    "cdp",
+    "web-scraping",
+    "automation",
+    "langchain",
+    "crewai",
+    "openai",
+    "claude",
+    "agent",
+    "browser",
+    "recon",
+    "selenium-alternative",
+    "puppeteer-alternative"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AllAboutAI-YT/surfagent"
+  },
+  "license": "MIT",
   "main": "dist/api/server.js",
   "type": "module",
   "bin": {

package/src/api/server.ts

@@ -27,6 +27,11 @@ function json(res: http.ServerResponse, status: number, data: any) {
   res.end(JSON.stringify(data));
 }
 
+function parseBody(raw: string): any {
+  if (!raw || !raw.trim()) throw new SyntaxError('Empty request body');
+  return JSON.parse(raw);
+}
+
 function cors(res: http.ServerResponse) {
   res.writeHead(204, {
     'Access-Control-Allow-Origin': '*',
@@ -45,7 +50,7 @@ const server = http.createServer(async (req, res) => {
   try {
     // POST /recon — full page reconnaissance
     if (path === '/recon' && req.method === 'POST') {
-      const body: RequestBody = JSON.parse(await readBody(req));
+      const body: RequestBody = parseBody(await readBody(req));
 
       if (!body.url && !body.tab) {
         return json(res, 400, { error: 'Provide "url" (to open new page) or "tab" (to recon existing tab)' });
@@ -73,10 +78,13 @@ const server = http.createServer(async (req, res) => {
 
     // POST /fill — fill form fields via CDP keystrokes
     if (path === '/fill' && req.method === 'POST') {
-      const body = JSON.parse(await readBody(req));
+      const body = parseBody(await readBody(req));
       if (!body.tab || !body.fields) {
         return json(res, 400, { error: 'Provide "tab" and "fields" [{ selector, value }]' });
       }
+      if (!Array.isArray(body.fields)) {
+        return json(res, 400, { error: '"fields" must be an array of { selector, value }' });
+      }
       const start = Date.now();
       const result = await fillFields(body, { port: CDP_PORT, host: CDP_HOST });
       return json(res, 200, { ...result, _fillMs: Date.now() - start });
@@ -84,7 +92,7 @@ const server = http.createServer(async (req, res) => {
 
     // POST /click — click an element
     if (path === '/click' && req.method === 'POST') {
-      const body = JSON.parse(await readBody(req));
+      const body = parseBody(await readBody(req));
       if (!body.tab || (!body.selector && !body.text)) {
         return json(res, 400, { error: 'Provide "tab" and "selector" or "text"' });
       }
@@ -94,7 +102,7 @@ const server = http.createServer(async (req, res) => {
 
     // POST /scroll — scroll a page
     if (path === '/scroll' && req.method === 'POST') {
-      const body = JSON.parse(await readBody(req));
+      const body = parseBody(await readBody(req));
       if (!body.tab) {
         return json(res, 400, { error: 'Provide "tab", optional "direction" (down/up), "amount" (pixels)' });
       }
@@ -104,7 +112,7 @@ const server = http.createServer(async (req, res) => {
 
     // POST /captcha — detect and interact with captchas
     if (path === '/captcha' && req.method === 'POST') {
-      const body = JSON.parse(await readBody(req));
+      const body = parseBody(await readBody(req));
       if (!body.action) {
         return json(res, 400, { error: 'Provide "action": detect, read, next, prev, submit, audio, restart' });
       }
@@ -117,7 +125,7 @@ const server = http.createServer(async (req, res) => {
 
     // POST /read — get structured readable content from a page
     if (path === '/read' && req.method === 'POST') {
-      const body = JSON.parse(await readBody(req));
+      const body = parseBody(await readBody(req));
       if (!body.tab) {
         return json(res, 400, { error: 'Provide "tab", optional "selector"' });
       }
@@ -127,7 +135,7 @@ const server = http.createServer(async (req, res) => {
 
     // POST /focus — bring a tab to front
     if (path === '/focus' && req.method === 'POST') {
-      const body = JSON.parse(await readBody(req));
+      const body = parseBody(await readBody(req));
       if (!body.tab) {
         return json(res, 400, { error: 'Provide "tab"' });
       }
@@ -137,7 +145,7 @@ const server = http.createServer(async (req, res) => {
 
     // POST /eval — run JavaScript in a tab or iframe
     if (path === '/eval' && req.method === 'POST') {
-      const body = JSON.parse(await readBody(req));
+      const body = parseBody(await readBody(req));
       if (!body.tab || !body.expression) {
         return json(res, 400, { error: 'Provide "tab" and "expression"' });
       }
@@ -147,7 +155,7 @@ const server = http.createServer(async (req, res) => {
 
     // POST /navigate — go to url, back, or forward in same tab
     if (path === '/navigate' && req.method === 'POST') {
-      const body = JSON.parse(await readBody(req));
+      const body = parseBody(await readBody(req));
       if (!body.tab) {
         return json(res, 400, { error: 'Provide "tab" and one of: "url", "back":true, "forward":true' });
       }
@@ -175,6 +183,16 @@ const server = http.createServer(async (req, res) => {
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     console.error(`[${new Date().toISOString()}] Error:`, message);
+
+    if (error instanceof SyntaxError) {
+      return json(res, 400, { error: 'Invalid JSON: ' + message });
+    }
+    if (message.includes('Tab not found')) {
+      return json(res, 404, { error: message });
+    }
+    if (message.includes('Cannot connect to Chrome') || message.includes('ECONNREFUSED')) {
+      return json(res, 503, { error: 'Chrome not running. Start with: surfagent start' });
+    }
     json(res, 500, { error: message });
   }
 });