@onmars/lunar-agent-claude 0.1.0

package/src/__tests__/adapter.test.ts

@@ -0,0 +1,1383 @@
+/**
+ * # ClaudeAgent Adapter — Functional Specification
+ *
+ * Tests the Claude Code CLI spawn adapter in isolation (no real subprocesses).
+ *
+ * ## buildArgs() — CLI argument construction
+ * Constructs the full argv array for Bun.spawn from AgentInput + options.
+ * Always includes: -p <prompt>, --output-format stream-json, --verbose,
+ * --permission-mode bypassPermissions.
+ * Conditionally: --resume, --append-system-prompt, --model, --max-turns.
+ *
+ * ## buildEnv() — Environment variable filtering
+ * Auth modes: 'stored' (clear API keys), 'api-key' (pass ANTHROPIC_API_KEY),
+ * 'oauth-token' (pass ANTHROPIC_AUTH_TOKEN).
+ * With security config: delegates to buildSafeEnv (allowlist).
+ * Without: legacy blocklist approach.
+ * context1m=false sets CLAUDE_CODE_DISABLE_1M_CONTEXT=1.
+ *
+ * ## processMessage() — JSONL event parsing
+ * Maps Claude CLI stream-json types to AgentEvent:
+ * - 'assistant' with text blocks → { type: 'text' }
+ * - 'assistant' with thinking blocks → { type: 'thinking' }
+ * - 'tool_use' → { type: 'tool_use' }
+ * - 'tool_result' → { type: 'tool_result' }
+ * - 'error' → { type: 'error' }
+ * - 'result' → no-op (final summary, text captured from assistant blocks)
+ *
+ * ## resolveModelAlias() — Model name resolution
+ * Maps short aliases to full Claude model IDs.
+ * 'opus' → 'claude-opus-4-6', 'sonnet' → 'claude-sonnet-4-6', etc.
+ * Unknown names pass through unchanged.
+ */
+import { beforeEach, describe, expect, it, mock, spyOn } from 'bun:test'
+import { ClaudeAgent, type ClaudeAgentOptions } from '../adapter'
+
+// ─── Helpers ────────────────────────────────────────────────────────
+
+/** Create an agent and extract private methods via prototype access */
+function createAgent(overrides: Partial<ClaudeAgentOptions> = {}): ClaudeAgent {
+  return new ClaudeAgent({
+    cwd: '/tmp/test-workspace',
+    ...overrides,
+  })
+}
+
+/**
+ * Access private buildArgs via casting.
+ * Tests the arg construction logic without spawning processes.
+ */
+function callBuildArgs(
+  agent: ClaudeAgent,
+  input: {
+    prompt: string
+    sessionId?: string
+    systemPrompt?: string
+    model?: string
+    context1m?: boolean
+  },
+): string[] {
+  return (agent as any).buildArgs(input)
+}
+
+/**
+ * Access private buildEnv via casting.
+ */
+function callBuildEnv(agent: ClaudeAgent): Record<string, string> {
+  return (agent as any).buildEnv()
+}
+
+/**
+ * Access private processMessage generator via casting.
+ */
+function callProcessMessage(agent: ClaudeAgent, msg: any): Array<any> {
+  const gen = (agent as any).processMessage(msg)
+  const events: any[] = []
+  for (const evt of gen) {
+    events.push(evt)
+  }
+  return events
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// buildArgs — CLI argument construction
+// ═══════════════════════════════════════════════════════════════════
+
+describe('buildArgs', () => {
+  // --- Core required args ---
+
+  it('always includes binary, -p, prompt, output-format, verbose, and permission-mode', () => {
+    const agent = createAgent()
+    const args = callBuildArgs(agent, { prompt: 'Hello world' })
+
+    expect(args[0]).toBe('claude')
+    expect(args).toContain('-p')
+    expect(args[args.indexOf('-p') + 1]).toBe('Hello world')
+    expect(args).toContain('--output-format')
+    expect(args[args.indexOf('--output-format') + 1]).toBe('stream-json')
+    expect(args).toContain('--verbose')
+    expect(args).toContain('--permission-mode')
+    expect(args[args.indexOf('--permission-mode') + 1]).toBe('bypassPermissions')
+  })
+
+  it('uses custom binaryPath when provided', () => {
+    const agent = createAgent({ binaryPath: '/usr/local/bin/claude-custom' })
+    const args = callBuildArgs(agent, { prompt: 'test' })
+
+    expect(args[0]).toBe('/usr/local/bin/claude-custom')
+  })
+
+  // --- Session resume ---
+
+  it('includes --resume flag when sessionId is provided', () => {
+    const agent = createAgent()
+    const args = callBuildArgs(agent, { prompt: 'continue', sessionId: 'sess_abc123' })
+
+    expect(args).toContain('--resume')
+    expect(args[args.indexOf('--resume') + 1]).toBe('sess_abc123')
+  })
+
+  it('omits --resume flag when no sessionId', () => {
+    const agent = createAgent()
+    const args = callBuildArgs(agent, { prompt: 'start fresh' })
+
+    expect(args).not.toContain('--resume')
+  })
+
+  // --- System prompt ---
+
+  it('includes --append-system-prompt from input', () => {
+    const agent = createAgent()
+    const args = callBuildArgs(agent, {
+      prompt: 'hello',
+      systemPrompt: 'You are a helpful assistant',
+    })
+
+    expect(args).toContain('--append-system-prompt')
+    expect(args[args.indexOf('--append-system-prompt') + 1]).toBe('You are a helpful assistant')
+  })
+
+  it('includes --append-system-prompt from agent options when input has none', () => {
+    const agent = createAgent({ systemPrompt: 'Default system prompt' })
+    const args = callBuildArgs(agent, { prompt: 'hello' })
+
+    expect(args).toContain('--append-system-prompt')
+    expect(args[args.indexOf('--append-system-prompt') + 1]).toBe('Default system prompt')
+  })
+
+  it('input systemPrompt overrides agent-level systemPrompt', () => {
+    const agent = createAgent({ systemPrompt: 'Agent-level prompt' })
+    const args = callBuildArgs(agent, {
+      prompt: 'hello',
+      systemPrompt: 'Per-query prompt',
+    })
+
+    expect(args[args.indexOf('--append-system-prompt') + 1]).toBe('Per-query prompt')
+  })
+
+  it('omits --append-system-prompt when neither input nor options have one', () => {
+    const agent = createAgent()
+    const args = callBuildArgs(agent, { prompt: 'hello' })
+
+    expect(args).not.toContain('--append-system-prompt')
+  })
+
+  // --- Model ---
+
+  it('includes --model from agent options', () => {
+    const agent = createAgent({ model: 'claude-sonnet-4-6' })
+    const args = callBuildArgs(agent, { prompt: 'hello' })
+
+    expect(args).toContain('--model')
+    expect(args[args.indexOf('--model') + 1]).toBe('claude-sonnet-4-6')
+  })
+
+  it('input model overrides agent-level model', () => {
+    const agent = createAgent({ model: 'claude-sonnet-4-6' })
+    const args = callBuildArgs(agent, { prompt: 'hello', model: 'claude-opus-4-6' })
+
+    expect(args[args.indexOf('--model') + 1]).toBe('claude-opus-4-6')
+  })
+
+  it('omits --model when neither input nor options have one', () => {
+    const agent = createAgent()
+    const args = callBuildArgs(agent, { prompt: 'hello' })
+
+    expect(args).not.toContain('--model')
+  })
+
+  // --- Max turns ---
+
+  it('includes --max-turns when set in options', () => {
+    const agent = createAgent({ maxTurns: 10 })
+    const args = callBuildArgs(agent, { prompt: 'hello' })
+
+    expect(args).toContain('--max-turns')
+    expect(args[args.indexOf('--max-turns') + 1]).toBe('10')
+  })
+
+  it('omits --max-turns when not set', () => {
+    const agent = createAgent()
+    const args = callBuildArgs(agent, { prompt: 'hello' })
+
+    expect(args).not.toContain('--max-turns')
+  })
+
+  // --- Context 1M + model alias resolution ---
+
+  it('appends [1m] suffix when context1m=true and model is provided', () => {
+    const agent = createAgent({ model: 'claude-opus-4-6', context1m: true })
+    const args = callBuildArgs(agent, { prompt: 'hello' })
+
+    expect(args[args.indexOf('--model') + 1]).toBe('claude-opus-4-6[1m]')
+  })
+
+  it('resolves alias before appending [1m] suffix', () => {
+    const agent = createAgent({ model: 'opus', context1m: true })
+    const args = callBuildArgs(agent, { prompt: 'hello' })
+
+    // 'opus' alias resolves to 'claude-opus-4-6', then gets [1m]
+    expect(args[args.indexOf('--model') + 1]).toBe('claude-opus-4-6[1m]')
+  })
+
+  it('resolves "sonnet" alias with context1m', () => {
+    const agent = createAgent({ model: 'sonnet', context1m: true })
+    const args = callBuildArgs(agent, { prompt: 'hello' })
+
+    expect(args[args.indexOf('--model') + 1]).toBe('claude-sonnet-4-6[1m]')
+  })
+
+  it('resolves "haiku" alias with context1m', () => {
+    const agent = createAgent({ model: 'haiku', context1m: true })
+    const args = callBuildArgs(agent, { prompt: 'hello' })
+
+    expect(args[args.indexOf('--model') + 1]).toBe('claude-haiku-4-5[1m]')
+  })
+
+  it('resolves "sonnet-4.5" alias with context1m', () => {
+    const agent = createAgent({ model: 'sonnet-4.5', context1m: true })
+    const args = callBuildArgs(agent, { prompt: 'hello' })
+
+    expect(args[args.indexOf('--model') + 1]).toBe('claude-sonnet-4-5[1m]')
+  })
+
+  it('does not double-append [1m] if already present', () => {
+    const agent = createAgent({ model: 'claude-opus-4-6[1m]', context1m: true })
+    const args = callBuildArgs(agent, { prompt: 'hello' })
+
+    expect(args[args.indexOf('--model') + 1]).toBe('claude-opus-4-6[1m]')
+  })
+
+  it('does not append [1m] when context1m is false', () => {
+    const agent = createAgent({ model: 'opus', context1m: false })
+    const args = callBuildArgs(agent, { prompt: 'hello' })
+
+    // Should use the alias as-is (no resolution needed when no [1m])
+    expect(args[args.indexOf('--model') + 1]).toBe('opus')
+  })
+
+  it('passes unknown model names through unchanged (without context1m)', () => {
+    const agent = createAgent({ model: 'my-custom-model' })
+    const args = callBuildArgs(agent, { prompt: 'hello' })
+
+    expect(args[args.indexOf('--model') + 1]).toBe('my-custom-model')
+  })
+
+  it('passes unknown model names through with [1m] appended (with context1m)', () => {
+    const agent = createAgent({ model: 'my-custom-model', context1m: true })
+    const args = callBuildArgs(agent, { prompt: 'hello' })
+
+    expect(args[args.indexOf('--model') + 1]).toBe('my-custom-model[1m]')
+  })
+
+  it('per-query context1m overrides agent-level', () => {
+    const agent = createAgent({ model: 'opus', context1m: false })
+    const args = callBuildArgs(agent, { prompt: 'hello', context1m: true })
+
+    expect(args[args.indexOf('--model') + 1]).toBe('claude-opus-4-6[1m]')
+  })
+
+  it('per-query model + context1m together', () => {
+    const agent = createAgent({ model: 'haiku' })
+    const args = callBuildArgs(agent, { prompt: 'hello', model: 'sonnet', context1m: true })
+
+    expect(args[args.indexOf('--model') + 1]).toBe('claude-sonnet-4-6[1m]')
+  })
+
+  // --- Full argument order verification ---
+
+  it('produces expected argument sequence for a full configuration', () => {
+    const agent = createAgent({
+      model: 'opus',
+      maxTurns: 5,
+      systemPrompt: 'Be concise',
+      context1m: true,
+    })
+    const args = callBuildArgs(agent, {
+      prompt: 'explain recursion',
+      sessionId: 'sess_123',
+    })
+
+    // Verify ordering: binary, -p, prompt, output-format, verbose, resume, system-prompt, model, max-turns, permission-mode
+    expect(args[0]).toBe('claude')
+    expect(args[1]).toBe('-p')
+    expect(args[2]).toBe('explain recursion')
+    expect(args[3]).toBe('--output-format')
+    expect(args[4]).toBe('stream-json')
+    expect(args[5]).toBe('--verbose')
+    expect(args[6]).toBe('--resume')
+    expect(args[7]).toBe('sess_123')
+    expect(args[8]).toBe('--append-system-prompt')
+    expect(args[9]).toBe('Be concise')
+    expect(args[10]).toBe('--model')
+    expect(args[11]).toBe('claude-opus-4-6[1m]')
+    expect(args[12]).toBe('--max-turns')
+    expect(args[13]).toBe('5')
+    expect(args[14]).toBe('--permission-mode')
+    expect(args[15]).toBe('bypassPermissions')
+    expect(args).toHaveLength(16)
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// buildEnv — Environment variable filtering
+// ═══════════════════════════════════════════════════════════════════
+
+describe('buildEnv', () => {
+  // Save original process.env
+  const originalEnv = { ...process.env }
+
+  beforeEach(() => {
+    // Clean env for predictable tests
+    process.env = {
+      HOME: '/home/testuser',
+      PATH: '/usr/bin',
+      USER: 'testuser',
+      ANTHROPIC_API_KEY: 'sk-test-key',
+      ANTHROPIC_AUTH_TOKEN: 'oauth-test-token',
+      DISCORD_TOKEN: 'discord-secret',
+    }
+  })
+
+  // Restore after each test
+  const afterEach = () => {
+    process.env = originalEnv
+  }
+
+  // --- Auth mode: stored (default) ---
+
+  describe('auth mode: stored (default)', () => {
+    it('removes ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN with security config', () => {
+      const agent = createAgent({
+        authMode: 'stored',
+        security: {
+          isolation: 'process',
+          envDefaults: ['HOME', 'PATH', 'USER'],
+          envPassthrough: [],
+          envPassthroughAll: false,
+          outputRedactPatterns: [],
+          inputSanitization: {
+            enabled: true,
+            stripMarkers: true,
+            logSuspicious: false,
+            notifyAgent: false,
+            customPatterns: [],
+          },
+        },
+      })
+      const env = callBuildEnv(agent)
+
+      // Auth vars should be explicitly cleared
+      expect(env.ANTHROPIC_API_KEY).toBeUndefined()
+      expect(env.ANTHROPIC_AUTH_TOKEN).toBeUndefined()
+    })
+
+    it('removes auth keys in legacy mode (no security config)', () => {
+      const agent = createAgent({ authMode: 'stored' })
+      const env = callBuildEnv(agent)
+
+      expect(env.ANTHROPIC_API_KEY).toBeUndefined()
+      expect(env.ANTHROPIC_AUTH_TOKEN).toBeUndefined()
+    })
+  })
+
+  // --- Auth mode: api-key ---
+
+  describe('auth mode: api-key', () => {
+    it('passes ANTHROPIC_API_KEY through in legacy mode', () => {
+      const agent = createAgent({ authMode: 'api-key' })
+      const env = callBuildEnv(agent)
+
+      expect(env.ANTHROPIC_API_KEY).toBe('sk-test-key')
+      expect(env.ANTHROPIC_AUTH_TOKEN).toBeUndefined()
+    })
+  })
+
+  // --- Auth mode: oauth-token ---
+
+  describe('auth mode: oauth-token', () => {
+    it('passes ANTHROPIC_AUTH_TOKEN through in legacy mode', () => {
+      const agent = createAgent({ authMode: 'oauth-token' })
+      const env = callBuildEnv(agent)
+
+      expect(env.ANTHROPIC_AUTH_TOKEN).toBe('oauth-test-token')
+      expect(env.ANTHROPIC_API_KEY).toBeUndefined()
+    })
+  })
+
+  // --- Context 1M ---
+
+  describe('context1m env control', () => {
+    it('sets CLAUDE_CODE_DISABLE_1M_CONTEXT=1 when context1m=false', () => {
+      const agent = createAgent({ context1m: false })
+      const env = callBuildEnv(agent)
+
+      expect(env.CLAUDE_CODE_DISABLE_1M_CONTEXT).toBe('1')
+    })
+
+    it('does NOT set disable var when context1m=true', () => {
+      const agent = createAgent({ context1m: true })
+      const env = callBuildEnv(agent)
+
+      expect(env.CLAUDE_CODE_DISABLE_1M_CONTEXT).toBeUndefined()
+    })
+
+    it('does NOT set disable var when context1m is undefined', () => {
+      const agent = createAgent()
+      const env = callBuildEnv(agent)
+
+      expect(env.CLAUDE_CODE_DISABLE_1M_CONTEXT).toBeUndefined()
+    })
+  })
+
+  // --- Security config (allowlist) ---
+
+  describe('with security config (allowlist mode)', () => {
+    it('only passes env vars listed in envDefaults', () => {
+      const agent = createAgent({
+        security: {
+          isolation: 'process',
+          envDefaults: ['HOME', 'PATH'],
+          envPassthrough: [],
+          envPassthroughAll: false,
+          outputRedactPatterns: [],
+          inputSanitization: {
+            enabled: true,
+            stripMarkers: true,
+            logSuspicious: false,
+            notifyAgent: false,
+            customPatterns: [],
+          },
+        },
+      })
+      const env = callBuildEnv(agent)
+
+      expect(env.HOME).toBe('/home/testuser')
+      expect(env.PATH).toBe('/usr/bin')
+      expect(env.DISCORD_TOKEN).toBeUndefined()
+    })
+
+    it('passes custom env vars from options as extraEnv', () => {
+      const agent = createAgent({
+        env: { CUSTOM_VAR: 'custom_value' },
+        security: {
+          isolation: 'process',
+          envDefaults: ['HOME'],
+          envPassthrough: [],
+          envPassthroughAll: false,
+          outputRedactPatterns: [],
+          inputSanitization: {
+            enabled: true,
+            stripMarkers: true,
+            logSuspicious: false,
+            notifyAgent: false,
+            customPatterns: [],
+          },
+        },
+      })
+      const env = callBuildEnv(agent)
+
+      expect(env.CUSTOM_VAR).toBe('custom_value')
+    })
+  })
+
+  // --- Legacy mode (no security config) ---
+
+  describe('without security config (legacy blocklist mode)', () => {
+    it('passes most env vars through', () => {
+      const agent = createAgent({ authMode: 'stored' })
+      const env = callBuildEnv(agent)
+
+      expect(env.HOME).toBe('/home/testuser')
+      expect(env.PATH).toBe('/usr/bin')
+      expect(env.USER).toBe('testuser')
+      expect(env.DISCORD_TOKEN).toBe('discord-secret')
+    })
+
+    it('merges custom env vars from options', () => {
+      const agent = createAgent({
+        authMode: 'stored',
+        env: { MY_VAR: 'my_value' },
+      })
+      const env = callBuildEnv(agent)
+
+      expect(env.MY_VAR).toBe('my_value')
+    })
+  })
+
+  // Cleanup
+  afterEach()
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// processMessage — JSONL event parsing
+// ═══════════════════════════════════════════════════════════════════
+
+describe('processMessage', () => {
+  const agent = createAgent()
+
+  // --- assistant messages ---
+
+  it('emits text event for assistant text blocks', () => {
+    const events = callProcessMessage(agent, {
+      type: 'assistant',
+      message: {
+        role: 'assistant',
+        content: [{ type: 'text', text: 'Hello, world!' }],
+      },
+    })
+
+    expect(events).toHaveLength(1)
+    expect(events[0]).toEqual({ type: 'text', content: 'Hello, world!' })
+  })
+
+  it('emits thinking event for assistant thinking blocks', () => {
+    const events = callProcessMessage(agent, {
+      type: 'assistant',
+      message: {
+        role: 'assistant',
+        content: [{ type: 'thinking', thinking: 'Let me consider...' }],
+      },
+    })
+
+    expect(events).toHaveLength(1)
+    expect(events[0]).toEqual({ type: 'thinking', content: 'Let me consider...' })
+  })
+
+  it('emits multiple events for mixed content blocks', () => {
+    const events = callProcessMessage(agent, {
+      type: 'assistant',
+      message: {
+        role: 'assistant',
+        content: [
+          { type: 'thinking', thinking: 'Thinking first...' },
+          { type: 'text', text: 'Here is my answer' },
+        ],
+      },
+    })
+
+    expect(events).toHaveLength(2)
+    expect(events[0]).toEqual({ type: 'thinking', content: 'Thinking first...' })
+    expect(events[1]).toEqual({ type: 'text', content: 'Here is my answer' })
+  })
+
+  it('skips text blocks with empty text', () => {
+    const events = callProcessMessage(agent, {
+      type: 'assistant',
+      message: {
+        role: 'assistant',
+        content: [{ type: 'text', text: '' }],
+      },
+    })
+
+    expect(events).toHaveLength(0)
+  })
+
+  it('skips assistant messages with no content', () => {
+    const events = callProcessMessage(agent, {
+      type: 'assistant',
+      message: { role: 'assistant' },
+    })
+
+    expect(events).toHaveLength(0)
+  })
+
+  // --- tool_use ---
+
+  it('emits tool_use event', () => {
+    const events = callProcessMessage(agent, {
+      type: 'tool_use',
+      message: {
+        role: 'assistant',
+        content: [{ type: 'tool_use', name: 'Read', input: { file_path: '/tmp/test.txt' } }],
+      },
+    })
+
+    expect(events).toHaveLength(1)
+    expect(events[0]).toEqual({
+      type: 'tool_use',
+      tool: 'Read',
+      input: { file_path: '/tmp/test.txt' },
+    })
+  })
+
+  it('skips tool_use blocks without a name', () => {
+    const events = callProcessMessage(agent, {
+      type: 'tool_use',
+      message: {
+        role: 'assistant',
+        content: [{ type: 'tool_use', input: { data: 'test' } }],
+      },
+    })
+
+    expect(events).toHaveLength(0)
+  })
+
+  // --- tool_result ---
+
+  it('emits tool_result event', () => {
+    const events = callProcessMessage(agent, {
+      type: 'tool_result',
+      message: {
+        role: 'tool',
+        content: [{ type: 'tool_result', content: 'File contents here' }],
+      },
+    })
+
+    expect(events).toHaveLength(1)
+    expect(events[0]).toEqual({
+      type: 'tool_result',
+      tool: '',
+      output: 'File contents here',
+    })
+  })
+
+  // --- error ---
+
+  it('emits error event', () => {
+    const events = callProcessMessage(agent, {
+      type: 'error',
+      result: 'Something went wrong',
+    })
+
+    expect(events).toHaveLength(1)
+    expect(events[0]).toEqual({
+      type: 'error',
+      error: 'Something went wrong',
+      recoverable: false,
+    })
+  })
+
+  it('uses fallback message for error without result', () => {
+    const events = callProcessMessage(agent, {
+      type: 'error',
+    })
+
+    expect(events).toHaveLength(1)
+    expect(events[0]).toEqual({
+      type: 'error',
+      error: 'Unknown CLI error',
+      recoverable: false,
+    })
+  })
+
+  // --- result (final) ---
+
+  it('emits nothing for result type (handled externally)', () => {
+    const events = callProcessMessage(agent, {
+      type: 'result',
+      result: 'Final summary',
+      session_id: 'sess_xyz',
+    })
+
+    expect(events).toHaveLength(0)
+  })
+
+  // --- unknown types ---
+
+  it('emits nothing for unknown message types', () => {
+    const events = callProcessMessage(agent, {
+      type: 'system',
+      message: { content: 'system info' },
+    })
+
+    expect(events).toHaveLength(0)
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// Constructor and metadata
+// ═══════════════════════════════════════════════════════════════════
+
+describe('ClaudeAgent — constructor and metadata', () => {
+  it('has correct id and name', () => {
+    const agent = createAgent()
+    expect(agent.id).toBe('claude')
+    expect(agent.name).toBe('Claude Code (CLI)')
+  })
+
+  it('stores options internally', () => {
+    const agent = createAgent({
+      cwd: '/my/workspace',
+      model: 'opus',
+      maxTurns: 5,
+    })
+
+    // Verify options are stored by checking buildArgs output
+    const args = callBuildArgs(agent, { prompt: 'test' })
+    expect(args).toContain('--model')
+    expect(args).toContain('--max-turns')
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// destroy — Process cleanup
+// ═══════════════════════════════════════════════════════════════════
+
+describe('ClaudeAgent — destroy', () => {
+  it('sets activeProcess to null', async () => {
+    const agent = createAgent()
+
+    // No active process — should not throw
+    await agent.destroy()
+    expect((agent as any).activeProcess).toBeNull()
+  })
+
+  it('kills active process if present', async () => {
+    const agent = createAgent()
+    const killMock = mock(() => {})
+
+    // Simulate an active process
+    ;(agent as any).activeProcess = { kill: killMock }
+
+    await agent.destroy()
+    expect(killMock).toHaveBeenCalledTimes(1)
+    expect((agent as any).activeProcess).toBeNull()
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// Model alias resolution (tested indirectly through buildArgs)
+// ═══════════════════════════════════════════════════════════════════
+
+describe('model alias resolution', () => {
+  it('opus → claude-opus-4-6 (only with context1m)', () => {
+    const agent = createAgent({ model: 'opus', context1m: true })
+    const args = callBuildArgs(agent, { prompt: 'test' })
+    expect(args[args.indexOf('--model') + 1]).toBe('claude-opus-4-6[1m]')
+  })
+
+  it('sonnet → claude-sonnet-4-6 (only with context1m)', () => {
+    const agent = createAgent({ model: 'sonnet', context1m: true })
+    const args = callBuildArgs(agent, { prompt: 'test' })
+    expect(args[args.indexOf('--model') + 1]).toBe('claude-sonnet-4-6[1m]')
+  })
+
+  it('haiku → claude-haiku-4-5 (only with context1m)', () => {
+    const agent = createAgent({ model: 'haiku', context1m: true })
+    const args = callBuildArgs(agent, { prompt: 'test' })
+    expect(args[args.indexOf('--model') + 1]).toBe('claude-haiku-4-5[1m]')
+  })
+
+  it('sonnet-4.5 → claude-sonnet-4-5 (only with context1m)', () => {
+    const agent = createAgent({ model: 'sonnet-4.5', context1m: true })
+    const args = callBuildArgs(agent, { prompt: 'test' })
+    expect(args[args.indexOf('--model') + 1]).toBe('claude-sonnet-4-5[1m]')
+  })
+
+  it('full model ID passes through unchanged (without context1m)', () => {
+    const agent = createAgent({ model: 'claude-opus-4-6' })
+    const args = callBuildArgs(agent, { prompt: 'test' })
+    expect(args[args.indexOf('--model') + 1]).toBe('claude-opus-4-6')
+  })
+
+  it('full model ID passes through with [1m] appended (with context1m)', () => {
+    const agent = createAgent({ model: 'claude-opus-4-6', context1m: true })
+    const args = callBuildArgs(agent, { prompt: 'test' })
+    expect(args[args.indexOf('--model') + 1]).toBe('claude-opus-4-6[1m]')
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// Mock Bun.spawn helper for init / health / query tests
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * Creates a mock Bun.spawn result with controllable stdout/stderr/exit.
+ * For streaming tests, stdout is a ReadableStream of JSONL lines.
+ */
+function createMockProcess(opts: { exitCode?: number; stdout?: string; stderr?: string } = {}) {
+  const { exitCode = 0, stdout = '', stderr = '' } = opts
+
+  return {
+    stdout: new Response(stdout).body!,
+    stderr: new Response(stderr).body!,
+    exited: Promise.resolve(exitCode),
+    kill: mock(() => {}),
+    pid: 12345,
+  }
+}
+
+/**
+ * Creates a mock Bun.spawn result with streaming stdout for query() tests.
+ * Each line in `lines` becomes a separate JSONL line in the stream.
+ */
+function createStreamingMockProcess(lines: string[], exitCode = 0) {
+  const body = lines.join('\n') + '\n'
+  return {
+    stdout: new ReadableStream({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode(body))
+        controller.close()
+      },
+    }),
+    stderr: new Response('').body!,
+    exited: Promise.resolve(exitCode),
+    kill: mock(() => {}),
+    pid: 12345,
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// init — Binary check and auth verification
+// ═══════════════════════════════════════════════════════════════════
+
+describe('ClaudeAgent — init', () => {
+  it('succeeds when binary exists and auth check passes', async () => {
+    const agent = createAgent()
+
+    const spawnSpy = spyOn(Bun, 'spawn')
+
+    // First call: `which claude` (exit 0)
+    spawnSpy.mockReturnValueOnce(createMockProcess({ exitCode: 0 }) as any)
+    // Second call: auth check `claude -p "Reply with OK" ...` (exit 0, valid JSON)
+    spawnSpy.mockReturnValueOnce(
+      createMockProcess({
+        exitCode: 0,
+        stdout: JSON.stringify({ result: 'OK' }),
+      }) as any,
+    )
+
+    await agent.init() // should not throw
+
+    expect(spawnSpy).toHaveBeenCalledTimes(2)
+    spawnSpy.mockRestore()
+  })
+
+  it('throws when binary is not found (which returns non-zero)', async () => {
+    const agent = createAgent({ binaryPath: '/nonexistent/claude' })
+
+    const spawnSpy = spyOn(Bun, 'spawn')
+    spawnSpy.mockReturnValueOnce(createMockProcess({ exitCode: 1 }) as any)
+
+    await expect(agent.init()).rejects.toThrow('Claude CLI not found')
+
+    spawnSpy.mockRestore()
+  })
+
+  it('throws when auth check process exits non-zero', async () => {
+    const agent = createAgent()
+
+    const spawnSpy = spyOn(Bun, 'spawn')
+    // which succeeds
+    spawnSpy.mockReturnValueOnce(createMockProcess({ exitCode: 0 }) as any)
+    // auth check fails
+    spawnSpy.mockReturnValueOnce(
+      createMockProcess({
+        exitCode: 1,
+        stderr: 'Authentication failed: invalid credentials',
+      }) as any,
+    )
+
+    await expect(agent.init()).rejects.toThrow('auth check failed')
+
+    spawnSpy.mockRestore()
+  })
+
+  it('throws when auth check response indicates invalid API key', async () => {
+    const agent = createAgent()
+
+    const spawnSpy = spyOn(Bun, 'spawn')
+    // which succeeds
+    spawnSpy.mockReturnValueOnce(createMockProcess({ exitCode: 0 }) as any)
+    // auth check returns error JSON
+    spawnSpy.mockReturnValueOnce(
+      createMockProcess({
+        exitCode: 0,
+        stdout: JSON.stringify({ is_error: true, result: 'Invalid API key' }),
+      }) as any,
+    )
+
+    await expect(agent.init()).rejects.toThrow('auth failed')
+
+    spawnSpy.mockRestore()
+  })
+
+  it('proceeds when auth check output is not valid JSON', async () => {
+    const agent = createAgent()
+
+    const spawnSpy = spyOn(Bun, 'spawn')
+    spawnSpy.mockReturnValueOnce(createMockProcess({ exitCode: 0 }) as any)
+    spawnSpy.mockReturnValueOnce(
+      createMockProcess({
+        exitCode: 0,
+        stdout: 'not json at all',
+      }) as any,
+    )
+
+    // Should not throw — the SyntaxError is caught and logged as warning
+    await agent.init()
+
+    spawnSpy.mockRestore()
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// health — Version check
+// ═══════════════════════════════════════════════════════════════════
+
+describe('ClaudeAgent — health', () => {
+  it('returns ok=true and latencyMs when --version succeeds', async () => {
+    const agent = createAgent()
+
+    const spawnSpy = spyOn(Bun, 'spawn')
+    spawnSpy.mockReturnValueOnce(createMockProcess({ exitCode: 0 }) as any)
+
+    const result = await agent.health()
+
+    expect(result.ok).toBe(true)
+    expect(result.latencyMs).toBeGreaterThanOrEqual(0)
+    expect(result.error).toBeUndefined()
+
+    spawnSpy.mockRestore()
+  })
+
+  it('returns ok=false with exit code error when --version fails', async () => {
+    const agent = createAgent()
+
+    const spawnSpy = spyOn(Bun, 'spawn')
+    spawnSpy.mockReturnValueOnce(createMockProcess({ exitCode: 127 }) as any)
+
+    const result = await agent.health()
+
+    expect(result.ok).toBe(false)
+    expect(result.error).toBe('Exit code 127')
+    expect(result.latencyMs).toBeGreaterThanOrEqual(0)
+
+    spawnSpy.mockRestore()
+  })
+
+  it('returns ok=false with error message when spawn throws', async () => {
+    const agent = createAgent()
+
+    const spawnSpy = spyOn(Bun, 'spawn')
+    spawnSpy.mockImplementationOnce(() => {
+      throw new Error('ENOENT: no such file')
+    })
+
+    const result = await agent.health()
+
+    expect(result.ok).toBe(false)
+    expect(result.error).toBe('ENOENT: no such file')
+
+    spawnSpy.mockRestore()
+  })
+
+  it('uses custom binaryPath for version check', async () => {
+    const agent = createAgent({ binaryPath: '/opt/claude-beta' })
+
+    const spawnSpy = spyOn(Bun, 'spawn')
+    spawnSpy.mockReturnValueOnce(createMockProcess({ exitCode: 0 }) as any)
+
+    await agent.health()
+
+    const firstArg = spawnSpy.mock.calls[0][0] as string[]
+    expect(firstArg[0]).toBe('/opt/claude-beta')
+
+    spawnSpy.mockRestore()
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// query — Async generator with streaming JSON output
+// ═══════════════════════════════════════════════════════════════════
+
+describe('ClaudeAgent — query', () => {
+  it('yields text events from assistant messages', async () => {
+    const agent = createAgent()
+    const spawnSpy = spyOn(Bun, 'spawn')
+
+    const lines = [
+      JSON.stringify({
+        type: 'assistant',
+        message: {
+          role: 'assistant',
+          content: [{ type: 'text', text: 'Hello from Claude!' }],
+          usage: { input_tokens: 100, output_tokens: 50 },
+          model: 'claude-sonnet-4-6',
+        },
+        session_id: 'sess_abc',
+      }),
+      JSON.stringify({
+        type: 'result',
+        result: 'Hello from Claude!',
+        session_id: 'sess_abc',
+      }),
+    ]
+    spawnSpy.mockReturnValueOnce(createStreamingMockProcess(lines) as any)
+
+    const events: any[] = []
+    for await (const evt of agent.query({ prompt: 'Hi' })) {
+      events.push(evt)
+    }
+
+    // Should have text + done events
+    const textEvents = events.filter((e) => e.type === 'text')
+    expect(textEvents).toHaveLength(1)
+    expect(textEvents[0].content).toBe('Hello from Claude!')
+
+    const doneEvents = events.filter((e) => e.type === 'done')
+    expect(doneEvents).toHaveLength(1)
+    expect(doneEvents[0].sessionId).toBe('sess_abc')
+    expect(doneEvents[0].usage.inputTokens).toBe(100)
+    expect(doneEvents[0].usage.outputTokens).toBe(50)
+    expect(doneEvents[0].usage.model).toBe('claude-sonnet-4-6')
+
+    spawnSpy.mockRestore()
+  })
+
+  it('yields thinking events from thinking blocks', async () => {
+    const agent = createAgent()
+    const spawnSpy = spyOn(Bun, 'spawn')
+
+    const lines = [
+      JSON.stringify({
+        type: 'assistant',
+        message: {
+          role: 'assistant',
+          content: [
+            { type: 'thinking', thinking: 'Let me reason about this...' },
+            { type: 'text', text: 'The answer is 42.' },
+          ],
+          usage: { input_tokens: 200, output_tokens: 80 },
+        },
+      }),
+      JSON.stringify({ type: 'result', session_id: 'sess_xyz' }),
+    ]
+    spawnSpy.mockReturnValueOnce(createStreamingMockProcess(lines) as any)
+
+    const events: any[] = []
+    for await (const evt of agent.query({ prompt: 'Explain' })) {
+      events.push(evt)
+    }
+
+    expect(events.filter((e) => e.type === 'thinking')).toHaveLength(1)
+    expect(events.filter((e) => e.type === 'thinking')[0].content).toBe(
+      'Let me reason about this...',
+    )
+    expect(events.filter((e) => e.type === 'text')).toHaveLength(1)
+
+    spawnSpy.mockRestore()
+  })
+
+  it('yields tool_use and tool_result events', async () => {
+    const agent = createAgent()
+    const spawnSpy = spyOn(Bun, 'spawn')
+
+    const lines = [
+      JSON.stringify({
+        type: 'tool_use',
+        message: {
+          role: 'assistant',
+          content: [{ type: 'tool_use', name: 'Read', input: { file_path: '/tmp/test.txt' } }],
+        },
+      }),
+      JSON.stringify({
+        type: 'tool_result',
+        message: {
+          role: 'tool',
+          content: [{ type: 'tool_result', content: 'File contents here' }],
+        },
+      }),
+      JSON.stringify({
+        type: 'assistant',
+        message: {
+          role: 'assistant',
+          content: [{ type: 'text', text: 'I read the file.' }],
+          usage: { input_tokens: 300, output_tokens: 20 },
+        },
+        session_id: 'sess_tools',
+      }),
+      JSON.stringify({ type: 'result', session_id: 'sess_tools' }),
+    ]
+    spawnSpy.mockReturnValueOnce(createStreamingMockProcess(lines) as any)
+
+    const events: any[] = []
+    for await (const evt of agent.query({ prompt: 'Read file' })) {
+      events.push(evt)
+    }
+
+    const toolUse = events.filter((e) => e.type === 'tool_use')
+    expect(toolUse).toHaveLength(1)
+    expect(toolUse[0].tool).toBe('Read')
+
+    const toolResult = events.filter((e) => e.type === 'tool_result')
+    expect(toolResult).toHaveLength(1)
+    expect(toolResult[0].output).toBe('File contents here')
+
+    spawnSpy.mockRestore()
+  })
+
+  it('yields error event on non-zero exit with stderr', async () => {
+    const agent = createAgent()
+    const spawnSpy = spyOn(Bun, 'spawn')
+
+    // Empty stdout, non-zero exit with stderr
+    spawnSpy.mockReturnValueOnce({
+      stdout: new ReadableStream({
+        start(controller) {
+          controller.close()
+        },
+      }),
+      stderr: new Response('Fatal: rate limit exceeded').body!,
+      exited: Promise.resolve(1),
+      kill: mock(() => {}),
+      pid: 99999,
+    } as any)
+
+    const events: any[] = []
+    for await (const evt of agent.query({ prompt: 'test' })) {
+      events.push(evt)
+    }
+
+    const errors = events.filter((e) => e.type === 'error')
+    expect(errors.length).toBeGreaterThanOrEqual(1)
+
+    spawnSpy.mockRestore()
+  })
+
+  it('yields rate-limit recoverable error for rate limit stderr', async () => {
+    const agent = createAgent()
+    const spawnSpy = spyOn(Bun, 'spawn')
+
+    spawnSpy.mockReturnValueOnce({
+      stdout: new ReadableStream({
+        start(controller) {
+          controller.close()
+        },
+      }),
+      stderr: new Response("you've hit your limit for today").body!,
+      exited: Promise.resolve(1),
+      kill: mock(() => {}),
+      pid: 99999,
+    } as any)
+
+    const events: any[] = []
+    for await (const evt of agent.query({ prompt: 'test' })) {
+      events.push(evt)
+    }
+
+    const errors = events.filter((e) => e.type === 'error')
+    expect(errors.length).toBeGreaterThanOrEqual(1)
+    expect(errors[0].recoverable).toBe(true)
+
+    spawnSpy.mockRestore()
+  })
+
+  it('accumulates token usage across multiple messages', async () => {
+    const agent = createAgent()
+    const spawnSpy = spyOn(Bun, 'spawn')
+
+    const lines = [
+      JSON.stringify({
+        type: 'assistant',
+        message: {
+          role: 'assistant',
+          content: [{ type: 'text', text: 'Step 1' }],
+          usage: {
+            input_tokens: 100,
+            output_tokens: 50,
+            cache_read_input_tokens: 10,
+            cache_creation_input_tokens: 5,
+          },
+          model: 'claude-sonnet-4-6',
+        },
+        session_id: 'sess_multi',
+      }),
+      JSON.stringify({
+        type: 'assistant',
+        message: {
+          role: 'assistant',
+          content: [{ type: 'text', text: 'Step 2' }],
+          usage: {
+            input_tokens: 200,
+            output_tokens: 60,
+            cache_read_input_tokens: 20,
+            cache_creation_input_tokens: 8,
+          },
+          model: 'claude-sonnet-4-6',
+        },
+      }),
+      JSON.stringify({ type: 'result', session_id: 'sess_multi' }),
+    ]
+    spawnSpy.mockReturnValueOnce(createStreamingMockProcess(lines) as any)
+
+    const events: any[] = []
+    for await (const evt of agent.query({ prompt: 'multi-step' })) {
+      events.push(evt)
+    }
+
+    const done = events.find((e) => e.type === 'done')
+    expect(done.usage.inputTokens).toBe(300) // 100 + 200
+    expect(done.usage.outputTokens).toBe(110) // 50 + 60
+    expect(done.usage.cacheReadTokens).toBe(30) // 10 + 20
+    expect(done.usage.cacheWriteTokens).toBe(13) // 5 + 8
+    // contextTokens = last call only: 200 + 20 + 8 = 228
+    expect(done.usage.contextTokens).toBe(228)
+
+    spawnSpy.mockRestore()
+  })
+
+  it('falls back to result text when no assistant text was emitted', async () => {
+    const agent = createAgent()
+    const spawnSpy = spyOn(Bun, 'spawn')
+
+    const lines = [
+      JSON.stringify({
+        type: 'result',
+        result: 'Direct result text',
+        session_id: 'sess_fallback',
+      }),
+    ]
+    spawnSpy.mockReturnValueOnce(createStreamingMockProcess(lines) as any)
+
+    const events: any[] = []
+    for await (const evt of agent.query({ prompt: 'quick' })) {
+      events.push(evt)
+    }
+
+    const textEvents = events.filter((e) => e.type === 'text')
+    expect(textEvents).toHaveLength(1)
+    expect(textEvents[0].content).toBe('Direct result text')
+
+    spawnSpy.mockRestore()
+  })
+
+  it('skips non-JSON lines gracefully', async () => {
+    const agent = createAgent()
+    const spawnSpy = spyOn(Bun, 'spawn')
+
+    const lines = [
+      'some random log output',
+      JSON.stringify({
+        type: 'assistant',
+        message: {
+          role: 'assistant',
+          content: [{ type: 'text', text: 'Valid response' }],
+          usage: { input_tokens: 10, output_tokens: 5 },
+        },
+        session_id: 'sess_skip',
+      }),
+      'another non-json line',
+      JSON.stringify({ type: 'result', session_id: 'sess_skip' }),
+    ]
+    spawnSpy.mockReturnValueOnce(createStreamingMockProcess(lines) as any)
+
+    const events: any[] = []
+    for await (const evt of agent.query({ prompt: 'test' })) {
+      events.push(evt)
+    }
+
+    const textEvents = events.filter((e) => e.type === 'text')
+    expect(textEvents).toHaveLength(1)
+    expect(textEvents[0].content).toBe('Valid response')
+
+    spawnSpy.mockRestore()
+  })
+
+  it('clears activeProcess in finally block', async () => {
+    const agent = createAgent()
+    const spawnSpy = spyOn(Bun, 'spawn')
+
+    const lines = [
+      JSON.stringify({
+        type: 'assistant',
+        message: {
+          role: 'assistant',
+          content: [{ type: 'text', text: 'Done' }],
+          usage: { input_tokens: 1, output_tokens: 1 },
+        },
+        session_id: 'sess_fin',
+      }),
+      JSON.stringify({ type: 'result', session_id: 'sess_fin' }),
+    ]
+    spawnSpy.mockReturnValueOnce(createStreamingMockProcess(lines) as any)
+
+    for await (const _evt of agent.query({ prompt: 'test' })) {
+      // consume all events
+    }
+
+    expect((agent as any).activeProcess).toBeNull()
+
+    spawnSpy.mockRestore()
+  })
+
+  it('tags model with [1m] suffix when context1m is active', async () => {
+    const agent = createAgent({ context1m: true })
+    const spawnSpy = spyOn(Bun, 'spawn')
+
+    const lines = [
+      JSON.stringify({
+        type: 'assistant',
+        message: {
+          role: 'assistant',
+          content: [{ type: 'text', text: 'Extended context response' }],
+          usage: { input_tokens: 500, output_tokens: 100 },
+          model: 'claude-opus-4-6',
+        },
+        session_id: 'sess_1m',
+      }),
+      JSON.stringify({ type: 'result', session_id: 'sess_1m' }),
+    ]
+    spawnSpy.mockReturnValueOnce(createStreamingMockProcess(lines) as any)
+
+    const events: any[] = []
+    for await (const evt of agent.query({ prompt: 'big context' })) {
+      events.push(evt)
+    }
+
+    const done = events.find((e) => e.type === 'done')
+    expect(done.usage.model).toBe('claude-opus-4-6[1m]')
+
+    spawnSpy.mockRestore()
+  })
+
+  it('returns empty sessionId when no assistant text or output tokens', async () => {
+    const agent = createAgent()
+    const spawnSpy = spyOn(Bun, 'spawn')
+
+    const lines = [
+      JSON.stringify({
+        type: 'error',
+        result: 'Authentication error',
+      }),
+      JSON.stringify({ type: 'result', session_id: 'sess_invalid' }),
+    ]
+    spawnSpy.mockReturnValueOnce(createStreamingMockProcess(lines) as any)
+
+    const events: any[] = []
+    for await (const evt of agent.query({ prompt: 'test' })) {
+      events.push(evt)
+    }
+
+    const done = events.find((e) => e.type === 'done')
+    // No assistant text and no output tokens → invalid session
+    expect(done.sessionId).toBe('')
+
+    spawnSpy.mockRestore()
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// Configurable id and name (Phase B — multi-agent routing)
+// ═══════════════════════════════════════════════════════════════════
+
+describe('configurable id and name (Phase B)', () => {
+  it('defaults to id=claude and name=Claude Code (CLI) when not specified', () => {
+    const agent = createAgent()
+    expect(agent.id).toBe('claude')
+    expect(agent.name).toBe('Claude Code (CLI)')
+  })
+
+  it('uses custom id and name from constructor options', () => {
+    const agent = createAgent({ id: 'hermes', name: 'Hermes Agent' })
+    expect(agent.id).toBe('hermes')
+    expect(agent.name).toBe('Hermes Agent')
+  })
+
+  it('uses custom id with default name', () => {
+    const agent = createAgent({ id: 'deimos' })
+    expect(agent.id).toBe('deimos')
+    expect(agent.name).toBe('Claude Code (CLI)')
+  })
+})