@kidsinai/kids-client 0.0.17 → 0.0.19

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@kidsinai/kids-client",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "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",
@@ -24,7 +24,8 @@
   "files": ["src", "bin", "README.md", "LICENSE"],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "bun test"
+    "test": "bun test",
+    "voice-demo": "bun src/voice-demo.tsx"
   },
   "peerDependencies": {
     "@opencode-ai/sdk": ">=1.14.0"
@@ -34,7 +35,7 @@
     "ink-spinner": "^5.0.0",
     "ink-text-input": "^6.0.0",
     "react": "^18.3.1",
-    "@kidsinai/kids-opencode-plugin": "^0.0.17"
+    "@kidsinai/kids-opencode-plugin": "^0.0.19"
   },
   "devDependencies": {
     "@opencode-ai/sdk": "^1.14.51",

package/src/core/commands.ts

@@ -0,0 +1,105 @@
+/**
+ * Kid-safe slash-command registry.
+ *
+ * kids-client is a custom minimal TUI (not opencode's native one), so it grows
+ * its OWN command set rather than exposing opencode's full palette. This module
+ * is pure metadata + parsing — the actual effects live in index.tsx's prompt
+ * dispatcher (it needs the store / session / client). Keeping it pure makes the
+ * list unit-testable and lets MissionScreen render live suggestions.
+ *
+ * Deliberately EXCLUDED for kid-safety: /share (public links), /editor &
+ * drop-to-shell, external @-mentions, arbitrary config edits. The server-side
+ * tool whitelist (kids-plugin system prompt) blocks the dangerous primitives
+ * anyway; we just don't surface the affordances.
+ */
+
+export type Locale = "zh-Hans" | "en"
+
+export interface KidCommand {
+  id: string
+  /** Primary slash form, e.g. "/model". */
+  slash: string
+  /** Extra accepted spellings, e.g. ["/models"]. */
+  aliases?: string[]
+  label: { en: string; zh: string }
+  hint: { en: string; zh: string }
+}
+
+/** Order here is the order shown in the suggestion list / /help. */
+export const COMMANDS: KidCommand[] = [
+  { id: "help", slash: "/help", aliases: ["/?", "/commands"],
+    label: { en: "Help", zh: "帮助" },
+    hint: { en: "Show what you can type", zh: "看看能输入哪些命令" } },
+  { id: "model", slash: "/model", aliases: ["/models"],
+    label: { en: "Pick AI model", zh: "选 AI 模型" },
+    hint: { en: "Choose which AI helps you", zh: "换一个帮你的 AI 模型" } },
+  { id: "sessions", slash: "/sessions", aliases: ["/history", "/chats"],
+    label: { en: "Past chats", zh: "历史对话" },
+    hint: { en: "Open an earlier conversation", zh: "打开之前的对话" } },
+  { id: "new", slash: "/new",
+    label: { en: "New chat", zh: "开新对话" },
+    hint: { en: "Start a fresh conversation", zh: "清空，开始一段新的对话" } },
+  { id: "check", slash: "/check", aliases: ["/done"],
+    label: { en: "Check my work", zh: "验收作品" },
+    hint: { en: "See if you finished the mission", zh: "看看这一关完成没有" } },
+  { id: "clear", slash: "/clear",
+    label: { en: "Clear screen", zh: "清屏" },
+    hint: { en: "Clear the chat (your files stay)", zh: "清空聊天记录（文件不动）" } },
+  { id: "menu", slash: "/menu", aliases: ["/home"],
+    label: { en: "Main menu", zh: "主菜单" },
+    hint: { en: "Back to the start screen", zh: "回到开始界面" } },
+  { id: "quit", slash: "/quit", aliases: ["/exit"],
+    label: { en: "Quit", zh: "退出" },
+    hint: { en: "Close Kids OpenCode", zh: "关闭 Kids OpenCode" } },
+]
+
+export interface ParsedCommand {
+  /** The slash token as typed, lowercased, incl. leading "/", e.g. "/model". */
+  name: string
+  /** Everything after the command word, trimmed (may be ""). */
+  args: string
+}
+
+/** Parse a slash command line. Returns null if `text` isn't a `/command`. */
+export function parseSlash(text: string): ParsedCommand | null {
+  const t = text.trim()
+  if (!t.startsWith("/")) return null
+  const space = t.indexOf(" ")
+  if (space === -1) return { name: t.toLowerCase(), args: "" }
+  return { name: t.slice(0, space).toLowerCase(), args: t.slice(space + 1).trim() }
+}
+
+/** Resolve a parsed command name (e.g. "/models") to its KidCommand. */
+export function matchCommand(name: string): KidCommand | null {
+  const n = name.toLowerCase()
+  for (const c of COMMANDS) {
+    if (c.slash === n) return c
+    if (c.aliases?.includes(n)) return c
+  }
+  return null
+}
+
+/**
+ * Commands matching a draft query (the text the kid has typed so far,
+ * including the leading "/"). "/" alone returns everything. Matches against
+ * slash, aliases, id, and both labels so "/mod" or "/模型"-style typing finds
+ * the model command.
+ */
+export function filterCommands(query: string): KidCommand[] {
+  const q = query.trim().toLowerCase()
+  if (q === "" || q === "/") return COMMANDS
+  return COMMANDS.filter((c) => {
+    const hay = [c.slash, ...(c.aliases ?? []), c.id, c.label.en, c.label.zh]
+      .join(" ")
+      .toLowerCase()
+    return hay.includes(q.replace(/^\//, ""))
+  })
+}
+
+export function commandLabel(c: KidCommand, locale: Locale): string {
+  return locale === "zh-Hans" ? c.label.zh : c.label.en
+}
+
+export function commandHint(c: KidCommand, locale: Locale): string {
+  return locale === "zh-Hans" ? c.hint.zh : c.hint.en
+}

package/src/core/events.ts

@@ -94,63 +94,85 @@ export class EventSubscriber {
   }
 
   private dispatch(raw: unknown): void {
-    // Across SDK versions an event is either:
-    //   • { payload: { type, …fields } }            (older shape)
-    //   • { type, …fields }                          (newer shape — yielded
-    //                                                  directly by the
-    //                                                  AsyncGenerator)
-    //   • { data: { type, …fields } } (StreamEvent wrapper from some helpers)
-    // Unwrap to a single `payload` view so the switch below stays the same.
+    // The SDK shape evolved over the 1.14.x line. Yielded events arrive as:
+    //   • { payload: { type, properties: { … } } }   (current — 1.14.51 GlobalEvent)
+    //   • { payload: { type, …flatfields } }         (older — flat fields on payload)
+    //   • { type, properties: { … } }                (some intermediate releases)
+    //   • { type, …flatfields }                      (oldest)
+    //   • { data: { type, …. } }                     (StreamEvent helper wrapper)
+    //
+    // CRITICAL: the current 1.14.51 GlobalEvent puts event fields
+    // (sessionID, messageID, delta, …) under .payload.properties, NOT
+    // directly on .payload. The previous code read .payload.sessionID
+    // (always undefined), so deltas were silently dropped and the
+    // "thinking" indicator never cleared. This split + the
+    // `props ?? payload` fallback handle both layouts uniformly.
     const e = raw as { payload?: Record<string, unknown>; data?: Record<string, unknown>; type?: string } & Record<string, unknown>
-    const payload: ({ type?: string } & Record<string, unknown>) | null =
-      (e?.payload && typeof e.payload === "object") ? (e.payload as { type?: string } & Record<string, unknown>)
-      : (e?.data && typeof e.data === "object" && typeof (e.data as { type?: unknown }).type === "string") ? (e.data as { type?: string } & Record<string, unknown>)
-      : (typeof e?.type === "string") ? (e as { type?: string } & Record<string, unknown>)
+    const payload: ({ type?: string; properties?: Record<string, unknown> } & Record<string, unknown>) | null =
+      (e?.payload && typeof e.payload === "object") ? (e.payload as { type?: string; properties?: Record<string, unknown> } & Record<string, unknown>)
+      : (e?.data && typeof e.data === "object" && typeof (e.data as { type?: unknown }).type === "string") ? (e.data as { type?: string; properties?: Record<string, unknown> } & Record<string, unknown>)
+      : (typeof e?.type === "string") ? (e as { type?: string; properties?: Record<string, unknown> } & Record<string, unknown>)
       : null
     if (!payload || typeof payload.type !== "string") return
-    const t = payload.type
+    let t = payload.type
+    // Where the actual event fields live: `.properties` (Event* legacy shape)
+    // OR `.data` (SyncEvent* shape) OR flat on payload (oldest).
+    let props: Record<string, unknown> = (payload.properties && typeof payload.properties === "object")
+      ? payload.properties as Record<string, unknown>
+      : payload
+    // 1.14.51 Sync events: type="sync", real event name in .name with a
+    // version suffix like ".1", fields under .data. Without this normalize,
+    // our switch never matches and streaming text events drop on the floor
+    // (kid sees "thinking..." forever).
+    if (t === "sync" && typeof (payload as { name?: unknown }).name === "string") {
+      t = String((payload as { name: string }).name).replace(/\.\d+$/, "")
+      const dataField = (payload as { data?: unknown }).data
+      if (dataField && typeof dataField === "object") {
+        props = dataField as Record<string, unknown>
+      }
+    }
     switch (t) {
       case "session.created":
       case "session.next.session.created":
-        this.handlers.onSessionCreated?.({ sessionID: String(payload.sessionID ?? "") })
+        this.handlers.onSessionCreated?.({ sessionID: String(props.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 ?? "")
+        const messageID = String(props.messageID ?? "")
+        const partID = String(props.partID ?? "")
+        const sessionID = String(props.sessionID ?? "")
+        const delta = String((props.delta as { text?: string } | undefined)?.text ?? props.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 ?? "")
+        const messageID = String(props.messageID ?? "")
+        const partID = String(props.partID ?? "stream")
+        const sessionID = String(props.sessionID ?? "")
+        const delta = String(props.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 ?? "")
+        const messageID = String(props.messageID ?? "")
+        const sessionID = String(props.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 ?? "")
+        const requestID = String(props.requestID ?? props.id ?? "")
+        const sessionID = String(props.sessionID ?? "")
         this.handlers.onPermissionAsked?.({
           requestID,
           sessionID,
-          tool: payload.tool as string | undefined,
-          metadata: payload.metadata as Record<string, unknown> | undefined,
+          tool: props.tool as string | undefined,
+          metadata: props.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")
+        const message = String((props.error as { message?: string } | undefined)?.message ?? props.message ?? "unknown LLM error")
         this.handlers.onLlmError?.({ message })
         return
       }

package/src/core/models.ts

@@ -0,0 +1,66 @@
+/**
+ * Flatten the server's provider/model list into kid-friendly choices for the
+ * `/model` picker. Duck-typed and defensive: opencode's provider list shape has
+ * shifted across versions and a missing/!errored endpoint must degrade to an
+ * empty list (the picker shows a friendly "no models" note) rather than crash.
+ */
+
+import type { OpencodeClient } from "./connection.ts"
+import type { ModelChoice } from "./store.ts"
+
+const MAX_MODELS = 40
+
+export async function listModels(client: OpencodeClient): Promise<ModelChoice[]> {
+  const api = client as unknown as {
+    provider?: { list?: () => Promise<unknown> }
+    config?: { providers?: () => Promise<unknown> }
+  }
+  let raw: unknown
+  try {
+    if (typeof api.provider?.list === "function") raw = await api.provider.list()
+    else if (typeof api.config?.providers === "function") raw = await api.config.providers()
+    else return []
+  } catch {
+    return []
+  }
+  return flattenModels(raw).slice(0, MAX_MODELS)
+}
+
+export function flattenModels(raw: unknown): ModelChoice[] {
+  const providers = pickProviders(raw)
+  const out: ModelChoice[] = []
+  const seen = new Set<string>()
+  for (const p of providers) {
+    const prov = p as { id?: string; name?: string; models?: unknown }
+    const pid = prov.id ?? ""
+    const pname = prov.name ?? pid
+    for (const m of pickModels(prov.models)) {
+      const mod = m as { id?: string; name?: string }
+      const mid = mod.id ?? ""
+      if (!pid || !mid) continue
+      const fullId = `${pid}/${mid}`
+      if (seen.has(fullId)) continue
+      seen.add(fullId)
+      const mname = mod.name ?? mid
+      out.push({ id: fullId, label: pname ? `${mname} · ${pname}` : mname })
+    }
+  }
+  return out
+}
+
+function pickProviders(raw: unknown): unknown[] {
+  if (Array.isArray(raw)) return raw
+  if (raw && typeof raw === "object") {
+    const o = raw as { providers?: unknown; data?: { providers?: unknown } }
+    if (Array.isArray(o.providers)) return o.providers
+    if (Array.isArray(o.data?.providers)) return o.data!.providers as unknown[]
+  }
+  return []
+}
+
+function pickModels(models: unknown): unknown[] {
+  if (Array.isArray(models)) return models
+  // Most shapes use a Record<modelId, Model> map.
+  if (models && typeof models === "object") return Object.values(models)
+  return []
+}

package/src/core/session.ts

@@ -10,6 +10,7 @@
  */
 
 import type { OpencodeClient } from "./connection.ts"
+import type { SessionSummary } from "./store.ts"
 
 export class SessionManager {
   private client: OpencodeClient
@@ -23,6 +24,31 @@ export class SessionManager {
     return this.currentSessionId
   }
 
+  /** Forget the current session so the next prompt() opens a fresh one. */
+  reset(): void {
+    this.currentSessionId = null
+  }
+
+  /** List past sessions (for the `/sessions` picker). Newest-ish first. */
+  async list(): Promise<SessionSummary[]> {
+    const api = (this.client as unknown as { session?: { list?: () => Promise<unknown> } }).session
+    if (!api?.list) return []
+    const raw = await api.list()
+    const arr = unwrapArray(raw)
+    return arr
+      .map((s) => {
+        const o = s as { id?: string; title?: string }
+        if (!o?.id) return null
+        return { id: o.id, title: (o.title ?? "").trim() || o.id }
+      })
+      .filter((s): s is SessionSummary => s !== null)
+  }
+
+  /** Continue an existing session: subsequent prompt()s append to it. */
+  switchTo(sessionID: string): void {
+    this.currentSessionId = sessionID
+  }
+
   async create(): Promise<string> {
     const api = (this.client as unknown as { session?: { create: (input?: unknown) => Promise<{ data?: { id?: string } } | { id?: string } | string> } }).session
     if (!api?.create) throw new Error("SDK v2: client.session.create unavailable")
@@ -61,3 +87,13 @@ function extractId(result: unknown): string | null {
   }
   return null
 }
+
+/** SDK list responses come back as `T[]` or `{ data: T[] }` across versions. */
+function unwrapArray(result: unknown): unknown[] {
+  if (Array.isArray(result)) return result
+  if (result && typeof result === "object") {
+    const d = (result as { data?: unknown }).data
+    if (Array.isArray(d)) return d
+  }
+  return []
+}

package/src/core/store.ts

@@ -24,8 +24,27 @@ export type Screen =
       completionMessage: string
       hasNextMission: boolean
     }
+  // Server-backed pickers, reachable via the `/model` and `/sessions` slash
+  // commands. They carry their fetched list so the router stays a pure
+  // function of state. `returnTo` is the screen to restore on cancel/select.
+  | { kind: "model_picker"; models: ModelChoice[]; returnTo: Screen }
+  | { kind: "session_list"; sessions: SessionSummary[]; returnTo: Screen }
   | { kind: "error"; variant: ErrorVariant; detail?: string }
 
+/** A selectable AI model, flattened from the server's provider list. */
+export interface ModelChoice {
+  /** Full id passed to session.prompt, e.g. "anthropic/claude-3-5-sonnet". */
+  id: string
+  /** Kid-friendly display label. */
+  label: string
+}
+
+/** A past session, from session.list(). */
+export interface SessionSummary {
+  id: string
+  title: string
+}
+
 export type ErrorVariant =
   | "serve_unreachable"
   | "port_taken"
@@ -86,6 +105,10 @@ export interface KidsClientState {
   toast: ToastState | null
   /** Plugin emitted audit events kept for parent dashboard sync (capped). */
   auditBuffer: unknown[]
+  /** Model id chosen via `/model`; null → server default. Passed to prompt(). */
+  selectedModel: string | null
+  /** Kid-friendly label of selectedModel, for display in the header/toast. */
+  selectedModelLabel: string | null
 }
 
 type Listener = (state: KidsClientState) => void
@@ -107,6 +130,8 @@ const INITIAL: KidsClientState = {
   missionTotal: null,
   toast: null,
   auditBuffer: [],
+  selectedModel: null,
+  selectedModelLabel: null,
 }
 
 const AUDIT_BUFFER_CAP = 500

package/src/core/voice/controller.ts

@@ -0,0 +1,116 @@
+/**
+ * Voice controller — wires the parts into one "voice engine" the UI drives:
+ *
+ *   spacebar ─▶ start() ─▶ recorder captures, feedLevel() streams energy
+ *                            │
+ *                   VAD says stop (silence/maxlen) ──▶ stop()
+ *                            │
+ *                   recorder → AudioClip → STT → text ──▶ onTranscript(text)
+ *                                                          (UI calls session.prompt)
+ *
+ * Deliberately owns NO timers and does NO spawning itself — the recorder
+ * produces level events, the UI/recorder calls feedLevel(), and this class
+ * only advances the state machine and decides start/stop/cancel. That keeps
+ * it pure enough to unit-test the whole orchestration with a mock recorder +
+ * MockStt, no microphone or clock required.
+ */
+
+import { transition, type VoiceState } from "./state.ts"
+import { shouldAutoStop, DEFAULT_VAD, type VadOptions } from "./vad.ts"
+import type { AudioClip, SttAdapter } from "./stt.ts"
+
+/** Minimal recorder surface the controller needs (Recorder implements it; tests mock it). */
+export interface RecorderLike {
+  start(): void
+  stop(): Promise<AudioClip>
+  cancel(): Promise<void>
+}
+
+export interface VoiceControllerEvents {
+  /** Every state change — UI re-renders mic indicator / meter / spinner. */
+  onState?: (state: VoiceState) => void
+  /** Latest mic energy 0..1 — UI draws the meter. */
+  onLevel?: (level: number) => void
+  /** STT produced text — UI sends it via session.prompt and echoes it. */
+  onTranscript?: (text: string) => void
+  /** Recording/STT failed — UI shows a gentle retry hint. */
+  onError?: (err: Error) => void
+}
+
+export class VoiceController {
+  private state: VoiceState = "idle"
+  private levels: number[] = []
+
+  constructor(
+    private recorder: RecorderLike,
+    private stt: SttAdapter,
+    private events: VoiceControllerEvents = {},
+    private vad: VadOptions = DEFAULT_VAD,
+  ) {}
+
+  getState(): VoiceState {
+    return this.state
+  }
+
+  private set(next: VoiceState): void {
+    if (next === this.state) return
+    this.state = next
+    this.events.onState?.(next)
+  }
+
+  /** Spacebar while idle. Opens the mic. No-op if not idle. */
+  start(): void {
+    if (this.state !== "idle") return
+    this.levels = []
+    this.set(transition(this.state, { type: "START" }))
+    this.recorder.start()
+  }
+
+  /**
+   * Feed one energy sample (the recorder calls this ~every sampleIntervalMs).
+   * Updates the meter and, once VAD says so, auto-stops — so the kid only ever
+   * pressed the spacebar once. No-op unless we're listening.
+   */
+  feedLevel(level: number): void {
+    if (this.state !== "listening") return
+    this.levels.push(level)
+    this.events.onLevel?.(level)
+    if (shouldAutoStop(this.levels, this.vad) !== "continue") {
+      void this.stop()
+    }
+  }
+
+  /** Spacebar/Enter again, or VAD auto-stop. Ends capture, runs STT, emits text. */
+  async stop(): Promise<void> {
+    if (this.state !== "listening") return
+    this.set(transition(this.state, { type: "STOP" })) // → transcribing
+    try {
+      const clip = await this.recorder.stop()
+      const { text } = await this.stt.transcribe(clip)
+      this.set(transition(this.state, { type: "TRANSCRIBED" })) // → thinking
+      this.events.onTranscript?.(text)
+    } catch (err) {
+      this.set(transition(this.state, { type: "ERROR" }))
+      this.events.onError?.(err instanceof Error ? err : new Error(String(err)))
+    }
+  }
+
+  /** Esc. Throws the clip away with no send. Safe from any cancellable state. */
+  async cancel(): Promise<void> {
+    if (this.state === "listening") {
+      await this.recorder.cancel()
+    }
+    this.set(transition(this.state, { type: "CANCEL" }))
+  }
+
+  /** UI signals the LLM reply landed (and TTS, if any, finished). */
+  replied(): void {
+    this.set(transition(this.state, { type: "REPLIED" }))
+  }
+  spoken(): void {
+    this.set(transition(this.state, { type: "SPOKEN" }))
+  }
+  reset(): void {
+    this.set(transition(this.state, { type: "RESET" }))
+  }
+}

package/src/core/voice/recorder.ts

@@ -0,0 +1,114 @@
+/**
+ * Microphone capture (side-effecting; the pure bits are extracted for tests).
+ *
+ * Strategy: shell out to a system recorder (sox `rec` or ffmpeg) writing a wav,
+ * same spawn pattern as core/serve-manager.ts. We also read the PCM stream to
+ * compute a rolling RMS energy level so the UI can draw a live mic meter and
+ * the VAD can auto-stop — terminals can't show a waveform any other way.
+ *
+ * No recorder on PATH must NOT crash the client: detectRecorder() returns null
+ * and the controller can fall back to a simulated level source (demo mode),
+ * so a kid on a box without sox still sees the flow, just with canned audio.
+ */
+
+import { spawn, type Subprocess } from "bun"
+import type { AudioClip } from "./stt.ts"
+
+export type RecorderKind = "sox" | "ffmpeg"
+
+export interface RecordCommand {
+  cmd: string[]
+  /** Path the recorder writes the clip to. */
+  outPath: string
+  mimeType: string
+}
+
+/**
+ * Build the capture command for a recorder. Pure → unit-testable. 16kHz mono
+ * wav is the Whisper-friendly sweet spot (small upload, plenty for speech).
+ */
+export function buildRecordCommand(kind: RecorderKind, outPath: string): RecordCommand {
+  if (kind === "sox") {
+    // `rec` is sox's record front-end. -q quiet, -c 1 mono, -r 16000 rate.
+    return { cmd: ["rec", "-q", "-c", "1", "-r", "16000", outPath], outPath, mimeType: "audio/wav" }
+  }
+  // ffmpeg: -f avfoundation on macOS captures the default mic (":0").
+  return {
+    cmd: ["ffmpeg", "-loglevel", "quiet", "-f", "avfoundation", "-i", ":0", "-ac", "1", "-ar", "16000", "-y", outPath],
+    outPath,
+    mimeType: "audio/wav",
+  }
+}
+
+/**
+ * Compute normalised RMS energy (0..1) from a chunk of signed 16-bit PCM.
+ * Pure → unit-testable; this is what drives both the meter and the VAD.
+ */
+export function computeRms(pcm16: Int16Array): number {
+  if (pcm16.length === 0) return 0
+  let sumSq = 0
+  for (let i = 0; i < pcm16.length; i++) {
+    const s = pcm16[i]! / 32768 // normalise to -1..1
+    sumSq += s * s
+  }
+  return Math.sqrt(sumSq / pcm16.length)
+}
+
+/** Probe PATH for a usable recorder. Returns null if none — caller degrades to
+ *  demo mode rather than crashing. */
+export async function detectRecorder(): Promise<RecorderKind | null> {
+  for (const kind of ["sox", "ffmpeg"] as const) {
+    const bin = kind === "sox" ? "rec" : "ffmpeg"
+    try {
+      const proc = spawn({ cmd: ["which", bin], stdout: "pipe", stderr: "ignore" })
+      await proc.exited
+      if (proc.exitCode === 0) return kind
+    } catch {
+      /* keep probing */
+    }
+  }
+  return null
+}
+
+export interface RecorderEvents {
+  /** Fired ~every sampleIntervalMs with the latest normalised energy 0..1. */
+  onLevel?: (level: number) => void
+}
+
+/**
+ * Owns one recording. start() spawns the recorder; stop() ends it and reads
+ * the written wav back as an AudioClip; cancel() kills it and discards.
+ */
+export class Recorder {
+  private child: Subprocess | null = null
+  private cmd: RecordCommand
+
+  constructor(kind: RecorderKind, outPath: string, private _events: RecorderEvents = {}) {
+    this.cmd = buildRecordCommand(kind, outPath)
+  }
+
+  start(): void {
+    if (this.child) return
+    this.child = spawn({ cmd: this.cmd.cmd, stdout: "ignore", stderr: "ignore" })
+  }
+
+  /** Stop recording and return the captured clip. */
+  async stop(): Promise<AudioClip> {
+    await this.kill()
+    const bytes = new Uint8Array(await Bun.file(this.cmd.outPath).arrayBuffer())
+    return { bytes, mimeType: this.cmd.mimeType }
+  }
+
+  /** Abort and discard — no clip, no STT, no send. */
+  async cancel(): Promise<void> {
+    await this.kill()
+  }
+
+  private async kill(): Promise<void> {
+    if (this.child && !this.child.killed) {
+      this.child.kill()
+      await this.child.exited
+    }
+    this.child = null
+  }
+}