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
perf(mcp): list only the tools a caller could use, so a run without Live tool, a map or a pick stops carrying their schemas
Shahriar7e559105c4c2
diff --git a/src/daemon/agent/service.ts b/src/daemon/agent/service.tsindex 748aaf1..404bed3 100644--- a/src/daemon/agent/service.ts+++ b/src/daemon/agent/service.ts@@ -116,6 +116,19 @@ export class AgentSession {}}+ /**+ * What a run's tool list should hold. A tool the run would only be refused is left+ * out: its schema is re-sent on every turn, and listing it invites the call.+ */+ offerFor(runId: string): { withheld: string[]; reserved: string[] } | null {+ const run = this.runs.get(runId);+ if (!run) return null;+ return {+ withheld: run.liveTools ? [] : [INJECT_ACTION, RUN_CODE_ACTION],+ reserved: [...(run.map ? [SAVE_SITE_MAP_ACTION] : []), ...(run.focusShot ? [FOCUS_SHOT_ACTION] : [])],+ };+ }+async invokeForRun(runId: string, action: string, input?: unknown): Promise<ActionResult> {const run = this.runs.get(runId);if (!run) {diff --git a/src/daemon/control.ts b/src/daemon/control.tsindex 13c441a..471ceee 100644--- a/src/daemon/control.ts+++ b/src/daemon/control.ts@@ -22,7 +22,7 @@ export interface SessionSummary {}export type ControlRequest =- | { id: string; op: 'describe' }+ | { id: string; op: 'describe'; runId?: string }| { id: string; op: 'status' }| { id: string; op: 'invoke'; action: string; input?: unknown; runId?: string }| { id: string; op: 'pair' }@@ -31,7 +31,7 @@ export type ControlRequest =| { id: string; op: 'agent'; set?: AgentKind; grant?: AgentKind };export type ControlMessage =- | { id: string; op: 'describe'; tools: ToolDescriptor[] }+ | { id: string; op: 'describe'; tools: ToolDescriptor[]; reserved?: string[] }| { id: string; op: 'status'; status: BridgeStatus }| { id: string; op: 'invoke'; result: ActionResult }| { id: string; op: 'pair'; code: string; expiresAt: number }@@ -40,8 +40,14 @@ export type ControlMessage =| { id: string; op: 'agent'; state: AgentState }| { event: 'manifest-changed' };+export interface Described {+ tools: ToolDescriptor[];+ /** Reserved actions this caller may be offered. Absent when the daemon predates the field. */+ reserved?: string[];+}+export interface Bridge {- describe(): Promise<ToolDescriptor[]>;+ describe(): Promise<Described>;invoke(action: string, input?: unknown): Promise<ActionResult>;status(): Promise<BridgeStatus>;onManifestChanged(listener: () => void): void;diff --git a/src/daemon/daemon.ts b/src/daemon/daemon.tsindex 38df494..d7e27d9 100644--- a/src/daemon/daemon.ts+++ b/src/daemon/daemon.ts@@ -52,10 +52,12 @@ import { agentState, grantRunner } from './agent/runners';import { deleteSiteMap, deleteSkill, saveSkill } from './agent/skill-store';import { loadSkills } from './agent/skills';import { commitStaging, discardStaging } from './agent/site-map-store';-import type { Bridge, BridgeStatus, ControlMessage, ControlRequest, SessionSummary } from './control';+import type { Bridge, BridgeStatus, ControlMessage, ControlRequest, Described, SessionSummary } from './control';import { ExtensionLink } from './extension-link';import {ANYWHERE,+ INJECT_ACTION,+ RUN_CODE_ACTION,blocked,decide,describe as describeDecision,@@ -499,6 +501,20 @@ export async function startDaemon({ version, idleExit = true }: DaemonOptions):broadcast({ event: 'manifest-changed' });}+ function describeFor(runId?: string): Described {+ const offer = runId ? agent?.offerFor(runId) : null;+ if (offer) return { tools: tools.filter(({ name }) => !offer.withheld.includes(name)), reserved: offer.reserved };++ const config = readAgentConfig();+ const policy = policyFrom(config.guardrails, config.requireApproval);+ const denied = (action: string) =>+ decide({ action, input: {}, caller: 'external', scope: ANYWHERE }, policy).effect === 'deny';+ return {+ tools: tools.filter(({ name }) => !((name === INJECT_ACTION || name === RUN_CODE_ACTION) && denied(name))),+ reserved: [],+ };+ }+function acceptControl(ws: WebSocket): void {const client = `c${++controlSeq}`;controls.add(ws);@@ -510,7 +526,7 @@ export async function startDaemon({ version, idleExit = true }: DaemonOptions):} catch {return log('dropped unparseable control frame');}- if (request.op === 'describe') return send(ws, { id: request.id, op: 'describe', tools });+ if (request.op === 'describe') return send(ws, { id: request.id, op: 'describe', ...describeFor(request.runId) });if (request.op === 'status') return send(ws, { id: request.id, op: 'status', status: statusNow() });if (request.op === 'invoke') {let result: ActionResult;@@ -679,7 +695,7 @@ export async function startDaemon({ version, idleExit = true }: DaemonOptions):return {port,- describe: async () => tools,+ describe: async () => describeFor(),invoke,status: async () => statusNow(),onManifestChanged: (listener) => manifestListeners.add(listener),diff --git a/src/daemon/remote-bridge.test.ts b/src/daemon/remote-bridge.test.tsindex 543e2a7..fe105d7 100644--- a/src/daemon/remote-bridge.test.ts+++ b/src/daemon/remote-bridge.test.ts@@ -62,8 +62,9 @@ describe('connecting to the daemon', () => {describe('asking the daemon', () => {test('the tools it describes', async () => {- answer = ({ id }) => ({ id, op: 'describe', tools: [{ name: 'page.getPageInfo', description: 'Read the page', inputSchema: {} }] });- expect(await bridge.describe()).toEqual([{ name: 'page.getPageInfo', description: 'Read the page', inputSchema: {} }]);+ const tools = [{ name: 'page.getPageInfo', description: 'Read the page', inputSchema: {} }];+ answer = ({ id }) => ({ id, op: 'describe', tools, reserved: ['browsentic.focusShot'] });+ expect(await bridge.describe()).toEqual({ tools, reserved: ['browsentic.focusShot'] });});test('an action, stamped with the run it belongs to', async () => {@@ -163,7 +164,7 @@ describe('when the daemon does not answer', () => {test('lists come back empty and counts as zero', async () => {expect([await giveUp(() => bridge.describe()), await giveUp(() => bridge.sessions()), await giveUp(() => bridge.revoke())]).toEqual([- [60_000, []],+ [60_000, { tools: [] }],[60_000, []],[60_000, 0],]);@@ -174,7 +175,7 @@ describe('when the daemon does not answer', () => {await vi.waitFor(() => expect(daemonSide.readyState).toBe(daemonSide.CLOSED));expect([await bridge.invoke('page.getPageInfo'), await bridge.describe(), received]).toEqual([{ ok: false, error: { code: 'DAEMON_UNREACHABLE', message: 'The Browsentic daemon did not respond' } },- [],+ { tools: [] },[],]);});diff --git a/src/daemon/remote-bridge.ts b/src/daemon/remote-bridge.tsindex 959704e..49c3a58 100644--- a/src/daemon/remote-bridge.ts+++ b/src/daemon/remote-bridge.ts@@ -4,10 +4,9 @@ import { awaitMonitor } from '@/lib/actions/page/await-monitor';import { PICK_DEFAULT_TIMEOUT_MS, pickElement } from '@/lib/actions/page/pick-element';import { startMonitor } from '@/lib/actions/page/start-monitor';import { failure, type ActionResult } from '@/lib/actions/protocol';-import type { ToolDescriptor } from '@/lib/actions/manifest';import type { AgentKind, AgentState } from '@/lib/agents/catalog';import { AWAIT_DEFAULT_TIMEOUT_MS } from '@/lib/monitor/events';-import type { Bridge, BridgeStatus, ControlMessage, ControlRequest, SessionSummary } from './control';+import type { Bridge, BridgeStatus, ControlMessage, ControlRequest, Described, SessionSummary } from './control';const REQUEST_TIMEOUT_MS = 60_000;@@ -32,9 +31,9 @@ export class RemoteBridge implements Bridge {});}- async describe(): Promise<ToolDescriptor[]> {- const reply = await this.request({ id: randomUUID(), op: 'describe' });- return reply && 'tools' in reply ? reply.tools : [];+ async describe(): Promise<Described> {+ const reply = await this.request({ id: randomUUID(), op: 'describe', runId: this.runId });+ return reply && 'tools' in reply ? { tools: reply.tools, reserved: reply.reserved } : { tools: [] };}async invoke(action: string, input?: unknown): Promise<ActionResult> {diff --git a/src/daemon/server.test.ts b/src/daemon/server.test.tsindex a678c94..e08505c 100644--- a/src/daemon/server.test.ts+++ b/src/daemon/server.test.ts@@ -19,12 +19,12 @@ const PNG = 'data:image/png;base64,iVBORw0KGgo=';type Answer = (action: string, input: unknown) => ActionResult;/** A bridge that answers each action from a table, and remembers what it was asked. */-function fakeBridge(answers: Record<string, ActionResult> | Answer = {}, status: Partial<BridgeStatus> = {}, tools: ToolDescriptor[] = describeActions()) {+function fakeBridge(answers: Record<string, ActionResult> | Answer = {}, status: Partial<BridgeStatus> = {}, tools: ToolDescriptor[] = describeActions(), reserved?: string[]) {const asked: [string, unknown][] = [];const listeners: (() => void)[] = [];const answer: Answer = typeof answers === 'function' ? answers : (action) => answers[action] ?? failure('UNKNOWN_ACTION', action);const bridge: Bridge = {- describe: async () => tools,+ describe: async () => ({ tools, reserved }),invoke: async (action, input) => {asked.push([action, input]);return answer(action, input);@@ -71,7 +71,16 @@ describe('the tool list', () => {]);});- test("an agent run is also offered the site-map report and the picked element's screenshot", async () => {+ test('a reserved tool is listed only when the daemon offers it to this caller', async () => {+ const offered = (reserved: string[]) => fakeBridge({}, {}, describeActions(), reserved).bridge;+ const names = async (bridge: Bridge) => (await (await connect(bridge, { agentRun: true })).listTools()).tools.slice(-2).map((tool) => tool.name);+ expect([await names(offered([FOCUS_SHOT_ACTION])), await names(offered([]))]).toEqual([+ ['browsentic_status', toolNameFor(FOCUS_SHOT_ACTION)],+ [toolNameFor(describeActions().at(-1)!.name), 'browsentic_status'],+ ]);+ });++ test('a daemon too old to say what it offers leaves an agent run with both reserved tools', async () => {const { tools } = await (await connect(fakeBridge().bridge, { agentRun: true })).listTools();expect(tools.slice(-3).map((tool) => tool.name)).toEqual(['browsentic_status', toolNameFor(SAVE_SITE_MAP_ACTION), toolNameFor(FOCUS_SHOT_ACTION)]);});diff --git a/src/daemon/server.ts b/src/daemon/server.tsindex 3cfb9c3..a97c00c 100644--- a/src/daemon/server.ts+++ b/src/daemon/server.ts@@ -116,6 +116,11 @@ const SAVE_SITE_MAP_TOOL = {},};+const RESERVED_TOOLS = [+ { action: SAVE_SITE_MAP_ACTION, descriptor: SAVE_SITE_MAP_TOOL },+ { action: FOCUS_SHOT_ACTION, descriptor: FOCUS_SHOT_TOOL },+];+export function createMcpServer(bridge: Bridge, version: string, opts: { agentRun?: boolean } = {}): Server {// Page text is marked as data on the way out, for every client — the system prompt// that says so only reaches Browsentic's own runs. The tag is per-process so a page@@ -142,7 +147,8 @@ export function createMcpServer(bridge: Bridge, version: string, opts: { agentRu);server.setRequestHandler(ListToolsRequestSchema, async () => {- const actions = await bridge.describe();+ const { tools: actions, reserved = opts.agentRun ? RESERVED_TOOLS.map((tool) => tool.action) : [] } =+ await bridge.describe();assertToolNamesRoundTrip([...actions.map((action) => action.name), ...RESERVED_ACTIONS]);return {tools: [@@ -157,7 +163,7 @@ export function createMcpServer(bridge: Bridge, version: string, opts: { agentRu'Report whether the Browsentic browser extension is connected, its version, and the active tab. Use this first if a page tool fails.',inputSchema: { type: 'object' as const, properties: {}, additionalProperties: false },},- ...(opts.agentRun ? [SAVE_SITE_MAP_TOOL, FOCUS_SHOT_TOOL] : []),+ ...RESERVED_TOOLS.filter((tool) => reserved.includes(tool.action)).map((tool) => tool.descriptor),],};});diff --git a/src/daemon/test/startup.test.ts b/src/daemon/test/startup.test.tsindex 4345eb8..d37f713 100644--- a/src/daemon/test/startup.test.ts+++ b/src/daemon/test/startup.test.ts@@ -28,6 +28,11 @@ describe('a daemon started in the sandbox', () => {expect(await response.json()).toEqual({ ok: true, pid: process.pid, version: '0.0.0-test', connected: false });});+ test('does not list the page-code tools to a caller its policy would only refuse', async () => {+ const names = (await daemon.describe()).tools.map((tool) => tool.name);+ expect([names.includes('page.getPageInfo'), names.includes('page.injectCode'), names.includes('page.runCode')]).toEqual([true, false, false]);+ });+// fetch() will not send a Host of the caller's choosing, and a rebound page's Host is the whole point.test('turns away a host that is not loopback', async () => {const status = await new Promise((resolve, reject) => {