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
feat(agent): Codex held over stdin declares each tool group as a deferred namespace that its own tool_search loads, so a Codex run lists only the core tools from its first request and calls the rest as its own once found
Shahriar7682286365d8
diff --git a/docs/guide/features/page-actions.md b/docs/guide/features/page-actions.mdindex d0999a3..454ed36 100644--- a/docs/guide/features/page-actions.md+++ b/docs/guide/features/page-actions.md@@ -4,10 +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, 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 send the model every tool's description on every turn. The agent opens their-guide when it needs one, and they then work exactly as the others do.+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.Every parameter is in [reference/tools.md](../../reference/tools.md).diff --git a/docs/internals/agent-runs.md b/docs/internals/agent-runs.mdindex 0094471..72d7a4a 100644--- a/docs/internals/agent-runs.md+++ b/docs/internals/agent-runs.md@@ -118,19 +118,35 @@ Codex also cuts any tool result at 10,000 tokens by default, a limit its model c`// @exec: {"max_output_tokens": 25000}`; only the prompt can ask for that, so it does. It alsoasks for page reads in pieces.-**Three CLIs send every tool they are given on every turn, so their runs list only the core.**-Claude Code (whose own `ToolSearch` is denied), Mistral Vibe and OpenCode declare-`Runner.delivery: 'on-demand'`. For their runs `offerFor` names every-[grouped action](registry.md) in `onDemand`, which the describe reply carries beside `withheld`, and-the tool host leaves those off the list and adds `browsentic_use`. The agent finds them through+**Four CLIs would send every tool they are given on every turn, so their runs list only the core.**+`Runner.delivery(settings)` says how the rest reach the model. Claude Code (whose own `ToolSearch`+is denied), Mistral Vibe and OpenCode answer `on-demand`. For their runs `offerFor` names every+[grouped action](registry.md) in `onDemand`, which the describe reply carries beside `withheld`+with the delivery, and the tool host leaves those off the list and adds `browsentic_use`. The agent finds them through`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 paneland 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 samefrom one turn to the next. Vibe and OpenCode are not granted the grouped tools by name, since they-never see them. Every other CLI is `listed`: it already keeps schemas out of the model's context-until they are looked up, and a second level of lookup would only lose the schema-checked call.+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+described by its index line. Codex leaves them out of the model's requests and gives it+`tool_search` instead, a BM25 search over the deferred tools and their namespaces; a match loads+the whole namespace into the conversation, so the tool list stays as it was, and the model then+calls the tools as its own. A code-mode model finds them in `ALL_TOOLS` and calls them inside+`exec` as `tools.<group>__<tool>`. The guide says so, and so does the line on the browser tools in+Codex's prompt. Measured against Codex 0.155.1 with a stand-in model on 16 Oct 2026, a search for+each group's name, for its tools' own names, and for a need in plain words ("make this page dark",+"remind me in ten minutes", "move the slider") found the right group first, and the first request+was about a quarter smaller. Codex 0.155.1 offers `tool_search` for deferred tools even to a model+its catalog marks `supports_search_tool: false`, so there is no per-model fallback to make.++Every other CLI is `listed`, Codex on `exec` among them, and so is a namespaced run's MCP server,+since MCP has no namespaces: each already keeps schemas out of the model's context until they are+looked up, and a second level of lookup would only lose the schema-checked call.**A CLI with limits on a tool call declares them** (`Runner.limits`), and the daemon works insidethem so the run does not have to discover them. Cursor abandons a call at 60 s (the MCP SDK's@@ -183,7 +199,7 @@ Code 2.1.283) with a stand-in model endpoint| | Claude Code | Codex (app-server, the default) | Codex (`exec`) || --- | --- | --- | --- |-| Browser tools in the model's list | the core, with the rest through `browsentic_openSkill` and `browsentic_use` | all of them, from the first request; a code-mode model gets each declared inside `exec` | deferred behind `tool_search`; a code-mode model reaches them only inside `exec`, and the prompt says so |+| Browser tools in the model's list | the core, with the rest through `browsentic_openSkill` and `browsentic_use` | the core, from the first request, with each group a namespace its `tool_search` loads; a code-mode model gets each declared inside `exec` | deferred behind `tool_search`; a code-mode model reaches them only inside `exec`, and the prompt says so || The user's own MCP servers | kept out by `--strict-mcp-config` | switched off one by one in the thread's config, from the list `config/read` gives; one that starts anyway stops the run | kept out by `--ignore-user-config`: a `-c` merges into `config.toml`, so `mcp_servers={}` cleared nothing, and keys on the user's own `browsentic` entry (an `enabled_tools` list) landed on the run's || The user's defaults | `settings.json` applies | the whole of `config.toml` except its MCP servers: model, provider, profile | the `model` and `model_reasoning_effort` at the top of `config.toml`, carried over by hand; nothing else in the file || Shell and disk | denied by name | `features.shell_tool=false` and `features.view_image=false` on its argv; `apply_patch` as on `exec` | `features.shell_tool=false` and `features.view_image=false`, which remove the tools from every model and every sub-agent; `apply_patch` has no switch and the read-only sandbox refuses its writes |@@ -220,9 +236,10 @@ runner ──initialize {experimentalApi}──────────► app-s```- **The tool list is fixed when the thread starts**, and `thread/resume` takes none. So `thread/start`- lists what the run is offered now, and what it withholds (the page-code tools, until the user- turns Live tool on) goes in a `browsentic` namespace with `deferLoading`, which Codex offers only- through its search. `Described.withheld` carries those from the daemon. A call to one while it is+ lists 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 tool+ on) 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 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/internals/registry.md b/docs/internals/registry.mdindex 9c8087d..7b50e83 100644--- a/docs/internals/registry.md+++ b/docs/internals/registry.md@@ -28,7 +28,8 @@ An action that only some tasks need also names its `group`: `captcha`, `theming``monitoring`, `downloads` or `drag`. [`src/lib/actions/groups.ts`](../../src/lib/actions/groups.ts)gives each group its line in the index and the skills that teach it, and `browsentic_openSkill`opens a group as one guide. Ungrouped actions are the core. A side-panel run on a CLI that sends-every schema on every turn lists only the core and calls the grouped ones through `browsentic_use`+every schema on every turn lists only the core, and calls the grouped ones through `browsentic_use`+or, on Codex's app-server, loads them by its own search, each group a namespace([Agent runs](agent-runs.md#runners)). The group never leaves the daemon'sown copy of the registry, so it changes neither the descriptors nor the manifest hash.diff --git a/docs/reference/tools.md b/docs/reference/tools.mdindex cd65404..c3b26d6 100644--- a/docs/reference/tools.md+++ b/docs/reference/tools.md@@ -90,7 +90,9 @@ OpenCode or Mistral Vibe lists only the core tools, because those CLIs send thetool they are given on every turn. The tools of the guides above are left off its list, and theagent calls them through `browsentic_use` once a guide, a skill or a result has named one. The callgoes the way the tool's own call would: the same approvals, guardrails, blocked sites and steps in-the panel, and the same result. Every other caller lists every tool and is not offered this one.+the panel, and the same result. A run on Codex's app-server gets each guide's tools as a namespace+that Codex's own `tool_search` loads, and every other caller lists every tool. Neither is offered+this one.| Parameter | Type | Default | Purpose || --- | --- | --- | --- |diff --git a/src/daemon/agent/runner.ts b/src/daemon/agent/runner.tsindex 5b827ac..332005d 100644--- a/src/daemon/agent/runner.ts+++ b/src/daemon/agent/runner.ts@@ -69,7 +69,7 @@ function inProcessTools(runId: string, config: AgentConfig): { open: () => Promireturn RemoteBridge.connect(lock.port, lock.token, runId);};return {- open: () => (host ??= (bridge = connect()).then((connected) => toolHost(connected, { agentRun: true, policy: policyFrom(config.guardrails), tag: fenceTag() }))),+ open: () => (host ??= (bridge = connect()).then((connected) => toolHost(connected, { agentRun: true, namespaces: true, policy: policyFrom(config.guardrails), tag: fenceTag() }))),close: () => void bridge?.then((connected) => connected.close()).catch(() => {}),};}diff --git a/src/daemon/agent/runners/claude.ts b/src/daemon/agent/runners/claude.tsindex bca9294..22afe10 100644--- a/src/daemon/agent/runners/claude.ts+++ b/src/daemon/agent/runners/claude.ts@@ -95,7 +95,7 @@ export const claudeRunner: Runner = {// resume, whatever --append-system-prompt says (`--system-prompt-snapshot`, on by default in 2.1.283).keepsFirstPrompt: true,// ToolSearch is denied, so every listed schema rides along on every turn.- delivery: 'on-demand',+ delivery: () => 'on-demand',workspace: () => stateDir,diff --git a/src/daemon/agent/runners/codex-app-server.test.ts b/src/daemon/agent/runners/codex-app-server.test.tsindex f61c7a1..dd079f1 100644--- a/src/daemon/agent/runners/codex-app-server.test.ts+++ b/src/daemon/agent/runners/codex-app-server.test.ts@@ -15,6 +15,7 @@ const host = () => {{ name: 'page_shot', description: 'Shot', inputSchema: schema },],withheld: [{ name: 'page_runCode', description: 'Run page code', inputSchema: schema }],+ groups: [{ name: 'drag', description: 'drag: drag one thing onto another', tools: [{ name: 'page_dragElement', description: 'Drag', inputSchema: schema }] }],})),call: vi.fn(async (name: string) =>name === 'page_shot'@@ -62,7 +63,7 @@ const response = (id: number) => recorded.find((line) => JSON.parse(line).id ===const sent = (written: Record<string, unknown>[], method: string) => written.find((message) => message.method === method);describe('the handshake', () => {- test("starts a thread with the browser tools as its own, the withheld ones out of sight, and every server of the user's switched off", async () => {+ test("starts a thread with the browser tools as its own, each group and the withheld ones out of sight, and every server of the user's switched off", async () => {const { written, feed } = hold({ bin: 'codex-handshake' });expect(written[0]).toMatchObject({ id: 1, method: 'initialize', params: { capabilities: { experimentalApi: true } } });await feed(response(1), response(2));@@ -83,6 +84,12 @@ describe('the handshake', () => {tools: [{ type: 'function', name: 'page_echo', description: 'Echo', inputSchema: schema, deferLoading: false },{ type: 'function', name: 'page_shot', description: 'Shot', inputSchema: schema, deferLoading: false },+ {+ type: 'namespace',+ name: 'drag',+ description: 'drag: drag one thing onto another',+ tools: [{ type: 'function', name: 'page_dragElement', description: 'Drag', inputSchema: schema, deferLoading: true }],+ },{type: 'namespace',name: 'browsentic',@@ -140,6 +147,17 @@ describe('a recorded turn', () => {});});+ test('a tool its search loaded from a group is answered by its name, with no row for the search itself', async () => {+ const { written, tools, calls, feed } = hold({ bin: 'codex-searched' });+ await feed(...transcript('codex', '0.155.1-tool-search.jsonl'));+ expect({+ called: vi.mocked(tools.call).mock.calls.map(([name]) => name),+ answered: written.filter((message) => 'result' in message && !('method' in message)).map((message) => message.id),+ rows: calls.filter(([signal]) => signal === 'tool' || signal === 'toolResult'),+ end: calls.at(-1),+ }).toEqual({ called: ['page_solveCaptcha'], answered: [0], rows: [], end: ['done', 'end_turn'] });+ });+test('a message that came whole, without deltas, is said once when it completes', async () => {const { calls, feed } = hold({ bin: 'codex-whole' });await feed(response(1), response(2), response(3));diff --git a/src/daemon/agent/runners/codex-app-server.ts b/src/daemon/agent/runners/codex-app-server.tsindex bf6e6e3..b6b9cbb 100644--- a/src/daemon/agent/runners/codex-app-server.ts+++ b/src/daemon/agent/runners/codex-app-server.ts@@ -1,4 +1,4 @@-import type { ListedTool, ToolReply } from '../../tool-host';+import type { ListedGroup, ListedTool, ToolReply } from '../../tool-host';import type { AgentSettings } from '../config';import { CONVERSATION_REFUSED, type Conversation, type ConversationIO, type Plan, type StreamContext, type StreamSink } from './types';@@ -84,14 +84,18 @@ export function appServerTurn(context: StreamContext, turn: AppServerTurn): Convcontext.tools().then((host) => host.list())- .then(({ tools, withheld }) =>+ .then(({ tools, withheld, groups }) =>io.write({jsonrpc: '2.0',id: ASK.thread,method: 'thread/start',params: {...threadParams(disabled),- dynamicTools: [...tools.map((tool) => dynamicTool(tool, false)), ...(withheld.length ? [outOfSight(withheld)] : [])],+ dynamicTools: [+ ...tools.map((tool) => dynamicTool(tool, false)),+ ...groups.map(deferred),+ ...(withheld.length ? [deferred({ name: 'browsentic', description: WITHHELD, tools: withheld })] : []),+ ],},}),)@@ -247,11 +251,17 @@ const dynamicTool = (tool: ListedTool, deferLoading: boolean) => ({deferLoading,});-/** Codex keeps a deferred tool only inside a namespace, where the model finds it by searching. */-const outOfSight = (tools: ListedTool[]) => ({+const WITHHELD = 'Browsentic tools that answer only once the user has switched them on for a message.';++/**+ * Codex keeps a deferred tool only inside a namespace, out of the model's requests until its+ * `tool_search` matches the namespace or the tool, and then loads the whole namespace into the+ * conversation, so the tool list and its cached prefix stay as they were.+ */+const deferred = ({ name, description, tools }: ListedGroup) => ({type: 'namespace',- name: 'browsentic',- description: 'Browsentic tools that answer only once the user has switched them on for a message.',+ name,+ description,tools: tools.map((tool) => dynamicTool(tool, true)),});diff --git a/src/daemon/agent/runners/codex.ts b/src/daemon/agent/runners/codex.tsindex a1475a5..9cad48e 100644--- a/src/daemon/agent/runners/codex.ts+++ b/src/daemon/agent/runners/codex.ts@@ -32,6 +32,8 @@ const SANDBOX_CONFIG = ['-c', 'sandbox_mode="read-only"', '-c', 'approval_policy/** A Codex whose app-server turned a conversation down, so later turns go straight to `exec`. */const noConversation = new Set<string>();+const heldOverStdin = (settings: AgentSettings) => settings.transport !== 'exec' && !noConversation.has(settings.bin);+/*** The shell and the image viewer read the machine, and a run has the page for that. A code-mode* model keeps its `exec` and reaches the browser tools from inside it, and the sub-agents it can@@ -111,7 +113,7 @@ ${keepToThePage(research)}`;*/const holdingTheBrowser = (research: boolean) => `# Your browser tools in Codex-Your browsentic tools — \`page_getPageInfo\`, \`page_clickElement\` and the rest — are in your tool list. If the only way you can call a tool is \`exec\`, they are there as \`tools.page_getPageInfo({ ... })\` and the like; a result that holds a picture comes back as text whose first line is a \`data:image/\` URL, and passing that line to \`image()\` is how you see it.+Your browsentic tools — \`page_getPageInfo\`, \`page_clickElement\` and the rest — are in your tool list. If the only way you can call a tool is \`exec\`, they are there as \`tools.page_getPageInfo({ ... })\` and the like; a result that holds a picture comes back as text whose first line is a \`data:image/\` URL, and passing that line to \`image()\` is how you see it. The less common ones, under the guides \`browsentic_openSkill\` names, load on demand: \`tool_search\` for the guide's name loads them, and inside \`exec\` they are \`tools.<guide>__<tool>\`, such as \`tools.captcha__page_solveCaptcha\`.${keepToThePage(research)}`;@@ -173,6 +175,8 @@ export const codexRunner: Runner = {efforts: ['low', 'medium', 'high', 'xhigh'],opens: ['text', 'image'],keepsFirstPrompt: true,+ // `exec` defers every MCP tool behind Codex's own search already.+ delivery: (settings) => (heldOverStdin(settings) ? 'namespaced' : 'listed'),workspace: () => stateDir,@@ -191,7 +195,7 @@ export const codexRunner: Runner = {*/converse(context: StreamContext): Conversation | null {const { settings, research } = context;- if (settings.transport === 'exec' || noConversation.has(settings.bin)) return null;+ if (!heldOverStdin(settings)) return null;return appServerTurn(context, {plan: {cwd: this.workspace('run'),diff --git a/src/daemon/agent/runners/drive.test.ts b/src/daemon/agent/runners/drive.test.tsindex b70deeb..6d4e9b4 100644--- a/src/daemon/agent/runners/drive.test.ts+++ b/src/daemon/agent/runners/drive.test.ts@@ -38,7 +38,7 @@ const printing = (...lines: unknown[]) =>const node = { bin: process.execPath };/** Browser tools with nothing in them, for a runner that asks for its own. */-const noTools = async () => ({ list: async () => ({ tools: [], withheld: [] }), call: async () => ({ content: [] }) });+const noTools = async () => ({ list: async () => ({ tools: [], withheld: [], groups: [] }), call: async () => ({ content: [] }) });const run = async (runner: Runner,diff --git a/src/daemon/agent/runners/fixtures/README.md b/src/daemon/agent/runners/fixtures/README.mdindex 4e61a95..3f79326 100644--- a/src/daemon/agent/runners/fixtures/README.md+++ b/src/daemon/agent/runners/fixtures/README.md@@ -10,7 +10,7 @@ What each agent CLI printed on stdout, one event per line, for the reader testscommands emptied. OpenCode's were recorded through the runner's own plan with the model providerreplaced by a local stand-in, so the model's words are scripted and its URL is 127.0.0.1 — all but`free-tier`, which the real Zen endpoint answered and which lost only its `cf-ray` and- `cf-placement` headers; paths became `/Users/you`. Codex's `web-search`, `shell` and `two-calls`+ `cf-placement` headers; paths became `/Users/you`. Codex's `web-search`, `shell`, `two-calls` and `tool-search`and Claude Code's `mcp-failed` were recorded the same way, each saying so in its first line.- `<case>.hand-written.jsonl` was written from the reader code, for streams a contained run cannotproduce or a CLI that was not installed. Its first line says so.diff --git a/src/daemon/agent/runners/fixtures/codex/0.155.1-tool-search.jsonl b/src/daemon/agent/runners/fixtures/codex/0.155.1-tool-search.jsonlnew file mode 100644index 0000000..f900600--- /dev/null+++ b/src/daemon/agent/runners/fixtures/codex/0.155.1-tool-search.jsonl@@ -0,0 +1,23 @@+# Recorded from codex 0.155.1's app-server with a local stand-in for the model, which searched with tool_search for "verify you are human" and then called page_solveCaptcha in the "captcha" namespace its search had loaded, before answering. The machine's name, installation id and paths are replaced.+{"id":1,"result":{"userAgent":"browsentic/0.155.1 (Mac OS 26.6.2; arm64) unknown (browsentic; 0)","codexHome":"/Users/you/.browsentic/homes/rec","platformFamily":"unix","platformOs":"macos"}}+{"method":"remoteControl/status/changed","params":{"status":"disabled","serverName":"your-mac","installationId":"00000000-0000-0000-0000-000000000000","environmentId":null},"emittedAtMs":1792107247883}+{"id":3,"result":{"thread":{"id":"01a141ea-7922-74a1-98bc-13ed5d3e2ef1","environments":[{"environmentId":"local","cwd":"/Users/you/.browsentic","runtimeWorkspaceRoots":["/Users/you/.browsentic"]}],"extra":null,"sessionId":"01a141ea-7922-74a1-98bc-13ed5d3e2ef1","forkedFromId":null,"parentThreadId":null,"preview":"","ephemeral":false,"section":null,"sectionEnteredAt":null,"projectId":null,"historyMode":"paginated","modelProvider":"mock","model":"gpt-5.5","reasoningEffort":null,"createdAt":1792107247,"updatedAt":1792107247,"recencyAt":1792107247,"status":{"type":"idle"},"path":"/Users/you/.browsentic/homes/rec/sessions/2026/10/16/rollout-2026-10-16T01-34-07-01a141ea-7922-74a1-98bc-13ed5d3e2ef1.jsonl","cwd":"/Users/you/.browsentic","cliVersion":"0.155.1","originator":"browsentic","source":"vscode","canAcceptDirectInput":true,"threadSource":null,"agentNickname":null,"agentRole":null,"gitInfo":null,"name":null,"daybreakEnabled":null,"turns":[]},"model":"gpt-5.5","modelProvider":"mock","serviceTier":null,"cwd":"/Users/you/.browsentic","runtimeWorkspaceRoots":["/Users/you/.browsentic"],"instructionSources":[],"approvalPolicy":"never","approvalsReviewer":"user","sandbox":{"type":"readOnly","networkAccess":false},"activePermissionProfile":null,"reasoningEffort":null,"multiAgentMode":"explicitRequestOnly"}}+{"method":"thread/started","params":{"thread":{"id":"01a141ea-7922-74a1-98bc-13ed5d3e2ef1","environments":[{"environmentId":"local","cwd":"/Users/you/.browsentic","runtimeWorkspaceRoots":["/Users/you/.browsentic"]}],"extra":null,"sessionId":"01a141ea-7922-74a1-98bc-13ed5d3e2ef1","forkedFromId":null,"parentThreadId":null,"preview":"","ephemeral":false,"section":null,"sectionEnteredAt":null,"projectId":null,"historyMode":"paginated","modelProvider":"mock","model":"gpt-5.5","reasoningEffort":null,"createdAt":1792107247,"updatedAt":1792107247,"recencyAt":1792107247,"status":{"type":"idle"},"path":"/Users/you/.browsentic/homes/rec/sessions/2026/10/16/rollout-2026-10-16T01-34-07-01a141ea-7922-74a1-98bc-13ed5d3e2ef1.jsonl","cwd":"/Users/you/.browsentic","cliVersion":"0.155.1","originator":"browsentic","source":"vscode","canAcceptDirectInput":true,"threadSource":null,"agentNickname":null,"agentRole":null,"gitInfo":null,"name":null,"daybreakEnabled":null,"turns":[]}},"emittedAtMs":1792107247957}+{"id":4,"result":{"turn":{"id":"01a141ea-795a-7641-b9da-ab2277c93ffa","items":[],"itemsView":"notLoaded","status":"inProgress","error":null,"startedAt":null,"completedAt":null,"durationMs":null}}}+{"method":"thread/status/changed","params":{"threadId":"01a141ea-7922-74a1-98bc-13ed5d3e2ef1","status":{"type":"active","activeFlags":[]}},"emittedAtMs":1792107247983}+{"method":"turn/started","params":{"threadId":"01a141ea-7922-74a1-98bc-13ed5d3e2ef1","turn":{"id":"01a141ea-795a-7641-b9da-ab2277c93ffa","items":[],"itemsView":"notLoaded","status":"inProgress","error":null,"startedAt":1792107247,"completedAt":null,"durationMs":null}},"emittedAtMs":1792107247983}+{"method":"item/started","params":{"item":{"type":"userMessage","id":"01a141ea-797e-7cb3-b9f3-7c81cb397c3b","clientId":null,"content":[{"type":"text","text":"Solve the captcha.","text_elements":[]}]},"threadId":"01a141ea-7922-74a1-98bc-13ed5d3e2ef1","turnId":"01a141ea-795a-7641-b9da-ab2277c93ffa","startedAtMs":1792107247998},"emittedAtMs":1792107247998}+{"method":"item/completed","params":{"item":{"type":"userMessage","id":"01a141ea-797e-7cb3-b9f3-7c81cb397c3b","clientId":null,"content":[{"type":"text","text":"Solve the captcha.","text_elements":[]}]},"threadId":"01a141ea-7922-74a1-98bc-13ed5d3e2ef1","turnId":"01a141ea-795a-7641-b9da-ab2277c93ffa","completedAtMs":1792107247998},"emittedAtMs":1792107247999}+{"method":"thread/tokenUsage/updated","params":{"threadId":"01a141ea-7922-74a1-98bc-13ed5d3e2ef1","turnId":"01a141ea-795a-7641-b9da-ab2277c93ffa","tokenUsage":{"total":{"totalTokens":105,"inputTokens":100,"cachedInputTokens":0,"cacheWriteInputTokens":0,"outputTokens":5,"reasoningOutputTokens":0},"last":{"totalTokens":105,"inputTokens":100,"cachedInputTokens":0,"cacheWriteInputTokens":0,"outputTokens":5,"reasoningOutputTokens":0},"modelContextWindow":258400}},"emittedAtMs":1792107248013}+{"method":"account/rateLimits/updated","params":{"rateLimits":{"limitId":"codex","limitName":null,"normalModelSlug":null,"primary":null,"secondary":null,"credits":null,"individualLimit":null,"spendControlReached":null,"planType":null,"rateLimitReachedType":null}},"emittedAtMs":1792107248013}+{"method":"item/started","params":{"item":{"type":"dynamicToolCall","id":"call-1","namespace":"captcha","tool":"page_solveCaptcha","arguments":{},"status":"inProgress","contentItems":null,"success":null,"durationMs":null},"threadId":"01a141ea-7922-74a1-98bc-13ed5d3e2ef1","turnId":"01a141ea-795a-7641-b9da-ab2277c93ffa","startedAtMs":1792107248016},"emittedAtMs":1792107248017}+{"method":"item/tool/call","id":0,"params":{"threadId":"01a141ea-7922-74a1-98bc-13ed5d3e2ef1","turnId":"01a141ea-795a-7641-b9da-ab2277c93ffa","callId":"call-1","namespace":"captcha","tool":"page_solveCaptcha","arguments":{}}}+{"method":"item/completed","params":{"item":{"type":"dynamicToolCall","id":"call-1","namespace":"captcha","tool":"page_solveCaptcha","arguments":{},"status":"completed","contentItems":[{"type":"inputText","text":"answered captcha/page_solveCaptcha"}],"success":true,"durationMs":2},"threadId":"01a141ea-7922-74a1-98bc-13ed5d3e2ef1","turnId":"01a141ea-795a-7641-b9da-ab2277c93ffa","completedAtMs":1792107248019},"emittedAtMs":1792107248020}+{"method":"thread/tokenUsage/updated","params":{"threadId":"01a141ea-7922-74a1-98bc-13ed5d3e2ef1","turnId":"01a141ea-795a-7641-b9da-ab2277c93ffa","tokenUsage":{"total":{"totalTokens":210,"inputTokens":200,"cachedInputTokens":0,"cacheWriteInputTokens":0,"outputTokens":10,"reasoningOutputTokens":0},"last":{"totalTokens":105,"inputTokens":100,"cachedInputTokens":0,"cacheWriteInputTokens":0,"outputTokens":5,"reasoningOutputTokens":0},"modelContextWindow":258400}},"emittedAtMs":1792107248021}+{"method":"account/rateLimits/updated","params":{"rateLimits":{"limitId":"codex","limitName":null,"normalModelSlug":null,"primary":null,"secondary":null,"credits":null,"individualLimit":null,"spendControlReached":null,"planType":null,"rateLimitReachedType":null}},"emittedAtMs":1792107248021}+{"method":"item/started","params":{"item":{"type":"agentMessage","id":"msg_2","text":"done","phase":null,"memoryCitation":null,"delivery":null,"questions":null},"threadId":"01a141ea-7922-74a1-98bc-13ed5d3e2ef1","turnId":"01a141ea-795a-7641-b9da-ab2277c93ffa","startedAtMs":1792107248023},"emittedAtMs":1792107248023}+{"method":"item/completed","params":{"item":{"type":"agentMessage","id":"msg_2","text":"done","phase":null,"memoryCitation":null,"delivery":null,"questions":null},"threadId":"01a141ea-7922-74a1-98bc-13ed5d3e2ef1","turnId":"01a141ea-795a-7641-b9da-ab2277c93ffa","completedAtMs":1792107248023},"emittedAtMs":1792107248023}+{"method":"thread/tokenUsage/updated","params":{"threadId":"01a141ea-7922-74a1-98bc-13ed5d3e2ef1","turnId":"01a141ea-795a-7641-b9da-ab2277c93ffa","tokenUsage":{"total":{"totalTokens":315,"inputTokens":300,"cachedInputTokens":0,"cacheWriteInputTokens":0,"outputTokens":15,"reasoningOutputTokens":0},"last":{"totalTokens":105,"inputTokens":100,"cachedInputTokens":0,"cacheWriteInputTokens":0,"outputTokens":5,"reasoningOutputTokens":0},"modelContextWindow":258400}},"emittedAtMs":1792107248024}+{"method":"account/rateLimits/updated","params":{"rateLimits":{"limitId":"codex","limitName":null,"normalModelSlug":null,"primary":null,"secondary":null,"credits":null,"individualLimit":null,"spendControlReached":null,"planType":null,"rateLimitReachedType":null}},"emittedAtMs":1792107248024}+{"method":"thread/status/changed","params":{"threadId":"01a141ea-7922-74a1-98bc-13ed5d3e2ef1","status":{"type":"idle"}},"emittedAtMs":1792107248025}+{"method":"turn/completed","params":{"threadId":"01a141ea-7922-74a1-98bc-13ed5d3e2ef1","turn":{"id":"01a141ea-795a-7641-b9da-ab2277c93ffa","items":[{"type":"agentMessage","id":"msg_2","text":"done","phase":null,"memoryCitation":null,"delivery":null,"questions":null}],"itemsView":"summary","status":"completed","error":null,"startedAt":1792107247,"completedAt":1792107248,"durationMs":59}},"emittedAtMs":1792107248025}diff --git a/src/daemon/agent/runners/opencode.ts b/src/daemon/agent/runners/opencode.tsindex 6eb1de0..ee8052c 100644--- a/src/daemon/agent/runners/opencode.ts+++ b/src/daemon/agent/runners/opencode.ts@@ -74,7 +74,7 @@ export const opencodeRunner: Runner = {// Passed as --variant, whose names each model defines; a model ignores one it lacks.efforts: ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'],endsOnExit: true,- delivery: 'on-demand',+ delivery: () => 'on-demand',workspace: (mode: RunMode) => join(stateDir, 'agents', 'opencode', mode),diff --git a/src/daemon/agent/runners/types.ts b/src/daemon/agent/runners/types.tsindex ed94daf..e936b7f 100644--- a/src/daemon/agent/runners/types.ts+++ b/src/daemon/agent/runners/types.ts@@ -2,6 +2,7 @@ import type { TokenUsage } from '@/lib/actions/protocol';import type { AgentKind, AgentProblem } from '@/lib/agents/catalog';import type { FileKind } from '@/lib/files/report';import type { AgentSettings } from '../config';+import type { ToolDelivery } from '../../control';import type { ToolHost } from '../../tool-host';/** `run` drives the browser and resumes conversations; `task` is a one-shot with no browser. */@@ -33,13 +34,6 @@ export interface Plan {prepare?: string[][];}-/**- * `listed`: every tool in the run's list, for a CLI that keeps schemas out of the model's context- * until it looks one up. `on-demand`: the grouped tools are left off the list and called through- * browsentic_use, for a CLI that sends every schema it is given on every turn.- */-export type ToolDelivery = 'listed' | 'on-demand';-/** What a CLI does to every tool call, which the daemon has to work inside of. */export interface CallLimits {/** The CLI abandons a call that takes longer than this, whatever it is waiting on. */@@ -151,8 +145,8 @@ export interface Runner {keepsFirstPrompt?: boolean;/** Limits this CLI puts on a browser tool call; unset where it waits and takes whatever comes. */limits?: CallLimits;- /** How a run's less common browser tools reach the model; `listed` when unsaid. */- delivery?: ToolDelivery;+ /** How a run's grouped browser tools reach the model with these settings; `listed` when unsaid. */+ delivery?(settings: AgentSettings): ToolDelivery;json(context: JsonContext): Plan;/** What a one-shot of this CLI is known to open when handed a file. Text alone when unsaid. */opens?: readonly FileKind[];diff --git a/src/daemon/agent/runners/vibe.ts b/src/daemon/agent/runners/vibe.tsindex c01a20c..d7a95ba 100644--- a/src/daemon/agent/runners/vibe.ts+++ b/src/daemon/agent/runners/vibe.ts@@ -38,7 +38,7 @@ export const vibeRunner: Runner = {versionArgs: ['--version'],efforts: [],endsOnExit: true,- delivery: 'on-demand',+ delivery: () => 'on-demand',workspace: (mode: RunMode) => join(stateDir, 'agents', 'vibe', mode),diff --git a/src/daemon/agent/service.test.ts b/src/daemon/agent/service.test.tsindex 0122b02..ed9cce7 100644--- a/src/daemon/agent/service.test.ts+++ b/src/daemon/agent/service.test.ts@@ -72,7 +72,12 @@ describe('what a phone run is offered', () => {});test('a desktop run beside it is offered what it always was', async () => {- expect(await offerTo('d', { sessionId: 's2' })).toEqual({ withheld: CODE_TOOLS, reserved: [FOCUS_SHOT_ACTION], onDemand: names.filter(grouped) });+ expect(await offerTo('d', { sessionId: 's2' })).toEqual({+ withheld: CODE_TOOLS,+ reserved: [FOCUS_SHOT_ACTION],+ onDemand: names.filter(grouped),+ delivery: 'on-demand',+ });});test('a phone run leaves the tool list the browser describes, and so its hash, as it was', async () => {@@ -103,8 +108,8 @@ describe("what a run's tool list holds", () => {test('the page-code tools only with Live tool on, and the pick’s screenshot either way', async () => {expect([await offerTo('a', { sessionId: 's1' }), await offerTo('b', { sessionId: 's2', liveTools: true })]).toEqual([- { withheld: CODE_TOOLS, reserved: [FOCUS_SHOT_ACTION], onDemand: [] },- { withheld: [], reserved: [FOCUS_SHOT_ACTION], onDemand: [] },+ { withheld: CODE_TOOLS, reserved: [FOCUS_SHOT_ACTION], onDemand: [], delivery: 'on-demand' },+ { withheld: [], reserved: [FOCUS_SHOT_ACTION], onDemand: [], delivery: 'on-demand' },]);});@@ -135,9 +140,26 @@ describe('the tools a run reaches on demand', () => {expect([first?.onDemand, next?.onDemand]).toEqual([names.filter(grouped), names.filter(grouped)]);});- test('are none on a CLI that looks a schema up only when it needs one', async () => {+ test('are none on a CLI that looks a schema up only when it needs one, Codex on exec among them', async () => {+ const offered = async (runId: string, config: object) => {+ writeFileSync(configPath, JSON.stringify(config));+ const { onDemand, delivery } = (await offerTo(runId, { sessionId: runId }))!;+ return { onDemand, delivery };+ };+ const codex = onlyAgent('codex', '/nonexistent/codex');+ expect([+ await offered('cursor', onlyAgent('cursor', '/nonexistent/cursor')),+ await offered('exec', { ...codex, agents: { ...codex.agents, codex: { bin: '/nonexistent/codex', transport: 'exec' } } }),+ ]).toEqual([+ { onDemand: [], delivery: 'listed' },+ { onDemand: [], delivery: 'listed' },+ ]);+ });++ test("are namespaced on Codex held over stdin, for its own search to load", async () => {writeFileSync(configPath, JSON.stringify(onlyAgent('codex', '/nonexistent/codex')));- expect((await offerTo('c', { sessionId: 's1' }))?.onDemand).toEqual([]);+ const offer = await offerTo('c', { sessionId: 's1' });+ expect([offer?.onDemand, offer?.delivery]).toEqual([names.filter(grouped), 'namespaced']);});test('on the phone, are only the grouped ones the phone runs', async () => {diff --git a/src/daemon/agent/service.ts b/src/daemon/agent/service.tsindex 591b7c7..7cfd5ac 100644--- a/src/daemon/agent/service.ts+++ b/src/daemon/agent/service.ts@@ -42,6 +42,7 @@ import {type Policy,type Scope,} from '../guardrails';+import type { ToolDelivery } from '../control';import { log } from '../log';import { readProfile } from '../profile';import { grouped } from '../tool-groups';@@ -145,6 +146,8 @@ interface Waiting {decision: Promise<Decision>;}+const deliveryFor = (config: AgentConfig): ToolDelivery => RUNNERS[config.agent].delivery?.(config.agents[config.agent]) ?? 'listed';+export class AgentSession {/*** Per session, the conversation its agent is holding open, and the prompt that conversation was last@@ -200,16 +203,17 @@ 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[]; onDemand: string[] } | null {+ offerFor(runId: string): { withheld: string[]; reserved: string[]; onDemand: string[]; delivery: ToolDelivery } | null {const run = this.runs.get(runId);if (!run) return null;const codeListed = run.liveTools || (run.sessionId !== undefined && this.codeListed.has(run.sessionId));const codeWithheld = codeListed ? [] : [INJECT_ACTION, RUN_CODE_ACTION];+ const delivery = deliveryFor(run.config);const offered = (withheld: string[]) => this.onDemand(run).filter((name) => !withheld.includes(name));if (run.phone) {const offPhone = this.deps.actionNames().filter((name) => !phoneOffers(name));const withheld = [...new Set([...offPhone, ...codeWithheld])];- return { withheld, reserved: [FOCUS_SHOT_ACTION], onDemand: offered(withheld) };+ return { withheld, reserved: [FOCUS_SHOT_ACTION], onDemand: offered(withheld), delivery };}return {withheld: codeWithheld,@@ -217,12 +221,13 @@ export class AgentSession {// comes and goes between the messages of one, so the tool that shows it stays.reserved: [...(run.map ? [SAVE_SITE_MAP_ACTION] : []), FOCUS_SHOT_ACTION],onDemand: offered(codeWithheld),+ delivery,};}- /** The grouped actions a run calls through browsentic_use, when its CLI would send their schemas on every turn. */+ /** The grouped actions a run does not list, when its CLI would otherwise send their schemas on every turn. */private onDemand(run: ActiveRun): string[] {- return RUNNERS[run.config.agent].delivery === 'on-demand' ? this.deps.actionNames().filter(grouped) : [];+ return deliveryFor(run.config) === 'listed' ? [] : this.deps.actionNames().filter(grouped);}/** `signal` aborts when the caller stops waiting for this call, so nothing it asked for outlives it. */diff --git a/src/daemon/control.ts b/src/daemon/control.tsindex 27bf437..72edb96 100644--- a/src/daemon/control.ts+++ b/src/daemon/control.ts@@ -59,7 +59,15 @@ export type ControlRequest =| { id: string; op: 'android'; launch?: string; url?: string; watch?: boolean; peek?: boolean };export type ControlMessage =- | { id: string; op: 'describe'; tools: ToolDescriptor[]; reserved?: string[]; withheld?: ToolDescriptor[]; onDemand?: string[] }+ | {+ id: string;+ op: 'describe';+ tools: ToolDescriptor[];+ reserved?: string[];+ withheld?: ToolDescriptor[];+ onDemand?: string[];+ delivery?: ToolDelivery;+ }| { id: string; op: 'status'; status: BridgeStatus }| { id: string; op: 'invoke'; result: ActionResult }| { id: string; op: 'working' }@@ -74,6 +82,14 @@ export type ControlMessage =| { event: 'settings-changed' }| { event: 'android-changed'; state: AndroidState };+/**+ * How a run's grouped tools reach its model. `listed`: in its tool list, for a CLI that keeps schemas+ * out of the model's context until it looks one up. `on-demand`: left off the list and called through+ * browsentic_use, for a CLI that sends every schema it is given on every turn. `namespaced`: one+ * deferred namespace a group, loaded by the CLI's own tool search (Codex's app-server).+ */+export type ToolDelivery = 'listed' | 'on-demand' | 'namespaced';+export interface Described {tools: ToolDescriptor[];/** Reserved actions this caller may be offered. Absent when the daemon predates the field. */@@ -85,10 +101,11 @@ export interface Described {*/withheld?: ToolDescriptor[];/**- * Actions in `tools` this run calls through browsentic_use rather than from its tool list, found- * through the guides. A caller that does not know the field lists them as it always has.+ * Actions in `tools` this run does not list, reached as `delivery` says and found through the+ * guides. A caller that does not know the field lists them as it always has.*/onDemand?: string[];+ delivery?: ToolDelivery;}export interface Bridge {diff --git a/src/daemon/daemon.ts b/src/daemon/daemon.tsindex da7c307..8daa4fe 100644--- a/src/daemon/daemon.ts+++ b/src/daemon/daemon.ts@@ -788,6 +788,7 @@ export async function startDaemon({ version, idleExit = true, android = androidOreserved: offer.reserved,withheld: running[0].tools.filter(({ name }) => withheld(name)),onDemand: offer.onDemand,+ delivery: offer.delivery,};}diff --git a/src/daemon/remote-bridge.test.ts b/src/daemon/remote-bridge.test.tsindex f68131f..ec5bfbf 100644--- a/src/daemon/remote-bridge.test.ts+++ b/src/daemon/remote-bridge.test.ts@@ -66,8 +66,9 @@ describe('asking the daemon', () => {{ name: 'page.getPageInfo', description: 'Read the page', inputSchema: {} },{ name: 'page.dragElement', description: 'Drag', inputSchema: {} },];- answer = ({ id }) => ({ id, op: 'describe', tools, reserved: ['browsentic.focusShot'], onDemand: ['page.dragElement'] });- expect(await bridge.describe()).toEqual({ tools, reserved: ['browsentic.focusShot'], onDemand: ['page.dragElement'] });+ const offer = { reserved: ['browsentic.focusShot'], onDemand: ['page.dragElement'], delivery: 'namespaced' as const };+ answer = ({ id }) => ({ id, op: 'describe', tools, ...offer });+ expect(await bridge.describe()).toStrictEqual({ tools, ...offer, withheld: undefined });});test('an action, stamped with the run it belongs to', async () => {diff --git a/src/daemon/remote-bridge.ts b/src/daemon/remote-bridge.tsindex 4515911..95a41bc 100644--- a/src/daemon/remote-bridge.ts+++ b/src/daemon/remote-bridge.ts@@ -36,7 +36,9 @@ export class RemoteBridge implements Bridge {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, withheld: reply.withheld, onDemand: reply.onDemand } : { tools: [] };+ if (!reply || !('tools' in reply)) return { tools: [] };+ const { tools, reserved, withheld, onDemand, delivery } = reply;+ return { tools, reserved, withheld, onDemand, delivery };}async invoke(action: string, input?: unknown, signal?: AbortSignal): Promise<ActionResult> {diff --git a/src/daemon/server.test.ts b/src/daemon/server.test.tsindex 7930c24..09f9daf 100644--- a/src/daemon/server.test.ts+++ b/src/daemon/server.test.ts@@ -10,13 +10,17 @@ import { describeActions } from '@/lib/actions/registry';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 } from './control';-import { FENCE_NOTE, IMAGE_NOTE } from './guardrails';+import type { Bridge, BridgeStatus, Described } from './control';+import { FENCE_NOTE, IMAGE_NOTE, policyFrom } from './guardrails';import { stateDir } from './lockfile';import { grouped } from './tool-groups';import { createMcpServer } from './server';+import { toolHost } from './tool-host';const KEY = 'sk-ant-api03-AbCdEfGhIjKlMnOpQrStUvWxYz012345';+const GROUPED = describeActions()+ .filter((action) => grouped(action.name))+ .map((action) => action.name);const PNG = 'data:image/png;base64,iVBORw0KGgo=';type Answer = (action: string, input: unknown) => ActionResult;@@ -26,14 +30,13 @@ function fakeBridge(answers: Record<string, ActionResult> | Answer = {},status: Partial<BridgeStatus> = {},tools: ToolDescriptor[] = describeActions(),- reserved?: string[],- onDemand?: string[],+ offer: Omit<Described, 'tools'> = {},) {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, reserved, onDemand }),+ describe: async () => ({ tools, ...offer }),invoke: async (action, input) => {asked.push([action, input]);return answer(action, input);@@ -106,8 +109,8 @@ describe('the tool list', () => {});test('a run that reaches the grouped tools on demand lists the rest, then the tool that runs those', async () => {- const onDemand = describeActions().filter((action) => grouped(action.name)).map((action) => action.name);- const { tools } = await (await connect(fakeBridge({}, {}, describeActions(), [], onDemand).bridge, { agentRun: true })).listTools();+ const onDemand = GROUPED;+ const { tools } = await (await connect(fakeBridge({}, {}, describeActions(), { reserved: [], onDemand, delivery: 'on-demand' }).bridge, { agentRun: true })).listTools();expect(tools.map((tool) => tool.name)).toEqual([...describeActions().filter((action) => !onDemand.includes(action.name)).map((action) => toolNameFor(action.name)),'browsentic_status',@@ -116,8 +119,50 @@ describe('the tool list', () => {]);});+ test('a namespaced run lists every tool to an MCP client, which takes no namespaces, and its guides say to call them by name', async () => {+ const offer = { reserved: [], onDemand: GROUPED, delivery: 'namespaced' as const };+ const client = await connect(fakeBridge({}, {}, describeActions(), offer).bridge, { agentRun: true });+ const { tools } = await client.listTools();+ const [guide] = texts(await call(client, 'browsentic_openSkill', { name: 'drag' }));+ expect([tools.length, tools.some((tool) => tool.name === 'browsentic_use'), guide.split('\n\n')[2]]).toEqual([+ describeActions().length + 2,+ false,+ 'Call them by name, as you would any other tool.',+ ]);+ });++ test("a namespaced run hands a CLI that takes namespaces each group apart, named and described by its index line, for the CLI's own search", async () => {+ const offer = { reserved: [], onDemand: GROUPED, delivery: 'namespaced' as const };+ const host = toolHost(fakeBridge({}, {}, describeActions(), offer).bridge, { agentRun: true, namespaces: true, policy: policyFrom(undefined), tag: 'tag' });+ const { tools, groups } = await host.list();+ const [guide] = texts((await host.call('browsentic_openSkill', { name: 'captcha' })) as Awaited<ReturnType<typeof call>>);+ expect({+ listed: tools.map((tool) => tool.name).filter((name) => GROUPED.map(toolNameFor).includes(name) || name === 'browsentic_use'),+ groups: groups.map((group) => [group.description.split(':')[0], group.name, group.tools.map((tool) => tool.name)]),+ captcha: groups[0].description,+ guide: guide.split('\n\n').find((part) => part.startsWith('They load')),+ }).toEqual({+ listed: [],+ groups: [+ ['captcha', 'captcha', ['page_findCaptcha', 'page_solveCaptcha']],+ ['theming', 'theming', ['page_readTheme', 'page_auditContrast', 'page_applyTheme']],+ ['diagnostics', 'diagnostics', ['page_startDiagnostics', 'page_readConsole', 'page_readNetwork', 'page_stopDiagnostics']],+ [+ 'monitoring',+ 'monitoring',+ ['page_findProgress', 'page_startMonitor', 'page_monitorStatus', 'page_awaitMonitor', 'page_stopMonitor', 'page_startTimer', 'page_timerStatus', 'page_stopTimer'],+ ],+ ['downloads', 'downloads', ['page_captureDownload', 'page_listDownloads']],+ ['drag', 'drag', ['page_dragElement']],+ ],+ captcha: 'captcha: get past a “verify you are human” check: reCAPTCHA, hCaptcha, Turnstile',+ guide:+ 'They load when you search for them: tool_search with "captcha" loads them all, then call each by name. Inside exec they are tools.captcha__<tool>, such as tools.captcha__page_findCaptcha.',+ });+ });+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 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_openSkill', toolNameFor(FOCUS_SHOT_ACTION)],@@ -347,8 +392,8 @@ describe('a guide', () => {});test('tells a run that reaches its tools on demand to call them through browsentic_use', async () => {- const onDemand = describeActions().filter((action) => grouped(action.name)).map((action) => action.name);- const client = await connect(fakeBridge({}, {}, describeActions(), [], onDemand).bridge);+ const onDemand = GROUPED;+ const client = await connect(fakeBridge({}, {}, describeActions(), { reserved: [], onDemand, delivery: 'on-demand' }).bridge);const [text] = texts(await call(client, 'browsentic_openSkill', { name: 'drag' }));expect(text.split('\n\n')[2]).toBe('They are not in your tool list. Call each through browsentic_use, its name as action and its parameters as input: {"action": "page_dragElement", "input": {...}}.',diff --git a/src/daemon/tool-groups.ts b/src/daemon/tool-groups.tsindex 3de1a9d..c6fde5a 100644--- a/src/daemon/tool-groups.ts+++ b/src/daemon/tool-groups.ts@@ -4,6 +4,7 @@ import { failure, success, type ActionResult } from '@/lib/actions/protocol';import { actions } from '@/lib/actions/registry';import { OPEN_SKILL_TOOL, toolNameFor, USE_TOOL } from '@/lib/actions/tool-names';import type { Skill } from './agent/skills';+import type { Described, ToolDelivery } from './control';const GROUP_NAMES = Object.keys(TOOL_GROUPS) as ToolGroupName[];@@ -39,18 +40,33 @@ export function groupNamed(name: string): ToolGroupName | undefined {);}-/**- * The group's skills, then each of its tools this caller is offered, with the schema to call it by,- * and how: by name, or through browsentic_use for tools left off this caller's list.- */-export function groupGuide(- group: ToolGroupName,- offered: readonly ToolDescriptor[],- onDemand: readonly string[],- skills: readonly Skill[],-): ActionResult<string> {+export interface GroupListing {+ name: ToolGroupName;+ /** Its index line, led by its name, which is what a search for it matches. */+ description: string;+ tools: ToolDescriptor[];+}++/** These tools by the group each belongs to, in index order; ungrouped ones are left out. */+export function groupsOf(tools: readonly ToolDescriptor[]): GroupListing[] {+ return GROUP_NAMES.map((group) => ({+ name: group,+ description: `${group}: ${TOOL_GROUPS[group].index}`,+ tools: tools.filter((tool) => actions.get(tool.name)?.group === group),+ })).filter((group) => group.tools.length);+}++const howToCall = (group: ToolGroupName, first: string, delivery: ToolDelivery) =>+ ({+ listed: 'Call them by name, as you would any other tool.',+ 'on-demand': `They are not in your tool list. Call each through ${USE_TOOL}, its name as action and its parameters as input: {"action": "${first}", "input": {...}}.`,+ namespaced: `They load when you search for them: tool_search with "${group}" loads them all, then call each by name. Inside exec they are tools.${group}__<tool>, such as tools.${group}__${first}.`,+ })[delivery];++/** The group's skills, then each of its tools this caller is offered, with the schema to call it by, and how to call it. */+export function groupGuide(group: ToolGroupName, offer: Described, skills: readonly Skill[]): ActionResult<string> {const members = membersOf(group).map((action) => action.name);- const tools = offered.filter((tool) => members.includes(tool.name));+ const tools = offer.tools.filter((tool) => members.includes(tool.name));const missing = members.filter((name) => !tools.some((tool) => tool.name === name)).map(toolNameFor);if (!tools.length) {return failure(@@ -65,10 +81,7 @@ export function groupGuide(`# The ${group} guide`,...bodies,'## Its tools',- tools.some((tool) => onDemand.includes(tool.name))- ? `They are not in your tool list. Call each through ${USE_TOOL}, its name as action and its parameters as input: ` +- `{"action": "${toolNameFor(tools[0].name)}", "input": {...}}.`- : 'Call them by name, as you would any other tool.',+ howToCall(group, toolNameFor(tools[0].name), tools.some((tool) => offer.onDemand?.includes(tool.name)) ? (offer.delivery ?? 'on-demand') : 'listed'),...tools.map((tool) => `### ${toolNameFor(tool.name)}\n${tool.description}\nInput schema: ${JSON.stringify(tool.inputSchema)}`),...(missing.length ? [`Not offered in this run: ${missing.join(', ')}.`] : []),].join('\n\n'),diff --git a/src/daemon/tool-host.ts b/src/daemon/tool-host.tsindex ca3f08a..5eb7cc9 100644--- a/src/daemon/tool-host.ts+++ b/src/daemon/tool-host.ts@@ -4,9 +4,9 @@ import { failure, type ActionResult } from '@/lib/actions/protocol';import { FOCUS_SHOT_ACTION, RESERVED_ACTIONS, SAVE_SITE_MAP_ACTION } from '@/lib/actions/reserved';import { actionNameFor, assertToolNamesRoundTrip, OPEN_SKILL_TOOL, STATUS_TOOL, toolNameFor, USE_TOOL } from '@/lib/actions/tool-names';import { loadSkills } from './agent/skills';-import type { Bridge } from './control';+import type { Bridge, Described } from './control';import { IMAGE_NOTE, fence, sealSecrets, shouldFence, type Policy } from './guardrails';-import { GROUP_INDEX, groupGuide, groupNamed, pageActionNamed } from './tool-groups';+import { GROUP_INDEX, groupGuide, groupNamed, groupsOf, pageActionNamed } from './tool-groups';const EXTRACT_ACTION = 'page.extractText';@@ -133,10 +133,18 @@ export interface ListedTool {inputSchema: { type: 'object' } & Record<string, unknown>;}+export interface ListedGroup {+ name: string;+ description: string;+ tools: ListedTool[];+}+export interface ToolList {tools: ListedTool[];/** Offered later in the conversation, perhaps — see `Described.withheld`. */withheld: ListedTool[];+ /** A namespaced run's grouped tools, for its CLI to load when its own search asks for them. */+ groups: ListedGroup[];}export type ToolContent = { type: 'text'; text: string } | { type: 'image'; data: string; mimeType: string };@@ -159,24 +167,30 @@ export interface ToolHost {interface HostOptions {agentRun?: boolean;+ /** The CLI takes deferred namespaces (Codex's app-server). Without them, a namespaced run's grouped tools are listed. */+ namespaces?: boolean;/** The most text, in UTF-8 bytes, the CLI on the other end passes to its model; unset for no limit. */resultBytes?: number;policy: Policy;tag: string;}-export function toolHost(bridge: Bridge, { agentRun = false, resultBytes, policy, tag }: HostOptions): ToolHost {+export function toolHost(bridge: Bridge, { agentRun = false, namespaces = false, resultBytes, policy, tag }: HostOptions): ToolHost {const invoke = (action: string, args: Record<string, unknown>, signal?: AbortSignal) =>bridge.invoke(action, resultBytes && action === EXTRACT_ACTION ? fitRead(args, resultBytes) : args, signal);const present = (action: string, result: ActionResult) =>(RENDERERS[action] ?? render)(result, shouldFence(action, policy) ? tag : undefined);+ const offer = async (): Promise<Described> => {+ const described = await bridge.describe();+ return described.delivery === 'namespaced' && !namespaces ? { ...described, onDemand: [], delivery: 'listed' } : described;+ };+const openSkill = async ({ name }: Record<string, unknown>): Promise<ToolReply> => {const group = typeof name === 'string' ? groupNamed(name) : undefined;if (!group) return render(failure('UNKNOWN_SKILL', `There is no guide named "${String(name ?? '')}". The guides are:\n${GROUP_INDEX}`));- const { tools, onDemand = [] } = await bridge.describe();- const guide = groupGuide(group, tools, onDemand, loadSkills());+ const guide = groupGuide(group, await offer(), loadSkills());return guide.ok ? { content: [{ type: 'text', text: guide.data }] } : render(guide);};@@ -216,8 +230,10 @@ export function toolHost(bridge: Bridge, { agentRun = false, resultBytes, policyreserved = agentRun ? RESERVED_TOOLS.map((tool) => tool.action) : [],withheld = [],onDemand = [],- } = await bridge.describe();+ delivery,+ } = await offer();assertToolNamesRoundTrip([...actions.map((action) => action.name), ...RESERVED_ACTIONS]);+ const namespaced = delivery === 'namespaced';return {tools: [...actions.filter((action) => !onDemand.includes(action.name)).map(listed),@@ -228,10 +244,13 @@ export function toolHost(bridge: Bridge, { agentRun = false, resultBytes, policyinputSchema: { type: 'object' as const, properties: {}, additionalProperties: false },},OPEN_SKILL,- ...(onDemand.length ? [USE] : []),+ ...(onDemand.length && !namespaced ? [USE] : []),...RESERVED_TOOLS.filter((tool) => reserved.includes(tool.action)).map((tool) => tool.descriptor),],withheld: withheld.map(listed),+ groups: namespaced+ ? groupsOf(actions.filter((action) => onDemand.includes(action.name))).map((group) => ({ ...group, tools: group.tools.map(listed) }))+ : [],};},