@plaited/acp-harness 0.2.5

package/src/tests/acp-client.spec.ts

@@ -0,0 +1,205 @@
+import { describe, expect, test } from 'bun:test'
+import { ACPClientError, createACPClient } from '../acp-client.ts'
+
+// ============================================================================
+// ACPClientError Tests
+// ============================================================================
+
+describe('ACPClientError', () => {
+  test('creates error with message only', () => {
+    const error = new ACPClientError('Connection failed')
+    expect(error.message).toBe('Connection failed')
+    expect(error.name).toBe('ACPClientError')
+    expect(error.code).toBeUndefined()
+  })
+
+  test('creates error with code', () => {
+    const error = new ACPClientError('Not connected', 'NOT_CONNECTED')
+    expect(error.code).toBe('NOT_CONNECTED')
+  })
+
+  test('is instance of Error', () => {
+    const error = new ACPClientError('Test')
+    expect(error instanceof Error).toBe(true)
+    expect(error instanceof ACPClientError).toBe(true)
+  })
+})
+
+// ============================================================================
+// Client Factory Tests
+// ============================================================================
+
+describe('createACPClient', () => {
+  test('creates client with minimal config', () => {
+    const client = createACPClient({
+      command: ['echo', 'test'],
+    })
+
+    expect(client).toBeDefined()
+    expect(typeof client.connect).toBe('function')
+    expect(typeof client.disconnect).toBe('function')
+    expect(typeof client.createSession).toBe('function')
+    expect(typeof client.prompt).toBe('function')
+    expect(typeof client.promptSync).toBe('function')
+    expect(typeof client.cancelPrompt).toBe('function')
+    expect(typeof client.getCapabilities).toBe('function')
+    expect(typeof client.getInitializeResult).toBe('function')
+    expect(typeof client.isConnected).toBe('function')
+  })
+
+  test('creates client with full config', () => {
+    const client = createACPClient({
+      command: ['claude', 'code'],
+      cwd: '/tmp',
+      env: { TEST: 'value' },
+      clientInfo: { name: 'test-client', version: '1.0.0' },
+      capabilities: { fs: { readTextFile: true } },
+      timeout: 60000,
+      onPermissionRequest: async () => ({ outcome: { outcome: 'cancelled' } }),
+    })
+
+    expect(client).toBeDefined()
+  })
+})
+
+// ============================================================================
+// State Methods (before connection)
+// ============================================================================
+
+describe('Client state before connection', () => {
+  test('isConnected returns false before connect', () => {
+    const client = createACPClient({
+      command: ['echo', 'test'],
+    })
+
+    expect(client.isConnected()).toBe(false)
+  })
+
+  test('getCapabilities returns undefined before connect', () => {
+    const client = createACPClient({
+      command: ['echo', 'test'],
+    })
+
+    expect(client.getCapabilities()).toBeUndefined()
+  })
+
+  test('getInitializeResult returns undefined before connect', () => {
+    const client = createACPClient({
+      command: ['echo', 'test'],
+    })
+
+    expect(client.getInitializeResult()).toBeUndefined()
+  })
+})
+
+// ============================================================================
+// Operations Before Connection
+// ============================================================================
+
+describe('Operations before connection', () => {
+  test('createSession throws when not connected', async () => {
+    const client = createACPClient({
+      command: ['echo', 'test'],
+    })
+
+    await expect(client.createSession({ cwd: '/tmp', mcpServers: [] })).rejects.toThrow('Not connected')
+  })
+
+  test('promptSync throws when not connected', async () => {
+    const client = createACPClient({
+      command: ['echo', 'test'],
+    })
+
+    await expect(client.promptSync('session-1', [{ type: 'text', text: 'Hello' }])).rejects.toThrow('Not connected')
+  })
+
+  test('cancelPrompt throws when not connected', async () => {
+    const client = createACPClient({
+      command: ['echo', 'test'],
+    })
+
+    await expect(client.cancelPrompt('session-1')).rejects.toThrow('Not connected')
+  })
+
+  test('prompt generator throws when not connected', async () => {
+    const client = createACPClient({
+      command: ['echo', 'test'],
+    })
+
+    const generator = client.prompt('session-1', [{ type: 'text', text: 'Hello' }])
+
+    await expect(generator.next()).rejects.toThrow('Not connected')
+  })
+})
+
+// ============================================================================
+// Disconnect Safety
+// ============================================================================
+
+describe('Disconnect safety', () => {
+  test('disconnect is safe when not connected', async () => {
+    const client = createACPClient({
+      command: ['echo', 'test'],
+    })
+
+    // Should not throw
+    await client.disconnect()
+    expect(client.isConnected()).toBe(false)
+  })
+
+  test('disconnect with graceful=false is safe when not connected', async () => {
+    const client = createACPClient({
+      command: ['echo', 'test'],
+    })
+
+    // Should not throw
+    await client.disconnect(false)
+    expect(client.isConnected()).toBe(false)
+  })
+})
+
+// ============================================================================
+// Integration Tests with Mock Process
+// ============================================================================
+
+describe('Client with mock process', () => {
+  test('connect starts transport', async () => {
+    const client = createACPClient({
+      command: ['cat'], // cat echoes back input
+      timeout: 1000,
+    })
+
+    // Start connection - cat won't respond with proper JSON-RPC
+    // so this will timeout, but it tests the transport startup
+    try {
+      await client.connect()
+    } catch {
+      // Expected - cat doesn't speak JSON-RPC
+    }
+
+    // Cleanup
+    await client.disconnect(false)
+  })
+
+  test('connect throws when already connected', async () => {
+    const client = createACPClient({
+      command: ['cat'],
+      timeout: 500,
+    })
+
+    // Start first connection
+    const connectPromise = client.connect()
+
+    // Immediately try second connection (before first completes)
+    // This should throw because transport is started
+    await expect(client.connect()).rejects.toThrow('Already connected')
+
+    // Cleanup - wait for first connect to timeout then disconnect
+    try {
+      await connectPromise
+    } catch {
+      // Expected timeout
+    }
+    await client.disconnect(false)
+  })
+})

