@vymalo/opencode-browser 0.11.0 → 0.14.0

package/dist/broker.js

@@ -1,610 +1,625 @@
 import { cancelFrame, decodeFrame, encodeFrame, errorFrame, nextId, PROTOCOL_VERSION, rejectedFrame, resultFrame, tokenFingerprint } from "./protocol.js";
 /** Thrown when a command can't be routed or the executor reports failure. */
 export class BrokerError extends Error {
-    code;
-    constructor(message, code) {
-        super(message);
-        this.name = "BrokerError";
-        this.code = code;
-    }
+	code;
+	constructor(message, code) {
+		super(message);
+		this.name = "BrokerError";
+		this.code = code;
+	}
 }
 /**
- * Hard ceiling for any per-command timeout, so a tool requesting a long
- * human-paced deadline can't pin a command open indefinitely. 10 minutes.
- */
-export const DEFAULT_MAX_COMMAND_MS = 600_000;
+* Hard ceiling for any per-command timeout, so a tool requesting a long
+* human-paced deadline can't pin a command open indefinitely. 10 minutes.
+*/
+export const DEFAULT_MAX_COMMAND_MS = 6e5;
 /** Actions that aren't group-scoped — routed to the primary/target executor. */
 const GLOBAL_ACTIONS = new Set(["cookies"]);
 /**
- * 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.
- */
+* 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 class Broker {
-    opts;
-    deps;
-    executors = new Map();
-    executorById = new Map();
-    agents = new Map();
-    groupOwner = new Map();
-    pending = new Map();
-    primaryExecutorId = null;
-    agentSeq = 0;
-    execSeq = 0;
-    started = false;
-    constructor(opts, deps) {
-        this.opts = opts;
-        this.deps = deps;
-    }
-    get executorCount() {
-        return this.executorById.size;
-    }
-    async start() {
-        if (this.started) {
-            return;
-        }
-        await this.deps.transport.listen({ host: this.opts.host, port: this.opts.port }, {
-            onOpen: () => { },
-            onMessage: (conn, data) => this.onMessage(conn, data),
-            onClose: (conn) => this.onClose(conn)
-        });
-        this.started = true;
-        this.deps.logger.info("browser_broker_listening", {
-            host: this.opts.host,
-            port: this.opts.port
-        });
-    }
-    stop() {
-        this.rejectAllPending(new BrokerError("broker stopped"));
-        this.executors.clear();
-        this.executorById.clear();
-        this.agents.clear();
-        this.groupOwner.clear();
-        this.primaryExecutorId = null;
-        this.started = false;
-        this.deps.transport.stop();
-    }
-    /** An in-process agent (the host adapter's own tools), bypassing a socket. */
-    createLocalAgent() {
-        const id = `local:${++this.agentSeq}`;
-        return {
-            send: (action, group, params, signal, target, timeoutMs) => this.route(id, { action, group, params, target, timeoutMs }, signal),
-            release: () => this.releaseForAgent(id)
-        };
-    }
-    // ─── connection handling ───────────────────────────────────────────────────
-    onMessage(conn, raw) {
-        const frame = decodeFrame(raw);
-        if (!frame) {
-            return;
-        }
-        if (frame.type === "hello") {
-            this.handleHello(conn, frame);
-            return;
-        }
-        const executor = this.executors.get(conn);
-        if (executor) {
-            if (frame.type === "result") {
-                this.handleResult(frame);
-            }
-            else if (frame.type === "event") {
-                this.routeEvent(frame);
-            }
-            else if (frame.type === "ping") {
-                this.safeSend(conn, { v: PROTOCOL_VERSION, type: "pong" });
-            }
-            return;
-        }
-        const agent = this.agents.get(conn);
-        if (agent) {
-            if (frame.type === "command") {
-                void this.handleAgentCommand(agent, conn, frame);
-            }
-            else if (frame.type === "ping") {
-                this.safeSend(conn, { v: PROTOCOL_VERSION, type: "pong" });
-            }
-            return;
-        }
-        this.deps.logger.warn("browser_frame_unauthenticated", { type: frame.type });
-    }
-    handleHello(conn, frame) {
-        const role = frame.role ?? "extension";
-        this.deps.logger.trace("browser_handshake_hello", {
-            role,
-            client: frame.client,
-            label: frame.label,
-            browser: frame.browser
-        });
-        if (frame.token !== this.opts.token) {
-            // The shared token may have rotated under this long-lived host (it resolved
-            // its token once at boot and otherwise never re-reads bridge.json). Re-read
-            // it; if the file now carries a different value, adopt it — so a rotation
-            // reaches a running host without a restart — then re-check the handshake.
-            this.adoptRotatedToken();
-            if (frame.token !== this.opts.token) {
-                // Fingerprints (never the raw tokens) make the mismatch diagnosable from
-                // the log alone — `expected` vs `got` of the same length but different
-                // value means a rotated/stale token, not a paste typo. role/client say
-                // which peer it was.
-                this.deps.logger.warn("browser_handshake_rejected", {
-                    reason: "bad_token",
-                    role: frame.role ?? "extension",
-                    client: frame.client,
-                    expected: tokenFingerprint(this.opts.token),
-                    got: tokenFingerprint(frame.token)
-                });
-                // Tell the dialer *why* before dropping it, so it can show an actionable
-                // error and stop hammering instead of retrying a token that can't work.
-                this.safeSend(conn, rejectedFrame("bad_token"));
-                conn.close();
-                return;
-            }
-            this.deps.logger.info("browser_bridge_token_reloaded", {
-                fingerprint: tokenFingerprint(this.opts.token)
-            });
-        }
-        if (role === "agent") {
-            const id = `agent:${++this.agentSeq}`;
-            this.agents.set(conn, { conn, id });
-            this.deps.logger.trace("browser_agent_accepted", { id, client: frame.client });
-            this.deps.logger.info("browser_agent_connected", { id, client: frame.client });
-            this.safeSend(conn, {
-                v: PROTOCOL_VERSION,
-                type: "ready",
-                server: "opencode-browser",
-                protocol: PROTOCOL_VERSION,
-                role: "agent",
-                clientId: id
-            });
-            return;
-        }
-        const id = frame.id || `exec:${++this.execSeq}`;
-        // Replace any stale connection carrying the same id (extension reconnect).
-        const prior = this.executorById.get(id);
-        if (prior && prior.conn !== conn) {
-            this.deps.logger.trace("browser_executor_replace_stale", { id });
-            this.executors.delete(prior.conn);
-            prior.conn.close();
-        }
-        const info = {
-            conn,
-            id,
-            label: frame.label || id,
-            browser: frame.browser || "unknown"
-        };
-        this.executors.set(conn, info);
-        this.executorById.set(id, info);
-        if (!this.primaryExecutorId || !this.executorById.has(this.primaryExecutorId)) {
-            this.primaryExecutorId = id;
-            this.deps.logger.trace("browser_primary_executor_set", { id });
-        }
-        this.deps.logger.info("browser_executor_connected", {
-            id,
-            label: info.label,
-            browser: info.browser
-        });
-        this.safeSend(conn, {
-            v: PROTOCOL_VERSION,
-            type: "ready",
-            server: "opencode-browser",
-            protocol: PROTOCOL_VERSION,
-            role: "extension",
-            clientId: id,
-            executor: this.opts.executor
-        });
-        // Rebuild group ownership from the executor's existing tabs (recovers after a
-        // broker re-election; groups come back orphaned and are adopted on first use).
-        void this.rebuildFromExecutor(info);
-    }
-    /**
-     * Re-read the shared token (via the injected `reloadToken`) and adopt it if the
-     * source of truth now holds a different, non-empty value. Lets a rotation in
-     * `bridge.json` reach this running host. No-op without a `reloadToken` dep, or
-     * when the file is unchanged/unavailable — so a genuinely wrong token still
-     * gets rejected. Reads only on a mismatch, so it's not on the hot path.
-     */
-    adoptRotatedToken() {
-        const latest = this.deps.reloadToken?.();
-        if (latest && latest.length > 0 && latest !== this.opts.token) {
-            this.opts.token = latest;
-        }
-    }
-    async rebuildFromExecutor(executor) {
-        try {
-            const data = (await this.sendToExecutor(executor, "broker", {
-                action: "tabs",
-                group: "",
-                params: {}
-            }));
-            for (const g of data.groups ?? []) {
-                if (g.name && !this.groupOwner.has(g.name)) {
-                    this.groupOwner.set(g.name, { executorId: executor.id, agentId: null });
-                    this.deps.logger.trace("browser_group_orphan_rebuilt", {
-                        group: g.name,
-                        executorId: executor.id
-                    });
-                }
-            }
-        }
-        catch {
-            /* best-effort */
-        }
-    }
-    onClose(conn) {
-        const executor = this.executors.get(conn);
-        if (executor) {
-            this.executors.delete(conn);
-            // Only forget the id mapping if it still points at this connection.
-            if (this.executorById.get(executor.id)?.conn === conn) {
-                this.executorById.delete(executor.id);
-                for (const [group, owner] of this.groupOwner) {
-                    if (owner.executorId === executor.id) {
-                        this.deps.logger.trace("browser_group_dropped_executor_gone", {
-                            group,
-                            executorId: executor.id
-                        });
-                        this.groupOwner.delete(group);
-                    }
-                }
-                for (const [reqId, p] of this.pending) {
-                    if (p.executorId === executor.id) {
-                        this.settleReject(reqId, new BrokerError("the browser disconnected", "executor_gone"));
-                    }
-                }
-            }
-            if (this.primaryExecutorId === executor.id) {
-                this.primaryExecutorId = this.executorById.keys().next().value ?? null;
-            }
-            this.deps.logger.info("browser_executor_disconnected", { id: executor.id });
-            return;
-        }
-        const agent = this.agents.get(conn);
-        if (agent) {
-            this.agents.delete(conn);
-            // Orphan this agent's groups (adoptable by the next user) AND send a
-            // release frame to the executors it owned, so a guest agent dropping
-            // (MCP server / guest OpenCode exit) detaches the CDP debugger/banner
-            // instead of leaving it attached until a later manual release.
-            this.releaseForAgent(agent.id);
-            for (const [reqId, p] of this.pending) {
-                if (p.agentId === agent.id) {
-                    // The executor may still be running this command — cancel it so any
-                    // open UI (e.g. a feedback overlay) is torn down, not just orphaned.
-                    this.abandon(reqId, new BrokerError("agent disconnected", "agent_gone"));
-                }
-            }
-            this.deps.logger.info("browser_agent_disconnected", { id: agent.id });
-        }
-    }
-    // ─── routing ───────────────────────────────────────────────────────────────
-    route(agentId, cmd, signal) {
-        if (cmd.action === "targets") {
-            return Promise.resolve(this.listTargets());
-        }
-        if (cmd.action === "release") {
-            this.releaseForAgent(agentId);
-            return Promise.resolve({ ok: true });
-        }
-        if (cmd.action === "tabs" && !cmd.group) {
-            return this.aggregateTabs();
-        }
-        let executor;
-        try {
-            executor = GLOBAL_ACTIONS.has(cmd.action)
-                ? this.pickExecutor(cmd.target)
-                : this.resolveExecutor(agentId, cmd);
-        }
-        catch (err) {
-            return Promise.reject(err);
-        }
-        return this.sendToExecutor(executor, agentId, cmd, signal);
-    }
-    resolveExecutor(agentId, cmd) {
-        const owner = this.groupOwner.get(cmd.group);
-        if (owner) {
-            if (owner.agentId && owner.agentId !== agentId) {
-                this.deps.logger.trace("browser_group_denied", {
-                    group: cmd.group,
-                    agentId,
-                    ownerAgentId: owner.agentId
-                });
-                throw new BrokerError(`group "${cmd.group}" is owned by another client`, "group_owned");
-            }
-            if (owner.agentId === null) {
-                this.deps.logger.trace("browser_group_adopted", { group: cmd.group, agentId });
-            }
-            owner.agentId = agentId; // claim (incl. adopting an orphan)
-            const exec = this.executorById.get(owner.executorId);
-            if (!exec) {
-                throw new BrokerError(`the browser for group "${cmd.group}" is disconnected`, "executor_gone");
-            }
-            return exec;
-        }
-        if (cmd.action !== "open") {
-            throw new BrokerError(`group "${cmd.group}" has no open tabs — call browser_open first`, "no_group");
-        }
-        const exec = this.pickExecutor(cmd.target);
-        this.groupOwner.set(cmd.group, { executorId: exec.id, agentId });
-        this.deps.logger.trace("browser_group_assigned", {
-            group: cmd.group,
-            agentId,
-            executorId: exec.id
-        });
-        return exec;
-    }
-    pickExecutor(target) {
-        if (this.executorById.size === 0) {
-            throw new BrokerError("no browser extension is connected to the bridge — open the extension and confirm it shows 'connected'", "not_connected");
-        }
-        if (target) {
-            const byId = this.executorById.get(target);
-            if (byId) {
-                return byId;
-            }
-            const byLabel = [...this.executorById.values()].filter((e) => e.label === target);
-            if (byLabel.length === 1) {
-                return byLabel[0];
-            }
-            if (byLabel.length > 1) {
-                throw new BrokerError(`target "${target}" is ambiguous — use the browser id`, "ambiguous_target");
-            }
-            throw new BrokerError(`no connected browser matches target "${target}"`, "unknown_target");
-        }
-        const primary = this.primaryExecutorId
-            ? this.executorById.get(this.primaryExecutorId)
-            : undefined;
-        if (primary) {
-            return primary;
-        }
-        for (const exec of this.executorById.values()) {
-            return exec;
-        }
-        throw new BrokerError("no browser extension is connected", "not_connected");
-    }
-    /** Effective per-command timeout: the override (or global), clamped to the ceiling. */
-    timeoutFor(override) {
-        const requested = override !== undefined ? override : this.opts.timeoutMs;
-        if (requested <= 0) {
-            return 0;
-        }
-        const ceiling = this.opts.maxCommandMs ?? DEFAULT_MAX_COMMAND_MS;
-        return Math.min(requested, ceiling);
-    }
-    sendToExecutor(executor, agentId, cmd, signal) {
-        if (signal?.aborted) {
-            return Promise.reject(new BrokerError("aborted", "aborted"));
-        }
-        const reqId = nextId();
-        const frame = {
-            v: PROTOCOL_VERSION,
-            type: "command",
-            id: reqId,
-            action: cmd.action,
-            group: cmd.group,
-            params: cmd.params
-        };
-        const timeoutMs = this.timeoutFor(cmd.timeoutMs);
-        this.deps.logger.trace("browser_command_dispatched", {
-            id: reqId,
-            action: cmd.action,
-            group: cmd.group,
-            executorId: executor.id,
-            agentId,
-            timeoutMs
-        });
-        return new Promise((resolve, reject) => {
-            const timer = timeoutMs > 0
-                ? setTimeout(() => {
-                    this.deps.logger.trace("browser_command_timeout_fired", {
-                        id: reqId,
-                        action: cmd.action,
-                        timeoutMs
-                    });
-                    this.abandon(reqId, new BrokerError(`command '${cmd.action}' timed out after ${timeoutMs}ms`, "timeout"));
-                }, timeoutMs)
-                : null;
-            let detachAbort = null;
-            if (signal) {
-                const onAbort = () => this.abandon(reqId, new BrokerError("aborted", "aborted"));
-                signal.addEventListener("abort", onAbort, { once: true });
-                detachAbort = () => signal.removeEventListener("abort", onAbort);
-            }
-            this.pending.set(reqId, {
-                resolve,
-                reject,
-                timer,
-                detachAbort,
-                agentId,
-                executorId: executor.id
-            });
-            try {
-                executor.conn.send(encodeFrame(frame));
-            }
-            catch (err) {
-                this.settleReject(reqId, new BrokerError(`failed to deliver '${cmd.action}': ${err instanceof Error ? err.message : String(err)}`, "send_failed"));
-            }
-        });
-    }
-    handleResult(frame) {
-        const p = this.pending.get(frame.id);
-        if (!p) {
-            this.deps.logger.trace("browser_result_unmatched", { id: frame.id });
-            return;
-        }
-        this.deps.logger.trace("browser_command_result_correlated", {
-            id: frame.id,
-            ok: frame.ok,
-            executorId: p.executorId,
-            agentId: p.agentId
-        });
-        this.clearPending(frame.id);
-        if (frame.ok) {
-            p.resolve(frame.data);
-        }
-        else {
-            p.reject(new BrokerError(frame.error?.message ?? "executor error", frame.error?.code));
-        }
-    }
-    async handleAgentCommand(agent, conn, frame) {
-        this.deps.logger.trace("browser_agent_command_received", {
-            agentId: agent.id,
-            id: frame.id,
-            action: frame.action,
-            group: frame.group,
-            target: frame.target
-        });
-        try {
-            const data = await this.route(agent.id, {
-                action: frame.action,
-                group: frame.group,
-                params: frame.params,
-                target: frame.target,
-                timeoutMs: frame.timeoutMs
-            });
-            this.deps.logger.trace("browser_agent_command_result", {
-                agentId: agent.id,
-                id: frame.id,
-                ok: true
-            });
-            this.safeSend(conn, resultFrame(frame.id, data));
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            const code = err instanceof BrokerError ? err.code : undefined;
-            this.deps.logger.trace("browser_agent_command_result", {
-                agentId: agent.id,
-                id: frame.id,
-                ok: false,
-                code
-            });
-            this.safeSend(conn, errorFrame(frame.id, message, code));
-        }
-    }
-    routeEvent(frame) {
-        // Forward to the owning agent if known, else broadcast to all remote agents.
-        const owner = frame.group ? this.groupOwner.get(frame.group) : undefined;
-        this.deps.logger.trace("browser_event_routed", {
-            name: frame.name,
-            group: frame.group,
-            ownerAgentId: owner?.agentId ?? null
-        });
-        for (const agent of this.agents.values()) {
-            if (!owner || owner.agentId === null || owner.agentId === agent.id) {
-                this.safeSend(agent.conn, frame);
-            }
-        }
-    }
-    listTargets() {
-        return {
-            targets: [...this.executorById.values()].map((e) => ({
-                id: e.id,
-                label: e.label,
-                browser: e.browser,
-                groups: [...this.groupOwner.entries()]
-                    .filter(([, o]) => o.executorId === e.id)
-                    .map(([g]) => g)
-            }))
-        };
-    }
-    async aggregateTabs() {
-        const groups = [];
-        for (const executor of this.executorById.values()) {
-            try {
-                const data = (await this.sendToExecutor(executor, "broker", {
-                    action: "tabs",
-                    group: "",
-                    params: {}
-                }));
-                for (const g of data.groups ?? []) {
-                    groups.push({ ...g, executor: executor.id });
-                }
-            }
-            catch {
-                /* skip a browser that errored */
-            }
-        }
-        return { groups };
-    }
-    releaseForAgent(agentId) {
-        const execIds = new Set();
-        for (const [group, owner] of this.groupOwner) {
-            if (owner.agentId === agentId) {
-                execIds.add(owner.executorId);
-                owner.agentId = null;
-                this.deps.logger.trace("browser_group_orphaned", { group, agentId });
-            }
-        }
-        // Only release the executors this agent actually owned. An agent that holds
-        // no groups must release nothing — broadcasting to every executor would
-        // detach CDP control from other clients' browsers in a shared bridge.
-        for (const id of execIds) {
-            const exec = this.executorById.get(id);
-            if (exec) {
-                this.safeSend(exec.conn, { v: PROTOCOL_VERSION, type: "release" });
-            }
-        }
-    }
-    // ─── helpers ─────────────────────────────────────────────────────────────────
-    safeSend(conn, frame) {
-        try {
-            conn.send(encodeFrame(frame));
-        }
-        catch {
-            /* connection went away; close handler cleans up */
-        }
-    }
-    clearPending(reqId) {
-        const p = this.pending.get(reqId);
-        if (!p) {
-            return;
-        }
-        if (p.timer) {
-            clearTimeout(p.timer);
-        }
-        p.detachAbort?.();
-        this.pending.delete(reqId);
-    }
-    settleReject(reqId, err) {
-        const p = this.pending.get(reqId);
-        if (!p) {
-            return;
-        }
-        this.clearPending(reqId);
-        p.reject(err);
-    }
-    /**
-     * Give up on a command the executor may still be running (abort, timeout, or
-     * the requesting agent vanishing): tell the still-connected executor to tear
-     * down via a `cancel` frame, then reject the pending promise. For an executor
-     * that's already gone the cancel is skipped — there's nothing to tear down.
-     */
-    abandon(reqId, err) {
-        const p = this.pending.get(reqId);
-        if (!p) {
-            return;
-        }
-        const exec = this.executorById.get(p.executorId);
-        this.deps.logger.trace("browser_command_abandoned", {
-            id: reqId,
-            executorId: p.executorId,
-            cancelSent: Boolean(exec),
-            reason: err.message
-        });
-        if (exec) {
-            this.safeSend(exec.conn, cancelFrame(reqId));
-        }
-        this.settleReject(reqId, err);
-    }
-    rejectAllPending(err) {
-        for (const [reqId, p] of this.pending) {
-            if (p.timer) {
-                clearTimeout(p.timer);
-            }
-            p.detachAbort?.();
-            this.pending.delete(reqId);
-            p.reject(err);
-        }
-    }
+	opts;
+	deps;
+	executors = new Map();
+	executorById = new Map();
+	agents = new Map();
+	groupOwner = new Map();
+	pending = new Map();
+	primaryExecutorId = null;
+	agentSeq = 0;
+	execSeq = 0;
+	started = false;
+	constructor(opts, deps) {
+		this.opts = opts;
+		this.deps = deps;
+	}
+	get executorCount() {
+		return this.executorById.size;
+	}
+	async start() {
+		if (this.started) {
+			return;
+		}
+		await this.deps.transport.listen({
+			host: this.opts.host,
+			port: this.opts.port
+		}, {
+			onOpen: () => {},
+			onMessage: (conn, data) => this.onMessage(conn, data),
+			onClose: (conn) => this.onClose(conn)
+		});
+		this.started = true;
+		this.deps.logger.info("browser_broker_listening", {
+			host: this.opts.host,
+			port: this.opts.port
+		});
+	}
+	stop() {
+		this.rejectAllPending(new BrokerError("broker stopped"));
+		this.executors.clear();
+		this.executorById.clear();
+		this.agents.clear();
+		this.groupOwner.clear();
+		this.primaryExecutorId = null;
+		this.started = false;
+		this.deps.transport.stop();
+	}
+	/** An in-process agent (the host adapter's own tools), bypassing a socket. */
+	createLocalAgent() {
+		const id = `local:${++this.agentSeq}`;
+		return {
+			send: (action, group, params, signal, target, timeoutMs) => this.route(id, {
+				action,
+				group,
+				params,
+				target,
+				timeoutMs
+			}, signal),
+			release: () => this.releaseForAgent(id)
+		};
+	}
+	// ─── connection handling ───────────────────────────────────────────────────
+	onMessage(conn, raw) {
+		const frame = decodeFrame(raw);
+		if (!frame) {
+			return;
+		}
+		if (frame.type === "hello") {
+			this.handleHello(conn, frame);
+			return;
+		}
+		const executor = this.executors.get(conn);
+		if (executor) {
+			if (frame.type === "result") {
+				this.handleResult(frame);
+			} else if (frame.type === "event") {
+				this.routeEvent(frame);
+			} else if (frame.type === "ping") {
+				this.safeSend(conn, {
+					v: PROTOCOL_VERSION,
+					type: "pong"
+				});
+			}
+			return;
+		}
+		const agent = this.agents.get(conn);
+		if (agent) {
+			if (frame.type === "command") {
+				void this.handleAgentCommand(agent, conn, frame);
+			} else if (frame.type === "ping") {
+				this.safeSend(conn, {
+					v: PROTOCOL_VERSION,
+					type: "pong"
+				});
+			}
+			return;
+		}
+		this.deps.logger.warn("browser_frame_unauthenticated", { type: frame.type });
+	}
+	handleHello(conn, frame) {
+		const role = frame.role ?? "extension";
+		this.deps.logger.trace("browser_handshake_hello", {
+			role,
+			client: frame.client,
+			label: frame.label,
+			browser: frame.browser
+		});
+		if (frame.token !== this.opts.token) {
+			// The shared token may have rotated under this long-lived host (it resolved
+			// its token once at boot and otherwise never re-reads bridge.json). Re-read
+			// it; if the file now carries a different value, adopt it — so a rotation
+			// reaches a running host without a restart — then re-check the handshake.
+			this.adoptRotatedToken();
+			if (frame.token !== this.opts.token) {
+				// Fingerprints (never the raw tokens) make the mismatch diagnosable from
+				// the log alone — `expected` vs `got` of the same length but different
+				// value means a rotated/stale token, not a paste typo. role/client say
+				// which peer it was.
+				this.deps.logger.warn("browser_handshake_rejected", {
+					reason: "bad_token",
+					role: frame.role ?? "extension",
+					client: frame.client,
+					expected: tokenFingerprint(this.opts.token),
+					got: tokenFingerprint(frame.token)
+				});
+				// Tell the dialer *why* before dropping it, so it can show an actionable
+				// error and stop hammering instead of retrying a token that can't work.
+				this.safeSend(conn, rejectedFrame("bad_token"));
+				conn.close();
+				return;
+			}
+			this.deps.logger.info("browser_bridge_token_reloaded", { fingerprint: tokenFingerprint(this.opts.token) });
+		}
+		if (role === "agent") {
+			const id = `agent:${++this.agentSeq}`;
+			this.agents.set(conn, {
+				conn,
+				id
+			});
+			this.deps.logger.trace("browser_agent_accepted", {
+				id,
+				client: frame.client
+			});
+			this.deps.logger.info("browser_agent_connected", {
+				id,
+				client: frame.client
+			});
+			this.safeSend(conn, {
+				v: PROTOCOL_VERSION,
+				type: "ready",
+				server: "opencode-browser",
+				protocol: PROTOCOL_VERSION,
+				role: "agent",
+				clientId: id
+			});
+			return;
+		}
+		const id = frame.id || `exec:${++this.execSeq}`;
+		// Replace any stale connection carrying the same id (extension reconnect).
+		const prior = this.executorById.get(id);
+		if (prior && prior.conn !== conn) {
+			this.deps.logger.trace("browser_executor_replace_stale", { id });
+			this.executors.delete(prior.conn);
+			prior.conn.close();
+		}
+		const info = {
+			conn,
+			id,
+			label: frame.label || id,
+			browser: frame.browser || "unknown"
+		};
+		this.executors.set(conn, info);
+		this.executorById.set(id, info);
+		if (!this.primaryExecutorId || !this.executorById.has(this.primaryExecutorId)) {
+			this.primaryExecutorId = id;
+			this.deps.logger.trace("browser_primary_executor_set", { id });
+		}
+		this.deps.logger.info("browser_executor_connected", {
+			id,
+			label: info.label,
+			browser: info.browser
+		});
+		this.safeSend(conn, {
+			v: PROTOCOL_VERSION,
+			type: "ready",
+			server: "opencode-browser",
+			protocol: PROTOCOL_VERSION,
+			role: "extension",
+			clientId: id,
+			executor: this.opts.executor
+		});
+		// Rebuild group ownership from the executor's existing tabs (recovers after a
+		// broker re-election; groups come back orphaned and are adopted on first use).
+		void this.rebuildFromExecutor(info);
+	}
+	/**
+	* Re-read the shared token (via the injected `reloadToken`) and adopt it if the
+	* source of truth now holds a different, non-empty value. Lets a rotation in
+	* `bridge.json` reach this running host. No-op without a `reloadToken` dep, or
+	* when the file is unchanged/unavailable — so a genuinely wrong token still
+	* gets rejected. Reads only on a mismatch, so it's not on the hot path.
+	*/
+	adoptRotatedToken() {
+		const latest = this.deps.reloadToken?.();
+		if (latest && latest.length > 0 && latest !== this.opts.token) {
+			this.opts.token = latest;
+		}
+	}
+	async rebuildFromExecutor(executor) {
+		try {
+			const data = await this.sendToExecutor(executor, "broker", {
+				action: "tabs",
+				group: "",
+				params: {}
+			});
+			for (const g of data.groups ?? []) {
+				if (g.name && !this.groupOwner.has(g.name)) {
+					this.groupOwner.set(g.name, {
+						executorId: executor.id,
+						agentId: null
+					});
+					this.deps.logger.trace("browser_group_orphan_rebuilt", {
+						group: g.name,
+						executorId: executor.id
+					});
+				}
+			}
+		} catch {}
+	}
+	onClose(conn) {
+		const executor = this.executors.get(conn);
+		if (executor) {
+			this.executors.delete(conn);
+			// Only forget the id mapping if it still points at this connection.
+			if (this.executorById.get(executor.id)?.conn === conn) {
+				this.executorById.delete(executor.id);
+				for (const [group, owner] of this.groupOwner) {
+					if (owner.executorId === executor.id) {
+						this.deps.logger.trace("browser_group_dropped_executor_gone", {
+							group,
+							executorId: executor.id
+						});
+						this.groupOwner.delete(group);
+					}
+				}
+				for (const [reqId, p] of this.pending) {
+					if (p.executorId === executor.id) {
+						this.settleReject(reqId, new BrokerError("the browser disconnected", "executor_gone"));
+					}
+				}
+			}
+			if (this.primaryExecutorId === executor.id) {
+				this.primaryExecutorId = this.executorById.keys().next().value ?? null;
+			}
+			this.deps.logger.info("browser_executor_disconnected", { id: executor.id });
+			return;
+		}
+		const agent = this.agents.get(conn);
+		if (agent) {
+			this.agents.delete(conn);
+			// Orphan this agent's groups (adoptable by the next user) AND send a
+			// release frame to the executors it owned, so a guest agent dropping
+			// (MCP server / guest OpenCode exit) detaches the CDP debugger/banner
+			// instead of leaving it attached until a later manual release.
+			this.releaseForAgent(agent.id);
+			for (const [reqId, p] of this.pending) {
+				if (p.agentId === agent.id) {
+					// The executor may still be running this command — cancel it so any
+					// open UI (e.g. a feedback overlay) is torn down, not just orphaned.
+					this.abandon(reqId, new BrokerError("agent disconnected", "agent_gone"));
+				}
+			}
+			this.deps.logger.info("browser_agent_disconnected", { id: agent.id });
+		}
+	}
+	// ─── routing ───────────────────────────────────────────────────────────────
+	route(agentId, cmd, signal) {
+		if (cmd.action === "targets") {
+			return Promise.resolve(this.listTargets());
+		}
+		if (cmd.action === "release") {
+			this.releaseForAgent(agentId);
+			return Promise.resolve({ ok: true });
+		}
+		if (cmd.action === "tabs" && !cmd.group) {
+			return this.aggregateTabs();
+		}
+		let executor;
+		try {
+			executor = GLOBAL_ACTIONS.has(cmd.action) ? this.pickExecutor(cmd.target) : this.resolveExecutor(agentId, cmd);
+		} catch (err) {
+			return Promise.reject(err);
+		}
+		return this.sendToExecutor(executor, agentId, cmd, signal);
+	}
+	resolveExecutor(agentId, cmd) {
+		const owner = this.groupOwner.get(cmd.group);
+		if (owner) {
+			if (owner.agentId && owner.agentId !== agentId) {
+				this.deps.logger.trace("browser_group_denied", {
+					group: cmd.group,
+					agentId,
+					ownerAgentId: owner.agentId
+				});
+				throw new BrokerError(`group "${cmd.group}" is owned by another client`, "group_owned");
+			}
+			if (owner.agentId === null) {
+				this.deps.logger.trace("browser_group_adopted", {
+					group: cmd.group,
+					agentId
+				});
+			}
+			owner.agentId = agentId;
+			const exec = this.executorById.get(owner.executorId);
+			if (!exec) {
+				throw new BrokerError(`the browser for group "${cmd.group}" is disconnected`, "executor_gone");
+			}
+			return exec;
+		}
+		if (cmd.action !== "open") {
+			throw new BrokerError(`group "${cmd.group}" has no open tabs — call browser_open first`, "no_group");
+		}
+		const exec = this.pickExecutor(cmd.target);
+		this.groupOwner.set(cmd.group, {
+			executorId: exec.id,
+			agentId
+		});
+		this.deps.logger.trace("browser_group_assigned", {
+			group: cmd.group,
+			agentId,
+			executorId: exec.id
+		});
+		return exec;
+	}
+	pickExecutor(target) {
+		if (this.executorById.size === 0) {
+			throw new BrokerError("no browser extension is connected to the bridge — open the extension and confirm it shows 'connected'", "not_connected");
+		}
+		if (target) {
+			const byId = this.executorById.get(target);
+			if (byId) {
+				return byId;
+			}
+			const byLabel = [...this.executorById.values()].filter((e) => e.label === target);
+			if (byLabel.length === 1) {
+				return byLabel[0];
+			}
+			if (byLabel.length > 1) {
+				throw new BrokerError(`target "${target}" is ambiguous — use the browser id`, "ambiguous_target");
+			}
+			throw new BrokerError(`no connected browser matches target "${target}"`, "unknown_target");
+		}
+		const primary = this.primaryExecutorId ? this.executorById.get(this.primaryExecutorId) : undefined;
+		if (primary) {
+			return primary;
+		}
+		for (const exec of this.executorById.values()) {
+			return exec;
+		}
+		throw new BrokerError("no browser extension is connected", "not_connected");
+	}
+	/** Effective per-command timeout: the override (or global), clamped to the ceiling. */
+	timeoutFor(override) {
+		const requested = override !== undefined ? override : this.opts.timeoutMs;
+		if (requested <= 0) {
+			return 0;
+		}
+		const ceiling = this.opts.maxCommandMs ?? DEFAULT_MAX_COMMAND_MS;
+		return Math.min(requested, ceiling);
+	}
+	sendToExecutor(executor, agentId, cmd, signal) {
+		if (signal?.aborted) {
+			return Promise.reject(new BrokerError("aborted", "aborted"));
+		}
+		const reqId = nextId();
+		const frame = {
+			v: PROTOCOL_VERSION,
+			type: "command",
+			id: reqId,
+			action: cmd.action,
+			group: cmd.group,
+			params: cmd.params
+		};
+		const timeoutMs = this.timeoutFor(cmd.timeoutMs);
+		this.deps.logger.trace("browser_command_dispatched", {
+			id: reqId,
+			action: cmd.action,
+			group: cmd.group,
+			executorId: executor.id,
+			agentId,
+			timeoutMs
+		});
+		return new Promise((resolve, reject) => {
+			const timer = timeoutMs > 0 ? setTimeout(() => {
+				this.deps.logger.trace("browser_command_timeout_fired", {
+					id: reqId,
+					action: cmd.action,
+					timeoutMs
+				});
+				this.abandon(reqId, new BrokerError(`command '${cmd.action}' timed out after ${timeoutMs}ms`, "timeout"));
+			}, timeoutMs) : null;
+			let detachAbort = null;
+			if (signal) {
+				const onAbort = () => this.abandon(reqId, new BrokerError("aborted", "aborted"));
+				signal.addEventListener("abort", onAbort, { once: true });
+				detachAbort = () => signal.removeEventListener("abort", onAbort);
+			}
+			this.pending.set(reqId, {
+				resolve,
+				reject,
+				timer,
+				detachAbort,
+				agentId,
+				executorId: executor.id
+			});
+			try {
+				executor.conn.send(encodeFrame(frame));
+			} catch (err) {
+				this.settleReject(reqId, new BrokerError(`failed to deliver '${cmd.action}': ${err instanceof Error ? err.message : String(err)}`, "send_failed"));
+			}
+		});
+	}
+	handleResult(frame) {
+		const p = this.pending.get(frame.id);
+		if (!p) {
+			this.deps.logger.trace("browser_result_unmatched", { id: frame.id });
+			return;
+		}
+		this.deps.logger.trace("browser_command_result_correlated", {
+			id: frame.id,
+			ok: frame.ok,
+			executorId: p.executorId,
+			agentId: p.agentId
+		});
+		this.clearPending(frame.id);
+		if (frame.ok) {
+			p.resolve(frame.data);
+		} else {
+			p.reject(new BrokerError(frame.error?.message ?? "executor error", frame.error?.code));
+		}
+	}
+	async handleAgentCommand(agent, conn, frame) {
+		this.deps.logger.trace("browser_agent_command_received", {
+			agentId: agent.id,
+			id: frame.id,
+			action: frame.action,
+			group: frame.group,
+			target: frame.target
+		});
+		try {
+			const data = await this.route(agent.id, {
+				action: frame.action,
+				group: frame.group,
+				params: frame.params,
+				target: frame.target,
+				timeoutMs: frame.timeoutMs
+			});
+			this.deps.logger.trace("browser_agent_command_result", {
+				agentId: agent.id,
+				id: frame.id,
+				ok: true
+			});
+			this.safeSend(conn, resultFrame(frame.id, data));
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			const code = err instanceof BrokerError ? err.code : undefined;
+			this.deps.logger.trace("browser_agent_command_result", {
+				agentId: agent.id,
+				id: frame.id,
+				ok: false,
+				code
+			});
+			this.safeSend(conn, errorFrame(frame.id, message, code));
+		}
+	}
+	routeEvent(frame) {
+		// Forward to the owning agent if known, else broadcast to all remote agents.
+		const owner = frame.group ? this.groupOwner.get(frame.group) : undefined;
+		this.deps.logger.trace("browser_event_routed", {
+			name: frame.name,
+			group: frame.group,
+			ownerAgentId: owner?.agentId ?? null
+		});
+		for (const agent of this.agents.values()) {
+			if (!owner || owner.agentId === null || owner.agentId === agent.id) {
+				this.safeSend(agent.conn, frame);
+			}
+		}
+	}
+	listTargets() {
+		return { targets: [...this.executorById.values()].map((e) => ({
+			id: e.id,
+			label: e.label,
+			browser: e.browser,
+			groups: [...this.groupOwner.entries()].filter(([, o]) => o.executorId === e.id).map(([g]) => g)
+		})) };
+	}
+	async aggregateTabs() {
+		const groups = [];
+		for (const executor of this.executorById.values()) {
+			try {
+				const data = await this.sendToExecutor(executor, "broker", {
+					action: "tabs",
+					group: "",
+					params: {}
+				});
+				for (const g of data.groups ?? []) {
+					groups.push({
+						...g,
+						executor: executor.id
+					});
+				}
+			} catch {}
+		}
+		return { groups };
+	}
+	releaseForAgent(agentId) {
+		const execIds = new Set();
+		for (const [group, owner] of this.groupOwner) {
+			if (owner.agentId === agentId) {
+				execIds.add(owner.executorId);
+				owner.agentId = null;
+				this.deps.logger.trace("browser_group_orphaned", {
+					group,
+					agentId
+				});
+			}
+		}
+		// Only release the executors this agent actually owned. An agent that holds
+		// no groups must release nothing — broadcasting to every executor would
+		// detach CDP control from other clients' browsers in a shared bridge.
+		for (const id of execIds) {
+			const exec = this.executorById.get(id);
+			if (exec) {
+				this.safeSend(exec.conn, {
+					v: PROTOCOL_VERSION,
+					type: "release"
+				});
+			}
+		}
+	}
+	// ─── helpers ─────────────────────────────────────────────────────────────────
+	safeSend(conn, frame) {
+		try {
+			conn.send(encodeFrame(frame));
+		} catch {}
+	}
+	clearPending(reqId) {
+		const p = this.pending.get(reqId);
+		if (!p) {
+			return;
+		}
+		if (p.timer) {
+			clearTimeout(p.timer);
+		}
+		p.detachAbort?.();
+		this.pending.delete(reqId);
+	}
+	settleReject(reqId, err) {
+		const p = this.pending.get(reqId);
+		if (!p) {
+			return;
+		}
+		this.clearPending(reqId);
+		p.reject(err);
+	}
+	/**
+	* Give up on a command the executor may still be running (abort, timeout, or
+	* the requesting agent vanishing): tell the still-connected executor to tear
+	* down via a `cancel` frame, then reject the pending promise. For an executor
+	* that's already gone the cancel is skipped — there's nothing to tear down.
+	*/
+	abandon(reqId, err) {
+		const p = this.pending.get(reqId);
+		if (!p) {
+			return;
+		}
+		const exec = this.executorById.get(p.executorId);
+		this.deps.logger.trace("browser_command_abandoned", {
+			id: reqId,
+			executorId: p.executorId,
+			cancelSent: Boolean(exec),
+			reason: err.message
+		});
+		if (exec) {
+			this.safeSend(exec.conn, cancelFrame(reqId));
+		}
+		this.settleReject(reqId, err);
+	}
+	rejectAllPending(err) {
+		for (const [reqId, p] of this.pending) {
+			if (p.timer) {
+				clearTimeout(p.timer);
+			}
+			p.detachAbort?.();
+			this.pending.delete(reqId);
+			p.reject(err);
+		}
+	}
 }
+
 //# sourceMappingURL=broker.js.map