@kidsinai/kids-client 0.0.1

package/README.md

@@ -0,0 +1,114 @@
+# @kidsinai/kids-client
+
+> **Status:** Phase 2.5 MVP scaffold (2026-05-16). Not yet npm-published; consumed via workspace + `bun link` for dogfood.
+
+The own-client TUI for Kids OpenCode. Talks to a local `opencode serve` process over `@opencode-ai/sdk/v2`. Replaces the upstream Solid.js TUI with a kid-warm Ink (React+Node) experience: branded welcome screen, Mission progress + Stars balance, permission dialogs the kid actually understands, friendly error screens, Kids Helpline overlay for crisis terms.
+
+## Why this exists
+
+Per [`kids-opencode-client-prd.md`](../../../airbotix/docs/product/prd/kids-opencode-client-prd.md) §2 **C route**, the terminal-end UX must not look like an engineer tool. Upstream `opencode` is a great agent runtime but a hostile first impression for a 12-year-old. This package owns the rendering layer.
+
+Architecture (see PRD §2.3):
+
+```
+kids-opencode wrapper → kids-client (this package, Ink)
+                         │
+                         spawns + supervises
+                         ↓
+                       opencode serve (upstream kernel + @kidsinai/kids-opencode-plugin)
+                         │
+                         routes LLM via
+                         ↓
+                       DeepRouter
+```
+
+## How it runs
+
+```
+$ kids-opencode --course portfolio-site --mission mission-1
+```
+
+The wrapper:
+1. Loads `OPENCODE_SERVER_PASSWORD` from `~/.config/kids-opencode/server-password`
+2. Translates `--course` / `--mission` to env vars
+3. Exec's `kids-client`
+
+The client:
+1. Probes `http://127.0.0.1:4096/app` with Basic Auth
+2. If down, spawns `opencode serve` as its child and pipes stderr
+3. Parses `[kids-audit] {...}` lines into the audit pipeline (local jsonl buffer; remote ingest plumbed but disabled)
+4. Subscribes to `client.global.event()` SSE
+5. Renders the kid-warm Ink TUI
+
+## Architecture inside this package
+
+- **`src/core/`** — pure TS, no Ink imports. State machine, SDK client, SSE dispatcher, serve subprocess manager, audit pipeline. **V1 Tauri reuses this verbatim.**
+- **`src/render/ink/`** — Ink components and screens. Replaceable with a WebView render layer for V1.
+
+### Files
+
+```
+src/index.tsx                  Composition root; main()
+src/core/env.ts                Reads KIDS_*/OPENCODE_* env, validates
+src/core/serve-manager.ts      Spawns + tails opencode serve
+src/core/connection.ts         createOpencodeClient with Basic Auth
+src/core/session.ts            session.create / prompt / abort
+src/core/events.ts             SSE subscribe + dispatch
+src/core/store.ts              useSyncExternalStore-compatible pub/sub
+src/core/audit-pipeline.ts     stderr → jsonl buffer (+ future remote POST)
+src/dangerous-topic-bridge.ts  Crisis-term patterns (mirrors kids-tui-plugin)
+
+src/render/ink/App.tsx                  Router
+src/render/ink/theme.ts                 Kid-warm color tokens
+src/render/ink/screens/StartupScreen.tsx
+src/render/ink/screens/MissionScreen.tsx
+src/render/ink/screens/PermissionModal.tsx
+src/render/ink/screens/DangerousTopicModal.tsx
+src/render/ink/screens/ErrorScreen.tsx
+src/render/ink/components/Header.tsx
+src/render/ink/components/ChatStream.tsx
+src/render/ink/components/Input.tsx
+src/render/ink/components/Thinking.tsx
+src/render/ink/components/KeyHints.tsx
+```
+
+## Dogfood (current path)
+
+From a clone of `kidsinai/kids-opencode`:
+
+```
+bun install
+bun link --cwd packages/kids-client
+KIDS_LLM_BYPASS_GATEWAY=1 ANTHROPIC_API_KEY=sk-ant-... \
+  kids-opencode --course portfolio-site --mission mission-1
+```
+
+The startup screen should render within ~3 seconds. The wrapper's `--shutdown` subcommand kills any lingering serve on `:4096`.
+
+## V0 MVP scope cuts
+
+Items in the PRD that we deliberately deferred to keep Phase 2.5 shippable for Workshop #2:
+
+- **Session resume across client crashes** (PRD §5.3) — client kills serve on exit; deferred to V1
+- **Sound pack** — deferred to V1 Tauri
+- **Embedded browser preview** — V1 Tauri
+- **Locale runtime switching** — V0 reads `$LANG` once at startup
+- **Multi-mission parallel** — single active session only
+- **Project sharing** — handled in `airbotix-app` web side
+
+## Tests
+
+```
+bun test
+```
+
+31 tests across env validation, store mutation, audit pipeline jsonl write,
+dangerous-topic pattern detection, and Ink snapshot of StartupScreen/ErrorScreen
+variants. Wired into CI via `.github/workflows/ci.yml`.
+
+## Related
+
+- Plan: `~/.claude/plans/resilient-sleeping-pancake.md`
+- Q3 spike result: `../../docs/v2-api-verification.md` §Q3
+- Plugin (server-side kid-safety): `../kids-plugin/`
+- TUI plugin (A-route theme/keymap, sibling): `../kids-tui-plugin/`

