@huynle/hub 0.10.1 → 0.11.0

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) },

package/src/central/recording/settings.ts

@@ -7,7 +7,15 @@ export const SETTINGS_COLLECTION = "voice-recording-settings"
 const KEY = "settings"
 export const DEFAULT_SETTINGS: RecordingSettings = { enabled: false, revision: 0 }
 
-export type SettingsWrite = { readonly ok: true; readonly settings: RecordingSettings; readonly changed: boolean } | { readonly ok: false; readonly currentRevision: number }
+export type SettingsWrite =
+  | { readonly ok: true; readonly settings: RecordingSettings; readonly changed: boolean; readonly developerChanged: boolean }
+  | { readonly ok: false; readonly currentRevision: number }
+
+/** A PUT's change: either or both (never enabled: false with developer: true, the route refuses it). */
+export interface SettingsChange {
+  readonly enabled?: boolean
+  readonly developer?: boolean
+}
 
 export class RecordingSettingsStore {
   constructor(
@@ -19,15 +27,21 @@ export class RecordingSettingsStore {
     return (await this.state.get<RecordingSettings>(userID, SETTINGS_COLLECTION, KEY))?.value ?? DEFAULT_SETTINGS
   }
 
-  /** Sets `enabled` when the stored revision is `expectedRevision`; a stale one answers the current revision. */
-  async set(userID: string, enabled: boolean, expectedRevision: number): Promise<SettingsWrite> {
+  /**
+   * Sets `enabled` and/or `developer` when the stored revision is `expectedRevision`; a stale one answers the current
+   * revision. Developer mode implies recording: developer on turns recording on, recording off turns developer off;
+   * a change of `enabled` alone (an older console) keeps developer as it is.
+   */
+  async set(userID: string, change: SettingsChange, expectedRevision: number): Promise<SettingsWrite> {
     for (let attempt = 0; attempt < 8; attempt++) {
       const stored = await this.state.get<RecordingSettings>(userID, SETTINGS_COLLECTION, KEY)
       const current = stored?.value ?? DEFAULT_SETTINGS
       if (current.revision !== expectedRevision) return { ok: false, currentRevision: current.revision }
-      const next: RecordingSettings = { enabled, revision: current.revision + 1, updatedAt: this.now() }
+      const developer = change.developer ?? (change.enabled === false ? false : current.developer === true)
+      const enabled = developer || (change.enabled ?? current.enabled)
+      const next: RecordingSettings = { enabled, ...(current.developer !== undefined || developer ? { developer } : {}), revision: current.revision + 1, updatedAt: this.now() }
       const written = await this.state.put(userID, SETTINGS_COLLECTION, KEY, next, { ifVersion: stored?.version ?? 0 })
-      if (written.ok) return { ok: true, settings: next, changed: current.enabled !== enabled }
+      if (written.ok) return { ok: true, settings: next, changed: current.enabled !== enabled, developerChanged: (current.developer === true) !== developer }
     }
     const current = await this.get(userID)
     return { ok: false, currentRevision: current.revision }

package/src/central/recording/store.ts

@@ -81,6 +81,19 @@ export interface AudioEntry {
   readonly redacted?: true
 }
 
+/** Developer mode: an audio clip (k) or a reply sentence's audio (r), numbered per recording. */
+export interface ExtraEntry {
+  readonly hash: string
+  readonly bytes: number
+  readonly at: number
+  /** Replies: the sentence's ref. */
+  readonly ref?: { readonly messageID: string; readonly ordinal: number; readonly seq?: number; readonly i: number }
+}
+export const clipKey = (n: number) => `k${String(n).padStart(6, "0")}`
+export const replyKey = (n: number) => `r${String(n).padStart(6, "0")}`
+/** Index keys of event pages (c…, h…); a… are segments, k… clips, r… reply audio. */
+export const isPageKey = (key: string) => key.startsWith("c") || key.startsWith("h")
+
 export const consoleKey = (firstSeq: number) => `c${String(firstSeq).padStart(10, "0")}`
 export const hubKey = (podTag: string, n: number) => `h${podTag}-${String(n).padStart(8, "0")}`
 export const audioKey = (n: number) => `a${String(n).padStart(6, "0")}`
@@ -116,6 +129,9 @@ export function summaryOf(r: RecordingRecord): RecordingSummary {
     events: r.events,
     audio: r.audio,
     redactions: r.redactions,
+    ...(r.developer ? { developer: true as const } : {}),
+    ...(r.clips ? { clips: r.clips } : {}),
+    ...(r.replies ? { replies: r.replies } : {}),
   }
 }
 
@@ -274,6 +290,8 @@ export interface StartFacts {
   readonly anchor: RecordingAnchor
   readonly audio: boolean
   readonly at: number
+  /** Developer mode was on at start. */
+  readonly developer?: boolean
 }
 
 export function newRecord(facts: StartFacts, speech: SpeechFacts): RecordingRecord {
@@ -303,6 +321,7 @@ export function newRecord(facts: StartFacts, speech: SpeechFacts): RecordingReco
     lastEventAt: facts.at,
     capNoted: [],
     skipped: { cap: 0, failed: 0 },
+    ...(facts.developer ? { developer: true as const } : {}),
     ...speech,
   }
 }

package/src/central/recording/taps.ts

@@ -10,6 +10,25 @@ export interface TapSink {
   hub(userID: string, sessionID: string, kind: HubEventKind, fields: Record<string, unknown>): void
   /** False when the user surely has no active recording (a fresh, empty cache); true when unsure. */
   mayRecord(userID: string): boolean
+  /** (Developer mode) A turn ended: its timings, for the session's developer recordings (turn.detail). */
+  turnDetail?(userID: string, sessionID: string, detail: TurnTimings): void
+}
+
+/** A turn's timings (ms from its start), for Developer mode's turn.detail. Tool names only, never their input. */
+export interface TurnTimings {
+  readonly outcome: "succeeded" | "failed" | "interrupted"
+  readonly ms: number
+  readonly firstTokenMs?: number
+  readonly tools: ReadonlyArray<{ readonly callID: string; readonly tool?: string; readonly startMs: number; readonly endMs?: number; readonly state: "called" | "success" | "failed" }>
+}
+
+/** Tool calls kept per turn in turn.detail. */
+const TURN_TOOLS_MAX = 50
+
+interface TurnTrack {
+  readonly at: number
+  firstTokenMs?: number
+  readonly tools: Map<string, { callID: string; tool?: string; startMs: number; endMs?: number; state: "called" | "success" | "failed" }>
 }
 
 const OUTCOMES: Record<string, "succeeded" | "failed" | "interrupted"> = {
@@ -34,8 +53,16 @@ export class RegistryTaps implements RecordingTap {
   private readonly firstToken = new Set<string>()
   /** Tool names by call ID (session.tool.input.started carries the name, the later events do not). */
   private readonly tools = new Map<string, string>()
+  /** (Developer mode) The running turn of each root session: its start, first token and tool calls. */
+  private readonly turns = new Map<string, TurnTrack>()
+  private readonly now: () => number
 
-  constructor(private readonly sink: TapSink) {}
+  constructor(
+    private readonly sink: TapSink,
+    now: () => number = Date.now,
+  ) {
+    this.now = now
+  }
 
   wants(tenant: string, sessionID: string, type: string): boolean {
     if (type === "session.text.delta") return this.firstToken.has(sessionID) && this.sink.mayRecord(tenant)
@@ -47,6 +74,7 @@ export class RegistryTaps implements RecordingTap {
     if (type === "session.execution.started") {
       this.firstToken.add(sessionID)
       if (this.firstToken.size > 1000) this.firstToken.delete(this.firstToken.values().next().value as string)
+      if (this.sink.turnDetail) remember(this.turns, sessionID, { at: this.now(), tools: new Map() })
       this.sink.hub(tenant, sessionID, "turn.started", {})
       return
     }
@@ -54,10 +82,17 @@ export class RegistryTaps implements RecordingTap {
     if (outcome) {
       this.firstToken.delete(sessionID)
       this.sink.hub(tenant, sessionID, "turn.ended", { outcome })
+      const track = this.turns.get(sessionID)
+      if (track) {
+        this.turns.delete(sessionID)
+        this.sink.turnDetail?.(tenant, sessionID, { outcome, ms: this.now() - track.at, ...(track.firstTokenMs !== undefined ? { firstTokenMs: track.firstTokenMs } : {}), tools: [...track.tools.values()] })
+      }
       return
     }
     if (type === "session.text.delta") {
       if (!this.firstToken.delete(sessionID)) return
+      const track = this.turns.get(sessionID)
+      if (track) track.firstTokenMs = this.now() - track.at
       const { assistantMessageID: messageID, ordinal } = data
       this.sink.hub(tenant, sessionID, "first.token", { ...(typeof messageID === "string" ? { messageID } : {}), ...(typeof ordinal === "number" ? { ordinal } : {}) })
       return
@@ -71,6 +106,15 @@ export class RegistryTaps implements RecordingTap {
     if (!state || !callID) return
     const tool = this.tools.get(callID)
     if (state !== "called") this.tools.delete(callID)
+    const track = this.turns.get(sessionID)
+    if (track) {
+      const ms = this.now() - track.at
+      const call = track.tools.get(callID)
+      if (call) {
+        call.state = state
+        if (state !== "called") call.endMs = ms
+      } else if (track.tools.size < TURN_TOOLS_MAX) track.tools.set(callID, { callID, ...(tool ? { tool } : {}), startMs: ms, ...(state !== "called" ? { endMs: ms } : {}), state })
+    }
     // The summary only (summarizeToolInput on the spoke): never the input itself, never the output or error.
     const summary = state === "called" && typeof data.summary === "string" ? data.summary : undefined
     this.sink.hub(tenant, sessionID, "tool", { callID, ...(tool ? { tool } : {}), ...(summary !== undefined ? { summary } : {}), state })

package/src/central/speech/openai.ts

@@ -1,7 +1,7 @@
 // OpenAI-compatible speech endpoints (OpenAI, Groq, local whisper/kokoro servers, ...):
 // STT as multipart POST {baseURL}/audio/transcriptions (file, model, language?), TTS as
 // POST {baseURL}/audio/speech {model, input, voice, response_format: "mp3", speed?}.
-import { audioBody, audioMime, collect, SpeechError, transcriptText, upstreamDetail, wantsVerbose, withSpeedRetry, withVerboseRetry, type SpeechProvider } from "./provider"
+import { audioBody, audioMime, collect, SpeechError, timedTranscription, transcriptText, upstreamDetail, wantsVerbose, withSpeedRetry, withVerboseRetry, type SpeechProvider, type TranscribeStats } from "./provider"
 
 export interface OpenAICompatibleOptions {
   /** Base URL including the version path, e.g. https://api.openai.com/v1 (no trailing slash). */
@@ -25,7 +25,7 @@ export class OpenAICompatible implements SpeechProvider {
     this.verbose = wantsVerbose(options.sttModel)
   }
 
-  async transcribe(audio: Uint8Array, format: string, signal?: AbortSignal): Promise<string> {
+  async transcribe(audio: Uint8Array, format: string, signal?: AbortSignal, stats?: TranscribeStats): Promise<string> {
     const headers = await this.headers()
     const send = (verbose: boolean) => {
       const form = new FormData()
@@ -36,9 +36,9 @@ export class OpenAICompatible implements SpeechProvider {
       if (verbose) form.append("response_format", "verbose_json")
       return this.fetch(`${this.options.baseURL}/audio/transcriptions`, { method: "POST", headers, body: form, signal })
     }
-    const response = await withVerboseRetry(send, this.verbose, () => (this.verbose = false))
+    const { response, json } = await timedTranscription(() => withVerboseRetry(send, this.verbose, () => (this.verbose = false)), stats)
     if (!response.ok) throw await failure("transcription", response)
-    return transcriptText(await response.json())
+    return transcriptText(await json())
   }
 
   async speak(text: string, speed?: number, signal?: AbortSignal): Promise<Uint8Array<ArrayBuffer>> {

package/src/central/speech/openrouter.ts

@@ -1,6 +1,6 @@
 // OpenRouter speech-to-text (/audio/transcriptions as OpenAI-style multipart: the audio goes up as binary,
 // not as base64 JSON, a third smaller and no encoding) and text-to-speech (/audio/speech).
-import { audioBody, audioMime, collect, SpeechError, transcriptText, upstreamDetail, wantsVerbose, withSpeedRetry, withVerboseRetry, type SpeechProvider } from "./provider"
+import { audioBody, audioMime, collect, SpeechError, timedTranscription, transcriptText, upstreamDetail, wantsVerbose, withSpeedRetry, withVerboseRetry, type SpeechProvider, type TranscribeStats } from "./provider"
 
 export const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
 
@@ -33,7 +33,7 @@ export class OpenRouter implements SpeechProvider {
     this.verbose = wantsVerbose(options.sttModel)
   }
 
-  async transcribe(audio: Uint8Array, format: string, signal?: AbortSignal): Promise<string> {
+  async transcribe(audio: Uint8Array, format: string, signal?: AbortSignal, stats?: TranscribeStats): Promise<string> {
     const { sttModel: model, language } = this.options
     // OpenRouter documents multipart file/model/language (up to 25 MB; an utterance is at most ~2 MB of WAV), and
     // response_format verbose_json (segments with Whisper's no_speech_prob) for OpenAI-compatible providers.
@@ -45,9 +45,9 @@ export class OpenRouter implements SpeechProvider {
       if (verbose) form.append("response_format", "verbose_json")
       return this.post("/audio/transcriptions", form, signal)
     }
-    const response = await withVerboseRetry(send, this.verbose, () => (this.verbose = false))
+    const { response, json } = await timedTranscription(() => withVerboseRetry(send, this.verbose, () => (this.verbose = false)), stats)
     if (!response.ok) throw await failure("transcription", response)
-    return transcriptText(await response.json())
+    return transcriptText(await json())
   }
 
   async speak(text: string, speed?: number, signal?: AbortSignal): Promise<Uint8Array<ArrayBuffer>> {

package/src/central/speech/provider.ts

@@ -1,15 +1,46 @@
 // Speech provider interface shared by OpenRouter and OpenAI-compatible endpoints, the typed upstream
 // error (mapped to 502 by the hub), audio format detection, and the speed-retry rule.
 
+/**
+ * (Recording) What a transcription's upstream request looked like, filled in by the provider when asked: the HTTP
+ * status, the response's bytes and the time to its headers (ms, from the first request: a verbose retry included).
+ */
+export interface TranscribeStats {
+  status?: number
+  bytes?: number
+  headersMs?: number
+}
+
 /** Speech-to-text and text-to-speech against one configured provider. */
 export interface SpeechProvider {
-  transcribe(audio: Uint8Array, format: string, signal?: AbortSignal): Promise<string>
+  transcribe(audio: Uint8Array, format: string, signal?: AbortSignal, stats?: TranscribeStats): Promise<string>
   /** MP3 audio. `speed` is optional; providers that reject it get one retry without it. */
   speak(text: string, speed?: number, signal?: AbortSignal): Promise<Uint8Array<ArrayBuffer>>
   /** The same MP3 as a stream, passed through as the provider sends it (errors are thrown before any byte). */
   speakStream(text: string, speed?: number, signal?: AbortSignal): Promise<ReadableStream<Uint8Array>>
 }
 
+/**
+ * Sends a transcription (`send`, with its retries) noting the status and the time to the headers in `stats`, then
+ * reads the JSON body noting its size. A failed status is returned as is (the caller turns it into its error).
+ */
+export async function timedTranscription(send: () => Promise<Response>, stats: TranscribeStats | undefined): Promise<{ response: Response; json: () => Promise<unknown> }> {
+  const started = performance.now()
+  const response = await send()
+  if (stats) {
+    stats.status = response.status
+    stats.headersMs = Math.round(performance.now() - started)
+  }
+  return {
+    response,
+    json: async () => {
+      const raw = new Uint8Array(await response.arrayBuffer())
+      if (stats) stats.bytes = raw.byteLength
+      return JSON.parse(new TextDecoder().decode(raw))
+    },
+  }
+}
+
 /** A successful upstream response's body (an empty stream when it has none). */
 export function audioBody(response: Response): ReadableStream<Uint8Array> {
   return response.body ?? new ReadableStream({ start: (controller) => controller.close() })

package/src/central/speech/service.ts

@@ -3,7 +3,7 @@
 import { OpenAICompatible } from "./openai"
 import { OpenRouter } from "./openrouter"
 import { speechModelList, withCurrent, type SpeechModelInfo, type SpeechModelList } from "./models"
-import { SpeechError, upstreamDetail, type SpeechProvider } from "./provider"
+import { SpeechError, upstreamDetail, type SpeechProvider, type TranscribeStats } from "./provider"
 import {
   lowerLayers,
   resolveStt,
@@ -34,7 +34,8 @@ export interface SpeechSettingsStore {
 
 /** Speech for one scope: a user (their settings over the default) or, without a user, the server default. */
 export interface ScopedSpeech {
-  transcribe(audio: Uint8Array, format: string): Promise<string>
+  /** `stats`: the upstream request's status, bytes and time to headers (recording mode). */
+  transcribe(audio: Uint8Array, format: string, stats?: TranscribeStats): Promise<string>
   speak(text: string): Promise<Uint8Array<ArrayBuffer>>
   /** The audio as the provider streams it; `signal` aborts the upstream request (the phone moved on). */
   speakStream(text: string, signal?: AbortSignal): Promise<ReadableStream<Uint8Array>>
@@ -94,14 +95,14 @@ export class SpeechService {
   /** Speech with a user's effective settings (undefined: the server default). */
   forUser(userID: string | undefined): ScopedSpeech {
     return {
-      transcribe: (audio, format) => this.transcribe(audio, format, undefined, userID),
+      transcribe: (audio, format, stats) => this.transcribe(audio, format, undefined, userID, stats),
       speak: (text) => this.speak(text, undefined, userID),
       speakStream: (text, signal) => this.speakStream(text, signal, userID),
     }
   }
 
-  transcribe(audio: Uint8Array, format: string, signal?: AbortSignal, userID?: string): Promise<string> {
-    return this.provider("stt", userID).transcribe(audio, format, signal)
+  transcribe(audio: Uint8Array, format: string, signal?: AbortSignal, userID?: string, stats?: TranscribeStats): Promise<string> {
+    return this.provider("stt", userID).transcribe(audio, format, signal, stats)
   }
 
   speak(text: string, signal?: AbortSignal, userID?: string): Promise<Uint8Array<ArrayBuffer>> {

package/src/central/teams/hop-stalls.ts

@@ -0,0 +1,72 @@
+// One persistent hop-cap stall per team. A reservation prevents simultaneous sends from opening two Decisions.
+import type { StateStore } from "../backend/types"
+import { updateVersioned } from "../agent/versioned"
+
+export const TEAM_HOP_STALLS = "team-hop-stalls"
+/** A hub that crashed after reserving, but before opening its Decision, may retry after this long. */
+export const TEAM_HOP_CLAIM_STALE_MS = 5 * 60_000
+
+interface Stall {
+  readonly sender: string
+  readonly recipient: string
+  readonly limit: number
+  readonly decisionID?: string
+  readonly at: number
+}
+
+export class TeamHopStalls {
+  constructor(private readonly deps: {
+    readonly state: StateStore
+    readonly seats: (userID: string, teamID: string) => Promise<readonly string[]>
+    readonly open: (userID: string, teamID: string, sender: string, recipient: string, limit: number) => Promise<string>
+    readonly notice?: (userID: string, teamID: string, decisionID: string) => Promise<void>
+    readonly close?: (userID: string, decisionID: string) => Promise<void>
+    readonly reset: (userID: string, sessionID: string) => Promise<void>
+    readonly now?: () => number
+  }) {}
+
+  async hit(userID: string, teamID: string, sender: string, recipient: string, limit: number): Promise<boolean> {
+    const previous = await this.deps.state.get<Stall>(userID, TEAM_HOP_STALLS, teamID)
+    if (previous && previous.value.decisionID === undefined && (this.deps.now ?? Date.now)() - previous.value.at >= TEAM_HOP_CLAIM_STALE_MS) {
+      // CAS: never erase an open Decision or a replacement claim made by another caller.
+      await this.deps.state.delete(userID, TEAM_HOP_STALLS, teamID, { ifVersion: previous.version })
+    }
+    const claimed = await this.deps.state.put<Stall>(userID, TEAM_HOP_STALLS, teamID, { sender, recipient, limit, at: (this.deps.now ?? Date.now)() }, { ifVersion: 0 })
+    if (!claimed.ok) return false
+    try {
+      const decisionID = await this.deps.open(userID, teamID, sender, recipient, limit)
+      await updateVersioned<Stall>(this.deps.state, userID, TEAM_HOP_STALLS, teamID, (current) => current?.sender === sender && current.recipient === recipient && current.decisionID === undefined ? { ...current, decisionID } : undefined)
+      try {
+        await this.deps.notice?.(userID, teamID, decisionID)
+      } catch (cause) {
+        // The Decision was opened and persisted; never erase it because a spoke refused a quiet notice.
+        console.error(`[hub] team hop-cap entry notice failed: ${cause instanceof Error ? cause.message : String(cause)}`)
+      }
+      return true
+    } catch (cause) {
+      await this.deps.state.delete(userID, TEAM_HOP_STALLS, teamID, { ifVersion: claimed.version })
+      throw cause
+    }
+  }
+
+  async stalled(userID: string, teamID: string, sessionID: string): Promise<(Stall & { readonly decisionID: string }) | undefined> {
+    const stall = (await this.deps.state.get<Stall>(userID, TEAM_HOP_STALLS, teamID))?.value
+    if (!stall?.decisionID || stall.recipient !== sessionID) return undefined
+    return stall as Stall & { readonly decisionID: string }
+  }
+
+  async renew(userID: string, teamID: string, decisionID: string): Promise<void> {
+    const entry = await this.deps.state.get<Stall>(userID, TEAM_HOP_STALLS, teamID)
+    if (!entry || entry.value.decisionID !== decisionID) throw new Error("No matching team hop-cap Decision")
+    for (const sessionID of new Set(await this.deps.seats(userID, teamID))) await this.deps.reset(userID, sessionID)
+    await this.deps.state.delete(userID, TEAM_HOP_STALLS, teamID, { ifVersion: entry.version })
+  }
+
+  async clearForHuman(userID: string, sessionID: string): Promise<void> {
+    for (const { key, value, version } of await this.deps.state.list<Stall>(userID, TEAM_HOP_STALLS)) {
+      if (value.recipient !== sessionID && value.sender !== sessionID) continue
+      if (!(await this.deps.state.delete(userID, TEAM_HOP_STALLS, key, { ifVersion: version })).ok) continue
+      if (value.decisionID) await this.deps.close?.(userID, value.decisionID)
+    }
+  }
+}

package/src/central/teams/policy.ts

@@ -109,6 +109,16 @@ const sessionParty = (entry: DirectoryEntry): Party => ({ kind: "session", sessi
 export class TeamPolicy {
   constructor(private readonly deps: TeamPolicyDeps) {}
 
+  /** Shared active seat(s) only; cross-team and non-team sends use the global limit. */
+  async hopContext(userID: string, from: Party, to: Party, explicitTeamID?: string): Promise<{ teamID: string; limit?: number } | undefined> {
+    if (from.kind !== "session" || to.kind !== "session") return undefined
+    const ctx = await this.context(userID, [from.sessionID, to.sessionID])
+    const shared = seatsIn(ctx, from.sessionID).map((s) => s.teamID).filter((id) => (explicitTeamID === undefined || explicitTeamID === id) && seatsIn(ctx, to.sessionID).some((s) => s.teamID === id) && ctx.teams.get(id)?.state === "active").sort()
+    const teamID = shared[0]
+    if (!teamID) return undefined
+    return { teamID, ...(ctx.teams.get(teamID)?.hopLimit !== undefined ? { limit: ctx.teams.get(teamID)!.hopLimit } : {}) }
+  }
+
   /** Starts a send from `from` to `addr` (see the header). */
   async prepare(userID: string, from: Party, addr: string): Promise<TeamSend> {
     const resolved = await this.resolve(userID, from, addr)