@huynle/hub 0.10.0 → 0.11.0

package/src/central/http.ts

@@ -8,7 +8,7 @@ import { diskAssets, type WebAssets } from "./assets"
 import path from "node:path"
 import { promisify } from "node:util"
 import { brotliCompress, constants as zlib, gzip } from "node:zlib"
-import { CONNECT_PATHS, formAnswerProblem, isDeliverResult, isPreviewPath, parseMediaAllowlist, parseMediaRef, PREVIEW_BUNDLE_LIMITS, NOT_A_USER_MESSAGE, RECORDING_AUDIO_RESULT_HEADER, REVERT_BUSY, REVERT_END_BUSY, PROMPT_IMAGE_MIMES, WORKSPACE_LIMITS, promptImagesProblem, redactEmbeddedMedia, type AvailableModel, type CoreOp, type EnrollStart, type FormAnswer, type ModelSelection, type PermissionDecision, type PromptImage, type ResultFor, type SessionModelPrefs } from "../protocol"
+import { CONNECT_PATHS, formAnswerProblem, isDeliverResult, isPreviewPath, parseMediaAllowlist, parseMediaRef, PREVIEW_BUNDLE_LIMITS, NOT_A_USER_MESSAGE, RECORDING_AUDIO_RESULT_HEADER, RECORDING_HEADER, REVERT_BUSY, REVERT_END_BUSY, PROMPT_IMAGE_MIMES, WORKSPACE_LIMITS, promptImagesProblem, redactEmbeddedMedia, type AvailableModel, type CoreOp, type EnrollStart, type FormAnswer, type ModelSelection, type PermissionDecision, type PromptImage, type ResultFor, type SessionModelPrefs, type SessionSummary } from "../protocol"
 import { isLoopbackAddress, isLoopbackHost, isLoopbackURL, loopbackOrigins } from "../loopback"
 import { speakable } from "../speakable"
 import { Auth, RateLimitError, ValidationError } from "./auth"
@@ -60,7 +60,7 @@ import { BusyError, Registry, RELAY_REASON, RelayRefused, type Timers } from "./
 import { RELAY_REASON_CONFIRMED, relayMessage, relayQuestionProblem, STATUS_QUESTION_SOFT_REFUSAL } from "./front-relays"
 import { createActions, type Unsupported, unsupportedMessage } from "./actions"
 import { IntentRetention, SessionIntents, withPromptIntents } from "./agent/intents"
-import { audioFormat, SpeechError } from "./speech/provider"
+import { audioFormat, SpeechError, type TranscribeStats } from "./speech/provider"
 import { SpeechService } from "./speech/service"
 import { NodeRegistry } from "./nodes"
 import { ConnDirectory } from "./cluster/directory"
@@ -85,7 +85,7 @@ import { coordinatorActor, SupervisorCoordinator } from "./workspaces/coordinato
 import { artifactJournalEvent } from "./artifacts/events"
 import { ArtifactMaintenance } from "./artifacts/maintenance"
 import { MemoryBlobStore } from "./backend/memory-blobs"
-import { RecordingService } from "./recording"
+import { RecordingService, type DevLimits } from "./recording"
 import { recordingRoutes } from "./recording/routes"
 import { wrapConciergeSend } from "./recording/concierge-taps"
 import { ARTIFACT_UPLOAD_LIMITS } from "./artifacts/routes"
@@ -100,6 +100,7 @@ import { teamDeniedEvent, TeamPolicy } from "./teams/policy"
 import { TeamSeatStore } from "./teams/seats"
 import { TeamStaffingService } from "./teams/staffing"
 import { intakeActor, TeamIntakeService } from "./teams/intake"
+import { TeamHopStalls } from "./teams/hop-stalls"
 import { TeamStore } from "./teams/store"
 import { ActivityTracker } from "./concierge/activity"
 import { HumanActivity, withHumanActivity } from "./human-activity"
