@moxxy/plugin-provider-acp 0.0.0-stage → 0.46.0

package/src/agent-provider.ts

@@ -0,0 +1,234 @@
+import {
+  estimateTextTokens,
+  type AgentActivity,
+  type AgentStepEvent,
+  type AgentTurnStart,
+  type AgentStepRequest,
+  type LLMProvider,
+  type ModelDescriptor,
+  type ProviderEvent,
+  type ProviderRequest,
+  type TokenUsage,
+} from '@moxxy/sdk';
+import { AgentSessionPool, Inbox, JsonRpcLineClient, oneOffPrompt, type AgentSessionLease } from '@moxxy/agent-connection-kit';
+import { AcpAgentSession, CLIENT_CAPABILITIES, type AcpConnection, type StartAcpAgent } from './acp-session.js';
+import { OPENCODE_AGENT, type AcpAgentSpec } from './agents.js';
+import { spawnOpenCodeAcp } from './executable.js';
+import { readOpenCodeMcpServers, readOpenCodeRules } from './login.js';
+import type { ReadAgentMcpServers, ReadAgentRules } from './rules.js';
+import { ACP_PROTOCOL_VERSION, type AcpPromptResponse, type AcpSessionResponse } from './protocol.js';
+import { toTokenUsage } from './translate.js';
+
+const NON_TEXT_BLOCK_TOKENS = 256;
+const MAX_LIVE_SESSIONS = 8;
+/** The agent picks its own window per model; this only sizes Moxxy's view of the conversation. */
+const CONTEXT_WINDOW = 200_000;
+
+const agentCapabilities = {
+  contextWindow: CONTEXT_WINDOW,
+  supportsTools: true,
+  supportsStreaming: true,
+  supportsImages: true,
+  supportsDocuments: false,
+  supportsAudio: false,
+  supportsReasoning: true,
+} as const;
+
+export function acpModel(id: string): ModelDescriptor {
+  return { id, ...agentCapabilities };
+}
+
+export interface AcpAgentProviderConfig {
+  readonly agent?: AcpAgentSpec;
+  /** The person's agent CLI; resolved from PATH when left out. */
+  readonly executable?: string;
+  /** Persisted provider-item model (`plugins.provider.items.opencode.model`). */
+  readonly model?: string;
+  readonly defaultModel?: string;
+  /** Runner workspace, supplied on activation. */
+  readonly cwd?: string;
+  /** The models the person's agent offers (`opencode models`), read when the connection is switched on. */
+  readonly models?: ReadonlyArray<string>;
+  /** How the agent is started; spawns the person's `opencode acp` by default. */
+  readonly startAgent?: StartAcpAgent;
+  /** How the person's agent runs; reads `opencode debug agent` by default. */
+  readonly readRules?: ReadAgentRules;
+  /** The person's own MCP servers; reads `opencode debug config` by default. */
+  readonly readMcpServers?: ReadAgentMcpServers;
+  /** The live agent sessions; shared across the process by default. */
+  readonly sessions?: AgentSessionPool<AcpAgentSession>;
+}
+
+let sharedSessions: AgentSessionPool<AcpAgentSession> | undefined;
+
+/** The live ACP agent sessions of this process, one per Moxxy conversation. */
+export function acpSessions(): AgentSessionPool<AcpAgentSession> {
+  sharedSessions ??= new AgentSessionPool<AcpAgentSession>({ limit: MAX_LIVE_SESSIONS });
+  return sharedSessions;
+}
+
+/**
+ * An agent connection over the Agent Client Protocol: the agent (OpenCode)
+ * does each turn itself, unmodified (its instructions, config, tools, skills,
+ * permission rules and MCP servers). Moxxy adds only its own MCP server to
+ * the session, and nothing to the prompt.
+ */
+export class AcpAgentProvider implements LLMProvider {
+  readonly name: string;
+  readonly agentName: string;
+  readonly models: ModelDescriptor[];
+  /** No plan hand-off and no goal of its own: Moxxy's plan and goal modes steer it. */
+  readonly agentOwns = { plan: false, goal: false } as const;
+  private readonly agent: AcpAgentSpec;
+  private readonly defaultModel: string;
+  private readonly start: StartAcpAgent;
+  private readonly readRules: ReadAgentRules;
+  private readonly readMcpServers: ReadAgentMcpServers;
+
+  constructor(private readonly config: AcpAgentProviderConfig = {}) {
+    this.agent = config.agent ?? OPENCODE_AGENT;
+    this.name = this.agent.providerId;
+    this.agentName = this.agent.label;
+    this.defaultModel = config.model ?? config.defaultModel ?? this.agent.defaultModel;
+    const ids = config.models && config.models.length > 0 ? config.models : [this.defaultModel];
+    this.models = [...new Set([this.defaultModel, ...ids])].map(acpModel);
+    this.start = config.startAgent ?? spawnOpenCodeAcp(config.executable ?? 'opencode');
+    this.readRules = config.readRules ?? readOpenCodeRules(config.executable ?? 'opencode');
+    this.readMcpServers = config.readMcpServers ?? readOpenCodeMcpServers(config.executable ?? 'opencode');
+  }
+
+  /** Any model the agent names can be picked; it gets the same description as the rest. */
+  async prepareModel(model: string): Promise<void> {
+    if (model && !this.models.some((descriptor) => descriptor.id === model)) this.models.push(acpModel(model));
+  }
+
+  async *agentStep(req: AgentStepRequest): AsyncIterable<AgentStepEvent> {
+    let lease: AgentSessionLease<AcpAgentSession>;
+    try {
+      lease = await this.lease(req);
+    } catch (err) {
+      if (!req.signal.aborted) yield { type: 'error', message: messageOf(err), retryable: false };
+      return;
+    }
+    try {
+      yield* lease.session.turn(req);
+    } finally {
+      if (lease.session.isAlive) lease.release();
+      else await lease.discard();
+    }
+  }
+
+  /**
+   * A subagent OpenCode ran in the background finished while no Moxxy turn
+   * runs, and OpenCode answered it by itself: Moxxy opens a turn to show that.
+   */
+  onAgentTurn(listener: (start: AgentTurnStart) => void): () => void {
+    return this.sessions().onAgentTurn(listener);
+  }
+
+  /** What OpenCode's background subagents do, recorded at once. */
+  onAgentActivity(listener: (activity: AgentActivity) => void): () => void {
+    return this.sessions().onActivity(listener);
+  }
+
+  /** Stop one subagent OpenCode runs in the background in the conversation. */
+  async stopBackgroundWork(sessionId: string, workId: string): Promise<boolean> {
+    const live = this.sessions().running(sessionId);
+    return live ? live.stopWork(workId) : false;
+  }
+
+  private sessions(): AgentSessionPool<AcpAgentSession> {
+    return this.config.sessions ?? acpSessions();
+  }
+
+  /** One-off text (summaries, skill drafts): a session of its own in plan mode, without Moxxy's tools. */
+  async *stream(req: ProviderRequest): AsyncIterable<ProviderEvent> {
+    const model = req.model || this.defaultModel;
+    yield { type: 'message_start', model };
+    const cwd = this.config.cwd ?? process.cwd();
+    let usage: TokenUsage | undefined;
+    let connection: AcpConnection | undefined;
+    try {
+      connection = await this.start({ cwd });
+      const client = new JsonRpcLineClient({ readable: connection.readable, writable: connection.writable, jsonrpc: true });
+      const deltas = new Inbox<string | null>();
+      client.onNotification((method, params) => {
+        const update = (params as { update?: { sessionUpdate?: unknown; content?: { type?: unknown; text?: unknown } } } | undefined)?.update;
+        if (method === 'session/update' && update?.sessionUpdate === 'agent_message_chunk' && update.content?.type === 'text' && typeof update.content.text === 'string') {
+          deltas.push(update.content.text);
+        }
+      });
+      await client.request('initialize', { protocolVersion: ACP_PROTOCOL_VERSION, clientCapabilities: CLIENT_CAPABILITIES });
+      const session = await client.request<AcpSessionResponse>('session/new', { cwd, mcpServers: [] });
+      const sessionId = session.sessionId;
+      if (!sessionId) throw new Error(`${this.agent.label} started no session.`);
+      for (const option of session.configOptions ?? []) {
+        const wanted = option.category === 'model' ? model : option.category === 'mode' ? 'plan' : undefined;
+        if (wanted && option.currentValue !== wanted && (option.options ?? []).some((o) => o.value === wanted)) {
+          await client.request('session/set_config_option', { sessionId, configId: option.id, value: wanted });
+        }
+      }
+      const { system, prompt } = oneOffPrompt(req);
+      const text = [system, prompt].filter(Boolean).join('\n\n');
+      const stop = () => client.notify('session/cancel', { sessionId });
+      req.signal?.addEventListener('abort', stop, { once: true });
+      const answered = client.request<AcpPromptResponse>('session/prompt', { sessionId, prompt: [{ type: 'text', text }] }).finally(() => deltas.push(null));
+      try {
+        for (let delta = await deltas.next(); delta !== null; delta = await deltas.next()) yield { type: 'text_delta', delta };
+        const result = await answered;
+        if (result.usage) usage = toTokenUsage(result.usage);
+      } finally {
+        req.signal?.removeEventListener('abort', stop);
+      }
+    } catch (err) {
+      if (!req.signal?.aborted) yield { type: 'error', message: messageOf(err), retryable: false };
+      return;
+    } finally {
+      connection?.close();
+    }
+    yield { type: 'message_end', stopReason: 'end_turn', ...(usage ? { usage } : {}) };
+  }
+
+  async countTokens(req: Pick<ProviderRequest, 'model' | 'messages' | 'system' | 'tools'>): Promise<number> {
+    let text = req.system ?? '';
+    let nonTextBlocks = 0;
+    for (const message of req.messages) {
+      for (const block of message.content) {
+        if (block.type === 'text') text += block.text;
+        else nonTextBlocks += 1;
+      }
+    }
+    for (const tool of req.tools ?? []) text += tool.name + tool.description;
+    return estimateTextTokens(text) + nonTextBlocks * NON_TEXT_BLOCK_TOKENS;
+  }
+
+  /** The conversation's running agent, or a new one (loading its session) when there is none that fits. */
+  private async lease(req: AgentStepRequest): Promise<AgentSessionLease<AcpAgentSession>> {
+    const settings = {
+      agent: this.agent,
+      start: this.start,
+      readRules: this.readRules,
+      readMcpServers: this.readMcpServers,
+      cwd: req.cwd,
+      tools: req.allTools ?? req.tools,
+      ...(req.skills ? { skills: req.skills } : {}),
+      ...(req.resumeSessionId ? { resume: req.resumeSessionId } : {}),
+      onAgentTurn: (name: string, workId?: string) => this.sessions().agentTurn({ sessionId: req.sessionId, name, ...(workId ? { workId } : {}) }),
+      onActivity: (events: ReadonlyArray<AgentStepEvent>) => this.sessions().activity({ sessionId: req.sessionId, events }),
+    };
+    const sessions = this.sessions();
+    const create = () => AcpAgentSession.start(settings);
+    const lease = await sessions.acquire(req.sessionId, { signal: req.signal, create });
+    if (lease.session.isAlive && lease.session.fits(settings)) return lease;
+    await lease.discard();
+    return sessions.acquire(req.sessionId, { signal: req.signal, create });
+  }
+}
+
+export function createAcpAgentClient(config: AcpAgentProviderConfig = {}): LLMProvider {
+  return new AcpAgentProvider(config);
+}
+
+function messageOf(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/agents.ts

@@ -0,0 +1,37 @@
+import { MOXXY_MCP_SERVER, OPENCODE_DEFAULT_MODEL, OPENCODE_PROVIDER_ID } from './constants.js';
+
+/** What differs between agents that speak ACP. OpenCode is the only one so far. */
+export interface AcpAgentSpec {
+  readonly providerId: string;
+  /** The agent's name in messages ("OpenCode stopped."). */
+  readonly label: string;
+  readonly defaultModel: string;
+  /** The name Moxxy's MCP server has in the agent's session. */
+  readonly mcpServerName: string;
+  /** How the agent names a tool of Moxxy's MCP server: those calls are recorded by Moxxy when it runs them. */
+  readonly moxxyToolPrefix: string;
+  /** Moxxy tools the agent has its own of, so they are not lent over MCP; the person's Moxxy skills come as a `load_skill` of their own. */
+  readonly ownTools: ReadonlySet<string>;
+  /** What the person runs to sign the agent in to a model provider. */
+  readonly loginCommand: string;
+}
+
+/**
+ * OpenCode (`opencode acp`). It has its own file, shell, web-fetch, todo,
+ * skill and sub-agent tools. It has no question tool over ACP, no plan hand-off
+ * and no goal, so Moxxy lends `ask_user`, `plan_complete` and the goal tools,
+ * and `recall`, which searches Moxxy's record of the whole conversation.
+ */
+export const OPENCODE_AGENT: AcpAgentSpec = {
+  providerId: OPENCODE_PROVIDER_ID,
+  label: 'OpenCode',
+  defaultModel: OPENCODE_DEFAULT_MODEL,
+  mcpServerName: MOXXY_MCP_SERVER,
+  moxxyToolPrefix: `${MOXXY_MCP_SERVER}_`,
+  ownTools: new Set([
+    'Read', 'Edit', 'Write', 'Bash', 'Grep', 'Glob', 'Sleep', 'Wait', 'StopJob',
+    'web_fetch', 'session_recall',
+    'load_skill', 'reload_skills', 'synthesize_skill', 'load_tool',
+  ]),
+  loginCommand: 'opencode auth login',
+};

package/src/constants.ts

@@ -0,0 +1,36 @@
+/** Provider name in the registry / model picker / provider config. */
+export const OPENCODE_PROVIDER_ID = 'opencode';
+
+/** Human-readable upstream service, shown in login and setup surfaces. */
+export const OPENCODE_SERVICE_NAME = 'OpenCode';
+
+/** Optional executable override for login/status surfaces that do not carry provider config. */
+export const OPENCODE_EXECUTABLE_ENV = 'OPENCODE_EXECUTABLE';
+
+/** What a fresh OpenCode runs; the person's own default wins when they set one. */
+export const OPENCODE_DEFAULT_MODEL = 'opencode/big-pickle';
+
+/**
+ * What the picker offers before OpenCode is switched on and lists the person's own. Only the free model OpenCode
+ * keeps: its promotional free models come and go (space-bunny-free was one), and the daily compat check fails
+ * when one listed here is no longer offered.
+ */
+export const OPENCODE_FREE_MODELS: ReadonlyArray<string> = [OPENCODE_DEFAULT_MODEL];
+
+/** The name Moxxy's MCP server has in the agent's session; OpenCode calls its tools `moxxy_<tool>`. */
+export const MOXXY_MCP_SERVER = 'moxxy';
+
+export const OPENCODE_ACP_ARGS = ['acp'] as const;
+/** Where `opencode acp` serves its HTTP API: Moxxy reads OpenCode's background subagents there, which ACP does not report. */
+export const OPENCODE_API_HOST = '127.0.0.1';
+export const OPENCODE_API_USERNAME = 'opencode';
+export const OPENCODE_SERVER_USERNAME_ENV = 'OPENCODE_SERVER_USERNAME';
+export const OPENCODE_SERVER_PASSWORD_ENV = 'OPENCODE_SERVER_PASSWORD';
+/** OpenCode 1.19's switch for subagents that work on after its turn (`task` with `background: true`). */
+export const OPENCODE_BACKGROUND_SUBAGENTS_ENV = 'OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS';
+export const OPENCODE_MODELS_ARGS = ['models'] as const;
+export const OPENCODE_DEBUG_AGENT_ARGS = ['debug', 'agent'] as const;
+export const OPENCODE_DEBUG_CONFIG_ARGS = ['debug', 'config'] as const;
+export const OPENCODE_AUTH_LIST_ARGS = ['auth', 'list'] as const;
+export const OPENCODE_AUTH_LOGIN_ARGS = ['auth', 'login'] as const;
+export const OPENCODE_AUTH_LOGOUT_ARGS = ['auth', 'logout'] as const;

package/src/event-coverage.test.ts

@@ -0,0 +1,65 @@
+/**
+ * Every session update the Agent Client Protocol defines — its `SessionUpdate`
+ * kinds, listed in fixtures/ — checked against what Moxxy does with it: shown
+ * in the chat, or left alone for the reason given. A kind the protocol adds
+ * becomes a decision here instead of something lost without a trace. A tool
+ * shows whatever it is called: one Moxxy has no formatting for is a plain call.
+ */
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import type { AcpSessionUpdate } from './protocol.js';
+import { AcpTurnTranslator } from './translate.js';
+
+const kinds = JSON.parse(readFileSync(new URL('./fixtures/acp-session-updates.json', import.meta.url), 'utf8')) as { readonly updates: ReadonlyArray<string> };
+
+/** The kinds that show, each with an update of that kind. */
+const SHOWN: Record<string, AcpSessionUpdate> = {
+  agent_message_chunk: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: 'Done.' } },
+  agent_thought_chunk: { sessionUpdate: 'agent_thought_chunk', content: { type: 'text', text: 'Looking.' } },
+  tool_call: { sessionUpdate: 'tool_call', toolCallId: 'c1', title: 'read', kind: 'read', status: 'in_progress', rawInput: { filePath: '/repo/a.txt' } },
+  tool_call_update: { sessionUpdate: 'tool_call_update', toolCallId: 'c2', title: 'read', kind: 'read', status: 'completed', rawInput: { filePath: '/repo/a.txt' }, rawOutput: { output: 'hi' } },
+  plan: { sessionUpdate: 'plan', entries: [{ content: 'Read the code', priority: 'high', status: 'pending' }] },
+};
+
+/** The kinds Moxxy leaves out of the chat, and why. */
+const LEFT_ALONE: Record<string, string> = {
+  user_message_chunk: "the person's own message, which Moxxy already shows (sent again when a session is loaded)",
+  available_commands_update: "the session reads the agent's commands and skills from it, so a Moxxy skill of the same name is left to the agent's",
+  config_option_update: 'the agent reporting its model, mode and effort, which Moxxy sets itself',
+  current_mode_update: 'the agent reporting its mode, which Moxxy sets itself',
+  session_info_update: "the session's title and details, for the agent's own list",
+  usage_update: "how full the agent's context is; the session reads the window size from it, not the tokens of the turn",
+  notice: "a note for the agent's own screen",
+  compaction_update: "the agent shortening its own context; Moxxy's record of the conversation stays whole",
+  compaction_summary_chunk: "the agent shortening its own context; Moxxy's record of the conversation stays whole",
+};
+
+describe('every session update ACP defines', () => {
+  it('has a decision here, so a kind the protocol adds needs one', () => {
+    expect([...Object.keys(SHOWN), ...Object.keys(LEFT_ALONE)].sort()).toEqual([...kinds.updates]);
+  });
+
+  it.each(Object.keys(SHOWN))('%s shows in the chat', (kind) => {
+    const update = SHOWN[kind];
+
+    expect(update?.sessionUpdate).toBe(kind);
+    expect(update ? new AcpTurnTranslator('moxxy_', '/repo').update(update).length : 0).toBeGreaterThan(0);
+  });
+
+  it.each(Object.keys(LEFT_ALONE))('%s leaves the chat as it is', (kind) => {
+    expect(new AcpTurnTranslator('moxxy_', '/repo').update({ sessionUpdate: kind })).toEqual([]);
+  });
+});
+
+describe('a tool Moxxy has no formatting for', () => {
+  it('shows as a call by its name, with its result', () => {
+    const t = new AcpTurnTranslator('moxxy_', '/repo');
+
+    expect(t.update({ sessionUpdate: 'tool_call', toolCallId: 'm1', title: 'lsp_hover', kind: 'other', status: 'in_progress', rawInput: { line: 3 } })).toEqual([
+      expect.objectContaining({ type: 'tool_call', callId: 'm1', name: 'lsp_hover' }),
+    ]);
+    expect(t.update({ sessionUpdate: 'tool_call_update', toolCallId: 'm1', status: 'completed', rawOutput: { output: 'a number' } })).toEqual([
+      expect.objectContaining({ type: 'tool_result', callId: 'm1', ok: true }),
+    ]);
+  });
+});

