@zooid/acp-client 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zooid contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@zooid/acp-client",
+  "version": "0.7.0",
+  "description": "Zooid's ACP client: spawn agent subprocesses, drive them via Agent Client Protocol, route events and permission requests through callbacks.",
+  "type": "module",
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^0.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.2.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/acp-client.cancel.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect, vi } from 'vitest'
+import { AcpClient } from './acp-client.js'
+
+describe('AcpClient.cancel', () => {
+  it('forwards to the underlying ClientSideConnection.cancel with the sessionId', async () => {
+    const fakeCancel = vi.fn(async () => {})
+    const fakeConnection = { cancel: fakeCancel }
+    const client = new AcpClient({
+      agent: { id: 'a', command: 'noop', args: [] },
+      onEvent: () => {},
+      onApprovalRequest: async () => ({ decision: 'cancel' }),
+    })
+    // Skip start(); install the connection directly.
+    ;(client as unknown as { connection: typeof fakeConnection }).connection = fakeConnection
+    ;(client as unknown as { initialized: boolean }).initialized = true
+    await client.cancel('sess-abc')
+    expect(fakeCancel).toHaveBeenCalledWith({ sessionId: 'sess-abc' })
+  })
+
+  it('is a no-op (does not throw) when never started', async () => {
+    const client = new AcpClient({
+      agent: { id: 'a', command: 'noop', args: [] },
+      onEvent: () => {},
+      onApprovalRequest: async () => ({ decision: 'cancel' }),
+    })
+    await expect(client.cancel('sess-abc')).resolves.toBeUndefined()
+  })
+
+  it('is idempotent — second cancel for the same sessionId is forwarded again without error', async () => {
+    const fakeCancel = vi.fn(async () => {})
+    const client = new AcpClient({
+      agent: { id: 'a', command: 'noop', args: [] },
+      onEvent: () => {},
+      onApprovalRequest: async () => ({ decision: 'cancel' }),
+    })
+    ;(client as unknown as { connection: { cancel: typeof fakeCancel } }).connection = {
+      cancel: fakeCancel,
+    }
+    ;(client as unknown as { initialized: boolean }).initialized = true
+    await client.cancel('sess-abc')
+    await client.cancel('sess-abc')
+    expect(fakeCancel).toHaveBeenCalledTimes(2)
+  })
+})

