@huynle/hub 0.10.0 → 0.11.0

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 })
@@ -656,3 +854,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

package/src/central/recording/routes.ts

@@ -2,10 +2,10 @@
 // is a console route with access "user": the user's cookie or device token only (the hub refuses session, app and
 // act tokens before these run), so no agent, not even the Concierge, can read or export a recording, and there is
 // no admin route. Every lookup is by (user.id, id); another user's, an unknown and a deleted ID answer 404 alike.
-import { RECORDING_AUDIO_TYPE, RECORDING_FEATURES, RECORDING_LIMITS, type RecordingClient } from "../../protocol"
+import { RECORDING_AUDIO_TYPE, RECORDING_FEATURES, RECORDING_LIMITS, RECORDING_REPLY_TYPE, type RecordingClient } from "../../protocol"
 import { readBounded } from "../agent/body"
 import { checkConsoleBatch } from "./schema"
-import { audioKey, blobTenant, isSegmentNumber, summaryOf, type AudioEntry } from "./store"
+import { audioKey, blobTenant, clipKey, type ExtraEntry, isSegmentNumber, replyKey, summaryOf, type AudioEntry } from "./store"
 import { exportEntries } from "./export"
 import type { RecordingService, StartInput } from "./index"
 import { zipStream } from "./zip"
