@huynle/hub 0.8.2 → 0.8.3

package/src/central/recording/concierge-taps.ts

@@ -0,0 +1,104 @@
+// REC-01 Concierge taps (contract: Event schema → Hub): `concierge.tool` for every agent-route call of the user's
+// recorded Concierge session (method, route pattern, target, status, ms: never a request body, never a response),
+// and `wake.arrived` when the notifier's send to the Concierge succeeded (the rendered batch: hub-written IDs,
+// enums and counts only). Both are best effort and never change what the route or the send answers.
+import { AGENT_ERROR_STATUS, AgentError } from "../agent/errors"
+import type { AgentContext, AgentRoute } from "../agent/routes"
+
+export interface ConciergeCallFields {
+  readonly verb?: string
+  readonly method: string
+  readonly route: string
+  readonly target?: string
+  readonly status: number
+  readonly ms: number
+}
+
+export interface ConciergeCallRecorder {
+  /** A session actor's agent call (the recorder keeps it only for a recorded Concierge session). */
+  call(userID: string, sessionID: string, fields: ConciergeCallFields): void
+}
+
+/** The hub verb a route maps to: its last literal path segment (board, decisions, proposals, approve, …). */
+export function conciergeKind(path: string): string | undefined {
+  const literal = path.split("/").filter((s) => s && !s.startsWith(":"))
+  const last = literal.at(-1)
+  return last && last !== "agent" && last !== "api" ? last : undefined
+}
+
+const TARGET_PARAMS = ["addr", "id", "form", "staffing"] as const
+
+/** Wraps every route: session-actor calls are reported to the recorder after they answer (or throw). */
+export function recordConciergeCalls(routes: readonly AgentRoute[], recorder: ConciergeCallRecorder, now: () => number = Date.now): AgentRoute[] {
+  return routes.map((route) => ({
+    ...route,
+    handle: async (context: AgentContext) => {
+      if (context.actor.kind !== "session") return route.handle(context)
+      const started = now()
+      let status = 500
+      try {
+        const response = await route.handle(context)
+        status = response.status
+        return response
+      } catch (cause) {
+        status = cause instanceof AgentError ? (AGENT_ERROR_STATUS[cause.code] ?? 500) : 500
+        throw cause
+      } finally {
+        try {
+          const target = TARGET_PARAMS.map((p) => context.params[p]).find((v) => typeof v === "string" && v.length > 0)
+          const verb = conciergeKind(route.path)
+          recorder.call(context.user.id, (context.actor as { sessionID: string }).sessionID, {
+            ...(verb ? { verb } : {}),
+            method: route.method,
+            route: route.path,
+            ...(target ? { target: target.slice(0, 300) } : {}),
+            status,
+            ms: now() - started,
+          })
+        } catch {
+          // best effort
+        }
+      }
+    },
+  }))
+}
+
+export interface ConciergeBatchFacts {
+  readonly id: string
+  readonly kind: string
+  readonly budget?: string
+  readonly lines: number
+}
+
+export type ConciergeSend = (userID: string, text: string, options: { readonly wake: boolean; readonly urgent?: boolean; readonly batch?: ConciergeBatchFacts }) => Promise<{ readonly messageID: string; readonly woke?: boolean }>
+
+export interface WakeRecorder {
+  /** The user's current Concierge session (the send's recipient). */
+  current(userID: string): Promise<string | undefined>
+  wake(userID: string, sessionID: string, fields: Record<string, unknown>): void
+}
+
+/** The batch facts from the rendered text when the sender did not pass them ("Concierge update b7 …"). */
+function factsOf(text: string): ConciergeBatchFacts {
+  const head = text.split("\n", 1)[0] ?? ""
+  const id = /\bb(\d+)\b/.exec(head)?.[0] ?? "b?"
+  const kind = head.startsWith("Concierge digest") ? "digest" : head.includes("quiet hours ended") ? "release" : head.includes("changes were missed") ? "snapshot" : "update"
+  return { id, kind, lines: Math.max(0, text.split("\n").length - 2) }
+}
+
+/** Wraps the Concierge ports' send: a successful send is recorded as wake.arrived (a refused one is not). */
+export function wrapConciergeSend(send: ConciergeSend, recorder: WakeRecorder): ConciergeSend {
+  return async (userID, text, options) => {
+    const result = await send(userID, text, options)
+    try {
+      const sessionID = await recorder.current(userID)
+      if (sessionID !== undefined) {
+        const facts = options.batch ?? factsOf(text)
+        recorder.wake(userID, sessionID, { batchID: facts.id, batchKind: facts.kind, ...(facts.budget !== undefined ? { budget: facts.budget } : {}), wake: options.wake, lines: facts.lines, text })
+      }
+    } catch {
+      // best effort: the send succeeded either way
+    }
+    return result
+  }
+}

package/src/central/recording/export.ts