package/bin/kids-client

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+// Entry shim for the kids-client TUI. The actual app lives in src/index.tsx.
+// The wrapper bin/kids-opencode exec's this binary after preparing env.
+import "../src/index.tsx"

package/package.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@kidsinai/kids-client",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Own-client TUI for Kids OpenCode — talks to local `opencode serve` via @opencode-ai/sdk v2 with kid-warm rendering, mission progress, permission dialog, and stderr-tail audit pipeline.",
+  "license": "MIT",
+  "homepage": "https://github.com/kidsinai/kids-opencode",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kidsinai/kids-opencode.git",
+    "directory": "packages/kids-client"
+  },
+  "keywords": ["opencode", "kids", "tui", "ink", "education", "k-12", "agentic"],
+  "bin": {
+    "kids-client": "./bin/kids-client"
+  },
+  "exports": {
+    ".": {
+      "import": "./src/index.tsx",
+      "types": "./src/index.tsx"
+    }
+  },
+  "files": ["src", "bin", "README.md", "LICENSE"],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "@opencode-ai/sdk": ">=1.14.0"
+  },
+  "dependencies": {
+    "ink": "^5.0.1",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "react": "^18.3.1",
+    "@kidsinai/kids-opencode-plugin": "workspace:*"
+  },
+  "devDependencies": {
+    "@opencode-ai/sdk": "^1.14.51",
+    "@types/react": "^18.3.12",
+    "ink-testing-library": "^4.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/core/audit-pipeline.ts

@@ -0,0 +1,93 @@
+/**
+ * Audit pipeline: stderr-tail input → batch → local jsonl buffer
+ * → (later) POST to platform-backend /api/audit.
+ *
+ * V0 MVP scope: write only to local file at
+ *   ~/.config/kids-opencode/audit-buffer.jsonl
+ * Remote ingest is plumbed but disabled until platform-backend ships
+ * the endpoint and `@airbotix/audit-schema` is published (see PRD
+ * audit-event-schema-prd.md §8).
+ *
+ * Format on disk: one JSON envelope per line. Each line is the event
+ * exactly as parsed from `[kids-audit] {...}` stderr output.
+ */
+
+import { appendFile, mkdir } from "node:fs/promises"
+import { dirname } from "node:path"
+
+export interface AuditPipelineOptions {
+  bufferPath: string
+  /** Optional remote endpoint. When unset, only the local buffer is written. */
+  remoteUrl?: string
+  remoteAuthHeader?: string
+  /** Max items held in memory before flushing to disk. */
+  batchSize?: number
+  /** Max ms between flushes regardless of batch size. */
+  flushIntervalMs?: number
+}
+
+export class AuditPipeline {
+  private opts: AuditPipelineOptions
+  private pending: unknown[] = []
+  private flushTimer: ReturnType<typeof setInterval> | null = null
+  private writing = false
+
+  constructor(opts: AuditPipelineOptions) {
+    this.opts = { batchSize: 20, flushIntervalMs: 2000, ...opts }
+  }
+
+  start(): void {
+    if (this.flushTimer) return
+    this.flushTimer = setInterval(() => {
+      void this.flush().catch(() => {})
+    }, this.opts.flushIntervalMs!)
+  }
+
+  push(event: unknown): void {
+    this.pending.push(event)
+    if (this.pending.length >= (this.opts.batchSize ?? 20)) {
+      void this.flush().catch(() => {})
+    }
+  }
+
+  async flush(): Promise<void> {
+    if (this.writing) return
+    if (this.pending.length === 0) return
+    this.writing = true
+    const batch = this.pending
+    this.pending = []
+    try {
+      await mkdir(dirname(this.opts.bufferPath), { recursive: true })
+      const lines = batch.map((e) => JSON.stringify(e)).join("\n") + "\n"
+      await appendFile(this.opts.bufferPath, lines, "utf8")
+      if (this.opts.remoteUrl) await this.postRemote(batch)
+    } catch {
+      // Restore on failure so we retry next tick.
+      this.pending = [...batch, ...this.pending]
+    } finally {
+      this.writing = false
+    }
+  }
+
+  async stop(): Promise<void> {
+    if (this.flushTimer) clearInterval(this.flushTimer)
+    this.flushTimer = null
+    await this.flush()
+  }
+
+  private async postRemote(batch: unknown[]): Promise<void> {
+    if (!this.opts.remoteUrl) return
+    try {
+      await fetch(this.opts.remoteUrl, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          ...(this.opts.remoteAuthHeader ? { authorization: this.opts.remoteAuthHeader } : {}),
+        },
+        body: JSON.stringify({ events: batch }),
+      })
+    } catch {
+      // Swallow; local jsonl is the source of truth.
+    }
+  }
+}

