feat: route opencode through headless spawn via app-server

OpenCode exposes an HTTP app-server (opencode serve); relay connects to it
instead of spawning an interactive PTY. spawnAgentOnce routes cli=opencode
through spawnCli({ transport: 'headless' }) (relay 8.3.0 API).

Adds the agentRuntimes map and attachTerminal headless guard so PTY-only
operations (resize, snapshot) are skipped for OpenCode agents. worker_stream
chunks still flow through broker:pty-chunk → xterm for V1 terminal rendering.

https://claude.ai/code/session_01KXU1uAUwx3L82TMLnAmU4z

Author: claude

src/main/broker.test.ts

@@ -16,6 +16,7 @@ type MockClient = {
   resizePty: ReturnType<typeof vi.fn>
   getPending: ReturnType<typeof vi.fn>
   spawnPty: ReturnType<typeof vi.fn>
+  spawnCli: ReturnType<typeof vi.fn>
   onEvent: ReturnType<typeof vi.fn>
   addListener: ReturnType<typeof vi.fn>
   connectEvents: ReturnType<typeof vi.fn>
@@ -44,6 +45,10 @@ const mock = vi.hoisted(() => {
         client.agentNames.push(input.name)
         return { name: input.name, runtime: 'pty' }
       }),
+      spawnCli: vi.fn(async (input: { name: string }) => {
+        client.agentNames.push(input.name)
+        return { name: input.name, runtime: 'headless' }
+      }),
       setInboundDeliveryMode: vi.fn(async (_name: string, mode: string) => ({ mode, flushed: 0 })),
       snapshot: vi.fn(async () => ({ rows: 24, cols: 80, cursor: { x: 0, y: 0 }, screen: 'aGVsbG8=' })),
       resizePty: vi.fn(async () => undefined),

src/main/broker.ts

@@ -9,6 +9,7 @@ import {
   HarnessDriverClient as AgentRelayClient,
   type RuntimeSpawnOptions as AgentRelaySpawnOptions,
   type SpawnPtyInput,
+  type SpawnCliInput,
   type SendMessageInput,
   type BrokerEvent,
   type BrokerStatus,
@@ -1182,6 +1183,9 @@ export class BrokerManager {
   // so agent names are project-unique in practice — the set tracks which
   // session actually owns the worker so agent-scoped calls route correctly.
   private agentSessions = new Map<string, Set<string>>()
+  // Tracks the runtime for each agent name so attachTerminal can skip PTY
+  // operations (snapshot, resizePty, input streams) for headless agents.
+  private agentRuntimes = new Map<string, 'pty' | 'headless'>()
   private inputStreams = new Map<string, PtyInputStream>()
   private inputStreamFallbacks = new Set<string>()
   private inputStreamFallbackRetryAt = new Map<string, number>()
@@ -2037,12 +2041,16 @@ export class BrokerManager {
 
       if (event.kind === 'agent_spawned' && event.name) {
         this.rememberAgentSession(event.name, sessionKey)
+        if ('runtime' in event && (event.runtime === 'pty' || event.runtime === 'headless')) {
+          this.agentRuntimes.set(event.name, event.runtime)
+        }
         if (event.parent) {
           void this.handleSpawnedChildLineage(sessionKey, event)
         }
       } else if (event.kind === 'agent_exit' && event.name) {
         this.closeInputStream(this.getInputStreamKey(sessionKey, event.name), 1000, 'agent closed')
         this.forgetAgentSession(event.name, sessionKey)
+        this.agentRuntimes.delete(event.name)
         void client.release(event.name, 'agent exit').catch((err) => {
           if (!isMissingAgentError(err)) {
             console.warn(`[broker] Failed to release exited agent ${event.name}:`, err)
@@ -2051,6 +2059,7 @@ export class BrokerManager {
       } else if ((event.kind === 'agent_exited' || event.kind === 'agent_released') && event.name) {
         this.closeInputStream(this.getInputStreamKey(sessionKey, event.name), 1000, 'agent closed')
         this.forgetAgentSession(event.name, sessionKey)
+        this.agentRuntimes.delete(event.name)
       } else if ('name' in event && typeof event.name === 'string') {
         this.rememberAgentSession(event.name, sessionKey)
       } else if ('from' in event && typeof event.from === 'string') {
@@ -2376,8 +2385,22 @@ export class BrokerManager {
             nextInput.cli
           )
         }
-        const spawned = await session.client.spawnPty(nextInput)
+        // OpenCode exposes an HTTP app-server; run it headless so relay connects
+        // to the server instead of spawning an interactive PTY. worker_stream
+        // chunks still flow to broker:pty-chunk → xterm for V1 rendering.
+        const useHeadless = !shellSession && spawnCliLabel(nextInput.cli) === 'opencode'
+        const headlessClient = session.client as AgentRelayClient & {
+          spawnCli(input: SpawnCliInput): Promise<{ name: string; runtime: string }>
+        }
+        const spawned = useHeadless
+          ? await headlessClient.spawnCli({ ...nextInput, transport: 'headless' } as SpawnCliInput)
+          : await session.client.spawnPty(nextInput)
         const spawnedName = spawned.name || nextInput.name
+        const resolvedRuntime: 'pty' | 'headless' =
+          spawned.runtime === 'headless' || (useHeadless && !spawned.runtime) ? 'headless' : 'pty'
+        // Set immediately so attachTerminal sees the correct runtime before the
+        // async agent_spawned event fires.
+        this.agentRuntimes.set(spawnedName, resolvedRuntime)
         this.rememberAgentSession(spawnedName, sessionKeyFor(session))
         const burnInput = { ...nextInput, name: spawnedName }
         const lineage = session.pearLineage.get(spawnedName)
@@ -2393,12 +2416,7 @@ export class BrokerManager {
         ).catch((err) => {
           console.warn('[burn-spawn-hook] post-spawn burn stamp failed:', err)
         })
-        return {
-          name: spawnedName,
-          runtime: typeof spawned.runtime === 'string' && spawned.runtime.trim()
-            ? spawned.runtime
-            : 'pty'
-        }
+        return { name: spawnedName, runtime: resolvedRuntime }
       } catch (err) {
         if (!isAgentNameConflict(err)) {
           throw buildSpawnFailureError(err, nextInput, session.cloudSandboxId ? 'cloud' : 'local')
@@ -2731,6 +2749,7 @@ export class BrokerManager {
       console.warn(`[broker] attachTerminal: ${name} did not appear in listAgents within wait window; falling through to per-call retry`)
     }
     const mode = toInboundDeliveryMode(input.mode)
+    const isHeadless = this.agentRuntimes.get(name) === 'headless'
     let previousMode: InboundDeliveryMode | undefined
 
     try {
@@ -2743,6 +2762,14 @@ export class BrokerManager {
     // queue mode while human terminal input continues to go through sendInput.
     await this.withAgentMissingRetry('setInboundDeliveryMode', name, () => client.setInboundDeliveryMode(name, mode))
 
+    // Headless agents (app-server based) have no PTY — skip resize and snapshot.
+    if (isHeadless) {
+      const pending = mode === 'manual_flush'
+        ? await this.withAgentMissingRetry('getPending', name, () => client.getPending(name)).then((messages) => messages.length).catch(() => 0)
+        : 0
+      return { name, mode, previousMode, pending, runtime: 'headless' }
+    }
+
     let resizedBeforeSnapshot = false
     if (isPositiveInteger(input.rows) && isPositiveInteger(input.cols)) {
       try {