tab-agent 0.2.0

package/relay/node_modules/ws/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "ws",
+  "version": "8.19.0",
+  "description": "Simple to use, blazing fast and thoroughly tested websocket client and server for Node.js",
+  "keywords": [
+    "HyBi",
+    "Push",
+    "RFC-6455",
+    "WebSocket",
+    "WebSockets",
+    "real-time"
+  ],
+  "homepage": "https://github.com/websockets/ws",
+  "bugs": "https://github.com/websockets/ws/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/websockets/ws.git"
+  },
+  "author": "Einar Otto Stangvik <einaros@gmail.com> (http://2x.io)",
+  "license": "MIT",
+  "main": "index.js",
+  "exports": {
+    ".": {
+      "browser": "./browser.js",
+      "import": "./wrapper.mjs",
+      "require": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "browser": "browser.js",
+  "engines": {
+    "node": ">=10.0.0"
+  },
+  "files": [
+    "browser.js",
+    "index.js",
+    "lib/*.js",
+    "wrapper.mjs"
+  ],
+  "scripts": {
+    "test": "nyc --reporter=lcov --reporter=text mocha --throw-deprecation test/*.test.js",
+    "integration": "mocha --throw-deprecation test/*.integration.js",
+    "lint": "eslint . && prettier --check --ignore-path .gitignore \"**/*.{json,md,yaml,yml}\""
+  },
+  "peerDependencies": {
+    "bufferutil": "^4.0.1",
+    "utf-8-validate": ">=5.0.2"
+  },
+  "peerDependenciesMeta": {
+    "bufferutil": {
+      "optional": true
+    },
+    "utf-8-validate": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "benchmark": "^2.1.4",
+    "bufferutil": "^4.0.1",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-prettier": "^5.0.0",
+    "globals": "^16.0.0",
+    "mocha": "^8.4.0",
+    "nyc": "^15.0.0",
+    "prettier": "^3.0.0",
+    "utf-8-validate": "^6.0.0"
+  }
+}

package/relay/node_modules/ws/wrapper.mjs

@@ -0,0 +1,8 @@
+import createWebSocketStream from './lib/stream.js';
+import Receiver from './lib/receiver.js';
+import Sender from './lib/sender.js';
+import WebSocket from './lib/websocket.js';
+import WebSocketServer from './lib/websocket-server.js';
+
+export { createWebSocketStream, Receiver, Sender, WebSocket, WebSocketServer };
+export default WebSocket;

package/relay/package-lock.json

@@ -0,0 +1,36 @@
+{
+  "name": "tab-agent-relay",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "tab-agent-relay",
+      "version": "0.1.0",
+      "dependencies": {
+        "ws": "^8.16.0"
+      }
+    },
+    "node_modules/ws": {
+      "version": "8.19.0",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.19.0.tgz",
+      "integrity": "sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    }
+  }
+}

package/relay/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "tab-agent-relay",
+  "version": "0.1.0",
+  "description": "WebSocket relay for Tab Agent Chrome extension",
+  "main": "server.js",
+  "scripts": {
+    "start": "node server.js"
+  },
+  "dependencies": {
+    "ws": "^8.16.0"
+  }
+}

package/relay/server.js

@@ -0,0 +1,114 @@
+// relay/server.js
+const WebSocket = require('ws');
+const http = require('http');
+
+const PORT = process.env.PORT || 9876;
+
+const httpServer = http.createServer((req, res) => {
+  if (req.url === '/health') {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ ok: true, clients: wss.clients.size }));
+  } else {
+    res.writeHead(404);
+    res.end('Not found');
+  }
+});
+
+const wss = new WebSocket.Server({ server: httpServer });
+
+// Store extension connection
+let extensionConnection = null;
+const pendingRequests = new Map();
+
+function safeParse(data, label) {
+  try {
+    return JSON.parse(data);
+  } catch (error) {
+    console.warn(`Invalid JSON from ${label}:`, error);
+    return null;
+  }
+}
+
+function failPendingRequests(reason) {
+  for (const [id, pending] of pendingRequests.entries()) {
+    try {
+      pending.ws.send(JSON.stringify({ id: pending.clientId, ok: false, error: reason }));
+    } catch (error) {
+      console.warn('Failed to notify pending request:', error);
+    }
+    pendingRequests.delete(id);
+  }
+}
+
+wss.on('connection', (ws, req) => {
+  const isExtension = req.headers['x-client-type'] === 'extension';
+
+  if (isExtension) {
+    console.log('Extension connected');
+    extensionConnection = ws;
+
+    ws.on('message', (data) => {
+      const message = safeParse(data, 'extension');
+      if (!message || typeof message.id === 'undefined') {
+        return;
+      }
+      const { id, ...response } = message;
+
+      const pending = pendingRequests.get(id);
+      if (pending) {
+        pending.ws.send(JSON.stringify({ id: pending.clientId, ...response }));
+        pendingRequests.delete(id);
+      }
+    });
+
+    ws.on('close', () => {
+      console.log('Extension disconnected');
+      extensionConnection = null;
+      failPendingRequests('Extension disconnected');
+    });
+
+  } else {
+    console.log('Skill client connected');
+
+    ws.on('message', async (data) => {
+      const message = safeParse(data, 'client');
+      if (!message || typeof message.id === 'undefined') {
+        return;
+      }
+      const { id, ...command } = message;
+
+      console.log(`Command: ${command.action}`, command);
+
+      if (!extensionConnection) {
+        ws.send(JSON.stringify({ id, ok: false, error: 'Extension not connected' }));
+        return;
+      }
+
+      const internalId = Date.now() + Math.random();
+      pendingRequests.set(internalId, { ws, clientId: id });
+
+      extensionConnection.send(JSON.stringify({ id: internalId, ...command }));
+    });
+
+    ws.on('close', () => {
+      console.log('Skill client disconnected');
+      for (const [id, pending] of pendingRequests.entries()) {
+        if (pending.ws === ws) {
+          pendingRequests.delete(id);
+        }
+      }
+    });
+  }
+});
+
+httpServer.listen(PORT, () => {
+  console.log(`Tab Agent Relay running on ws://localhost:${PORT}`);
+  console.log(`Health check: http://localhost:${PORT}/health`);
+});
+
+process.on('SIGINT', () => {
+  console.log('\nShutting down...');
+  wss.close();
+  httpServer.close();
+  process.exit(0);
+});

