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.

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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) => {