openclaw-browsy 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# openclaw-browsy
+
+Zero-render browser plugin for OpenClaw. Integrates [browsy](https://github.com/nichochar/agentbrowser) as a fast, lightweight alternative to Playwright/CDP for AI agent browsing tasks.
+
+## Why browsy?
+
+OpenClaw's built-in browser uses Playwright + CDP: ~300MB RAM, 2-5s per page. browsy handles 70%+ of agent browsing tasks (forms, logins, search, data extraction) at **10x speed** and **60x less memory** by parsing HTML into a Spatial DOM without rendering pixels.
+
+## Install
+
+```bash
+npm install openclaw-browsy
+```
+
+Requires the `browsy` CLI binary in your PATH. Install from the [browsy releases](https://github.com/nichochar/agentbrowser/releases).
+
+## Configure
+
+In your OpenClaw config:
+
+```json
+{
+  "plugins": {
+    "openclaw-browsy": {
+      "port": 3847,
+      "autoStart": true,
+      "allowPrivateNetwork": false,
+      "preferBrowsy": true,
+      "serverTimeout": 10000
+    }
+  }
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `port` | `3847` | Port for the browsy REST server |
+| `autoStart` | `true` | Start `browsy serve` automatically on plugin init |
+| `allowPrivateNetwork` | `false` | Allow fetching private/internal network URLs |
+| `preferBrowsy` | `true` | Intercept built-in browser tool calls and redirect through browsy |
+| `serverTimeout` | `10000` | Timeout (ms) waiting for server startup |
+
+## Usage
+
+### As an OpenClaw plugin
+
+```typescript
+// openclaw.config.ts
+import { register } from "openclaw-browsy";
+export default { register };
+```
+
+Once registered, every agent gets 13 browsy tools automatically:
+
+| Tool | Description |
+|------|-------------|
+| `browsy_browse` | Navigate to a URL |
+| `browsy_click` | Click an element by ID |
+| `browsy_type_text` | Type text into an input |
+| `browsy_check` | Check a checkbox/radio |
+| `browsy_uncheck` | Uncheck a checkbox/radio |
+| `browsy_select` | Select a dropdown option |
+| `browsy_search` | Search the web |
+| `browsy_login` | Log in with credentials |
+| `browsy_enter_code` | Enter a 2FA/verification code |
+| `browsy_find` | Find elements by text or ARIA role |
+| `browsy_page_info` | Get page metadata and suggested actions |
+| `browsy_tables` | Extract structured table data |
+| `browsy_back` | Go back in browsing history |
+
+### Standalone
+
+```typescript
+import { BrowsyContext } from "openclaw-browsy";
+
+const ctx = new BrowsyContext({ port: 3847, autoStart: false });
+const result = await ctx.executeToolCall("browse", { url: "https://example.com" });
+console.log(result);
+```
+
+## Skills
+
+Three runtime skills are included:
+
+- **browse-and-extract** — Navigate + extract with auto-handling of login walls and cookie consent
+- **web-research** — Search + read multiple pages + compile summary
+- **form-filler** — Detect form fields + fill + submit using page intelligence
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+import type { BrowsyConfig, BrowsyConfigInput } from "./types.js";
+export declare function defaultConfig(): BrowsyConfig;
+/**
+ * Merge partial user input onto defaults, producing a complete BrowsyConfig.
+ */
+export declare function parseConfig(input?: BrowsyConfigInput): BrowsyConfig;

package/dist/config.js

@@ -0,0 +1,30 @@
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+export function defaultConfig() {
+    return {
+        port: 3847,
+        autoStart: true,
+        allowPrivateNetwork: false,
+        preferBrowsy: true,
+        serverTimeout: 10_000,
+    };
+}
+// ---------------------------------------------------------------------------
+// Config parsing
+// ---------------------------------------------------------------------------
+/**
+ * Merge partial user input onto defaults, producing a complete BrowsyConfig.
+ */
+export function parseConfig(input) {
+    const base = defaultConfig();
+    if (!input)
+        return base;
+    return {
+        port: input.port ?? base.port,
+        autoStart: input.autoStart ?? base.autoStart,
+        allowPrivateNetwork: input.allowPrivateNetwork ?? base.allowPrivateNetwork,
+        preferBrowsy: input.preferBrowsy ?? base.preferBrowsy,
+        serverTimeout: input.serverTimeout ?? base.serverTimeout,
+    };
+}

package/dist/context.d.ts

@@ -0,0 +1,26 @@
+import type { BrowsyConfig, BrowsyConfigInput, BrowsyServerInfo } from "./types.js";
+import { BrowsyClient } from "./core/client.js";
+import { ServerManager } from "./core/server-manager.js";
+import { SessionManager } from "./core/session-manager.js";
+/**
+ * Central facade holding config, client, server manager, and session manager.
+ * One instance per plugin lifetime.
+ */
+export declare class BrowsyContext {
+    readonly config: BrowsyConfig;
+    readonly client: BrowsyClient;
+    readonly serverManager: ServerManager;
+    readonly sessionManager: SessionManager;
+    /** Agent ID to use when no agent context is available */
+    private defaultAgentId;
+    constructor(configInput?: BrowsyConfigInput);
+    /** Ensure the browsy server is running. */
+    ensureServer(): Promise<void>;
+    /** Get current server status. */
+    getStatus(): BrowsyServerInfo;
+    /**
+     * Execute a browsy tool call.
+     * Ensures server is running, manages sessions, calls the client, and returns results.
+     */
+    executeToolCall(method: string, params: Record<string, unknown>, agentId?: string): Promise<string>;
+}

package/dist/context.js

@@ -0,0 +1,100 @@
+import { parseConfig } from "./config.js";
+import { BrowsyClient } from "./core/client.js";
+import { ServerManager } from "./core/server-manager.js";
+import { SessionManager } from "./core/session-manager.js";
+/**
+ * Central facade holding config, client, server manager, and session manager.
+ * One instance per plugin lifetime.
+ */
+export class BrowsyContext {
+    config;
+    client;
+    serverManager;
+    sessionManager;
+    /** Agent ID to use when no agent context is available */
+    defaultAgentId = "__default__";
+    constructor(configInput) {
+        this.config = parseConfig(configInput);
+        this.client = new BrowsyClient(this.config.port);
+        this.serverManager = new ServerManager(this.config);
+        this.sessionManager = new SessionManager();
+    }
+    /** Ensure the browsy server is running. */
+    async ensureServer() {
+        if (!this.serverManager.isRunning()) {
+            await this.serverManager.start();
+        }
+    }
+    /** Get current server status. */
+    getStatus() {
+        return this.serverManager.getStatus();
+    }
+    /**
+     * Execute a browsy tool call.
+     * Ensures server is running, manages sessions, calls the client, and returns results.
+     */
+    async executeToolCall(method, params, agentId) {
+        await this.ensureServer();
+        const aid = agentId ?? this.defaultAgentId;
+        const session = this.sessionManager.getOrCreate(aid);
+        const token = session.token || undefined;
+        let response;
+        switch (method) {
+            case "browse":
+                response = await this.client.browse(params, token);
+                break;
+            case "click":
+                response = await this.client.click(params, token);
+                break;
+            case "typeText":
+                response = await this.client.typeText(params, token);
+                break;
+            case "check":
+                response = await this.client.check(params, token);
+                break;
+            case "uncheck":
+                response = await this.client.uncheck(params, token);
+                break;
+            case "select":
+                response = await this.client.select(params, token);
+                break;
+            case "search":
+                response = await this.client.search(params, token);
+                break;
+            case "login":
+                response = await this.client.login(params, token);
+                break;
+            case "enterCode":
+                response = await this.client.enterCode(params, token);
+                break;
+            case "find":
+                response = await this.client.find(params, token);
+                break;
+            case "pageInfo":
+                response = await this.client.pageInfo(token);
+                break;
+            case "tables":
+                response = await this.client.tables(token);
+                break;
+            case "getPage":
+                response = await this.client.getPage(params, token);
+                break;
+            case "back":
+                response = await this.client.back(token);
+                break;
+            default:
+                throw new Error(`Unknown browsy method: ${method}`);
+        }
+        // Update session token from response
+        if (response.session) {
+            this.sessionManager.update(aid, response.session);
+        }
+        // Append CAPTCHA/blocked fallback guidance if detected
+        let result = response.body;
+        if (!response.ok) {
+            const errorJson = response.json;
+            result = errorJson?.error ?? response.body;
+        }
+        return result;
+    }
+}

package/dist/core/client.d.ts

@@ -0,0 +1,70 @@
+import type { BrowsyResponse } from "../types.js";
+/**
+ * HTTP client for the browsy REST API.
+ * Uses Node.js built-in fetch(). Passes and extracts X-Browsy-Session header.
+ */
+export declare class BrowsyClient {
+    private baseUrl;
+    constructor(port: number);
+    /** GET /health */
+    health(): Promise<BrowsyResponse>;
+    /** POST /api/browse */
+    browse(params: {
+        url: string;
+        format?: string;
+        scope?: string;
+    }, session?: string): Promise<BrowsyResponse>;
+    /** POST /api/click */
+    click(params: {
+        id: number;
+    }, session?: string): Promise<BrowsyResponse>;
+    /** POST /api/type */
+    typeText(params: {
+        id: number;
+        text: string;
+    }, session?: string): Promise<BrowsyResponse>;
+    /** POST /api/check */
+    check(params: {
+        id: number;
+    }, session?: string): Promise<BrowsyResponse>;
+    /** POST /api/uncheck */
+    uncheck(params: {
+        id: number;
+    }, session?: string): Promise<BrowsyResponse>;
+    /** POST /api/select */
+    select(params: {
+        id: number;
+        value: string;
+    }, session?: string): Promise<BrowsyResponse>;
+    /** POST /api/search */
+    search(params: {
+        query: string;
+        engine?: string;
+    }, session?: string): Promise<BrowsyResponse>;
+    /** POST /api/login */
+    login(params: {
+        username: string;
+        password: string;
+    }, session?: string): Promise<BrowsyResponse>;
+    /** POST /api/enter-code */
+    enterCode(params: {
+        code: string;
+    }, session?: string): Promise<BrowsyResponse>;
+    /** POST /api/find */
+    find(params: {
+        text?: string;
+        role?: string;
+    }, session?: string): Promise<BrowsyResponse>;
+    /** GET /api/page */
+    getPage(params?: {
+        format?: string;
+        scope?: string;
+    }, session?: string): Promise<BrowsyResponse>;
+    /** GET /api/page-info */
+    pageInfo(session?: string): Promise<BrowsyResponse>;
+    /** GET /api/tables */
+    tables(session?: string): Promise<BrowsyResponse>;
+    /** POST /api/back */
+    back(session?: string): Promise<BrowsyResponse>;
+    private request;
+}

package/dist/core/client.js

@@ -0,0 +1,109 @@
+/**
+ * HTTP client for the browsy REST API.
+ * Uses Node.js built-in fetch(). Passes and extracts X-Browsy-Session header.
+ */
+export class BrowsyClient {
+    baseUrl;
+    constructor(port) {
+        this.baseUrl = `http://127.0.0.1:${port}`;
+    }
+    /** GET /health */
+    async health() {
+        return this.request("GET", "/health");
+    }
+    /** POST /api/browse */
+    async browse(params, session) {
+        return this.request("POST", "/api/browse", params, session);
+    }
+    /** POST /api/click */
+    async click(params, session) {
+        return this.request("POST", "/api/click", params, session);
+    }
+    /** POST /api/type */
+    async typeText(params, session) {
+        return this.request("POST", "/api/type", params, session);
+    }
+    /** POST /api/check */
+    async check(params, session) {
+        return this.request("POST", "/api/check", params, session);
+    }
+    /** POST /api/uncheck */
+    async uncheck(params, session) {
+        return this.request("POST", "/api/uncheck", params, session);
+    }
+    /** POST /api/select */
+    async select(params, session) {
+        return this.request("POST", "/api/select", params, session);
+    }
+    /** POST /api/search */
+    async search(params, session) {
+        return this.request("POST", "/api/search", params, session);
+    }
+    /** POST /api/login */
+    async login(params, session) {
+        return this.request("POST", "/api/login", params, session);
+    }
+    /** POST /api/enter-code */
+    async enterCode(params, session) {
+        return this.request("POST", "/api/enter-code", params, session);
+    }
+    /** POST /api/find */
+    async find(params, session) {
+        return this.request("POST", "/api/find", params, session);
+    }
+    /** GET /api/page */
+    async getPage(params, session) {
+        const query = new URLSearchParams();
+        if (params?.format)
+            query.set("format", params.format);
+        if (params?.scope)
+            query.set("scope", params.scope);
+        const qs = query.toString();
+        return this.request("GET", `/api/page${qs ? `?${qs}` : ""}`, undefined, session);
+    }
+    /** GET /api/page-info */
+    async pageInfo(session) {
+        return this.request("GET", "/api/page-info", undefined, session);
+    }
+    /** GET /api/tables */
+    async tables(session) {
+        return this.request("GET", "/api/tables", undefined, session);
+    }
+    /** POST /api/back */
+    async back(session) {
+        return this.request("POST", "/api/back", undefined, session);
+    }
+    // ---------------------------------------------------------------------------
+    // Internal
+    // ---------------------------------------------------------------------------
+    async request(method, path, body, session) {
+        const headers = {};
+        if (session) {
+            headers["X-Browsy-Session"] = session;
+        }
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+        }
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        const responseSession = res.headers.get("X-Browsy-Session") ?? session ?? "";
+        const text = await res.text();
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            // Response is plain text, not JSON
+        }
+        return {
+            ok: res.ok,
+            status: res.status,
+            session: responseSession,
+            body: text,
+            json,
+        };
+    }
+}

