@zooid/acp-client 0.7.0

package/src/index.ts

@@ -0,0 +1,25 @@
+export { AcpClient } from './acp-client.js'
+export { AgentProcess } from './agent-process.js'
+export { SessionMap } from './session-map.js'
+export { PRESETS, resolvePreset, isPreset } from './presets.js'
+export type { PresetName, PresetSpec } from './presets.js'
+export {
+  acpUpdateToAgentEvent,
+  approvalDecisionToPermissionResponse,
+} from './event-mapping.js'
+export type {
+  AgentConfig,
+  AgentEvent,
+  ApprovalDecision,
+  ApprovalRequest,
+  AgentMessageChunkEvent,
+  PlanEvent,
+  PromptInput,
+  PromptResult,
+  ToolCallEvent,
+  ToolCallUpdateEvent,
+} from './types.js'
+export type { SessionKey, SessionRecord } from './session-map.js'
+export type { AcpClientOptions } from './acp-client.js'
+export { TurnTracker } from './turn-tracker.js'
+export type { TapEvent, SessionUpdate, TurnTrackerOpts } from './turn-tracker.js'

package/src/presets.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from 'vitest'
+import { PRESETS, resolvePreset, isPreset } from './presets.js'
+
+describe('PRESETS registry', () => {
+  it('includes the ACP-native harnesses from SPEC.md', () => {
+    expect(PRESETS.opencode).toEqual({ command: 'opencode', args: ['acp'] })
+    expect(PRESETS.cline).toEqual({ command: 'cline', args: ['--acp'] })
+    expect(PRESETS.kiro).toEqual({ command: 'kiro', args: ['--acp'] })
+    expect(PRESETS.gemini).toEqual({ command: 'gemini', args: ['--acp'] })
+  })
+
+  it('includes the vendored-shim harnesses', () => {
+    expect(PRESETS.claude).toEqual({
+      command: 'npx',
+      args: ['-y', '@agentclientprotocol/claude-agent-acp'],
+    })
+    expect(PRESETS.codex).toEqual({
+      command: 'npx',
+      args: ['-y', '@zed-industries/codex-acp'],
+    })
+  })
+})
+
+describe('resolvePreset', () => {
+  it('returns the command/args tuple for a known preset', () => {
+    expect(resolvePreset('claude')).toEqual({
+      command: 'npx',
+      args: ['-y', '@agentclientprotocol/claude-agent-acp'],
+    })
+  })
+
+  it('throws a clear error for an unknown preset', () => {
+    expect(() => resolvePreset('made-up')).toThrow(/unknown ACP preset/i)
+  })
+
+  it('error message lists the available presets', () => {
+    try {
+      resolvePreset('made-up')
+    } catch (e) {
+      const msg = (e as Error).message
+      expect(msg).toContain('claude')
+      expect(msg).toContain('opencode')
+    }
+  })
+
+  it('returns a fresh args array each call (no shared mutable state)', () => {
+    const a = resolvePreset('claude')
+    const b = resolvePreset('claude')
+    expect(a).not.toBe(b)
+    expect(a.args).not.toBe(b.args)
+    a.args.push('mutated')
+    expect(b.args).toEqual(['-y', '@agentclientprotocol/claude-agent-acp'])
+  })
+
+  it('appends --model <id> to claude when opts.model is set', () => {
+    const spec = resolvePreset('claude', { model: 'claude-sonnet-4-6' })
+    expect(spec.args).toEqual([
+      '-y',
+      '@agentclientprotocol/claude-agent-acp',
+      '--model',
+      'claude-sonnet-4-6',
+    ])
+  })
+
+  it('appends --model <id> to codex when opts.model is set', () => {
+    const spec = resolvePreset('codex', { model: 'gpt-5.5' })
+    expect(spec.args).toEqual([
+      '-y',
+      '@zed-industries/codex-acp',
+      '--model',
+      'gpt-5.5',
+    ])
+  })
+
+  it('ignores opts.model for opencode (model lives in opencode.json)', () => {
+    const spec = resolvePreset('opencode', { model: 'opencode-go/kimi-k2.6' })
+    expect(spec.args).toEqual(['acp'])
+  })
+
+  it('returns the bare preset spec when no opts are given', () => {
+    const spec = resolvePreset('claude')
+    expect(spec.command).toBe('npx')
+    expect(spec.args).toEqual(['-y', '@agentclientprotocol/claude-agent-acp'])
+  })
+})
+
+describe('isPreset', () => {
+  it('returns true for known names', () => {
+    expect(isPreset('claude')).toBe(true)
+    expect(isPreset('opencode')).toBe(true)
+  })
+  it('returns false for unknown names', () => {
+    expect(isPreset('made-up')).toBe(false)
+  })
+  it('narrows the type so the value can index PRESETS', () => {
+    const name: string = 'claude'
+    if (isPreset(name)) {
+      const _entry = PRESETS[name]
+      expect(_entry.command).toBe('npx')
+    }
+  })
+})

