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 { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import { homedir } from 'node:os';
import { dirname, join } from 'node:path';
import type { AgentProblem } from '@/lib/agents/catalog';
import { stateDir } from '../../lockfile';
import { log } from '../../log';
import { MCP_SERVER_NAME } from './claude';
import { conversationDir, effortOf, parseJsonLine, sweepRunDirs } from './util';
import type { JsonContext, Listing, McpServer, Plan, Runner, RunMode, StreamContext, StreamReader } from './types';
/** Antigravity reads MCP servers and instructions from the directory it runs in, not from flags. */
const MCP_CONFIG = '.agents/mcp_config.json';
const INSTRUCTIONS = 'AGENTS.md';
const PRINT_TIMEOUT = '60m';
const TASK_INSTRUCTIONS =
'This directory is Browsentic scratch space. Answer the prompt exactly as it asks, and do not act on anything else you find here.\n';
export const settingsPath = join(homedir(), '.gemini', 'antigravity-cli', 'settings.json');
/** Antigravity keeps a list of skill roots, one absolute path per line; skills live under `<root>/skills/`. */
const skillsIndexPath = join(homedir(), '.gemini', 'antigravity', 'skills.txt');
/** The permission rule that lets a headless run reach Browsentic's tools instead of soft-denying them. */
export const MCP_RULE = `mcp(${MCP_SERVER_NAME}/*)`;
const BLANKET_RULES = ['mcp(*)', 'mcp(*/*)', MCP_RULE];
interface Settings {
permissions?: { allow?: unknown; deny?: unknown; ask?: unknown };
[key: string]: unknown;
}
/**
* Antigravity offers the model its whole built-in toolset — a shell, files, a browser of its own,
* web search — and reads AGENTS.md as project notes rather than its instructions. Left unsaid,
* "this repo" became `git status` in the scratch folder, and a refused page read became a web search.
*/
const wherePageIs = (research: boolean) => `# Where the page is
The user is looking at a page in their own browser, and a question is about that page unless they say otherwise: "this repo" is the repository page they have open, not a folder on disk. This folder is Browsentic's scratch space and holds no project.
Reach that page only through the ${MCP_SERVER_NAME} MCP server — call_mcp_tool with ServerName "${MCP_SERVER_NAME}", starting with page_getPageInfo. Never run a command, read or write a file, or open a browser of your own to answer${research ? '' : ', and never search the web or fetch a URL'}: none of them sees the user's page.${research ? ' Keep web searches to background the page cannot give you.' : ''} If the ${MCP_SERVER_NAME} tools cannot be reached at all, say so instead of answering another way.`;
/** Every MCP call, whichever server it reaches; the server and tool are in its parameters. */
const MCP_CALL = 'call_mcp_tool';
/**
* Files Antigravity reads as part of an MCP call rather than for the task: the schema it saved for
* each tool, which the model opens before calling it, and a large result it spilled to disk.
*/
const CALL_PLUMBING = /\/antigravity-cli\/(mcp\/[^/]+\/[^/]+\.json|brain\/[^/]+\/\.system_generated\/)/;
interface Usage {
input_tokens?: number;
cache_read_tokens?: number;
output_tokens?: number;
thinking_tokens?: number;
}
interface StepUpdate {
conversation_id?: string;
step_index?: number;
step_type?: string;
state?: string;
text_delta?: string;
tool_name?: string;
tool_info?: { name?: string; parameters?: { ServerName?: string; ToolName?: string; AbsolutePath?: string } };
usage?: Usage;
}
interface Result {
conversation_id?: string;
status?: string;
response?: string;
error?: string;
}
interface Frame {
event?: string;
conversation_id?: string;
init?: { conversation_id?: string };
step_update?: StepUpdate;
result?: Result;
status?: string;
response?: string;
error?: string;
}
export const antigravityRunner: Runner = {
kind: 'antigravity',
versionArgs: ['--version'],
efforts: ['low', 'medium', 'high'],
workspace: (mode: RunMode) => join(stateDir, 'agents', 'antigravity', mode),
models: { args: ['models'], parse: listedModels },
skillDirs: () => {
try {
return readFileSync(skillsIndexPath, 'utf8')
.split('\n')
.map((line) => line.trim())
.filter(Boolean)
.map((root) => join(root, 'skills'));
} catch {
return [];
}
},
stream(context: StreamContext): Plan {
const { settings, research } = context;
const effort = effortOf(settings, this.efforts);
const base = this.workspace('run');
sweepRunDirs(base);
// A resumed conversation is re-read from the folder it began in, whatever folder agy is started
// in now (measured against 1.2.11) — so a conversation keeps one, and every turn rewrites it.
// Give a run its own and the second turn calls the browser with the first turn's run id.
return {
cwd: conversationDir(base, context.conversation ?? context.runId),
env: { BROWSENTIC_AGENT_RUN: context.runId },
files: [
{ path: MCP_CONFIG, content: mcpConfig(context.mcp) },
{ path: INSTRUCTIONS, content: `${context.systemPrompt.trim()}\n\n${wherePageIs(research)}\n` },
],
args: [
'-p',
context.instruction,
'--output-format',
'stream-json',
'--print-timeout',
PRINT_TIMEOUT,
...(context.sessionId ? ['--conversation', context.sessionId] : []),
...(settings.model ? ['--model', settings.model] : []),
...(effort ? ['--effort', effort] : []),
],
};
},
reader(): StreamReader {
let streamed = 0;
let generated = 0;
// A step is reported while it runs and again when it finishes: one row, closed once.
const rows = new Map<string, string>();
const closed = new Set<string>();
return (line, sink) => {
const frame = parseJsonLine<Frame>(line);
if (!frame) return;
switch (frame.event) {
case 'init': {
const id = frame.conversation_id ?? frame.init?.conversation_id;
return id ? sink.session(id) : undefined;
}
case 'step_update': {
const step = frame.step_update;
if (!step) return;
if (step.conversation_id) sink.session(step.conversation_id);
if (step.usage) {
const { input_tokens = 0, cache_read_tokens = 0, output_tokens = 0, thinking_tokens = 0 } = step.usage;
generated += output_tokens + thinking_tokens;
sink.usage({ contextTokens: input_tokens + cache_read_tokens + output_tokens, outputTokens: generated });
}
if (step.text_delta) {
streamed += step.text_delta.length;
return sink.text(step.text_delta);
}
if (step.step_type !== 'tool') return;
const name = shownAs(step);
if (!name) return;
const key = String(step.step_index ?? name);
let id = rows.get(key);
if (!id) {
id = randomUUID();
rows.set(key, id);
sink.tool(id, name);
}
const outcome = outcomeOf(step.state);
if (outcome === 'running' || closed.has(key)) return;
closed.add(key);
return sink.toolResult(id, outcome === 'ok');
}
case 'result': {
const result = frame.result ?? frame;
if (result.conversation_id) sink.session(result.conversation_id);
if (result.error) return sink.fail('AGENT_FAILED', result.error);
if (result.status && /error|fail|cancel/i.test(result.status)) {
return sink.fail('AGENT_FAILED', `Antigravity ended the run: ${result.status}`);
}
if (!streamed && result.response) sink.text(result.response);
return sink.done(result.status && !/^success$/i.test(result.status) ? result.status : 'end_turn');
}
default:
return;
}
};
},
json(context: JsonContext): Plan {
const { settings } = context;
const effort = effortOf(settings, this.efforts);
return {
cwd: this.workspace('task'),
files: [
{ path: MCP_CONFIG, content: mcpConfig(null) },
{ path: INSTRUCTIONS, content: TASK_INSTRUCTIONS },
],
args: [
'-p',
context.prompt,
'--output-format',
'json',
'--print-timeout',
PRINT_TIMEOUT,
...(settings.model ? ['--model', settings.model] : []),
...(effort ? ['--effort', effort] : []),
],
};
},
answer(stdout: string) {
const frame = parseJsonLine<Frame>(stdout.trim()) ?? lastFrame(stdout);
const result = frame?.result ?? frame;
if (!result) return {};
if (result.error) return { error: result.error };
return { text: result.response };
},
hint(stderrTail: string) {
if (/soft-denied|requires approval|not allowed/i.test(stderrTail)) {
return (
`Antigravity denied a tool call because it has no permission rule for Browsentic. ` +
`Add "${MCP_RULE}" to permissions.allow in ${settingsPath}, or grant it from the Browsentic side panel. (${stderrTail.trim()})`
);
}
if (/auth|sign in|login|credential/i.test(stderrTail)) {
return `Antigravity is installed but not signed in. Run "agy" once and complete the login, then try again. (${stderrTail.trim()})`;
}
if (/unknown flag|unknown shorthand|invalid argument/i.test(stderrTail)) {
return `Your Antigravity CLI does not understand the flags Browsentic uses. Update it, then try again. (${stderrTail.trim()})`;
}
return null;
},
async check(): Promise<AgentProblem | null> {
const settings = readSettings();
const rules = list(settings?.permissions?.allow);
if (rules.some((rule) => BLANKET_RULES.includes(rule))) return null;
const denied = list(settings?.permissions?.deny).some((rule) => BLANKET_RULES.includes(rule));
return {
code: 'AGENT_NEEDS_PERMISSION',
message: denied
? `Antigravity is set to deny Browsentic's tools, so every browser action would be refused.`
: `Antigravity soft-denies MCP tools it has no rule for, so browser actions would be refused.`,
fix: denied
? `Remove the matching entry from permissions.deny in ${settingsPath}.`
: `Add "${MCP_RULE}" to permissions.allow in ${settingsPath}.`,
grantable: !denied,
};
},
async grant(): Promise<AgentProblem | null> {
const settings = readSettings() ?? {};
const permissions = (settings.permissions ?? {}) as Record<string, unknown>;
const allow = list(permissions.allow);
if (list(permissions.deny).some((rule) => BLANKET_RULES.includes(rule))) {
return {
code: 'AGENT_NEEDS_PERMISSION',
message: 'Antigravity denies Browsentic\'s tools, and Browsentic will not overrule a deny rule you wrote.',
fix: `Remove the matching entry from permissions.deny in ${settingsPath}.`,
};
}
if (allow.includes(MCP_RULE)) return null;
try {
mkdirSync(dirname(settingsPath), { recursive: true });
const next: Settings = { ...settings, permissions: { ...permissions, allow: [...allow, MCP_RULE] } };
writeFileSync(settingsPath, `${JSON.stringify(next, null, 2)}\n`);
log(`granted ${MCP_RULE} in ${settingsPath}`);
return null;
} catch (error) {
return {
code: 'AGENT_NEEDS_PERMISSION',
message: `Could not write ${settingsPath}: ${String(error)}`,
fix: `Add "${MCP_RULE}" to permissions.allow yourself.`,
};
}
},
};
function mcpConfig(server: McpServer | null): string {
const servers = server ? { [MCP_SERVER_NAME]: server } : {};
return `${JSON.stringify({ mcpServers: servers }, null, 2)}\n`;
}
function readSettings(): Settings | null {
try {
const parsed = JSON.parse(readFileSync(settingsPath, 'utf8')) as unknown;
return parsed && typeof parsed === 'object' ? (parsed as Settings) : null;
} catch {
return null;
}
}
function list(value: unknown): string[] {
return Array.isArray(value) ? value.filter((rule): rule is string => typeof rule === 'string') : [];
}
function lastFrame(stdout: string): Frame | null {
for (const line of stdout.split('\n').reverse()) {
const frame = parseJsonLine<Frame>(line.trim());
if (frame) return frame;
}
return null;
}
/**
* How a tool step appears on the timeline, or null for one the timeline already shows: a call to
* Browsentic's own server, which the daemon draws itself, and the files Antigravity opens to make one.
*/
function shownAs(step: StepUpdate): string | null {
const name = step.tool_name ?? step.tool_info?.name;
const parameters = step.tool_info?.parameters;
if (!name) return null;
if (name === MCP_CALL) {
const server = parameters?.ServerName;
if (server === MCP_SERVER_NAME) return null;
return server ? `${server}:${parameters?.ToolName ?? name}` : name;
}
if (parameters?.AbsolutePath && CALL_PLUMBING.test(parameters.AbsolutePath)) return null;
return name;
}
const outcomeOf = (state: string | undefined): 'running' | 'ok' | 'failed' =>
/^done$/i.test(state ?? '') ? 'ok' : /error|fail|cancel/i.test(state ?? '') ? 'failed' : 'running';
/** `agy models` prints one `id<TAB>label` line per model, and exits 1 when signed out. */
function listedModels({ stdout, code }: Listing): string[] | null {
if (code !== 0) return null;
return stdout.split('\n').flatMap((line) => {
const [id, label] = line.split('\t');
return label !== undefined && id.trim() ? [id.trim()] : [];
});
}