@@ -169,6 +169,25 @@ export function recordingRoutes(service: RecordingService, options: { readonly v
     return n
   }
 
+  /** A clip's or reply's number: 1 to the recording's limit. */
+  const extraNumber = (raw: string | undefined, max: number, what: string): number => {
+    const n = raw && /^\d{1,6}$/.test(raw) ? Number(raw) : 0
+    if (n < 1 || n > max) throw new BadInput(`${what} must be a number 1–${max}`)
+    return n
+  }
+
+  /** GET of a stored extra (a clip or a reply's audio): owner-only, private, as a download. */
+  const extraResponse = async (userID: string, id: string, key: string, type: string, file: string): Promise<Response> => {
+    const record = await service.visible(userID, id)
+    if (!record) return notFound()
+    const entry = await service.store.indexEntry<ExtraEntry>(userID, record.id, key)
+    const blob = entry ? await service.store.blobs.get(blobTenant(userID), entry.hash) : undefined
+    if (!blob) return notFound()
+    return new Response(blob.body, {
+      headers: { ...PRIVATE, "content-type": type, "content-length": String(blob.bytes), "cross-origin-resource-policy": "same-origin", "content-disposition": `attachment; filename="${record.id}-${file}"` },
+    })
+  }
+
   return [
     route("GET", "/api/settings/recording", async ({ user }) =>
       Response.json({ settings: await service.settings.get(user.id), usage: await service.usage(user.id), limits: { retentionDays: L.retentionMs / 86_400_000, userBytes: L.userBytes, recordingBytes: L.recordingBytes } }, { headers: NO_STORE }),
@@ -176,11 +195,14 @@ export function recordingRoutes(service: RecordingService, options: { readonly v
     route("PUT", "/api/settings/recording", async ({ request, user, device }) => {
       const input = await jsonOf(request)
       if (input instanceof Response) return input
-      only(input, ["enabled", "expectedRevision"])
-      if (typeof input.enabled !== "boolean" || !Number.isSafeInteger(input.expectedRevision) || (input.expectedRevision as number) < 0) {
-        throw new BadInput("Expected {enabled: boolean, expectedRevision: number}")
+      only(input, ["enabled", "developer", "expectedRevision"])
+      const flag = (v: unknown) => v === undefined || typeof v === "boolean"
+      if (!flag(input.enabled) || !flag(input.developer) || (input.enabled === undefined && input.developer === undefined) || !Number.isSafeInteger(input.expectedRevision) || (input.expectedRevision as number) < 0) {
+        throw new BadInput("Expected {enabled?: boolean, developer?: boolean, expectedRevision: number}")
       }
-      const result = await service.setEnabled(user.id, device.id, input.enabled, input.expectedRevision as number)
+      if (input.enabled === false && input.developer === true) throw new BadInput("Developer mode needs recording on")
+      const change = { ...(input.enabled !== undefined ? { enabled: input.enabled as boolean } : {}), ...(input.developer !== undefined ? { developer: input.developer as boolean } : {}) }
+      const result = await service.setSettings(user.id, device.id, change, input.expectedRevision as number)
       if (!result.ok) return fail(409, "The setting changed meanwhile; reload it", "conflict", { currentRevision: result.currentRevision })
       return Response.json({ settings: result.settings }, { headers: NO_STORE })
     }),
@@ -199,7 +221,10 @@ export function recordingRoutes(service: RecordingService, options: { readonly v
           return fail(429, `At most ${L.recordingsStored} recordings are kept; delete some in Settings → Voice`, "limit", { limit: L.recordingsStored })
       }
       const record = started.record
-      return Response.json({ recording: summaryOf(record), audio: record.audio, hubAt: options.now(), features: [...RECORDING_FEATURES] }, { status: started.kind === "created" ? 201 : 200, headers: NO_STORE })
+      return Response.json(
+        { recording: summaryOf(record), audio: record.audio, hubAt: options.now(), features: [...RECORDING_FEATURES], ...(record.developer ? { developer: true } : {}) },
+        { status: started.kind === "created" ? 201 : 200, headers: NO_STORE },
+      )
     }),
     route("GET", "/api/recordings", async ({ url, user }) => {
       const limitRaw = url.searchParams.get("limit")
@@ -235,6 +260,7 @@ export function recordingRoutes(service: RecordingService, options: { readonly v
       return after ? Response.json({ recording: summaryOf(after) }, { headers: NO_STORE }) : notFound()
     }),
     route("POST", "/api/recordings/:id/events", async ({ request, params, user, device }) => {
+      const startedAt = options.now()
       const appendable = await service.appendable(user.id, device.id, params.id!)
       if (appendable.kind === "not_found") return notFound()
       if (appendable.kind === "ended") return fail(409, "This recording has ended", "recording_ended", { reason: appendable.reason })
@@ -244,6 +270,7 @@ export function recordingRoutes(service: RecordingService, options: { readonly v
       const checked = checkConsoleBatch(input.events)
       if (!checked.ok) return checked.limit ? fail(413, checked.problem, "limit") : fail(400, checked.problem, "invalid", checked.seq !== undefined ? { seq: checked.seq } : {})
       const appended = await service.appendConsole(user.id, appendable.record, checked.events)
+      void service.requestLine(user.id, device.id, appendable.record.id, { route: "events", method: "POST", status: appended.kind === "ok" ? 200 : appended.kind === "limit" ? 413 : 404, ms: options.now() - startedAt }).catch(() => undefined)
       if (appended.kind === "not_found") return notFound()
       if (appended.kind === "limit") return fail(413, "This recording reached its event limit and has ended", "limit")
       return Response.json({ through: appended.through, hubAt: options.now(), audio: appended.audio }, { headers: NO_STORE })
@@ -275,6 +302,33 @@ export function recordingRoutes(service: RecordingService, options: { readonly v
         headers: { ...PRIVATE, "content-type": RECORDING_AUDIO_TYPE, "content-length": String(blob.bytes), "cross-origin-resource-policy": "same-origin", "content-disposition": `attachment; filename="${record.id}-${n}.wav"` },
       })
     }),
+    // Developer mode: audio clips around near-misses and marks (uploaded by the recording's device) and reply audio.
+    route("PUT", "/api/recordings/:id/clips/:n", async ({ request, params, user, device }) => {
+      const appendable = await service.appendable(user.id, device.id, params.id!)
+      if (appendable.kind === "not_found") return notFound()
+      const n = extraNumber(params.n, service.devLimits.clipsPerRecording, "clip")
+      if (appendable.kind === "ended") return fail(409, "This recording has ended", "recording_ended", { reason: appendable.reason })
+      if (!appendable.record.developer) return fail(409, "This recording does not keep Developer mode's extras", "developer_off")
+      const type = request.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase()
+      if (type !== RECORDING_AUDIO_TYPE) return fail(415, `Clips are ${RECORDING_AUDIO_TYPE}`, "unsupported")
+      const bytes = await bytesOf(request, service.devLimits.clipBytes)
+      if (bytes instanceof Response) return bytes
+      if (!bytes.length) throw new BadInput("Empty clip")
+      const stored = await service.storeExtra(user.id, appendable.record, "clip", n, bytes)
+      if (stored.kind === "cap") return fail(413, "Developer mode's share of the storage is full: the clip is not saved", "limit")
+      if (stored.kind === "gone") return notFound()
+      if (stored.kind === "off") return fail(409, "This recording does not keep Developer mode's extras", "developer_off")
+      if (stored.kind === "failed") return fail(503, "The clip could not be stored; retry", "unavailable")
+      return Response.json({ clip: { n, bytes: stored.entry.bytes, hash: stored.entry.hash } }, { status: stored.fresh ? 201 : 200, headers: NO_STORE })
+    }),
+    route("GET", "/api/recordings/:id/clips/:n", async ({ params, user }) => {
+      const n = extraNumber(params.n, service.devLimits.clipsPerRecording, "clip")
+      return extraResponse(user.id, params.id!, clipKey(n), RECORDING_AUDIO_TYPE, `clip-${n}.wav`)
+    }),
+    route("GET", "/api/recordings/:id/replies/:n", async ({ params, user }) => {
+      const n = extraNumber(params.n, service.devLimits.repliesPerRecording, "reply")
+      return extraResponse(user.id, params.id!, replyKey(n), RECORDING_REPLY_TYPE, `reply-${n}.mp3`)
+    }),
     route("GET", "/api/recordings/:id/export", async ({ params, user }) => ((await service.visible(user.id, params.id!)) ? exportOf(user.id, params.id!) : notFound())),
     route("DELETE", "/api/recordings/:id", async ({ params, user }) => ((await service.deleteOne(user.id, params.id!)) ? new Response(null, { status: 204 }) : notFound())),
   ]

package/src/central/recording/schema.ts

@@ -32,6 +32,8 @@ const object = (fields: Fields): FieldSpec => ({ t: "object", fields })
 const L = RECORDING_LIMITS
 const ref = object({ messageID: id, ordinal: int, "seq?": int, i: int })
 const AUDIO_RESULTS = ["stored", "skipped-cap", "failed", "off"]
+/** A device label (enumerateDevices, a track's label): ✂ like any text. */
+const DEVICE_LABEL = 120
 
 /** The console kinds (REC-02 emits exactly these fields). */
 export const CONSOLE_FIELDS: Readonly<Record<ConsoleEventKind, Fields>> = {
@@ -42,13 +44,25 @@ export const CONSOLE_FIELDS: Readonly<Record<ConsoleEventKind, Fields>> = {
   "segment.closed": { segment: int, bytes: int, durationMs: num, speechMs: num, forced: bool },
   "stt.sent": { segment: int, bytes: int },
   // `text` is optional: a failed request has none (failed names why).
-  "stt.received": { segment: int, "text?": text(L.textChars), "junk?": yes, "empty?": yes, "failed?": text(L.messageChars), "audio?": oneOf(...AUDIO_RESULTS) },
+  // Feature "capture.v2" adds junkReason (junkTranscript's reason), held (the text held at that moment) and speechMs.
+  "stt.received": {
+    segment: int,
+    "text?": text(L.textChars),
+    "junk?": yes,
+    "empty?": yes,
+    "failed?": text(L.messageChars),
+    "audio?": oneOf(...AUDIO_RESULTS),
+    "junkReason?": label,
+    "held?": text(L.utteranceChars),
+    "speechMs?": num,
+  },
   "utterance.held": { text: text(L.utteranceChars) },
   "utterance.merged": { segments: list(int, 1000), pauseMs: num },
   "utterance.sent": { text: text(L.utteranceChars), segments: list(int, 1000), reason: oneOf("finished", "hold", "max", "command", "typed", "smart", "smart-fallback"), holdMs: num },
   "utterance.accepted": { inboxID: id },
   "utterance.failed": { "status?": int, message: text(L.messageChars) },
-  "utterance.command": { command: oneOf("pause", "interrupt"), text: text(L.textChars) },
+  // "mark": feature "capture.v2".
+  "utterance.command": { command: oneOf("pause", "interrupt", "mark"), text: text(L.textChars) },
   heard: { inboxID: id },
   // The contract's `seq?` (the say's seq) collides with the envelope's `seq`: a flat event carries only the latter.
   "say.received": { messageID: id, ordinal: int, chars: int, sentences: int, muted: bool },
@@ -70,6 +84,56 @@ export const CONSOLE_FIELDS: Readonly<Record<ConsoleEventKind, Fields>> = {
   "turn.timing": { "speechEnd?": num, "transcript?": num, "accepted?": num, "firstSay?": num, "firstByte?": num, firstAudio: num },
   // Feature "turn.predict" (Smart Turn): a score (none when the model failed or was slow) and what it decided.
   "turn.predict": { "p?": num, ms: num, silenceMs: num, decision: oneOf("send", "hold", "fallback", "timer-fallback"), "error?": text(L.messageChars) },
+  // Feature "capture.v2": what the detector almost took for speech, its 10 s summary, a slow STT answer, a bookmark.
+  "vad.near": {
+    ms: num,
+    "voicedMs?": num,
+    "peakProb?": num,
+    "peakDb?": num,
+    threshold: num,
+    echoGuard: bool,
+    mode: oneOf("silero", "energy"),
+    reason: oneOf("short-onset", "below-threshold", "voiced-ratio"),
+  },
+  "vad.summary": {
+    frames: int,
+    "maxProb?": num,
+    "p90Prob?": num,
+    "maxDb?": num,
+    "noiseFloorDb?": num,
+    framesAboveStart: int,
+    framesAboveSpeakingStart: int,
+    msEchoGuard: num,
+    "nearDropped?": int,
+    mode: oneOf("silero", "energy"),
+    sensitivity: oneOf("low", "normal", "high"),
+  },
+  "stt.slow": { segment: int, ms: num },
+  mark: { via: oneOf("voice", "button"), "note?": text(L.textChars) },
+  // Feature "dev.v1" (Developer mode; stored only in a developer recording, see ingest).
+  "vad.trace": {
+    reason: oneOf("speech.start", "speech.end", "vad.near"),
+    mode: oneOf("silero", "energy"),
+    frameMs: num,
+    // p100: probabilities × 100; db: dBFS, both rounded to integers. `guard`: one "0"/"1" per frame (echo guard up).
+    scale: oneOf("p100", "db"),
+    values: list(int, 128),
+    threshold: int,
+    guard: { t: "str", max: 128 },
+  },
+  "audio.clip": { clip: int, for: object({ kind: oneOf("vad.near", "mark"), seq: int }), preMs: num, postMs: num, bytes: int },
+  "device.info": {
+    reason: oneOf("start", "change"),
+    "outputs?": list(object({ kind: label, "label?": text(DEVICE_LABEL) }), 20),
+    "inputs?": list(object({ kind: label, "label?": text(DEVICE_LABEL) }), 20),
+    "track?": object({ "echoCancellation?": bool, "noiseSuppression?": bool, "autoGainControl?": bool, "sampleRate?": num, "channelCount?": num, "label?": text(DEVICE_LABEL) }),
+    "network?": object({ "effectiveType?": label, "rtt?": num, "downlink?": num, "saveData?": bool }),
+    "visibility?": label,
+    "wakeLock?": bool,
+    "battery?": object({ "level?": num, "charging?": bool }),
+  },
+  "resource.timing": { route: oneOf("transcribe", "speak", "events", "utterance", "recording"), n: int, medianMs: num, maxMs: num, "medianTtfbMs?": num, "bytes?": int },
+  "console.log": { level: oneOf("error", "warn", "unhandled"), message: text(L.messageChars), "count?": int, "source?": label },
   "decision.voice": { decisionID: id, option: id, outcome: oneOf("answered", "refused", "failed") },
   "clock.sync": { t0: num, t1: num, hubAt: num },
   error: { where: oneOf("stt", "tts", "send", "mic", "upload", "audio"), message: text(L.messageChars) },