An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.
TypeScript agentic-browseragentic-browsingagy-cliaiai-agentai-browser-extensionai-toolsbrave-extensionbrowser-agentbrowser-automationbrowser-extensionbrowser-usebrowserskillchrome-extensionclaude-codecodexfirefox-addonmcp-servernanobrowserweb-automation
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.tsnew file mode 100644index 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.tsindex 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,+ });}