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(agents): give a Vibe conversation one folder and rewrite it every turn, because a resumed session is re-read from the folder it began in and so called the browser with a finished run's id
Shahriar6dc97dfd13e8
diff --git a/docs/guide/agents.md b/docs/guide/agents.mdindex 430e9ee..f775316 100644--- a/docs/guide/agents.md+++ b/docs/guide/agents.md@@ -52,12 +52,30 @@ for exactly what each flag buys.too old to understand them fails the run with an explicit "update it" message rather than runninguncontained.+### Codex keeps the browser tools out of sight++Codex does not put an MCP server's tools in the model's list. They are deferred behind its+`tool_search`, and on a code-mode model (`gpt-5.6-terra` and the like) they exist only inside its+`exec` sandbox. Left to itself, a model answers a question about the page from the tools it *can*+see — its own memory, or a web search — without ever looking at your browser.++So a Codex run is given a section of prompt saying where its browser tools are and how to load them,+and it is told to read the page rather than recall it. Web search is switched off unless the run is+[mapping a site](features/site-maps.md), and sub-agents, goal memory, connector apps and plugin suggestions+are switched off for good measure.++One thing Browsentic cannot change: **Codex cuts any tool result longer than about 10,000 tokens**,+which a whole-page snapshot can pass. The prompt asks for smaller reads, but on a dense page expect+Codex to see less of it than the other agents do.+### Mistral Vibe is in betaIt needs nothing set up beyond `vibe --setup` (or `MISTRAL_API_KEY` in `~/.vibe/.env`). Browsentic-writes a project config into the run's own folder under `~/.browsentic` — the `browsentic` MCP server-and an `always` permission for each of its tools — and starts Vibe there with `--trust`, so your-`~/.vibe/config.toml` is read for your key and models but never written.+writes a project config into the conversation's own folder under `~/.browsentic` — the `browsentic`+MCP server and an `always` permission for each of its tools — and starts Vibe there with `--trust`,+so your `~/.vibe/config.toml` is read for your key and models but never written. One folder per+conversation, rewritten each turn, because Vibe re-reads a resumed session from the folder it began+in rather than the one it is started in.Two things differ from the others. Vibe's headless stream carries whole messages, not tokens, so areply **arrives a message at a time** instead of being typed out. And it reports no token counts, so@@ -131,6 +149,8 @@ Claude runner's settings.| `AGENT_MISSING` | The daemon's `PATH` differs from your shell's. Set `agents.<name>.bin` to an absolute path. || `AGENT_NEEDS_PERMISSION` | Antigravity has no rule for Browsentic's tools: press the button, or `browsentic agent fix antigravity`. Grok Build is not signed in: run `grok login`. || Codex: "not logged in" | The daemon inherits no session. Run `codex login`, then retry. |+| Codex answers about the page without opening it, or from a web search | Update Browsentic. Codex hides the browser tools until the model searches for them, and an older Browsentic left Codex's own web search switched on, which the model reached for first. |+| Mistral Vibe: a follow-up turn says *this agent run is no longer active* | Update Browsentic. An older one gave each turn its own folder, and Vibe kept re-reading the first turn's. || "does not understand the flags Browsentic uses" | The CLI is too old. Update it. || Antigravity answers but never touches the page | Its permission rule was removed. `browsentic agent` reports *needs setup* again. || Grok Build sits silent for minutes, then *xAI did not answer* | The Grok account is rate-limited — a free one usually is. Wait, or upgrade the account. |diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.mdindex 712a9c7..3cbc3b6 100644--- a/docs/guide/troubleshooting.md+++ b/docs/guide/troubleshooting.md@@ -57,6 +57,9 @@ Those three answer most questions. The daemon log also lives at `~/.browsentic/d| Mistral Vibe fails with *has no API key* | Vibe was never set up, or its key lives only in a shell the daemon was not started from | `vibe --setup`, which stores it in `~/.vibe/.env` || Antigravity answers but never touches the page | Its permission rule was removed | `browsentic agent` — it reports *needs setup* again || Codex fails with "not logged in" | The daemon inherits no session | `codex login`, then retry |+| Codex answers about the page without opening it, or from a web search | Codex defers an MCP server's tools until the model searches for them, so a web search is the tool it can see; an older Browsentic also failed to switch that search off | Update Browsentic; the run now says where its browser tools are and switches web search off |+| Codex sees only part of a long page | Codex cuts any tool result over about 10,000 tokens | Ask for less at a time: a smaller `maxPerKind`, or `page_extractText` group by group |+| Mistral Vibe: every action on a follow-up turn fails with `RUN_INACTIVE` | Vibe re-reads a resumed session from the folder it began in, and an older Browsentic wrote each turn to a folder of its own | Update Browsentic — a conversation now keeps one folder, rewritten each turn || Grok Build sits silent for minutes, then fails with *xAI did not answer* | The Grok account is rate-limited, as a free one is; Grok retries quietly before giving up | Wait, or upgrade the account || `AGENT_UNSAFE`: *Grok Build offered this run …* | Grok offered tools Browsentic never asks for, so the run was stopped before the model saw them | Update Grok Build and Browsentic; report it if it persists |diff --git a/docs/internals/agent-runs.md b/docs/internals/agent-runs.mdindex d07a451..826c090 100644--- a/docs/internals/agent-runs.md+++ b/docs/internals/agent-runs.md@@ -91,11 +91,24 @@ Every runner is given the same four things, by whichever mechanism its CLI suppo| MCP server | `--mcp-config` + `--strict-mcp-config` | `-c mcp_servers.browsentic.*`, with `default_tools_approval_mode="approve"` — headless Codex refuses any MCP call it would have prompted for | `.agents/mcp_config.json` in its cwd | `.grok/config.toml` in its cwd, loaded with `GROK_FOLDER_TRUST=0`, and approved with `--allow MCPTool(browsentic__*)` || System prompt | `--append-system-prompt` | `-c developer_instructions` | `AGENTS.md` in its cwd | `--rules` || Follow-up turns | `--resume <session>` | `exec resume <thread>` | `--conversation <id>` | `--session-id <uuid>` names it, `--resume <uuid>` continues it, in a folder named after it |-| Kept off the machine by | `--allowedTools` + `--disallowedTools` | `-c sandbox_mode="read-only"`, `-c approval_policy="never"` | its own permission rules | `--tools`, `--permission-mode dontAsk`, `--deny`, `--sandbox workspace` |+| Kept off the machine by | `--allowedTools` + `--disallowedTools` | `-c sandbox_mode="read-only"`, `-c approval_policy="never"`, `-c features.multi_agent=false` | its own permission rules | `--tools`, `--permission-mode dontAsk`, `--deny`, `--sandbox workspace` |+**Two CLIs do not put the browser tools in the model's list, and both are told so in the prompt.**Grok reaches MCP tools only through two meta-tools, `search_tool` and `use_tool`, under a-`browsentic__` prefix; the system prompt it is given says so, because the skills name tools the way-the server lists them.+`browsentic__` prefix. Codex defers them behind its own `tool_search`, and a code-mode model+(`tool_mode: "code_mode_only"` in its model catalog) reaches them only from inside `exec`, as+`tools.mcp__browsentic__*`, where an image reaches the model only if the script passes it to+`image()`. Left unsaid, a model answers from what it can see — its memory, or the web search Codex+switches on by default, which is why a run now passes `web_search="disabled"` unless it is mapping.+Codex also truncates any tool result over about 10,000 tokens, a limit its model catalog sets and no+flag raises, so its prompt asks for page reads in pieces.++**A CLI that re-reads its own folder gets one per conversation, not one per run.** Vibe restores a+resumed session from the folder it began in, whatever folder it is started in now, so a folder per+run left every follow-up turn calling the browser with the first turn's `BROWSENTIC_AGENT_RUN` —+refused as `RUN_INACTIVE` — behind a system prompt frozen at the first turn. `StreamContext`+carries the conversation for exactly this: `conversationDir()` names the folder after it, and every+turn rewrites what is in it.**Conversation continuity** is what makes "now click the second one" work: the runner reportswhatever session id its CLI established (`session_id`, `thread_id`, `conversation_id`, `sessionId`) and gets itdiff --git a/src/daemon/agent/runner.ts b/src/daemon/agent/runner.tsindex adb98b8..f83a587 100644--- a/src/daemon/agent/runner.ts+++ b/src/daemon/agent/runner.ts@@ -10,6 +10,8 @@ export type { RunOutcome };export interface RunRequest {runId: string;+ /** The conversation the panel is holding, which outlives this one run. */+ conversation: string | null;instruction: string;systemPrompt: string;config: AgentConfig;@@ -28,6 +30,7 @@ export function runInstruction(request: RunRequest): Promise<RunOutcome> {runner,{runId: request.runId,+ conversation: request.conversation,instruction: request.instruction,systemPrompt: request.systemPrompt,research: request.research === true,diff --git a/src/daemon/agent/runners/fixtures/support.ts b/src/daemon/agent/runners/fixtures/support.tsindex 717ab5f..4381b30 100644--- a/src/daemon/agent/runners/fixtures/support.ts+++ b/src/daemon/agent/runners/fixtures/support.ts@@ -43,6 +43,7 @@ const mcp: McpServer = {export const streamContext = (settings: AgentSettings, overrides: Partial<StreamContext> = {}): StreamContext => ({runId: 'run-1',+ conversation: 'conversation-1',instruction: 'what does this page cost',systemPrompt: 'You are Browsentic.',research: false,diff --git a/src/daemon/agent/runners/grok.ts b/src/daemon/agent/runners/grok.tsindex 2a2aeee..0d426d5 100644--- a/src/daemon/agent/runners/grok.ts+++ b/src/daemon/agent/runners/grok.ts@@ -5,7 +5,7 @@ import { join } from 'node:path';import type { AgentProblem } from '@/lib/agents/catalog';import { stateDir } from '../../lockfile';import { MCP_SERVER_NAME } from './claude';-import { effortOf, parseJsonLine, sweepRunDirs } from './util';+import { conversationDir, effortOf, parseJsonLine, sweepRunDirs } from './util';import type { JsonContext, McpServer, Plan, Runner, RunMode, StreamContext, StreamReader, StreamSink } from './types';/** Grok takes every setting a run needs as a flag except its MCP server, which only a project config can add. */@@ -81,7 +81,7 @@ export const grokRunner: Runner = {// A conversation keeps one directory, so a resume finds its session wherever Grok files it.const conversation = context.sessionId ?? randomUUID();return {- cwd: join(base, conversation.replace(/[^\w-]/g, '_')),+ cwd: conversationDir(base, conversation),env: { BROWSENTIC_AGENT_RUN: context.runId, ...SEALED, ...TRUSTED },files: [{ path: CONFIG, content: config(context.mcp) }],args: [diff --git a/src/daemon/agent/runners/types.ts b/src/daemon/agent/runners/types.tsindex f254393..e44d45e 100644--- a/src/daemon/agent/runners/types.ts+++ b/src/daemon/agent/runners/types.ts@@ -26,6 +26,8 @@ export interface Plan {export interface StreamContext {runId: string;+ /** The panel conversation this run belongs to, which every turn of it shares — unlike `runId`. */+ conversation: string | null;instruction: string;systemPrompt: string;research: boolean;diff --git a/src/daemon/agent/runners/util.ts b/src/daemon/agent/runners/util.tsindex 4fecd35..7bf61b6 100644--- a/src/daemon/agent/runners/util.ts+++ b/src/daemon/agent/runners/util.ts@@ -24,6 +24,14 @@ export function sweepRunDirs(base: string, ttlMs = RUN_DIR_TTL_MS): void {}}+/**+ * One directory per conversation, for a CLI that reads its settings from the folder a run starts+ * in. The name is whatever identifies the conversation, spelled so it is safe as a path segment.+ */+export function conversationDir(base: string, key: string): string {+ return join(base, key.replace(/[^\w-]/g, '_'));+}+/** Drops a reasoning-effort name the CLI would reject rather than letting it fail the run. */export function effortOf(settings: AgentSettings, accepted: string[]): string | undefined {const effort = settings.effort;diff --git a/src/daemon/agent/runners/vibe.test.ts b/src/daemon/agent/runners/vibe.test.tsnew file mode 100644index 0000000..54f6cc4--- /dev/null+++ b/src/daemon/agent/runners/vibe.test.ts@@ -0,0 +1,109 @@+import { describe, expect, test } from 'vitest';+import { stateDir } from '../../lockfile';+import { jsonContext, shown, streamContext } from './fixtures/support';+import { vibeRunner } from './vibe';++const settings = { bin: 'vibe' };+const stream = (overrides: Parameters<typeof streamContext>[1] = {}) => vibeRunner.stream(streamContext(settings, overrides));++const fileIn = (plan: { files?: readonly { path: string; content: string }[] }, path: string) =>+ plan.files?.find((file) => file.path === path)?.content ?? '';++describe('a streamed run', () => {+ test('a fresh run writes its server, model and tool grants where Vibe will read them', () => {+ expect(shown(stream({ settings: { bin: 'vibe', model: 'mistral-medium-3.5' } }))).toMatchInlineSnapshot(`+ {+ "args": [+ "--prompt",+ "what does this page cost",+ "--output",+ "streaming",+ "--trust",+ "--agent",+ "ask",+ "--enabled-tools",+ "browsentic_*",+ ],+ "cwd": "<state>/agents/vibe/run/conversation-1",+ "env": {+ "BROWSENTIC_AGENT_RUN": "run-1",+ },+ "files": [+ {+ "content": "active_model = "mistral-medium-3.5"++ [[mcp_servers]]+ name = "browsentic"+ transport = "stdio"+ command = ["/usr/local/bin/node"]+ args = ["/usr/local/lib/node_modules/browsentic/dist/cli.js", "mcp"]++ [mcp_servers.env]+ BROWSENTIC_AGENT_RUN = "run-1"++ [tools."browsentic_page_getPageInfo"]+ permission = "always"++ [tools."browsentic_page_clickElement"]+ permission = "always"++ [tools."browsentic_browsentic_status"]+ permission = "always"+ ",+ "path": ".vibe/config.toml",+ },+ {+ "content": "You are Browsentic.+ ",+ "path": "AGENTS.md",+ },+ ],+ }+ `);+ });++ /**+ * Vibe re-reads a resumed session from the folder it began in, not the one it is started in. A+ * folder per run left the second turn calling the browser with the first turn's run id — which+ * the daemon answers RUN_INACTIVE, every time — behind the first turn's system prompt.+ */+ test('a follow-up rewrites the same folder, so the run id and the prompt are this turn’s', () => {+ const first = stream();+ const second = stream({+ runId: 'run-2',+ // The daemon points the server at the run it belongs to; the config carries whatever it says.+ mcp: { ...streamContext(settings).mcp, env: { BROWSENTIC_AGENT_RUN: 'run-2' } },+ sessionId: 'vibe-session-1',+ systemPrompt: 'You are Browsentic. Second turn.',+ });++ expect(second.cwd).toBe(first.cwd);+ expect(second.args).toContain('--resume');+ expect(fileIn(second, '.vibe/config.toml')).toContain('BROWSENTIC_AGENT_RUN = "run-2"');+ expect(fileIn(second, 'AGENTS.md')).toContain('Second turn.');+ expect(second.env?.BROWSENTIC_AGENT_RUN).toBe('run-2');+ });++ test('a run with no conversation keeps a folder of its own', () => {+ expect(stream({ conversation: null }).cwd).toBe(`${stateDir}/agents/vibe/run/run-1`);+ });++ test('a conversation id is spelled so it stays one path segment', () => {+ expect(stream({ conversation: '../../escape me' }).cwd).toBe(`${stateDir}/agents/vibe/run/______escape_me`);+ });++ test('research adds the web tools to the allowlist, and nothing else is switched on', () => {+ const args = stream({ research: true }).args;+ const allowed = args.flatMap((arg, at) => (arg === '--enabled-tools' ? [args[at + 1]] : []));+ expect(allowed).toEqual(['browsentic_*', 'web_search', 'web_fetch']);+ });+});++describe('a one-shot task', () => {+ test('a task reaches no browser and switches no tool on', () => {+ const plan = vibeRunner.json(jsonContext(settings));+ expect(plan.cwd).toBe(`${stateDir}/agents/vibe/task`);+ expect(plan.args).toContain('re:^$');+ expect(fileIn(plan, '.vibe/config.toml')).not.toContain('mcp_servers');+ });+});diff --git a/src/daemon/agent/runners/vibe.ts b/src/daemon/agent/runners/vibe.tsindex 364d61f..e1fa774 100644--- a/src/daemon/agent/runners/vibe.ts+++ b/src/daemon/agent/runners/vibe.ts@@ -2,7 +2,7 @@ import { homedir } from 'node:os';import { join } from 'node:path';import { stateDir } from '../../lockfile';import { MCP_SERVER_NAME } from './claude';-import { parseJsonLine, sweepRunDirs } from './util';+import { conversationDir, parseJsonLine, sweepRunDirs } from './util';import type { JsonContext, McpServer, Plan, Runner, RunMode, StreamContext, StreamReader } from './types';/** Vibe reads MCP servers and tool permissions from a project config, and only from a folder it trusts. */@@ -48,8 +48,12 @@ export const vibeRunner: Runner = {sweepRunDirs(base);const builtins = context.research ? WEB_TOOLS : [];const granted = [...context.mcpTools.map((tool) => `${MCP_SERVER_NAME}_${tool}`), ...builtins];+ // A resumed session is re-read from the folder it began in, whatever folder Vibe is started+ // in now — so a conversation keeps one, and every turn rewrites it. Give a run its own and+ // the second turn calls the browser with the first turn's run id, which the daemon refuses,+ // behind a system prompt that also stopped at the first turn.return {- cwd: join(base, context.runId),+ cwd: conversationDir(base, context.conversation ?? context.runId),env: { BROWSENTIC_AGENT_RUN: context.runId },files: [{ path: CONFIG, content: config(context.settings.model, context.mcp, granted) },diff --git a/src/daemon/agent/service.ts b/src/daemon/agent/service.tsindex 156a51d..725e71e 100644--- a/src/daemon/agent/service.ts+++ b/src/daemon/agent/service.ts@@ -384,6 +384,7 @@ export class AgentSession {try {const outcome = await runInstruction({runId,+ conversation: sessionId ?? null,instruction: instructionText,systemPrompt: built.prompt,research: run.map ? run.map.settings.research : false,diff --git a/src/daemon/guardrails/spawn.test.ts b/src/daemon/guardrails/spawn.test.tsindex 0ddf042..ba87f5b 100644--- a/src/daemon/guardrails/spawn.test.ts+++ b/src/daemon/guardrails/spawn.test.ts@@ -11,6 +11,7 @@ const planOf = (kind: AgentKind, mode: 'run' | 'task', { research = false, readsmode === 'run'? RUNNERS[kind].stream({runId: 'run-1',+ conversation: 'conversation-1',instruction: 'what does this page cost',systemPrompt: 'You are Browsentic.',research,