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.

refactor(agents): the ACP client OpenCode 2 turns run on moves to acp.ts, with OpenCode's differences as options, so another ACP agent can share it

Shahriar009e2f49048f
diff --git a/src/daemon/agent/runners/acp.ts b/src/daemon/agent/runners/acp.ts
new file mode 100644
index 0000000..a1ef656
--- /dev/null
+++ b/src/daemon/agent/runners/acp.ts
@@ -0,0 +1,270 @@
+import { CONVERSATION_REFUSED, type Conversation, type ConversationIO, type Plan, type StreamContext, type StreamSink } from './types';
+import { browserToolsDidNotStart } from './util';
+
+const ASK = { initialize: 1, session: 2, fresh: 3, model: 4, effort: 5, prompt: 6 } as const;
+
+/** JSON-RPC's own code for a method the agent does not know: a CLI without this protocol, not a failed turn. */
+const UNKNOWN = -32601;
+
+/** ACP's answer to a parameter it cannot use, which for `session/resume` is a session the CLI no longer holds. */
+const INVALID = -32602;
+
+/** How long a run's browser tools may take to reach the CLI before the turn is given up. */
+const LISTED_WITHIN_MS = 20_000;
+
+interface Message {
+ id?: number | string;
+ method?: string;
+ params?: { sessionId?: string; update?: Update };
+ result?: { sessionId?: string; configOptions?: ConfigOption[]; stopReason?: string; usage?: { outputTokens?: number } };
+ error?: { code?: number; message?: string };
+}
+
+export interface ConfigOption {
+ id?: string;
+ currentValue?: string;
+ /** Flat values, or groups of them, as DeepSeek Harness lists its models under each provider. */
+ options?: { value?: string; name?: string; options?: { value?: string; name?: string }[] }[];
+}
+
+export interface Update {
+ sessionUpdate?: string;
+ toolCallId?: string;
+ messageId?: string;
+ name?: string;
+ title?: string;
+ status?: string;
+ content?: unknown;
+ used?: number;
+}
+
+/** The model a turn ran on, and whether it was picked in Browsentic or left to the CLI. */
+export interface TurnModel {
+ id: string;
+ picked: boolean;
+}
+
+/** A model a session offers: the id a Browsentic setting names it by, and the value ACP is sent. */
+export interface ModelEntry {
+ id: string;
+ value: string;
+}
+
+export interface AcpAgent {
+ plan: Plan;
+ /** The CLI's name, in what the user reads. */
+ label: string;
+ /** The MCP servers a session opens with. A resumed session reconnects only those it is given. */
+ mcpServers: unknown[];
+ declined: (reason: string) => void;
+ explain: (message: string | undefined, model?: TurnModel) => string;
+ stoppedFor: (tool: string) => string;
+ /** Why a session the CLI opened is not the run's own, or null when it is. */
+ refuses?: (options: ConfigOption[] | undefined) => string | null;
+ effortOption: string;
+ /** Each model the session offers, the one the CLI would pick for a setting first. */
+ models: (choice: ConfigOption | undefined) => ModelEntry[];
+ /** How a model is spelled in the side panel, for the message naming one the CLI lacks. */
+ spelled?: string;
+ /** A tool of the run's own browser server, whose calls the daemon draws as they happen. */
+ own: (name: string) => boolean;
+ /** Built-ins the panel draws as they run. */
+ drawn: string[];
+ /** Built-ins that may run without a row of their own. */
+ quiet?: string[];
+ /** Whether a finished call to any other tool ran, which means the run's containment did not hold. */
+ ran: (update: Update) => boolean;
+ /** How long after the browser tools are listed the prompt waits, for a CLI that registers them late. */
+ settleMs: number;
+ /** Assistant text arrives as whole messages, each needing a paragraph of its own. */
+ paragraphs?: boolean;
+}
+
+/**
+ * One turn over the Agent Client Protocol with a CLI that keeps its own server for as long as the
+ * turn holds it. The prompt goes only once the browser tools have reached the session, a session the
+ * CLI opened as anything but the run's own is refused, and a built-in that runs stops the run.
+ */
+export function acpConversation(context: StreamContext, agent: AcpAgent): Conversation {
+ let session: string | undefined;
+ let model: TurnModel | undefined;
+ let holding = false;
+ let contextTokens = 0;
+ let message: string | undefined;
+ const calls = new Map<string, string>();
+
+ const refuse = (sink: StreamSink, reason: string) => {
+ agent.declined(reason);
+ sink.fail(CONVERSATION_REFUSED, reason);
+ };
+
+ const ask = (io: ConversationIO, id: number, method: string, params: Record<string, unknown>) => io.write({ jsonrpc: '2.0', id, method, params });
+
+ const openSession = (io: ConversationIO, resuming: boolean) =>
+ resuming
+ ? ask(io, ASK.session, 'session/resume', { sessionId: context.sessionId, cwd: agent.plan.cwd, mcpServers: agent.mcpServers })
+ : ask(io, ASK.fresh, 'session/new', { cwd: agent.plan.cwd, mcpServers: agent.mcpServers });
+
+ const option = (options: ConfigOption[] | undefined, id: string) => options?.find((candidate) => candidate.id === id);
+ const offers = (choice: ConfigOption | undefined, value: string) => choice?.options?.some((offered) => offered.value === value) === true;
+
+ const prompt = (io: ConversationIO, sink: StreamSink) => {
+ const late = new Promise<'late'>((resolve) => setTimeout(() => resolve('late'), LISTED_WITHIN_MS).unref());
+ void Promise.race([context.toolsListed(), late]).then((listed) => {
+ if (listed === 'late') return sink.fail('AGENT_FAILED', browserToolsDidNotStart(agent.label));
+ setTimeout(() => ask(io, ASK.prompt, 'session/prompt', { sessionId: session, prompt: [{ type: 'text', text: context.instruction }] }), agent.settleMs);
+ });
+ };
+
+ // An effort is listed only for a model that has it, and a CLI may refuse a run asking for one it lacks.
+ const chooseEffort = (options: ConfigOption[] | undefined, io: ConversationIO, sink: StreamSink) => {
+ const effort = context.settings.effort;
+ const choice = option(options, agent.effortOption);
+ if (effort && choice?.currentValue !== effort && offers(choice, effort)) {
+ return ask(io, ASK.effort, 'session/set_config_option', { sessionId: session, configId: agent.effortOption, value: effort });
+ }
+ return prompt(io, sink);
+ };
+
+ const modelOf = (options: ConfigOption[] | undefined): TurnModel | undefined => {
+ const pinned = context.settings.model;
+ if (pinned) return { id: pinned, picked: true };
+ const choice = option(options, 'model');
+ const current = choice?.currentValue;
+ if (!current) return undefined;
+ return { id: agent.models(choice).find((entry) => entry.value === current)?.id ?? current, picked: false };
+ };
+
+ // A model a CLI does not know may be swapped for another without a word, so a pinned one is asked for by name.
+ const chooseModel = (options: ConfigOption[] | undefined, io: ConversationIO, sink: StreamSink) => {
+ const pinned = context.settings.model;
+ const choice = option(options, 'model');
+ const offered = agent.models(choice);
+ const entry = offered.find((candidate) => candidate.id === pinned);
+ if (!pinned || choice?.currentValue === (entry?.value ?? pinned)) return chooseEffort(options, io, sink);
+ if (!entry) {
+ const some = offered.map((candidate) => candidate.id).slice(0, 6);
+ return sink.fail(
+ 'AGENT_FAILED',
+ `${agent.label} offers no model "${pinned}" here.${some.length ? ` It offers ${some.join(', ')}, among others.` : ''} ` +
+ `Pick one in the Browsentic side panel, ${agent.spelled ? `${agent.spelled}, ` : ''}then try again.`,
+ );
+ }
+ return ask(io, ASK.model, 'session/set_config_option', { sessionId: session, configId: 'model', value: entry.value });
+ };
+
+ const onSession = (reply: Message, io: ConversationIO, sink: StreamSink) => {
+ const options = reply.result?.configOptions;
+ const refusal = agent.refuses?.(options);
+ if (refusal) return sink.fail('AGENT_UNSAFE', refusal);
+ session = reply.result?.sessionId ?? context.sessionId ?? undefined;
+ if (!session) return sink.fail('AGENT_FAILED', `${agent.label} opened a session without naming it.`);
+ holding = true;
+ model = modelOf(options);
+ sink.session(session);
+ chooseModel(options, io, sink);
+ };
+
+ const onResponse = (reply: Message, io: ConversationIO, sink: StreamSink) => {
+ const failed = reply.error;
+ switch (reply.id) {
+ case ASK.initialize:
+ if (failed) return refuse(sink, `its ACP server would not start: ${failed.message}`);
+ return openSession(io, context.sessionId !== null);
+
+ case ASK.session:
+ case ASK.fresh:
+ if (failed?.code === INVALID && reply.id === ASK.session) return openSession(io, false);
+ if (failed) {
+ const reason = `${agent.label} would not ${reply.id === ASK.session ? 'resume' : 'start'} the session: ${failed.message}`;
+ return failed.code === UNKNOWN ? refuse(sink, reason) : sink.fail('AGENT_FAILED', agent.explain(failed.message));
+ }
+ return onSession(reply, io, sink);
+
+ case ASK.model:
+ if (failed) return sink.fail('AGENT_FAILED', agent.explain(failed.message, model));
+ return chooseEffort(reply.result?.configOptions, io, sink);
+
+ case ASK.effort:
+ return prompt(io, sink);
+
+ case ASK.prompt: {
+ if (failed) return sink.fail('AGENT_FAILED', agent.explain(failed.message, model));
+ const output = reply.result?.usage?.outputTokens;
+ if (output !== undefined) sink.usage({ contextTokens, outputTokens: output });
+ // Stopped from Browsentic, the CLI ends the prompt itself before it exits.
+ if (reply.result?.stopReason === 'cancelled') return sink.fail('CANCELLED', 'Run cancelled.');
+ return sink.done(reply.result?.stopReason ?? 'end_turn');
+ }
+ }
+ };
+
+ const onToolCall = (update: Update, sink: StreamSink) => {
+ const id = update.toolCallId;
+ if (!id) return;
+ const name = update.name ?? calls.get(id) ?? update.title ?? '';
+ if (!calls.has(id)) {
+ calls.set(id, name);
+ if (agent.drawn.includes(name)) sink.tool(id, name);
+ }
+ if (update.status !== 'completed' && update.status !== 'failed') return;
+ if (agent.drawn.includes(name)) return sink.toolResult(id, update.status === 'completed');
+ if (agent.own(name) || agent.quiet?.includes(name)) return;
+ // A refused call is the model reaching for a tool it was never offered; one that ran means the rules did not hold.
+ if (agent.ran(update)) sink.fail('AGENT_UNSAFE', agent.stoppedFor(name));
+ };
+
+ const onText = (update: Update, sink: StreamSink) => {
+ const content = update.content as { type?: string; text?: string } | undefined;
+ if (content?.type !== 'text' || !content.text) return;
+ if (agent.paragraphs && message !== undefined && update.messageId !== message) sink.text('\n\n');
+ message = update.messageId;
+ sink.text(content.text);
+ };
+
+ const onUpdate = (update: Update | undefined, sink: StreamSink) => {
+ switch (update?.sessionUpdate) {
+ case 'agent_message_chunk':
+ return onText(update, sink);
+ case 'tool_call':
+ case 'tool_call_update':
+ return onToolCall(update, sink);
+ case 'usage_update':
+ if (typeof update.used === 'number') contextTokens = update.used;
+ return;
+ }
+ };
+
+ return {
+ plan: agent.plan,
+ get holding() {
+ return holding;
+ },
+ declined: agent.declined,
+ open(io) {
+ ask(io, ASK.initialize, 'initialize', {
+ protocolVersion: 1,
+ clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+ clientInfo: { name: 'browsentic', title: 'Browsentic', version: '1' },
+ });
+ },
+ read(line, sink, io) {
+ let incoming: Message;
+ try {
+ incoming = JSON.parse(line) as Message;
+ } catch {
+ return;
+ }
+ if (incoming.method && incoming.id !== undefined) {
+ // Nobody is there to approve anything, and a denied tool is never asked about.
+ if (incoming.method === 'session/request_permission') return io.write({ jsonrpc: '2.0', id: incoming.id, result: { outcome: { outcome: 'cancelled' } } });
+ return io.write({ jsonrpc: '2.0', id: incoming.id, error: { code: UNKNOWN, message: `Browsentic does not answer ${incoming.method}` } });
+ }
+ if (incoming.method === 'session/update') {
+ if (session && incoming.params?.sessionId === session) onUpdate(incoming.params.update, sink);
+ return;
+ }
+ if (!incoming.method) onResponse(incoming, io, sink);
+ },
+ };
+}
diff --git a/src/daemon/agent/runners/opencode-acp.ts b/src/daemon/agent/runners/opencode-acp.ts
index fa31b19..1043719 100644
--- a/src/daemon/agent/runners/opencode-acp.ts
+++ b/src/daemon/agent/runners/opencode-acp.ts
@@ -1,14 +1,8 @@
+import { acpConversation, type TurnModel } from './acp';
import { MCP_SERVER_NAME } from './claude';
-import { CONVERSATION_REFUSED, type Conversation, type ConversationIO, type Plan, type StreamContext, type StreamSink } from './types';
-import { browserToolsDidNotStart } from './util';
+import type { Conversation, Plan, StreamContext } from './types';
-const ASK = { initialize: 1, session: 2, fresh: 3, model: 4, effort: 5, prompt: 6 } as const;
-
-/** JSON-RPC's own code for a method the agent does not know: an OpenCode without this protocol, not a failed turn. */
-const UNKNOWN = -32601;
-
-/** ACP's answer to a parameter it cannot use, which for `session/resume` is a session this database never held. */
-const INVALID = -32602;
+export type { TurnModel } from './acp';
/**
* OpenCode connects MCP servers in the background and reads its tool list afresh at each step, so a
@@ -18,41 +12,8 @@ const INVALID = -32602;
*/
const SETTLE_MS = 600;
-/** How long a run's browser tools may take to reach OpenCode before the turn is given up. */
-const LISTED_WITHIN_MS = 20_000;
-
const WEB_TOOLS = ['webfetch', 'websearch'];
-interface Message {
- id?: number | string;
- method?: string;
- params?: { sessionId?: string; update?: Update };
- result?: { sessionId?: string; configOptions?: ConfigOption[]; stopReason?: string; usage?: { outputTokens?: number } };
- error?: { code?: number; message?: string };
-}
-
-interface ConfigOption {
- id?: string;
- currentValue?: string;
- options?: { value?: string }[];
-}
-
-interface Update {
- sessionUpdate?: string;
- toolCallId?: string;
- name?: string;
- title?: string;
- status?: string;
- content?: { type?: string; text?: string };
- used?: number;
-}
-
-/** The model a turn ran on, and whether it was picked in Browsentic or left to OpenCode. */
-export interface TurnModel {
- id: string;
- picked: boolean;
-}
-
export interface AcpTurn {
plan: Plan;
/** The agent the config defines, which every session has to be in. */
@@ -63,180 +24,29 @@ export interface AcpTurn {
}
/**
- * One turn with OpenCode 2 over the Agent Client Protocol, `opencode acp`, which keeps its own server
- * for as long as the turn holds it. The run's config comes from its environment as it would for
- * `opencode run`, but the prompt goes only once the browser tools have reached the session. A session
- * found in any agent but the run's own is refused, and a built-in that runs stops the run.
+ * One turn with OpenCode 2 over the Agent Client Protocol, `opencode acp`. The run's config, its MCP
+ * server included, comes from its environment as it would for `opencode run`, so the session opens
+ * with no servers of its own. A session found in any agent but the run's own is refused.
*/
export function acpTurn(context: StreamContext, turn: AcpTurn): Conversation {
- let session: string | undefined;
- let model: TurnModel | undefined;
- let holding = false;
- let contextTokens = 0;
- const calls = new Map<string, string>();
-
- const refuse = (sink: StreamSink, reason: string) => {
- turn.declined(reason);
- sink.fail(CONVERSATION_REFUSED, reason);
- };
-
- const ask = (io: ConversationIO, id: number, method: string, params: Record<string, unknown>) => io.write({ jsonrpc: '2.0', id, method, params });
-
- const openSession = (io: ConversationIO, resuming: boolean) =>
- resuming
- ? ask(io, ASK.session, 'session/resume', { sessionId: context.sessionId, cwd: turn.plan.cwd, mcpServers: [] })
- : ask(io, ASK.fresh, 'session/new', { cwd: turn.plan.cwd, mcpServers: [] });
-
- const option = (options: ConfigOption[] | undefined, id: string) => options?.find((candidate) => candidate.id === id);
- const offers = (choice: ConfigOption | undefined, value: string) => choice?.options?.some((offered) => offered.value === value) === true;
-
- const prompt = (io: ConversationIO, sink: StreamSink) => {
- const late = new Promise<'late'>((resolve) => setTimeout(() => resolve('late'), LISTED_WITHIN_MS).unref());
- void Promise.race([context.toolsListed(), late]).then((listed) => {
- if (listed === 'late') return sink.fail('AGENT_FAILED', browserToolsDidNotStart('OpenCode'));
- setTimeout(() => ask(io, ASK.prompt, 'session/prompt', { sessionId: session, prompt: [{ type: 'text', text: context.instruction }] }), SETTLE_MS);
- });
- };
-
- // OpenCode lists each level of effort only for a model that has it, and refuses a run asking for one it lacks.
- const chooseEffort = (options: ConfigOption[] | undefined, io: ConversationIO, sink: StreamSink) => {
- const effort = context.settings.effort;
- const choice = option(options, 'effort');
- if (effort && choice?.currentValue !== effort && offers(choice, effort)) {
- return ask(io, ASK.effort, 'session/set_config_option', { sessionId: session, configId: 'effort', value: effort });
- }
- return prompt(io, sink);
- };
-
- const modelOf = (options: ConfigOption[] | undefined): TurnModel | undefined => {
- const pinned = context.settings.model;
- if (pinned) return { id: pinned, picked: true };
- const current = option(options, 'model')?.currentValue;
- return current ? { id: current, picked: false } : undefined;
- };
-
- // A model OpenCode does not know is swapped for another without a word, so a pinned one is asked for by name.
- const chooseModel = (options: ConfigOption[] | undefined, io: ConversationIO, sink: StreamSink) => {
- const pinned = context.settings.model;
- const choice = option(options, 'model');
- if (!pinned || choice?.currentValue === pinned) return chooseEffort(options, io, sink);
- if (!offers(choice, pinned)) {
- const some = (choice?.options ?? []).flatMap((offered) => (offered.value ? [offered.value] : [])).slice(0, 6);
- return sink.fail(
- 'AGENT_FAILED',
- `OpenCode offers no model "${pinned}" here.${some.length ? ` It offers ${some.join(', ')}, among others.` : ''} ` +
- 'Pick one in the Browsentic side panel, spelled provider/model, then try again.',
- );
- }
- return ask(io, ASK.model, 'session/set_config_option', { sessionId: session, configId: 'model', value: pinned });
- };
-
- const onSession = (message: Message, io: ConversationIO, sink: StreamSink) => {
- const options = message.result?.configOptions;
- const mode = option(options, 'mode')?.currentValue;
- if (mode !== turn.agent) {
- return sink.fail('AGENT_UNSAFE', `OpenCode opened this session as its "${mode ?? 'unnamed'}" agent rather than Browsentic's, so the run was stopped.`);
- }
- session = message.result?.sessionId ?? context.sessionId ?? undefined;
- if (!session) return sink.fail('AGENT_FAILED', 'OpenCode opened a session without naming it.');
- holding = true;
- model = modelOf(options);
- sink.session(session);
- chooseModel(options, io, sink);
- };
-
- const onResponse = (message: Message, io: ConversationIO, sink: StreamSink) => {
- const failed = message.error;
- switch (message.id) {
- case ASK.initialize:
- if (failed) return refuse(sink, `its ACP server would not start: ${failed.message}`);
- return openSession(io, context.sessionId !== null);
-
- case ASK.session:
- case ASK.fresh:
- if (failed?.code === INVALID && message.id === ASK.session) return openSession(io, false);
- if (failed) {
- const reason = `OpenCode would not ${message.id === ASK.session ? 'resume' : 'start'} the session: ${failed.message}`;
- return failed.code === UNKNOWN ? refuse(sink, reason) : sink.fail('AGENT_FAILED', turn.explain(failed.message));
- }
- return onSession(message, io, sink);
-
- case ASK.model:
- if (failed) return sink.fail('AGENT_FAILED', turn.explain(failed.message, model));
- return chooseEffort(message.result?.configOptions, io, sink);
-
- case ASK.effort:
- return prompt(io, sink);
-
- case ASK.prompt: {
- if (failed) return sink.fail('AGENT_FAILED', turn.explain(failed.message, model));
- const output = message.result?.usage?.outputTokens;
- if (output !== undefined) sink.usage({ contextTokens, outputTokens: output });
- // Stopped from Browsentic, OpenCode ends the prompt itself before it exits.
- if (message.result?.stopReason === 'cancelled') return sink.fail('CANCELLED', 'Run cancelled.');
- return sink.done(message.result?.stopReason ?? 'end_turn');
- }
- }
- };
-
- const onToolCall = (update: Update, sink: StreamSink) => {
- const id = update.toolCallId;
- if (!id) return;
- const name = update.name ?? calls.get(id) ?? update.title ?? '';
- if (!calls.has(id)) {
- calls.set(id, name);
- if (WEB_TOOLS.includes(name)) sink.tool(id, name);
- }
- if (update.status !== 'completed' && update.status !== 'failed') return;
- if (WEB_TOOLS.includes(name)) return sink.toolResult(id, update.status === 'completed');
- // A refused call is the model reaching for a tool it was never offered; one that ran means the rules did not hold.
- if (update.status === 'completed' && !name.startsWith(`${MCP_SERVER_NAME}_`)) sink.fail('AGENT_UNSAFE', turn.stoppedFor(name));
- };
-
- const onUpdate = (update: Update | undefined, sink: StreamSink) => {
- switch (update?.sessionUpdate) {
- case 'agent_message_chunk':
- if (update.content?.type === 'text' && update.content.text) sink.text(update.content.text);
- return;
- case 'tool_call':
- case 'tool_call_update':
- return onToolCall(update, sink);
- case 'usage_update':
- if (typeof update.used === 'number') contextTokens = update.used;
- return;
- }
- };
-
- return {
+ return acpConversation(context, {
plan: turn.plan,
- get holding() {
- return holding;
- },
+ label: 'OpenCode',
+ mcpServers: [],
declined: turn.declined,
- open(io) {
- ask(io, ASK.initialize, 'initialize', {
- protocolVersion: 1,
- clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
- clientInfo: { name: 'browsentic', title: 'Browsentic', version: '1' },
- });
- },
- read(line, sink, io) {
- let message: Message;
- try {
- message = JSON.parse(line) as Message;
- } catch {
- return;
- }
- if (message.method && message.id !== undefined) {
- // Nobody is there to approve anything, and a denied tool is never asked about.
- if (message.method === 'session/request_permission') return io.write({ jsonrpc: '2.0', id: message.id, result: { outcome: { outcome: 'cancelled' } } });
- return io.write({ jsonrpc: '2.0', id: message.id, error: { code: UNKNOWN, message: `Browsentic does not answer ${message.method}` } });
- }
- if (message.method === 'session/update') {
- if (session && message.params?.sessionId === session) onUpdate(message.params.update, sink);
- return;
- }
- if (!message.method) onResponse(message, io, sink);
+ explain: turn.explain,
+ stoppedFor: turn.stoppedFor,
+ refuses: (options) => {
+ const mode = options?.find((candidate) => candidate.id === 'mode')?.currentValue;
+ return mode === turn.agent ? null : `OpenCode opened this session as its "${mode ?? 'unnamed'}" agent rather than Browsentic's, so the run was stopped.`;
},
- };
+ effortOption: 'effort',
+ models: (choice) => (choice?.options ?? []).flatMap((offered) => (offered.value ? [{ id: offered.value, value: offered.value }] : [])),
+ spelled: 'spelled provider/model',
+ own: (name) => name.startsWith(`${MCP_SERVER_NAME}_`),
+ drawn: WEB_TOOLS,
+ // OpenCode refuses a tool its rules deny, which reads as failed: only one that completed ran.
+ ran: (update) => update.status === 'completed',
+ settleMs: SETTLE_MS,
+ });
}