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.
TypeScript agentic-browseragentic-browsingagy-cliaiai-agentai-browser-extensionai-toolsbrave-extensionbrowser-agentbrowser-automationbrowser-extensionbrowser-usebrowserskillchrome-extensionclaude-codecodexfirefox-addonmcp-servernanobrowserweb-automation
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 type { TaskOrder } from '@/lib/schedules/task';
import { awaitMonitor } from '@/lib/actions/page/await-monitor';
import { PICK_DEFAULT_TIMEOUT_MS, pickElement } from '@/lib/actions/page/pick-element';
import { SOLVE_CAPTCHA_TIMEOUT_MS, solveCaptcha } from '@/lib/actions/page/solve-captcha';
import { startMonitor } from '@/lib/actions/page/start-monitor';
import { typeText, typingDurationMs } from '@/lib/actions/page/type-text';
import { AWAIT_DEFAULT_TIMEOUT_MS } from '@/lib/monitor/events';
import { log } from './log';
const PING_INTERVAL_MS = 20_000;
const DEFAULT_TIMEOUT_MS = 30_000;
const DESCRIBE_TIMEOUT_MS = 10_000;
const RUN_TASK_TIMEOUT_MS = 30_000;
interface Pending {
resolve: (result: ActionResult) => void;
timer: ReturnType<typeof setTimeout>;
}
let activity = 0;
/** A counter rather than a clock: two browsers can be touched within one millisecond, and the later one has to win. */
const touched = () => ++activity;
export class ExtensionLink {
readonly extensionVersion: string;
readonly manifestHash: string;
readonly origin: string;
readonly id: string;
readonly browser?: string;
readonly protocolVersion: number;
/** Which connected browser the user was last in, so a caller that names none reaches that one. */
lastActive = touched();
/** What this browser offers: a Firefox build lists fewer tools than a Chromium one, and a drifted build its own. */
tools: ToolDescriptor[] = [];
private readonly pending = new Map<string, Pending>();
private readonly ping: ReturnType<typeof setTimeout>;
private closed = false;
constructor(
private readonly socket: WebSocket,
hello: {
protocolVersion: number;
extensionVersion: string;
manifestHash: string;
origin: string;
installId: string;
browser?: string;
},
private readonly onClose: (link: ExtensionLink) => void,
private readonly onRequest?: (request: ExtensionRequest, link: ExtensionLink) => void,
) {
this.extensionVersion = hello.extensionVersion;
this.manifestHash = hello.manifestHash;
this.origin = hello.origin;
this.id = hello.installId;
this.browser = hello.browser;
this.protocolVersion = hello.protocolVersion;
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 label(): string {
return this.browser ?? this.origin;
}
speaks(version: number): boolean {
return this.protocolVersion >= version;
}
get bufferedAmount(): number {
return this.socket.bufferedAmount;
}
get isOpen(): boolean {
return !this.closed && this.socket.readyState === this.socket.OPEN;
}
invoke(action: string, input?: unknown, opts?: { tabId?: number; runId?: string }): Promise<ActionResult> {
const frame = { t: 'invoke' as const, id: randomUUID(), action, input, ...opts };
return this.request(frame, 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;
}
runTask(order: TaskOrder): Promise<ActionResult> {
return this.request({ t: 'runTask', id: randomUUID(), order }, RUN_TASK_TIMEOUT_MS);
}
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 {
}
}
private request(frame: SocketFrame & { id: string }, timeoutMs: number): Promise<ActionResult> {
if (!this.isOpen) {
return Promise.resolve(failure('EXTENSION_OFFLINE', 'The Browsentic 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;
if (frame.t === 'focus') return void (this.lastActive = touched());
if (isExtensionRequest(frame)) {
// A notice is sent because nobody is looking at this browser, so it says nothing about where the user is.
if (frame.t !== 'notice') this.lastActive = touched();
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);
}
}
const SCREENSHOT_TIMEOUT_MS = 120_000;
function timeoutFor(action: string, input: unknown): number {
if (action === 'page.screenshot') return SCREENSHOT_TIMEOUT_MS;
if (action === typeText.name) return typingDurationMs(input) + DEFAULT_TIMEOUT_MS;
if (action === startMonitor.name) return DEFAULT_TIMEOUT_MS;
if (action === awaitMonitor.name) return (declaredTimeout(input) ?? AWAIT_DEFAULT_TIMEOUT_MS) + 5_000;
if (action === pickElement.name) return (declaredTimeout(input) ?? PICK_DEFAULT_TIMEOUT_MS) + 5_000;
if (action === solveCaptcha.name) return (declaredTimeout(input) ?? SOLVE_CAPTCHA_TIMEOUT_MS) + 5_000;
const declared = declaredTimeout(input);
return declared != null ? declared + 5_000 : DEFAULT_TIMEOUT_MS;
}
function declaredTimeout(input: unknown): number | null {
const declared = (input as { timeoutMs?: unknown } | undefined)?.timeoutMs;
return typeof declared === 'number' && declared > 0 ? declared : null;
}