package/src/executable.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest';
+import { opencodeAcpLaunch, opencodeServesApiBesideAcp, opencodeTarget } from './executable.js';
+
+describe('starting the person OpenCode without a shell', () => {
+  it('runs what PATH finds as it is on macOS and Linux', () => {
+    expect(opencodeTarget('opencode', { platform: 'darwin', find: () => '/opt/homebrew/bin/opencode' })).toEqual({
+      kind: 'direct',
+      command: '/opt/homebrew/bin/opencode',
+    });
+  });
+
+  it('runs opencode.exe as it is on Windows', () => {
+    const exe = 'C:\\Users\\me\\scoop\\shims\\opencode.exe';
+    expect(opencodeTarget('opencode', { platform: 'win32', find: () => exe })).toEqual({ kind: 'direct', command: exe });
+  });
+
+  it('starts the opencode.exe behind the npm .cmd shim on Windows', () => {
+    const shim = 'C:\\Users\\me\\AppData\\Roaming\\npm\\opencode.cmd';
+    const exe = 'C:\\Users\\me\\AppData\\Roaming\\npm\\node_modules\\opencode-ai\\bin\\opencode.exe';
+    expect(opencodeTarget('opencode', { platform: 'win32', find: () => shim, exists: (file) => file === exe })).toEqual({
+      kind: 'direct',
+      command: exe,
+    });
+  });
+
+  it('starts the opencode.exe behind the npm shim of OpenCode 2, which npm installs as @opencode/cli', () => {
+    const shim = 'C:\\Users\\me\\AppData\\Roaming\\npm\\opencode.cmd';
+    const exe = 'C:\\Users\\me\\AppData\\Roaming\\npm\\node_modules\\@opencode\\cli\\bin\\opencode.exe';
+    expect(opencodeTarget('opencode', { platform: 'win32', find: () => shim, exists: (file) => file === exe })).toEqual({
+      kind: 'direct',
+      command: exe,
+    });
+  });
+
+  it('says what to do when the shim leads nowhere', () => {
+    expect(() => opencodeTarget('opencode', { platform: 'win32', find: () => 'C:\\npm\\opencode.cmd', exists: () => false })).toThrow(
+      /reinstall OpenCode/,
+    );
+  });
+
+  it('says how to install OpenCode when it is not found', () => {
+    expect(() => opencodeTarget('opencode', { find: () => null })).toThrow(/OPENCODE_EXECUTABLE/);
+  });
+});
+
+describe('the OpenCode Moxxy starts for a conversation', () => {
+  it('serves its HTTP API on a port Moxxy picked, behind a password only Moxxy knows, with background subagents on', () => {
+    const launch = opencodeAcpLaunch({ server: { port: 4321, password: 'secret' }, inherited: {} });
+
+    expect(launch.args).toEqual(['acp', '--port', '4321', '--hostname', '127.0.0.1']);
+    expect(launch.env).toEqual({
+      OPENCODE_SERVER_USERNAME: 'opencode',
+      OPENCODE_SERVER_PASSWORD: 'secret',
+      OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS: 'true',
+    });
+    expect(launch.api).toEqual({ url: 'http://127.0.0.1:4321', authorization: `Basic ${Buffer.from('opencode:secret').toString('base64')}` });
+  });
+
+  it('keeps background subagents off when the person turned them off', () => {
+    const launch = opencodeAcpLaunch({ server: { port: 4321, password: 'secret' }, inherited: { OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS: 'false' } });
+
+    expect(launch.env.OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS).toBe('false');
+  });
+
+  it('adds its own settings to those of the restart that asks before changes', () => {
+    const launch = opencodeAcpLaunch({ server: { port: 1, password: 'p' }, inherited: {}, env: { OPENCODE_CONFIG_CONTENT: '{}' } });
+
+    expect(launch.env).toMatchObject({ OPENCODE_CONFIG_CONTENT: '{}', OPENCODE_SERVER_PASSWORD: 'p' });
+  });
+
+  it('starts OpenCode 2 with `acp` alone: it runs a private server and takes no port, so Moxxy has no API to read', () => {
+    const launch = opencodeAcpLaunch({ inherited: {} });
+
+    expect(launch.args).toEqual(['acp']);
+    expect(launch.env).toEqual({ OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS: 'true' });
+    expect(launch.api).toBeUndefined();
+  });
+});
+
+describe('which OpenCode serves its HTTP API beside ACP', () => {
+  it('is OpenCode 1, which takes --port and --hostname for it', () => {
+    expect(opencodeServesApiBesideAcp('1.19.4')).toBe(true);
+  });
+
+  it('is not OpenCode 2, nor one whose version could not be read, since `acp` alone starts on both', () => {
+    expect(opencodeServesApiBesideAcp('2.0.22')).toBe(false);
+    expect(opencodeServesApiBesideAcp(null)).toBe(false);
+  });
+});

