OpenCode structured chat over the Agent Client Protocol

src/main/acp/acp-account-binding.ts

@@ -0,0 +1,40 @@
+// How an ACP agent's chats pin their account: what a new chat records, and how a launch points the
+// agent at the account its record pinned. Both run on the machine that runs the agent.
+
+import {
+  isLegacyAgentSessionAccountHome,
+  type AgentSessionAccountHome
+} from '../../shared/agent-session-account-home'
+import { resolveStructuredEnvAccountHomePath } from '../runtime/structured-agent-account-home'
+
+type AccountPin = { accountHomeVariable: string } | { accountLocatorKind: 'opencode' }
+
+export type AcpAccountBinding = {
+  /** What the agent's definition says its records pin. */
+  pin: AccountPin
+  /** The account a new chat pins: the current selection, read without side effects. */
+  resolve(input: { launchEnv: NodeJS.ProcessEnv }): Promise<AgentSessionAccountHome>
+  /** `env` pointed at the pinned account; throws for an account of another kind. */
+  environment(home: AgentSessionAccountHome, env: Record<string, string>): Record<string, string>
+}
+
+/** An agent whose account is one config directory named by `variable`, with a default under the
+ *  user's home. */
+export function directoryAccountBinding(
+  variable: string,
+  defaultHome: (homePath: string) => string
+): AcpAccountBinding {
+  return {
+    pin: { accountHomeVariable: variable },
+    resolve: async ({ launchEnv }) => ({
+      variable,
+      path: resolveStructuredEnvAccountHomePath({ launchEnv, variable, defaultPath: defaultHome })
+    }),
+    environment: (home, env) => {
+      if (!isLegacyAgentSessionAccountHome(home) || home.variable !== variable) {
+        throw new Error(`sessions of this agent pin ${variable}`)
+      }
+      return { ...env, [variable]: home.path }
+    }
+  }
+}

src/main/acp/acp-dialects/acp-dialect.ts

@@ -4,7 +4,7 @@ import type { AgentSessionPromptResponse } from '../../../shared/agent-session-q
 import type { NativeChatBackgroundTaskBlock } from '../../../shared/native-chat-types'
 import type { ProviderTimelineRequestBody } from '../../native-chat/agent-session-timeline/provider-timeline-event'
 import type { AcpAgentError } from '../acp-errors'
