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.

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.md
index 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 running
uncontained.
+### 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 beta
It 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 a
reply **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.md
index 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.md
index 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 reports
whatever session id its CLI established (`session_id`, `thread_id`, `conversation_id`, `sessionId`) and gets it
diff --git a/src/daemon/agent/runner.ts b/src/daemon/agent/runner.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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, reads
mode === 'run'
? RUNNERS[kind].stream({
runId: 'run-1',
+ conversation: 'conversation-1',
instruction: 'what does this page cost',
systemPrompt: 'You are Browsentic.',
research,