package/dist/core/index.d.ts

@@ -0,0 +1,4 @@
+export { BrowsyClient } from "./client.js";
+export { ServerManager } from "./server-manager.js";
+export { SessionManager } from "./session-manager.js";
+export { createBrowsyTools } from "./tool-definitions.js";

package/dist/core/index.js

@@ -0,0 +1,4 @@
+export { BrowsyClient } from "./client.js";
+export { ServerManager } from "./server-manager.js";
+export { SessionManager } from "./session-manager.js";
+export { createBrowsyTools } from "./tool-definitions.js";

package/dist/core/server-manager.d.ts

@@ -0,0 +1,22 @@
+import type { BrowsyConfig, BrowsyServerInfo } from "../types.js";
+/**
+ * Manages the lifecycle of a `browsy serve` child process.
+ */
+export declare class ServerManager {
+    private process;
+    private status;
+    private error;
+    private config;
+    private client;
+    constructor(config: BrowsyConfig);
+    /** Start the browsy server. No-op if already running. */
+    start(): Promise<void>;
+    /** Stop the browsy server. */
+    stop(): Promise<void>;
+    /** Whether the server is running. */
+    isRunning(): boolean;
+    /** Get the current server status. */
+    getStatus(): BrowsyServerInfo;
+    /** Poll /health until ready or timeout. */
+    waitForReady(): Promise<void>;
+}