-import type { ToolCallUpdate } from '../generated/acp-protocol.generated'
+import type { PermissionOption, ToolCallUpdate } from '../generated/acp-protocol.generated'
 
 export type AcpRequestPresentation = {
   body: ProviderTimelineRequestBody
@@ -41,6 +41,10 @@ export type AcpDialectNotification =
 /** Hooks interpret extensions; lifecycle and row identity stay shared. */
 export type AcpDialect = {
   injectedPromptIdentity?: true
+  /** A tool update in the shared shape (`rawOutput.stdout`, `rawOutput.exitCode`), read first. */
+  normalizeToolUpdate?(update: ToolCallUpdate): ToolCallUpdate
+  /** The words for a permission option whose own name misstates what it grants. */
+  permissionOptionLabel?(option: PermissionOption): string | undefined
   toolName?(update: ToolCallUpdate): string | undefined
   toolBackgroundTasks?(
     update: ToolCallUpdate,

src/main/acp/acp-dialects/opencode-dialect.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod'
+import type { ToolCallUpdate } from '../generated/acp-protocol.generated'
+import type { AcpDialect } from './acp-dialect'
+
+// OpenCode reports a command's output and exit code under `rawOutput.metadata`; the shared shape
+// is `stdout` and `exitCode`.
+const commandRawOutputSchema = z.looseObject({
+  output: z.unknown().optional(),
+  metadata: z
+    .looseObject({
+      exit: z.number().int().nullable().optional(),
+      output: z.string().optional()
+    })
+    .optional()
+})
+
+function normalizeToolUpdate(update: ToolCallUpdate): ToolCallUpdate {
+  const parsed = commandRawOutputSchema.safeParse(update.rawOutput)
+  if (!parsed.success) {
+    return update
+  }
+  const rawOutput = parsed.data
+  const output =
+    typeof rawOutput.output === 'string' ? rawOutput.output : rawOutput.metadata?.output
+  const hasSharedOutput = ['stdout', 'stderr', 'output_for_prompt'].some(
+    (key) => rawOutput[key] !== undefined
+  )
+  const hasSharedExitCode = rawOutput.exitCode !== undefined || rawOutput.exit_code !== undefined
+  const exitCode = rawOutput.metadata?.exit ?? undefined
+  if ((output === undefined || hasSharedOutput) && (exitCode === undefined || hasSharedExitCode)) {
+    return update
+  }
+  return {
+    ...update,
+    rawOutput: {
+      ...rawOutput,
+      ...(output === undefined || hasSharedOutput ? {} : { stdout: output }),
+      ...(exitCode === undefined || hasSharedExitCode ? {} : { exitCode })
+    }
+  }
+}
+
+export const OPENCODE_ACP_DIALECT: AcpDialect = {
+  normalizeToolUpdate,
+  // OpenCode 1.x keeps an "always" grant in its own process, which is this chat's alone and ends
+  // whenever Orca ends it (a Stop, quitting, or stopping an idle chat's agent): not "always".
+  permissionOptionLabel: (option) =>
+    option.kind === 'allow_always' ? 'Allow until OpenCode restarts' : undefined
+}

src/main/acp/acp-launch-specs.ts

@@ -9,15 +9,26 @@ import {
 import { AGENT_HOOK_RUNTIME_ENV_KEYS } from '../ipc/pty/host-env/spawn-env-keys'
 import type { AcpDialect } from './acp-dialects/acp-dialect'
 import { GROK_ACP_DIALECT } from './acp-dialects/grok-dialect'
+import { OPENCODE_ACP_DIALECT } from './acp-dialects/opencode-dialect'
+import { directoryAccountBinding, type AcpAccountBinding } from './acp-account-binding'
+import { openCodeAcpAccountBinding } from '../opencode/opencode-structured-account-home'
+import { scrubOpenCodeAcpEnvironment } from '../opencode/opencode-acp-environment'
+import { openCodeStoredUserMessagesReader } from '../opencode/opencode-acp-stored-messages'
+import type { AcpStoredUserMessagesReader } from './acp-recovery-history'
+import { isStableCliVersionOnLine } from '../agent-cli-version-probe'
+import type { TuiAgent } from '../../shared/tui-agent'
 
 export type AcpLaunchSpec = {
-  /** The Orca agent id (a `TuiAgent`), which names the agent's records and its catalog label. */
-  agent: string
+  /** The Orca agent id, which names the agent's records, its catalog label and its settings. */
+  agent: TuiAgent
   command: string
   /** Built per launch: `fullAccess` is the Agent Permissions setting's bypass posture. */
   args(input: { fullAccess: boolean }): string[]
-  /** Overlaid on the child's environment. */
+  /** Laid over the child's environment last, after the account and the user's own variables. */
   env: Readonly<Record<string, string>>
+  /** Rewrites what the child would inherit from Orca's own plumbing; returns the keys it must not
+   *  inherit at all. `inherited` is the environment the child process starts from. */
+  scrubEnvironment?(env: Record<string, string>, inherited: NodeJS.ProcessEnv): string[]
   dialect: AcpDialect
   /** The agent's own sign-in command, for a person to run when it reports auth required. */
   loginCommand: readonly string[]
@@ -27,12 +38,17 @@ export type AcpLaunchSpec = {
     advertised: readonly string[]
     env: Readonly<Record<string, string>>
   }): string | undefined
-  /** Variable naming the agent's config directory, pinned as each record's account home. */
-  accountHomeVariable: string
-  /** The config directory the agent uses when the variable is unset, under the user's home. */
-  defaultAccountHome(homePath: string): string
+  /** The account each chat pins, and how a launch points the agent at it. */
+  account: AcpAccountBinding
+  /** The `--version` releases a structured chat runs on, asked before a create and again at every
+   *  launch; any other release keeps the terminal chat. Absent runs whatever is installed. */
+  supportsVersion?(version: string): boolean
   /** Where the agent installs its own binary, searched after PATH. */
-  installDirectories(accountHomePath: string): string[]
+  installDirectories(input: { env: Readonly<Record<string, string>>; homePath: string }): string[]
+  /** Images go to the agent when it also advertises them; off sends text prompts only. */
+  imagePrompts?: true
+  /** The agent's own store of a session's user messages, read for restart recovery only. */
+  readStoredUserMessages?: AcpStoredUserMessagesReader
 }
 
 const GROK_LAUNCH_SPEC: AcpLaunchSpec = {
@@ -50,12 +66,33 @@ const GROK_LAUNCH_SPEC: AcpLaunchSpec = {
       : advertised.includes('cached_token')
         ? 'cached_token'
         : undefined,
-  accountHomeVariable: 'GROK_HOME',
-  defaultAccountHome: (homePath) => join(homePath, '.grok'),
-  installDirectories: (accountHomePath) => [join(accountHomePath, 'bin')]
+  account: directoryAccountBinding('GROK_HOME', (homePath) => join(homePath, '.grok')),
+  installDirectories: ({ env }) => (env.GROK_HOME ? [join(env.GROK_HOME, 'bin')] : [])
 }
 
-export const ACP_LAUNCH_SPECS: readonly AcpLaunchSpec[] = [GROK_LAUNCH_SPEC]
+// OpenCode 1.x serves ACP in-process through `opencode acp`. OpenCode 2 (`opencode2`, and any
+// `opencode` that is 2.x) is not: its `acp` runs inside the user's own background service, which a
+// chat's environment and account pin do not reach, so it keeps its terminal-backed chat.
+const OPENCODE_LAUNCH_SPEC: AcpLaunchSpec = {
+  agent: 'opencode',
+  command: 'opencode',
+  // OpenCode has no bypass flag: full access answers each permission request yes.
+  args: () => ['acp'],
+  // Applied last: the client name ACP sessions report, and no question tool, which ACP cannot
+  // answer (it would wait forever).
+  env: { OPENCODE_CLIENT: 'acp', OPENCODE_ENABLE_QUESTION_TOOL: 'false' },
+  scrubEnvironment: scrubOpenCodeAcpEnvironment,
+  dialect: OPENCODE_ACP_DIALECT,
+  loginCommand: ['opencode', 'auth', 'login'],
+  account: openCodeAcpAccountBinding(),
+  installDirectories: ({ homePath }) => [join(homePath, '.opencode', 'bin')],
+  // Stable 1.x from 1.18.31, the release the recorded sessions capture.
+  supportsVersion: (version) => isStableCliVersionOnLine(version, { major: 1, floor: '1.18.31' }),
+  imagePrompts: true,
+  readStoredUserMessages: openCodeStoredUserMessagesReader()
+}
+
+export const ACP_LAUNCH_SPECS: readonly AcpLaunchSpec[] = [GROK_LAUNCH_SPEC, OPENCODE_LAUNCH_SPEC]
 
 export function acpLaunchSpecFor(agent: string): AcpLaunchSpec | null {
   return ACP_LAUNCH_SPECS.find((spec) => spec.agent === agent) ?? null

src/main/acp/acp-prompt-content.test.ts

@@ -0,0 +1,109 @@
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import type { AgentJournalMessageItem } from '../../shared/agent-session-journal-types'
+import type { NativeChatBlock } from '../../shared/native-chat-types'
+import {
+  ACP_PROMPT_IMAGE_MAX_BYTES,
+  AcpPromptContentError,
+  acpPromptBlocks
+} from './acp-prompt-content'
+
+const PNG = Buffer.from('89504e470d0a1a0a', 'hex')
+const dir = mkdtempSync(join(tmpdir(), 'acp-prompt-content-'))
+const pngPath = join(dir, 'shot.png')
+writeFileSync(pngPath, PNG)
+
+function message(...blocks: NativeChatBlock[]): AgentJournalMessageItem {
+  return { kind: 'message', role: 'user', blocks }
+}
+
+async function refusal(body: AgentJournalMessageItem, images = true) {
+  const error = await acpPromptBlocks(body, images).catch((caught: unknown) => caught)
+  if (!(error instanceof AcpPromptContentError)) {
+    throw new Error(`expected a refusal, got ${String(error)}`)
+  }
+  return error.failure
+}
+
+describe('ACP prompt content', () => {
+  it('sends text as text blocks', async () => {
+    await expect(acpPromptBlocks(message({ type: 'text', text: 'hi' }), false)).resolves.toEqual([
+      { type: 'text', text: 'hi' }
+    ])
+  })
+
+  it('sends a file or data image as an ACP image block, in order', async () => {
+    const data = PNG.toString('base64')
+    await expect(
+      acpPromptBlocks(
+        message(
+          { type: 'image-ref', path: pngPath },
+          { type: 'text', text: 'what is this?' },
+          { type: 'image-ref', url: pathToFileURL(pngPath).href },
+          { type: 'image-ref', url: `data:image/png;base64,${data}` }
+        ),
+        true
+      )
+    ).resolves.toEqual([
+      { type: 'image', mimeType: 'image/png', data },
+      { type: 'text', text: 'what is this?' },
+      { type: 'image', mimeType: 'image/png', data },
+      { type: 'image', mimeType: 'image/png', data }
+    ])
+  })
+
+  it('refuses an image when the agent takes none', async () => {
+    expect(await refusal(message({ type: 'image-ref', path: pngPath }), false)).toMatchObject({
+      kind: 'attachmentInvalid',
+      attachment: { reason: 'unsupportedType' }
+    })
+  })
+
+  it('refuses what it cannot read or send before anything leaves Orca', async () => {
+    expect(await refusal(message({ type: 'image-ref', path: 'relative.png' }))).toMatchObject({
+      attachment: { reason: 'noSource' }
+    })
+    expect(await refusal(message({ type: 'image-ref', path: join(dir, 'a.bmp') }))).toMatchObject({
+      attachment: { reason: 'unsupportedType' }
+    })
+    expect(await refusal(message({ type: 'image-ref', path: `${dir}.png` }))).toMatchObject({
+      kind: 'attachmentUnreadable'
+    })
+    expect(
+      await refusal(message({ type: 'image-ref', url: 'data:image/svg+xml;base64,PHN2Zz4=' }))
+    ).toMatchObject({ attachment: { reason: 'unsupportedType' } })
+  })
+
+  it('keeps a message with images within one protocol line', async () => {
+    // The images fit their raw limit, but with this much text the prompt would pass the line.
+    const text = 'x'.repeat(8 * 1024 * 1024)
+    const image = {
+      type: 'image-ref' as const,
+      url: `data:image/png;base64,${PNG.toString('base64')}`
+    }
+    expect(
+      await refusal(message({ type: 'text', text }, { type: 'text', text }, image))
+    ).toMatchObject({
+      attachment: { reason: 'totalTooLarge' }
+    })
+    expect(ACP_PROMPT_IMAGE_MAX_BYTES * (4 / 3)).toBeLessThan(16 * 1024 * 1024)
+  })
+
+  it('leaves a text-only message to the agent, however long', async () => {
+    const text = 'x'.repeat(9 * 1024 * 1024)
+    await expect(
+      acpPromptBlocks(message({ type: 'text', text }, { type: 'text', text }), true)
+    ).resolves.toHaveLength(2)
+  })
+
+  it("bounds one message's images together", async () => {
+    const big = Buffer.alloc(ACP_PROMPT_IMAGE_MAX_BYTES / 2 + 1).toString('base64')
+    const image = { type: 'image-ref' as const, url: `data:image/png;base64,${big}` }
+    expect(await refusal(message(image, image))).toMatchObject({
+      attachment: { reason: 'totalTooLarge', limit: ACP_PROMPT_IMAGE_MAX_BYTES }
+    })
+  })
+})