package/src/presets.ts

@@ -0,0 +1,64 @@
+// Registry of ACP agent presets. Each preset maps a short name (e.g. "claude")
+// to the command + args needed to spawn that harness as an ACP agent.
+//
+// Categories:
+//   - ACP-native: invoked with a flag (opencode, cline, kiro, gemini)
+//   - Vendored shim: invoked via npx (claude, codex)
+//
+// See epics/002-ZOD019-acp-runtime/SPEC.md §"Agent compatibility matrix".
+
+export interface PresetSpec {
+  command: string
+  args: string[]
+}
+
+const PRESETS_INTERNAL = {
+  opencode: { command: 'opencode', args: ['acp'] },
+  cline: { command: 'cline', args: ['--acp'] },
+  kiro: { command: 'kiro', args: ['--acp'] },
+  gemini: { command: 'gemini', args: ['--acp'] },
+  claude: { command: 'npx', args: ['-y', '@agentclientprotocol/claude-agent-acp'] },
+  codex: { command: 'npx', args: ['-y', '@zed-industries/codex-acp'] },
+} as const satisfies Record<string, PresetSpec>
+
+export type PresetName = keyof typeof PRESETS_INTERNAL
+
+export const PRESETS: Record<PresetName, PresetSpec> = Object.freeze(
+  Object.fromEntries(
+    (Object.keys(PRESETS_INTERNAL) as PresetName[]).map((k) => [
+      k,
+      { command: PRESETS_INTERNAL[k].command, args: [...PRESETS_INTERNAL[k].args] },
+    ]),
+  ),
+) as Record<PresetName, PresetSpec>
+
+export function isPreset(name: string): name is PresetName {
+  return Object.prototype.hasOwnProperty.call(PRESETS_INTERNAL, name)
+}
+
+export interface ResolvePresetOpts {
+  /** Optional model string. Forwarded to the underlying shim as a `--model`
+   * flag where supported. Ignored for `opencode` (model lives in opencode.json). */
+  model?: string
+}
+
+// null = preset has its own model channel (opencode reads opencode.json); undefined = not implemented yet.
+const MODEL_FLAG_PER_PRESET: Partial<Record<PresetName, string | null>> = {
+  claude: '--model',
+  codex: '--model',
+  opencode: null,
+}
+
+export function resolvePreset(name: string, opts: ResolvePresetOpts = {}): PresetSpec {
+  if (!isPreset(name)) {
+    const known = Object.keys(PRESETS_INTERNAL).sort().join(', ')
+    throw new Error(`unknown ACP preset "${name}". Known presets: ${known}`)
+  }
+  const entry = PRESETS_INTERNAL[name]
+  const args: string[] = [...entry.args]
+  if (opts.model !== undefined) {
+    const flag = MODEL_FLAG_PER_PRESET[name]
+    if (flag) args.push(flag, opts.model)
+  }
+  return { command: entry.command, args }
+}