package/src/acp-client.context.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect, vi } from 'vitest'
+import { AcpClient } from './acp-client.js'
+
+function injectConnection(client: AcpClient, calls: Array<{ method: string; params: unknown }>) {
+  const connection = {
+    newSession: vi.fn(async (params: unknown) => {
+      calls.push({ method: 'newSession', params })
+      return { sessionId: 'sess-1' }
+    }),
+    loadSession: vi.fn(async (params: unknown) => {
+      calls.push({ method: 'loadSession', params })
+      return {}
+    }),
+  }
+  // @ts-expect-error — test reaches into private state to skip subprocess spawn
+  client.connection = connection
+  // @ts-expect-error
+  client.initialized = true
+  // @ts-expect-error
+  client.agentCapabilities = { loadSession: true }
+  return connection
+}
+
+describe('AcpClient — context MCP wiring', () => {
+  it('omits zooid-context from mcpServers when no contextSpawn factory is set', async () => {
+    const calls: Array<{ method: string; params: unknown }> = []
+    const client = new AcpClient({
+      agent: { id: 'architect', command: 'x', args: [] },
+      onEvent: () => {},
+      onApprovalRequest: async () => ({ decision: 'allow', optionId: 'allow' }),
+    })
+    injectConnection(client, calls)
+    await client.ensureSession('!room:hs')
+    const params = calls.find((c) => c.method === 'newSession')!.params as {
+      mcpServers: unknown[]
+    }
+    expect(params.mcpServers).toEqual([])
+  })
+
+  it('includes the zooid-context mcpServer entry when contextSpawn is set', async () => {
+    const calls: Array<{ method: string; params: unknown }> = []
+    const contextSpawn = vi.fn(async (threadId: string) => ({
+      name: 'zooid-context' as const,
+      command: 'node',
+      args: ['/bin/zooid-context-mcp.js', '--spawn-id', `spawn-${threadId}`],
+      env: [{ name: 'ZOOID_DAEMON_SOCK', value: '/run/zooid/test.sock' }],
+    }))
+    const client = new AcpClient({
+      agent: { id: 'architect', command: 'x', args: [] },
+      onEvent: () => {},
+      onApprovalRequest: async () => ({ decision: 'allow', optionId: 'allow' }),
+      contextSpawn,
+    })
+    injectConnection(client, calls)
+    await client.ensureSession('!room:hs')
+    expect(contextSpawn).toHaveBeenCalledWith('!room:hs', undefined)
+    const params = calls.find((c) => c.method === 'newSession')!.params as {
+      mcpServers: Array<{ name: string; args: string[] }>
+    }
+    expect(params.mcpServers).toHaveLength(1)
+    expect(params.mcpServers[0].name).toBe('zooid-context')
+    expect(params.mcpServers[0].args).toContain('--spawn-id')
+    expect(params.mcpServers[0].args).toContain('spawn-!room:hs')
+  })
+
+  it('includes zooid-context in loadSession mcpServers too', async () => {
+    const calls: Array<{ method: string; params: unknown }> = []
+    const contextSpawn = vi.fn(async () => ({
+      name: 'zooid-context' as const,
+      command: 'node',
+      args: ['/bin/zooid-context-mcp.js'],
+      env: [],
+    }))
+    const client = new AcpClient({
+      agent: { id: 'architect', command: 'x', args: [] },
+      agentDataDir: '/tmp/zooid-acp-test',
+      onEvent: () => {},
+      onApprovalRequest: async () => ({ decision: 'allow', optionId: 'allow' }),
+      contextSpawn,
+    })
+    const conn = injectConnection(client, calls)
+    // @ts-expect-error
+    client.store = { load: async () => {}, get: () => 'sess-old', set: async () => {}, delete: async () => {} }
+    // @ts-expect-error
+    client.storeLoaded = Promise.resolve()
+    await client.ensureSession('!room:hs')
+    expect(conn.loadSession).toHaveBeenCalled()
+    const params = calls.find((c) => c.method === 'loadSession')!.params as {
+      mcpServers: Array<{ name: string }>
+    }
+    expect(params.mcpServers.map((s) => s.name)).toEqual(['zooid-context'])
+  })
+})

package/src/acp-client.preset.test.ts

