@vymalo/opencode-browser 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vymalo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,321 @@
+# @vymalo/opencode-browser
+
+> Give an OpenCode agent hands in a real browser — open tabs, click, type, scroll, screenshot —
+> organized into **named tab groups**.
+
+[![npm](https://img.shields.io/npm/v/@vymalo/opencode-browser)](https://www.npmjs.com/package/@vymalo/opencode-browser)
+![node: >=22](https://img.shields.io/badge/node-%3E%3D22-339933)
+![license: MIT](https://img.shields.io/badge/license-MIT-blue)
+
+This is the **OpenCode plugin** half of a dual plugin. It registers `browser_*` tools the model
+can call and hosts a localhost WebSocket **bridge**. A companion **browser extension**
+(Chromium MV3 + Firefox) connects to the bridge and drives real tabs.
+
+> Browser extensions can't host servers, so the plugin is the server and the extension dials
+> out to it. The plugin runs on Bun (inside OpenCode) and serves the bridge with `Bun.serve`.
+
+```mermaid
+flowchart LR
+    Model[OpenCode model] -->|browser_* tools| Plugin["@vymalo/opencode-browser<br/>(bridge host)"]
+    Plugin <-->|ws://127.0.0.1:4517<br/>token handshake| Ext[Browser extension]
+    Ext -->|CDP / content script| Tabs[(Real browser tabs<br/>in named groups)]
+```
+
+## Table of contents
+
+- [How it works](#how-it-works)
+- [Install](#install)
+- [Quickstart](#quickstart)
+- [Options](#options)
+- [The 33 tools](#the-33-tools)
+- [Targeting elements](#targeting-elements--prefer-refs)
+- [Screenshots](#screenshots)
+- [Named groups](#named-groups)
+- [Scoping tools per agent](#scoping-tools-per-agent)
+- [Multiple browsers & agents](#multiple-browsers--agents)
+- [Executors: CDP vs content-script](#executors-cdp-vs-content-script)
+- [Stopping / releasing control](#stopping--releasing-control)
+- [Security](#security)
+- [Troubleshooting](#troubleshooting)
+
+## How it works
+
+1. OpenCode loads the plugin; it binds a WebSocket bridge on `127.0.0.1:<port>` and prints a
+   shared `token` (or uses the one you set).
+2. You load the extension once, paste the bridge URL + token into its dashboard, and connect.
+3. The model calls a `browser_*` tool → the plugin sends a command frame over the bridge → the
+   extension executes it against a real tab → the result comes back to the model.
+
+The extension and plugin agree on a small, dependency-free wire protocol; the same protocol is
+mirrored into the extension so the two never drift.
+
+## Install
+
+```jsonc
+// opencode.json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [["@vymalo/opencode-browser", { "port": 4517 }]]
+}
+```
+
+On first run with no `token`, the plugin generates one and logs it once
+(`browser_bridge_token_generated`). Paste that into the extension's dashboard along with the
+bridge URL (`ws://127.0.0.1:4517`).
+
+Get the extension from the [Releases page](https://github.com/vymalo/opencode-oauth2/releases)
+(`opencode-browser-extension-<version>-chrome.zip` / `-firefox.zip`), from the Chrome Web Store /
+Firefox Add-ons, or build it from
+[`apps/browser-extension`](https://github.com/vymalo/opencode-oauth2/tree/main/apps/browser-extension).
+
+## Quickstart
+
+A typical first session, end to end:
+
+```text
+You:    Open example.com in a group called "research" and tell me the page heading.
+Model:  browser_open({ group: "research", url: "https://example.com" })
+        browser_snapshot({ group: "research" })          → refs e1, e2, …
+        browser_get_text({ group: "research" })
+        → "Example Domain — This domain is for use in illustrative examples…"
+
+You:    Screenshot it.
+Model:  browser_screenshot({ group: "research", fullPage: true })
+        → "Saved screenshot to .opencode/browser/research/2026-…png (1280×3200)."
+        (the model then reads that file to see it)
+```
+
+A titled **tab group** named "research" appears in the browser; the extension dashboard logs
+every action and keeps a screenshot gallery.
+
+## Options
+
+Second argument to the plugin tuple in `opencode.json`:
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `true` | Master switch. |
+| `host` | `"127.0.0.1"` | Bind interface. **Keep it loopback** — see [Security](#security). |
+| `port` | `4517` | Bridge port. |
+| `token` | _generated_ | Shared secret the extension must present. Empty string ⇒ generated + logged. |
+| `groups` | `["page","control"]` | Tool groups to register (`page` \| `control` \| `debug`). |
+| `executor` | `"auto"` | `auto` \| `cdp` \| `content` — forwarded to the extension as a preference. |
+| `timeoutMs` | `30000` | Per-command timeout. |
+| `screenshotDir` | `".opencode/browser"` | Screenshot output dir (relative → resolved against the worktree). |
+
+## The 33 tools
+
+Names are stable `browser_*` identifiers, partitioned into three **groups** gated by the
+`groups` option. Every tool takes a `group` (the named tab group) unless noted.
+
+### `page` — observe (8, default on)
+
+| Tool | Key args | Does |
+| --- | --- | --- |
+| `browser_snapshot` | `group` | Accessibility/DOM outline with stable **refs** the other tools target. Start here. |
+| `browser_get_text` | `group, tabId?` | Visible/readable text of the active tab. |
+| `browser_get_html` | `group, ref?/selector?, outer?` | HTML of an element or the document. |
+| `browser_get_attribute` | `group, ref?/selector, name?` | Tag, text, value, and attributes of an element. |
+| `browser_query` | `group, selector, limit?` | Match a CSS selector → list of elements with fresh refs. |
+| `browser_tabs` | `group?` | List groups and their tabs. Omit `group` for everything you own. |
+| `browser_targets` | — | List connected browsers (for multi-browser routing). |
+| `browser_screenshot` | `group, fullPage?, tabId?` | PNG to disk; returns the path. See [Screenshots](#screenshots). |
+
+### `control` — drive (19, default on)
+
+| Tool | Key args | Does |
+| --- | --- | --- |
+| `browser_open` | `group, url?, focus?, target?` | Open a tab in the group (creates the group on first use). |
+| `browser_navigate` | `group, url, tabId?` | Navigate an existing tab. |
+| `browser_back` / `browser_forward` / `browser_reload` | `group, tabId?` | History / reload. |
+| `browser_activate` | `group, tabId?` | Bring a tab to the foreground. |
+| `browser_click` | `group, ref?/selector?/x?,y?, button?` | Click an element or coordinates. |
+| `browser_double_click` | `group, ref?/selector?/x?,y?` | Double-click. |
+| `browser_hover` | `group, ref?/selector?/x?,y?` | Hover. |
+| `browser_drag` | `group, fromRef?/fromSelector?, ref?/selector?` | Drag source → target. |
+| `browser_type` | `group, text, ref?/selector?, submit?` | Type into a field (optionally press Enter). |
+| `browser_fill` | `group, fields:[{ref?/selector,value}]` | Batch-fill several fields. |
+| `browser_select` | `group, ref?/selector, value?/values?` | Choose `<select>` option(s). |
+| `browser_press_key` | `group, key` | Press a key or chord (`"Enter"`, `"Control+a"`). |
+| `browser_scroll` | `group, deltaX?, deltaY?, ref?, to?` | Scroll the page or an element. |
+| `browser_upload` | `group, ref?/selector, paths:[…]` | Attach file(s) to a file input (CDP/Chromium). |
+| `browser_wait` | `group, ms?/selector?, state?` | Wait a fixed delay or for a selector. |
+| `browser_close` | `group, tabId?` | Close a tab, or the whole group if `tabId` omitted. |
+| `browser_release` | `group?` | Hand the browser back (detach CDP) without closing tabs. |
+
+### `debug` — powerful / sensitive (6, **off by default**)
+
+Enable with `{ "groups": ["page","control","debug"] }`.
+
+| Tool | Key args | Does |
+| --- | --- | --- |
+| `browser_eval` | `group, code, tabId?` | Evaluate arbitrary JavaScript in the page. |
+| `browser_console` | `group` | Recent console messages. |
+| `browser_network` | `group` | Recent network requests. |
+| `browser_handle_dialog` | `group, accept?, promptText?` | Accept/dismiss a native `alert`/`confirm`/`prompt`. |
+| `browser_set_viewport` | `group, width, height, mobile?, deviceScaleFactor?` | Emulate a viewport (CDP/Chromium only). |
+| `browser_cookies` | `op, url?, name?, …` | Get/list/set/clear cookies (profile-wide). |
+
+## Targeting elements — prefer refs
+
+Two ways to address an element:
+
+- **By ref (recommended)** — call `browser_snapshot` (or `browser_query`), get back stable refs
+  like `e1`, `e2`, then `browser_click({ group, ref: "e3" })`. Refs survive minor layout shifts
+  and are far more reliable than brittle selectors.
+- **By CSS selector or coordinates** — `selector: "#login"` or `x`/`y`. Useful for canvases,
+  maps, and elements a snapshot doesn't expose.
+
+## Screenshots
+
+OpenCode tool output is **text-only** — it can't carry an image. So the plugin writes the PNG to
+`<screenshotDir>/<group>/<timestamp>.png` and returns the path; the model then opens it with
+OpenCode's built-in `read` tool (which renders images). `fullPage: true` captures the whole
+scrollable page (CDP `captureBeyondViewport` on Chromium; scroll-and-stitch on the content
+executor). The extension also keeps a copy in its dashboard gallery.
+
+> Driving from a non-OpenCode MCP client instead? `@vymalo/opencode-browser-mcp` returns
+> screenshots as **inline images** (MCP can carry them).
+
+## Named groups
+
+Every action targets a **group** — a named bucket of tabs the agent created. On Chromium groups
+map to real `chrome.tabGroups` (titled, colored); on Firefox they're a logical registry. Groups
+keep each task's tabs isolated and inspectable, and are the unit of ownership when multiple
+agents share one bridge.
+
+## Scoping tools per agent
+
+There are **two independent levers**, and they answer different questions:
+
+| Lever | Scope | Use it to |
+| --- | --- | --- |
+| `groups` plugin option | **Global** — which tools are *registered* at all | Set the org-wide default surface. |
+| OpenCode agent `tools` map | **Per-agent** — which registered tools an agent may *call* | Give each agent only the tools it needs. |
+
+If your team keeps **all groups enabled by default** (`"groups": ["page","control","debug"]`),
+the `groups` option won't narrow anything — every `browser_*` tool is registered. To restrict an
+individual agent, use OpenCode's per-agent **`tools`** map (a `{ "<tool>": true|false }` record on
+the agent). The tool names are stable `browser_*` identifiers (see [the 33 tools](#the-33-tools)),
+so you target them directly. This is OpenCode's own mechanism — nothing plugin-specific.
+
+### Denylist — drop the sensitive tools (most common)
+
+Keep everything except the `debug` group and destructive actions for a general agent:
+
+```jsonc
+// opencode.json
+{
+  "plugin": [["@vymalo/opencode-browser", {}]],   // all groups stay registered
+  "agent": {
+    "build": {
+      "tools": {
+        "browser_eval": false,
+        "browser_cookies": false,
+        "browser_console": false,
+        "browser_network": false,
+        "browser_handle_dialog": false,
+        "browser_set_viewport": false,
+        "browser_close": false
+      }
+    }
+  }
+}
+```
+
+### Allowlist — a read-only research agent (observe, never drive)
+
+Disable the whole namespace with a wildcard, then re-enable only the `page` tools you want. A
+more specific key wins over the `browser_*` wildcard:
+
+```jsonc
+{
+  "agent": {
+    "researcher": {
+      "description": "Reads pages, never changes them.",
+      "tools": {
+        "browser_*": false,
+        "browser_open": true,
+        "browser_navigate": true,
+        "browser_snapshot": true,
+        "browser_get_text": true,
+        "browser_query": true,
+        "browser_screenshot": true,
+        "browser_tabs": true
+      }
+    }
+  }
+}
+```
+
+### Markdown agents
+
+The same `tools` map works in a `.opencode/agent/<name>.md` front-matter file:
+
+```markdown
+---
+description: Reads pages, never changes them.
+tools:
+  browser_*: false
+  browser_snapshot: true
+  browser_get_text: true
+  browser_screenshot: true
+---
+You are a read-only web researcher. Use browser_snapshot to get refs, then read.
+```
+
+> The plugin-level `groups` option is still useful as a hard floor — e.g. **never** register
+> `debug` org-wide with `{ "groups": ["page","control"] }`, then no agent can re-enable
+> `browser_eval` no matter its `tools` map. Use `groups` for "nobody gets this," and the agent
+> `tools` map for "this agent only gets these."
+
+## Multiple browsers & agents
+
+The bridge is an **auto-elect broker**: multiple agents (plugin, MCP, sessions) and multiple
+executors (browsers) can share one bridge. The first process to bind the port becomes the host;
+others join as guests. Groups are owned by the agent that created them (owner-exclusive), and
+ownership is rebuilt automatically on failover. Use `browser_targets` to see connected browsers
+and `browser_open({ target })` to pick one. Full design:
+[`plans/multi-client-routing.md`](https://github.com/vymalo/opencode-oauth2/blob/main/plans/multi-client-routing.md).
+
+## Executors: CDP vs content-script
+
+- **CDP executor** (`chrome.debugger`, Chromium) — trusted input, full-page capture, console &
+  network logs. Shows Chrome's "being debugged" banner — an intentional signal.
+- **Content-script executor** — synthetic events + `captureVisibleTab`; the Firefox-safe
+  fallback, also used when the debugger is unavailable.
+
+`executor: "auto"` picks CDP on Chromium when the `debugger` permission is granted, else the
+content script. Force one with `"cdp"` / `"content"`.
+
+## Stopping / releasing control
+
+Control is **plugin-managed** — you never disconnect by hand. It's released when:
+
+- the model/plugin calls **`browser_release`** (mid-session), or
+- **OpenCode exits** — the plugin's `exit` hook shuts the bridge down, and the dropped socket
+  independently makes the extension release. A hard kill releases too.
+
+## Security
+
+The bridge binds `127.0.0.1` only and requires a token handshake. It grants the model control of
+a **real browser profile** — **use a dedicated or throwaway Chrome profile**, not your daily one.
+The `chrome.debugger` banner is a deliberate, continuous indicator that automation is active.
+`debug` tools (`browser_eval`, `browser_cookies`, …) are off by default for this reason. See the
+consolidated [`docs/security.md`](https://github.com/vymalo/opencode-oauth2/blob/main/docs/security.md).
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+| --- | --- |
+| Extension won't connect | URL/token mismatch, or another process already on the port. Re-copy the logged token. |
+| "being debugged" banner stays after a session | Normal until release; `browser_release` or exiting OpenCode clears it. |
+| `set_viewport` / full-page differs on Firefox | CDP-only features; Firefox uses the content executor. |
+| Screenshot path returned but model "can't see" it | The model must `read` the path — output is text-only. |
+
+Symptom-keyed fixes: [`docs/troubleshooting.md`](https://github.com/vymalo/opencode-oauth2/blob/main/docs/troubleshooting.md).
+Full architecture, wire protocol, and tool reference: [`docs/browser.md`](https://github.com/vymalo/opencode-oauth2/blob/main/docs/browser.md).
+
+## License
+
+[MIT](https://github.com/vymalo/opencode-oauth2/blob/main/LICENSE) © vymalo contributors

package/dist/agent-client.d.ts

@@ -0,0 +1,54 @@
+import type { AgentEndpoint } from "./broker.js";
+import type { Logger } from "./logging.js";
+import { type BrowserAction } from "./protocol.js";
+/** Minimal socket the agent-client drives — provided per runtime by the endpoint. */
+export interface AgentSocket {
+    send(data: string): void;
+    close(): void;
+}
+export interface AgentSocketHandlers {
+    onOpen(): void;
+    onMessage(data: string): void;
+    onClose(): void;
+}
+export type AgentSocketFactory = (url: string, handlers: AgentSocketHandlers) => AgentSocket;
+export interface AgentClientOptions {
+    url: string;
+    token: string;
+    label?: string;
+    timeoutMs: number;
+}
+export interface AgentClientDeps {
+    logger: Logger;
+    createSocket: AgentSocketFactory;
+    /** Called when the connection drops (host gone) — the endpoint re-elects. */
+    onClose?: () => void;
+}
+export declare class AgentClientError extends Error {
+    readonly code?: string;
+    constructor(message: string, code?: string);
+}
+/**
+ * Connects to a running broker as an `agent` and brokers request/response for the
+ * host adapter's tools (the guest path). One connection attempt + lifecycle; the
+ * endpoint orchestrates re-election/reconnect via `onClose`.
+ */
+export declare class AgentClient implements AgentEndpoint {
+    private readonly opts;
+    private readonly deps;
+    private socket;
+    private ready;
+    private closed;
+    private readonly pending;
+    private readyWaiters;
+    constructor(opts: AgentClientOptions, deps: AgentClientDeps);
+    connect(): Promise<void>;
+    stop(): void;
+    release(): void;
+    send(action: BrowserAction, group: string, params: Record<string, unknown>, signal?: AbortSignal, target?: string): Promise<unknown>;
+    private waitReady;
+    private handleResult;
+    private clearPending;
+    private settleReject;
+    private rejectAllPending;
+}

package/dist/agent-client.js

@@ -0,0 +1,180 @@
+import { decodeFrame, encodeFrame, helloFrame, nextId, PROTOCOL_VERSION } from "./protocol.js";
+export class AgentClientError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "AgentClientError";
+        this.code = code;
+    }
+}
+/**
+ * Connects to a running broker as an `agent` and brokers request/response for the
+ * host adapter's tools (the guest path). One connection attempt + lifecycle; the
+ * endpoint orchestrates re-election/reconnect via `onClose`.
+ */
+export class AgentClient {
+    opts;
+    deps;
+    socket = null;
+    ready = false;
+    closed = false;
+    pending = new Map();
+    readyWaiters = [];
+    constructor(opts, deps) {
+        this.opts = opts;
+        this.deps = deps;
+    }
+    connect() {
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            this.socket = this.deps.createSocket(this.opts.url, {
+                onOpen: () => {
+                    this.socket?.send(encodeFrame(helloFrame(this.opts.token, { role: "agent", client: this.opts.label })));
+                    // Resolve only once the broker replies `ready`.
+                },
+                onMessage: (data) => {
+                    const frame = decodeFrame(data);
+                    if (!frame) {
+                        return;
+                    }
+                    if (frame.type === "ready") {
+                        this.ready = true;
+                        for (const w of this.readyWaiters.splice(0)) {
+                            w();
+                        }
+                        if (!settled) {
+                            settled = true;
+                            resolve();
+                        }
+                    }
+                    else if (frame.type === "result") {
+                        this.handleResult(frame);
+                    }
+                },
+                onClose: () => {
+                    this.ready = false;
+                    this.rejectAllPending(new AgentClientError("disconnected from bridge", "disconnected"));
+                    this.socket = null;
+                    if (!settled) {
+                        settled = true;
+                        reject(new AgentClientError("bridge connection closed before ready", "connect_failed"));
+                    }
+                    if (!this.closed) {
+                        this.deps.onClose?.();
+                    }
+                }
+            });
+        });
+    }
+    stop() {
+        this.closed = true;
+        this.socket?.close();
+        this.socket = null;
+        this.rejectAllPending(new AgentClientError("agent stopped", "stopped"));
+    }
+    release() {
+        // Best-effort: ask the broker to release this agent's browsers.
+        void this.send("release", "", {}).catch(() => { });
+    }
+    async send(action, group, params, signal, target) {
+        if (signal?.aborted) {
+            throw new AgentClientError("aborted", "aborted");
+        }
+        await this.waitReady(signal);
+        const socket = this.socket;
+        if (!socket) {
+            throw new AgentClientError("not connected to the bridge", "disconnected");
+        }
+        const id = nextId();
+        const frame = {
+            v: PROTOCOL_VERSION,
+            type: "command",
+            id,
+            action,
+            group,
+            params,
+            target
+        };
+        return new Promise((resolve, reject) => {
+            const timer = this.opts.timeoutMs > 0
+                ? setTimeout(() => this.settleReject(id, new AgentClientError(`command '${action}' timed out`, "timeout")), this.opts.timeoutMs)
+                : null;
+            let detachAbort = null;
+            if (signal) {
+                const onAbort = () => this.settleReject(id, new AgentClientError("aborted", "aborted"));
+                signal.addEventListener("abort", onAbort, { once: true });
+                detachAbort = () => signal.removeEventListener("abort", onAbort);
+            }
+            this.pending.set(id, { resolve, reject, timer, detachAbort });
+            try {
+                socket.send(encodeFrame(frame));
+            }
+            catch (err) {
+                this.settleReject(id, new AgentClientError(`failed to send '${action}': ${err instanceof Error ? err.message : String(err)}`, "send_failed"));
+            }
+        });
+    }
+    waitReady(signal) {
+        if (this.ready) {
+            return Promise.resolve();
+        }
+        if (this.closed || !this.socket) {
+            return Promise.reject(new AgentClientError("not connected to the bridge", "disconnected"));
+        }
+        return new Promise((resolve, reject) => {
+            const onAbort = () => reject(new AgentClientError("aborted", "aborted"));
+            if (signal) {
+                signal.addEventListener("abort", onAbort, { once: true });
+            }
+            this.readyWaiters.push(() => {
+                if (signal) {
+                    signal.removeEventListener("abort", onAbort);
+                }
+                resolve();
+            });
+        });
+    }
+    handleResult(frame) {
+        const p = this.pending.get(frame.id);
+        if (!p) {
+            return;
+        }
+        this.clearPending(frame.id);
+        if (frame.ok) {
+            p.resolve(frame.data);
+        }
+        else {
+            p.reject(new AgentClientError(frame.error?.message ?? "bridge error", frame.error?.code));
+        }
+    }
+    clearPending(id) {
+        const p = this.pending.get(id);
+        if (!p) {
+            return;
+        }
+        if (p.timer) {
+            clearTimeout(p.timer);
+        }
+        p.detachAbort?.();
+        this.pending.delete(id);
+    }
+    settleReject(id, err) {
+        const p = this.pending.get(id);
+        if (!p) {
+            return;
+        }
+        this.clearPending(id);
+        p.reject(err);
+    }
+    rejectAllPending(err) {
+        for (const [id, p] of this.pending) {
+            if (p.timer) {
+                clearTimeout(p.timer);
+            }
+            p.detachAbort?.();
+            this.pending.delete(id);
+            p.reject(err);
+        }
+    }
+}
+//# sourceMappingURL=agent-client.js.map

package/dist/agent-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-client.js","sourceRoot":"","sources":["../src/agent-client.ts"],"names":[],"mappings":"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"}

package/dist/broker.d.ts

@@ -0,0 +1,70 @@
+import type { Logger } from "./logging.js";
+import { type BrowserAction } from "./protocol.js";
+import type { BridgeTransport } from "./transport.js";
+/** Thrown when a command can't be routed or the executor reports failure. */
+export declare class BrokerError extends Error {
+    readonly code?: string;
+    constructor(message: string, code?: string);
+}
+/** What an agent (local or remote) uses to drive browsers through the broker. */
+export interface AgentEndpoint {
+    send(action: BrowserAction, group: string, params: Record<string, unknown>, signal?: AbortSignal, target?: string): Promise<unknown>;
+    /** Release this agent's browsers (detach the debugger) without closing tabs. */
+    release(): void;
+}
+export interface BrokerOptions {
+    host: string;
+    port: number;
+    token: string;
+    /** Executor preference forwarded to extensions in `ready`. */
+    executor?: "auto" | "cdp" | "content";
+    /** Per-command timeout in ms; `<= 0` disables. */
+    timeoutMs: number;
+}
+export interface BrokerDeps {
+    logger: Logger;
+    transport: BridgeTransport;
+}
+/**
+ * Hosts the WebSocket server and routes commands between **agents** (producers:
+ * the plugin, the MCP server, guest adapters) and **executors** (the browser
+ * extensions), keyed by named-group ownership. Generalizes the old single-client
+ * bridge. Runtime-agnostic via the injected transport.
+ */
+export declare class Broker {
+    private readonly opts;
+    private readonly deps;
+    private readonly executors;
+    private readonly executorById;
+    private readonly agents;
+    private readonly groupOwner;
+    private readonly pending;
+    private primaryExecutorId;
+    private agentSeq;
+    private execSeq;
+    private started;
+    constructor(opts: BrokerOptions, deps: BrokerDeps);
+    get executorCount(): number;
+    start(): Promise<void>;
+    stop(): void;
+    /** An in-process agent (the host adapter's own tools), bypassing a socket. */
+    createLocalAgent(): AgentEndpoint;
+    private onMessage;
+    private handleHello;
+    private rebuildFromExecutor;
+    private onClose;
+    private route;
+    private resolveExecutor;
+    private pickExecutor;
+    private sendToExecutor;
+    private handleResult;
+    private handleAgentCommand;
+    private routeEvent;
+    private listTargets;
+    private aggregateTabs;
+    private releaseForAgent;
+    private safeSend;
+    private clearPending;
+    private settleReject;
+    private rejectAllPending;
+}