package/src/session-map.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { SessionMap, type SessionKey } from './session-map.js'
+
+describe('SessionMap', () => {
+  let map: SessionMap
+
+  beforeEach(() => {
+    map = new SessionMap()
+  })
+
+  const key = (threadId: string, agentId: string): SessionKey => ({ threadId, agentId })
+
+  it('returns undefined for missing keys', () => {
+    expect(map.get(key('t1', 'a1'))).toBeUndefined()
+  })
+
+  it('stores and retrieves sessions by (thread, agent) tuple', () => {
+    const session = { sessionId: 's-1', startedAt: Date.now() }
+    map.set(key('t1', 'a1'), session)
+    expect(map.get(key('t1', 'a1'))).toEqual(session)
+  })
+
+  it('keeps sessions for different agents in the same thread separate', () => {
+    map.set(key('t1', 'a1'), { sessionId: 's-1', startedAt: 0 })
+    map.set(key('t1', 'a2'), { sessionId: 's-2', startedAt: 0 })
+    expect(map.get(key('t1', 'a1'))?.sessionId).toBe('s-1')
+    expect(map.get(key('t1', 'a2'))?.sessionId).toBe('s-2')
+  })
+
+  it('keeps sessions for the same agent in different threads separate', () => {
+    map.set(key('t1', 'a1'), { sessionId: 's-1', startedAt: 0 })
+    map.set(key('t2', 'a1'), { sessionId: 's-2', startedAt: 0 })
+    expect(map.get(key('t1', 'a1'))?.sessionId).toBe('s-1')
+    expect(map.get(key('t2', 'a1'))?.sessionId).toBe('s-2')
+  })
+
+  it('removes a session by key', () => {
+    const k = key('t1', 'a1')
+    map.set(k, { sessionId: 's-1', startedAt: 0 })
+    map.delete(k)
+    expect(map.get(k)).toBeUndefined()
+  })
+
+  it('lists all sessions for a given agent across threads', () => {
+    map.set(key('t1', 'a1'), { sessionId: 's-1', startedAt: 0 })
+    map.set(key('t2', 'a1'), { sessionId: 's-2', startedAt: 0 })
+    map.set(key('t1', 'a2'), { sessionId: 's-3', startedAt: 0 })
+    const ids = map
+      .listForAgent('a1')
+      .map((s) => s.sessionId)
+      .sort()
+    expect(ids).toEqual(['s-1', 's-2'])
+  })
+})

package/src/session-map.ts

@@ -0,0 +1,47 @@
+export interface SessionKey {
+  threadId: string
+  agentId: string
+}
+
+export interface SessionRecord {
+  sessionId: string
+  startedAt: number
+}
+
+const keyOf = (k: SessionKey) => `${k.threadId}\x00${k.agentId}`
+
+interface InternalRecord extends SessionRecord {
+  agentId: string
+}
+
+export class SessionMap {
+  private readonly inner = new Map<string, InternalRecord>()
+
+  get(k: SessionKey): SessionRecord | undefined {
+    const v = this.inner.get(keyOf(k))
+    if (!v) return undefined
+    return { sessionId: v.sessionId, startedAt: v.startedAt }
+  }
+
+  set(k: SessionKey, value: SessionRecord): void {
+    this.inner.set(keyOf(k), {
+      sessionId: value.sessionId,
+      startedAt: value.startedAt,
+      agentId: k.agentId,
+    })
+  }
+
+  delete(k: SessionKey): void {
+    this.inner.delete(keyOf(k))
+  }
+
+  listForAgent(agentId: string): SessionRecord[] {
+    const out: SessionRecord[] = []
+    for (const v of this.inner.values()) {
+      if (v.agentId === agentId) {
+        out.push({ sessionId: v.sessionId, startedAt: v.startedAt })
+      }
+    }
+    return out
+  }
+}

package/src/session-store.test.ts