@@ -0,0 +1,120 @@
+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 { AcpClient } = await import('./acp-client.js')
+
+class FakeChild extends EventEmitter {
+  stdout = new Readable({ read() {} })
+  stdin = new Writable({
+    write(_c, _e, cb) {
+      cb()
+    },
+  })
+  stderr = new Readable({ read() {} })
+  pid = 99999
+  kill = vi.fn(() => true)
+}
+
+describe('AcpClient preset support', () => {
+  beforeEach(() => {
+    spawnMock.mockReset()
+    spawnMock.mockReturnValue(new FakeChild())
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('spawns the preset command/args when agent.preset is set', async () => {
+    const client = new AcpClient({
+      agent: { id: 'claude-1', preset: 'claude' },
+      onEvent: () => {},
+      onApprovalRequest: async () => ({ decision: 'cancel' }),
+    })
+
+    void client.start().catch(() => {})
+
+    expect(spawnMock).toHaveBeenCalledTimes(1)
+    const [cmd, args] = spawnMock.mock.calls[0]
+    expect(cmd).toBe('npx')
+    expect(args).toEqual(['-y', '@agentclientprotocol/claude-agent-acp'])
+
+    await client.stop()
+  })
+
+  it('still accepts explicit command/args (no preset)', async () => {
+    const client = new AcpClient({
+      agent: { id: 'opencode-1', command: 'opencode', args: ['acp'] },
+      onEvent: () => {},
+      onApprovalRequest: async () => ({ decision: 'cancel' }),
+    })
+    void client.start().catch(() => {})
+
+    const [cmd, args] = spawnMock.mock.calls[0]
+    expect(cmd).toBe('opencode')
+    expect(args).toEqual(['acp'])
+    await client.stop()
+  })
+
+  it('lets explicit command override a preset', async () => {
+    const client = new AcpClient({
+      agent: {
+        id: 'claude-custom',
+        preset: 'claude',
+        command: '/usr/local/bin/my-claude-acp',
+        args: ['--verbose'],
+      },
+      onEvent: () => {},
+      onApprovalRequest: async () => ({ decision: 'cancel' }),
+    })
+    void client.start().catch(() => {})
+
+    const [cmd, args] = spawnMock.mock.calls[0]
+    expect(cmd).toBe('/usr/local/bin/my-claude-acp')
+    expect(args).toEqual(['--verbose'])
+    await client.stop()
+  })
+
+  it('throws if neither preset nor command is provided', async () => {
+    const client = new AcpClient({
+      // @ts-expect-error — missing both command and preset
+      agent: { id: 'broken' },
+      onEvent: () => {},
+      onApprovalRequest: async () => ({ decision: 'cancel' }),
+    })
+    await expect(client.start()).rejects.toThrow(/preset.*or.*command/i)
+  })
+
+  it('throws on an unknown preset name', async () => {
+    const client = new AcpClient({
+      // @ts-expect-error — preset is typed to known names
+      agent: { id: 'broken', preset: 'made-up' },
+      onEvent: () => {},
+      onApprovalRequest: async () => ({ decision: 'cancel' }),
+    })
+    await expect(client.start()).rejects.toThrow(/unknown ACP preset/i)
+  })
+
+  it('forwards env and cwd alongside a preset', async () => {
+    const client = new AcpClient({
+      agent: {
+        id: 'claude-2',
+        preset: 'claude',
+        env: { ANTHROPIC_API_KEY: 'sk-test' },
+        cwd: '/workspace',
+      },
+      onEvent: () => {},
+      onApprovalRequest: async () => ({ decision: 'cancel' }),
+    })
+    void client.start().catch(() => {})
+
+    const [, , options] = spawnMock.mock.calls[0]
+    expect(options.env.ANTHROPIC_API_KEY).toBe('sk-test')
+    expect(options.cwd).toBe('/workspace')
+    await client.stop()
+  })
+})

package/src/acp-client.runtime.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect, vi } from 'vitest'
+import { EventEmitter } from 'node:events'
+import { Readable, Writable } from 'node:stream'
+import type { ChildProcess } from 'node:child_process'
+import { AcpClient } from './acp-client.js'
+
+class FakeChild extends EventEmitter {
+  stdout = new Readable({ read() {} })
+  stdin = new Writable({ write(_c, _e, cb) { cb() } })
+  stderr = new Readable({ read() {} })
+  pid = 1
+  kill = vi.fn(() => true)
+}
+
+describe('AcpClient honors a passed-in runtime', () => {
+  it('delegates the spawn to the runtime when one is provided', () => {
+    const child = new FakeChild() as unknown as ChildProcess
+    const rt = { spawn: vi.fn().mockReturnValue(child) }
+    const client = new AcpClient({
+      agent: { id: 'x', command: 'foo', args: ['bar'], env: { K: 'v' }, cwd: '/x' },
+      onEvent: () => {},
+      onApprovalRequest: async () => ({ decision: 'cancel' }),
+      runtime: rt,
+    })
+    void client.start().catch(() => {})
+    expect(rt.spawn).toHaveBeenCalledTimes(1)
+    expect(rt.spawn).toHaveBeenCalledWith(
+      expect.objectContaining({
+        command: 'foo',
+        args: ['bar'],
+        env: { K: 'v' },
+        cwd: '/x',
+      }),
+    )
+  })
+
+  it('resolves a preset before passing to the runtime', () => {
+    const child = new FakeChild() as unknown as ChildProcess
+    const rt = { spawn: vi.fn().mockReturnValue(child) }
+    const client = new AcpClient({
+      agent: { id: 'c', preset: 'claude' },
+      onEvent: () => {},
+      onApprovalRequest: async () => ({ decision: 'cancel' }),
+      runtime: rt,
+    })
+    void client.start().catch(() => {})
+    const arg = rt.spawn.mock.calls[0][0]
+    expect(arg.command).toBe('npx')
+    expect(arg.args).toEqual(['-y', '@agentclientprotocol/claude-agent-acp'])
+  })
+})

package/src/acp-client.session-load.test.ts

@@ -0,0 +1,184 @@
+import { mkdtemp } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { AcpClient } from './acp-client.js'
+
+function makeStubbedClient(opts: {
+  agentDataDir: string
+  agentId: string
+  loadSessionCapability: boolean
+  newSessionImpl?: () => Promise<{ sessionId: string }>
+  loadSessionImpl?: (req: { sessionId: string }) => Promise<unknown>
+}) {
+  const newSession = vi.fn(opts.newSessionImpl ?? (async () => ({ sessionId: 'sess_new' })))
+  const loadSession = vi.fn(
+    opts.loadSessionImpl ?? (async () => ({})),
+  )
+  const fakeConnection = {
+    initialize: vi.fn(async () => ({
+      protocolVersion: 1,
+      agentCapabilities: { loadSession: opts.loadSessionCapability },
+    })),
+    newSession,
+    loadSession,
+    prompt: vi.fn(async () => ({ stopReason: 'end_turn' })),
+    cancel: vi.fn(async () => {}),
+  }
+
+  const client = new AcpClient({
+    agent: { id: opts.agentId, command: '/bin/true' },
+    agentDataDir: opts.agentDataDir,
+    onEvent: () => {},
+    onApprovalRequest: async () => ({ decision: 'cancel' }),
+  })
+  ;(client as unknown as { connection: typeof fakeConnection }).connection = fakeConnection
+  ;(client as unknown as { initialized: boolean }).initialized = true
+  ;(client as unknown as { agentCapabilities: { loadSession?: boolean } }).agentCapabilities = {
+    loadSession: opts.loadSessionCapability,
+  }
+  return { client, fakeConnection, newSession, loadSession }
+}
+
+describe('AcpClient.ensureSession resume', () => {
+  let agentDataDir: string
+  beforeEach(async () => {
+    agentDataDir = await mkdtemp(join(tmpdir(), 'acpclient-ensure-'))
+  })
+  afterEach(async () => {
+    await import('node:fs/promises').then((fs) => fs.rm(agentDataDir, { recursive: true, force: true }))
+  })
+
+  it('first call mints via newSession and persists the id', async () => {
+    const { client, newSession, loadSession } = makeStubbedClient({
+      agentDataDir,
+      agentId: 'docs',
+      loadSessionCapability: true,
+      newSessionImpl: async () => ({ sessionId: 'sess_first' }),
+    })
+    await (client as unknown as { ensureStoreLoaded: () => Promise<void> }).ensureStoreLoaded()
+
+    const id = await client.ensureSession('$root1')
+    expect(id).toBe('sess_first')
+    expect(newSession).toHaveBeenCalledTimes(1)
+    expect(loadSession).not.toHaveBeenCalled()
+  })
+
+  it('a fresh AcpClient on the same agent data dir resumes via loadSession when capability is on', async () => {
+    {
+      const a = makeStubbedClient({
+        agentDataDir,
+        agentId: 'docs',
+        loadSessionCapability: true,
+        newSessionImpl: async () => ({ sessionId: 'sess_persist' }),
+      })
+      await (a.client as unknown as { ensureStoreLoaded: () => Promise<void> }).ensureStoreLoaded()
+      await a.client.ensureSession('$root1')
+    }
+
+    const b = makeStubbedClient({
+      agentDataDir,
+      agentId: 'docs',
+      loadSessionCapability: true,
+    })
+    await (b.client as unknown as { ensureStoreLoaded: () => Promise<void> }).ensureStoreLoaded()
+
+    const id = await b.client.ensureSession('$root1')
+    expect(id).toBe('sess_persist')
+    expect(b.loadSession).toHaveBeenCalledWith(
+      expect.objectContaining({ sessionId: 'sess_persist' }),
+    )
+    expect(b.newSession).not.toHaveBeenCalled()
+  })
+
+  it('skips loadSession when the agent does not advertise the capability', async () => {
+    {
+      const a = makeStubbedClient({
+        agentDataDir,
+        agentId: 'docs',
+        loadSessionCapability: false,
+        newSessionImpl: async () => ({ sessionId: 'sess_one' }),
+      })
+      await (a.client as unknown as { ensureStoreLoaded: () => Promise<void> }).ensureStoreLoaded()
+      await a.client.ensureSession('$root1')
+    }
+
+    const b = makeStubbedClient({
+      agentDataDir,
+      agentId: 'docs',
+      loadSessionCapability: false,
+      newSessionImpl: async () => ({ sessionId: 'sess_two' }),
+    })
+    await (b.client as unknown as { ensureStoreLoaded: () => Promise<void> }).ensureStoreLoaded()
+
+    const id = await b.client.ensureSession('$root1')
+    expect(id).toBe('sess_two')
+    expect(b.loadSession).not.toHaveBeenCalled()
+    expect(b.newSession).toHaveBeenCalledTimes(1)
+  })
+
+  it('falls back to newSession when loadSession rejects, and clears the stored id', async () => {
+    {
+      const a = makeStubbedClient({
+        agentDataDir,
+        agentId: 'docs',
+        loadSessionCapability: true,
+        newSessionImpl: async () => ({ sessionId: 'sess_old' }),
+      })
+      await (a.client as unknown as { ensureStoreLoaded: () => Promise<void> }).ensureStoreLoaded()
+      await a.client.ensureSession('$root1')
+    }
+
+    const b = makeStubbedClient({
+      agentDataDir,
+      agentId: 'docs',
+      loadSessionCapability: true,
+      loadSessionImpl: async () => {
+        throw new Error('shim does not recognise this id')
+      },
+      newSessionImpl: async () => ({ sessionId: 'sess_replacement' }),
+    })
+    await (b.client as unknown as { ensureStoreLoaded: () => Promise<void> }).ensureStoreLoaded()
+
+    const id = await b.client.ensureSession('$root1')
+    expect(id).toBe('sess_replacement')
+    expect(b.loadSession).toHaveBeenCalledTimes(1)
+    expect(b.newSession).toHaveBeenCalledTimes(1)
+
+    const c = makeStubbedClient({
+      agentDataDir,
+      agentId: 'docs',
+      loadSessionCapability: true,
+    })
+    await (c.client as unknown as { ensureStoreLoaded: () => Promise<void> }).ensureStoreLoaded()
+    const id3 = await c.client.ensureSession('$root1')
+    expect(id3).toBe('sess_replacement')
+    expect(c.loadSession).toHaveBeenCalledWith(
+      expect.objectContaining({ sessionId: 'sess_replacement' }),
+    )
+  })
+
+  it('endSession() also clears the persisted id', async () => {
+    const { client } = makeStubbedClient({
+      agentDataDir,
+      agentId: 'docs',
+      loadSessionCapability: true,
+      newSessionImpl: async () => ({ sessionId: 'sess_one' }),
+    })
+    await (client as unknown as { ensureStoreLoaded: () => Promise<void> }).ensureStoreLoaded()
+    await client.ensureSession('$root1')
+    client.endSession('$root1')
+    await (client as unknown as { flushStore: () => Promise<void> }).flushStore()
+
+    const fresh = makeStubbedClient({
+      agentDataDir,
+      agentId: 'docs',
+      loadSessionCapability: true,
+      newSessionImpl: async () => ({ sessionId: 'sess_after_clear' }),
+    })
+    await (fresh.client as unknown as { ensureStoreLoaded: () => Promise<void> }).ensureStoreLoaded()
+    const id = await fresh.client.ensureSession('$root1')
+    expect(id).toBe('sess_after_clear')
+    expect(fresh.loadSession).not.toHaveBeenCalled()
+  })
+})

package/src/acp-client.tap.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it, vi } from 'vitest'
+import { EventEmitter } from 'node:events'
+import { Readable, Writable } from 'node:stream'
+import type { ChildProcess } from 'node:child_process'
+import { AcpClient } from './acp-client.js'
+
+class FakeChild extends EventEmitter {
+  stdout = new Readable({ read() {} })
+  stdin = new Writable({ write(_c, _e, cb) { cb() } })
+  stderr = new Readable({ read() {} })
+  pid = 1
+  kill = vi.fn(() => true)
+}
+
+describe('AcpClient onTap', () => {
+  it('accepts an optional onTap option without breaking the existing surface', () => {
+    const child = new FakeChild() as unknown as ChildProcess
+    const rt = { spawn: vi.fn().mockReturnValue(child) }
+    expect(() => {
+      new AcpClient({
+        agent: { id: 'x', command: 'foo', args: [] },
+        onEvent: () => {},
+        onApprovalRequest: async () => ({ decision: 'cancel' }),
+        runtime: rt,
+        // onTap is optional
+      })
+      new AcpClient({
+        agent: { id: 'y', command: 'foo', args: [] },
+        onEvent: () => {},
+        onApprovalRequest: async () => ({ decision: 'cancel' }),
+        runtime: rt,
+        onTap: () => {},
+      })
+    }).not.toThrow()
+  })
+})