Skip to content

An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.

feat(mcp): add the loopback daemon and its origin-pinned extension link

Shahriarbdfab99c5fca
diff --git a/mcp/src/daemon-main.ts b/mcp/src/daemon-main.ts
new file mode 100644
index 0000000..c2525b7
--- /dev/null
+++ b/mcp/src/daemon-main.ts
@@ -0,0 +1,18 @@
+import { startDaemon } from './daemon';
+import { log } from './log';
+import pkg from '../package.json';
+
+const daemon = await startDaemon({
+ version: pkg.version,
+ idleExit: !process.argv.includes('--no-idle-exit'),
+}).catch((error) => {
+ log('daemon failed to start', error);
+ process.stderr.write(`voicelink-mcpd: ${error instanceof Error ? error.message : error}\n`);
+ process.exit(1);
+});
+
+for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+ process.on(signal, () => {
+ void daemon.stop().then(() => process.exit(0));
+ });
+}
diff --git a/mcp/src/daemon.ts b/mcp/src/daemon.ts
new file mode 100644
index 0000000..850b711
--- /dev/null
+++ b/mcp/src/daemon.ts
@@ -0,0 +1,412 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { createServer, type IncomingMessage, type Server } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { WebSocketServer, type WebSocket } from 'ws';
+import { DAEMON_PORTS, SOCKET_PROTOCOL_VERSION, failure, parseFrame, type ActionResult } from '@/lib/actions/protocol';
+import { hashManifest } from '@/lib/actions/manifest';
+import { describeActions } from '@/lib/actions/registry';
+import { saveScreenshot } from './screenshots';
+import {
+ consumePairing,
+ createPairing,
+ createSession,
+ hasPendingPairing,
+ listSessions,
+ revokeSessions,
+ validateSession,
+} from './auth-store';
+import { AgentSession } from './agent/service';
+import { summarizeFile } from './agent/analyze';
+import { readAgentConfig } from './agent/config';
+import type { Bridge, BridgeStatus, ControlMessage, ControlRequest, SessionSummary } from './control';
+import { ExtensionLink } from './extension-link';
+import { log } from './log';
+import { readLockfile, writeLockfile, clearLockfile, type Lockfile } from './lockfile';
+
+const IDLE_EXIT_MS = 30 * 60 * 1000;
+const EXTENSION_ORIGIN = /^(chrome|moz|safari-web)-extension:\/\//;
+
+export interface DaemonOptions {
+ version: string;
+ idleExit?: boolean;
+}
+
+export interface Daemon extends Bridge {
+ port: number;
+ stop(): Promise<void>;
+}
+
+/**
+ * When a `page.screenshot { save: true }` succeeds, write the captured image to disk and note the
+ * path (or the write error) on the result. A failed save never fails the capture — the caller
+ * still gets the image to look at.
+ */
+function persistScreenshot(action: string, input: unknown, result: ActionResult): ActionResult {
+ if (action !== 'page.screenshot' || !result.ok) return result;
+ const args = (input ?? {}) as { save?: unknown; filename?: unknown };
+ const data = result.data as { dataUrl?: unknown } | null;
+ if (args.save !== true || typeof data?.dataUrl !== 'string') return result;
+ try {
+ const savedTo = saveScreenshot(data.dataUrl, {
+ filename: typeof args.filename === 'string' ? args.filename : undefined,
+ });
+ log(`screenshot saved to ${savedTo}`);
+ return { ok: true, data: { ...(result.data as object), savedTo } };
+ } catch (error) {
+ const saveError = error instanceof Error ? error.message : String(error);
+ log(`screenshot save failed: ${saveError}`);
+ return { ok: true, data: { ...(result.data as object), saveError } };
+ }
+}
+
+export async function startDaemon({ version, idleExit = true }: DaemonOptions): Promise<Daemon> {
+ const bundled = describeActions();
+ const bundledHash = hashManifest(bundled);
+
+ let tools = bundled;
+ let manifestInSync = true;
+ let link: ExtensionLink | null = null;
+ let agent: AgentSession | null = null;
+ const controls = new Set<WebSocket>();
+ const manifestListeners = new Set<() => void>();
+ let idleTimer: ReturnType<typeof setTimeout> | null = null;
+
+ const previous = readLockfile();
+ const lock: Lockfile = {
+ pid: process.pid,
+ port: 0,
+ // Reuse the previous token so CLIs holding a stale copy keep working across restarts.
+ token: previous?.token ?? randomBytes(24).toString('base64url'),
+ protocolVersion: SOCKET_PROTOCOL_VERSION,
+ daemonVersion: version,
+ };
+
+ const http = createServer((req, res) => {
+ if (req.url?.startsWith('/health')) {
+ res.writeHead(200, { 'content-type': 'application/json' });
+ res.end(JSON.stringify({ ok: true, pid: process.pid, version, connected: !!link?.isOpen }));
+ return;
+ }
+ res.writeHead(404).end();
+ });
+
+ const wss = new WebSocketServer({ noServer: true });
+ http.on('upgrade', (req, socket, head) => {
+ const role = authorize(req);
+ if (!role) return refuseUpgrade(socket, 'unauthorized');
+ wss.handleUpgrade(req, socket, head, (ws) => {
+ if (role === 'extension') acceptExtension(ws, req);
+ else acceptControl(ws);
+ });
+ });
+
+ const port = await listen(http);
+ lock.port = port;
+ writeLockfile(lock);
+ log(`daemon ${version} listening on 127.0.0.1:${port} (pid ${process.pid})`);
+ scheduleIdleExit();
+
+ /**
+ * Gate the HTTP upgrade by peer *kind*. Browsers set `Origin` themselves and pages cannot
+ * forge or omit it, so the two branches are mutually exclusive: a web page can never reach
+ * the control path, and a local process can never impersonate the extension.
+ *
+ * This only decides which door to knock on. An extension still has to authenticate with a
+ * pairing token or session key in its `hello` frame before it can do anything.
+ */
+ function authorize(req: IncomingMessage): 'extension' | 'control' | null {
+ const origin = req.headers.origin;
+ if (origin && EXTENSION_ORIGIN.test(origin)) return 'extension';
+ if (origin) {
+ log(`rejected web origin ${origin}`);
+ return null;
+ }
+ // No Origin header: a local process. Must prove it can read the 0600 lockfile.
+ if (!hasValidToken(req)) {
+ log('rejected control client: missing or invalid token');
+ return null;
+ }
+ return 'control';
+ }
+
+ function hasValidToken(req: IncomingMessage): boolean {
+ const header = req.headers.authorization ?? '';
+ const offered = Buffer.from(header.replace(/^Bearer\s+/i, ''));
+ const expected = Buffer.from(lock.token);
+ return offered.length === expected.length && timingSafeEqual(offered, expected);
+ }
+
+ function acceptExtension(ws: WebSocket, req: IncomingMessage): void {
+ // Nothing is served on this socket until `hello` proves the extension was paired.
+ const reject = (reason: string, retryable: boolean) => {
+ log(`rejected extension: ${reason}`);
+ try {
+ ws.send(JSON.stringify({ t: 'unauthorized', reason, retryable }));
+ } catch {
+ // Closing anyway.
+ }
+ ws.close(4401, 'unauthorized');
+ };
+
+ ws.once('message', async (raw) => {
+ const hello = parseFrame(String(raw));
+ if (hello?.t !== 'hello') {
+ log('extension sent no hello frame; closing');
+ ws.close(1002, 'expected hello');
+ return;
+ }
+ if (hello.protocolVersion !== SOCKET_PROTOCOL_VERSION) {
+ log(`extension protocol v${hello.protocolVersion} != daemon v${SOCKET_PROTOCOL_VERSION}; closing`);
+ ws.close(1002, `protocol version mismatch: daemon speaks v${SOCKET_PROTOCOL_VERSION}`);
+ return;
+ }
+
+ const origin = req.headers.origin!;
+ const auth = hello.auth;
+ let issuedKey: string | undefined;
+ if (auth && 'pairingToken' in auth) {
+ if (!consumePairing(auth.pairingToken)) {
+ return reject('That pairing code is wrong or expired. Run "voicelink-mcp pair" for a new one.', true);
+ }
+ issuedKey = createSession(origin, hello.extensionVersion).key;
+ log(`paired ${origin} (extension ${hello.extensionVersion})`);
+ } else if (auth && 'sessionKey' in auth) {
+ if (!validateSession(auth.sessionKey, origin)) {
+ // Revoked, or the auth store was cleared: tell the extension to forget its key.
+ return reject('This browser is no longer paired. Run "voicelink-mcp pair" to pair again.', false);
+ }
+ } else {
+ return reject('No pairing token or session key supplied.', false);
+ }
+
+ link?.close('superseded by a newer connection');
+ agent?.dispose();
+ manifestInSync = hello.manifestHash === bundledHash;
+ const accepted = new ExtensionLink(
+ ws,
+ { ...hello, origin },
+ (closing) => {
+ if (link !== closing) return;
+ link = null;
+ // The conversation was about a browser that is gone; nothing survives it.
+ agent?.dispose();
+ agent = null;
+ log('extension disconnected');
+ scheduleIdleExit();
+ },
+ // The agent harness: the extension asks the daemon to think, and the daemon answers
+ // by driving the browser back down this same socket. A file to summarize is the one
+ // stateless request — it runs outside the conversation and replies with `fileSummary`,
+ // so it is handled here rather than in the run-gated AgentSession.
+ (request, source) => {
+ if (request.t === 'analyzeFile') {
+ void summarizeFile(request, readAgentConfig())
+ .then((result) => source.send({ t: 'fileSummary', id: request.id, result }))
+ .catch((error) =>
+ source.send({ t: 'fileSummary', id: request.id, result: failure('AGENT_FAILED', String(error)) }),
+ );
+ return;
+ }
+ session(source).handle(request);
+ },
+ );
+ link = accepted;
+ log(`extension ${hello.extensionVersion} connected from ${origin} (manifest ${manifestInSync ? 'in sync' : 'DRIFTED'})`);
+ accepted.send({
+ t: 'welcome',
+ daemonVersion: version,
+ manifestHash: bundledHash,
+ manifestInSync,
+ sessionKey: issuedKey,
+ });
+ scheduleIdleExit();
+ if (!manifestInSync) await adoptExtensionManifest(accepted);
+ });
+ }
+
+ /**
+ * The agent state for the connected browser, created on its first instruction. It routes tool
+ * calls through the same `invoke` MCP clients use, so the agent has no privileged path.
+ */
+ function session(source: ExtensionLink): AgentSession {
+ return (agent ??= new AgentSession({
+ invoke,
+ emit: (id, event) => source.send({ t: 'run', id, event }),
+ }));
+ }
+
+ /** The installed extension was built from a different registry — believe the browser, not the bundle. */
+ async function adoptExtensionManifest(source: ExtensionLink): Promise<void> {
+ const reported = await source.describe();
+ if (!reported?.length) {
+ log('extension manifest drifted but could not be fetched; keeping the bundled tool list');
+ return;
+ }
+ tools = reported;
+ log(`adopted ${reported.length} tools from the extension (bundled list was ${bundled.length})`);
+ for (const listener of manifestListeners) listener();
+ broadcast({ event: 'manifest-changed' });
+ }
+
+ function acceptControl(ws: WebSocket): void {
+ controls.add(ws);
+ scheduleIdleExit();
+ ws.on('message', async (raw) => {
+ let request: ControlRequest;
+ try {
+ request = JSON.parse(String(raw)) as ControlRequest;
+ } catch {
+ return log('dropped unparseable control frame');
+ }
+ if (request.op === 'describe') return send(ws, { id: request.id, op: 'describe', tools });
+ if (request.op === 'status') return send(ws, { id: request.id, op: 'status', status: statusNow() });
+ if (request.op === 'invoke') {
+ // A run-tagged invocation belongs to a spawned agent: it goes through the run's
+ // approval gate and shows up on the extension's timeline. Anything else is a plain
+ // MCP client and takes the direct path.
+ const result = request.runId
+ ? ((await agent?.invokeForRun(request.runId, request.action, request.input)) ??
+ failure('RUN_INACTIVE', 'This agent run is no longer active'))
+ : await invoke(request.action, request.input);
+ return send(ws, { id: request.id, op: 'invoke', result });
+ }
+ if (request.op === 'pair') {
+ const { code, expiresAt } = createPairing();
+ log('minted a pairing code');
+ return send(ws, { id: request.id, op: 'pair', code, expiresAt });
+ }
+ if (request.op === 'sessions') {
+ return send(ws, { id: request.id, op: 'sessions', sessions: sessionSummaries() });
+ }
+ if (request.op === 'revoke') {
+ const target = request.origin;
+ const revoked = revokeSessions((session) => !target || session.origin === target);
+ // A revoked browser must not keep driving the tab it is already attached to.
+ if (revoked && link?.isOpen && (!target || link.origin === target)) {
+ link.close('pairing revoked');
+ }
+ log(`revoked ${revoked} session(s)`);
+ return send(ws, { id: request.id, op: 'revoke', revoked });
+ }
+ });
+ const drop = () => {
+ controls.delete(ws);
+ scheduleIdleExit();
+ };
+ ws.on('close', drop);
+ ws.on('error', drop);
+ }
+
+ function send(ws: WebSocket, message: ControlMessage): void {
+ if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(message));
+ }
+
+ function broadcast(message: ControlMessage): void {
+ for (const ws of controls) send(ws, message);
+ }
+
+ function sessionSummaries(): SessionSummary[] {
+ return listSessions().map(({ key: _key, ...session }) => ({
+ ...session,
+ connected: link?.isOpen === true && link.origin === session.origin,
+ }));
+ }
+
+ function statusNow(): BridgeStatus {
+ return {
+ connected: !!link?.isOpen,
+ daemonVersion: version,
+ protocolVersion: SOCKET_PROTOCOL_VERSION,
+ port,
+ manifestInSync,
+ extensionVersion: link?.extensionVersion,
+ pairedBrowsers: listSessions().length,
+ pairingPending: hasPendingPairing(),
+ };
+ }
+
+ async function invoke(action: string, input?: unknown) {
+ if (!link?.isOpen) {
+ return failure(
+ 'EXTENSION_OFFLINE',
+ 'The VoiceLink extension is not connected — open your browser with the extension loaded, then retry',
+ );
+ }
+ // Every caller — direct MCP clients and spawned agent runs alike — reaches the browser
+ // through here, so this is the one place to write a screenshot to disk when asked.
+ return persistScreenshot(action, input, await link.invoke(action, input));
+ }
+
+ /** Nothing attached and nobody asking: don't linger in the user's process list forever. */
+ function scheduleIdleExit(): void {
+ if (idleTimer) clearTimeout(idleTimer);
+ if (!idleExit) return;
+ if (link?.isOpen || controls.size > 0) return;
+ idleTimer = setTimeout(() => {
+ if (link?.isOpen || controls.size > 0) return scheduleIdleExit();
+ log('idle with no clients; exiting');
+ void stop().then(() => process.exit(0));
+ }, IDLE_EXIT_MS);
+ idleTimer.unref();
+ }
+
+ async function stop(): Promise<void> {
+ if (idleTimer) clearTimeout(idleTimer);
+ agent?.dispose();
+ link?.close('daemon shutting down');
+ for (const ws of controls) ws.close(1001, 'daemon shutting down');
+ wss.close();
+ await new Promise<void>((resolve) => http.close(() => resolve()));
+ // Only clear the lockfile if it still describes us; a successor may have replaced it.
+ if (readLockfile()?.pid === process.pid) clearLockfile();
+ log('daemon stopped');
+ }
+
+ return {
+ port,
+ describe: async () => tools,
+ invoke,
+ status: async () => statusNow(),
+ onManifestChanged: (listener) => manifestListeners.add(listener),
+ close: stop,
+ stop,
+ };
+}
+
+/**
+ * Bind the first free port in the fixed range. The bind is also the mutex against two
+ * daemons racing to start: the loser sees EADDRINUSE and connects to the winner instead.
+ */
+function listen(http: Server): Promise<number> {
+ return new Promise((resolve, reject) => {
+ const remaining = [...DAEMON_PORTS];
+ const attempt = () => {
+ const port = remaining.shift();
+ if (port === undefined) {
+ reject(new Error(`No free port in ${DAEMON_PORTS.join(', ')} — another process is using them all`));
+ return;
+ }
+ const onListening = () => {
+ http.removeListener('error', onError);
+ resolve(port);
+ };
+ const onError = (error: NodeJS.ErrnoException) => {
+ // Drop this attempt's success handler too: a later attempt's bind would otherwise
+ // fire it as well, resolving with a port the daemon is not actually listening on.
+ http.removeListener('listening', onListening);
+ if (error.code !== 'EADDRINUSE') return reject(error);
+ http.removeListener('error', onError);
+ attempt();
+ };
+ http.once('error', onError);
+ http.once('listening', onListening);
+ http.listen(port, '127.0.0.1');
+ };
+ attempt();
+ });
+}
+
+function refuseUpgrade(socket: Duplex, reason: string): void {
+ socket.write(`HTTP/1.1 403 Forbidden\r\nContent-Length: 0\r\nConnection: close\r\nX-VoiceLink-Reason: ${reason}\r\n\r\n`);
+ socket.destroy();
+}
diff --git a/mcp/src/ensure-daemon.ts b/mcp/src/ensure-daemon.ts
new file mode 100644
index 0000000..12a16bb
--- /dev/null
+++ b/mcp/src/ensure-daemon.ts
@@ -0,0 +1,61 @@
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { DAEMON_PORTS } from '@/lib/actions/protocol';
+import { isRunning, readLockfile, type Lockfile } from './lockfile';
+import { log } from './log';
+
+const SPAWN_TIMEOUT_MS = 8_000;
+const POLL_INTERVAL_MS = 150;
+
+/** A live daemon, started if one was not already running. */
+export async function ensureDaemon(): Promise<Lockfile> {
+ const existing = await probeExisting();
+ if (existing) return existing;
+
+ log('no daemon reachable; spawning one');
+ const daemonMain = join(dirname(fileURLToPath(import.meta.url)), 'daemon-main.js');
+ const child = spawn(process.execPath, [daemonMain], {
+ detached: true,
+ // Inheriting stdio would tie the daemon's lifetime and output to this MCP session.
+ stdio: 'ignore',
+ env: process.env,
+ });
+ child.unref();
+
+ const deadline = Date.now() + SPAWN_TIMEOUT_MS;
+ while (Date.now() < deadline) {
+ await delay(POLL_INTERVAL_MS);
+ const started = await probeExisting();
+ if (started) return started;
+ }
+ throw new Error(`The VoiceLink daemon did not come up within ${SPAWN_TIMEOUT_MS}ms — see the log with "voicelink-mcp logs"`);
+}
+
+/** The lockfile of a daemon that is actually answering, or null. */
+export async function probeExisting(): Promise<Lockfile | null> {
+ const lock = readLockfile();
+ if (lock && isRunning(lock.pid) && (await isHealthy(lock.port))) return lock;
+
+ // A stale lockfile (crash, or a daemon started under a different HOME) hides a live daemon;
+ // the port range is small enough to just check it.
+ for (const port of DAEMON_PORTS) {
+ if (port !== lock?.port && (await isHealthy(port)) && lock) return { ...lock, port };
+ }
+ return null;
+}
+
+async function isHealthy(port: number): Promise<boolean> {
+ try {
+ const response = await fetch(`http://127.0.0.1:${port}/health`, {
+ signal: AbortSignal.timeout(1_000),
+ });
+ return response.ok;
+ } catch {
+ return false;
+ }
+}
+
+function delay(ms: number): Promise<void> {
+ return new Promise((resolve) => setTimeout(resolve, ms));
+}
diff --git a/mcp/src/extension-link.ts b/mcp/src/extension-link.ts
new file mode 100644
index 0000000..92dad09
--- /dev/null
+++ b/mcp/src/extension-link.ts
@@ -0,0 +1,138 @@
+import { randomUUID } from 'node:crypto';
+import type { WebSocket } from 'ws';
+import {
+ failure,
+ isExtensionRequest,
+ parseFrame,
+ type ActionResult,
+ type ExtensionRequest,
+ type SocketFrame,
+} from '@/lib/actions/protocol';
+import type { ToolDescriptor } from '@/lib/actions/manifest';
+import { log } from './log';
+
+/** Chrome kills an idle MV3 worker after 30s; socket traffic resets that timer. */
+const PING_INTERVAL_MS = 20_000;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DESCRIBE_TIMEOUT_MS = 10_000;
+
+interface Pending {
+ resolve: (result: ActionResult) => void;
+ timer: ReturnType<typeof setTimeout>;
+}
+
+/** One live connection to the extension's service worker. */
+export class ExtensionLink {
+ readonly extensionVersion: string;
+ readonly manifestHash: string;
+ readonly origin: string;
+ private readonly pending = new Map<string, Pending>();
+ private readonly ping: ReturnType<typeof setTimeout>;
+ private closed = false;
+
+ constructor(
+ private readonly socket: WebSocket,
+ hello: { extensionVersion: string; manifestHash: string; origin: string },
+ private readonly onClose: (link: ExtensionLink) => void,
+ /** Extension-initiated frames — the agent harness. Absent means "ignore them". */
+ private readonly onRequest?: (request: ExtensionRequest, link: ExtensionLink) => void,
+ ) {
+ this.extensionVersion = hello.extensionVersion;
+ this.manifestHash = hello.manifestHash;
+ this.origin = hello.origin;
+ socket.on('message', (raw) => this.receive(String(raw)));
+ socket.on('close', () => this.dispose('socket closed'));
+ socket.on('error', (error) => {
+ log('extension socket error', error);
+ this.dispose('socket error');
+ });
+ this.ping = setInterval(() => this.send({ t: 'ping', id: randomUUID() }), PING_INTERVAL_MS);
+ }
+
+ get isOpen(): boolean {
+ return !this.closed && this.socket.readyState === this.socket.OPEN;
+ }
+
+ invoke(action: string, input?: unknown): Promise<ActionResult> {
+ return this.request({ t: 'invoke', id: randomUUID(), action, input }, timeoutFor(action, input));
+ }
+
+ async describe(): Promise<ToolDescriptor[] | null> {
+ const result = await this.request({ t: 'describe', id: randomUUID() }, DESCRIBE_TIMEOUT_MS);
+ return result.ok ? (result.data as ToolDescriptor[]) : null;
+ }
+
+ send(frame: SocketFrame): void {
+ try {
+ this.socket.send(JSON.stringify(frame));
+ } catch (error) {
+ log('failed to send frame to extension', error);
+ }
+ }
+
+ close(reason: string): void {
+ this.dispose(reason);
+ try {
+ this.socket.close(1000, reason);
+ } catch {
+ // Already gone.
+ }
+ }
+
+ private request(frame: SocketFrame & { id: string }, timeoutMs: number): Promise<ActionResult> {
+ if (!this.isOpen) {
+ return Promise.resolve(failure('EXTENSION_OFFLINE', 'The VoiceLink extension is not connected'));
+ }
+ return new Promise((resolve) => {
+ const timer = setTimeout(() => {
+ this.pending.delete(frame.id);
+ resolve(failure('TIMEOUT', `The extension did not respond within ${timeoutMs}ms`));
+ }, timeoutMs);
+ this.pending.set(frame.id, { resolve, timer });
+ this.send(frame);
+ });
+ }
+
+ private receive(raw: string): void {
+ const frame = parseFrame(raw);
+ if (!frame) return log('dropped unparseable frame from extension');
+ if (frame.t === 'ping') return this.send({ t: 'pong', id: frame.id });
+ if (frame.t === 'pong') return;
+ // Requests, not replies: their ids name an agent run, so they must not be matched
+ // against `pending`, which only tracks invocations the daemon itself started.
+ if (isExtensionRequest(frame)) return this.onRequest?.(frame, this);
+
+ const id = 'id' in frame ? frame.id : undefined;
+ const waiting = id ? this.pending.get(id) : undefined;
+ if (!waiting || !id) return;
+ this.pending.delete(id);
+ clearTimeout(waiting.timer);
+ if (frame.t === 'result') waiting.resolve(frame.result);
+ else if (frame.t === 'manifest') waiting.resolve({ ok: true, data: frame.tools });
+ }
+
+ private dispose(reason: string): void {
+ if (this.closed) return;
+ this.closed = true;
+ clearInterval(this.ping);
+ for (const [, waiting] of this.pending) {
+ clearTimeout(waiting.timer);
+ waiting.resolve(failure('EXTENSION_OFFLINE', `Connection lost: ${reason}`));
+ }
+ this.pending.clear();
+ this.onClose(this);
+ }
+}
+
+/**
+ * `page.screenshot` scrolls and captures the tab tile by tile, so its worst case (bounded by the
+ * background's tile cap) far exceeds a single action's budget; give it a generous fixed window.
+ * Actions that wait (only `page.waitForElement` today) declare their own `timeoutMs`.
+ */
+const SCREENSHOT_TIMEOUT_MS = 120_000;
+
+function timeoutFor(action: string, input: unknown): number {
+ if (action === 'page.screenshot') return SCREENSHOT_TIMEOUT_MS;
+ const declared = (input as { timeoutMs?: unknown } | undefined)?.timeoutMs;
+ return typeof declared === 'number' && declared > 0 ? declared + 5_000 : DEFAULT_TIMEOUT_MS;
+}