@@ -0,0 +1,115 @@
+import { mkdtemp, readFile, writeFile, mkdir, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { JsonFileSessionStore } from './session-store.js'
+
+describe('JsonFileSessionStore', () => {
+  let dir: string
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'zooid-session-store-'))
+  })
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  it('returns undefined for an unseen threadId on a fresh store', async () => {
+    const store = new JsonFileSessionStore({ agentId: 'docs', dir })
+    await store.load()
+    expect(store.get('$thread1')).toBeUndefined()
+  })
+
+  it('persists a write and is readable from a new instance', async () => {
+    const a = new JsonFileSessionStore({ agentId: 'docs', dir })
+    await a.load()
+    await a.set('$thread1', 'sess_aaa')
+
+    const b = new JsonFileSessionStore({ agentId: 'docs', dir })
+    await b.load()
+    expect(b.get('$thread1')).toBe('sess_aaa')
+  })
+
+  it('overwrites an existing threadId on set()', async () => {
+    const store = new JsonFileSessionStore({ agentId: 'docs', dir })
+    await store.load()
+    await store.set('$thread1', 'sess_aaa')
+    await store.set('$thread1', 'sess_bbb')
+    expect(store.get('$thread1')).toBe('sess_bbb')
+  })
+
+  it('delete() removes a threadId, persists, survives reload', async () => {
+    const a = new JsonFileSessionStore({ agentId: 'docs', dir })
+    await a.load()
+    await a.set('$thread1', 'sess_aaa')
+    await a.delete('$thread1')
+
+    const b = new JsonFileSessionStore({ agentId: 'docs', dir })
+    await b.load()
+    expect(b.get('$thread1')).toBeUndefined()
+  })
+
+  it('creates the dir on first write if it does not yet exist', async () => {
+    const nested = join(dir, 'agents', 'docs')
+    const store = new JsonFileSessionStore({ agentId: 'docs', dir: nested })
+    await store.load()
+    await store.set('$t', 'sess_x')
+    const raw = await readFile(join(nested, 'sessions.json'), 'utf8')
+    expect(JSON.parse(raw).agent_id).toBe('docs')
+  })
+
+  it('treats a missing file as empty (no throw)', async () => {
+    const store = new JsonFileSessionStore({ agentId: 'docs', dir })
+    await expect(store.load()).resolves.toBeUndefined()
+    expect(store.get('anything')).toBeUndefined()
+  })
+
+  it('treats a corrupted JSON file as empty (logs, no throw)', async () => {
+    await mkdir(dir, { recursive: true })
+    await writeFile(join(dir, 'sessions.json'), 'this is not json{', 'utf8')
+    const store = new JsonFileSessionStore({ agentId: 'docs', dir })
+    await expect(store.load()).resolves.toBeUndefined()
+    expect(store.get('anything')).toBeUndefined()
+  })
+
+  it('treats a file with mismatched agent_id as empty', async () => {
+    await mkdir(dir, { recursive: true })
+    await writeFile(
+      join(dir, 'sessions.json'),
+      JSON.stringify({
+        version: 1,
+        agent_id: 'someone-else',
+        sessions: [{ thread_id: '$t', session_id: 'sess_x', updated_at: '2026-05-07T00:00:00Z' }],
+      }),
+      'utf8',
+    )
+    const store = new JsonFileSessionStore({ agentId: 'docs', dir })
+    await store.load()
+    expect(store.get('$t')).toBeUndefined()
+  })
+
+  it('writes atomically (temp file then rename) and produces valid JSON', async () => {
+    const store = new JsonFileSessionStore({ agentId: 'docs', dir })
+    await store.load()
+    await store.set('$t', 'sess_x')
+    const raw = await readFile(join(dir, 'sessions.json'), 'utf8')
+    const parsed = JSON.parse(raw) as { version: number; agent_id: string; sessions: unknown[] }
+    expect(parsed.version).toBe(1)
+    expect(parsed.agent_id).toBe('docs')
+    expect(parsed.sessions).toHaveLength(1)
+  })
+
+  it('serialises concurrent set() calls (last write wins, file stays valid)', async () => {
+    const store = new JsonFileSessionStore({ agentId: 'docs', dir })
+    await store.load()
+    await Promise.all([
+      store.set('$t1', 'sess_1'),
+      store.set('$t2', 'sess_2'),
+      store.set('$t3', 'sess_3'),
+    ])
+    const raw = await readFile(join(dir, 'sessions.json'), 'utf8')
+    expect(() => JSON.parse(raw)).not.toThrow()
+    expect(store.get('$t1')).toBe('sess_1')
+    expect(store.get('$t2')).toBe('sess_2')
+    expect(store.get('$t3')).toBe('sess_3')
+  })
+})

package/src/session-store.ts