package/src/core/check-runner.ts

@@ -0,0 +1,77 @@
+/**
+ * In-TUI mission acceptance check. Calls runMissionChecks from
+ * @kidsinai/kids-opencode-plugin against the kid's current project
+ * directory.
+ *
+ * Triggered by the kid typing "/check" or a vernacular completion phrase
+ * (e.g. "我做完了" / "I'm done") in the chat input. index.tsx intercepts
+ * those strings before they reach the LLM.
+ */
+
+import { runMissionChecks, type MissionResult } from "@kidsinai/kids-opencode-plugin"
+
+export interface CheckOutcome {
+  kind: "pass" | "fail" | "error"
+  missionId: string
+  /** Friendly summary for the kid. Composed from MissionResult.completion_message + per-check labels. */
+  message: string
+  /** Detailed per-check labels for the chat trail. */
+  details: string[]
+  result?: MissionResult
+}
+
+export const COMPLETION_PHRASES_ZH = ["/check", "我做完了", "做完了", "完成了", "我完成了", "/done"]
+export const COMPLETION_PHRASES_EN = ["/check", "i'm done", "im done", "done!", "i am done", "/done", "all done"]
+
+export function isCompletionTrigger(text: string, locale: "zh-Hans" | "en"): boolean {
+  const t = text.trim().toLowerCase()
+  if (!t) return false
+  const candidates = locale === "zh-Hans" ? COMPLETION_PHRASES_ZH : COMPLETION_PHRASES_EN
+  return candidates.some((p) => t === p.toLowerCase() || (t.length < 25 && t.includes(p.toLowerCase())))
+}
+
+export interface RunCheckOptions {
+  missionId: string
+  packId: string
+  projectDir?: string
+  locale: "zh-Hans" | "en"
+}
+
+export function runCheck(opts: RunCheckOptions): CheckOutcome {
+  if (!opts.missionId) {
+    return {
+      kind: "error",
+      missionId: opts.missionId ?? "",
+      message: opts.locale === "zh-Hans" ? "没设当前 Mission，没法验收。" : "No active Mission to check.",
+      details: [],
+    }
+  }
+  const result = runMissionChecks(opts.missionId, {
+    packId: opts.packId,
+    projectDir: opts.projectDir,
+  })
+  if ("error" in result) {
+    return {
+      kind: "error",
+      missionId: opts.missionId,
+      message: result.error,
+      details: [],
+    }
+  }
+  const details = (result.results ?? []).map((r) => {
+    const tick = r.status === "pass" ? "✅" : r.status === "skip" ? "⏭" : "❌"
+    return `${tick} ${r.description || r.id || "check"}`
+  })
+  const ok = result.ok
+  if (ok) {
+    const msg = result.completion_message
+      ?? (opts.locale === "zh-Hans"
+        ? `Mission ${result.mission_id} 全部通过！${result.passed}/${result.total} 项检查 ✓`
+        : `Mission ${result.mission_id} passed all checks. ${result.passed}/${result.total} ✓`)
+    return { kind: "pass", missionId: opts.missionId, message: msg, details, result }
+  }
+  const msg = opts.locale === "zh-Hans"
+    ? `还差一点：${result.passed}/${result.total} 通过，${result.failed} 个需要再修一下。`
+    : `Almost: ${result.passed}/${result.total} passed, ${result.failed} still need work.`
+  return { kind: "fail", missionId: opts.missionId, message: msg, details, result }
+}

