@zooid/acp-client 0.7.0

package/src/acp-client.ts

@@ -0,0 +1,361 @@
+import type { ChildProcess } from 'node:child_process'
+import { resolve as pathResolve } from 'node:path'
+import { Readable, Writable } from 'node:stream'
+import {
+  ClientSideConnection,
+  PROTOCOL_VERSION,
+  ndJsonStream,
+  type Client,
+} from '@agentclientprotocol/sdk'
+import { AgentProcess } from './agent-process.js'
+import { SessionMap } from './session-map.js'
+import { JsonFileSessionStore } from './session-store.js'
+import { resolvePreset } from './presets.js'
+import {
+  acpUpdateToAgentEvent,
+  approvalDecisionToPermissionResponse,
+} from './event-mapping.js'
+import { TurnTracker, type TapEvent } from './turn-tracker.js'
+import type {
+  AgentConfig,
+  AgentEvent,
+  ApprovalDecision,
+  ApprovalRequest,
+  PromptInput,
+  PromptResult,
+} from './types.js'
+
+/**
+ * Minimal interface for an external process spawner. Mirrors `AcpRuntime`
+ * in `@zooid/core` but kept structural here to avoid a back-edge.
+ */
+export interface SpawnRuntime {
+  spawn(spec: {
+    command: string
+    args: string[]
+    env?: Record<string, string>
+    cwd?: string
+    /** Container image. Honoured by container runtimes; ignored by local spawners. */
+    image?: string
+  }): ChildProcess
+}
+
+export interface AcpClientOptions {
+  agent: AgentConfig
+  /**
+   * Per-agent state directory (typically `<dataRoot>/agents/<agentId>/`).
+   * `sessions.json` is written here so threads survive daemon restarts.
+   * When omitted, session continuity across restarts is disabled (a warning
+   * is logged once on first ensureSession).
+   */
+  agentDataDir?: string
+  onEvent: (event: AgentEvent) => void
+  onApprovalRequest: (req: ApprovalRequest) => Promise<ApprovalDecision>
+  /**
+   * If set, the runtime is used to spawn the ACP shim process instead of
+   * the built-in `AgentProcess` host-spawn path. Lets the daemon launch
+   * the shim inside a container (DockerAcpRuntime) without changing the
+   * AcpClient surface.
+   */
+  runtime?: SpawnRuntime
+  /**
+   * Observability tap. Receives the unfiltered ACP protocol stream plus
+   * synthetic turn-boundary events (turn_started / turn_completed). Optional;
+   * when omitted the client behaves as before.
+   */
+  onTap?: (e: TapEvent) => void
+  /**
+   * Optional per-spawn factory. When set, the returned spec is included in
+   * `session/new mcpServers` (and `session/load mcpServers`) so the shim
+   * connects to the daemon-side zooid-context MCP server for the session
+   * lifetime. Called once per `ensureSession(threadId)`.
+   */
+  contextSpawn?: (threadId: string, channelId?: string) => Promise<{
+    name: 'zooid-context'
+    command: string
+    args: string[]
+    env: Array<{ name: string; value: string }>
+  }>
+}
+
+export class AcpClient {
+  private process: AgentProcess | null = null
+  private runtimeChild: ChildProcess | null = null
+  private connection: ClientSideConnection | null = null
+  private readonly sessions = new SessionMap()
+  private store: JsonFileSessionStore | null = null
+  private storeLoaded: Promise<void> | null = null
+  private agentCapabilities: { loadSession?: boolean } = {}
+  private warnedNoStore = false
+  private initialized = false
+  private readonly turns: TurnTracker | null
+
+  constructor(private readonly options: AcpClientOptions) {
+    this.turns = options.onTap
+      ? new TurnTracker({ agentId: options.agent.id, onTap: options.onTap })
+      : null
+  }
+
+  async start(): Promise<void> {
+    const { command, args } = this.resolveSpawn()
+    let stdout: Readable
+    let stdin: Writable
+    let stderr: Readable | null = null
+    if (this.options.runtime) {
+      const child = this.options.runtime.spawn({
+        command,
+        args,
+        env: this.options.agent.env,
+        cwd: this.options.agent.cwd,
+        image: this.options.agent.image,
+      })
+      this.runtimeChild = child
+      if (!child.stdout || !child.stdin) {
+        throw new Error('AcpClient: runtime returned a child without piped stdio')
+      }
+      stdout = child.stdout
+      stdin = child.stdin
+      stderr = child.stderr
+    } else {
+      this.process = new AgentProcess({
+        command,
+        args,
+        env: this.options.agent.env,
+        cwd: this.options.agent.cwd,
+      })
+      this.process.start()
+      stdout = this.process.stdout
+      stdin = this.process.stdin
+      stderr = this.process.stderr
+    }
+
+    if (stderr) forwardStderr(stderr, this.options.agent.id)
+
+    const input = Readable.toWeb(stdout) as ReadableStream<Uint8Array>
+    const output = Writable.toWeb(stdin) as WritableStream<Uint8Array>
+    const stream = ndJsonStream(output, input)
+
+    this.connection = new ClientSideConnection(() => this.buildClient(), stream)
+
+    const init = await this.connection.initialize({
+      protocolVersion: PROTOCOL_VERSION,
+      clientCapabilities: {
+        fs: { readTextFile: false, writeTextFile: false },
+        terminal: false,
+      },
+      clientInfo: { name: 'zooid', title: 'Zooid', version: '0.0.1' },
+    })
+    this.agentCapabilities = init.agentCapabilities ?? {}
+    this.initialized = true
+  }
+
+  async stop(): Promise<void> {
+    this.process?.kill()
+    this.runtimeChild?.kill('SIGTERM')
+    this.process = null
+    this.runtimeChild = null
+    this.connection = null
+    this.initialized = false
+  }
+
+  async ensureSession(threadId: string, channelId?: string): Promise<string> {
+    if (!this.connection || !this.initialized) {
+      throw new Error('AcpClient.start() must be called before ensureSession()')
+    }
+    await this.ensureStoreLoaded()
+
+    const key = { threadId, agentId: this.options.agent.id }
+    const cached = this.sessions.get(key)
+    if (cached) return cached.sessionId
+
+    const mcpServers = this.options.contextSpawn
+      ? [await this.options.contextSpawn(threadId, channelId)]
+      : []
+    process.stderr.write(
+      `[acp-client:${this.options.agent.id}] ensureSession(${threadId}) mcpServers=${
+        mcpServers.length === 0
+          ? '[]'
+          : JSON.stringify(mcpServers.map((s) => ({ name: s.name, command: s.command, args: s.args })))
+      }\n`,
+    )
+
+    const persisted = this.store?.get(threadId)
+    if (persisted && this.agentCapabilities.loadSession) {
+      try {
+        await this.connection.loadSession({
+          sessionId: persisted,
+          cwd: pathResolve(this.options.agent.cwd ?? process.cwd()),
+          mcpServers,
+        })
+        this.sessions.set(key, { sessionId: persisted, startedAt: Date.now() })
+        return persisted
+      } catch (err) {
+        console.warn(
+          `[acp-client:${this.options.agent.id}] loadSession(${persisted}) failed; ` +
+            `falling back to newSession:`,
+          err,
+        )
+        await this.store?.delete(threadId)
+      }
+    }
+
+    const { sessionId } = await this.connection.newSession({
+      cwd: pathResolve(this.options.agent.cwd ?? process.cwd()),
+      mcpServers,
+    })
+    this.sessions.set(key, { sessionId, startedAt: Date.now() })
+    await this.store?.set(threadId, sessionId)
+    return sessionId
+  }
+
+  private async ensureStoreLoaded(): Promise<void> {
+    if (!this.store) {
+      if (!this.options.agentDataDir) {
+        if (!this.warnedNoStore) {
+          console.warn(
+            `[acp-client:${this.options.agent.id}] no agentDataDir configured; ` +
+              `session continuity across restarts disabled`,
+          )
+          this.warnedNoStore = true
+        }
+        this.storeLoaded = Promise.resolve()
+        return this.storeLoaded
+      }
+      this.store = new JsonFileSessionStore({
+        agentId: this.options.agent.id,
+        dir: this.options.agentDataDir,
+      })
+    }
+    if (!this.storeLoaded) {
+      this.storeLoaded = this.store.load().catch((err) => {
+        console.warn(`[acp-client:${this.options.agent.id}] store load failed:`, err)
+      })
+    }
+    await this.storeLoaded
+  }
+
+  private async flushStore(): Promise<void> {
+    if (this.store) await this.store.flush()
+  }
+
+  async cancel(sessionId: string): Promise<void> {
+    if (!this.connection || !this.initialized) return
+    await this.connection.cancel({ sessionId })
+  }
+
+  /**
+   * Drop the session for the given thread so the next prompt starts fresh.
+   * No ACP-side cancellation — callers should ensure no prompt is in flight.
+   */
+  endSession(threadId: string): void {
+    this.sessions.delete({ threadId, agentId: this.options.agent.id })
+    void this.store?.delete(threadId)
+  }
+
+  async prompt(input: PromptInput): Promise<PromptResult> {
+    const sessionId = await this.ensureSession(input.threadId, input.channelId)
+    const promptText = stringifyPromptForLog(input.content)
+    this.turns?.startTurn({ sessionId, promptText })
+    debugLog(this.options.agent.id, 'prompt →', { sessionId, content: input.content })
+    try {
+      const result = await this.connection!.prompt({
+        sessionId,
+        prompt: input.content,
+      })
+      this.turns?.endTurn({ sessionId, stopReason: result.stopReason })
+      debugLog(this.options.agent.id, 'prompt ←', { sessionId, stopReason: result.stopReason })
+      return { stopReason: result.stopReason }
+    } catch (err) {
+      this.turns?.endTurn({ sessionId, stopReason: 'error' })
+      throw err
+    }
+  }
+
+  private resolveSpawn(): { command: string; args: string[] } {
+    const { preset, command, args, model } = this.options.agent
+    if (command) {
+      return { command, args: args ?? [] }
+    }
+    if (preset) {
+      return resolvePreset(preset, { model })
+    }
+    throw new Error('AcpClient: agent must specify either `preset` or `command`')
+  }
+
+  private buildClient(): Client {
+    const agentId = this.options.agent.id
+    return {
+      sessionUpdate: async (params) => {
+        this.turns?.observeUpdate(params.sessionId, params.update)
+        debugLog(agentId, 'sessionUpdate', params)
+        const event = acpUpdateToAgentEvent(params)
+        if (event) this.options.onEvent(event)
+        else debugLog(agentId, 'sessionUpdate dropped (unmapped)', params)
+      },
+      requestPermission: async (params) => {
+        debugLog(agentId, 'requestPermission', params)
+        const tc = params.toolCall as {
+          toolCallId: string
+          kind?: string
+          title?: string
+          rawInput?: unknown
+        }
+        const decision = await this.options.onApprovalRequest({
+          sessionId: params.sessionId,
+          toolCallId: tc.toolCallId,
+          toolKind: tc.kind,
+          toolTitle: tc.title,
+          toolInput: tc.rawInput,
+          options: params.options.map((o) => ({
+            optionId: o.optionId,
+            name: o.name,
+            kind: o.kind,
+          })),
+        })
+        debugLog(agentId, 'requestPermission ←', decision)
+        return approvalDecisionToPermissionResponse(decision)
+      },
+    }
+  }
+}
+
+function stringifyPromptForLog(content: PromptInput['content']): string {
+  try {
+    return JSON.stringify(content).slice(0, 4096)
+  } catch {
+    return '<unstringifiable>'
+  }
+}
+
+function debugLog(agentId: string, label: string, payload?: unknown): void {
+  if (payload === undefined) {
+    process.stderr.write(`[${agentId}] ${label}\n`)
+    return
+  }
+  let s: string
+  try {
+    s = JSON.stringify(payload)
+  } catch {
+    s = String(payload)
+  }
+  if (s.length > 2000) s = s.slice(0, 2000) + '…'
+  process.stderr.write(`[${agentId}] ${label} ${s}\n`)
+}
+
+function forwardStderr(stream: Readable, agentId: string): void {
+  let buf = ''
+  const prefix = `[${agentId}] `
+  stream.setEncoding('utf8')
+  stream.on('data', (chunk: string) => {
+    buf += chunk
+    let nl: number
+    while ((nl = buf.indexOf('\n')) !== -1) {
+      const line = buf.slice(0, nl)
+      buf = buf.slice(nl + 1)
+      process.stderr.write(prefix + line + '\n')
+    }
+  })
+  stream.on('end', () => {
+    if (buf.length > 0) process.stderr.write(prefix + buf + '\n')
+  })
+}

