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
fix(agent): browsentic_use takes a tool by the name the agent's CLI shows it under, a Codex thread begun on the phone keeps a group's withheld tools in that group's namespace so exec names them the same on every turn, and the docs say which Codex runs leave the less common tools off and that a guide opens by its group's name
Shahriarae2204594138
diff --git a/docs/guide/features/page-actions.md b/docs/guide/features/page-actions.mdindex 454ed36..036712c 100644--- a/docs/guide/features/page-actions.md+++ b/docs/guide/features/page-actions.md@@ -4,11 +4,11 @@ The 52 page tools the agent uses to read, click, type, move between tabs and scrnot name them in an instruction, since the agent picks the tool, but knowing what exists tells youwhat is worth asking for.-On Claude Code, Codex, OpenCode and Mistral Vibe, the less common ones (captchas, theming,-diagnostics, monitors and timers, downloads, dragging) stay out of the agent's tool list until a-page calls for them, because those agents would otherwise send the model every tool's description-on every turn. The agent opens their guide, or Codex searches for them, when it needs one, and they-then work exactly as the others do.+On Claude Code, OpenCode, Mistral Vibe and Codex (unless it runs through `codex exec`), the less+common ones (captchas, theming, diagnostics, monitors and timers, downloads, dragging) stay out of+the agent's tool list until a page calls for them, because those agents would otherwise send the+model every tool's description on every turn. The agent opens their guide, or Codex searches for+them, when it needs one, and they then work exactly as the others do.Every parameter is in [reference/tools.md](../../reference/tools.md).diff --git a/docs/internals/agent-runs.md b/docs/internals/agent-runs.mdindex 72d7a4a..9def1d1 100644--- a/docs/internals/agent-runs.md+++ b/docs/internals/agent-runs.md@@ -126,10 +126,10 @@ with the delivery, and the tool host leaves those off the list and adds `browsen`browsentic_openSkill`, whose description and the server's instructions carry one line per group,and the guide it opens says to call them through `browsentic_use`. That call reaches`invokeForRun()` with the action itself, so its approval, guardrails, phone gate, step in the panel-and rendered result are the ones the tool's own call would get. The set depends only on the runner,-the browser's actions and the phone, never on the message, so a conversation's list stays the same-from one turn to the next. Vibe and OpenCode are not granted the grouped tools by name, since they-never see them.+and rendered result are the ones the tool's own call would get. The set depends only on the runner+and the browser's actions, so a conversation's list stays the same from one turn to the next; a+message on the phone withholds the grouped tools the phone lacks, as it withholds every other tool+it lacks. Vibe and OpenCode are not granted the grouped tools by name, since they never see them.Codex held over stdin answers `namespaced`: the tool host hands its runner each group apart, and`thread/start` declares every one as a namespace of deferred tools, named after the group and@@ -239,7 +239,8 @@ runner ──initialize {experimentalApi}──────────► app-slists what the run is offered now, each group goes in a namespace of its own (see[Runners](#runners)), and what it withholds (the page-code tools, until the user turns Live toolon) goes in a `browsentic` namespace, all with `deferLoading`, which Codex offers only through its- search. `Described.withheld` carries those from the daemon. A call to one while it is+ search. A grouped tool withheld on the phone stays in its group's namespace, so `exec` names it+ the same on every turn. `Described.withheld` carries those from the daemon. A call to one while it isstill withheld is refused by `invokeForRun()` as `LIVE_TOOLS_OFF`, as on any other runner.- **Only the run's own thread speaks.** A code-mode model's sub-agents run on threads of their own;their tool calls are answered, their words are not forwarded.diff --git a/docs/reference/tools.md b/docs/reference/tools.mdindex c3b26d6..2fd94f1 100644--- a/docs/reference/tools.md+++ b/docs/reference/tools.md@@ -81,7 +81,7 @@ only the tools this caller is offered and names the rest; one with nothing to of| Parameter | Type | Default | Purpose || --- | --- | --- | --- |-| `name` | string | required | The guide to open. The name of its skill (`page-theming`) or of one of its tools (`page_applyTheme`) opens it too |+| `name` | string | required | The guide to open, one of the six above |### browsentic_use@@ -96,7 +96,7 @@ this one.| Parameter | Type | Default | Purpose || --- | --- | --- | --- |-| `action` | string | required | The tool to run: `page_dragElement`, `page.dragElement` and `dragElement` all name it. Anything that is not a page tool is answered with `UNKNOWN_ACTION` and the list of guides |+| `action` | string | required | The tool to run: `page_dragElement`, `page.dragElement`, `dragElement` and the name an agent's CLI shows, such as `mcp__browsentic__page_dragElement`, all name it. Anything that is not a page tool is answered with `UNKNOWN_ACTION` and the list of guides || `input` | object | `{}` | Its parameters, as its own schema has them. A JSON string of the object is taken too. Input the tool refuses comes back as `INVALID_INPUT` with its schema |---diff --git a/src/daemon/server.test.ts b/src/daemon/server.test.tsindex 09f9daf..16b729b 100644--- a/src/daemon/server.test.ts+++ b/src/daemon/server.test.ts@@ -11,7 +11,7 @@ import { FOCUS_SHOT_ACTION, SAVE_SITE_MAP_ACTION } from '@/lib/actions/reserved'import { toolNameFor } from '@/lib/actions/tool-names';import { configPath } from './agent/config';import type { Bridge, BridgeStatus, Described } from './control';-import { FENCE_NOTE, IMAGE_NOTE, policyFrom } from './guardrails';+import { FENCE_NOTE, IMAGE_NOTE, INJECT_ACTION, policyFrom } from './guardrails';import { stateDir } from './lockfile';import { grouped } from './tool-groups';import { createMcpServer } from './server';@@ -161,6 +161,23 @@ describe('the tool list', () => {});});+ test('a namespaced run keeps a grouped tool it withholds, as on the phone, in its own group, so exec names it alike on every turn', async () => {+ const off = ['page.findCaptcha', 'page.solveCaptcha', INJECT_ACTION];+ const all = describeActions();+ const offer = {+ reserved: [],+ withheld: all.filter((tool) => off.includes(tool.name)),+ onDemand: GROUPED.filter((name) => !off.includes(name)),+ delivery: 'namespaced' as const,+ };+ const bridge = fakeBridge({}, {}, all.filter((tool) => !off.includes(tool.name)), offer).bridge;+ const { withheld, groups } = await toolHost(bridge, { agentRun: true, namespaces: true, policy: policyFrom(undefined), tag: 'tag' }).list();+ expect({+ withheld: withheld.map((tool) => tool.name),+ captcha: groups.find((group) => group.name === 'captcha')?.tools.map((tool) => tool.name),+ }).toEqual({ withheld: [toolNameFor(INJECT_ACTION)], captcha: ['page_findCaptcha', 'page_solveCaptcha'] });+ });+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);@@ -475,6 +492,15 @@ describe('a call through browsentic_use', () => {]);});+ test('takes the action as an agent CLI shows its tool', async () => {+ const { bridge, asked } = fakeBridge({ 'page.dragElement': success({ dragged: true }) });+ const client = await connect(bridge);+ for (const action of ['mcp__browsentic__page_dragElement', 'browsentic__page_dragElement', 'browsentic_page_dragElement']) {+ await call(client, 'browsentic_use', { action, input: { from: 1 } });+ }+ expect(asked.map(([action]) => action)).toEqual(['page.dragElement', 'page.dragElement', 'page.dragElement']);+ });+test('takes the action as its tool, its action or bare, and the input as an object, a JSON string or flat', async () => {const { bridge, asked } = fakeBridge({ 'page.solveCaptcha': success({ state: 'solved' }) });const client = await connect(bridge);diff --git a/src/daemon/tool-groups.ts b/src/daemon/tool-groups.tsindex c6fde5a..41124c8 100644--- a/src/daemon/tool-groups.ts+++ b/src/daemon/tool-groups.ts@@ -22,9 +22,15 @@ export const GROUPS_NOTE =export const grouped = (action: string) => actions.get(action)?.group !== undefined;-/** A page action the registry knows, named as an action, as its tool, or bare: page.dragElement, page_dragElement, dragElement. */+/**+ * A page action the registry knows, named as an action, as its tool, bare, or as an agent CLI shows+ * its tool: page.dragElement, page_dragElement, dragElement, mcp__browsentic__page_dragElement.+ */export function pageActionNamed(name: string): string | undefined {- const action = `page.${name.trim().replace(/^page[._]/, '')}`;+ const action = `page.${name+ .trim()+ .replace(/^(?:mcp__)?browsentic_{1,2}/, '')+ .replace(/^page[._]/, '')}`;return actions.has(action) ? action : undefined;}diff --git a/src/daemon/tool-host.ts b/src/daemon/tool-host.tsindex 5eb7cc9..75a9906 100644--- a/src/daemon/tool-host.ts+++ b/src/daemon/tool-host.ts@@ -6,7 +6,7 @@ import { actionNameFor, assertToolNamesRoundTrip, OPEN_SKILL_TOOL, STATUS_TOOL,import { loadSkills } from './agent/skills';import type { Bridge, Described } from './control';import { IMAGE_NOTE, fence, sealSecrets, shouldFence, type Policy } from './guardrails';-import { GROUP_INDEX, groupGuide, groupNamed, groupsOf, pageActionNamed } from './tool-groups';+import { GROUP_INDEX, groupGuide, grouped, groupNamed, groupsOf, pageActionNamed } from './tool-groups';const EXTRACT_ACTION = 'page.extractText';@@ -234,6 +234,7 @@ export function toolHost(bridge: Bridge, { agentRun = false, namespaces = false,} = await offer();assertToolNamesRoundTrip([...actions.map((action) => action.name), ...RESERVED_ACTIONS]);const namespaced = delivery === 'namespaced';+ const inItsGroup = (tool: ToolDescriptor) => namespaced && grouped(tool.name);return {tools: [...actions.filter((action) => !onDemand.includes(action.name)).map(listed),@@ -247,9 +248,12 @@ export function toolHost(bridge: Bridge, { agentRun = false, namespaces = false,...(onDemand.length && !namespaced ? [USE] : []),...RESERVED_TOOLS.filter((tool) => reserved.includes(tool.action)).map((tool) => tool.descriptor),],- withheld: withheld.map(listed),+ withheld: withheld.filter((tool) => !inItsGroup(tool)).map(listed),groups: namespaced- ? groupsOf(actions.filter((action) => onDemand.includes(action.name))).map((group) => ({ ...group, tools: group.tools.map(listed) }))+ ? groupsOf([...actions.filter((action) => onDemand.includes(action.name)), ...withheld.filter(inItsGroup)]).map((group) => ({+ ...group,+ tools: group.tools.map(listed),+ })): [],};},