package/skills/claude-code/tab-agent.md

@@ -0,0 +1,53 @@
+---
+name: tab-agent
+description: Browser control via WebSocket - snapshot, click, type, fill, evaluate, screenshot
+---
+
+# Tab Agent
+
+WebSocket `ws://localhost:9876`. User activates tabs via extension icon (green = active).
+
+## Before First Command
+
+```bash
+curl -s http://localhost:9876/health || (npx tab-agent start &)
+sleep 2
+```
+
+## Commands
+
+```json
+{"id": 1, "action": "tabs"}                                    // list active tabs
+{"id": 2, "action": "snapshot", "tabId": ID}                   // get page with refs [e1], [e2]...
+{"id": 3, "action": "screenshot", "tabId": ID}                 // viewport screenshot
+{"id": 4, "action": "screenshot", "tabId": ID, "fullPage": true}  // full page screenshot
+{"id": 5, "action": "click", "tabId": ID, "ref": "e1"}         // click element
+{"id": 6, "action": "fill", "tabId": ID, "ref": "e1", "value": "text"}  // fill input
+{"id": 7, "action": "type", "tabId": ID, "ref": "e1", "text": "hello"}  // type text
+{"id": 8, "action": "type", "tabId": ID, "ref": "e1", "text": "query", "submit": true}  // type and Enter
+{"id": 9, "action": "press", "tabId": ID, "key": "Enter"}      // press key
+{"id": 10, "action": "scroll", "tabId": ID, "direction": "down", "amount": 500}
+{"id": 11, "action": "scrollintoview", "tabId": ID, "ref": "e1"}  // scroll element visible
+{"id": 12, "action": "navigate", "tabId": ID, "url": "https://..."}
+{"id": 13, "action": "wait", "tabId": ID, "text": "Loading complete"}  // wait for text
+{"id": 14, "action": "wait", "tabId": ID, "selector": ".results", "timeout": 5000}  // wait for element
+{"id": 15, "action": "evaluate", "tabId": ID, "script": "document.title"}  // run JavaScript
+{"id": 16, "action": "batchfill", "tabId": ID, "fields": [{"ref": "e1", "value": "a"}, {"ref": "e2", "value": "b"}]}
+{"id": 17, "action": "dialog", "tabId": ID, "accept": true}    // handle alert/confirm
+```
+
+## Usage
+
+1. `tabs` -> get tabId of active tab
+2. `snapshot` -> read page, get element refs [e1], [e2]...
+3. `click`/`fill`/`type` using refs
+4. If snapshot incomplete (complex page) -> `screenshot` and analyze visually
+
+## Notes
+
+- Screenshot returns `{"screenshot": "data:image/png;base64,..."}` - analyze directly
+- Snapshot refs reset on each call - always snapshot before interacting
+- Keys: Enter, Escape, Tab, Backspace, ArrowUp/Down/Left/Right
+- `type` with `submit: true` presses Enter after typing (for search boxes)
+- `evaluate` runs in page context - can access page variables/functions
+- `dialog` handles alert/confirm/prompt - debugger bar appears when attached

package/skills/codex/tab-agent.md

@@ -0,0 +1,40 @@
+---
+name: tab-agent
+description: Browser control via WebSocket
+---
+
+# Tab Agent
+
+`ws://localhost:9876` - User activates tabs via extension (green = active)
+
+## Start Relay
+
+```bash
+curl -s http://localhost:9876/health || (npx tab-agent start &)
+```
+
+## Commands
+
+```
+tabs                                  -> list active tabs
+snapshot tabId                        -> page with refs [e1], [e2]...
+screenshot tabId                      -> viewport screenshot (base64 PNG)
+screenshot tabId fullPage=true        -> full page screenshot
+click tabId ref                       -> click element
+fill tabId ref value                  -> fill input
+type tabId ref text                   -> type text
+type tabId ref text submit=true       -> type and press Enter
+press tabId key                       -> Enter/Escape/Tab/Arrow*
+scroll tabId direction amount         -> scroll page
+scrollintoview tabId ref              -> scroll element visible
+navigate tabId url                    -> go to URL
+wait tabId text="..."                 -> wait for text
+wait tabId selector="..." timeout=ms  -> wait for element
+evaluate tabId script="..."           -> run JavaScript
+batchfill tabId fields=[...]          -> fill multiple fields
+dialog tabId accept=true              -> handle alert/confirm
+```
+
+## Flow
+
+`tabs` -> `snapshot` -> `click`/`fill` -> repeat. Use `screenshot` if snapshot incomplete.