@@ -0,0 +1,215 @@
+// REC-01 export (contract: List, read, export, delete → Export; docs/voice-recording.md). One recording: at the
+// zip's root `manifest.json`, `events.jsonl` (both sources merged, sorted by ts, then src (hub first), then
+// seq/id), `audio/<n 6 digits>.wav` (exactly as sent to STT). All: a root manifest.json of every recording plus one
+// folder `<id>/` per recording with the same three entries. Streamed: each recording's pages are read when its
+// 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 { ZipEntry } from "./zip"
+
+export interface ExportOptions {
+  readonly version: string
+  readonly now: () => number
+}
+
+export interface SegmentManifest {
+  readonly n: number
+  readonly file?: string
+  readonly bytes?: number
+  readonly sha256?: string
+  readonly durationMs?: number
+  readonly speechMs?: number
+  readonly forced?: boolean
+  readonly startTs?: number
+  readonly endTs?: number
+  readonly text?: string
+  readonly audio: string
+  readonly redacted?: true
+}
+
+const decoder = new TextDecoder()
+const encoder = new TextEncoder()
+const audioFile = (n: number) => `audio/${String(n).padStart(6, "0")}.wav`
+
+/** A hub event ID "<podTag>.<n>" as a sort key. */
+const idKey = (id: unknown): [string, number] => {
+  const text = typeof id === "string" ? id : ""
+  const dot = text.lastIndexOf(".")
+  return [text.slice(0, dot), Number(text.slice(dot + 1)) || 0]
+}
+
+function compare(a: RecordingEvent, b: RecordingEvent): number {
+  if (a.ts! !== b.ts!) return a.ts! - b.ts!
+  if (a.src !== b.src) return a.src === "hub" ? -1 : 1
+  if (a.src === "console") return (a.seq ?? 0) - (b.seq ?? 0)
+  const [ta, na] = idKey(a.id)
+  const [tb, nb] = idKey(b.id)
+  return ta < tb ? -1 : ta > tb ? 1 : na - nb
+}
+
+interface Loaded {
+  readonly events: RecordingEvent[]
+  readonly clock: ClockSummary
+  readonly audio: Map<number, AudioEntry>
+}
+
+/** Every stored event of a recording (pages that are missing or unreadable are skipped), aligned and sorted. */
+async function load(store: RecordingStore, userID: string, record: RecordingRecord): Promise<Loaded> {
+  const index = await store.index<Record<string, unknown>>(userID, record.id)
+  const raw: RecordingEvent[] = []
+  const audio = new Map<number, AudioEntry>()
+  for (const entry of index) {
+    if (entry.key.startsWith("a")) {
+      audio.set(Number(entry.key.slice(1)), entry.value as unknown as AudioEntry)
+      continue
+    }
+    const hash = entry.value.hash
+    if (typeof hash !== "string") continue
+    const blob = await store.blobs.get(blobTenant(userID), hash).catch(() => undefined)
+    if (!blob) continue
+    const text = decoder.decode(new Uint8Array(await new Response(blob.body).arrayBuffer()))
+    for (const line of text.split("\n")) {
+      if (!line) continue
+      try {
+        raw.push(JSON.parse(line) as RecordingEvent)
+      } catch {
+        // a damaged line is skipped
+      }
+    }
+  }
+  const samples: ClockSample[] = raw.filter((e) => e.src === "console" && e.kind === "clock.sync").map((e) => ({ t0: e.t0 as number, t1: e.t1 as number, hubAt: e.hubAt as number }))
+  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 }
+}
+
+const num = (v: unknown) => (typeof v === "number" && Number.isFinite(v) ? v : undefined)
+
+/** segments[]: the index joined with segment.closed, speech.end (aligned window), stt.result / stt.received. */
+function segments(loaded: Loaded): SegmentManifest[] {
+  const out = new Map<number, Record<string, unknown>>()
+  const at = (n: unknown) => {
+    if (typeof n !== "number" || !Number.isSafeInteger(n)) return undefined
+    let s = out.get(n)
+    if (!s) out.set(n, (s = { n }))
+    return s
+  }
+  for (const e of loaded.events) {
+    if (e.kind === "segment.closed" && e.src === "console") {
+      const s = at(e.segment)
+      if (!s) continue
+      s.durationMs ??= num(e.durationMs)
+      s.speechMs ??= num(e.speechMs)
+      if (typeof e.forced === "boolean") s.forced ??= e.forced
+      s.closedBytes ??= num(e.bytes)
+    } else if (e.kind === "speech.end" && e.src === "console") {
+      const s = at(e.segment)
+      if (!s) continue
+      s.endTs = e.ts
+      s.windowMs = num(e.durationMs)
+      s.durationMs ??= num(e.durationMs)
+      s.speechMs ??= num(e.speechMs)
+      if (typeof e.forced === "boolean") s.forced ??= e.forced
+    } else if (e.kind === "stt.result" && e.src === "hub") {
+      const s = at(e.segment)
+      if (!s) continue
+      if (typeof e.text === "string") s.text = e.text
+      if (typeof e.audio === "string") s.result = e.audio
+      if (e.redacted?.length) s.redacted = true
+    } else if (e.kind === "stt.received" && e.src === "console") {
+      const s = at(e.segment)
+      if (!s) continue
+      if (typeof e.text === "string") s.text ??= e.text
+      if (typeof e.audio === "string") s.received ??= e.audio
+    }
+  }
+  for (const n of loaded.audio.keys()) at(n)
+  return [...out.values()]
+    .sort((a, b) => (a.n as number) - (b.n as number))
+    .map((s) => {
+      const n = s.n as number
+      const stored = loaded.audio.get(n)
+      const result = (s.result ?? s.received) as string | undefined
+      const audio = stored ? "stored" : result === "stored" || result === undefined ? (result === undefined ? "off" : "failed") : result
+      const window = (s.windowMs ?? s.durationMs) as number | undefined
+      const endTs = s.endTs as number | undefined
+      return {
+        n,
+        ...(stored ? { file: audioFile(n), bytes: stored.bytes, sha256: stored.hash.replace(/^sha256:/, "") } : {}),
+        ...(s.durationMs !== undefined ? { durationMs: s.durationMs as number } : stored?.durationMs !== undefined ? { durationMs: stored.durationMs } : {}),
+        ...(s.speechMs !== undefined ? { speechMs: s.speechMs as number } : {}),
+        ...(s.forced !== undefined ? { forced: s.forced as boolean } : {}),
+        ...(endTs !== undefined && window !== undefined ? { startTs: Math.round((endTs - window) * 10) / 10 } : {}),
+        ...(endTs !== undefined ? { endTs } : {}),
+        ...(typeof s.text === "string" ? { text: s.text } : {}),
+        audio,
+        ...(s.redacted || stored?.redacted ? { redacted: true as const } : {}),
+      }
+    })
+}
+
+function manifestEntry(record: RecordingRecord, loaded: Loaded): Record<string, unknown> {
+  const list = segments(loaded)
+  const skipped = { cap: 0, failed: 0 }
+  let redacted = 0
+  for (const s of list) {
+    if (s.audio === "skipped-cap") skipped.cap++
+    else if (s.audio === "failed") skipped.failed++
+    if (s.redacted) redacted++
+  }
+  return {
+    id: record.id,
+    kind: record.kind,
+    sessionID: record.sessionID,
+    ...(record.sessionTitle !== undefined ? { sessionTitle: record.sessionTitle } : {}),
+    device: { id: record.deviceID, ...(record.deviceName !== undefined ? { name: record.deviceName } : {}) },
+    state: record.state,
+    startedAt: record.startedAt,
+    ...(record.endedAt !== undefined ? { endedAt: record.endedAt } : {}),
+    ...(record.endReason !== undefined ? { endReason: record.endReason } : {}),
+    expiresAt: record.expiresAt,
+    client: record.client,
+    ...(record.stt ? { stt: record.stt } : {}),
+    ...(record.tts ? { tts: record.tts } : {}),
+    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 },
+  }
+}
+
+const manifest = (entries: Record<string, unknown>[], records: readonly RecordingRecord[], options: ExportOptions) =>
+  encoder.encode(
+    `${JSON.stringify(
+      { format: RECORDING_FORMAT, version: RECORDING_FORMAT_VERSION, exportedAt: options.now(), hub: { version: options.version }, partial: records.some((r) => r.state === "active"), recordings: entries },
+      null,
+      2,
+    )}\n`,
+  )
+
+/** The three entries of one recording, under `prefix` ("" or "<id>/"). */
+async function* recordingEntries(store: RecordingStore, userID: string, record: RecordingRecord, prefix: string, options: ExportOptions): AsyncGenerator<ZipEntry> {
+  const loaded = await load(store, userID, record)
+  const entry = manifestEntry(record, loaded)
+  yield { name: `${prefix}manifest.json`, body: async () => manifest([entry], [record], options) }
+  yield { name: `${prefix}events.jsonl`, body: async () => encoder.encode(loaded.events.map((e) => JSON.stringify(e)).join("\n") + (loaded.events.length ? "\n" : "")) }
+  for (const [n, audio] of [...loaded.audio].sort((a, b) => a[0] - b[0])) {
+    const blob = await store.blobs.get(blobTenant(userID), audio.hash).catch(() => undefined)
+    if (!blob) continue
+    yield { name: `${prefix}${audioFile(n)}`, body: async () => blob.body }
+  }
+}
+
+/** The zip entries of one recording (at the root) or of several (root manifest + one folder each). */
+export async function* exportEntries(store: RecordingStore, userID: string, records: readonly RecordingRecord[], single: boolean, options: ExportOptions): AsyncGenerator<ZipEntry> {
+  if (single) {
+    yield* recordingEntries(store, userID, records[0]!, "", options)
+    return
+  }
+  const entries: Record<string, unknown>[] = []
+  for (const record of records) entries.push(manifestEntry(record, await load(store, userID, record)))
+  yield { name: "manifest.json", body: async () => manifest(entries, records, options) }
+  for (const record of records) yield* recordingEntries(store, userID, record, `${record.id}/`, options)
+}