@@ -137,7 +138,8 @@ import { ACTIVITY_INTERVAL_MAX, ACTIVITY_INTERVAL_MIN, LOCAL_USER, PUSH_PREF_KEY
 const HUMAN_ACTIVITY_STOP_MS = 3_000
 
 export interface Speech {
-  transcribe(audio: Uint8Array, format: string): Promise<string>
+  /** `stats` (recording mode): the provider fills in its upstream request's status, bytes and time to headers. */
+  transcribe(audio: Uint8Array, format: string, stats?: TranscribeStats): Promise<string>
   speak(text: string): Promise<Uint8Array<ArrayBuffer>>
   /** Streams the audio as it is synthesized (the built-in providers do; an override may only buffer). */
   speakStream?(text: string, signal?: AbortSignal): Promise<ReadableStream<Uint8Array>>
@@ -149,6 +151,8 @@ export interface CentralOptions {
   readonly previewRetention?: { readonly archiveAfterMs?: number; readonly purgeAfterMs?: number }
   /** The registry's timers (tests: a fake clock for its delayed checks); real timers by default. */
   readonly registryTimers?: Timers
+  /** Developer mode's recording limits (tests shrink them; default DEV_LIMITS). */
+  readonly recordingDevLimits?: Partial<DevLimits>
   /** The built web app (web/dist, see web/vite.config.ts) on disk; or pass `web` (e.g. files embedded in a compiled binary). */
   readonly webDir?: string
   readonly web?: WebAssets
@@ -453,7 +457,7 @@ class HttpError extends Error {
 /** A core op the session's spoke does not serve (another harness's spoke): 409 code unsupported, like plugin_outdated. */
 /** (AF3) The same, as an /api/agent error. */
 const unsupportedAgentError = (feature: string, harness: string) => new AgentError("unsupported", unsupportedMessage({ feature, harness }), { extra: { feature, harness } })
-const unsupportedError = (lacking: { readonly feature: Unsupported["feature"] | "fork" | "revert"; readonly harness: string }) => new HttpError(409, unsupportedMessage(lacking), "unsupported")
+const unsupportedError = (lacking: { readonly feature: Unsupported["feature"] | "fork" | "revert" | "setModel"; readonly harness: string }) => new HttpError(409, unsupportedMessage(lacking), "unsupported")
 
 const error = (status: number, message: string, code?: string, headers?: Record<string, string>) =>
   Response.json({ error: message, ...(code ? { code } : {}) }, { status, ...(headers ? { headers } : {}) })
@@ -888,7 +892,7 @@ export function startCentral(options: CentralOptions): Central {
   // sessions frame; human turns (console turn/utterance, prompts typed in the harness) reset hop chains.
   // Teams (HWA-33) and their communication policy in delivery (HWA-34): a denial is audited and journaled (IDs only).
   let teamSeats: TeamSeatStore | undefined
-  const teamStore = new TeamStore({ state: backends.state, now, pinnedVersions: (userID, teamID) => teamSeats!.pinnedVersions(userID, teamID) })
+  const teamStore = new TeamStore({ state: backends.state, now, globalHopLimit: config.hopLimit, pinnedVersions: (userID, teamID) => teamSeats!.pinnedVersions(userID, teamID) })
   const teamPresence = directoryPresence(directory, (userID) => store.agentData(userID).sessions ?? [])
   teamSeats = new TeamSeatStore({ state: backends.state, teams: teamStore, now, knowsSession: async (userID, sessionID) => !["unknown", "deleted"].includes(await teamPresence(userID, sessionID)) })
   const teamPolicy = new TeamPolicy({
@@ -901,8 +905,35 @@ export function startCentral(options: CentralOptions): Central {
       await Promise.all([audit.record(userID, { actor: { kind: "session", sessionID: denial.senderID }, verb: "team.denied", target, decision: "forbidden", reason, outcome: "refused" }), agentEvents.append(userID, teamDeniedEvent(denial))])
     },
   })
+  let decisions: Decisions
+  const teamHopStalls = new TeamHopStalls({
+    state: backends.state,
+    now,
+    seats: async (userID, teamID) => [...new Set((await teamSeats!.list(userID, teamID, { current: true })).map((seat) => seat.sessionID))],
+    reset: (userID, sessionID) => delivery.hops.humanTurn(userID, sessionID),
+    close: async (userID, decisionID) => { await decisions.close(userID, decisionID, "A person continued this team's work; renewal is no longer needed") },
+    notice: (userID, teamID, decisionID) => delivery.notifyTeamHopCap(userID, teamID, decisionID),
+    open: async (userID, teamID, sender, recipient, limit) => {
+      const team = await teamStore.require(userID, teamID)
+      const intake = await teamIntake?.list(userID, { kind: "user", userID, deviceID: "hub", via: "cookie" }, teamID, { limit: 50 })
+      const active = intake?.items.find((item) => item.status === "routed" && (item.sessionID === sender || item.sessionID === recipient))
+      const detail = active ? `, intake ${active.id} (${active.title})` : ""
+      const { decision } = await decisions.ask(userID, { kind: "app", userID, tokenID: "team-hop", scopes: [], label: "Hub team hop cap" }, {
+        question: `Team #${team.name}${detail} reached its ${limit}-hop limit (${sender} → ${recipient}). Renew this team's seats?`,
+        options: [{ id: "renew", label: "Renew" }, { id: "leave", label: "Leave stopped", safe: true }],
+        urgency: "high", tier: "tap", about: [recipient],
+      }, { action: { kind: "teamHopRenew", teamID } })
+      return decision.id
+    },
+  })
   const delivery = new Delivery({
+    hopLimit: config.hopLimit,
     teams: teamPolicy,
+    teamHopCap: async (userID, input) => { await teamHopStalls.hit(userID, input.teamID, input.sender, input.recipient, input.limit) },
+    teamHopNotice: async (userID, teamID) => {
+      const team = await teamStore.get(userID, teamID)
+      return (await teamSeats!.list(userID, teamID, { current: true })).find((seat) => seat.role === team?.entryRole)?.sessionID
+    },
     // CON-04 inbound rule: only the user, app:concierge and replies to its asks reach a Concierge session.
     inbound: conciergeInbound({ identity: conciergeTimedIdentity, audit: { record: (userID, entry) => audit.record(userID, entry) } }),
     state: backends.state,
@@ -937,7 +968,7 @@ export function startCentral(options: CentralOptions): Central {
   /** (CON-06) The Concierge tiers (set below, once the Concierge modules exist): proposals' act, via, disarm. */
   let conciergeTierHooks: ConciergeTiers | undefined
   // Decisions (design §12.1): asks to @me; deadlines run over every user's Decisions (survive restarts).
-  const decisions = new Decisions({
+  decisions = new Decisions({
     state: backends.state,
     delivery,
     now,
@@ -954,6 +985,13 @@ export function startCentral(options: CentralOptions): Central {
     // (CON-06) Concierge proposals run their verb as the user (all set up below).
     act: (userID, decision, choice, by) => {
       const kind = decision.action?.kind
+      if (kind === "teamHopRenew") {
+        if (by.userID !== userID || by.via !== "cookie") return Promise.resolve("gone" as const)
+        const teamID = decision.action!.teamID
+        return choice.option === "renew"
+          ? teamHopStalls.renew(userID, teamID, decision.id).then(async () => { await audit.record(userID, { actor: { kind: "user" }, verb: "team.hop.renew", target: {}, decision: "allow", outcome: "ok" }); return "done" as const })
+          : Promise.resolve("done" as const)
+      }
       if (kind === "act") {
         if (!conciergeTierHooks?.act) throw new Error("This decision's action cannot run on this hub")
         return conciergeTierHooks.act(userID, decision, choice, by)
@@ -975,6 +1013,7 @@ export function startCentral(options: CentralOptions): Central {
     const tenant = registry.sessionTenant(sessionID)
     if (tenant === undefined) return
     await delivery.humanTurn(tenant, sessionID).catch((cause) => console.error(`[hub] hop reset failed: ${(cause as Error).message}`))
+    await teamHopStalls.clearForHuman(tenant, sessionID).catch((cause) => console.error(`[hub] team hop reset failed: ${(cause as Error).message}`))
   }
   registry.onSessions((connID) => void delivery.onSessions(connID).catch((cause) => console.error(`[hub] message flush failed: ${(cause as Error).message}`)))
   // Committed revert windows (./revert-windows): the hub message rows of a removed history stay hidden for good.
@@ -1313,6 +1352,23 @@ export function startCentral(options: CentralOptions): Central {
     audit: (entry) => store.audit(entry),
     users: allUsers,
     log: (message) => console.error(message),
+    pod: config.cluster?.podID ?? "hub",
+    // (Developer mode) What ran a turn: the session's model and context size from its spoke (summary), counts only.
+    turnFacts: async (_userID, sessionID) => {
+      const summary = (await spokes.request(ownerOf(sessionID), { op: "summary", sessionID })) as SessionSummary
+      const model = summary?.model
+      const context = summary?.context
+      const agent = registry.session(sessionID)?.agent
+      return {
+        ...(model?.providerID ? { provider: model.providerID } : {}),
+        ...(model?.modelID ? { model: model.modelID } : context?.model ? { model: context.model } : {}),
+        ...(model?.variant ? { variant: model.variant } : {}),
+        ...(agent ? { agent } : {}),
+        ...(typeof context?.used === "number" ? { contextTokens: context.used } : {}),
+        ...(typeof context?.limit === "number" ? { contextLimit: context.limit } : {}),
+      }
+    },
+    ...(options.recordingDevLimits ? { devLimits: options.recordingDevLimits } : {}),
   })
   recordings = recordingService
   registry.recordingTap = recordingService.registryTap
@@ -1378,7 +1434,7 @@ export function startCentral(options: CentralOptions): Central {
   const workspaces = { workspaces: workspaceStore, members: workspaceMembers, supervision: workspaceSupervision, lifecycle: workspaceLifecycle }
   // Team staffing (HWA-35): seats end on session deletion; launched members are staffed when their launch runs.
   const sessionDirectory = (userID: string, sessionID: string) => (registry.sessionTenant(sessionID) === userID ? registry.session(sessionID)?.directory : undefined)
-  const teamStaffing = new TeamStaffingService({ state: backends.state, teams: teamStore, seats: teamSeats, workspaces: workspaceStore, members: workspaceMembers, supervision: workspaceSupervision, presence: teamPresence, sessionDirectory, launches, grants, acting, audit, profiles, events: agentEvents, now, protects: conciergeProtects(conciergeTimedIdentity) })
+  const teamStaffing = new TeamStaffingService({ state: backends.state, teams: teamStore, seats: teamSeats, workspaces: workspaceStore, members: workspaceMembers, supervision: workspaceSupervision, presence: teamPresence, hopStalls: teamHopStalls, sessionDirectory, launches, grants, acting, audit, profiles, events: agentEvents, now, protects: conciergeProtects(conciergeTimedIdentity) })
   registry.onSessionDeleted((sessionID, tenant) => void teamStaffing.sessionEnded(tenant, sessionID).catch((cause) => console.error(`[hub] team session end failed: ${(cause as Error).message}`)))
   launchFeed.subscribe((userID, launch) => void teamStaffing.launchChanged(userID, launch).catch((cause) => console.error(`[hub] team staffing launch failed: ${(cause as Error).message}`)), { origin: true })
   // Team intake (HWA-36): delivered to an entry seat from the fixed party app:team-intake (never the submitter). The
@@ -1435,6 +1491,7 @@ export function startCentral(options: CentralOptions): Central {
   const subscriptionLeader = leader("subscriptions", { onElected: () => subscriptions?.start(), onDeposed: () => subscriptions?.stop() })
   subscriptions = new Subscriptions({
     state: backends.state,
+    hopLimit: config.hopLimit,
     events: agentEvents,
     send: async (userID, sessionID, text, options) => void (await delivery.send(userID, subscriptionActor(userID), sessionID, "msg", text, options)),
     hopDepth: (userID, sessionID) => delivery.hops.depth(userID, { kind: "session", sessionID }),
@@ -1744,7 +1801,7 @@ export function startCentral(options: CentralOptions): Central {
     conversationOf: (sessionID) => registry.conversationOf(sessionID),
     stateOf: (sessionID) => registry.status(sessionID)?.find((s) => s.id === sessionID)?.state ?? "idle",
   }
-  const agentDeps = { contextCards: cards, conversation: { ports: conversationPorts, source: appStreamSource, streams: appStreams, cookieName: COOKIE, ...options.appStreams }, connect: appConnect, speech: speechDeps, recording: { call: (userID: string, sessionID: string, fields: Parameters<RecordingService["conciergeCall"]>[2]) => recordingService.conciergeCall(userID, sessionID, fields) }, intents, teamDiscovery, draining: drainSignal.signal, store, sessionTokens, directory, registry, spokes, delivery, decisions, messageState: backends.state, feed, heartbeatMs, now, audit, grants, grantRequests, acting, actions, escalate, launches, webhooks, subscriptions, agentEvents, eventCursorKeys: tokenKeys, maxPromptChars: MAX_PROMPT_CHARS, profiles, workspaces, workspaceCheckpoints, teamIntake, graph: { teams: { teams: teamStore, seats: teamSeats! } }, teams: { teams: teamStore, seats: teamSeats!, staffing: teamStaffing }, artifacts: { ...(artifacts && backends.blobs ? { artifacts, blobs: backends.blobs } : {}), state: backends.state, now }, artifactHost: { caps: artifactHostCaps, ...(artifacts ? { artifacts } : {}) }, concierge: { state: backends.state, activity: conciergeActivity, results: conciergeResults, identity: conciergeTimedIdentity, protects: conciergeProtects(conciergeTimedIdentity), service: conciergeService, models: machineModels({ serviceFor: (machineID) => registry.serviceFor(machineID), reportedSessions: (connID) => registry.reportedSessions(connID), request: (connID, req) => spokes.request(connID, req) }), routes: () => [...conciergeParts.tiers.routes(), ...conciergeGrantRequestRoutes({ requests: conciergeGrantRequests, identity: conciergeTimedIdentity })], armed: conciergeArmed, timeZone: conciergeBoardDeps.timeZone, coverage: conciergeCoverage, projectGrant: conciergeProjectGrant } }
+  const agentDeps = { nodes, contextCards: cards, conversation: { ports: conversationPorts, source: appStreamSource, streams: appStreams, cookieName: COOKIE, ...options.appStreams }, connect: appConnect, speech: speechDeps, recording: { call: (userID: string, sessionID: string, fields: Parameters<RecordingService["conciergeCall"]>[2]) => recordingService.conciergeCall(userID, sessionID, fields) }, intents, teamDiscovery, draining: drainSignal.signal, store, sessionTokens, directory, registry, spokes, delivery, decisions, messageState: backends.state, feed, heartbeatMs, now, audit, grants, grantRequests, acting, actions, escalate, launches, webhooks, subscriptions, agentEvents, eventCursorKeys: tokenKeys, maxPromptChars: MAX_PROMPT_CHARS, profiles, workspaces, workspaceCheckpoints, teamIntake, graph: { teams: { teams: teamStore, seats: teamSeats! } }, teams: { teams: teamStore, seats: teamSeats!, staffing: teamStaffing }, artifacts: { ...(artifacts && backends.blobs ? { artifacts, blobs: backends.blobs } : {}), state: backends.state, now }, artifactHost: { caps: artifactHostCaps, ...(artifacts ? { artifacts } : {}) }, concierge: { state: backends.state, activity: conciergeActivity, results: conciergeResults, identity: conciergeTimedIdentity, protects: conciergeProtects(conciergeTimedIdentity), service: conciergeService, models: machineModels({ serviceFor: (machineID) => registry.serviceFor(machineID), reportedSessions: (connID) => registry.reportedSessions(connID), request: (connID, req) => spokes.request(connID, req) }), routes: () => [...conciergeParts.tiers.routes(), ...conciergeGrantRequestRoutes({ requests: conciergeGrantRequests, identity: conciergeTimedIdentity })], armed: conciergeArmed, timeZone: conciergeBoardDeps.timeZone, coverage: conciergeCoverage, projectGrant: conciergeProjectGrant } }
   const resolveActor = createResolver({
     cookieName: COOKIE,
     findDevice: (token) => deviceOfToken(token),
@@ -2026,16 +2083,18 @@ export function startCentral(options: CentralOptions): Central {
       await store.removeDevice(device.id)
       return new Response(null, { status: 204, headers: { "set-cookie": cookie("", 0) } })
     }),
-    route("POST", "/api/transcribe", "user", ({ request, user, device }) => transcribe(request, speechFor(user.id), user.id, device.id)),
-    route("POST", "/api/speak", "user", async ({ request, user, device }) => {
-      const text = speakable(String((await body(request)).text ?? ""), config.maxSpeechChars)
-      if (!text) return error(400, "Nothing to speak")
-      const speech = speechFor(user.id)
-      // (REC-01) x-hub-recording (+ x-hub-tts-ref): tts.synth timing; best effort, the audio is never stored.
-      const tap = await recordingService.speakTap(user.id, device.id, request.headers, text.length).catch(() => undefined)
-      const audio = await speakAudio(speech, text, request.signal)
-      return new Response(tap ? tap.wrap(audio) : audio, { headers: { "content-type": "audio/mpeg" } })
-    }),
+    route("POST", "/api/transcribe", "user", ({ request, user, device }) => requestLined(user.id, device.id, request, "transcribe", () => transcribe(request, speechFor(user.id), user.id, device.id))),
+    route("POST", "/api/speak", "user", ({ request, user, device }) =>
+      requestLined(user.id, device.id, request, "speak", async () => {
+        const text = speakable(String((await body(request)).text ?? ""), config.maxSpeechChars)
+        if (!text) return error(400, "Nothing to speak")
+        const speech = speechFor(user.id)
+        // (REC-01) x-hub-recording (+ x-hub-tts-ref): tts.synth timing; in Developer mode the audio is kept too.
+        const tap = await recordingService.speakTap(user.id, device.id, request.headers, text.length).catch(() => undefined)
+        const audio = await speakAudio(speech, text, request.signal)
+        return new Response(tap ? tap.wrap(audio) : audio, { headers: { "content-type": "audio/mpeg" } })
+      }),
+    ),
     // (REC-01) Recording routes: console only ("user": the user's cookie or device token), see docs/voice-recording.md.
     ...recordingRoutes(recordingService, { version: options.version ?? "0.0.0", now, audit: (entry) => store.audit(entry) }).map((r) => route(r.method, r.path, "user", (context) => r.handle(context))),
     route("GET", "/api/push/key", "user", async () => Response.json({ publicKey: await push.publicKey() })),
@@ -2196,11 +2255,14 @@ export function startCentral(options: CentralOptions): Central {
       const change = modelPrefsInput(await jsonBody(request))
       // Only an obsolete Worker model (an older console): nothing changes.
       if (!("voice" in change)) return getModelPrefs(params.session!, user.id)
-      await checkModelSelections(ownerOf(params.session!), params.session!, change)
+      await checkModelSelections(ownerOf(params.session!), params.session!, [change.voice])
       const reply = await spokes.request(ownerOf(params.session!), { op: "setModelPrefs", sessionID: params.session!, ...change })
       const prefs = await store.setModelPrefs(user.id, params.session!, change)
       return Response.json({ prefs, defaults: voiceOnly(reply.defaults) }, { headers: NO_STORE })
     }),
+    // The session's own model (feature "setModel"): every later turn runs on it, whoever prompts. Same access as a
+    // prompt (the session's owner); the Voice model above is separate.
+    route("PUT", "/api/sessions/:session/model", "session", async ({ request, params, user }) => setSessionModel(request, params.session!, user.id)),
     route("GET", "/api/sessions/:session/timeline", "session", async ({ params, url }) => {
       const limitRaw = url.searchParams.get("limit")
       const limit = limitRaw === null ? undefined : Number(limitRaw)
@@ -2668,6 +2730,20 @@ export function startCentral(options: CentralOptions): Central {
     })
   }
 
+  /**
+   * PUT /api/sessions/:id/model {model}: 400 for a malformed body or a model (variant) the session's catalog lacks,
+   * 409 unsupported when its spoke did not announce setModel (an older plugin: the console's chip stays display only).
+   */
+  async function setSessionModel(request: Request, sessionID: string, userID: string): Promise<Response> {
+    const model = sessionModelInput(await jsonBody(request))
+    const connID = ownerOf(sessionID)
+    if (!registry.supports(connID, "setModel")) throw unsupportedError({ feature: "setModel", harness: registry.harnessOf(connID) ?? "unknown" })
+    await checkModelSelections(connID, sessionID, [model])
+    const result = await spokes.request(connID, { op: "setModel", sessionID, model })
+    await store.audit({ actor: userID, action: "session.model", target: sessionID, detail: `${model.providerID}/${model.modelID}${model.variant ? `#${model.variant}` : ""}` })
+    return Response.json({ model: result.model }, { headers: NO_STORE })
+  }
+
   /** A session's Voice model preference, re-sent to its spoke (which answers with its defaults). */
   async function getModelPrefs(sessionID: string, userID: string): Promise<Response> {
     const prefs = store.modelPrefs(userID, sessionID)
@@ -2706,8 +2782,8 @@ export function startCentral(options: CentralOptions): Central {
    * Every selection must be in the session's catalog (provider, model and variant), so a typo cannot leave
    * the session failing every turn. A catalog that cannot be fetched is a 502, never an accepted selection.
    */
-  async function checkModelSelections(connID: string, sessionID: string, change: { voice?: ModelSelection | null }): Promise<void> {
-    const selections = [change.voice].filter((m): m is ModelSelection => !!m)
+  async function checkModelSelections(connID: string, sessionID: string, picked: ReadonlyArray<ModelSelection | null | undefined>): Promise<void> {
+    const selections = picked.filter((m): m is ModelSelection => !!m)
     if (selections.length === 0) return
     let models: readonly AvailableModel[]
     try {
@@ -3135,6 +3211,28 @@ export function startCentral(options: CentralOptions): Central {
     return answered.outcome === "done" ? new Response(null, { status: 204 }) : error(409, PERMISSION_GONE, "gone")
   }
 
+  /**
+   * (Developer mode) A voice request naming a recording (x-hub-recording): its route, status and time are recorded
+   * as a request line in that recording when it is a developer one (recordingService.requestLine). Never a body.
+   */
+  async function requestLined(userID: string, deviceID: string, request: Request, route: "transcribe" | "speak", handle: () => Promise<Response>): Promise<Response> {
+    const recordingID = request.headers.get(RECORDING_HEADER)
+    if (recordingID === null) return handle()
+    const started = performance.now()
+    let status = 500
+    try {
+      const res = await handle()
+      status = res.status
+      return res
+    } catch (cause) {
+      const s = (cause as { status?: unknown }).status
+      status = cause instanceof SpeechError ? 502 : typeof s === "number" ? s : 500
+      throw cause
+    } finally {
+      void recordingService.requestLine(userID, deviceID, recordingID, { route, method: "POST", status, ms: performance.now() - started }).catch(() => undefined)
+    }
+  }
+
   async function transcribe(request: Request, speech: Speech, userID: string, deviceID: string): Promise<Response> {
     const format = audioFormat(request.headers.get("content-type"))
     if (!format) return error(415, `Unsupported audio type: ${request.headers.get("content-type")}`)
@@ -3146,9 +3244,10 @@ export function startCentral(options: CentralOptions): Central {
     // (REC-01) With x-hub-recording + x-hub-segment: the segment is kept for the recording (no second upload).
     const tap = await recordingService.transcribeTap(userID, deviceID, request.headers, audio, format).catch(() => undefined)
     const started = performance.now()
-    const text = await speech.transcribe(audio, format)
+    const stats: TranscribeStats = {}
+    const text = await (tap ? speech.transcribe(audio, format, stats) : speech.transcribe(audio, format))
     if (!tap) return Response.json({ text })
-    const result = await tap.finish(text, Math.round(performance.now() - started)).catch(() => "failed" as const)
+    const result = await tap.finish(text, Math.round(performance.now() - started), stats).catch(() => "failed" as const)
     return Response.json({ text }, { headers: { [RECORDING_AUDIO_RESULT_HEADER]: result } })
   }
 
@@ -3572,6 +3671,18 @@ function modelPrefsInput(value: unknown): { voice?: ModelSelection | null } {
   return "voice" in out ? { voice: out.voice! } : {}
 }
 
+/** The body of PUT /api/sessions/:id/model: {model: {providerID, modelID, variant?}}; other keys inside `model` are dropped. */
+function sessionModelInput(value: unknown): ModelSelection {
+  const invalid = () => new HttpError(400, "Expected {model: {providerID, modelID, variant?}}")
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw invalid()
+  const record = value as Record<string, unknown>
+  if (Object.keys(record).some((key) => key !== "model")) throw invalid()
+  const m = record.model as Record<string, unknown> | null | undefined
+  if (typeof m !== "object" || m === null || Array.isArray(m)) throw invalid()
+  if (typeof m.providerID !== "string" || !MODEL_ID.test(m.providerID) || typeof m.modelID !== "string" || !MODEL_ID.test(m.modelID) || (m.variant !== undefined && (typeof m.variant !== "string" || !MODEL_ID.test(m.variant)))) throw invalid()
+  return { providerID: m.providerID, modelID: m.modelID, ...(typeof m.variant === "string" && m.variant !== "default" ? { variant: m.variant } : {}) }
+}
+
 function param(raw: string): string {
   try {
     return decodeURIComponent(raw)

package/src/central/recording/export.ts

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