package/src/tests/acp-helpers.spec.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from 'bun:test'
+import type { SessionNotification } from '@agentclientprotocol/sdk'
+import { createPrompt, createPromptWithFiles, createPromptWithImage, summarizeResponse } from '../acp-helpers.ts'
+
+// ============================================================================
+// Prompt Building Utilities
+// ============================================================================
+
+describe('createPrompt', () => {
+  test('creates single text block prompt', () => {
+    const prompt = createPrompt('Hello agent')
+    expect(prompt).toHaveLength(1)
+    expect(prompt[0]).toEqual({ type: 'text', text: 'Hello agent' })
+  })
+})
+
+describe('createPromptWithFiles', () => {
+  test('creates prompt with file context', () => {
+    const prompt = createPromptWithFiles('Analyze this', [
+      { path: '/src/main.ts', content: 'const x = 1;' },
+      { path: '/src/utils.ts', content: 'export const y = 2;' },
+    ])
+    expect(prompt).toHaveLength(3)
+    expect(prompt[0]).toEqual({ type: 'text', text: 'Analyze this' })
+    expect(prompt[1]?.type).toBe('resource')
+    expect(prompt[2]?.type).toBe('resource')
+  })
+})
+
+describe('createPromptWithImage', () => {
+  test('creates prompt with image', () => {
+    const prompt = createPromptWithImage({ text: 'Describe this', imageData: 'base64img', mimeType: 'image/png' })
+    expect(prompt).toHaveLength(2)
+    expect(prompt[0]).toEqual({ type: 'text', text: 'Describe this' })
+    expect(prompt[1]).toEqual({
+      type: 'image',
+      data: 'base64img',
+      mimeType: 'image/png',
+    })
+  })
+})
+
+// ============================================================================
+// Response Analysis
+// ============================================================================
+
+describe('summarizeResponse', () => {
+  test('creates comprehensive summary', () => {
+    const notifications: SessionNotification[] = [
+      {
+        sessionId: 's1',
+        update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: 'Processing...' } },
+      },
+      {
+        sessionId: 's1',
+        update: { sessionUpdate: 'tool_call', toolCallId: 't1', title: 'read', status: 'in_progress' },
+      },
+      {
+        sessionId: 's1',
+        update: {
+          sessionUpdate: 'plan',
+          entries: [{ content: 'Step 1', status: 'in_progress', priority: 'high' }],
+        },
+      },
+      {
+        sessionId: 's1',
+        update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: 'Done!' } },
+      },
+      {
+        sessionId: 's1',
+        update: { sessionUpdate: 'tool_call', toolCallId: 't1', title: 'read', status: 'completed' },
+      },
+      {
+        sessionId: 's1',
+        update: {
+          sessionUpdate: 'plan',
+          entries: [{ content: 'Step 1', status: 'completed', priority: 'high' }],
+        },
+      },
+    ]
+
+    const summary = summarizeResponse(notifications)
+
+    expect(summary.text).toBe('Processing...Done!')
+    expect(summary.toolCallCount).toBe(1)
+    expect(summary.completedToolCalls).toHaveLength(1)
+    expect(summary.failedToolCalls).toHaveLength(0)
+    expect(summary.plan).toHaveLength(1)
+    expect(summary.planProgress).toBe(100)
+    expect(summary.hasErrors).toBe(false)
+  })
+
+  test('detects errors in summary', () => {
+    const notifications: SessionNotification[] = [
+      {
+        sessionId: 's1',
+        update: { sessionUpdate: 'tool_call', toolCallId: 't1', title: 'read', status: 'failed' },
+      },
+    ]
+
+    const summary = summarizeResponse(notifications)
+    expect(summary.hasErrors).toBe(true)
+    expect(summary.failedToolCalls).toHaveLength(1)
+  })
+})