package/src/core/connection.ts

@@ -0,0 +1,26 @@
+/**
+ * SDK v2 client factory + cheap auth probe.
+ *
+ * The SDK ships at the @opencode-ai/sdk/v2 subpath (see Q1 verification).
+ * We instantiate once per client process; reconnection on SSE drop is
+ * handled by events.ts (it re-creates the stream, not the client).
+ */
+
+import { createOpencodeClient } from "@opencode-ai/sdk/v2"
+
+export type OpencodeClient = ReturnType<typeof createOpencodeClient>
+
+export interface ConnectionOptions {
+  baseUrl: string
+  serverPassword: string
+}
+
+export function createKidsClient(opts: ConnectionOptions): OpencodeClient {
+  const authHeader = "Basic " + btoa(`:${opts.serverPassword}`)
+  return createOpencodeClient({
+    baseUrl: opts.baseUrl,
+    headers: {
+      authorization: authHeader,
+    },
+  } as Parameters<typeof createOpencodeClient>[0])
+}

package/src/core/course-pack.ts

@@ -0,0 +1,89 @@
+/**
+ * Course Pack loader bridge. Wraps @kidsinai/kids-opencode-plugin's pack
+ * loader so the client can render real pack/mission metadata (title,
+ * mission index, Stars budget) instead of just echoing env vars.
+ *
+ * Also lists installed packs by scanning the bundled course-packs directory
+ * — used by CoursePackPicker.
+ */
+
+import { readdirSync, statSync } from "node:fs"
+import { join } from "node:path"
+import {
+  bundledCoursePacksDir,
+  findMission,
+  loadCoursePack,
+  type CoursePack,
+  type CoursePackMission,
+} from "@kidsinai/kids-opencode-plugin"
+
+export interface ResolvedMissionContext {
+  pack: CoursePack
+  packTitle: string
+  mission: CoursePackMission | null
+  missionTitle: string | null
+  /** 1-based index of the current mission within pack.missions. null if free-play. */
+  missionIndex: number | null
+  missionTotal: number
+  starsBudget: number
+}
+
+export function resolveContext(packId: string | null, missionId: string | null): ResolvedMissionContext | null {
+  if (!packId) return null
+  const pack = loadCoursePack(packId)
+  if (!pack) return null
+  const missions = pack.missions ?? []
+  const mission = missionId ? findMission(pack, missionId) : null
+  const missionIndex = mission ? missions.findIndex((m) => m.id === mission.id) + 1 : null
+  return {
+    pack,
+    packTitle: pack.title,
+    mission,
+    missionTitle: mission?.title ?? null,
+    missionIndex: missionIndex && missionIndex > 0 ? missionIndex : null,
+    missionTotal: missions.length,
+    starsBudget: pack.estimated_stars_budget ?? 0,
+  }
+}
+
+export interface InstalledPack {
+  id: string
+  title: string
+  shortDescription: string | null
+  missionCount: number
+  starsBudget: number
+}
+
+/**
+ * Enumerate packs available in the bundled course-packs/ directory. Used
+ * by the picker screen. Tolerant of malformed packs (skips, doesn't
+ * throw).
+ */
+export function listInstalledPacks(): InstalledPack[] {
+  const dir = bundledCoursePacksDir()
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return []
+  }
+  const out: InstalledPack[] = []
+  for (const id of entries) {
+    try {
+      const full = join(dir, id)
+      if (!statSync(full).isDirectory()) continue
+      const pack = loadCoursePack(id)
+      if (!pack) continue
+      out.push({
+        id: pack.id,
+        title: pack.title,
+        shortDescription: pack.short_description ?? null,
+        missionCount: pack.missions?.length ?? 0,
+        starsBudget: pack.estimated_stars_budget ?? 0,
+      })
+    } catch {
+      // skip malformed entry
+    }
+  }
+  return out
+}