package/dist/core/server-manager.js

@@ -0,0 +1,115 @@
+import { spawn } from "node:child_process";
+import { BrowsyClient } from "./client.js";
+import { findBrowsyBinary, isPortInUse } from "../utils/process.js";
+/**
+ * Manages the lifecycle of a `browsy serve` child process.
+ */
+export class ServerManager {
+    process = null;
+    status = "stopped";
+    error;
+    config;
+    client;
+    constructor(config) {
+        this.config = config;
+        this.client = new BrowsyClient(config.port);
+    }
+    /** Start the browsy server. No-op if already running. */
+    async start() {
+        if (this.status === "running")
+            return;
+        // Check if something is already listening on the port
+        if (await isPortInUse(this.config.port)) {
+            // Verify it's actually browsy by hitting /health
+            try {
+                const res = await this.client.health();
+                if (res.ok) {
+                    this.status = "running";
+                    return;
+                }
+            }
+            catch {
+                // Port in use but not browsy — error
+            }
+            this.status = "error";
+            this.error = `Port ${this.config.port} is already in use by another process`;
+            throw new Error(this.error);
+        }
+        const binary = findBrowsyBinary();
+        if (!binary) {
+            this.status = "error";
+            this.error = "browsy binary not found in PATH";
+            throw new Error(this.error);
+        }
+        this.status = "starting";
+        this.error = undefined;
+        const args = ["serve", "--port", String(this.config.port)];
+        if (this.config.allowPrivateNetwork) {
+            args.push("--allow-private-network");
+        }
+        this.process = spawn(binary, args, {
+            stdio: "pipe",
+            detached: false,
+        });
+        this.process.on("error", (err) => {
+            this.status = "error";
+            this.error = err.message;
+        });
+        this.process.on("exit", (code) => {
+            if (this.status !== "error") {
+                this.status = "stopped";
+            }
+            if (code !== null && code !== 0) {
+                this.status = "error";
+                this.error = `browsy exited with code ${code}`;
+            }
+            this.process = null;
+        });
+        await this.waitForReady();
+    }
+    /** Stop the browsy server. */
+    async stop() {
+        if (!this.process) {
+            this.status = "stopped";
+            return;
+        }
+        this.process.kill();
+        this.process = null;
+        this.status = "stopped";
+        this.error = undefined;
+    }
+    /** Whether the server is running. */
+    isRunning() {
+        return this.status === "running";
+    }
+    /** Get the current server status. */
+    getStatus() {
+        return {
+            status: this.status,
+            port: this.config.port,
+            pid: this.process?.pid,
+            error: this.error,
+        };
+    }
+    /** Poll /health until ready or timeout. */
+    async waitForReady() {
+        const deadline = Date.now() + this.config.serverTimeout;
+        const interval = 200;
+        while (Date.now() < deadline) {
+            try {
+                const res = await this.client.health();
+                if (res.ok) {
+                    this.status = "running";
+                    return;
+                }
+            }
+            catch {
+                // Server not ready yet
+            }
+            await new Promise((r) => setTimeout(r, interval));
+        }
+        this.status = "error";
+        this.error = `browsy server did not become ready within ${this.config.serverTimeout}ms`;
+        throw new Error(this.error);
+    }
+}