package/src/tests/acp-integration.docker.ts

@@ -0,0 +1,214 @@
+/**
+ * ACP Client Integration Tests
+ *
+ * @remarks
+ * These tests verify the ACP client works against real Claude Code
+ * via the `claude-code-acp` adapter.
+ *
+ * **Run in Docker only** for consistent environment:
+ * ```bash
+ * ANTHROPIC_API_KEY=sk-... bun run test:acp
+ * ```
+ *
+ * Prerequisites:
+ * 1. Docker installed
+ * 2. API key: `ANTHROPIC_API_KEY` environment variable
+ *
+ * These tests make real API calls and consume credits.
+ */
+
+import { afterAll, beforeAll, describe, expect, setDefaultTimeout, test } from 'bun:test'
+import { type ACPClient, createACPClient } from '../acp-client.ts'
+import { createPrompt, summarizeResponse } from '../acp-helpers.ts'
+
+// Long timeout for real agent interactions (2 minutes)
+setDefaultTimeout(120000)
+
+// Fixtures directory with .claude/skills and .mcp.json
+const FIXTURES_DIR = `${import.meta.dir}/fixtures`
+
+// Use haiku for all tests to reduce costs
+const TEST_MODEL = 'claude-haiku-4-5-20251001'
+
+describe('ACP Client Integration', () => {
+  let client: ACPClient
+
+  beforeAll(async () => {
+    // cc-acp adapter expects ANTHROPIC_API_KEY
+    client = createACPClient({
+      command: ['bunx', 'claude-code-acp'],
+      timeout: 120000, // 2 min timeout for initialization
+      env: {
+        ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY ?? '',
+      },
+    })
+
+    await client.connect()
+  })
+
+  afterAll(async () => {
+    await client?.disconnect()
+  })
+
+  test('connects and initializes', () => {
+    expect(client.isConnected()).toBe(true)
+
+    const initResult = client.getInitializeResult()
+    expect(initResult).toBeDefined()
+    expect(initResult?.protocolVersion).toBeDefined()
+  })
+
+  test('reports agent capabilities', () => {
+    const capabilities = client.getCapabilities()
+    expect(capabilities).toBeDefined()
+  })
+
+  test('creates session', async () => {
+    const session = await client.createSession({
+      cwd: FIXTURES_DIR,
+      mcpServers: [],
+    })
+
+    expect(session).toBeDefined()
+    expect(session.id).toBeDefined()
+    expect(typeof session.id).toBe('string')
+  })
+
+  test('sends prompt and receives response', async () => {
+    const session = await client.createSession({
+      cwd: FIXTURES_DIR,
+      mcpServers: [],
+    })
+
+    // Use haiku for faster/cheaper test runs
+    await client.setModel(session.id, TEST_MODEL)
+
+    // Simple prompt that doesn't require tools
+    const { result, updates } = await client.promptSync(
+      session.id,
+      createPrompt('What is 2 + 2? Reply with just the number.'),
+    )
+
+    expect(result).toBeDefined()
+    expect(updates).toBeInstanceOf(Array)
+
+    // Summarize and verify response structure
+    const summary = summarizeResponse(updates)
+    expect(summary.text).toBeDefined()
+    expect(summary.text.length).toBeGreaterThan(0)
+  })
+
+  test('streaming prompt yields updates', async () => {
+    const session = await client.createSession({
+      cwd: FIXTURES_DIR,
+      mcpServers: [],
+    })
+
+    // Use haiku for faster/cheaper test runs
+    await client.setModel(session.id, TEST_MODEL)
+
+    const events: string[] = []
+
+    for await (const event of client.prompt(session.id, createPrompt('Say "hello" and nothing else.'))) {
+      events.push(event.type)
+      if (event.type === 'complete') {
+        expect(event.result).toBeDefined()
+      }
+    }
+
+    expect(events).toContain('complete')
+  })
+
+  test('handles tool usage prompt', async () => {
+    const session = await client.createSession({
+      cwd: FIXTURES_DIR,
+      mcpServers: [],
+    })
+
+    // Use haiku for faster/cheaper test runs
+    await client.setModel(session.id, TEST_MODEL)
+
+    // Prompt that should trigger tool usage - reading a specific file
+    const { updates } = await client.promptSync(
+      session.id,
+      createPrompt('Use the Read tool to read calculator-mcp.ts and tell me what tools the MCP server provides.'),
+    )
+
+    const summary = summarizeResponse(updates)
+
+    // Verify response mentions calculator tools
+    expect(summary.text.length).toBeGreaterThan(0)
+    // Response should mention the calculator tools (add, subtract, etc.)
+    expect(summary.text.toLowerCase()).toMatch(/add|subtract|multiply|divide|calculator/)
+  })
+
+  test('uses skill from cwd', async () => {
+    const session = await client.createSession({
+      cwd: FIXTURES_DIR,
+      mcpServers: [],
+    })
+
+    // Use haiku for faster/cheaper test runs
+    await client.setModel(session.id, TEST_MODEL)
+
+    // Ask Claude to use the greeting skill
+    const { updates } = await client.promptSync(session.id, createPrompt('Please greet me using the greeting skill.'))
+
+    const summary = summarizeResponse(updates)
+
+    // The greeting skill instructs Claude to include specific phrases
+    expect(summary.text.length).toBeGreaterThan(0)
+    expect(summary.text.toLowerCase()).toMatch(/hello|greet|welcome/)
+  })
+
+  test('uses MCP server tools', async () => {
+    // Path to calculator MCP server fixture (must be absolute per ACP spec)
+    const calculatorPath = `${FIXTURES_DIR}/calculator-mcp.ts`
+    const bunPath = Bun.which('bun') ?? 'bun'
+
+    // Retry helper for flaky MCP server startup
+    const maxRetries = 3
+    let lastError: Error | undefined
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      const session = await client.createSession({
+        cwd: FIXTURES_DIR,
+        mcpServers: [
+          {
+            name: 'calculator',
+            command: bunPath,
+            args: [calculatorPath],
+            env: [],
+          },
+        ],
+      })
+
+      // Set model to haiku for faster/cheaper test runs
+      await client.setModel(session.id, TEST_MODEL)
+
+      // Ask Claude to use the calculator MCP server
+      const { updates } = await client.promptSync(
+        session.id,
+        createPrompt('Use the calculator MCP server add tool to compute 15 + 27. Reply with just the number.'),
+      )
+
+      const summary = summarizeResponse(updates)
+
+      // Check if we got 42 in the response
+      if (summary.text.match(/42/)) {
+        expect(summary.text.length).toBeGreaterThan(0)
+        expect(summary.text).toMatch(/42/)
+        return // Success!
+      }
+
+      // MCP server might not have been ready, retry
+      lastError = new Error(`Attempt ${attempt}: Response did not contain 42. Got: ${summary.text.slice(0, 100)}...`)
+      if (attempt < maxRetries) {
+        console.log(`MCP test attempt ${attempt} failed, retrying...`)
+      }
+    }
+
+    // All retries exhausted
+    throw lastError ?? new Error('MCP test failed after all retries')
+  })
+})