package/src/core/env.ts

@@ -0,0 +1,69 @@
+/**
+ * Env contract between the wrapper (`bin/kids-opencode`) and this client.
+ * Wrapper resolves auth + flag → env vars → exec kids-client.
+ *
+ * Required keys cause hard-fail at startup with a friendly ErrorScreen
+ * (config_missing / auth_failed variant).
+ */
+
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+export interface KidsClientEnv {
+  /** Local opencode serve endpoint. Default http://127.0.0.1:4096. */
+  opencodeBaseUrl: string
+  /** HTTP Basic Auth password for serve. Mandatory. */
+  opencodeServerPassword: string
+  /** DeepRouter tenant key. May be empty when using BYOK bypass. */
+  deeprouterApiKey: string
+  /** True if the wrapper set KIDS_LLM_BYPASS_GATEWAY=1 (BYOK dogfood mode). */
+  bypassGateway: boolean
+  /** Optional course pack id (e.g. "portfolio-site"). */
+  coursePack: string | null
+  /** Optional mission id (e.g. "mission-1"). */
+  mission: string | null
+  /** Locale hint ("zh-Hans" / "en"). Picked from KIDS_LOCALE or $LANG. */
+  locale: "zh-Hans" | "en"
+  /** Path to opencode binary so client can spawn `opencode serve`. */
+  opencodeBin: string
+  /** Path to ~/.config/kids-opencode/ for audit buffer + future state. */
+  configDir: string
+  /** When true, the client renders a "Tony banner" / suppresses interactive prompts (CI). */
+  noBanner: boolean
+}
+
+export function readEnv(): KidsClientEnv {
+  const password = process.env.OPENCODE_SERVER_PASSWORD ?? ""
+  const lang = process.env.KIDS_LOCALE ?? process.env.LANG ?? "en"
+  const locale: "zh-Hans" | "en" = lang.toLowerCase().startsWith("zh") ? "zh-Hans" : "en"
+  return {
+    opencodeBaseUrl: process.env.OPENCODE_BASE_URL ?? "http://127.0.0.1:4096",
+    opencodeServerPassword: password,
+    deeprouterApiKey: process.env.DEEPROUTER_API_KEY ?? "",
+    bypassGateway: process.env.KIDS_LLM_BYPASS_GATEWAY === "1",
+    coursePack: process.env.KIDS_COURSE_PACK || null,
+    mission: process.env.KIDS_MISSION || null,
+    locale,
+    opencodeBin: process.env.OPENCODE_BIN ?? "opencode",
+    configDir: process.env.KIDS_OPENCODE_CONFIG_DIR ?? join(homedir(), ".config", "kids-opencode"),
+    noBanner: process.env.KIDS_OPENCODE_NO_BANNER === "1",
+  }
+}
+
+export function validateEnv(env: KidsClientEnv): { ok: true } | { ok: false; reason: string; variant: "config_missing" | "auth_failed" } {
+  if (!env.opencodeServerPassword) {
+    return {
+      ok: false,
+      reason: "OPENCODE_SERVER_PASSWORD is empty. The wrapper should have loaded it from " + join(env.configDir, "server-password"),
+      variant: "config_missing",
+    }
+  }
+  if (!env.bypassGateway && !env.deeprouterApiKey) {
+    return {
+      ok: false,
+      reason: "DEEPROUTER_API_KEY is empty. Run `kids-opencode register` first, or set KIDS_LLM_BYPASS_GATEWAY=1 with a provider key for dogfood.",
+      variant: "auth_failed",
+    }
+  }
+  return { ok: true }
+}