package/src/executable.ts

@@ -0,0 +1,143 @@
+import { randomBytes } from 'node:crypto';
+import { createServer } from 'node:net';
+import { spawnExecutableTarget, type ExecutableTarget } from '@moxxy/sdk/server';
+import {
+  OPENCODE_CLI,
+  agentCliTargetAt,
+  compareVersions,
+  findAgentCli,
+  readCliVersion,
+  stopAgentProcess,
+  type AgentCliTargetOptions,
+} from '@moxxy/agent-connection-kit';
+import {
+  OPENCODE_ACP_ARGS,
+  OPENCODE_API_HOST,
+  OPENCODE_API_USERNAME,
+  OPENCODE_BACKGROUND_SUBAGENTS_ENV,
+  OPENCODE_EXECUTABLE_ENV,
+  OPENCODE_SERVER_PASSWORD_ENV,
+  OPENCODE_SERVER_USERNAME_ENV,
+} from './constants.js';
+import type { AcpConnection, StartAcpAgent } from './acp-session.js';
+import type { OpenCodeApi } from './opencode-api.js';
+
+export interface OpenCodeTargetOptions extends AgentCliTargetOptions {
+  readonly find?: (command: string) => string | null;
+}
+
+/**
+ * How to start the person's OpenCode without a shell. A Windows npm install
+ * puts an `opencode.cmd` shim on PATH, which only a shell can run; the
+ * `opencode.exe` it points at is started directly instead. The other
+ * installers (scoop, choco, the install script) put `opencode.exe` on PATH.
+ */
+export function opencodeTarget(command: string, opts: OpenCodeTargetOptions = {}): ExecutableTarget {
+  const found = (opts.find ?? ((name) => findAgentCli(OPENCODE_CLI, { command: name })))(command);
+  if (!found) throw new Error(`OpenCode not found: ${command}. Install OpenCode or set ${OPENCODE_EXECUTABLE_ENV}.`);
+  return agentCliTargetAt(OPENCODE_CLI, found, opts);
+}
+
+export interface OpenCodeAcpLaunch {
+  readonly args: ReadonlyArray<string>;
+  readonly env: Readonly<Record<string, string>>;
+  /** OpenCode's HTTP API, when this OpenCode serves it beside ACP. */
+  readonly api?: OpenCodeApi;
+}
+
+/**
+ * Whether `opencode acp` serves OpenCode's HTTP API beside ACP. OpenCode 1
+ * does, on `--port` / `--hostname`; OpenCode 2 runs a private server with no
+ * port and refuses those flags. An unreadable version is started as OpenCode
+ * 2 is, since `acp` alone starts on both.
+ */
+export function opencodeServesApiBesideAcp(version: string | null): boolean {
+  return version !== null && compareVersions(version, '2.0.0-0') < 0;
+}
+
+/**
+ * How `opencode acp` is started. Given a `server`, OpenCode serves its HTTP
+ * API on that port behind that password, so Moxxy can read the subagents
+ * OpenCode runs in the background, which ACP does not report, and nothing
+ * else on the computer can use the API. Background subagents are switched on
+ * unless the person switched them off.
+ */
+export function opencodeAcpLaunch(opts: {
+  readonly server?: { readonly port: number; readonly password: string };
+  /** The environment OpenCode inherits (`process.env`). */
+  readonly inherited: Readonly<Record<string, string | undefined>>;
+  /** Settings of this start (the restart that asks before changes). */
+  readonly env?: Readonly<Record<string, string>>;
+}): OpenCodeAcpLaunch {
+  const env = {
+    ...opts.env,
+    [OPENCODE_BACKGROUND_SUBAGENTS_ENV]: opts.inherited[OPENCODE_BACKGROUND_SUBAGENTS_ENV] ?? 'true',
+  };
+  const { server } = opts;
+  if (!server) return { args: [...OPENCODE_ACP_ARGS], env };
+  return {
+    args: [...OPENCODE_ACP_ARGS, '--port', String(server.port), '--hostname', OPENCODE_API_HOST],
+    env: {
+      ...env,
+      [OPENCODE_SERVER_USERNAME_ENV]: OPENCODE_API_USERNAME,
+      [OPENCODE_SERVER_PASSWORD_ENV]: server.password,
+    },
+    api: {
+      url: `http://${OPENCODE_API_HOST}:${server.port}`,
+      authorization: `Basic ${Buffer.from(`${OPENCODE_API_USERNAME}:${server.password}`).toString('base64')}`,
+    },
+  };
+}
+
+/** A port free on the loopback right now, for OpenCode to serve its API on. */
+function freePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once('error', reject);
+    server.listen(0, OPENCODE_API_HOST, () => {
+      const address = server.address();
+      server.close(() => (typeof address === 'object' && address ? resolve(address.port) : reject(new Error('No free port for OpenCode.'))));
+    });
+  });
+}
+
+/** Starts `opencode acp` in the conversation folder, speaking ACP on stdio. */
+export function spawnOpenCodeAcp(command: string): StartAcpAgent {
+  return async ({ cwd, env }) => {
+    const target = opencodeTarget(command);
+    const server = opencodeServesApiBesideAcp(await readCliVersion(target))
+      ? { port: await freePort(), password: randomBytes(24).toString('base64url') }
+      : undefined;
+    const launch = opencodeAcpLaunch({ inherited: process.env, ...(server ? { server } : {}), ...(env ? { env } : {}) });
+    return new Promise<AcpConnection>((resolve, reject) => {
+      const child = spawnExecutableTarget(target, launch.args, {
+        cwd,
+        env: launch.env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
+      });
+      const { stdin, stdout, stderr } = child;
+      if (!stdin || !stdout || !stderr) {
+        stopAgentProcess(child);
+        reject(new Error('OpenCode started without its stdio.'));
+        return;
+      }
+      child.once('error', reject);
+      child.once('spawn', () => {
+        child.off('error', reject);
+        // A failed write after OpenCode exits is reported by the closed stdout.
+        stdin.on('error', () => undefined);
+        resolve({
+          readable: stdout,
+          writable: stdin,
+          stderr,
+          ...(launch.api ? { api: launch.api } : {}),
+          close: () => {
+            stdin.end();
+            stopAgentProcess(child);
+          },
+        });
+      });
+    });
+  };
+}