@huynle/hub 0.10.1 → 0.11.1

package/src/central/recording/export.ts

@@ -5,7 +5,7 @@
 // entries are reached (the root manifest of "all" reads them once more beforehand).
 import { RECORDING_AUDIO_TYPE, RECORDING_FORMAT, RECORDING_FORMAT_VERSION, type RecordingEvent } from "../../protocol"
 import { clockAlignment, type ClockSample, type ClockSummary } from "./clock"
-import { type AudioEntry, blobTenant, type RecordingRecord, type RecordingStore } from "./store"
+import { type AudioEntry, blobTenant, type ExtraEntry, isPageKey, type RecordingRecord, type RecordingStore } from "./store"
 import type { ZipEntry } from "./zip"
 
 export interface ExportOptions {
@@ -31,6 +31,8 @@ export interface SegmentManifest {
 const decoder = new TextDecoder()
 const encoder = new TextEncoder()
 const audioFile = (n: number) => `audio/${String(n).padStart(6, "0")}.wav`
+const clipFile = (n: number) => `clips/${String(n).padStart(6, "0")}.wav`
+const replyFile = (n: number) => `replies/${String(n).padStart(6, "0")}.mp3`
 
 /** A hub event ID "<podTag>.<n>" as a sort key. */
 const idKey = (id: unknown): [string, number] => {
@@ -52,6 +54,9 @@ interface Loaded {
   readonly events: RecordingEvent[]
   readonly clock: ClockSummary
   readonly audio: Map<number, AudioEntry>
+  /** Developer mode: clips (k…) and reply audio (r…) by number. */
+  readonly clips: Map<number, ExtraEntry>
+  readonly replies: Map<number, ExtraEntry>
 }
 
 /** Every stored event of a recording (pages that are missing or unreadable are skipped), aligned and sorted. */
@@ -59,11 +64,16 @@ async function load(store: RecordingStore, userID: string, record: RecordingReco
   const index = await store.index<Record<string, unknown>>(userID, record.id)
   const raw: RecordingEvent[] = []
   const audio = new Map<number, AudioEntry>()
+  const clips = new Map<number, ExtraEntry>()
+  const replies = new Map<number, ExtraEntry>()
   for (const entry of index) {
     if (entry.key.startsWith("a")) {
       audio.set(Number(entry.key.slice(1)), entry.value as unknown as AudioEntry)
       continue
     }
+    if (entry.key.startsWith("k")) clips.set(Number(entry.key.slice(1)), entry.value as unknown as ExtraEntry)
+    if (entry.key.startsWith("r")) replies.set(Number(entry.key.slice(1)), entry.value as unknown as ExtraEntry)
+    if (!isPageKey(entry.key)) continue
     const hash = entry.value.hash
     if (typeof hash !== "string") continue
     const blob = await store.blobs.get(blobTenant(userID), hash).catch(() => undefined)
@@ -82,7 +92,36 @@ async function load(store: RecordingStore, userID: string, record: RecordingReco
   const clock = clockAlignment(samples, record.anchor)
   const events = raw.map((e) => ({ ...e, ts: e.src === "console" ? clock.ts(e.t ?? 0) : (e.at ?? 0) }) as RecordingEvent)
   events.sort(compare)
-  return { events, clock: clock.summary, audio }
+  return { events, clock: clock.summary, audio, clips, replies }
+}
+
+const sha = (hash: string) => hash.replace(/^sha256:/, "")
+
+/** Developer mode: clips[] joined with their audio.clip events (what each belongs to), replies[] with their ref. */
+function extras(loaded: Loaded): { clips: Record<string, unknown>[]; replies: Record<string, unknown>[] } {
+  const clipEvents = new Map<number, RecordingEvent>()
+  for (const e of loaded.events) if (e.src === "console" && e.kind === "audio.clip" && typeof e.clip === "number") clipEvents.set(e.clip, e)
+  const sentences = new Map<string, string>()
+  for (const e of loaded.events) {
+    const ref = e.ref as ExtraEntry["ref"]
+    if (e.src === "console" && e.kind === "tts.sentence.queued" && ref && typeof e.text === "string") sentences.set(`${ref.messageID}:${ref.ordinal}:${ref.seq ?? ""}:${ref.i}`, e.text)
+  }
+  const clips = [...loaded.clips].sort((a, b) => a[0] - b[0]).map(([n, entry]) => {
+    const e = clipEvents.get(n)
+    return {
+      n,
+      file: clipFile(n),
+      bytes: entry.bytes,
+      sha256: sha(entry.hash),
+      ...(e ? { for: e.for, preMs: e.preMs, postMs: e.postMs, ts: e.ts } : {}),
+    }
+  })
+  const replies = [...loaded.replies].sort((a, b) => a[0] - b[0]).map(([n, entry]) => {
+    const ref = entry.ref
+    const text = ref ? sentences.get(`${ref.messageID}:${ref.ordinal}:${ref.seq ?? ""}:${ref.i}`) : undefined
+    return { n, file: replyFile(n), bytes: entry.bytes, sha256: sha(entry.hash), ...(ref ? { ref } : {}), ...(text !== undefined ? { text } : {}), at: entry.at }
+  })
+  return { clips, replies }
 }
 
 const num = (v: unknown) => (typeof v === "number" && Number.isFinite(v) ? v : undefined)
@@ -176,7 +215,15 @@ function manifestEntry(record: RecordingRecord, loaded: Loaded): Record<string,
     clock: loaded.clock,
     audio: { format: RECORDING_AUDIO_TYPE, sampleRate: 16000, channels: 1, bitsPerSample: 16 },
     segments: list,
-    counts: { events: loaded.events.length, consoleGaps: record.consoleGaps, redactions: record.redactions, segmentsRedacted: redacted, segmentsSkipped: skipped },
+    ...(record.developer || loaded.clips.size || loaded.replies.size ? { developer: record.developer === true, ...extras(loaded) } : {}),
+    counts: {
+      events: loaded.events.length,
+      consoleGaps: record.consoleGaps,
+      redactions: record.redactions,
+      segmentsRedacted: redacted,
+      segmentsSkipped: skipped,
+      ...(loaded.clips.size || loaded.replies.size || record.developer ? { clips: loaded.clips.size, replies: loaded.replies.size } : {}),
+    },
   }
 }
 
@@ -200,6 +247,13 @@ async function* recordingEntries(store: RecordingStore, userID: string, record:
     if (!blob) continue
     yield { name: `${prefix}${audioFile(n)}`, body: async () => blob.body }
   }
+  for (const [files, name] of [[loaded.clips, clipFile], [loaded.replies, replyFile]] as const) {
+    for (const [n, extra] of [...files].sort((a, b) => a[0] - b[0])) {
+      const blob = await store.blobs.get(blobTenant(userID), extra.hash).catch(() => undefined)
+      if (!blob) continue
+      yield { name: `${prefix}${name(n)}`, body: async () => blob.body }
+    }
+  }
 }
 
 /** The zip entries of one recording (at the root) or of several (root manifest + one folder each). */

package/src/central/recording/index.ts

@@ -8,8 +8,11 @@
 // only while a recording is active for that session, only into the session owner's recordings, and never change
 // what the voice path answers (failures are logged without content or IDs).
 import { randomBytes } from "node:crypto"
+import type { TranscribeStats } from "../speech/provider"
 import {
+  DEV_LIMITS,
   RECORDING_AUDIO_TYPE,
+  RECORDING_REPLY_TYPE,
   RECORDING_HEADER,
   RECORDING_LIMITS,
   RECORDING_REF_HEADER,
@@ -29,10 +32,13 @@ import { redactCredentials } from "../profiles/content"
 import type { ConciergeCallFields } from "./concierge-taps"
 import { HubEventWriter, ingestConsole, PAGE_QUOTA_BYTES } from "./ingest"
 import { RecordingRetention } from "./retention"
-import { RecordingSettingsStore } from "./settings"
+import { RecordingSettingsStore, type SettingsChange } from "./settings"
 import {
   type AudioEntry,
   audioKey,
+  clipKey,
+  type ExtraEntry,
+  replyKey,
   ended,
   isSegmentNumber,
   newRecord,
@@ -42,7 +48,7 @@ import {
   type SpeechFacts,
   summaryOf,
 } from "./store"
-import { parseTtsRef, RegistryTaps } from "./taps"
+import { parseTtsRef, RegistryTaps, type TurnTimings } from "./taps"
 
 const L = RECORDING_LIMITS
 export const RECORDINGS_TOPIC = "recordings.changed"
@@ -82,20 +88,57 @@ export interface RecordingServiceOptions {
   readonly log?: (message: string) => void
   readonly sweepMs?: number
   readonly hubFlushMs?: number
+  /** Developer mode's limits (tests shrink them). */
+  readonly devLimits?: Partial<DevLimits>
+  /** This pod's name for request lines (Developer mode). */
+  readonly pod?: string
+  /**
+   * (Developer mode) What ran a session's turn: the model and its provider, the agent, the context size (token
+   * counts only). Asked only when a developer recording of the session is active; never text.
+   */
+  readonly turnFacts?: (userID: string, sessionID: string) => Promise<TurnFacts>
+}
+
+export interface TurnFacts {
+  readonly provider?: string
+  readonly model?: string
+  readonly variant?: string
+  readonly agent?: string
+  readonly contextTokens?: number
+  readonly contextLimit?: number
+}
+
+/** How long a turn detail waits for the session's facts before it is recorded without them. */
+export const TURN_FACTS_MS = 3000
+
+export type DevLimits = { -readonly [K in keyof typeof DEV_LIMITS]: number }
+
+/** One voice request of the user (Developer mode's request lines): what route, its status and time. Never a body. */
+export interface RequestLine {
+  readonly route: "transcribe" | "speak" | "events"
+  readonly method: string
+  readonly status: number
+  readonly ms: number
 }
 
+export type ExtraOutcome = { readonly kind: "stored"; readonly entry: ExtraEntry; readonly n: number; readonly fresh: boolean } | { readonly kind: "cap" } | { readonly kind: "gone" } | { readonly kind: "off" } | { readonly kind: "failed"; readonly cause: unknown }
+
 interface ActiveRef {
   readonly id: string
   readonly sessionID: string
   readonly kind: RecordingKind
   readonly deviceID: string
+  readonly developer?: true
 }
 
 export type AudioOutcome = { readonly kind: "stored"; readonly entry: AudioEntry; readonly fresh: boolean } | { readonly kind: "cap" } | { readonly kind: "gone" } | { readonly kind: "failed"; readonly cause: unknown }
 
 export interface TranscribeTap {
-  /** The answer's x-hub-recording-audio after STT answered (the write of a small body is done by then). */
-  finish(text: string, providerMs: number): Promise<RecordingAudioResult>
+  /**
+   * The answer's x-hub-recording-audio after STT answered (the write of a small body is done by then). `stats`: the
+   * provider's HTTP status, response bytes and time to headers, recorded in stt.result when known.
+   */
+  finish(text: string, providerMs: number, stats?: TranscribeStats): Promise<RecordingAudioResult>
 }
 
 export interface SpeakTap {
@@ -118,9 +161,11 @@ export class RecordingService {
   private readonly background = new Set<Promise<unknown>>()
   private readonly opened = new Set<string>()
   private unsubscribe?: () => Promise<void>
+  readonly devLimits: DevLimits
 
   constructor(private readonly options: RecordingServiceOptions) {
     this.now = options.now ?? Date.now
+    this.devLimits = { ...DEV_LIMITS, ...options.devLimits }
     // Unique per process: a restarted pod never reuses another's page keys.
     this.podTag = `${(options.podID ?? "hub").replace(/[^A-Za-z0-9]/g, "").slice(0, 12) || "hub"}${randomBytes(3).toString("hex")}`
     this.store = new RecordingStore(options.state, options.blobs, this.now)
@@ -139,7 +184,14 @@ export class RecordingService {
         })().catch(() => undefined),
     })
     this.retention = new RecordingRetention({ users: options.users, sweepUser: (userID) => this.sweepUser(userID), ...(options.sweepMs !== undefined ? { sweepMs: options.sweepMs } : {}), log: (m) => this.log(m) })
-    this.registryTap = new RegistryTaps({ hub: (userID, sessionID, kind, fields) => this.hub(userID, sessionID, kind, fields), mayRecord: (userID) => this.mayRecord(userID) })
+    this.registryTap = new RegistryTaps(
+      {
+        hub: (userID, sessionID, kind, fields) => this.hub(userID, sessionID, kind, fields),
+        mayRecord: (userID) => this.mayRecord(userID),
+        turnDetail: (userID, sessionID, detail) => void this.track(this.turnDetail(userID, sessionID, detail)).catch((cause) => this.log(`[hub] recording turn detail failed: ${(cause as Error).message}`)),
+      },
+      this.now,
+    )
     if (options.bus) {
       options.bus
         .subscribe(RECORDINGS_TOPIC, (message) => {
@@ -168,7 +220,7 @@ export class RecordingService {
   private async activeOf(userID: string): Promise<ActiveRef[]> {
     const cached = this.active.get(userID)
     if (cached && this.now() - cached.at < ACTIVE_TTL_MS) return cached.refs
-    const refs = (await this.store.list(userID)).filter((r) => r.state === "active").map((r) => ({ id: r.id, sessionID: r.sessionID, kind: r.kind, deviceID: r.deviceID }))
+    const refs = (await this.store.list(userID)).filter((r) => r.state === "active").map((r) => ({ id: r.id, sessionID: r.sessionID, kind: r.kind, deviceID: r.deviceID, ...(r.developer ? { developer: true as const } : {}) }))
     this.active.set(userID, { at: this.now(), refs })
     if (this.active.size > 10_000) this.active.delete(this.active.keys().next().value as string)
     return refs
@@ -214,6 +266,29 @@ export class RecordingService {
     return run
   }
 
+  /**
+   * (Developer mode) turn.detail into the session's active developer recordings: the turn's timings and what ran it
+   * (asked of the session only then, at most TURN_FACTS_MS). Only the whitelisted facts: never text.
+   */
+  private async turnDetail(userID: string, sessionID: string, detail: TurnTimings): Promise<void> {
+    if (!this.mayRecord(userID)) return
+    const refs = (await this.activeOf(userID)).filter((r) => r.sessionID === sessionID && r.developer)
+    if (!refs.length) return
+    let facts: TurnFacts = {}
+    if (this.options.turnFacts) {
+      const timeout = new Promise<TurnFacts>((resolve) => setTimeout(() => resolve({}), TURN_FACTS_MS).unref?.())
+      facts = await Promise.race([this.options.turnFacts(userID, sessionID).catch(() => ({})), timeout])
+    }
+    const at = this.now()
+    const label = (v: unknown) => (typeof v === "string" && v ? v.slice(0, 120) : undefined)
+    const count = (v: unknown) => (typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.round(v) : undefined)
+    const picked = Object.fromEntries(
+      Object.entries({ provider: label(facts.provider), model: label(facts.model), variant: label(facts.variant), agent: label(facts.agent), contextTokens: count(facts.contextTokens), contextLimit: count(facts.contextLimit) }).filter(([, v]) => v !== undefined),
+    )
+    const tools = detail.tools.map((t) => ({ callID: t.callID.slice(0, 120), ...(t.tool ? { tool: t.tool } : {}), startMs: t.startMs, ...(t.endMs !== undefined ? { endMs: t.endMs } : {}), state: t.state }))
+    for (const ref of refs) this.writer.add(userID, ref.id, "turn.detail", { outcome: detail.outcome, ms: detail.ms, ...(detail.firstTokenMs !== undefined ? { firstTokenMs: detail.firstTokenMs } : {}), ...picked, tools }, at)
+  }
+
   /** Writes every buffered hub event now. */
   async flush(): Promise<void> {
     await Promise.all([...this.tails.values()])
@@ -239,13 +314,28 @@ export class RecordingService {
     return { bytes, recordings: records.filter((r) => r.state !== "deleting").length, capBytes: L.userBytes }
   }
 
-  async setEnabled(userID: string, deviceID: string, enabled: boolean, expectedRevision: number): Promise<{ ok: true; settings: RecordingSettings } | { ok: false; currentRevision: number }> {
-    const written = await this.settings.set(userID, enabled, expectedRevision)
+  /** The setting: recording and Developer mode (developer implies enabled; see RecordingSettingsStore.set). */
+  async setSettings(userID: string, deviceID: string, change: SettingsChange, expectedRevision: number): Promise<{ ok: true; settings: RecordingSettings } | { ok: false; currentRevision: number }> {
+    const written = await this.settings.set(userID, change, expectedRevision)
     if (!written.ok) return written
+    const { enabled } = written.settings
+    const developer = written.settings.developer === true
     this.options.notify(userID, { type: "recording", settings: written.settings }, deviceID)
-    if (written.changed) {
-      await this.options.audit({ actor: userID, action: enabled ? "recording.enable" : "recording.disable" })
-      if (!enabled) for (const r of await this.store.list(userID)) if (r.state === "active") await this.endByHub(userID, r.id, "disabled")
+    if (written.changed) await this.options.audit({ actor: userID, action: enabled ? "recording.enable" : "recording.disable" })
+    if (written.developerChanged) await this.options.audit({ actor: userID, action: developer ? "recording.developer.enable" : "recording.developer.disable" })
+    if (written.changed && !enabled) for (const r of await this.store.list(userID)) if (r.state === "active") await this.endByHub(userID, r.id, "disabled")
+    // Developer mode off: the running recordings go on without their extras from now on (on: from the next start).
+    if (written.developerChanged && !developer && enabled) {
+      for (const r of await this.store.list(userID)) {
+        if (r.state !== "active" || !r.developer) continue
+        await this.store.update(userID, r.id, (current) => {
+          if (!current.developer) return undefined
+          const { developer: _off, ...rest } = current
+          return rest as RecordingRecord
+        })
+        this.changed(userID, r.sessionID)
+        this.options.notify(userID, { type: "recording", recordingID: r.id, developer: false })
+      }
     }
     return { ok: true, settings: written.settings }
   }
@@ -271,7 +361,8 @@ export class RecordingService {
   }
 
   async start(userID: string, device: { id: string; name?: string }, input: StartInput): Promise<StartResult> {
-    if (!(await this.settings.get(userID)).enabled) return { kind: "off" }
+    const setting = await this.settings.get(userID)
+    if (!setting.enabled) return { kind: "off" }
     if (!this.options.owns(userID, input.sessionID)) return { kind: "not_found" }
     const records = await this.store.list(userID)
     const same = records.find((r) => r.clientID === input.clientID && r.deviceID === device.id && r.state !== "deleting")
@@ -298,6 +389,7 @@ export class RecordingService {
         anchor: input.anchor ?? { perf: 0, epoch: at },
         audio,
         at,
+        developer: setting.developer === true,
       },
       speech,
     )
@@ -445,7 +537,7 @@ export class RecordingService {
     this.writer.add(userID, id, "stt.request", { segment: n, bytes: audio.length, format }, at)
     const model = live.stt?.model
     return {
-      finish: async (text, providerMs) => {
+      finish: async (text, providerMs, stats) => {
         // (USER CHANGE vs the contract text) A transcript matching a secret pattern: the text is scrubbed (the
         // hub record of stt.result is), the audio kept, and the segment marked redacted.
         const redacted = redactCredentials(text).kinds.length > 0
@@ -460,7 +552,7 @@ export class RecordingService {
         } catch (cause) {
           result = this.audioResult(userID, id, n, { kind: "failed", cause })
         }
-        this.writer.add(userID, id, "stt.result", { segment: n, text, providerMs, ...(model ? { model } : {}), audio: result })
+        this.writer.add(userID, id, "stt.result", { segment: n, text, providerMs, ...(model ? { model } : {}), audio: result, ...providerStats(stats) })
         return result
       },
     }
@@ -482,19 +574,34 @@ export class RecordingService {
     return "failed"
   }
 
-  /** /api/speak with x-hub-recording (and x-hub-tts-ref): tts.synth timing; the reply audio is never stored. */
+  /**
+   * /api/speak with x-hub-recording (and x-hub-tts-ref): tts.synth timing. In a developer recording (with a ref) the
+   * reply audio is also kept, as the client received it (copied while streaming, no second upload).
+   */
   async speakTap(userID: string, deviceID: string, headers: Headers, chars: number): Promise<SpeakTap | undefined> {
     const id = headers.get(RECORDING_HEADER)
     if (id === null) return undefined
     const record = await this.store.visible(userID, id).catch(() => undefined)
     if (!record || record.state !== "active" || record.deviceID !== deviceID) return undefined
     const ref = parseTtsRef(headers.get(RECORDING_REF_HEADER))
+    const keep = record.developer === true && ref !== undefined
     const started = this.now()
-    const done = (firstByteMs: number | undefined) => this.writer.add(userID, id, "tts.synth", { ...(ref ? { ref } : {}), chars, ...(firstByteMs !== undefined ? { firstByteMs } : {}), ms: this.now() - started })
+    const chunks: Uint8Array[] = []
+    let kept = 0
+    const collect = (chunk: Uint8Array) => {
+      if (!keep || kept > this.devLimits.replyBytes) return
+      kept += chunk.length
+      if (kept <= this.devLimits.replyBytes) chunks.push(chunk)
+    }
+    const done = (firstByteMs: number | undefined) => {
+      this.writer.add(userID, id, "tts.synth", { ...(ref ? { ref } : {}), chars, ...(firstByteMs !== undefined ? { firstByteMs } : {}), ms: this.now() - started })
+      if (keep) void this.track(this.keepReply(userID, id, ref!, kept > this.devLimits.replyBytes ? undefined : chunks))
+    }
     return {
       wrap: <T extends Uint8Array | ReadableStream<Uint8Array>>(audio: T): T => {
         if (audio instanceof Uint8Array) {
           const ms = this.now() - started
+          collect(audio)
           done(ms)
           return audio
         }
@@ -503,6 +610,7 @@ export class RecordingService {
           new TransformStream<Uint8Array, Uint8Array>({
             transform: (chunk, controller) => {
               first ??= this.now() - started
+              collect(chunk)
               controller.enqueue(chunk)
             },
             flush: () => done(first),
@@ -513,6 +621,96 @@ export class RecordingService {
     }
   }
 
+  /** A reply sentence's audio (Developer mode): stored under the next reply number; reply.audio says what happened. */
+  private async keepReply(userID: string, id: string, ref: NonNullable<ExtraEntry["ref"]>, chunks: Uint8Array[] | undefined): Promise<void> {
+    const bytes = chunks ? concat(chunks) : undefined
+    const record = await this.store.visible(userID, id)
+    if (!record) return
+    const outcome: ExtraOutcome = bytes?.length ? await this.storeExtra(userID, record, "reply", undefined, bytes, ref) : { kind: "cap" }
+    const audio = outcome.kind === "stored" ? "stored" : outcome.kind === "cap" ? "skipped-cap" : outcome.kind === "failed" ? "failed" : "off"
+    this.writer.add(userID, id, "reply.audio", { ref, ...(outcome.kind === "stored" ? { n: outcome.n } : {}), bytes: bytes?.length ?? 0, audio })
+  }
+
+  /**
+   * (Developer mode) Stores an audio clip (`n` from the console) or a reply's audio (the next number). Only for a
+   * developer recording; the extras' audio stops first: never past (cap − headroom) of the user's or the recording's
+   * cap, so segments keep the rest (cap.reached {what: "extras"} once).
+   */
+  async storeExtra(userID: string, record: RecordingRecord, what: "clip" | "reply", n: number | undefined, audio: Uint8Array, ref?: ExtraEntry["ref"]): Promise<ExtraOutcome> {
+    const D = this.devLimits
+    if (!record.developer) return { kind: "off" }
+    if (what === "clip" && n !== undefined) {
+      const existing = await this.store.indexEntry<ExtraEntry>(userID, record.id, clipKey(n))
+      if (existing) return { kind: "stored", entry: existing, n, fresh: false }
+    }
+    if ((await this.store.usage(userID)) + audio.length > L.userBytes - D.userHeadroomBytes) {
+      await this.extrasCap(userID, record, "user", L.userBytes - D.userHeadroomBytes)
+      return { kind: "cap" }
+    }
+    // Reserve the bytes (and a reply's number) in the record, so parallel writes never pass the limits.
+    let verdict = "gone" as "ok" | "over" | "gone" | "off"
+    let number = n ?? 0
+    await this.store.update(userID, record.id, (current) => {
+      if (current.state === "deleting") return void (verdict = "gone")
+      if (!current.developer) return void (verdict = "off")
+      const count = what === "clip" ? (current.clips ?? 0) : (current.replies ?? 0)
+      const max = what === "clip" ? D.clipsPerRecording : D.repliesPerRecording
+      if (count >= max || current.bytes + audio.length > L.recordingBytes - D.recordingHeadroomBytes) return void (verdict = "over")
+      verdict = "ok"
+      if (what === "reply") number = count + 1
+      return { ...current, bytes: current.bytes + audio.length, ...(what === "clip" ? { clips: count + 1 } : { replies: count + 1 }) }
+    })
+    if (verdict === "gone" || verdict === "off") return { kind: verdict }
+    if (verdict === "over") {
+      await this.extrasCap(userID, record, "recording", L.recordingBytes - D.recordingHeadroomBytes)
+      return { kind: "cap" }
+    }
+    const release = () =>
+      this.store.update(userID, record.id, (current) =>
+        current.state === "deleting" ? undefined : { ...current, bytes: Math.max(0, current.bytes - audio.length), ...(what === "clip" ? { clips: Math.max(0, (current.clips ?? 1) - 1) } : {}) },
+      )
+    let blob
+    try {
+      blob = await this.store.putBlob(userID, audio, what === "clip" ? RECORDING_AUDIO_TYPE : RECORDING_REPLY_TYPE, what === "clip" ? D.clipBytes : D.replyBytes, L.userBytes - D.userHeadroomBytes)
+    } catch (cause) {
+      await release()
+      if (cause instanceof BlobQuotaError) {
+        await this.extrasCap(userID, record, "user", L.userBytes - D.userHeadroomBytes)
+        return { kind: "cap" }
+      }
+      return { kind: "failed", cause }
+    }
+    const at = this.now()
+    const key = what === "clip" ? clipKey(number) : replyKey(number)
+    const entry: ExtraEntry = { hash: blob.hash, bytes: blob.bytes, at, ...(ref ? { ref } : {}) }
+    if (!(await this.store.putIndex(userID, record.id, key, entry))) {
+      await release()
+      const first = await this.store.indexEntry<ExtraEntry>(userID, record.id, key)
+      if (first?.hash !== blob.hash) await this.store.dropIfUnindexed(userID, blob.hash, at)
+      return first ? { kind: "stored", entry: first, n: number, fresh: false } : { kind: "failed", cause: new Error("extra index lost") }
+    }
+    if (await this.store.undoIfDeleted(userID, record.id, key, blob.hash)) return { kind: "gone" }
+    return { kind: "stored", entry, n: number, fresh: true }
+  }
+
+  /** cap.reached {what: "extras"} once per scope; audio (segments) goes on. */
+  private async extrasCap(userID: string, record: RecordingRecord, scope: "user" | "recording", limit: number): Promise<void> {
+    const key = `extras:${scope}`
+    const result = await this.store.update(userID, record.id, (current) => (current.capNoted.includes(key) ? undefined : { ...current, capNoted: [...current.capNoted, key] }))
+    if (result?.changed) this.writer.add(userID, record.id, "cap.reached", { what: "extras", scope, limit })
+  }
+
+  /**
+   * (Developer mode) A request line for one of the user's voice requests naming a recording (transcribe, speak:
+   * x-hub-recording; events: the path): only into an active developer recording of that device. Never a body.
+   */
+  async requestLine(userID: string, deviceID: string, recordingID: string | null | undefined, line: RequestLine): Promise<void> {
+    if (!recordingID || !this.mayRecord(userID)) return
+    const record = await this.store.visible(userID, recordingID).catch(() => undefined)
+    if (!record?.developer || record.deviceID !== deviceID || (record.state !== "active" && !(record.graceUntil !== undefined && this.now() <= record.graceUntil))) return
+    this.writer.add(userID, record.id, "request", { route: line.route, method: line.method, status: line.status, ms: Math.round(line.ms), pod: this.options.pod ?? "hub" })
+  }
+
   /** POST …/conversation: the event, and (off) the session's recordings end with a grace for the last batches. */
   async conversationChanged(userID: string, sessionID: string, on: boolean): Promise<void> {
     await this.hubNow(userID, sessionID, "conversation", { on })
@@ -537,7 +735,8 @@ export class RecordingService {
       if (this.opened.size > 2000) this.opened.delete(this.opened.values().next().value as string)
       this.hub(userID, sessionID, "decision.opened", { decisionID: decision.id, from: partyKey(from), tier: decision.tier, urgency: decision.urgency, options: decision.options.map((o) => o.id), text: decision.question })
     } else if (decision.state === "answered" && decision.answer?.answeredBy === "user") {
-      this.hub(userID, sessionID, "decision.answered", { decisionID: decision.id, ...(decision.answer.option !== undefined ? { option: decision.answer.option } : {}), via: decision.answer.via ?? "tap" })
+      const picks = decision.answer.picks && Object.entries(decision.answer.picks).map(([group, option]) => ({ group, option }))
+      this.hub(userID, sessionID, "decision.answered", { decisionID: decision.id, ...(decision.answer.option !== undefined ? { option: decision.answer.option } : {}), ...(picks ? { picks } : {}), via: decision.answer.via ?? "tap" })
     }
   }
 
@@ -656,3 +855,23 @@ export type StartResult =
   | { readonly kind: "existing" | "created"; readonly record: RecordingRecord }
 
 export { summaryOf }
+
+const concat = (chunks: readonly Uint8Array[]): Uint8Array => {
+  const out = new Uint8Array(chunks.reduce((n, c) => n + c.length, 0))
+  let at = 0
+  for (const c of chunks) {
+    out.set(c, at)
+    at += c.length
+  }
+  return out
+}
+
+/** stt.result's provider fields (capture.v2): the upstream HTTP status, response bytes and time to headers, when known. */
+function providerStats(stats: TranscribeStats | undefined): Record<string, number> {
+  const out: Record<string, number> = {}
+  const finite = (x: unknown): x is number => typeof x === "number" && Number.isFinite(x)
+  if (finite(stats?.status)) out.httpStatus = stats.status
+  if (finite(stats?.bytes)) out.responseBytes = stats.bytes
+  if (finite(stats?.headersMs)) out.headersMs = Math.round(stats.headersMs)
+  return out
+}

package/src/central/recording/ingest.ts

@@ -3,7 +3,7 @@
 // ifVersion 0 (an existing key is a page stored before a crash: treated as stored), then the record CAS-updated.
 // Hub events: buffered per pod and recording, written as pages of up to hubFlushEvents every hubFlushMs (and at
 // end and drain) under h<podTag>-<n>; a pod that dies loses at most its last hubFlushMs of hub events.
-import { type ConsoleEvent, type HubEventKind, RECORDING_LIMITS, type RecordingEvent } from "../../protocol"
+import { type ConsoleEvent, DEV_CONSOLE_KINDS, type HubEventKind, RECORDING_LIMITS, type RecordingEvent } from "../../protocol"
 import { BlobQuotaError } from "../artifacts/blob-store"
 import type { Clock, Timers } from "../backend/types"
 import { consoleRecord, hubRecord } from "./schema"
@@ -15,6 +15,7 @@ export const PAGE_QUOTA_BYTES = L.userBytes + L.activePerUser * L.eventBytesPerR
 /** Room past PAGE_QUOTA_BYTES for the end markers of a recording whose user filled the page quota. */
 export const CONTROL_HEADROOM_BYTES = 1024 * 1024
 const CONTROL_KINDS = new Set<string>(["cap.reached", "recording.ended", "error"])
+const DEV_KINDS: ReadonlySet<string> = new Set(DEV_CONSOLE_KINDS)
 /** A page is the batch plus the envelope the hub adds (≈ 50 bytes per event). */
 const PAGE_MAX_BYTES = L.batchBytes + L.eventsPerBatch * 128
 
@@ -33,7 +34,15 @@ export async function ingestConsole(store: RecordingStore, userID: string, recor
   const fresh = events.filter((e) => e.seq > record.consoleThrough)
   if (!fresh.length) return { kind: "stored", record }
   const at = now()
-  const records = fresh.map((e) => consoleRecord(e, at))
+  // Developer mode's kinds only in a developer recording (a console that has not seen it turned off yet): dropped
+  // here, their seqs still count as stored (no gap).
+  const kept = record.developer ? fresh : fresh.filter((e) => !DEV_KINDS.has(e.kind))
+  if (!kept.length) {
+    const last = fresh.at(-1)!.seq
+    const updated = await store.update(userID, record.id, (current) => (current.state === "deleting" || current.consoleThrough >= last ? undefined : { ...current, consoleThrough: last, consoleGaps: current.consoleGaps + Math.max(0, fresh[0]!.seq - (current.consoleThrough + 1)), lastEventAt: at }))
+    return updated ? { kind: "stored", record: updated.record } : { kind: "gone" }
+  }
+  const records = kept.map((e) => consoleRecord(e, at))
   const page = ndjson(records)
   if (record.events + records.length > L.eventsPerRecording || record.eventBytes + page.length > L.eventBytesPerRecording) return { kind: "limit" }
   const first = fresh[0]!.seq