package/src/core/events.ts

@@ -0,0 +1,168 @@
+/**
+ * SSE subscriber over `client.global.event()`.
+ *
+ * Handles:
+ * - automatic reconnect on disconnect (5s back-off, max ten retries before
+ *   surfacing serve_unreachable to the store)
+ * - dispatch of the discriminated union GlobalEvent.payload to per-type
+ *   handlers
+ * - graceful shutdown via AbortSignal
+ *
+ * The actual `client.global.event()` return shape is an async iterable
+ * of GlobalEvent. We narrow on `payload.type`. See
+ * `~/Documents/sites/kidsinai/opencode-kernel/packages/sdk/js/src/v2/types.gen.ts`
+ * for the full union.
+ */
+
+import type { OpencodeClient } from "./connection.ts"
+
+export type EventHandlers = {
+  onSessionCreated?: (e: { sessionID: string }) => void
+  onMessagePartDelta?: (e: { sessionID: string; messageID: string; partID: string; delta: string }) => void
+  onTextEnded?: (e: { sessionID: string; messageID: string }) => void
+  onPermissionAsked?: (e: { requestID: string; sessionID: string; tool?: string; metadata?: Record<string, unknown> }) => void
+  onLlmError?: (e: { message: string }) => void
+  onCompactionEnded?: () => void
+  onUnknown?: (type: string, payload: unknown) => void
+  /** Fires when the SSE loop fails too many times in a row. */
+  onDisconnected?: (reason: string) => void
+  /** Fires once when reconnected after at least one failure. */
+  onReconnected?: () => void
+}
+
+export class EventSubscriber {
+  private client: OpencodeClient
+  private handlers: EventHandlers
+  private abort: AbortController
+  private retries = 0
+  private readonly MAX_RETRIES = 10
+
+  constructor(client: OpencodeClient, handlers: EventHandlers) {
+    this.client = client
+    this.handlers = handlers
+    this.abort = new AbortController()
+  }
+
+  /** Start the subscription loop. Resolves only when the loop exits. */
+  async run(): Promise<void> {
+    while (!this.abort.signal.aborted) {
+      try {
+        await this.consume()
+        // SSE stream ended cleanly (server-side); loop reconnects.
+        await this.sleep(1000)
+      } catch (err) {
+        if (this.abort.signal.aborted) return
+        this.retries++
+        if (this.retries > this.MAX_RETRIES) {
+          this.handlers.onDisconnected?.(`event stream failed ${this.retries} times: ${stringifyErr(err)}`)
+          return
+        }
+        await this.sleep(5000)
+      }
+    }
+  }
+
+  stop(): void {
+    this.abort.abort()
+  }
+
+  private async consume(): Promise<void> {
+    // The SDK exposes the SSE stream via client.global.event(). Shape varies
+    // between SDK minor versions (some return async iterable, some a stream
+    // helper). We use the duck-typed iterable path.
+    const eventApi = (this.client as unknown as { global?: { event: () => AsyncIterable<unknown> } }).global
+    if (!eventApi || typeof eventApi.event !== "function") {
+      throw new Error("@opencode-ai/sdk/v2: client.global.event() not available — SDK version drift")
+    }
+    const stream = eventApi.event()
+    for await (const raw of stream) {
+      if (this.abort.signal.aborted) return
+      if (this.retries > 0) {
+        this.retries = 0
+        this.handlers.onReconnected?.()
+      }
+      this.dispatch(raw)
+    }
+  }
+
+  private dispatch(raw: unknown): void {
+    const env = raw as { payload?: { type?: string } & Record<string, unknown> }
+    const payload = env?.payload
+    if (!payload || typeof payload.type !== "string") return
+    const t = payload.type
+    switch (t) {
+      case "session.created":
+      case "session.next.session.created":
+        this.handlers.onSessionCreated?.({ sessionID: String(payload.sessionID ?? "") })
+        return
+      case "message.part.delta": {
+        const messageID = String(payload.messageID ?? "")
+        const partID = String(payload.partID ?? "")
+        const sessionID = String(payload.sessionID ?? "")
+        const delta = String((payload.delta as { text?: string } | undefined)?.text ?? payload.delta ?? "")
+        if (delta) this.handlers.onMessagePartDelta?.({ sessionID, messageID, partID, delta })
+        return
+      }
+      case "session.next.text.delta": {
+        const messageID = String(payload.messageID ?? "")
+        const partID = String(payload.partID ?? "stream")
+        const sessionID = String(payload.sessionID ?? "")
+        const delta = String(payload.delta ?? "")
+        if (delta) this.handlers.onMessagePartDelta?.({ sessionID, messageID, partID, delta })
+        return
+      }
+      case "session.next.text.ended": {
+        const messageID = String(payload.messageID ?? "")
+        const sessionID = String(payload.sessionID ?? "")
+        this.handlers.onTextEnded?.({ sessionID, messageID })
+        return
+      }
+      case "permission.asked":
+      case "session.next.permission.asked": {
+        const requestID = String(payload.requestID ?? payload.id ?? "")
+        const sessionID = String(payload.sessionID ?? "")
+        this.handlers.onPermissionAsked?.({
+          requestID,
+          sessionID,
+          tool: payload.tool as string | undefined,
+          metadata: payload.metadata as Record<string, unknown> | undefined,
+        })
+        return
+      }
+      case "session.error":
+      case "llm.error": {
+        const message = String((payload.error as { message?: string } | undefined)?.message ?? payload.message ?? "unknown LLM error")
+        this.handlers.onLlmError?.({ message })
+        return
+      }
+      case "session.next.compaction.ended":
+        this.handlers.onCompactionEnded?.()
+        return
+      default:
+        this.handlers.onUnknown?.(t, payload)
+    }
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => {
+      const timer = setTimeout(resolve, ms)
+      this.abort.signal.addEventListener(
+        "abort",
+        () => {
+          clearTimeout(timer)
+          resolve()
+        },
+        { once: true },
+      )
+    })
+  }
+}
+
+function stringifyErr(err: unknown): string {
+  if (err instanceof Error) return err.message
+  try {
+    return JSON.stringify(err)
+  } catch {
+    return String(err)
+  }
+}