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.

test(agent): pin each runner's plans, stream readers, answers and hints against recorded and hand-written transcripts

Shahriard098e6319e3e
diff --git a/src/daemon/agent/runners/antigravity.test.ts b/src/daemon/agent/runners/antigravity.test.ts
new file mode 100644
index 0000000..dc02323
--- /dev/null
+++ b/src/daemon/agent/runners/antigravity.test.ts
@@ -0,0 +1,294 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { beforeEach, describe, expect, test } from 'vitest';
+import { stateDir } from '../../lockfile';
+import { antigravityRunner, MCP_RULE, settingsPath } from './antigravity';
+import { jsonContext, readThrough, shown, streamContext, transcript } from './fixtures/support';
+
+const settings = { bin: 'agy' };
+const stream = (overrides: Parameters<typeof streamContext>[1] = {}) => antigravityRunner.stream(streamContext(settings, overrides));
+const read = (name: string) => readThrough(antigravityRunner, transcript('antigravity', name));
+const readLines = (...lines: object[]) => readThrough(antigravityRunner, lines.map((line) => JSON.stringify(line)));
+
+describe('a streamed run', () => {
+ test('a fresh run gets its own directory, with the browser server and the system prompt written into it', () => {
+ expect(shown(stream())).toMatchInlineSnapshot(`
+ {
+ "args": [
+ "-p",
+ "what does this page cost",
+ "--output-format",
+ "stream-json",
+ "--print-timeout",
+ "60m",
+ ],
+ "cwd": "<state>/agents/antigravity/run/run-1",
+ "env": {
+ "BROWSENTIC_AGENT_RUN": "run-1",
+ },
+ "files": [
+ {
+ "content": "{
+ "mcpServers": {
+ "browsentic": {
+ "command": "/usr/local/bin/node",
+ "args": [
+ "/usr/local/lib/node_modules/browsentic/dist/cli.js",
+ "mcp"
+ ],
+ "env": {
+ "BROWSENTIC_AGENT_RUN": "run-1"
+ }
+ }
+ }
+ }
+ ",
+ "path": ".agents/mcp_config.json",
+ },
+ {
+ "content": "You are Browsentic.
+ ",
+ "path": "AGENTS.md",
+ },
+ ],
+ }
+ `);
+ });
+
+ test('a follow-up continues the conversation it is given', () => {
+ const args = stream({ sessionId: 'conv-1' }).args;
+ expect(args.slice(args.indexOf('--conversation'), args.indexOf('--conversation') + 2)).toEqual(['--conversation', 'conv-1']);
+ });
+
+ // Antigravity takes no per-run tool list; its own settings decide whether it may search.
+ test('research changes nothing about the plan', () => {
+ expect(stream({ research: true })).toEqual(stream());
+ });
+
+ test('the chosen model and effort are passed through', () => {
+ const args = antigravityRunner.stream(streamContext({ bin: 'agy', model: 'gemini-3-pro', effort: 'high' })).args;
+ expect(args.slice(-4)).toEqual(['--model', 'gemini-3-pro', '--effort', 'high']);
+ });
+
+ test('an effort Antigravity does not accept is dropped rather than failing the run', () => {
+ expect(antigravityRunner.stream(streamContext({ bin: 'agy', effort: 'xhigh' })).args).not.toContain('--effort');
+ });
+
+ test("yesterday's run directories are swept when a new run starts, and today's are kept", () => {
+ const base = antigravityRunner.workspace('run');
+ const [old, recent] = [join(base, 'run-old'), join(base, 'run-recent')];
+ for (const dir of [old, recent]) mkdirSync(dir, { recursive: true });
+ const yesterday = (Date.now() - 25 * 60 * 60_000) / 1000;
+ utimesSync(old, yesterday, yesterday);
+ stream({ runId: 'run-new' });
+ expect([existsSync(old), existsSync(recent)]).toEqual([false, true]);
+ });
+});
+
+describe('a one-shot task', () => {
+ test('a task runs in its own directory, with no server and instructions that say it is scratch space', () => {
+ expect(shown(antigravityRunner.json(jsonContext(settings)))).toMatchInlineSnapshot(`
+ {
+ "args": [
+ "-p",
+ "summarize this",
+ "--output-format",
+ "json",
+ "--print-timeout",
+ "60m",
+ ],
+ "cwd": "<state>/agents/antigravity/task",
+ "files": [
+ {
+ "content": "{
+ "mcpServers": {}
+ }
+ ",
+ "path": ".agents/mcp_config.json",
+ },
+ {
+ "content": "This directory is Browsentic scratch space. Answer the prompt exactly as it asks, and do not act on anything else you find here.
+ ",
+ "path": "AGENTS.md",
+ },
+ ],
+ }
+ `);
+ });
+
+ test('runs and tasks never share a directory, so a task cannot rewrite a running agent’s config', () => {
+ expect(antigravityRunner.workspace('run')).not.toBe(antigravityRunner.workspace('task'));
+ });
+
+ test('model and effort apply to a task too', () => {
+ const args = antigravityRunner.json(jsonContext({ bin: 'agy', model: 'gemini-3-flash', effort: 'low' })).args;
+ expect(args.slice(-4)).toEqual(['--model', 'gemini-3-flash', '--effort', 'low']);
+ });
+});
+
+describe('reading the stream', () => {
+ test('a run establishes the conversation, announces its own tool once, streams the answer and finishes', () => {
+ expect(read('run.hand-written.jsonl')).toEqual([
+ ['session', '9a1b2c3d-4e5f-4061-8a7b-8c9d0e1f2a3b'],
+ ['session', '9a1b2c3d-4e5f-4061-8a7b-8c9d0e1f2a3b'],
+ ['tool', expect.any(String), 'search_web'],
+ ['text', 'It costs '],
+ ['text', '$12 a month.'],
+ ['session', '9a1b2c3d-4e5f-4061-8a7b-8c9d0e1f2a3b'],
+ ['done', 'end_turn'],
+ ]);
+ });
+
+ test('an answer that only arrives on the result line is still said', () => {
+ expect(read('response-only.hand-written.jsonl')).toEqual([
+ ['session', '0f1e2d3c-4b5a-4968-8776-655443322110'],
+ ['session', '0f1e2d3c-4b5a-4968-8776-655443322110'],
+ ['text', 'Signed in and opened the orders page.'],
+ ['done', 'end_turn'],
+ ]);
+ });
+
+ test('an error on the result line fails the run with it', () => {
+ expect(read('error.hand-written.jsonl').slice(-1)).toEqual([['fail', 'AGENT_FAILED', 'quota exceeded for this model']]);
+ });
+
+ test('a cancelled run fails, and names the status', () => {
+ expect(readLines({ event: 'result', status: 'cancelled' })).toEqual([['fail', 'AGENT_FAILED', 'Antigravity ended the run: cancelled']]);
+ });
+
+ test('any other status finishes the run under that name', () => {
+ expect(readLines({ event: 'result', status: 'max_steps' })).toEqual([['done', 'max_steps']]);
+ });
+
+ test('lines it does not understand are passed over', () => {
+ expect(readThrough(antigravityRunner, ['not json', '{"event":"heartbeat"}', '{"event":"step_update"}', '{"event":"init"}'])).toEqual([]);
+ });
+});
+
+describe('the answer to a one-shot task', () => {
+ test('is the response on the result', () => {
+ expect(antigravityRunner.answer('{"result":{"status":"success","response":"A pricing page."}}')).toEqual({ text: 'A pricing page.' });
+ });
+
+ test('is found on the last line when the CLI printed something first', () => {
+ expect(antigravityRunner.answer('Loading model…\n{"status":"success","response":"A pricing page."}\n')).toEqual({ text: 'A pricing page.' });
+ });
+
+ test('an error is the error', () => {
+ expect(antigravityRunner.answer('{"result":{"error":"quota exceeded"}}')).toEqual({ error: 'quota exceeded' });
+ });
+
+ test('output with no JSON in it is no answer', () => {
+ expect(antigravityRunner.answer('panic: nil map')).toEqual({});
+ });
+});
+
+describe('what a failed start is explained as', () => {
+ test('a soft-denied tool names the rule to add and where', () => {
+ expect(antigravityRunner.hint?.('tool call soft-denied: mcp(browsentic/page_click)')).toBe(
+ `Antigravity denied a tool call because it has no permission rule for Browsentic. Add "${MCP_RULE}" to permissions.allow in ${settingsPath}, or grant it from the Browsentic popup. (tool call soft-denied: mcp(browsentic/page_click))`,
+ );
+ });
+
+ test('a signed-out Antigravity is told to sign in', () => {
+ expect(antigravityRunner.hint?.('error: no credentials found')).toBe(
+ 'Antigravity is installed but not signed in. Run "agy" once and complete the login, then try again. (error: no credentials found)',
+ );
+ });
+
+ test('an Antigravity too old for the flags is told to update', () => {
+ expect(antigravityRunner.hint?.('Error: unknown flag: --print-timeout')).toBe(
+ 'Your Antigravity CLI does not understand the flags Browsentic uses. Update it, then try again. (Error: unknown flag: --print-timeout)',
+ );
+ });
+
+ test('anything else is left to the exit code', () => {
+ expect(antigravityRunner.hint?.('segmentation fault')).toBeNull();
+ });
+});
+
+describe('readiness', () => {
+ const writeSettings = (value: unknown) => {
+ mkdirSync(dirname(settingsPath), { recursive: true });
+ writeFileSync(settingsPath, JSON.stringify(value));
+ };
+ const storedSettings = () => JSON.parse(readFileSync(settingsPath, 'utf8')) as unknown;
+
+ beforeEach(() => {
+ rmSync(join(homedir(), '.gemini'), { recursive: true, force: true });
+ });
+
+ test('with no rule for Browsentic it needs a permission it can grant', async () => {
+ expect(await antigravityRunner.check?.(settings)).toEqual({
+ code: 'AGENT_NEEDS_PERMISSION',
+ message: 'Antigravity soft-denies MCP tools it has no rule for, so browser actions would be refused.',
+ fix: `Add "${MCP_RULE}" to permissions.allow in ${settingsPath}.`,
+ grantable: true,
+ });
+ });
+
+ test('a blanket MCP rule the user wrote is enough', async () => {
+ writeSettings({ permissions: { allow: ['mcp(*)'] } });
+ expect(await antigravityRunner.check?.(settings)).toBeNull();
+ });
+
+ test('a deny rule the user wrote is reported and not offered as a fix', async () => {
+ writeSettings({ permissions: { deny: [MCP_RULE] } });
+ expect(await antigravityRunner.check?.(settings)).toMatchObject({ grantable: false, fix: `Remove the matching entry from permissions.deny in ${settingsPath}.` });
+ });
+
+ test("granting adds exactly the one rule and keeps everything else the user wrote", async () => {
+ writeSettings({ theme: 'dark', permissions: { allow: ['shell(ls)'], ask: ['shell(*)'] } });
+ expect(await antigravityRunner.grant?.()).toBeNull();
+ expect(storedSettings()).toEqual({ theme: 'dark', permissions: { allow: ['shell(ls)', MCP_RULE], ask: ['shell(*)'] } });
+ });
+
+ test('granting creates the settings file when there is none, and then the check passes', async () => {
+ await antigravityRunner.grant?.();
+ expect([storedSettings(), await antigravityRunner.check?.(settings)]).toEqual([{ permissions: { allow: [MCP_RULE] } }, null]);
+ });
+
+ test('granting twice adds the rule once', async () => {
+ await antigravityRunner.grant?.();
+ await antigravityRunner.grant?.();
+ expect(storedSettings()).toEqual({ permissions: { allow: [MCP_RULE] } });
+ });
+
+ test('granting never overrules a deny rule, and leaves the file alone', async () => {
+ writeSettings({ permissions: { deny: ['mcp(*)'] } });
+ expect(await antigravityRunner.grant?.()).toMatchObject({ code: 'AGENT_NEEDS_PERMISSION' });
+ expect(storedSettings()).toEqual({ permissions: { deny: ['mcp(*)'] } });
+ });
+
+ test('a settings file that cannot be written is reported with the rule to add by hand', async () => {
+ mkdirSync(join(homedir(), '.gemini'), { recursive: true });
+ writeFileSync(dirname(settingsPath), 'a file where the directory should be');
+ expect(await antigravityRunner.grant?.()).toMatchObject({ code: 'AGENT_NEEDS_PERMISSION', fix: `Add "${MCP_RULE}" to permissions.allow yourself.` });
+ });
+});
+
+describe("the user's own skills", () => {
+ const index = join(homedir(), '.gemini', 'antigravity', 'skills.txt');
+
+ beforeEach(() => {
+ rmSync(join(homedir(), '.gemini'), { recursive: true, force: true });
+ });
+
+ test('are listed from each root in its skills index', () => {
+ mkdirSync(dirname(index), { recursive: true });
+ writeFileSync(index, '/work/team-skills\n\n /Users/me/antigravity \n');
+ expect(antigravityRunner.skillDirs?.()).toEqual(['/work/team-skills/skills', '/Users/me/antigravity/skills']);
+ });
+
+ test('are none when there is no index', () => {
+ expect(antigravityRunner.skillDirs?.()).toEqual([]);
+ });
+});
+
+test('its run and task directories live under the state directory', () => {
+ expect([antigravityRunner.workspace('run'), antigravityRunner.workspace('task')]).toEqual([
+ join(stateDir, 'agents', 'antigravity', 'run'),
+ join(stateDir, 'agents', 'antigravity', 'task'),
+ ]);
+});
diff --git a/src/daemon/agent/runners/claude.test.ts b/src/daemon/agent/runners/claude.test.ts
index c50750b..82a20a9 100644
--- a/src/daemon/agent/runners/claude.test.ts
+++ b/src/daemon/agent/runners/claude.test.ts
@@ -1,43 +1,240 @@
-import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
import { describe, expect, test } from 'vitest';
+import { stateDir } from '../../lockfile';
import { claudeRunner } from './claude';
-import type { StreamSink } from './types';
-
-type Signal = keyof StreamSink;
-type Call = [Signal, ...unknown[]];
-
-const transcript = (name: string) =>
- readFileSync(new URL(`./fixtures/claude/${name}`, import.meta.url), 'utf8')
- .split('\n')
- .filter((line) => line.trim() && !line.startsWith('#'));
-
-const read = (lines: string[], only?: Signal): Call[] => {
- const calls: Call[] = [];
- const record = (signal: Signal) => (...args: unknown[]) => void calls.push([signal, ...args]);
- const sink: StreamSink = {
- text: record('text'),
- tool: record('tool'),
- session: record('session'),
- usage: record('usage'),
- done: record('done'),
- fail: record('fail'),
- };
- const reader = claudeRunner.reader();
- for (const line of lines) reader(line, sink);
- return only ? calls.filter(([signal]) => signal === only) : calls;
-};
+import { jsonContext, readThrough, shown, streamContext, transcript, valueOf, valuesOf } from './fixtures/support';
+
+const settings = { bin: 'claude' };
+const stream = (overrides: Parameters<typeof streamContext>[1] = {}) => claudeRunner.stream(streamContext(settings, overrides));
+const json = (overrides: Parameters<typeof jsonContext>[1] = {}) => claudeRunner.json(jsonContext(settings, overrides));
+const read = (name: string, only?: Parameters<typeof readThrough>[2]) => readThrough(claudeRunner, transcript('claude', name), only);
+const readLines = (...lines: object[]) => readThrough(claudeRunner, lines.map((line) => JSON.stringify(line)));
+
+describe('a streamed run', () => {
+ test('a fresh run starts a session of its own and reaches only the browser', () => {
+ expect(shown(stream())).toMatchInlineSnapshot(`
+ {
+ "args": [
+ "-p",
+ "what does this page cost",
+ "--output-format",
+ "stream-json",
+ "--include-partial-messages",
+ "--verbose",
+ "--mcp-config",
+ "{"mcpServers":{"browsentic":{"command":"/usr/local/bin/node","args":["/usr/local/lib/node_modules/browsentic/dist/cli.js","mcp"],"env":{"BROWSENTIC_AGENT_RUN":"run-1"}}}}",
+ "--strict-mcp-config",
+ "--tools",
+ "",
+ "--allowedTools",
+ "mcp__browsentic",
+ "--disallowedTools",
+ "Bash",
+ "Edit",
+ "Write",
+ "NotebookEdit",
+ "Glob",
+ "Grep",
+ "Read",
+ "Task",
+ "Monitor",
+ "Workflow",
+ "Skill",
+ "ToolSearch",
+ "SendMessage",
+ "TaskOutput",
+ "TaskStop",
+ "TodoWrite",
+ "ReportFindings",
+ "CronCreate",
+ "CronDelete",
+ "CronList",
+ "ScheduleWakeup",
+ "RemoteTrigger",
+ "PushNotification",
+ "DesignSync",
+ "EnterWorktree",
+ "ExitWorktree",
+ "WebSearch",
+ "WebFetch",
+ "--append-system-prompt",
+ "You are Browsentic.",
+ "--session-id",
+ "<uuid>",
+ ],
+ "cwd": "<state>",
+ "env": {
+ "BROWSENTIC_AGENT_RUN": "run-1",
+ },
+ }
+ `);
+ });
+
+ test('a follow-up resumes the session it is given instead of starting one', () => {
+ const args = stream({ sessionId: 'sess-1' }).args;
+ expect([valueOf(args, '--resume'), args.includes('--session-id')]).toEqual(['sess-1', false]);
+ });
+
+ test('research hands it the web tools and takes them off the deny list', () => {
+ const args = stream({ research: true }).args;
+ expect({
+ tools: valuesOf(args, '--tools'),
+ allowed: valuesOf(args, '--allowedTools'),
+ deniesTheWeb: valuesOf(args, '--disallowedTools').some((tool) => tool.startsWith('Web')),
+ }).toEqual({ tools: ['WebSearch', 'WebFetch'], allowed: ['mcp__browsentic', 'WebSearch', 'WebFetch'], deniesTheWeb: false });
+ });
+
+ test('the chosen model and effort are passed through', () => {
+ const args = claudeRunner.stream(streamContext({ bin: 'claude', model: 'claude-opus-5', effort: 'max' })).args;
+ expect([valueOf(args, '--model'), valueOf(args, '--effort')]).toEqual(['claude-opus-5', 'max']);
+ });
+
+ test('an effort Claude Code does not accept is dropped rather than failing the run', () => {
+ expect(claudeRunner.stream(streamContext({ bin: 'claude', effort: 'minimal' })).args).not.toContain('--effort');
+ });
+
+ test('it runs in the state directory, where its saved sessions are looked up', () => {
+ expect([claudeRunner.workspace('run'), claudeRunner.workspace('task')]).toEqual([stateDir, stateDir]);
+ });
+});
+
+describe('a one-shot task', () => {
+ test('a task reaches no browser and no tools at all', () => {
+ expect(shown(json())).toMatchInlineSnapshot(`
+ {
+ "args": [
+ "-p",
+ "summarize this",
+ "--output-format",
+ "json",
+ "--mcp-config",
+ "{"mcpServers":{}}",
+ "--strict-mcp-config",
+ "--tools",
+ "",
+ "--disallowedTools",
+ "Bash",
+ "Edit",
+ "Write",
+ "NotebookEdit",
+ "Glob",
+ "Grep",
+ "Read",
+ "Task",
+ "Monitor",
+ "Workflow",
+ "Skill",
+ "ToolSearch",
+ "SendMessage",
+ "TaskOutput",
+ "TaskStop",
+ "TodoWrite",
+ "ReportFindings",
+ "CronCreate",
+ "CronDelete",
+ "CronList",
+ "ScheduleWakeup",
+ "RemoteTrigger",
+ "PushNotification",
+ "DesignSync",
+ "EnterWorktree",
+ "ExitWorktree",
+ "WebSearch",
+ "WebFetch",
+ ],
+ "cwd": "<state>",
+ }
+ `);
+ });
+
+ test('a task that has to open a file may read, and do nothing else', () => {
+ const args = json({ reads: true }).args;
+ expect({
+ tools: valuesOf(args, '--tools'),
+ allowed: valuesOf(args, '--allowedTools'),
+ deniesRead: valuesOf(args, '--disallowedTools').includes('Read'),
+ }).toEqual({ tools: ['Read'], allowed: ['Read'], deniesRead: false });
+ });
+
+ test('model and effort apply to a task too', () => {
+ const args = claudeRunner.json(jsonContext({ bin: 'claude', model: 'claude-haiku-4-5', effort: 'low' })).args;
+ expect([valueOf(args, '--model'), valueOf(args, '--effort')]).toEqual(['claude-haiku-4-5', 'low']);
+ });
+});
+
+describe('reading the stream', () => {
+ test('a recorded turn establishes the session, says the answer and finishes', () => {
+ expect(read('2.1.278-fresh.jsonl')).toEqual([
+ ['session', '2e281281-10ef-47b8-8a23-d6137f6770f6'],
+ ['text', 'ok'],
+ ['usage', { contextTokens: 7389, outputTokens: 41 }],
+ ['done', 'end_turn'],
+ ]);
+ });
+
+ test('a recorded follow-up reports the session it resumed', () => {
+ expect(read('2.1.278-resumed.jsonl', 'session')).toEqual([['session', '2e281281-10ef-47b8-8a23-d6137f6770f6']]);
+ });
+
+ test('a model the account cannot use fails the run with what Claude Code said', () => {
+ expect(read('2.1.278-unknown-model.jsonl').filter(([signal]) => signal !== 'session')).toEqual([
+ [
+ 'fail',
+ 'AGENT_FAILED',
+ "There's an issue with the selected model (claude-nonexistent-9). It may not exist or you may not have access to it. Run --model to pick a different model.",
+ ],
+ ]);
+ });
+
+ test('a browser tool is not announced, because the daemon reports those itself', () => {
+ expect(read('tool-loop.hand-written.jsonl', 'tool')).toEqual([]);
+ });
+
+ test('its own web tools are announced under the ids Claude gave them', () => {
+ expect(read('web-search.hand-written.jsonl', 'tool')).toEqual([
+ ['tool', 'toolu_ws', 'WebSearch'],
+ ['tool', 'toolu_wf', 'WebFetch'],
+ ]);
+ });
+
+ test('nothing a subagent says, calls or spends reaches the run', () => {
+ expect(read('subagent.hand-written.jsonl')).toEqual([
+ ['session', 'c41a9e07-2f65-4b18-93d0-6e7a2b1c8f45'],
+ ['usage', { contextTokens: 5540, outputTokens: 40 }],
+ ['text', 'Done.'],
+ ['usage', { contextTokens: 6303, outputTokens: 43 }],
+ ['done', 'end_turn'],
+ ]);
+ });
+
+ test('an error with no message fails with its subtype', () => {
+ expect(readLines({ type: 'result', is_error: true, subtype: 'error_max_turns' })).toEqual([
+ ['fail', 'AGENT_FAILED', 'error_max_turns'],
+ ]);
+ });
+
+ test('a result with no stop reason finishes as end_turn', () => {
+ expect(readLines({ type: 'result', subtype: 'success' })).toEqual([['done', 'end_turn']]);
+ });
+
+ test('lines it does not understand are passed over', () => {
+ const lines = ['not json', '{"type":"rate_limit_event"}', '{"type":"system","subtype":"status"}', '{"type":"user"}'];
+ expect(readThrough(claudeRunner, lines)).toEqual([]);
+ });
+});
describe('token usage', () => {
test('a turn reports what its message finally generated, once', () => {
- expect(read(transcript('2.1.278-fresh.jsonl'), 'usage')).toEqual([['usage', { contextTokens: 7389, outputTokens: 41 }]]);
+ expect(read('2.1.278-fresh.jsonl', 'usage')).toEqual([['usage', { contextTokens: 7389, outputTokens: 41 }]]);
});
test('a resumed turn counts the cached conversation as context', () => {
- expect(read(transcript('2.1.278-resumed.jsonl'), 'usage')).toEqual([['usage', { contextTokens: 7467, outputTokens: 31 }]]);
+ expect(read('2.1.278-resumed.jsonl', 'usage')).toEqual([['usage', { contextTokens: 7467, outputTokens: 31 }]]);
});
test('output adds up across the messages of one run, and context is the latest message', () => {
- expect(read(transcript('tool-loop.hand-written.jsonl'), 'usage')).toEqual([
+ expect(read('tool-loop.hand-written.jsonl', 'usage')).toEqual([
['usage', { contextTokens: 8260, outputTokens: 60 }],
['usage', { contextTokens: 9112, outputTokens: 72 }],
]);
@@ -45,6 +242,40 @@ describe('token usage', () => {
test('a stream with no message deltas falls back to the total on the result line', () => {
const result = { type: 'result', subtype: 'success', usage: { input_tokens: 10, cache_read_input_tokens: 90, output_tokens: 5 } };
- expect(read([JSON.stringify(result)], 'usage')).toEqual([['usage', { contextTokens: 105, outputTokens: 5 }]]);
+ expect(readLines(result).filter(([signal]) => signal === 'usage')).toEqual([['usage', { contextTokens: 105, outputTokens: 5 }]]);
+ });
+});
+
+describe('the answer to a one-shot task', () => {
+ test('is the result text', () => {
+ expect(claudeRunner.answer('{"type":"result","is_error":false,"result":"A pricing page."}')).toEqual({ text: 'A pricing page.' });
+ });
+
+ test('an error result is the error', () => {
+ expect(claudeRunner.answer('{"is_error":true,"result":"Credit balance is too low"}')).toEqual({ error: 'Credit balance is too low' });
+ });
+
+ test('an error with no message names its subtype', () => {
+ expect(claudeRunner.answer('{"is_error":true,"subtype":"error_during_execution"}')).toEqual({ error: 'error_during_execution' });
+ });
+
+ test('output that is not JSON is no answer at all', () => {
+ expect(claudeRunner.answer('Segmentation fault')).toEqual({});
});
});
+
+describe('what a failed start is explained as', () => {
+ test('a Claude Code too old for the sandbox flags is told to update', () => {
+ expect(claudeRunner.hint?.("error: unknown option '--strict-mcp-config'\n")).toBe(
+ "Your Claude Code does not understand the flags Browsentic uses to sandbox a run. Update Claude Code, then try again. (error: unknown option '--strict-mcp-config')",
+ );
+ });
+
+ test('anything else is left to the exit code', () => {
+ expect(claudeRunner.hint?.('Error: connect ECONNREFUSED')).toBeNull();
+ });
+});
+
+test("the user's own skills are listed from ~/.claude/skills", () => {
+ expect(claudeRunner.skillDirs?.()).toEqual([join(homedir(), '.claude', 'skills')]);
+});
diff --git a/src/daemon/agent/runners/codex.test.ts b/src/daemon/agent/runners/codex.test.ts
new file mode 100644
index 0000000..dc1e874
--- /dev/null
+++ b/src/daemon/agent/runners/codex.test.ts
@@ -0,0 +1,266 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, test } from 'vitest';
+import { stateDir } from '../../lockfile';
+import { codexRunner } from './codex';
+import { jsonContext, readThrough, shown, streamContext, transcript } from './fixtures/support';
+
+const settings = { bin: 'codex' };
+const stream = (overrides: Parameters<typeof streamContext>[1] = {}) => codexRunner.stream(streamContext(settings, overrides));
+const read = (name: string, only?: Parameters<typeof readThrough>[2]) => readThrough(codexRunner, transcript('codex', name), only);
+const readLines = (...lines: object[]) => readThrough(codexRunner, lines.map((line) => JSON.stringify(line)));
+const recorded = (name: string) => transcript('codex', name).join('\n');
+
+describe('a streamed run', () => {
+ test('a fresh run registers the browser as its only server and stays in a read-only sandbox', () => {
+ expect(shown(stream())).toMatchInlineSnapshot(`
+ {
+ "args": [
+ "exec",
+ "--json",
+ "-c",
+ "sandbox_mode="read-only"",
+ "-c",
+ "approval_policy="never"",
+ "--skip-git-repo-check",
+ "-c",
+ "mcp_servers.browsentic.command="/usr/local/bin/node"",
+ "-c",
+ "mcp_servers.browsentic.args=["/usr/local/lib/node_modules/browsentic/dist/cli.js","mcp"]",
+ "-c",
+ "mcp_servers.browsentic.env={BROWSENTIC_AGENT_RUN="run-1"}",
+ "-c",
+ "mcp_servers.browsentic.required=true",
+ "-c",
+ "mcp_servers.browsentic.default_tools_approval_mode="approve"",
+ "-c",
+ "developer_instructions="You are Browsentic."",
+ "-c",
+ "tools.web_search=false",
+ "--",
+ "what does this page cost",
+ ],
+ "cwd": "<state>",
+ "env": {
+ "BROWSENTIC_AGENT_RUN": "run-1",
+ },
+ }
+ `);
+ });
+
+ // `exec resume` takes neither --sandbox nor --ask-for-approval, which is why both are config.
+ test('a follow-up resumes the thread and keeps its sandbox, set as config rather than flags', () => {
+ const args = stream({ sessionId: 'thread-1' }).args;
+ expect({
+ command: args.slice(0, 3),
+ sandbox: args.includes('sandbox_mode="read-only"') && args.includes('approval_policy="never"'),
+ flags: args.filter((arg) => /^--(sandbox|ask-for-approval|full-auto)/.test(arg)),
+ }).toEqual({ command: ['exec', 'resume', 'thread-1'], sandbox: true, flags: [] });
+ });
+
+ test("the Browsentic server's tools are approved up front, because headless Codex refuses what it would ask about", () => {
+ expect(stream().args).toContain('mcp_servers.browsentic.default_tools_approval_mode="approve"');
+ });
+
+ test('research turns web search on, and it is off otherwise', () => {
+ expect([stream({ research: true }).args, stream().args].map((args) => args.find((arg) => arg.startsWith('tools.web_search=')))).toEqual([
+ 'tools.web_search=true',
+ 'tools.web_search=false',
+ ]);
+ });
+
+ test('the chosen model and effort are passed through', () => {
+ const args = codexRunner.stream(streamContext({ bin: 'codex', model: 'gpt-5.4', effort: 'xhigh' })).args;
+ expect([args[args.indexOf('--model') + 1], args.find((arg) => arg.startsWith('model_reasoning_effort='))]).toEqual([
+ 'gpt-5.4',
+ 'model_reasoning_effort="xhigh"',
+ ]);
+ });
+
+ test('an effort Codex does not accept is dropped rather than failing the run', () => {
+ const args = codexRunner.stream(streamContext({ bin: 'codex', effort: 'max' })).args;
+ expect(args.some((arg) => arg.startsWith('model_reasoning_effort='))).toBe(false);
+ });
+
+ test('an instruction that looks like a flag is still the prompt', () => {
+ expect(stream({ instruction: '--help me find the pricing page' }).args.slice(-2)).toEqual(['--', '--help me find the pricing page']);
+ });
+
+ test('a system prompt with quotes and line breaks survives as one TOML string', () => {
+ const instructions = stream({ systemPrompt: 'Rule one.\nSay "done" when done.' }).args.find((arg) => arg.startsWith('developer_instructions='));
+ expect(instructions).toBe('developer_instructions="Rule one.\\nSay \\"done\\" when done."');
+ });
+
+ test('it runs in the state directory, where its saved threads are looked up', () => {
+ expect([codexRunner.workspace('run'), codexRunner.workspace('task')]).toEqual([stateDir, stateDir]);
+ });
+});
+
+describe('a one-shot task', () => {
+ test('a task is ephemeral, reaches no server and cannot search', () => {
+ expect(shown(codexRunner.json(jsonContext(settings)))).toMatchInlineSnapshot(`
+ {
+ "args": [
+ "exec",
+ "--json",
+ "--ephemeral",
+ "-c",
+ "sandbox_mode="read-only"",
+ "-c",
+ "approval_policy="never"",
+ "--skip-git-repo-check",
+ "-c",
+ "mcp_servers={}",
+ "-c",
+ "tools.web_search=false",
+ "--",
+ "summarize this",
+ ],
+ "cwd": "<state>",
+ }
+ `);
+ });
+
+ test('model and effort apply to a task too', () => {
+ const args = codexRunner.json(jsonContext({ bin: 'codex', model: 'gpt-5.4-mini', effort: 'low' })).args;
+ expect([args[args.indexOf('--model') + 1], args.find((arg) => arg.startsWith('model_reasoning_effort='))]).toEqual([
+ 'gpt-5.4-mini',
+ 'model_reasoning_effort="low"',
+ ]);
+ });
+});
+
+describe('reading the stream', () => {
+ test('a recorded turn establishes the thread, says the answer and finishes', () => {
+ expect(read('0.155.1-fresh.jsonl')).toEqual([
+ ['session', '01a0c578-947f-7460-aa12-a9987c8ec2d5'],
+ ['text', 'ok'],
+ ['usage', { contextTokens: 14611, outputTokens: 5 }],
+ ['done', 'end_turn'],
+ ]);
+ });
+
+ test('a recorded follow-up reports the thread it resumed', () => {
+ expect(read('0.155.1-resumed.jsonl')).toEqual([
+ ['session', '01a0c578-947f-7460-aa12-a9987c8ec2d5'],
+ ['text', 'done'],
+ ['usage', { contextTokens: 29803, outputTokens: 10 }],
+ ['done', 'end_turn'],
+ ]);
+ });
+
+ test('a refused model fails the run with the sentence from the API, and says what to do', () => {
+ const calls = read('0.155.1-unknown-model.jsonl');
+ expect([calls.find(([signal]) => signal === 'fail'), calls.some(([signal]) => signal === 'done')]).toEqual([
+ [
+ 'fail',
+ 'AGENT_FAILED',
+ "The 'gpt-nonexistent-9' model is not supported when using Codex with a ChatGPT account. Pick another model for Codex in the Browsentic popup, then try again.",
+ ],
+ false,
+ ]);
+ });
+
+ test('a message sent as growing snapshots is said once, and the next message in full', () => {
+ expect(read('snapshots.hand-written.jsonl')).toEqual([
+ ['session', '01a0c580-1d2e-7f30-8a41-5b6c7d8e9f00'],
+ ['text', 'Looking'],
+ ['text', ' it up'],
+ ['text', '.'],
+ ['tool', 'item_1', 'web_search'],
+ ['text', 'It costs $12 a month.'],
+ ['usage', { contextTokens: 20045, outputTokens: 45 }],
+ ['done', 'end_turn'],
+ ]);
+ });
+
+ test('the older protocol is read too, without repeating the message its deltas already said', () => {
+ expect(read('legacy.hand-written.jsonl')).toEqual([
+ ['session', '3e9a7b21-6c4d-4f80-b1a2-9d8e7f6c5b4a'],
+ ['text', 'It costs '],
+ ['text', '$12.'],
+ ['tool', expect.any(String), 'web_search'],
+ ['usage', { contextTokens: 16030, outputTokens: 80 }],
+ ['done', 'end_turn'],
+ ]);
+ });
+
+ test('an older error fails the run', () => {
+ expect(readLines({ msg: { type: 'error', message: 'stream disconnected before completion' } })).toEqual([
+ ['fail', 'AGENT_FAILED', 'stream disconnected before completion'],
+ ]);
+ });
+
+ test('a failure with nothing to say still fails, in words', () => {
+ expect(readLines({ type: 'turn.failed' }, { type: 'error' }, { msg: { type: 'error' } })).toEqual([
+ ['fail', 'AGENT_FAILED', 'Codex could not finish the turn'],
+ ['fail', 'AGENT_FAILED', 'Codex reported an error'],
+ ['fail', 'AGENT_FAILED', 'Codex reported an error'],
+ ]);
+ });
+
+ test('a model that does not exist is explained the same way as a refused one', () => {
+ const message = JSON.stringify({ error: { message: 'The model `gpt-9` does not exist' } });
+ expect(readLines({ type: 'error', message })).toEqual([
+ ['fail', 'AGENT_FAILED', 'The model `gpt-9` does not exist Pick another model for Codex in the Browsentic popup, then try again.'],
+ ]);
+ });
+
+ test('lines it does not understand are passed over', () => {
+ expect(readThrough(codexRunner, ['not json', '{"type":"turn.started"}', '{"msg":{"type":"exec_command_begin"}}', '{"type":"thread.started"}'])).toEqual(
+ [],
+ );
+ });
+});
+
+describe('the answer to a one-shot task', () => {
+ test('is the last message it completed', () => {
+ expect(codexRunner.answer(recorded('0.155.1-fresh.jsonl'))).toEqual({ text: 'ok' });
+ });
+
+ test('a refused model is an error, not an answer', () => {
+ expect(codexRunner.answer(recorded('0.155.1-unknown-model.jsonl')).error).toContain(
+ "The 'gpt-nonexistent-9' model is not supported when using Codex with a ChatGPT account.",
+ );
+ });
+
+ test('the older protocol answers too', () => {
+ expect(codexRunner.answer('{"msg":{"type":"agent_message","message":"A pricing page."}}')).toEqual({ text: 'A pricing page.' });
+ });
+
+ test('an older error is the error', () => {
+ expect(codexRunner.answer('{"msg":{"type":"error","error":"quota exceeded"}}')).toEqual({ error: 'quota exceeded' });
+ });
+
+ test('output with no message is no answer', () => {
+ expect(codexRunner.answer('Reading additional input from stdin...')).toEqual({});
+ });
+});
+
+describe('what a failed start is explained as', () => {
+ test('an untrusted directory names the one to trust', () => {
+ expect(codexRunner.hint?.('Error: Not inside a trusted directory and --skip-git-repo-check was not specified.')).toBe(
+ `Codex refused to run in ${stateDir}. Run "codex" there once and trust the directory, then try again.`,
+ );
+ });
+
+ test('a signed-out Codex is told to log in', () => {
+ expect(codexRunner.hint?.('unexpected status 401 Unauthorized')).toBe(
+ 'Codex is installed but not signed in. Run "codex login", then try again.',
+ );
+ });
+
+ test('a Codex too old for the flags is told to update', () => {
+ expect(codexRunner.hint?.("error: unexpected argument '--json' found\n")).toBe(
+ "Your Codex does not understand the flags Browsentic uses. Update Codex, then try again. (error: unexpected argument '--json' found)",
+ );
+ });
+
+ test('anything else is left to the exit code', () => {
+ expect(codexRunner.hint?.('thread panicked')).toBeNull();
+ });
+});
+
+test("the user's own skills and prompts are listed from ~/.codex", () => {
+ expect(codexRunner.skillDirs?.()).toEqual([join(homedir(), '.codex', 'skills'), join(homedir(), '.codex', 'prompts')]);
+});
diff --git a/src/daemon/agent/runners/fixtures/README.md b/src/daemon/agent/runners/fixtures/README.md
new file mode 100644
index 0000000..74adad0
--- /dev/null
+++ b/src/daemon/agent/runners/fixtures/README.md
@@ -0,0 +1,12 @@
+# Agent CLI transcripts
+
+What each agent CLI printed on stdout, one event per line, for the reader tests in `../<agent>.test.ts`.
+
+- `<cli version>-<case>.jsonl` was recorded from that version of the real CLI. The only edits are to
+ Claude Code's `init` line, where the working directory became `/Users/you/.browsentic` and the
+ recording machine's slash commands, agents, skills, plugins and memory paths were emptied, and to
+ its `rate_limit_event`, which keeps only its status.
+- `<case>.hand-written.jsonl` was written from the reader code, for streams a contained run cannot
+ produce or a CLI that was not installed. Its first line says so.
+
+Lines starting with `#` are comments, and the tests skip them.
diff --git a/src/daemon/agent/runners/fixtures/antigravity/error.hand-written.jsonl b/src/daemon/agent/runners/fixtures/antigravity/error.hand-written.jsonl
new file mode 100644
index 0000000..10f9ab5
--- /dev/null
+++ b/src/daemon/agent/runners/fixtures/antigravity/error.hand-written.jsonl
@@ -0,0 +1,4 @@
+# Hand-written from antigravity.ts's reader, not recorded: agy is not installed where this was written. A run the CLI ends with an error after it has started talking.
+{"event":"init","conversation_id":"5e6f7a8b-9c0d-41e2-83f4-a5b6c7d8e9f0"}
+{"event":"step_update","step_update":{"step_index":0,"step_type":"response","text_delta":"Opening the page"}}
+{"event":"result","result":{"conversation_id":"5e6f7a8b-9c0d-41e2-83f4-a5b6c7d8e9f0","status":"error","error":"quota exceeded for this model"}}
diff --git a/src/daemon/agent/runners/fixtures/antigravity/response-only.hand-written.jsonl b/src/daemon/agent/runners/fixtures/antigravity/response-only.hand-written.jsonl
new file mode 100644
index 0000000..3caa69a
--- /dev/null
+++ b/src/daemon/agent/runners/fixtures/antigravity/response-only.hand-written.jsonl
@@ -0,0 +1,3 @@
+# Hand-written from antigravity.ts's reader, not recorded: agy is not installed where this was written. A run that streams nothing and puts its whole answer on the result line, flat rather than nested.
+{"event":"init","init":{"conversation_id":"0f1e2d3c-4b5a-4968-8776-655443322110"}}
+{"event":"result","conversation_id":"0f1e2d3c-4b5a-4968-8776-655443322110","status":"success","response":"Signed in and opened the orders page."}
diff --git a/src/daemon/agent/runners/fixtures/antigravity/run.hand-written.jsonl b/src/daemon/agent/runners/fixtures/antigravity/run.hand-written.jsonl
new file mode 100644
index 0000000..2619417
--- /dev/null
+++ b/src/daemon/agent/runners/fixtures/antigravity/run.hand-written.jsonl
@@ -0,0 +1,9 @@
+# Hand-written from antigravity.ts's reader, not recorded: agy is not installed where this was written. A run that streams its answer, calls one Browsentic tool and one of its own, and reports each step while it runs and again when it finishes.
+{"event":"init","conversation_id":"9a1b2c3d-4e5f-4061-8a7b-8c9d0e1f2a3b"}
+{"event":"step_update","step_update":{"conversation_id":"9a1b2c3d-4e5f-4061-8a7b-8c9d0e1f2a3b","step_index":0,"step_type":"tool","state":"running","tool_name":"browsentic/page_getPageInfo"}}
+{"event":"step_update","step_update":{"step_index":0,"step_type":"tool","state":"done","tool_name":"browsentic/page_getPageInfo"}}
+{"event":"step_update","step_update":{"step_index":1,"step_type":"tool","state":"running","tool_info":{"name":"search_web"}}}
+{"event":"step_update","step_update":{"step_index":1,"step_type":"tool","state":"done","tool_info":{"name":"search_web"}}}
+{"event":"step_update","step_update":{"step_index":2,"step_type":"response","text_delta":"It costs "}}
+{"event":"step_update","step_update":{"step_index":2,"step_type":"response","text_delta":"$12 a month."}}
+{"event":"result","result":{"conversation_id":"9a1b2c3d-4e5f-4061-8a7b-8c9d0e1f2a3b","status":"success","response":"It costs $12 a month."}}
diff --git a/src/daemon/agent/runners/fixtures/claude/2.1.278-unknown-model.jsonl b/src/daemon/agent/runners/fixtures/claude/2.1.278-unknown-model.jsonl
new file mode 100644
index 0000000..f165b44
--- /dev/null
+++ b/src/daemon/agent/runners/fixtures/claude/2.1.278-unknown-model.jsonl
@@ -0,0 +1,4 @@
+{"type":"system","subtype":"init","cwd":"/Users/you/.browsentic","session_id":"67d835e0-e35e-4671-9590-370062aa0516","tools":[],"mcp_servers":[],"model":"claude-nonexistent-9","permissionMode":"default","slash_commands":[],"terminal_slash_commands":[],"apiKeySource":"none","claude_code_version":"2.1.278","output_style":"default","agents":[],"skills":[],"plugins":[],"capabilities":["interrupt_receipt_v1","interrupt_cancel_queued_v1","msg_lifecycle_v1"],"analytics_disabled":false,"product_feedback_disabled":false,"uuid":"573f003f-a690-4e5d-920c-3ba7b8b1bce7","memory_paths":{},"fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required"}
+{"type":"system","subtype":"status","status":"requesting","session_id":"67d835e0-e35e-4671-9590-370062aa0516","uuid":"5cac414a-78b8-48bc-96f8-434bc8b8669b"}
+{"type":"assistant","message":{"diagnostics":null,"id":"8779790f-42a1-40dc-9c37-7326a0f3c41f","container":null,"model":"<synthetic>","role":"assistant","stop_details":null,"stop_reason":"stop_sequence","stop_sequence":"","type":"message","usage":{"output_tokens_details":null,"input_tokens":0,"output_tokens":0,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":null,"cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":0},"inference_geo":null,"iterations":null,"speed":null},"content":[{"type":"text","text":"There's an issue with the selected model (claude-nonexistent-9). It may not exist or you may not have access to it. Run --model to pick a different model."}],"context_management":null},"parent_tool_use_id":null,"session_id":"67d835e0-e35e-4671-9590-370062aa0516","uuid":"c1606b3c-e92c-4686-a37f-befe0d279515","timestamp":"2026-09-21T19:43:45.121Z","error":"model_not_found","request_id":"req_011CfHA4XGyQigeqLQo89gb4","is_api_error_message":true}
+{"duration_api_ms":0,"stop_reason":"stop_sequence","session_id":"67d835e0-e35e-4671-9590-370062aa0516","total_cost_usd":0,"usage":{"output_tokens_details":{"thinking_tokens":0},"input_tokens":0,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":0,"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":0},"inference_geo":"","iterations":[],"speed":"standard"},"modelUsage":{},"permission_denials":[],"terminal_reason":"api_error","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"is_error":true,"num_turns":1,"subtype":"success","api_error_status":404,"result":"There's an issue with the selected model (claude-nonexistent-9). It may not exist or you may not have access to it. Run --model to pick a different model.","type":"result","duration_ms":704,"uuid":"c92fcca0-fafc-47d3-a2da-59e84e7815a9","queued_turn_count":0,"result_index":0}
diff --git a/src/daemon/agent/runners/fixtures/claude/subagent.hand-written.jsonl b/src/daemon/agent/runners/fixtures/claude/subagent.hand-written.jsonl
new file mode 100644
index 0000000..5e9e290
--- /dev/null
+++ b/src/daemon/agent/runners/fixtures/claude/subagent.hand-written.jsonl
@@ -0,0 +1,14 @@
+# Hand-written from claude.ts's reader, not recorded. Everything a subagent says arrives tagged with the parent_tool_use_id that spawned it, and none of it is the run's own answer.
+{"type":"system","subtype":"init","session_id":"c41a9e07-2f65-4b18-93d0-6e7a2b1c8f45","tools":["Agent"],"model":"claude-sonnet-5"}
+{"type":"stream_event","parent_tool_use_id":null,"event":{"type":"message_start","message":{"usage":{"input_tokens":500,"cache_read_input_tokens":5000,"cache_creation_input_tokens":0,"output_tokens":1}}}}
+{"type":"stream_event","parent_tool_use_id":null,"event":{"type":"content_block_start","index":0,"content_block":{"type":"tool_use","id":"toolu_task","name":"Agent"}}}
+{"type":"stream_event","parent_tool_use_id":null,"event":{"type":"message_delta","delta":{"stop_reason":"tool_use"},"usage":{"output_tokens":40}}}
+{"type":"stream_event","parent_tool_use_id":"toolu_task","event":{"type":"message_start","message":{"usage":{"input_tokens":9000,"cache_read_input_tokens":0,"cache_creation_input_tokens":0,"output_tokens":1}}}}
+{"type":"stream_event","parent_tool_use_id":"toolu_task","event":{"type":"content_block_start","index":0,"content_block":{"type":"tool_use","id":"toolu_sub_ws","name":"WebSearch"}}}
+{"type":"stream_event","parent_tool_use_id":"toolu_task","event":{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Subagent notes nobody asked to see."}}}
+{"type":"stream_event","parent_tool_use_id":"toolu_task","event":{"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":700}}}
+{"type":"assistant","parent_tool_use_id":"toolu_task","message":{"content":[{"type":"text","text":"Subagent notes nobody asked to see."}],"usage":{"input_tokens":9000,"output_tokens":700}}}
+{"type":"stream_event","parent_tool_use_id":null,"event":{"type":"message_start","message":{"usage":{"input_tokens":800,"cache_read_input_tokens":5500,"cache_creation_input_tokens":0,"output_tokens":1}}}}
+{"type":"stream_event","parent_tool_use_id":null,"event":{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Done."}}}
+{"type":"stream_event","parent_tool_use_id":null,"event":{"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":3}}}
+{"type":"result","subtype":"success","is_error":false,"stop_reason":"end_turn","result":"Done.","session_id":"c41a9e07-2f65-4b18-93d0-6e7a2b1c8f45"}
diff --git a/src/daemon/agent/runners/fixtures/claude/web-search.hand-written.jsonl b/src/daemon/agent/runners/fixtures/claude/web-search.hand-written.jsonl
new file mode 100644
index 0000000..5f7cb9d
--- /dev/null
+++ b/src/daemon/agent/runners/fixtures/claude/web-search.hand-written.jsonl
@@ -0,0 +1,14 @@
+# Hand-written from claude.ts's reader, not recorded. A research run: Claude's own WebSearch and WebFetch are tools the daemon cannot see, so the reader announces them.
+{"type":"system","subtype":"init","session_id":"7d3f1c20-8b4a-4e59-a6d2-0c9e1f3b5a77","tools":["WebSearch","WebFetch","mcp__browsentic__page_getPageInfo"],"model":"claude-sonnet-5"}
+{"type":"stream_event","parent_tool_use_id":null,"event":{"type":"message_start","message":{"usage":{"input_tokens":400,"cache_read_input_tokens":6000,"cache_creation_input_tokens":0,"output_tokens":1}}}}
+{"type":"stream_event","parent_tool_use_id":null,"event":{"type":"content_block_start","index":0,"content_block":{"type":"tool_use","id":"toolu_ws","name":"WebSearch"}}}
+{"type":"stream_event","parent_tool_use_id":null,"event":{"type":"content_block_stop","index":0}}
+{"type":"stream_event","parent_tool_use_id":null,"event":{"type":"content_block_start","index":1,"content_block":{"type":"tool_use","id":"toolu_wf","name":"WebFetch"}}}
+{"type":"stream_event","parent_tool_use_id":null,"event":{"type":"content_block_stop","index":1}}
+{"type":"stream_event","parent_tool_use_id":null,"event":{"type":"content_block_start","index":2,"content_block":{"type":"tool_use","id":"toolu_mcp","name":"mcp__browsentic__page_getPageInfo"}}}
+{"type":"stream_event","parent_tool_use_id":null,"event":{"type":"content_block_stop","index":2}}
+{"type":"stream_event","parent_tool_use_id":null,"event":{"type":"message_delta","delta":{"stop_reason":"tool_use"},"usage":{"output_tokens":90}}}
+{"type":"stream_event","parent_tool_use_id":null,"event":{"type":"message_start","message":{"usage":{"input_tokens":3000,"cache_read_input_tokens":6400,"cache_creation_input_tokens":0,"output_tokens":1}}}}
+{"type":"stream_event","parent_tool_use_id":null,"event":{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Their docs list three plans."}}}
+{"type":"stream_event","parent_tool_use_id":null,"event":{"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":20}}}
+{"type":"result","subtype":"success","is_error":false,"stop_reason":"end_turn","result":"Their docs list three plans.","session_id":"7d3f1c20-8b4a-4e59-a6d2-0c9e1f3b5a77"}
diff --git a/src/daemon/agent/runners/fixtures/codex/0.155.1-fresh.jsonl b/src/daemon/agent/runners/fixtures/codex/0.155.1-fresh.jsonl
new file mode 100644
index 0000000..06d0c27
--- /dev/null
+++ b/src/daemon/agent/runners/fixtures/codex/0.155.1-fresh.jsonl
@@ -0,0 +1,4 @@
+{"type":"thread.started","thread_id":"01a0c578-947f-7460-aa12-a9987c8ec2d5"}
+{"type":"turn.started"}
+{"type":"item.completed","item":{"id":"item_0","type":"agent_message","text":"ok"}}
+{"type":"turn.completed","usage":{"input_tokens":14606,"cached_input_tokens":0,"cache_write_input_tokens":0,"output_tokens":5,"reasoning_output_tokens":0}}
diff --git a/src/daemon/agent/runners/fixtures/codex/0.155.1-resumed.jsonl b/src/daemon/agent/runners/fixtures/codex/0.155.1-resumed.jsonl
new file mode 100644
index 0000000..4f6c3d0
--- /dev/null
+++ b/src/daemon/agent/runners/fixtures/codex/0.155.1-resumed.jsonl
@@ -0,0 +1,4 @@
+{"type":"thread.started","thread_id":"01a0c578-947f-7460-aa12-a9987c8ec2d5"}
+{"type":"turn.started"}
+{"type":"item.completed","item":{"id":"item_0","type":"agent_message","text":"done"}}
+{"type":"turn.completed","usage":{"input_tokens":29793,"cached_input_tokens":14080,"cache_write_input_tokens":0,"output_tokens":10,"reasoning_output_tokens":0}}
diff --git a/src/daemon/agent/runners/fixtures/codex/0.155.1-unknown-model.jsonl b/src/daemon/agent/runners/fixtures/codex/0.155.1-unknown-model.jsonl
new file mode 100644
index 0000000..c0ae7b5
--- /dev/null
+++ b/src/daemon/agent/runners/fixtures/codex/0.155.1-unknown-model.jsonl
@@ -0,0 +1,5 @@
+{"type":"thread.started","thread_id":"01a0c57e-f2a3-7b91-91ed-ab7706046c6d"}
+{"type":"item.completed","item":{"id":"item_0","type":"error","message":"Model metadata for `gpt-nonexistent-9` not found. Defaulting to fallback metadata; this can degrade performance and cause issues."}}
+{"type":"turn.started"}
+{"type":"error","message":"{\"type\":\"error\",\"status\":400,\"error\":{\"type\":\"invalid_request_error\",\"message\":\"The 'gpt-nonexistent-9' model is not supported when using Codex with a ChatGPT account.\"}}"}
+{"type":"turn.failed","error":{"message":"{\"type\":\"error\",\"status\":400,\"error\":{\"type\":\"invalid_request_error\",\"message\":\"The 'gpt-nonexistent-9' model is not supported when using Codex with a ChatGPT account.\"}}"}}
diff --git a/src/daemon/agent/runners/fixtures/codex/legacy.hand-written.jsonl b/src/daemon/agent/runners/fixtures/codex/legacy.hand-written.jsonl
new file mode 100644
index 0000000..b0a5078
--- /dev/null
+++ b/src/daemon/agent/runners/fixtures/codex/legacy.hand-written.jsonl
@@ -0,0 +1,9 @@
+# Hand-written from codex.ts's reader, not recorded. The older msg-wrapped protocol: deltas, then the whole message again, which must not be said twice.
+{"id":"0","msg":{"type":"session_configured","session_id":"3e9a7b21-6c4d-4f80-b1a2-9d8e7f6c5b4a","model":"gpt-5.4"}}
+{"id":"1","msg":{"type":"task_started"}}
+{"id":"1","msg":{"type":"agent_message_delta","delta":"It costs "}}
+{"id":"1","msg":{"type":"agent_message_delta","delta":"$12."}}
+{"id":"1","msg":{"type":"agent_message","message":"It costs $12."}}
+{"id":"1","msg":{"type":"web_search_begin","query":"acme pricing"}}
+{"id":"1","msg":{"type":"token_count","info":{"total_token_usage":{"input_tokens":30000,"output_tokens":80},"last_token_usage":{"input_tokens":16000,"output_tokens":30}}}}
+{"id":"1","msg":{"type":"task_complete","last_agent_message":"It costs $12."}}
diff --git a/src/daemon/agent/runners/fixtures/codex/snapshots.hand-written.jsonl b/src/daemon/agent/runners/fixtures/codex/snapshots.hand-written.jsonl
new file mode 100644
index 0000000..5cadeeb
--- /dev/null
+++ b/src/daemon/agent/runners/fixtures/codex/snapshots.hand-written.jsonl
@@ -0,0 +1,11 @@
+# Hand-written from codex.ts's reader, not recorded. One turn in which Codex reports a message as growing snapshots, searches the web, then finishes a second message it only sends whole.
+{"type":"thread.started","thread_id":"01a0c580-1d2e-7f30-8a41-5b6c7d8e9f00"}
+{"type":"turn.started"}
+{"type":"item.updated","item":{"id":"item_0","type":"agent_message","text":"Looking"}}
+{"type":"item.updated","item":{"id":"item_0","type":"agent_message","text":"Looking it up"}}
+{"type":"item.completed","item":{"id":"item_0","type":"agent_message","text":"Looking it up."}}
+{"type":"item.started","item":{"id":"item_1","type":"web_search","query":"acme pricing"}}
+{"type":"item.completed","item":{"id":"item_1","type":"web_search","query":"acme pricing"}}
+{"type":"item.completed","item":{"id":"item_2","type":"command_execution","command":"ls"}}
+{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"It costs $12 a month."}}
+{"type":"turn.completed","usage":{"input_tokens":20000,"cached_input_tokens":18000,"output_tokens":45}}
diff --git a/src/daemon/agent/runners/fixtures/support.ts b/src/daemon/agent/runners/fixtures/support.ts
new file mode 100644
index 0000000..a031d22
--- /dev/null
+++ b/src/daemon/agent/runners/fixtures/support.ts
@@ -0,0 +1,85 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import type { AgentKind } from '@/lib/agents/catalog';
+import { stateDir } from '../../../lockfile';
+import type { AgentSettings } from '../../config';
+import type { JsonContext, McpServer, Plan, Runner, StreamContext, StreamSink } from '../types';
+
+export type Signal = keyof StreamSink;
+export type Call = [Signal, ...unknown[]];
+
+export function transcript(agent: AgentKind, name: string): string[] {
+ return readFileSync(new URL(`./${agent}/${name}`, import.meta.url), 'utf8')
+ .split('\n')
+ .filter((line) => line.trim() && !line.startsWith('#'));
+}
+
+/** Every sink call a fresh reader makes for these lines, in order. */
+export function readThrough(runner: Runner, lines: string[], only?: Signal): Call[] {
+ const calls: Call[] = [];
+ const record =
+ (signal: Signal) =>
+ (...args: unknown[]) =>
+ void calls.push([signal, ...args]);
+ const sink: StreamSink = {
+ text: record('text'),
+ tool: record('tool'),
+ session: record('session'),
+ usage: record('usage'),
+ done: record('done'),
+ fail: record('fail'),
+ };
+ const reader = runner.reader();
+ for (const line of lines) reader(line, sink);
+ return only ? calls.filter(([signal]) => signal === only) : calls;
+}
+
+// A fixed server rather than mcpServerFor(), whose node path differs on every machine.
+const mcp: McpServer = {
+ command: '/usr/local/bin/node',
+ args: ['/usr/local/lib/node_modules/browsentic/dist/cli.js', 'mcp'],
+ env: { BROWSENTIC_AGENT_RUN: 'run-1' },
+};
+
+export const streamContext = (settings: AgentSettings, overrides: Partial<StreamContext> = {}): StreamContext => ({
+ runId: 'run-1',
+ instruction: 'what does this page cost',
+ systemPrompt: 'You are Browsentic.',
+ research: false,
+ settings,
+ sessionId: null,
+ workspace: stateDir,
+ mcp,
+ ...overrides,
+});
+
+export const jsonContext = (settings: AgentSettings, overrides: Partial<JsonContext> = {}): JsonContext => ({
+ prompt: 'summarize this',
+ settings,
+ workspace: stateDir,
+ reads: false,
+ ...overrides,
+});
+
+const UUID = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/g;
+
+/** A plan as a snapshot shows it: the sandbox's paths and any freshly minted id replaced by names. */
+export function shown(plan: Plan): Plan {
+ const text = JSON.stringify(plan).replaceAll(stateDir, '<state>').replaceAll(homedir(), '<home>').replace(UUID, '<uuid>');
+ return JSON.parse(text) as Plan;
+}
+
+/** The value a flag takes, or undefined when the flag is absent. */
+export function valueOf(args: string[], flag: string): string | undefined {
+ const at = args.indexOf(flag);
+ return at === -1 ? undefined : args[at + 1];
+}
+
+/** The values a variadic flag takes, up to the next flag. */
+export function valuesOf(args: string[], flag: string): string[] {
+ const at = args.indexOf(flag);
+ if (at === -1) return [];
+ const values: string[] = [];
+ for (let i = at + 1; i < args.length && !args[i].startsWith('--'); i++) values.push(args[i]);
+ return values;
+}
diff --git a/src/daemon/agent/runners/index.test.ts b/src/daemon/agent/runners/index.test.ts
new file mode 100644
index 0000000..ed34a02
--- /dev/null
+++ b/src/daemon/agent/runners/index.test.ts
@@ -0,0 +1,132 @@
+import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+import { beforeAll, beforeEach, describe, expect, test } from 'vitest';
+import { AGENT_KINDS, AGENTS, type AgentKind } from '@/lib/agents/catalog';
+import { stateDir } from '../../lockfile';
+import type { AgentConfig, AgentSettings } from '../config';
+import { MCP_RULE, settingsPath } from './antigravity';
+import { agentState, grantRunner, mcpServerFor, RUNNERS, runnerFor } from './index';
+
+const bin = join(stateDir, 'stub-bin');
+const probes = join(stateDir, 'probes.log');
+
+/** A stand-in CLI that notes each time it is probed, then answers --version the given way. */
+const stub = (name: string, { prints = `${name} 1.0.0`, exit = 0 } = {}) => {
+ const path = join(bin, name);
+ writeFileSync(path, `#!/bin/sh\necho ${name} >> "${probes}"\necho "${prints}" >&2\nexit ${exit}\n`);
+ chmodSync(path, 0o755);
+ return path;
+};
+
+/** The stubs probed so far, a round at a time. The three agents are probed at once, so each round is sorted. */
+const rounds = () => {
+ const lines = readFileSync(probes, 'utf8').split('\n').filter(Boolean);
+ return [lines.slice(0, 3).sort(), lines.slice(3, 6).sort()].filter((round) => round.length);
+};
+
+const configWith = (agents: Partial<Record<AgentKind, AgentSettings>>, agent: AgentKind = 'claude'): AgentConfig => ({
+ agent,
+ agents: { claude: { bin: join(bin, 'claude') }, codex: { bin: join(bin, 'codex') }, antigravity: { bin: join(bin, 'agy') }, ...agents },
+ requireApproval: [],
+});
+
+const runner = async (kind: AgentKind, config: AgentConfig) =>
+ (await agentState(config, { refresh: true })).runners.find((status) => status.kind === kind);
+
+describe('the registry', () => {
+ test('every agent in the catalog has a runner that answers to its name', () => {
+ expect(AGENT_KINDS.map((kind) => RUNNERS[kind].kind)).toEqual([...AGENT_KINDS]);
+ });
+
+ test('the configured agent is the one that runs, with its own settings', () => {
+ const config = configWith({ codex: { bin: '/opt/codex', model: 'gpt-5.4' } }, 'codex');
+ expect(runnerFor(config)).toEqual({ runner: RUNNERS.codex, settings: { kind: 'codex', bin: '/opt/codex', model: 'gpt-5.4' } });
+ });
+
+ test("the MCP server an agent is handed is this CLI's own, serving MCP for that run", () => {
+ const server = mcpServerFor('run-7');
+ expect({ command: server.command, cli: basename(server.args[0]), args: server.args.slice(1), env: server.env }).toEqual({
+ command: process.execPath,
+ cli: 'cli.js',
+ args: ['mcp'],
+ env: { BROWSENTIC_AGENT_RUN: 'run-7' },
+ });
+ });
+});
+
+describe('readiness probes', () => {
+ beforeAll(() => {
+ mkdirSync(bin, { recursive: true });
+ for (const name of ['claude', 'claude-next', 'codex', 'agy']) stub(name);
+ stub('codex-expired', { prints: 'licence expired', exit: 3 });
+ });
+
+ beforeEach(() => {
+ rmSync(probes, { force: true });
+ rmSync(join(homedir(), '.gemini'), { recursive: true, force: true });
+ });
+
+ test('an installed agent is ready, with the version it printed', async () => {
+ expect(await runner('claude', configWith({}))).toMatchObject({ ready: true, version: 'claude 1.0.0' });
+ });
+
+ test('an agent that is not installed is missing, with the command that installs it', async () => {
+ expect(await runner('codex', configWith({ codex: { bin: join(bin, 'no-such-codex') } }))).toMatchObject({
+ ready: false,
+ problem: { code: 'AGENT_MISSING', fix: AGENTS.codex.install },
+ });
+ });
+
+ test('an agent whose version check fails is unusable, and says what it printed', async () => {
+ const expired = join(bin, 'codex-expired');
+ expect((await runner('codex', configWith({ codex: { bin: expired } })))?.problem).toEqual({
+ code: 'AGENT_UNUSABLE',
+ message: `"${expired} --version" failed: licence expired.`,
+ fix: AGENTS.codex.install,
+ });
+ });
+
+ test('an installed agent that still needs setting up is not ready, and says why', async () => {
+ expect(await runner('antigravity', configWith({}))).toMatchObject({
+ ready: false,
+ version: 'agy 1.0.0',
+ problem: { code: 'AGENT_NEEDS_PERMISSION', grantable: true },
+ });
+ });
+
+ test('probes are reused for half a minute, even when only the active agent changed', async () => {
+ await agentState(configWith({}), { refresh: true });
+ const again = await agentState(configWith({}, 'antigravity'));
+ expect([rounds(), again.active]).toEqual([[['agy', 'claude', 'codex']], 'antigravity']);
+ });
+
+ test('asking for a refresh probes again', async () => {
+ await agentState(configWith({}), { refresh: true });
+ await agentState(configWith({}), { refresh: true });
+ expect(rounds()).toHaveLength(2);
+ });
+
+ test('a different binary is probed afresh', async () => {
+ await agentState(configWith({}), { refresh: true });
+ await agentState(configWith({ claude: { bin: join(bin, 'claude-next') } }));
+ expect(rounds()).toEqual([
+ ['agy', 'claude', 'codex'],
+ ['agy', 'claude-next', 'codex'],
+ ]);
+ });
+
+ test('setting an agent up repairs it and forgets the stale probe', async () => {
+ await agentState(configWith({}), { refresh: true });
+ expect(await grantRunner('antigravity')).toBeNull();
+ const state = await agentState(configWith({}));
+ expect([JSON.parse(readFileSync(settingsPath, 'utf8')).permissions.allow, state.runners.find((status) => status.kind === 'antigravity')?.ready]).toEqual([
+ [MCP_RULE],
+ true,
+ ]);
+ });
+
+ test('an agent with nothing to set up reports no problem', async () => {
+ expect(await grantRunner('claude')).toBeNull();
+ });
+});
diff --git a/src/daemon/agent/runners/util.test.ts b/src/daemon/agent/runners/util.test.ts
new file mode 100644
index 0000000..6ec8343
--- /dev/null
+++ b/src/daemon/agent/runners/util.test.ts
@@ -0,0 +1,65 @@
+import { existsSync, mkdirSync, readFileSync, utimesSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, test } from 'vitest';
+import { logPath, stateDir } from '../../lockfile';
+import { effortOf, parseJsonBlob, parseJsonLine, sweepRunDirs } from './util';
+
+describe('sweeping run directories', () => {
+ const base = join(stateDir, 'sweep-test');
+ const aged = (name: string, hoursAgo: number) => {
+ const dir = join(base, name);
+ mkdirSync(dir, { recursive: true });
+ const at = (Date.now() - hoursAgo * 60 * 60_000) / 1000;
+ utimesSync(dir, at, at);
+ return dir;
+ };
+
+ test('a directory older than a day goes, and a newer one stays', () => {
+ const [old, recent] = [aged('yesterday', 25), aged('this-morning', 3)];
+ sweepRunDirs(base);
+ expect([existsSync(old), existsSync(recent)]).toEqual([false, true]);
+ });
+
+ test('the age limit can be shortened', () => {
+ const dir = aged('an-hour-ago', 1);
+ sweepRunDirs(base, 30 * 60_000);
+ expect(existsSync(dir)).toBe(false);
+ });
+
+ test('a base that does not exist yet is nothing to sweep', () => {
+ expect(() => sweepRunDirs(join(stateDir, 'never-made'))).not.toThrow();
+ });
+});
+
+describe('reasoning effort', () => {
+ test('an effort the CLI accepts is passed on', () => {
+ expect(effortOf({ bin: 'x', effort: 'high' }, ['low', 'high'])).toBe('high');
+ });
+
+ test('no effort chosen is no effort sent', () => {
+ expect(effortOf({ bin: 'x' }, ['low', 'high'])).toBeUndefined();
+ });
+
+ test('an effort the CLI would reject is dropped, and the log says what it accepts', () => {
+ expect(effortOf({ bin: 'x', effort: 'turbo' }, ['low', 'high'])).toBeUndefined();
+ expect(readFileSync(logPath, 'utf8')).toContain('ignoring effort "turbo" — accepted values are low, high');
+ });
+});
+
+describe('reading JSON a CLI printed', () => {
+ test('a line of JSON is parsed', () => {
+ expect(parseJsonLine('{"type":"result"}')).toEqual({ type: 'result' });
+ });
+
+ test('a line that is not JSON is null', () => {
+ expect(parseJsonLine('Loading…')).toBeNull();
+ });
+
+ test('an object wrapped in prose is found', () => {
+ expect(parseJsonBlob('Here is the summary:\n{"title":"Pricing","pages":3}\nHope that helps!')).toEqual({ title: 'Pricing', pages: 3 });
+ });
+
+ test('text with no object in it is null', () => {
+ expect([parseJsonBlob('no braces here'), parseJsonBlob('} backwards {'), parseJsonBlob('{"broken": }')]).toEqual([null, null, null]);
+ });
+});
diff --git a/vitest.config.ts b/vitest.config.ts
index f4fa79d..4ffe1f2 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -56,7 +56,7 @@ export default defineConfig({
coverage: {
provider: 'v8',
include: ['src/**/*.{ts,tsx}'],
- exclude: ['src/**/*.test.ts', 'src/**/*.test-d.ts', 'src/**/*.d.ts', 'src/daemon/test/**', 'src/daemon/dist/**'],
+ exclude: ['src/**/*.test.ts', 'src/**/*.test-d.ts', 'src/**/*.d.ts', 'src/**/fixtures/**', 'src/daemon/test/**', 'src/daemon/dist/**'],
reporter: ['json-summary', 'html'],
thresholds: Object.fromEntries(COVERAGE_AREAS.map(({ glob, lines }) => [glob, { lines }])),
},