package/src/agent-process.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { EventEmitter } from 'node:events'
+import { Readable, Writable } from 'node:stream'
+
+const spawnMock = vi.fn()
+
+vi.mock('node:child_process', () => ({
+  spawn: spawnMock,
+}))
+
+const { AgentProcess } = await import('./agent-process.js')
+
+class FakeChild extends EventEmitter {
+  stdout = new Readable({ read() {} })
+  stdin = new Writable({
+    write(_c, _e, cb) {
+      cb()
+    },
+  })
+  stderr = new Readable({ read() {} })
+  pid = 12345
+  kill = vi.fn(() => true)
+}
+
+describe('AgentProcess', () => {
+  beforeEach(() => {
+    spawnMock.mockReset()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('spawns the configured command with args, piped stdio, and env', () => {
+    const child = new FakeChild()
+    spawnMock.mockReturnValue(child)
+
+    const proc = new AgentProcess({
+      command: 'opencode',
+      args: ['acp'],
+      env: { OPENAI_API_KEY: 'sk-test' },
+      cwd: '/workspace',
+    })
+    proc.start()
+
+    expect(spawnMock).toHaveBeenCalledTimes(1)
+    const [cmd, args, options] = spawnMock.mock.calls[0]
+    expect(cmd).toBe('opencode')
+    expect(args).toEqual(['acp'])
+    expect(options.stdio).toEqual(['pipe', 'pipe', 'pipe'])
+    expect(options.env).toMatchObject({ OPENAI_API_KEY: 'sk-test' })
+    expect(options.cwd).toBe('/workspace')
+  })
+
+  it('exposes stdout and stdin streams from the spawned child', () => {
+    const child = new FakeChild()
+    spawnMock.mockReturnValue(child)
+
+    const proc = new AgentProcess({ command: 'x', args: [] })
+    proc.start()
+
+    expect(proc.stdout).toBe(child.stdout)
+    expect(proc.stdin).toBe(child.stdin)
+  })
+
+  it('emits "exit" with code when the child exits', async () => {
+    const child = new FakeChild()
+    spawnMock.mockReturnValue(child)
+
+    const proc = new AgentProcess({ command: 'x', args: [] })
+    proc.start()
+
+    const exitPromise = new Promise<number | null>((resolve) => {
+      proc.on('exit', resolve)
+    })
+    child.emit('exit', 0, null)
+    await expect(exitPromise).resolves.toBe(0)
+  })
+
+  it('kill() forwards SIGTERM to the child', () => {
+    const child = new FakeChild()
+    spawnMock.mockReturnValue(child)
+
+    const proc = new AgentProcess({ command: 'x', args: [] })
+    proc.start()
+    proc.kill()
+    expect(child.kill).toHaveBeenCalledWith('SIGTERM')
+  })
+
+  it('inherits parent env unless inheritEnv is false', () => {
+    process.env.FROM_PARENT = 'yes'
+    const child = new FakeChild()
+    spawnMock.mockReturnValue(child)
+
+    const proc = new AgentProcess({ command: 'x', args: [], env: { EXTRA: '1' } })
+    proc.start()
+
+    const [, , options] = spawnMock.mock.calls[0]
+    expect(options.env.FROM_PARENT).toBe('yes')
+    expect(options.env.EXTRA).toBe('1')
+    delete process.env.FROM_PARENT
+  })
+})

package/src/agent-process.ts

@@ -0,0 +1,49 @@
+import { spawn, type ChildProcess } from 'node:child_process'
+import { EventEmitter } from 'node:events'
+import type { Readable, Writable } from 'node:stream'
+
+export interface AgentProcessOptions {
+  command: string
+  args?: string[]
+  env?: Record<string, string>
+  cwd?: string
+}
+
+export class AgentProcess extends EventEmitter {
+  private child: ChildProcess | null = null
+
+  constructor(private readonly options: AgentProcessOptions) {
+    super()
+  }
+
+  start(): void {
+    if (this.child) return
+    const env = { ...process.env, ...(this.options.env ?? {}) }
+    this.child = spawn(this.options.command, this.options.args ?? [], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env,
+      cwd: this.options.cwd,
+    })
+    this.child.on('exit', (code, signal) => this.emit('exit', code, signal))
+    this.child.on('error', (err) => this.emit('error', err))
+  }
+
+  kill(signal: NodeJS.Signals = 'SIGTERM'): void {
+    this.child?.kill(signal)
+  }
+
+  get stdout(): Readable {
+    if (!this.child?.stdout) throw new Error('agent process not started')
+    return this.child.stdout
+  }
+
+  get stdin(): Writable {
+    if (!this.child?.stdin) throw new Error('agent process not started')
+    return this.child.stdin
+  }
+
+  get stderr(): Readable {
+    if (!this.child?.stderr) throw new Error('agent process not started')
+    return this.child.stderr
+  }
+}

package/src/event-mapping.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect } from 'vitest'
+import {
+  acpUpdateToAgentEvent,
+  approvalDecisionToPermissionResponse,
+} from './event-mapping.js'
+import type { AgentEvent } from './types.js'
+
+describe('acpUpdateToAgentEvent', () => {
+  it('maps agent_message_chunk to agent_message_chunk event', () => {
+    const event = acpUpdateToAgentEvent({
+      sessionId: 's-1',
+      update: {
+        sessionUpdate: 'agent_message_chunk',
+        content: { type: 'text', text: 'hello' },
+      },
+    })
+    expect(event).toEqual<AgentEvent>({
+      type: 'agent_message_chunk',
+      sessionId: 's-1',
+      content: { type: 'text', text: 'hello' },
+    })
+  })
+
+  it('maps tool_call to tool_call event with id, title, kind, status', () => {
+    const event = acpUpdateToAgentEvent({
+      sessionId: 's-1',
+      update: {
+        sessionUpdate: 'tool_call',
+        toolCallId: 'tc-7',
+        title: 'Reading auth.ts',
+        kind: 'read',
+        status: 'pending',
+      },
+    })
+    expect(event).toEqual<AgentEvent>({
+      type: 'tool_call',
+      sessionId: 's-1',
+      toolCallId: 'tc-7',
+      title: 'Reading auth.ts',
+      kind: 'read',
+      status: 'pending',
+    })
+  })
+
+  it('maps tool_call_update with diff content', () => {
+    const event = acpUpdateToAgentEvent({
+      sessionId: 's-1',
+      update: {
+        sessionUpdate: 'tool_call_update',
+        toolCallId: 'tc-7',
+        status: 'completed',
+        content: [{ type: 'diff', path: '/abs/auth.ts', oldText: 'a', newText: 'b' }],
+      },
+    })
+    expect(event).toEqual<AgentEvent>({
+      type: 'tool_call_update',
+      sessionId: 's-1',
+      toolCallId: 'tc-7',
+      status: 'completed',
+      kind: undefined,
+      content: [{ type: 'diff', path: '/abs/auth.ts', oldText: 'a', newText: 'b' }],
+    })
+  })
+
+  it('maps plan update', () => {
+    const event = acpUpdateToAgentEvent({
+      sessionId: 's-1',
+      update: {
+        sessionUpdate: 'plan',
+        entries: [{ content: 'Step 1', priority: 'high', status: 'pending' }],
+      },
+    })
+    expect(event?.type).toBe('plan')
+    if (event?.type === 'plan') {
+      expect(event.entries).toHaveLength(1)
+      expect(event.entries[0].content).toBe('Step 1')
+    }
+  })
+
+  it('returns null for unknown update variants (forward-compat)', () => {
+    const event = acpUpdateToAgentEvent({
+      sessionId: 's-1',
+      // @ts-expect-error — exercising unknown variant
+      update: { sessionUpdate: 'something_new', foo: 'bar' },
+    })
+    expect(event).toBeNull()
+  })
+})
+
+describe('approvalDecisionToPermissionResponse', () => {
+  it('maps an allow decision to a selected outcome with the chosen optionId', () => {
+    const res = approvalDecisionToPermissionResponse({
+      decision: 'allow',
+      optionId: 'allow-once',
+    })
+    expect(res).toEqual({
+      outcome: { outcome: 'selected', optionId: 'allow-once' },
+    })
+  })
+
+  it('maps a cancel decision to a cancelled outcome', () => {
+    const res = approvalDecisionToPermissionResponse({ decision: 'cancel' })
+    expect(res).toEqual({ outcome: { outcome: 'cancelled' } })
+  })
+})

