hanzi-browse 2.2.0

package/dist/relay/server.js

@@ -0,0 +1,403 @@
+#!/usr/bin/env node
+/**
+ * WebSocket Relay Server
+ *
+ * Stateless message router between extension, MCP server, and CLI.
+ * Replaces file-based IPC with real-time WebSocket communication.
+ *
+ * Roles:
+ *   - extension: Chrome extension service worker (one at a time)
+ *   - mcp: MCP server (can have multiple)
+ *   - cli: CLI clients (can have multiple)
+ *
+ * Routing:
+ *   - extension → originating mcp/cli client when tagged, otherwise broadcast
+ *   - mcp/cli → send to extension
+ */
+import { WebSocketServer, WebSocket } from 'ws';
+import { randomUUID } from 'crypto';
+import { getClaudeCredentials, getClaudeKeychainCredentials, getCodexCredentials, refreshClaudeToken, saveClaudeCredentials, } from '../llm/credentials.js';
+const DEFAULT_PORT = 7862;
+const port = parseInt(process.env.WS_RELAY_PORT || String(DEFAULT_PORT), 10);
+const clients = new Map();
+// Queue messages for extension when it's disconnected (service worker sleeping)
+const extensionQueue = [];
+const MAX_QUEUE_SIZE = 50;
+const QUEUE_MAX_AGE_MS = 60000; // Drop queued messages older than 60s
+const queueTimestamps = [];
+function log(msg) {
+    console.error(`[Relay] ${msg}`);
+}
+function getClientsByRole(role) {
+    return Array.from(clients.values()).filter(c => c.role === role);
+}
+function getExtension() {
+    return getClientsByRole('extension')[0];
+}
+function sendToConsumers(message, targetClientId, exclude) {
+    for (const [ws, client] of clients) {
+        const isConsumer = client.role === 'mcp' || client.role === 'cli';
+        const matchesTarget = !targetClientId || client.clientId === targetClientId;
+        if (ws !== exclude && ws.readyState === WebSocket.OPEN && isConsumer && matchesTarget) {
+            ws.send(message);
+        }
+    }
+}
+function sendToExtension(message) {
+    const ext = getExtension();
+    if (ext && ext.ws.readyState === WebSocket.OPEN) {
+        ext.ws.send(message);
+        return true;
+    }
+    // Extension not connected — queue the message for delivery on reconnect
+    // Deduplicate start_task by sessionId: if a start_task for the same session
+    // is already queued, replace it instead of adding a duplicate.
+    try {
+        const parsed = JSON.parse(message);
+        if (parsed.type === 'mcp_start_task' && parsed.sessionId) {
+            for (let i = 0; i < extensionQueue.length; i++) {
+                try {
+                    const queued = JSON.parse(extensionQueue[i]);
+                    if (queued.type === 'mcp_start_task' && queued.sessionId === parsed.sessionId) {
+                        log(`Deduplicating queued start_task for session ${parsed.sessionId}`);
+                        extensionQueue[i] = message;
+                        queueTimestamps[i] = Date.now();
+                        return true;
+                    }
+                }
+                catch { /* skip malformed */ }
+            }
+        }
+    }
+    catch { /* not JSON, queue as-is */ }
+    if (extensionQueue.length >= MAX_QUEUE_SIZE) {
+        extensionQueue.shift();
+        queueTimestamps.shift();
+    }
+    extensionQueue.push(message);
+    queueTimestamps.push(Date.now());
+    log(`Extension offline, queued message (${extensionQueue.length} pending)`);
+    return true; // Return true — message is queued, not lost
+}
+function flushExtensionQueue(ext) {
+    if (extensionQueue.length === 0)
+        return;
+    const now = Date.now();
+    let delivered = 0;
+    let expired = 0;
+    while (extensionQueue.length > 0) {
+        const msg = extensionQueue.shift();
+        const ts = queueTimestamps.shift();
+        if (now - ts > QUEUE_MAX_AGE_MS) {
+            expired++;
+            continue;
+        }
+        ext.ws.send(msg);
+        delivered++;
+    }
+    log(`Flushed queue: ${delivered} delivered, ${expired} expired`);
+}
+const wss = new WebSocketServer({ port }, () => {
+    log(`Listening on ws://localhost:${port}`);
+});
+wss.on('error', (err) => {
+    if (err.code === 'EADDRINUSE') {
+        log(`Port ${port} already in use — another relay is running. Exiting.`);
+        process.exit(0);
+    }
+    log(`Server error: ${err.message}`);
+    process.exit(1);
+});
+wss.on('connection', (ws) => {
+    log(`New connection (${clients.size + 1} total)`);
+    ws.on('message', (data) => {
+        let msg;
+        try {
+            msg = JSON.parse(data.toString());
+        }
+        catch {
+            log('Invalid JSON received, ignoring');
+            return;
+        }
+        // Handle registration
+        if (msg.type === 'register') {
+            const role = msg.role;
+            if (!['extension', 'mcp', 'cli'].includes(role)) {
+                ws.send(JSON.stringify({ type: 'error', error: `Invalid role: ${role}` }));
+                return;
+            }
+            // If a new extension registers, disconnect old one
+            if (role === 'extension') {
+                const existing = getExtension();
+                if (existing && existing.ws !== ws) {
+                    log('New extension connecting, closing old one');
+                    existing.ws.close(1000, 'replaced');
+                    clients.delete(existing.ws);
+                }
+            }
+            clients.set(ws, {
+                ws,
+                role,
+                clientId: randomUUID().slice(0, 8),
+                sessionId: msg.sessionId,
+                registeredAt: Date.now(),
+            });
+            ws.send(JSON.stringify({ type: 'registered', role, clientId: clients.get(ws).clientId }));
+            log(`Client registered as ${role} (${clients.size} total)`);
+            // Deliver any queued messages to the extension
+            if (role === 'extension') {
+                flushExtensionQueue(clients.get(ws));
+            }
+            return;
+        }
+        // Route messages based on sender role
+        const client = clients.get(ws);
+        if (!client) {
+            // Unregistered client — require registration first
+            ws.send(JSON.stringify({ type: 'error', error: 'Must register first' }));
+            return;
+        }
+        // Handle status_query — relay answers directly (no round trip to extension)
+        if (msg.type === 'status_query') {
+            const ext = getExtension();
+            ws.send(JSON.stringify({
+                type: 'status_response',
+                requestId: msg.requestId,
+                extensionConnected: !!ext && ext.ws.readyState === WebSocket.OPEN,
+            }));
+            return;
+        }
+        // Handle read_credentials — relay reads from filesystem (replaces native host)
+        if (msg.type === 'read_credentials' && client.role === 'extension') {
+            const { credentialType } = msg;
+            try {
+                if (credentialType === 'claude') {
+                    const creds = getClaudeCredentials() || getClaudeKeychainCredentials();
+                    if (creds) {
+                        ws.send(JSON.stringify({
+                            type: 'credentials_result',
+                            requestId: msg.requestId,
+                            credentialType: 'claude',
+                            credentials: {
+                                accessToken: creds.accessToken,
+                                refreshToken: creds.refreshToken,
+                                expiresAt: creds.expiresAt,
+                            },
+                        }));
+                    }
+                    else {
+                        ws.send(JSON.stringify({
+                            type: 'credentials_result',
+                            requestId: msg.requestId,
+                            credentialType: 'claude',
+                            error: 'Claude credentials not found. Run `claude login` first.',
+                        }));
+                    }
+                }
+                else if (credentialType === 'codex') {
+                    const creds = getCodexCredentials();
+                    if (creds) {
+                        ws.send(JSON.stringify({
+                            type: 'credentials_result',
+                            requestId: msg.requestId,
+                            credentialType: 'codex',
+                            credentials: {
+                                accessToken: creds.accessToken,
+                                refreshToken: creds.refreshToken,
+                                accountId: creds.accountId,
+                            },
+                        }));
+                    }
+                    else {
+                        ws.send(JSON.stringify({
+                            type: 'credentials_result',
+                            requestId: msg.requestId,
+                            credentialType: 'codex',
+                            error: 'Codex credentials not found. Run `codex auth login` first.',
+                        }));
+                    }
+                }
+                else {
+                    ws.send(JSON.stringify({
+                        type: 'credentials_result',
+                        requestId: msg.requestId,
+                        error: `Unknown credential type: ${credentialType}`,
+                    }));
+                }
+            }
+            catch (err) {
+                ws.send(JSON.stringify({
+                    type: 'credentials_result',
+                    requestId: msg.requestId,
+                    error: err.message,
+                }));
+            }
+            return;
+        }
+        // Handle proxy_api_call — relay proxies API calls with impersonation headers
+        if (msg.type === 'proxy_api_call' && client.role === 'extension') {
+            handleApiProxy(ws, msg);
+            return;
+        }
+        const raw = data.toString();
+        if (client.role === 'extension') {
+            // Extension → originating MCP/CLI client when known, otherwise broadcast
+            sendToConsumers(raw, typeof msg.sourceClientId === 'string' ? msg.sourceClientId : undefined);
+        }
+        else {
+            // MCP/CLI → send to extension (queued if offline)
+            sendToExtension(JSON.stringify({ ...msg, sourceClientId: client.clientId }));
+        }
+    });
+    ws.on('close', () => {
+        const client = clients.get(ws);
+        if (client) {
+            log(`${client.role} disconnected (${clients.size - 1} remaining)`);
+            clients.delete(ws);
+        }
+    });
+    ws.on('error', (err) => {
+        log(`WebSocket error: ${err.message}`);
+    });
+});
+/**
+ * Proxy API calls with Claude Code impersonation headers.
+ * Reads OAuth token, makes the API call, streams SSE events back to extension.
+ */
+async function handleApiProxy(ws, msg) {
+    const { requestId, url, body } = msg;
+    const PROXY_TIMEOUT_MS = 150000;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), PROXY_TIMEOUT_MS);
+    const EXPIRY_BUFFER_MS = 60 * 1000;
+    const getFreshClaudeCredentials = async () => {
+        const existing = getClaudeCredentials() || getClaudeKeychainCredentials();
+        if (!existing) {
+            return null;
+        }
+        if (existing.expiresAt && existing.expiresAt > Date.now() + EXPIRY_BUFFER_MS) {
+            return existing;
+        }
+        log('Claude OAuth token expired or near expiry, refreshing before proxy call');
+        const refreshed = await refreshClaudeToken(existing.refreshToken);
+        saveClaudeCredentials(refreshed);
+        return refreshed;
+    };
+    try {
+        // Read OAuth credentials
+        let creds = await getFreshClaudeCredentials();
+        if (!creds) {
+            ws.send(JSON.stringify({ type: 'proxy_api_error', requestId, error: 'No Claude credentials found' }));
+            return;
+        }
+        // Claude Code impersonation headers
+        const headers = {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${creds.accessToken}`,
+            'anthropic-version': '2023-06-01',
+            'anthropic-dangerous-direct-browser-access': 'true',
+            'anthropic-beta': 'claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14',
+            'x-app': 'cli',
+            'user-agent': 'claude-code/2.1.29 (Darwin; arm64)',
+        };
+        let response = await fetch(url, { method: 'POST', headers, body, signal: controller.signal });
+        if (response.status === 401) {
+            log('Claude proxy request got 401, refreshing token and retrying once');
+            const refreshed = await refreshClaudeToken(creds.refreshToken);
+            saveClaudeCredentials(refreshed);
+            creds = refreshed;
+            headers.Authorization = `Bearer ${creds.accessToken}`;
+            response = await fetch(url, { method: 'POST', headers, body, signal: controller.signal });
+        }
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => '');
+            clearTimeout(timeoutId);
+            ws.send(JSON.stringify({
+                type: 'proxy_api_error',
+                requestId,
+                error: `API error: ${response.status} - ${errorText.slice(0, 500)}`,
+            }));
+            return;
+        }
+        // Parse SSE stream and forward events to extension
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split('\n');
+            buffer = lines.pop();
+            for (const line of lines) {
+                if (!line.startsWith('data: '))
+                    continue;
+                const data = line.slice(6);
+                if (data === '[DONE]')
+                    continue;
+                try {
+                    const event = JSON.parse(data);
+                    // Forward each SSE event to extension
+                    if (ws.readyState === WebSocket.OPEN) {
+                        ws.send(JSON.stringify({
+                            type: 'proxy_stream_chunk',
+                            requestId,
+                            data: event,
+                        }));
+                    }
+                }
+                catch {
+                    // Skip malformed JSON
+                }
+            }
+        }
+        clearTimeout(timeoutId);
+        // Signal stream complete
+        if (ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify({ type: 'proxy_stream_end', requestId }));
+        }
+    }
+    catch (err) {
+        clearTimeout(timeoutId);
+        if (ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify({
+                type: 'proxy_api_error',
+                requestId,
+                error: err.name === 'AbortError'
+                    ? `API proxy request timed out after ${PROXY_TIMEOUT_MS / 1000} seconds`
+                    : err.message,
+            }));
+        }
+    }
+}
+// Graceful shutdown
+process.on('SIGINT', () => {
+    log('Shutting down...');
+    wss.close();
+    process.exit(0);
+});
+process.on('SIGTERM', () => {
+    log('Shutting down...');
+    wss.close();
+    process.exit(0);
+});
+// Keep alive — log stats periodically
+setInterval(() => {
+    const roles = { extension: 0, mcp: 0, cli: 0 };
+    for (const client of clients.values()) {
+        roles[client.role]++;
+    }
+    if (clients.size > 0) {
+        log(`Clients: ${clients.size} (ext:${roles.extension} mcp:${roles.mcp} cli:${roles.cli})`);
+    }
+}, 30000);
+// Ping the extension every 20 seconds to keep its service worker alive.
+// Chrome suspends MV3 service workers after ~30s of inactivity, which drops
+// the WebSocket. Application-level pings (not WS frames) wake the worker.
+setInterval(() => {
+    const ext = getExtension();
+    if (ext && ext.ws.readyState === WebSocket.OPEN) {
+        ext.ws.send(JSON.stringify({ type: 'ping' }));
+    }
+}, 20000);

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Type Exports
+ */
+export type { SessionState, Session, SerializedSession, Question, TraceEntry, CreateSessionOptions, TransitionResult, SessionStatus, } from "./session.js";
+export { VALID_TRANSITIONS } from "./session.js";

package/dist/types/index.js

@@ -0,0 +1,4 @@
+/**
+ * Type Exports
+ */
+export { VALID_TRANSITIONS } from "./session.js";

package/dist/types/session.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Session Types
+ *
+ * Defines the session state machine and related types for browser automation tasks.
+ */
+/**
+ * All possible states a session can be in.
+ *
+ * State transitions:
+ *   CREATED → EXECUTING → COMPLETED
+ *                ↓
+ *             WAITING_FOR_USER → EXECUTING
+ *   Any state can transition to FAILED or CANCELLED
+ */
+export type SessionState = "CREATED" | "EXECUTING" | "WAITING_FOR_USER" | "COMPLETED" | "FAILED" | "CANCELLED";
+/**
+ * Valid state transitions for the session state machine.
+ */
+export declare const VALID_TRANSITIONS: Record<SessionState, SessionState[]>;
+/**
+ * A question to ask the user for missing information.
+ */
+export interface Question {
+    /** Unique identifier for the question */
+    id: string;
+    /** The field/info this question is asking about (e.g., "email", "departure_date") */
+    field: string;
+    /** Human-readable question to display */
+    question: string;
+    /** Optional hint or example */
+    hint?: string;
+    /** Whether this is required or optional */
+    required: boolean;
+    /** Data type expected (for validation) */
+    type?: "text" | "email" | "date" | "password" | "number" | "choice";
+    /** For choice type, the available options */
+    options?: string[];
+}
+/**
+ * A single entry in the execution trace.
+ */
+export interface TraceEntry {
+    timestamp: string;
+    type: "navigation" | "click" | "fill" | "screenshot" | "thinking" | "error" | "info";
+    description: string;
+    url?: string;
+    selector?: string;
+    value?: string;
+    screenshot?: string;
+    success: boolean;
+    error?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Main session object tracking a browser automation task.
+ */
+export interface Session {
+    id: string;
+    state: SessionState;
+    task: string;
+    url?: string;
+    context?: string;
+    domain?: string;
+    collectedInfo: Record<string, string>;
+    pendingQuestions: Question[];
+    executionTrace: TraceEntry[];
+    currentStep?: string;
+    answer?: string;
+    error?: string;
+    createdAt: Date;
+    updatedAt: Date;
+    completedAt?: Date;
+}
+/**
+ * Serializable session data for storage/transport.
+ * Dates are converted to ISO strings.
+ */
+export interface SerializedSession {
+    id: string;
+    state: SessionState;
+    task: string;
+    url?: string;
+    context?: string;
+    domain?: string;
+    collectedInfo: Record<string, string>;
+    pendingQuestions: Question[];
+    executionTrace: TraceEntry[];
+    currentStep?: string;
+    answer?: string;
+    error?: string;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+}
+/**
+ * Options for creating a new session.
+ */
+export interface CreateSessionOptions {
+    task: string;
+    url?: string;
+    context?: string;
+}
+/**
+ * Result of a state transition attempt.
+ */
+export interface TransitionResult {
+    /** Whether the transition was successful */
+    success: boolean;
+    /** Previous state (if successful) */
+    previousState?: SessionState;
+    /** New state (if successful) */
+    newState?: SessionState;
+    /** Error message (if failed) */
+    error?: string;
+}
+/**
+ * Session status for external API responses.
+ * Simplified view of session state.
+ */
+export interface SessionStatus {
+    sessionId: string;
+    status: SessionState;
+    task: string;
+    domain?: string;
+    currentStep?: string;
+    /** Summary of steps taken */
+    steps: string[];
+    /** If NEEDS_INFO, the questions to answer */
+    questions?: string[];
+    /** If COMPLETED, the answer/result */
+    answer?: string;
+    /** If FAILED, the error message */
+    error?: string;
+}

package/dist/types/session.js

@@ -0,0 +1,16 @@
+/**
+ * Session Types
+ *
+ * Defines the session state machine and related types for browser automation tasks.
+ */
+/**
+ * Valid state transitions for the session state machine.
+ */
+export const VALID_TRANSITIONS = {
+    CREATED: ["EXECUTING", "FAILED", "CANCELLED"],
+    EXECUTING: ["COMPLETED", "WAITING_FOR_USER", "FAILED", "CANCELLED"],
+    WAITING_FOR_USER: ["EXECUTING", "FAILED", "CANCELLED"],
+    COMPLETED: [], // Terminal state
+    FAILED: [], // Terminal state
+    CANCELLED: [], // Terminal state
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "hanzi-browse",
+  "version": "2.2.0",
+  "description": "Give your AI agent a real browser — click, type, fill forms, test workflows, post content, and read authenticated pages",
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "author": "hanzili",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hanzili/hanzi-browse.git"
+  },
+  "type": "module",
+  "bin": {
+    "hanzi-browse": "./dist/index.js",
+    "hanzi-browser": "./dist/cli.js",
+    "hanzi-relay": "./dist/relay/server.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && cd dashboard && npm run build",
+    "build:server": "tsc",
+    "build:dashboard": "cd dashboard && npm run build",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "cli": "node dist/cli.js",
+    "test": "npx tsx test/test-agents.ts",
+    "test:live": "npx tsx test/test-live.ts",
+    "test:followup": "npx tsx test/test-followup.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "better-auth": "^1.5.5",
+    "pg": "^8.11.3",
+    "stripe": "^20.4.1",
+    "undici": "^7.24.5",
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@types/pg": "^8.18.0",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.3.0",
+    "vitest": "^4.1.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "browser",
+    "chrome",
+    "automation",
+    "claude",
+    "model-context-protocol",
+    "browser-automation",
+    "web-agent"
+  ]
+}

package/skills/README.md

@@ -0,0 +1,48 @@
+# Hanzi Browse Skills
+
+Agent skills for [Hanzi Browse](https://browse.hanzilla.co) — give your AI agent a real browser.
+
+## Core Skill
+
+| Skill | Description |
+|-------|-------------|
+| [hanzi-browse](hanzi-browse/) | Browser automation via MCP — click, type, fill forms, read authenticated pages |
+
+## Workflow Skills
+
+| Skill | Description |
+|-------|-------------|
+| [e2e-tester](e2e-tester/) | Test web apps like a QA person with real browser interactions |
+| [social-poster](social-poster/) | Draft and post content across LinkedIn, Twitter/X, Reddit |
+| [linkedin-prospector](linkedin-prospector/) | Find and connect with prospects on LinkedIn |
+| [a11y-auditor](a11y-auditor/) | Run accessibility audits in a real browser |
+| [x-marketer](x-marketer/) | Twitter/X marketing workflows |
+
+## Installation
+
+### Claude Code
+```bash
+# Copy a skill to your project
+cp -r hanzi-browse/ .claude/skills/hanzi-browse/
+
+# Or install globally
+cp -r hanzi-browse/ ~/.claude/skills/hanzi-browse/
+```
+
+### Cursor
+```bash
+cp -r hanzi-browse/ .cursor/skills/hanzi-browse/
+```
+
+### Other agents
+Copy the skill directory to your agent's skills folder. See [awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills) for paths.
+
+## Setup
+
+The skills require the Hanzi Browse MCP server:
+
+```bash
+npx hanzi-browse setup
+```
+
+This installs the Chrome extension and configures your AI agents automatically.