package/src/tests/acp-transport.spec.ts

@@ -0,0 +1,153 @@
+import { describe, expect, test } from 'bun:test'
+import { createACPTransport } from '../acp-transport.ts'
+
+// ============================================================================
+// Transport Creation Tests (without spawning)
+// ============================================================================
+
+describe('createACPTransport', () => {
+  test('throws on empty command', async () => {
+    const transport = createACPTransport({
+      command: [],
+    })
+
+    await expect(transport.start()).rejects.toThrow('Command array is empty')
+  })
+
+  test('isConnected returns false before start', async () => {
+    const transport = createACPTransport({
+      command: ['echo', 'test'],
+    })
+
+    expect(transport.isConnected()).toBe(false)
+  })
+
+  test('request throws when not connected', async () => {
+    const transport = createACPTransport({
+      command: ['echo', 'test'],
+    })
+
+    await expect(transport.request('test/method')).rejects.toThrow('Transport is not connected')
+  })
+
+  test('notify throws when not connected', async () => {
+    const transport = createACPTransport({
+      command: ['echo', 'test'],
+    })
+
+    await expect(transport.notify('test/notification')).rejects.toThrow('Transport is not connected')
+  })
+
+  test('close is safe when not started', async () => {
+    const transport = createACPTransport({
+      command: ['echo', 'test'],
+    })
+
+    // Should not throw
+    await transport.close()
+    expect(transport.isConnected()).toBe(false)
+  })
+})
+
+// ============================================================================
+// Mock Subprocess Integration Tests
+// ============================================================================
+
+describe('Transport with mock subprocess', () => {
+  test('starts transport with valid command', async () => {
+    const transport = createACPTransport({
+      command: ['cat'], // cat echoes back input
+      timeout: 1000,
+    })
+
+    await transport.start()
+    expect(transport.isConnected()).toBe(true)
+
+    // Close immediately since cat doesn't speak JSON-RPC
+    await transport.close(false)
+    expect(transport.isConnected()).toBe(false)
+  })
+
+  test('throws on duplicate start', async () => {
+    const transport = createACPTransport({
+      command: ['cat'],
+      timeout: 1000,
+    })
+
+    await transport.start()
+
+    try {
+      await expect(transport.start()).rejects.toThrow('Transport already started')
+    } finally {
+      await transport.close(false)
+    }
+  })
+
+  test('handles process exit', async () => {
+    const { createACPTransport } = await import('../acp-transport.ts')
+
+    let closeCalled = false
+    let closeCode: number | null = null
+
+    const transport = createACPTransport({
+      command: ['true'], // exits immediately with code 0
+      timeout: 1000,
+      onClose: (code) => {
+        closeCalled = true
+        closeCode = code
+      },
+    })
+
+    await transport.start()
+
+    // Wait for process to exit
+    await new Promise((resolve) => setTimeout(resolve, 100))
+
+    expect(closeCalled).toBe(true)
+    expect(closeCode === 0).toBe(true)
+  })
+
+  test('handles invalid command', async () => {
+    const transport = createACPTransport({
+      command: ['nonexistent-command-that-does-not-exist-12345'],
+      timeout: 1000,
+    })
+
+    // Bun.spawn may throw or exit with error depending on the command
+    try {
+      await transport.start()
+      // If it doesn't throw, wait for process exit
+      await new Promise((resolve) => setTimeout(resolve, 100))
+    } catch {
+      // Expected - command not found
+    }
+  })
+})
+
+// ============================================================================
+// Error Handling Tests
+// ============================================================================
+
+describe('Transport error handling', () => {
+  test('request times out when no response received', async () => {
+    // TODO(human): Implement timeout test
+  })
+
+  test('close rejects pending requests', async () => {
+    const transport = createACPTransport({
+      command: ['cat'],
+      timeout: 5000,
+    })
+
+    await transport.start()
+
+    // Start a request that will never complete (cat doesn't speak JSON-RPC)
+    const requestPromise = transport.request('test/method')
+
+    // Close transport while request is pending
+    await transport.close(false)
+
+    // Request should be rejected with "Transport closed"
+    await expect(requestPromise).rejects.toThrow('Transport closed')
+  })
+})