package/src/event-mapping.ts

@@ -0,0 +1,69 @@
+import type {
+  RequestPermissionResponse,
+  SessionNotification,
+  ToolCallContent,
+  ToolCallStatus,
+  ToolKind,
+} from '@agentclientprotocol/sdk'
+import type { AgentEvent, ApprovalDecision } from './types.js'
+
+export function acpUpdateToAgentEvent(
+  notif: SessionNotification,
+): AgentEvent | null {
+  const { sessionId, update } = notif
+  switch (update.sessionUpdate) {
+    case 'agent_message_chunk':
+      return {
+        type: 'agent_message_chunk',
+        sessionId,
+        content: update.content,
+      }
+    case 'tool_call':
+      return {
+        type: 'tool_call',
+        sessionId,
+        toolCallId: update.toolCallId,
+        title: update.title,
+        kind: update.kind,
+        status: update.status,
+        rawInput: update.rawInput,
+        locations: mapLocations(update.locations),
+      }
+    case 'tool_call_update':
+      return {
+        type: 'tool_call_update',
+        sessionId,
+        toolCallId: update.toolCallId,
+        status: nullToUndef<ToolCallStatus>(update.status),
+        kind: nullToUndef<ToolKind>(update.kind),
+        content: nullToUndef<ToolCallContent[]>(update.content),
+        rawInput: update.rawInput,
+        rawOutput: update.rawOutput,
+        locations: mapLocations(update.locations),
+      }
+    case 'plan':
+      return { type: 'plan', sessionId, entries: update.entries }
+    default:
+      return null
+  }
+}
+
+export function approvalDecisionToPermissionResponse(
+  decision: ApprovalDecision,
+): RequestPermissionResponse {
+  if (decision.decision === 'cancel') {
+    return { outcome: { outcome: 'cancelled' } }
+  }
+  return { outcome: { outcome: 'selected', optionId: decision.optionId } }
+}
+
+function nullToUndef<T>(v: T | null | undefined): T | undefined {
+  return v ?? undefined
+}
+
+function mapLocations(
+  locs: Array<{ path: string; line?: number | null }> | null | undefined,
+): { path: string; line?: number }[] | undefined {
+  if (!locs || locs.length === 0) return undefined
+  return locs.map((l) => ({ path: l.path, line: l.line ?? undefined }))
+}