@@ -0,0 +1,110 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+export interface SessionStoreOptions {
+  /** Stable agent id; written into the file as a sanity-check on load. */
+  agentId: string
+  /** Directory holding `sessions.json`. Typically `<dataRoot>/agents/<agentId>/`. */
+  dir: string
+}
+
+interface StoredFile {
+  version: 1
+  agent_id: string
+  sessions: Array<{
+    thread_id: string
+    session_id: string
+    updated_at: string
+  }>
+}
+
+/**
+ * Per-agent JSON-file-backed map of `threadId → sessionId`. In-memory map is
+ * the source of truth at runtime; writes are flushed atomically (write to a
+ * temp file then rename) and serialised so concurrent set/delete calls never
+ * produce a partial file.
+ *
+ * Scale ceiling: every set rewrites the whole file. ZOD042 will swap this
+ * impl for a SQLite-backed one with the same surface beyond ~10k threads.
+ */
+export class JsonFileSessionStore {
+  private readonly mem = new Map<string, string>()
+  private readonly path: string
+  private writeChain: Promise<void> = Promise.resolve()
+
+  constructor(private readonly opts: SessionStoreOptions) {
+    this.path = join(opts.dir, 'sessions.json')
+  }
+
+  async load(): Promise<void> {
+    let raw: string
+    try {
+      raw = await readFile(this.path, 'utf8')
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') return
+      console.warn(`[acp-client:${this.opts.agentId}] sessions.json read failed:`, err)
+      return
+    }
+    let parsed: StoredFile
+    try {
+      parsed = JSON.parse(raw) as StoredFile
+    } catch (err) {
+      console.warn(`[acp-client:${this.opts.agentId}] sessions.json corrupt; treating as empty:`, err)
+      return
+    }
+    if (parsed.version !== 1) {
+      console.warn(
+        `[acp-client:${this.opts.agentId}] sessions.json version=${parsed.version} unknown; treating as empty`,
+      )
+      return
+    }
+    if (parsed.agent_id !== this.opts.agentId) {
+      console.warn(
+        `[acp-client:${this.opts.agentId}] sessions.json agent_id mismatch ` +
+          `(file=${parsed.agent_id}); treating as empty`,
+      )
+      return
+    }
+    for (const row of parsed.sessions ?? []) {
+      if (typeof row.thread_id === 'string' && typeof row.session_id === 'string') {
+        this.mem.set(row.thread_id, row.session_id)
+      }
+    }
+  }
+
+  get(threadId: string): string | undefined {
+    return this.mem.get(threadId)
+  }
+
+  async set(threadId: string, sessionId: string): Promise<void> {
+    this.mem.set(threadId, sessionId)
+    await this.flush()
+  }
+
+  async delete(threadId: string): Promise<void> {
+    if (!this.mem.has(threadId)) return
+    this.mem.delete(threadId)
+    await this.flush()
+  }
+
+  async flush(): Promise<void> {
+    const next = (this.writeChain = this.writeChain.then(() => this.writeNow()))
+    return next
+  }
+
+  private async writeNow(): Promise<void> {
+    await mkdir(this.opts.dir, { recursive: true })
+    const file: StoredFile = {
+      version: 1,
+      agent_id: this.opts.agentId,
+      sessions: Array.from(this.mem.entries()).map(([thread_id, session_id]) => ({
+        thread_id,
+        session_id,
+        updated_at: new Date().toISOString(),
+      })),
+    }
+    const tmp = `${this.path}.tmp-${process.pid}-${Date.now()}`
+    await writeFile(tmp, JSON.stringify(file, null, 2), 'utf8')
+    await rename(tmp, this.path)
+  }
+}