package/dist/core/session-manager.d.ts

@@ -0,0 +1,20 @@
+import type { BrowsySession } from "../types.js";
+/**
+ * Maps agentId -> browsy session token.
+ * Each agent gets its own isolated browsing session.
+ */
+export declare class SessionManager {
+    private sessions;
+    /** Get existing session or create a placeholder for the agent. */
+    getOrCreate(agentId: string): BrowsySession;
+    /** Update the session token (from X-Browsy-Session response header). */
+    update(agentId: string, token: string): void;
+    /** Remove an agent's session. */
+    remove(agentId: string): boolean;
+    /** Get a session by agentId. */
+    get(agentId: string): BrowsySession | undefined;
+    /** List all active sessions. */
+    listSessions(): BrowsySession[];
+    /** Number of active sessions. */
+    count(): number;
+}

package/dist/core/session-manager.js

@@ -0,0 +1,50 @@
+/**
+ * Maps agentId -> browsy session token.
+ * Each agent gets its own isolated browsing session.
+ */
+export class SessionManager {
+    sessions = new Map();
+    /** Get existing session or create a placeholder for the agent. */
+    getOrCreate(agentId) {
+        const existing = this.sessions.get(agentId);
+        if (existing)
+            return existing;
+        const session = {
+            agentId,
+            token: "", // Will be populated from server response
+            createdAt: new Date().toISOString(),
+        };
+        this.sessions.set(agentId, session);
+        return session;
+    }
+    /** Update the session token (from X-Browsy-Session response header). */
+    update(agentId, token) {
+        const session = this.sessions.get(agentId);
+        if (session) {
+            session.token = token;
+        }
+        else {
+            this.sessions.set(agentId, {
+                agentId,
+                token,
+                createdAt: new Date().toISOString(),
+            });
+        }
+    }
+    /** Remove an agent's session. */
+    remove(agentId) {
+        return this.sessions.delete(agentId);
+    }
+    /** Get a session by agentId. */
+    get(agentId) {
+        return this.sessions.get(agentId);
+    }
+    /** List all active sessions. */
+    listSessions() {
+        return Array.from(this.sessions.values());
+    }
+    /** Number of active sessions. */
+    count() {
+        return this.sessions.size;
+    }
+}

package/dist/core/tool-definitions.d.ts

@@ -0,0 +1,6 @@
+import type { ToolDescriptor } from "../types.js";
+import type { BrowsyContext } from "../context.js";
+/**
+ * Create the 13 browsy tools that map to the browsy REST API.
+ */
+export declare function createBrowsyTools(ctx: BrowsyContext): ToolDescriptor[];