Open-source AI browser agent for Chrome and Firefox (monorepo) ðŸ§
JavaScript ai-agentai-agentsai-toolsbrowser-aibrowser-automationbrowser-extensionchrome-aichrome-devtoolschrome-extensionchrome-extensionsfirefox-addonfirefox-addonsfirefox-extensionfirefox-extensionsgemmagemma4minimaxoffline-aioffline-llmqwen
/**
* Bridge server — the local endpoint the WebBrain extension connects OUT to.
*
* Direction matters: a Manifest V3 extension cannot listen on a socket, so
* `src/chrome/src/offscreen/cloud-bridge.js` dials out from an offscreen
* document and we host the listener. That also means every command below is
* initiated by us and answered by the extension.
*
* Wire protocol:
* us -> extension {type:'pairing_challenge', scheme, nonce} (on connect)
* extension -> us {type:'hello', client, protocolVersion, capabilities, status}
* extension -> us {type:'pairing_proof', scheme, proof} (either order)
* us -> extension {id, action, payload}
* extension -> us {id, ok:true, result}
* {id, ok:false, error, status?}
*
* A socket stays a candidate until it has sent both a valid hello and the
* pairing proof (see pairing.ts). Candidates never receive commands and never
* displace the connected extension, so a local process that merely claims to
* be WebBrain cannot take over the bridge or read task payloads.
*
* The extension spreads `payload` over the message it forwards to its own
* background worker, so payload keys become top-level fields there. Send the
* exact field names `cloud-runs.js` reads.
*/
import { randomUUID } from "node:crypto";
import { WebSocketServer, type WebSocket } from "ws";
import { config } from "./config.js";
import {
PAIRING_CLOSE_CODE,
PAIRING_SCHEME,
loadPairingKey,
newPairingNonce,
validatePairingKey,
verifyPairingProof,
} from "./pairing.js";
import { BOT_MEMORY_CAPABILITY, validateTaskMemory, taskMemoryPrivateValues, redactTaskMemory, redactMemoryRunResponse } from "./task-memory.js";
/** Actions already present in the extension's ALLOWED_BRIDGE_ACTIONS set. */
export type BridgeAction =
| "cloud_run"
| "cloud_status"
| "cloud_respond"
| "cloud_abort";
export interface CloudSnapshot {
runId: string;
status: "running" | "needs_user_input" | "aborting" | "completed" | "failed" | "aborted";
mode?: "ask" | "act";
tabId?: number;
task?: string;
structured?: boolean;
pendingInput?: {
promptKind?: string;
clarifyId?: string;
clarify_id?: string;
question?: string;
[key: string]: unknown;
} | null;
result?: unknown;
summary?: string;
content?: string;
finalUrl?: string;
error?: string;
createdAt?: string;
updatedAt?: string;
completedAt?: string | null;
updates?: unknown[];
[key: string]: unknown;
}
export const TERMINAL_STATUSES = new Set(["completed", "failed", "aborted"]);
/**
* Memory-run redaction scopes held at once. One bridge can live as long as the
* app hosting it, so this bounds concurrent scopes, not lifetime runs: an
* unfinished run keeps its scope until the extension reports it terminal, and
* finished scopes are recycled oldest-first when room is needed.
*/
export const MAX_MEMORY_RUN_SCOPES = 256;
interface MemoryRunState {
credentials: readonly string[];
/** The start was answered (or never sent): the run is in the extension's list or never will be. */
startSettled: boolean;
/** The extension reported a terminal status, so nothing new can reach this run. */
finished: boolean;
}
interface Pending {
resolve: (value: unknown) => void;
reject: (reason: Error) => void;
timer: NodeJS.Timeout;
protectedRequest?: boolean;
runId?: string;
memoryValues?: ReadonlySet<string>;
memoryStart?: boolean;
}
/** A socket that connected but has not yet proved it holds the pairing key. */
interface Candidate {
nonce: string;
hello: Record<string, unknown> | null;
paired: boolean;
timer: NodeJS.Timeout;
}
export interface BridgeOptions {
/** Pairing key supplied by a host process. Defaults to loadPairingKey(). */
pairingKey?: string;
/** How long a new socket may take to send hello and pair before it is closed. */
pairingTimeoutMs?: number;
}
export class BridgeError extends Error {
readonly status?: number;
readonly code?: "COMMAND_TIMEOUT" | "COMMAND_INTERRUPTED";
constructor(
message: string,
status?: number,
code?: "COMMAND_TIMEOUT" | "COMMAND_INTERRUPTED",
) {
super(message);
this.name = "BridgeError";
this.status = status;
this.code = code;
}
}
/** Log to stderr only — stdout is the MCP stdio transport and must stay clean. */
function log(...args: unknown[]): void {
console.error("[webbrain-mcp]", ...args);
}
function isAllowedBridgeOrigin(origin: string | string[] | undefined): boolean {
if (origin == null) return true;
if (Array.isArray(origin)) return false;
try {
const protocol = new URL(origin).protocol;
return protocol === "chrome-extension:" || protocol === "moz-extension:";
} catch {
return false;
}
}
export class WebBrainBridge {
private wss: WebSocketServer | null = null;
/** The paired extension. Only set once a socket has sent hello and paired. */
private socket: WebSocket | null = null;
private candidates = new Map<WebSocket, Candidate>();
private pending = new Map<number, Pending>();
private nextId = 1;
private extensionCapabilities: string[] = [];
private extensionProtocol: number | null = null;
private waiters: Array<() => void> = [];
private pairingKey = "";
private pairingSource = "";
private readonly pairingTimeoutMs: number;
private memoryPrivateValues = new Set<string>();
private memoryProtectedRunIds = new Set<string>();
private memoryRunValues = new Map<string, ReadonlySet<string>>();
/** Lifecycle of each scope above, in eviction order (oldest finished first). */
private memoryRuns = new Map<string, MemoryRunState>();
constructor(private readonly options: BridgeOptions = {}) {
this.pairingTimeoutMs = options.pairingTimeoutMs ?? 10_000;
}
/** Where the pairing key came from (a file path or variable name), for setup messages. */
pairingKeySource(): string {
return this.pairingSource;
}
async start(): Promise<void> {
if (this.wss) return;
// Resolve the key before binding: without it every socket would be refused.
if (this.options.pairingKey !== undefined) {
this.pairingKey = validatePairingKey(this.options.pairingKey, "The pairing key");
this.pairingSource = "host configuration";
} else {
const loaded = loadPairingKey();
this.pairingKey = loaded.key;
this.pairingSource = loaded.source;
}
await new Promise<void>((resolve, reject) => {
// Bind to loopback explicitly. Never expose this listener to the network:
// anything that can reach it can drive the user's logged-in browser.
const wss = new WebSocketServer(
{ host: "127.0.0.1", port: config.bridgePort },
() => resolve(),
);
wss.on("error", reject);
this.wss = wss;
});
this.wss!.on("connection", (socket, request) => {
const url = request.url || "";
const origin = request.headers.origin;
// Browser WebSocket clients always send Origin. Only extension pages may
// reach this trusted-local command channel; native clients send none.
if (!isAllowedBridgeOrigin(origin)) {
log(`rejected WebSocket origin: ${String(origin)}`);
socket.close(1008, "Untrusted Origin");
return;
}
if (!url.startsWith(config.bridgePath)) {
log(`rejected connection on unexpected path: ${url}`);
socket.close(1008, "Unexpected path");
return;
}
// The new socket is only a candidate. The connected extension keeps
// working until the candidate pairs, and is never touched if it fails.
const candidate: Candidate = {
nonce: newPairingNonce(),
hello: null,
paired: false,
timer: setTimeout(() => {
this.rejectCandidate(
socket,
candidate.hello
? "Pairing required: update WebBrain and paste the pairing key under Settings → Bridge"
: "Handshake timeout",
);
}, this.pairingTimeoutMs),
};
this.candidates.set(socket, candidate);
socket.on("message", (raw) => this.handleMessage(socket, raw.toString()));
socket.on("close", () => {
const unpaired = this.candidates.get(socket);
if (unpaired) {
clearTimeout(unpaired.timer);
this.candidates.delete(socket);
return;
}
if (this.socket !== socket) return;
this.socket = null;
this.extensionCapabilities = [];
this.extensionProtocol = null;
log("extension disconnected");
this.failAllPending(
new BridgeError(
"WebBrain extension disconnected mid-command.",
undefined,
"COMMAND_INTERRUPTED",
),
);
});
socket.on("error", (error) => {
log("socket error:", redactTaskMemory(error instanceof Error ? error.message : String(error), this.memoryPrivateValues));
});
try {
socket.send(JSON.stringify({ type: "pairing_challenge", scheme: PAIRING_SCHEME, nonce: candidate.nonce }));
} catch {
/* the close handler drops the candidate */
}
});
log(`listening on ws://127.0.0.1:${config.bridgePort}${config.bridgePath}`);
log(`extensions must pair with the key from ${this.pairingKeyHint()}`);
}
/** Where the user finds the key. Never the key itself. */
private pairingKeyHint(): string {
const source = this.pairingSource || "~/.webbrain/bridge-key";
return this.options.pairingKey === undefined ? `${source} (print it with: webbrain-mcp pairing-key)` : source;
}
private rejectCandidate(socket: WebSocket, reason: string, code = PAIRING_CLOSE_CODE): void {
const candidate = this.candidates.get(socket);
if (candidate) clearTimeout(candidate.timer);
this.candidates.delete(socket);
log(`rejected unpaired connection: ${reason}`);
try {
socket.close(code, reason);
} catch {
/* already gone */
}
}
private handleCandidateMessage(socket: WebSocket, candidate: Candidate, msg: Record<string, unknown>): void {
if (msg.type === "hello") {
if (msg.client !== "webbrain-extension") {
this.rejectCandidate(socket, "Unknown client", 1008);
return;
}
candidate.hello = msg;
} else if (msg.type === "pairing_proof" || msg.type === "auth") {
if (msg.scheme !== PAIRING_SCHEME || !verifyPairingProof(this.pairingKey, candidate.nonce, msg.proof)) {
this.rejectCandidate(socket, "Pairing key mismatch");
return;
}
candidate.paired = true;
} else {
// Candidates are never sent commands, so anything else is noise.
return;
}
if (candidate.paired && candidate.hello) this.adopt(socket, candidate);
}
/** Promote a paired candidate to the extension. Latest paired connection wins. */
private adopt(socket: WebSocket, candidate: Candidate): void {
clearTimeout(candidate.timer);
this.candidates.delete(socket);
const hello = candidate.hello!;
// The extension reconnects with backoff after a browser restart or an
// offscreen-document teardown, and the stale socket is never reused.
const previous = this.socket;
if (previous) {
this.socket = null;
this.failAllPending(
new BridgeError(
"WebBrain extension connection was superseded mid-command.",
undefined,
"COMMAND_INTERRUPTED",
),
);
try {
previous.close(1000, "Superseded by a newer extension connection");
} catch {
/* already gone */
}
}
this.socket = socket;
this.extensionProtocol = typeof hello.protocolVersion === "number" ? hello.protocolVersion : null;
this.extensionCapabilities = Array.isArray(hello.capabilities)
? (hello.capabilities as string[])
: [];
log(
`extension paired on ${config.bridgePath} — protocol v${this.extensionProtocol}, capabilities: ` +
(this.extensionCapabilities.join(", ") || "none"),
);
const waiters = this.waiters;
this.waiters = [];
for (const wake of waiters) wake();
}
private handleMessage(socket: WebSocket, data: string): void {
const candidate = this.candidates.get(socket);
if (!candidate && this.socket !== socket) return;
let msg: Record<string, unknown>;
try {
msg = JSON.parse(data);
} catch {
log("dropped non-JSON frame from extension");
return;
}
if (!msg || typeof msg !== "object") return;
if (candidate) {
this.handleCandidateMessage(socket, candidate, msg);
return;
}
const id = typeof msg.id === "number" ? msg.id : null;
if (id == null) return;
const entry = this.pending.get(id);
if (!entry) return;
this.pending.delete(id);
clearTimeout(entry.timer);
if (entry.memoryStart && entry.runId) {
// Answered either way, so the extension now lists this run or never will.
const state = this.memoryRuns.get(entry.runId);
if (state) state.startSettled = true;
}
if (msg.ok === false) {
const status = typeof msg.status === "number" ? msg.status : undefined;
entry.reject(new BridgeError(String(redactMemoryRunResponse(msg.error || "Unknown bridge error", this.memoryPrivateValues,
this.memoryProtectedRunIds, entry.protectedRequest, { runValues: this.memoryRunValues, requestRunId: entry.runId, requestValues: entry.memoryValues })), status));
return;
}
if (entry.memoryStart && msg.result && typeof msg.result === "object") {
const result = msg.result as Record<string, unknown>;
const runId = result.runId || result.run_id;
if (typeof runId === "string") {
this.memoryProtectedRunIds.add(runId);
if (entry.memoryValues) this.memoryRunValues.set(runId, new Set([...(this.memoryRunValues.get(runId) || []), ...entry.memoryValues]));
if (!this.memoryRuns.has(runId)) {
const credentials = (entry.runId && this.memoryRuns.get(entry.runId)?.credentials) || [];
this.memoryRuns.set(runId, { credentials, startSettled: true, finished: false });
}
}
}
this.noteMemoryRunStatuses(msg.result, entry.runId);
entry.resolve(redactMemoryRunResponse(msg.result, this.memoryPrivateValues, this.memoryProtectedRunIds,
entry.protectedRequest, { runValues: this.memoryRunValues, requestRunId: entry.runId, requestValues: entry.memoryValues }));
}
private failAllPending(error: Error): void {
for (const [, entry] of this.pending) {
clearTimeout(entry.timer);
entry.reject(error);
}
this.pending.clear();
}
/** Track which protected runs the extension reports as finished (or live again). */
private noteMemoryRunStatuses(result: unknown, requestRunId?: string): void {
if (!this.memoryRuns.size || !result || typeof result !== "object") return;
const listed = (result as { runs?: unknown }).runs;
for (const run of Array.isArray(listed) ? listed : [result]) {
if (!run || typeof run !== "object") continue;
const snapshot = run as Record<string, unknown>;
const runId = String(snapshot.runId || snapshot.run_id || (Array.isArray(listed) ? "" : requestRunId || ""));
const state = this.memoryRuns.get(runId);
if (!state || typeof snapshot.status !== "string") continue;
state.startSettled = true;
const finished = TERMINAL_STATUSES.has(snapshot.status);
if (finished && !state.finished) {
// Re-append so the most recently finished runs keep their scope longest.
this.memoryRuns.delete(runId);
this.memoryRuns.set(runId, state);
}
state.finished = finished;
}
}
/** Drop the oldest finished scopes until one more fits; false if every slot is unfinished. */
private evictFinishedMemoryRuns(): boolean {
let evicted = false;
for (const [runId, state] of this.memoryRuns) {
if (this.memoryRuns.size < MAX_MEMORY_RUN_SCOPES) break;
if (!state.finished) continue;
this.memoryRuns.delete(runId);
this.memoryProtectedRunIds.delete(runId);
this.memoryRunValues.delete(runId);
evicted = true;
}
if (evicted) {
// Runs can share a credential, so keep every one a retained run still uses.
this.memoryPrivateValues = new Set([...this.memoryRuns.values()].flatMap((state) => state.credentials));
}
return this.memoryRuns.size < MAX_MEMORY_RUN_SCOPES;
}
/**
* A caller that stopped polling leaves a finished run looking unfinished.
* The extension's run list is authoritative (it hydrates first), so re-read
* it: terminal runs are noted on the way in, and a settled start missing
* from the list can never be returned again.
*/
private async refreshMemoryRunStates(timeoutMs: number): Promise<void> {
try {
const listed = await this.request<{ runs?: CloudSnapshot[] }>("cloud_status", {}, timeoutMs);
if (!Array.isArray(listed?.runs)) return;
const present = new Set(listed.runs.map((run) => String(run.runId || run.run_id || "")));
for (const [runId, state] of this.memoryRuns) {
if (state.startSettled && !present.has(runId)) state.finished = true;
}
} catch {
/* the caller reports capacity */
}
}
isConnected(): boolean {
return this.socket !== null && this.socket.readyState === 1;
}
capabilities(): string[] {
return [...this.extensionCapabilities];
}
/** Resolve once the extension has connected and completed its handshake. */
waitForExtension(timeoutMs: number): Promise<boolean> {
if (this.isConnected()) return Promise.resolve(true);
return new Promise((resolve) => {
const timer = setTimeout(() => {
this.waiters = this.waiters.filter((w) => w !== wake);
resolve(false);
}, timeoutMs);
const wake = () => {
clearTimeout(timer);
resolve(true);
};
this.waiters.push(wake);
});
}
/** Send one command and await the extension's reply. */
async request<T = unknown>(
action: BridgeAction,
payload: Record<string, unknown> = {},
timeoutMs = config.commandTimeoutMs,
): Promise<T> {
const socket = this.socket;
if (!socket || !this.isConnected()) {
throw new BridgeError(
"No WebBrain extension is connected. Open the browser, then set " +
"WebBrain → Settings → Bridge to " +
`ws://127.0.0.1:${config.bridgePort}${config.bridgePath}, paste the pairing key ` +
`from ${this.pairingKeyHint()} into Pairing key, and enable the MCP bridge.`,
);
}
let memoryValues: ReadonlySet<string> | undefined;
if (payload.task_memory !== undefined || (action !== "cloud_run" && payload.taskMemory !== undefined)) {
throw new BridgeError("task_memory is supported only through the private cloud_run transport.", 400);
}
if (action === "cloud_run" && payload.taskMemory !== undefined) {
let memory;
try { memory = validateTaskMemory(payload.taskMemory); }
catch { throw new BridgeError("Invalid task_memory envelope.", 400); }
if (!this.capabilities().includes(BOT_MEMORY_CAPABILITY)) {
throw new BridgeError("Update the browser extension before starting a task with bot memory.", 409);
}
// Retain privacy through failed/late runs: a scope is never evicted
// before the extension reports its run finished, and only then once
// room is needed. A known run ID lets every start be tracked that way.
const runId = typeof payload.runId === "string" ? payload.runId : `mcp_${randomUUID()}`;
if (!this.memoryRuns.has(runId) && !this.evictFinishedMemoryRuns()) {
await this.refreshMemoryRunStates(timeoutMs);
if (this.socket !== socket || !this.isConnected()) {
throw new BridgeError("WebBrain extension disconnected before the memory run could start.");
}
// Re-checked with no await before the scope is added below.
if (!this.memoryRuns.has(runId) && !this.evictFinishedMemoryRuns()) {
throw new BridgeError(
`${MAX_MEMORY_RUN_SCOPES} bot-memory runs are still unfinished on this bridge. ` +
"Wait for one to finish or abort it before starting another memory run.",
409,
);
}
}
payload = { ...payload, runId, taskMemory: memory };
memoryValues = new Set([...(this.memoryRunValues.get(runId) || []), ...taskMemoryPrivateValues(memory)]);
const credentials = [memory.callbackToken, memory.callbackUrl];
for (const credential of credentials) this.memoryPrivateValues.add(credential);
this.memoryProtectedRunIds.add(runId);
this.memoryRunValues.set(runId, memoryValues);
const previous = this.memoryRuns.get(runId);
this.memoryRuns.delete(runId);
this.memoryRuns.set(runId, {
credentials: [...new Set([...(previous?.credentials || []), ...credentials])],
startSettled: false,
finished: false,
});
}
const id = this.nextId++;
const frame = JSON.stringify({ id, action, payload });
const responseTimeoutMs = Math.max(1, Math.min(config.commandTimeoutMs, timeoutMs));
return new Promise<T>((resolve, reject) => {
const timer = setTimeout(() => {
this.pending.delete(id);
reject(
new BridgeError(
`WebBrain did not answer '${action}' within ${responseTimeoutMs}ms.`,
undefined,
"COMMAND_TIMEOUT",
),
);
}, responseTimeoutMs);
this.pending.set(id, { resolve: resolve as (v: unknown) => void, reject, timer,
runId: typeof payload.runId === "string" ? payload.runId : undefined,
memoryValues: memoryValues || (typeof payload.runId === "string" ? this.memoryRunValues.get(payload.runId) : undefined),
memoryStart: action === "cloud_run" && payload.taskMemory !== undefined,
protectedRequest: payload.taskMemory !== undefined || (typeof payload.runId === "string" && this.memoryProtectedRunIds.has(payload.runId)) });
try {
socket.send(frame);
} catch (error) {
this.pending.delete(id);
clearTimeout(timer);
reject(
new BridgeError(
`Failed to send '${action}': ${String(redactMemoryRunResponse(error instanceof Error ? error.message : String(error),
this.memoryPrivateValues, this.memoryProtectedRunIds, payload.taskMemory !== undefined,
{ runValues: this.memoryRunValues, requestRunId: typeof payload.runId === "string" ? payload.runId : undefined, requestValues: memoryValues }))}`,
),
);
}
});
}
async stop(): Promise<void> {
this.failAllPending(new BridgeError("Bridge shutting down."));
this.memoryPrivateValues.clear();
this.memoryProtectedRunIds.clear();
this.memoryRunValues.clear();
this.memoryRuns.clear();
for (const [candidate, state] of this.candidates) {
clearTimeout(state.timer);
try {
candidate.close(1001, "Server shutting down");
} catch {
/* ignore */
}
}
this.candidates.clear();
if (this.socket) {
try {
this.socket.close(1001, "Server shutting down");
} catch {
/* ignore */
}
this.socket = null;
}
if (this.wss) {
await new Promise<void>((resolve) => this.wss!.close(() => resolve()));
this.wss = null;
}
}
}