package/src/turn-tracker.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it, vi } from 'vitest'
+import { TurnTracker, type TapEvent } from './turn-tracker.js'
+
+describe('TurnTracker', () => {
+  it('emits turn_started → session_update* → turn_completed in order', () => {
+    const seen: TapEvent[] = []
+    const t = new TurnTracker({
+      agentId: 'docs',
+      onTap: (e) => seen.push(e),
+      newTurnId: () => 'turn_001',
+    })
+    const turnId = t.startTurn({ sessionId: 'sess_a', promptText: 'hi' })
+    expect(turnId).toBe('turn_001')
+    t.observeUpdate('sess_a', {
+      sessionUpdate: 'agent_message_chunk',
+      content: { type: 'text', text: 'hello' },
+    } as never)
+    t.endTurn({ sessionId: 'sess_a', stopReason: 'end_turn' })
+    expect(seen.map((e) => e.kind)).toEqual([
+      'turn_started',
+      'session_update',
+      'turn_completed',
+    ])
+    expect(seen[1].turnId).toBe('turn_001')
+    expect(seen[2].kind === 'turn_completed' && seen[2].stopReason).toBe('end_turn')
+  })
+
+  it('tags concurrent sessions with their own turn ids', () => {
+    const seen: TapEvent[] = []
+    let n = 0
+    const t = new TurnTracker({
+      agentId: 'x',
+      onTap: (e) => seen.push(e),
+      newTurnId: () => `turn_${++n}`,
+    })
+    t.startTurn({ sessionId: 'a', promptText: 'p1' })
+    t.startTurn({ sessionId: 'b', promptText: 'p2' })
+    t.observeUpdate('a', { sessionUpdate: 'tool_call' } as never)
+    t.observeUpdate('b', { sessionUpdate: 'tool_call' } as never)
+    t.endTurn({ sessionId: 'a', stopReason: 'end_turn' })
+    t.endTurn({ sessionId: 'b', stopReason: 'cancelled' })
+    const updates = seen.filter((e) => e.kind === 'session_update')
+    expect(updates).toHaveLength(2)
+    expect(updates[0]).toMatchObject({ sessionId: 'a', turnId: 'turn_1' })
+    expect(updates[1]).toMatchObject({ sessionId: 'b', turnId: 'turn_2' })
+  })
+
+  it('emits update with turnId=null if no turn is active for that session', () => {
+    const seen: TapEvent[] = []
+    const t = new TurnTracker({
+      agentId: 'x',
+      onTap: (e) => seen.push(e),
+      newTurnId: () => 't',
+    })
+    t.observeUpdate('orphan', { sessionUpdate: 'agent_message_chunk' } as never)
+    expect(seen).toHaveLength(1)
+    expect(seen[0]).toMatchObject({
+      kind: 'session_update',
+      sessionId: 'orphan',
+      turnId: null,
+    })
+  })
+
+  it('endTurn for an unknown session is a silent no-op (defensive)', () => {
+    const onTap = vi.fn()
+    const t = new TurnTracker({ agentId: 'x', onTap, newTurnId: () => 't' })
+    expect(() => t.endTurn({ sessionId: 'nope', stopReason: 'end_turn' })).not.toThrow()
+    expect(onTap).not.toHaveBeenCalled()
+  })
+})

package/src/turn-tracker.ts

@@ -0,0 +1,96 @@
+import type { SessionNotification } from '@agentclientprotocol/sdk'
+
+export type SessionUpdate = SessionNotification['update']
+
+export type TapEvent =
+  | {
+      kind: 'turn_started'
+      agentId: string
+      sessionId: string
+      turnId: string
+      promptText: string
+    }
+  | {
+      kind: 'session_update'
+      agentId: string
+      sessionId: string
+      turnId: string | null
+      update: SessionUpdate
+    }
+  | {
+      kind: 'turn_completed'
+      agentId: string
+      sessionId: string
+      turnId: string
+      stopReason: string
+    }
+
+export interface TurnTrackerOpts {
+  agentId: string
+  onTap: (e: TapEvent) => void
+  /** Override for tests; defaults to crypto.randomUUID(). */
+  newTurnId?: () => string
+}
+
+export class TurnTracker {
+  private readonly active = new Map<string, string>()
+  private readonly newTurnId: () => string
+  private readonly agentId: string
+  private readonly onTap: (e: TapEvent) => void
+
+  constructor(opts: TurnTrackerOpts) {
+    this.agentId = opts.agentId
+    this.onTap = opts.onTap
+    this.newTurnId =
+      opts.newTurnId ?? (() => `turn_${crypto.randomUUID().slice(0, 8)}`)
+  }
+
+  startTurn({
+    sessionId,
+    promptText,
+  }: {
+    sessionId: string
+    promptText: string
+  }): string {
+    const turnId = this.newTurnId()
+    this.active.set(sessionId, turnId)
+    this.onTap({
+      kind: 'turn_started',
+      agentId: this.agentId,
+      sessionId,
+      turnId,
+      promptText,
+    })
+    return turnId
+  }
+
+  observeUpdate(sessionId: string, update: SessionUpdate): void {
+    const turnId = this.active.get(sessionId) ?? null
+    this.onTap({
+      kind: 'session_update',
+      agentId: this.agentId,
+      sessionId,
+      turnId,
+      update,
+    })
+  }
+
+  endTurn({
+    sessionId,
+    stopReason,
+  }: {
+    sessionId: string
+    stopReason: string
+  }): void {
+    const turnId = this.active.get(sessionId)
+    if (!turnId) return
+    this.active.delete(sessionId)
+    this.onTap({
+      kind: 'turn_completed',
+      agentId: this.agentId,
+      sessionId,
+      turnId,
+      stopReason,
+    })
+  }
+}