@huynle/hub 0.9.2 → 0.10.1

package/src/central/agent/routes.ts

@@ -16,7 +16,13 @@ import { directoryRoutes } from "./directory-routes"
 import { type ReadDeps, readRoutes, type ReadRegistry, type SpokeRequester } from "./read-routes"
 import { agentAllows, type AgentActor, type AgentAllow, type BearerVerifier, type Credential, type Resolver } from "./actor"
 import { appTokenRoutes, appTokenVerifier } from "./app-tokens"
+import type { AppConnect } from "./connect"
+import { connectRoutes } from "./connect-routes"
+import { speechRoutes, type SpeechRouteDeps } from "./speech-routes"
+import { appSessionCheck, type AppSessionDeps, type AppStreams, conversationRoutes, type ConversationPorts, type StreamSource } from "./conversation"
+import { APP_FRONT_FEATURES, APP_FRONT_SHIPPED } from "../../protocol"
 import type { Decisions } from "./decisions"
+import { appDecisionRoutes } from "./app-decisions"
 import type { Delivery } from "./delivery"
 import { MessageFeed, messageRoutes } from "./message-routes"
 import type { SessionTokens } from "./session-tokens"
@@ -31,6 +37,7 @@ import { actingRoutes } from "./acting-routes"
 import type { Actions } from "../actions"
 import { launchRoutes, type RouteLaunches } from "./launch-routes"
 import { type RouteWebhooks, webhookRoutes } from "./webhook-routes"
+import { type RouteSubscriptions, subscriptionRoutes } from "./subscription-routes"
 import { pinAuthorizer } from "../profiles/apply"
 import { profileRoutes } from "../profiles/routes"
 import { ProfileUsage } from "../profiles/usage"
@@ -61,6 +68,8 @@ import type { ConciergeService } from "../concierge/service"
 import type { SessionIntent } from "../../protocol"
 import type { SessionIntents } from "./intents"
 import { intentRoutes } from "./intent-routes"
+import { contextCardRoutes } from "../context-cards/routes"
+import type { ContextCardService } from "../context-cards/service"
 
 export const AGENT_PREFIX = "/api/agent"
 
@@ -89,6 +98,23 @@ export interface AgentRoute {
 /** What the agent API needs from the hub. */
 export interface AgentDeps {
   readonly store: Store
+  /** (AF1) Connect an app: the connected-app token verifier and the app-clients/connections routes when given. */
+  readonly connect?: AppConnect
+  /** (AF2) Speech for apps: POST /api/agent/speech/{transcribe,speak} (scope speech:use) when given. */
+  readonly speech?: SpeechRouteDeps
+  /**
+   * (AF3) Conversation for apps: the stream and conversation/utterance/interrupt routes (with grants, acting, audit,
+   * registry and directory), the prompt and log widened to conversation:write/read for the app's sessions.
+   */
+  readonly conversation?: {
+    readonly ports: ConversationPorts
+    readonly source: StreamSource
+    readonly streams: AppStreams
+    readonly cookieName: string
+    readonly heartbeatMs?: number
+    readonly recheckMs?: number
+    readonly bufferMaxBytes?: number
+  }
   /** (REC-01) Voice recordings: the Concierge's agent calls (recordConciergeCalls). */
   readonly recording?: ConciergeCallRecorder
   /** Hub-minted session tokens (P1-T5). */
@@ -125,6 +151,8 @@ export interface AgentDeps {
   readonly launches?: RouteLaunches
   /** Webhooks (P4-T10): the /api/agent/webhooks routes when given. */
   readonly webhooks?: RouteWebhooks
+  /** Session subscriptions (decision 74qawely): the /api/agent/subscriptions routes when given with the directory. */
+  readonly subscriptions?: RouteSubscriptions
   /** Profiles (HWA-14): the /api/agent/profiles and /sessions/:addr/profile routes when given with the directory. */
   readonly profiles?: ProfileStore
   /** Workspaces (HWA-06): the /api/agent/workspaces routes when given. */
@@ -181,9 +209,13 @@ export interface AgentDeps {
     readonly timeZone?: (userID: string) => Promise<string | undefined>
     /** (CON-13) The board's inGrant (board-routes.ts BoardRouteDeps.coverage). */
     readonly coverage?: (userID: string, conciergeSessionID: string, sessionID: string, requestID: string) => Promise<{ readonly inGrant: boolean; readonly auto: boolean }>
+    /** (Concierge grant requests) The board's project-level inGrant (board-routes.ts projectGrant). */
+    readonly projectGrant?: (userID: string, conciergeSessionID: string, directory: string) => Promise<readonly string[]>
   }
   /** (CON-02) Session intents: GET/PUT /api/agent/sessions/:addr/intent with the directory; reads carry `intent`. */
   readonly intents?: SessionIntents
+  /** Context cards (decision 9604b0a1): GET /api/agent/sessions/:addr/context-cards. */
+  readonly contextCards?: Pick<ContextCardService, "list" | "registry">
 }
 
 /**
@@ -191,7 +223,7 @@ export interface AgentDeps {
  * order after the device lookup; see BearerVerifier.
  */
 export function agentVerifiers(deps: AgentDeps): BearerVerifier[] {
-  return [...(deps.sessionTokens ? [deps.sessionTokens.verifier] : []), appTokenVerifier(deps.store)]
+  return [...(deps.sessionTokens ? [deps.sessionTokens.verifier] : []), appTokenVerifier(deps.store), ...(deps.connect ? [deps.connect.verifier] : [])]
 }
 
 const userView = (user: UserRecord) => ({
@@ -204,27 +236,34 @@ const userView = (user: UserRecord) => ({
 /** The built-in /api/agent routes. */
 export function agentRoutes(deps: AgentDeps): AgentRoute[] {
   const feed = deps.feed ?? new MessageFeed()
+  const appDecisions = appDecisionParts(deps, feed)
   const routes: AgentRoute[] = [
     ...(deps.directory ? directoryRoutes({ directory: deps.directory, store: deps.store, ...(deps.agentEvents ? { events: deps.agentEvents } : {}), ...(deps.registry ? { registry: deps.registry } : {}), ...(deps.grants ? { grants: deps.grants } : {}), ...(deps.acting ? { acting: deps.acting } : {}), ...(deps.audit ? { audit: deps.audit } : {}), ...(deps.eventCursorKeys ? { previewKeys: deps.eventCursorKeys } : {}), ...(deps.teamDiscovery ? { discovery: deps.teamDiscovery } : {}), ...intentReads(deps), ...conciergeReads(deps) }) : []),
     ...(deps.directory && deps.intents ? intentRoutes({ intents: deps.intents, directory: deps.directory, store: deps.store, ...(deps.registry ? { registry: deps.registry } : {}), ...(deps.teamDiscovery ? { discovery: deps.teamDiscovery } : {}) }) : []),
+    ...(deps.directory && deps.contextCards ? contextCardRoutes({ cards: deps.contextCards, directory: deps.directory, ...(deps.teamDiscovery ? { discovery: deps.teamDiscovery } : {}) }) : []),
     ...(deps.directory && deps.agentEvents && deps.eventCursorKeys ? eventsRoutes({ events: deps.agentEvents, keys: deps.eventCursorKeys, directory: deps.directory, ...eventScope(deps) }) : []),
-    ...(deps.directory && deps.delivery ? messageRoutes({ delivery: deps.delivery, directory: deps.directory, store: deps.store, feed, ...(deps.decisions ? { decisions: deps.decisions } : {}), ...(deps.messageState ? { state: deps.messageState } : {}), ...(deps.now ? { now: deps.now } : {}) }) : []),
-    ...(deps.directory && deps.registry ? readRoutes({ store: deps.store, directory: deps.directory, registry: deps.registry, ...(deps.spokes ? { spokes: deps.spokes } : {}), ...launchReads(deps), ...(deps.agentEvents && deps.eventCursorKeys ? { events: { events: deps.agentEvents, keys: deps.eventCursorKeys, directory: deps.directory, ...eventScope(deps) } } : {}), ...(deps.heartbeatMs !== undefined ? { heartbeatMs: deps.heartbeatMs } : {}), ...(deps.now ? { now: deps.now } : {}), ...(deps.draining ? { draining: deps.draining } : {}), ...(deps.teamDiscovery ? { discovery: deps.teamDiscovery } : {}), ...intentReads(deps), ...conciergeReads(deps) }) : []),
+    ...(deps.directory && deps.delivery ? messageRoutes({ delivery: deps.delivery, directory: deps.directory, store: deps.store, feed, ...(deps.decisions ? { decisions: deps.decisions } : {}), ...(appDecisions ? { answerable: appDecisions.answerable } : {}), ...(deps.messageState ? { state: deps.messageState } : {}), ...(deps.now ? { now: deps.now } : {}) }) : []),
+    ...(deps.directory && deps.registry ? readRoutes({ store: deps.store, directory: deps.directory, registry: deps.registry, ...(deps.spokes ? { spokes: deps.spokes } : {}), ...launchReads(deps), ...(deps.agentEvents && deps.eventCursorKeys ? { events: { events: deps.agentEvents, keys: deps.eventCursorKeys, directory: deps.directory, ...eventScope(deps) } } : {}), ...(deps.heartbeatMs !== undefined ? { heartbeatMs: deps.heartbeatMs } : {}), ...(deps.now ? { now: deps.now } : {}), ...(deps.draining ? { draining: deps.draining } : {}), ...(deps.teamDiscovery ? { discovery: deps.teamDiscovery } : {}), ...intentReads(deps), ...conciergeReads(deps), ...appSessionReads(deps) }) : []),
     {
       method: "GET",
       path: `${AGENT_PREFIX}/whoami`,
       allow: { session: true, app: true },
       handle: ({ actor, user }) => Response.json({ actor, user: userView(user) }, { headers: { "cache-control": "no-store" } }),
     },
-    ...appTokenRoutes(deps.store),
+    ...appTokenRoutes(deps.store, deps.conversation ? { revoked: (userID) => deps.conversation!.streams.pulse(userID) } : {}),
+    ...(deps.connect ? connectRoutes(deps.connect) : []),
+    ...(deps.speech ? speechRoutes(deps.speech) : []),
     ...(deps.audit ? auditRoutes(deps.audit) : []),
     ...(deps.grants ? grantRoutes(deps.grants, deps.now, deps.grantRequests) : []),
     ...(deps.acting ? actingSwitchRoutes(deps.acting) : []),
     ...actVerbRoutes(deps),
+    ...conversationVerbRoutes(deps),
+    ...(appDecisions?.routes ?? []),
     ...(deps.launches && deps.grants && deps.acting && deps.audit
       ? launchRoutes({ launches: deps.launches, grants: deps.grants, acting: deps.acting, audit: deps.audit, ...(deps.directory ? { directory: deps.directory } : {}) })
       : []),
     ...(deps.webhooks ? webhookRoutes(deps.webhooks, deps.store) : []),
+    ...(deps.subscriptions && deps.directory ? subscriptionRoutes({ subscriptions: deps.subscriptions, directory: deps.directory, store: deps.store, ...(deps.teamDiscovery ? { discovery: deps.teamDiscovery } : {}) }) : []),
     ...(deps.profiles && deps.directory
       ? profileRoutes({
           profiles: deps.profiles,
@@ -348,6 +387,65 @@ function intentReads(deps: AgentDeps): { intents?: (userID: string, sessionIDs:
   return intents ? { intents: (userID: string, sessionIDs: readonly string[]) => intents.many(userID, sessionIDs) } : {}
 }
 
+/** (AF3) "The app's sessions" (contract §1.2), when grants, registry and directory are given. */
+function appSessionDeps(deps: AgentDeps): AppSessionDeps | undefined {
+  const { grants, registry, directory, launches } = deps
+  if (!grants || !registry || !directory) return undefined
+  return {
+    registry,
+    directory,
+    grants,
+    ...(launches ? { launches: { list: (userID: string) => launches.list(userID) } } : {}),
+    ...(deps.concierge?.protects ? { protects: deps.concierge.protects } : {}),
+    ...(deps.conversation ? { deletedHere: (sessionID: string) => deps.conversation!.streams.wasDeleted(sessionID) } : {}),
+  }
+}
+
+/** (AF4) Decisions from apps (app-decisions.ts), when Decisions, grants, acting, audit, registry and directory are given. */
+function appDecisionParts(deps: AgentDeps, feed: MessageFeed): ReturnType<typeof appDecisionRoutes> | undefined {
+  const owned = appSessionDeps(deps)
+  const { decisions, acting, audit } = deps
+  if (!owned || !decisions || !acting || !audit || !deps.delivery) return undefined
+  return appDecisionRoutes({ ...owned, decisions, acting, audit, store: deps.store, publish: (userID, message) => feed.publish(userID, message) })
+}
+
+/** (AF3) The prompt and log widened to conversation:write/read: the app's own sessions only. */
+function appSessionReads(deps: AgentDeps): { appSession?: (actor: AgentActor, userID: string, addr: string) => Promise<unknown> } {
+  const owned = appSessionDeps(deps)
+  return owned ? { appSession: (actor, userID, addr) => appSessionCheck(owned, actor, userID, addr) } : {}
+}
+
+/** (AF3) The conversation routes, when every part they need is given. */
+function conversationVerbRoutes(deps: AgentDeps): AgentRoute[] {
+  const owned = appSessionDeps(deps)
+  const { conversation, grants, acting, audit } = deps
+  if (!conversation || !owned || !grants || !acting || !audit) return []
+  const verifiers = agentVerifiers(deps)
+  return conversationRoutes({
+    ...owned,
+    grants,
+    acting,
+    audit,
+    store: deps.store,
+    ports: conversation.ports,
+    source: conversation.source,
+    streams: conversation.streams,
+    cookieName: conversation.cookieName,
+    verify: async (token) => {
+      for (const verifier of verifiers) {
+        const result = await verifier.verify(token)
+        if (result !== undefined) return result
+      }
+      return undefined
+    },
+    ...(deps.draining ? { draining: deps.draining } : {}),
+    ...(deps.now ? { now: deps.now } : {}),
+    ...(conversation.heartbeatMs !== undefined ? { heartbeatMs: conversation.heartbeatMs } : {}),
+    ...(conversation.recheckMs !== undefined ? { recheckMs: conversation.recheckMs } : {}),
+    ...(conversation.bufferMaxBytes !== undefined ? { bufferMaxBytes: conversation.bufferMaxBytes } : {}),
+  })
+}
+
 /** The act verbs, when every part they need is given. */
 function actVerbRoutes(deps: AgentDeps): AgentRoute[] {
   const { actions, acting, grants, audit, registry, directory, spokes } = deps
@@ -366,6 +464,7 @@ function actVerbRoutes(deps: AgentDeps): AgentRoute[] {
       ...(deps.concierge?.protects ? { protect: deps.concierge.protects, conciergeActor: deps.concierge.protects } : {}),
       ...currentConciergeActor(deps),
     }),
+    appSessionReads(deps),
   )
 }
 
@@ -442,7 +541,10 @@ export function agentApi(options: AgentApiOptions): AgentApi {
       const { actor, credential, user, device } = resolved
       return await found.route.handle({ request, url, params: found.params, actor, credential, user, ...(device ? { device } : {}) })
     } catch (cause) {
-      return agentFailure(cause)
+      const failed = agentFailure(cause)
+      // (AF1) A refused connected-app access token says so the OAuth way (RFC 6750 §3.1).
+      if (failed.status === 401 && /^\s*Bearer\s+hca_/i.test(request.headers.get("authorization") ?? "")) failed.headers.set("www-authenticate", 'Bearer error="invalid_token"')
+      return failed
     }
   }
 
@@ -463,7 +565,7 @@ export function wellKnown(info: WellKnownInfo): Response {
   // Pairing codes also work on an OIDC hub (a signed-in device issues them).
   const auth = info.auth.mode === "oidc" ? { modes: ["oidc", "pairing"], oidc: { issuer: info.auth.issuer } } : { modes: ["pairing"] }
   return Response.json(
-    { publicURL: info.publicURL, version: info.version, minClientVersion: MIN_CLIENT_VERSION, auth, features: [] },
+    { publicURL: info.publicURL, version: info.version, minClientVersion: MIN_CLIENT_VERSION, auth, features: APP_FRONT_FEATURES.filter((flag) => APP_FRONT_SHIPPED[flag]) },
     { headers: { "cache-control": "public, max-age=60" } },
   )
 }

package/src/central/agent/speech-routes.ts

@@ -0,0 +1,316 @@
+// Speech for apps (AF2, docs/plans/2026-11-08-app-front-contracts.md §4): POST /api/agent/speech/transcribe (raw
+// audio → {text}) and POST /api/agent/speech/speak ({text} → audio/mpeg), for app credentials holding `speech:use`
+// (hand-made hat_ tokens and connected apps) only: the user's devices get 403 and use the console's /api/transcribe
+// and /api/speak. The hub speaks with THAT user's speech settings and key (http.ts speechFor(user.id)); apps never
+// read or change speech settings, models or keys (those routes stay console-only, behind the console gate).
+//
+// - Limits: the console's maxAudioBytes (HUB_MAX_AUDIO_BYTES) and maxSpeechChars (HUB_MAX_SPEECH_CHARS, after
+//   control characters are stripped and speakable(); longer text is refused, not cut), plus per-credential quotas
+//   (SPEECH_RATE_LIMITS, overridden by hub.json agents.speechQuotas): fixed windows aligned to the clock (a minute,
+//   an hour) in the shared Counters, so every pod of a cluster counts together and retryAfter is exact. Fixed
+//   windows allow up to twice a limit across a window edge (the end of one minute and the start of the next).
+//   Admission is atomic per window: increment first, check the returned count, undo this call's increments when
+//   any window is over (SpeechQuota.admit). A request that is refused for its input is not counted; one that
+//   reaches the provider is (whatever the provider answers).
+// - Errors: 400 invalid (unknown audio type, empty or oversized audio, nothing or too much to speak, a bad body),
+//   403 forbidden (no speech:use; not an app credential), 429 rate_limited {retryAfter, limit} + Retry-After,
+//   422 unsupported {feature: "speech", kind} when the user has no provider for the kind, 502 upstream_failed
+//   {providerStatus?} when the provider fails (a generic message; the provider's text is only logged).
+// - Recording (REC-01) is off for app actors: these handlers never call the recording taps, so x-hub-recording*
+//   headers are ignored and neither audio nor text is kept.
+// - Audit per credential, never content: every request is counted per kind, outcome and clock hour; the user's agent
+//   audit lists at most one speech.transcribe / speech.speak entry per credential, kind and outcome every
+//   AUDIT_SLOT_MS (15 min) with the hour's count so far ("12 this hour so far"), the hour's first one also with the
+//   previous hour's total, so use and abuse are visible without speech flooding the audit ring.
+import { SPEECH_PATHS, SPEECH_RATE_LIMITS } from "../../protocol"
+import type { Clock, Counters } from "../backend/types"
+import { audioFormat, SpeechError } from "../speech/provider"
+import { speakable } from "../../speakable"
+import type { AgentActor } from "./actor"
+import type { AuditDecision, AuditInput, AuditOutcome } from "./audit"
+import { bodyError, readBounded } from "./body"
+import { partyFromActor } from "./envelope"
+import { AgentError } from "./errors"
+import type { AgentContext, AgentRoute } from "./routes"
+
+export type SpeechQuotaKind = keyof typeof SPEECH_RATE_LIMITS
+
+/** Per-credential speech quotas (the contract's SPEECH_RATE_LIMITS shape). */
+export interface SpeechQuotas {
+  readonly transcribe: { readonly perMinute: number; readonly perHour: number }
+  readonly speak: { readonly perMinute: number; readonly perHour: number; readonly charsPerHour: number }
+}
+
+/** hub.json `agents.speechQuotas`: any subset of SpeechQuotas (positive whole numbers). */
+export interface SpeechQuotaOverrides {
+  readonly transcribe?: Partial<SpeechQuotas["transcribe"]>
+  readonly speak?: Partial<SpeechQuotas["speak"]>
+}
+
+/** The defaults with hub.json's overrides on top. */
+export function speechQuotas(overrides: SpeechQuotaOverrides = {}): SpeechQuotas {
+  return {
+    transcribe: { ...SPEECH_RATE_LIMITS.transcribe, ...overrides.transcribe },
+    speak: { ...SPEECH_RATE_LIMITS.speak, ...overrides.speak },
+  }
+}
+
+const MINUTE_MS = 60_000
+const HOUR_MS = 60 * MINUTE_MS
+/** At most one audit entry per credential, kind and outcome this often (it carries the hour's count so far). */
+export const AUDIT_SLOT_MS = 15 * MINUTE_MS
+/** C0/C1 control characters (tabs and line breaks aside, which speakable() folds): never sent to the provider. */
+const CONTROLS = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g
+/** A speak body is {text}: the text is at most maxSpeechChars after speakable(), so 64 KiB is plenty. */
+export const SPEAK_BODY_MAX = 64 * 1024
+
+interface Window {
+  readonly index: number
+  readonly remaining: number
+}
+
+const windowOf = (t: number, size: number): Window => {
+  const index = Math.floor(t / size)
+  return { index, remaining: (index + 1) * size - t }
+}
+
+/** Fixed per-credential windows in the shared Counters (cluster-wide). */
+export class SpeechQuota {
+  private readonly now: Clock
+
+  constructor(
+    private readonly counters: Counters,
+    private readonly quotas: SpeechQuotas,
+    now?: Clock,
+  ) {
+    this.now = now ?? Date.now
+  }
+
+  private checks(credential: string, kind: SpeechQuotaKind, chars: number) {
+    const t = this.now()
+    const minute = windowOf(t, MINUTE_MS)
+    const hour = windowOf(t, HOUR_MS)
+    const quota = this.quotas[kind]
+    const key = (name: string, window: Window) => `speech:${kind}:${name}:${credential}:${window.index}`
+    const checks: { name: string; key: string; window: Window; max: number; by: number }[] = [
+      { name: "perMinute", key: key("m", minute), window: minute, max: quota.perMinute, by: 1 },
+      { name: "perHour", key: key("h", hour), window: hour, max: quota.perHour, by: 1 },
+    ]
+    if (kind === "speak") checks.push({ name: "charsPerHour", key: key("c", hour), window: hour, max: this.quotas.speak.charsPerHour, by: chars })
+    return checks
+  }
+
+  private refused(kind: SpeechQuotaKind, check: { name: string; window: Window; max: number }): AgentError {
+    return new AgentError("rate_limited", `Too many speech requests (${kind} ${check.name} limit: ${check.max})`, {
+      hint: "Wait and try again",
+      extra: { retryAfter: Math.max(1, Math.ceil(check.window.remaining / 1000)), limit: check.name },
+    })
+  }
+
+  /**
+   * An early, non-counting refusal before the body is read (a full request window). Advisory only: `admit` decides.
+   */
+  async peek(credential: string, kind: SpeechQuotaKind): Promise<void> {
+    for (const check of this.checks(credential, kind, 0)) {
+      if (check.by > 0 && (await this.counters.get(check.key)) >= check.max) throw this.refused(kind, check)
+    }
+  }
+
+  /**
+   * Counts one request (and `chars` characters, speak) of the credential, atomically per window: each window is
+   * incremented first and its returned value checked, so parallel requests (on any pod) can never pass a limit. When
+   * one window is over, every increment this call made is undone and it throws rate_limited. While an undo is in
+   * flight a concurrent request may be refused that would have fit: refusals err on the safe side, admissions never.
+   */
+  async admit(credential: string, kind: SpeechQuotaKind, chars = 0): Promise<void> {
+    const done: { key: string; window: Window; by: number }[] = []
+    for (const check of this.checks(credential, kind, chars)) {
+      if (check.by <= 0) continue
+      const value = await this.counters.incr(check.key, check.window.remaining, check.by)
+      done.push(check)
+      if (value > check.max) {
+        await this.undo(done)
+        throw this.refused(kind, check)
+      }
+    }
+  }
+
+  private async undo(done: readonly { key: string; window: Window; by: number }[]): Promise<void> {
+    for (const step of done) {
+      try {
+        await this.counters.incr(step.key, Math.max(1, step.window.remaining), -step.by)
+      } catch (cause) {
+        // The window keeps the extra count until it ends: stricter, never looser.
+        console.error(`[hub] speech quota undo failed: ${(cause as Error).message}`)
+      }
+    }
+  }
+}
+
+/** What the speech routes need from the hub (http.ts): the user's own speech. */
+export interface AppSpeech {
+  /** Whether the user has a provider for each kind (an OpenRouter key, or an openai-compatible base URL). */
+  ready(userID: string): { readonly stt: boolean; readonly tts: boolean }
+  transcribe(userID: string, audio: Uint8Array, format: string): Promise<string>
+  /** The audio, streamed when the provider streams. */
+  speak(userID: string, text: string, signal: AbortSignal): Promise<ReadableStream<Uint8Array> | Uint8Array<ArrayBuffer>>
+}
+
+export interface SpeechRouteDeps {
+  readonly speech: AppSpeech
+  readonly counters: Counters
+  readonly maxAudioBytes: number
+  readonly maxSpeechChars: number
+  readonly quotas?: SpeechQuotaOverrides
+  readonly audit?: { record(userID: string, input: AuditInput): Promise<unknown> }
+  readonly now?: Clock
+}
+
+/** Runs checks made before the body is read; a refusal then says Connection: close when a body was sent (body.ts). */
+async function unread(request: Request, checks: () => Promise<void>): Promise<void> {
+  try {
+    await checks()
+  } catch (cause) {
+    if (!(cause instanceof AgentError) || request.body === null) throw cause
+    throw new AgentError(cause.code, cause.message, { ...cause.options, close: true })
+  }
+}
+
+/** The credential a quota counts against: the app's hand-made token or connection (appOnly ran before). */
+const credentialOf = (actor: AgentActor): string => (actor.kind === "app" ? `app:${actor.tokenID}` : `${actor.kind}:${actor.userID}`)
+
+export function speechRoutes(deps: SpeechRouteDeps): AgentRoute[] {
+  const now = deps.now ?? Date.now
+  const quota = new SpeechQuota(deps.counters, speechQuotas(deps.quotas), now)
+
+  /**
+   * Counts every request per kind and outcome and clock hour; lists at most one entry per AUDIT_SLOT_MS with the
+   * hour's count so far, the hour's first one also with the previous hour's total (see the header).
+   */
+  const audit = async (context: AgentContext, verb: "speech.transcribe" | "speech.speak", decision: AuditDecision, outcome: AuditOutcome) => {
+    const { actor, user } = context
+    if (!deps.audit || actor.kind !== "app") return
+    const t = now()
+    const hour = windowOf(t, HOUR_MS)
+    const slot = windowOf(t, AUDIT_SLOT_MS)
+    const base = `speech:audit:${verb}:${decision}:${outcome}:${credentialOf(actor)}`
+    try {
+      // Kept one hour longer, so the next hour's first entry can read it.
+      const count = await deps.counters.incr(`${base}:n:${hour.index}`, hour.remaining + HOUR_MS)
+      if ((await deps.counters.incr(`${base}:s:${slot.index}`, slot.remaining)) !== 1) return
+      const firstOfHour = (await deps.counters.incr(`${base}:f:${hour.index}`, hour.remaining)) === 1
+      const previous = firstOfHour ? await deps.counters.get(`${base}:n:${hour.index - 1}`) : 0
+      const reason = `${count} this hour so far${previous > 0 ? `; previous hour: ${previous}` : ""}`
+      await deps.audit.record(user.id, { actor: partyFromActor(actor), verb, target: {}, decision, outcome, reason })
+    } catch (cause) {
+      console.error(`[hub] speech audit failed: ${(cause as Error).message}`)
+    }
+  }
+
+  /** Runs `work`, auditing its rate-limit refusal, provider failure or success; input refusals are not audited. */
+  const audited = async (context: AgentContext, verb: "speech.transcribe" | "speech.speak", work: () => Promise<Response>): Promise<Response> => {
+    try {
+      const response = await work()
+      await audit(context, verb, "allow", "ok")
+      return response
+    } catch (cause) {
+      if (cause instanceof AgentError && cause.code === "rate_limited") await audit(context, verb, "rate_limited", "refused")
+      else if (cause instanceof AgentError && cause.code === "upstream_failed") await audit(context, verb, "allow", "failed")
+      else if (cause instanceof AgentError && cause.code === "unsupported") await audit(context, verb, "allow", "unsupported")
+      throw cause
+    }
+  }
+
+  const unsupported = (kind: "stt" | "tts") =>
+    new AgentError("unsupported", kind === "stt" ? "No speech-to-text provider is set up for this user" : "No text-to-speech provider is set up for this user", {
+      hint: "The user sets one up in Settings → Speech",
+      extra: { feature: "speech", kind },
+    })
+
+  /**
+   * A provider failure as 502 upstream_failed: a generic message and the provider's HTTP status only. The provider's
+   * own text (its name, model, masked key fragments) is logged on the hub, never sent to the app.
+   */
+  const upstream = (cause: unknown, verb: string): AgentError => {
+    if (cause instanceof AgentError) return cause
+    console.error(`[hub] app speech provider failed (${verb}): ${(cause as Error)?.message ?? cause}`)
+    const status = cause instanceof SpeechError && typeof cause.status === "number" && Number.isInteger(cause.status) ? cause.status : undefined
+    return new AgentError("upstream_failed", `The speech provider failed${status !== undefined ? ` (HTTP ${status})` : ""}`, {
+      hint: "Try again later",
+      ...(status !== undefined ? { extra: { providerStatus: status } } : {}),
+    })
+  }
+
+  /** (O3) Apps only: the user's devices have the console's own routes. */
+  const appOnly = (actor: AgentActor, consoleRoute: string): void => {
+    if (actor.kind !== "app") throw new AgentError("forbidden", "These routes are for app credentials (hat_ or a connected app)", { hint: `The console uses POST ${consoleRoute}` })
+  }
+
+  return [
+    {
+      method: "POST",
+      path: SPEECH_PATHS.transcribe,
+      allow: { scope: "speech:use" },
+      handle: (context) =>
+        audited(context, "speech.transcribe", async () => {
+          const { request, actor, user } = context
+          appOnly(actor, "/api/transcribe")
+          const credential = credentialOf(actor)
+          // Refused before the audio is read: the cheap checks first, answered with Connection: close (body.ts).
+          await unread(request, async () => {
+            await quota.peek(credential, "transcribe")
+            const type = request.headers.get("content-type")
+            if (!audioFormat(type)) throw new AgentError("invalid", `Unsupported audio type: ${(type ?? "none").slice(0, 100)}`, { hint: "Send webm, mp4/m4a, aac, ogg, wav, mpeg or flac" })
+            if (!deps.speech.ready(user.id).stt) throw unsupported("stt")
+          })
+          const format = audioFormat(request.headers.get("content-type"))!
+          const read = await readBounded(request, deps.maxAudioBytes)
+          if (!read.ok) throw bodyError(read, deps.maxAudioBytes)
+          if (read.bytes.length === 0) throw new AgentError("invalid", "Empty recording", { extra: { limit: deps.maxAudioBytes } })
+          await quota.admit(credential, "transcribe")
+          let text: string
+          try {
+            text = await deps.speech.transcribe(user.id, read.bytes, format)
+          } catch (cause) {
+            throw upstream(cause, "transcribe")
+          }
+          return Response.json({ text }, { headers: { "cache-control": "no-store" } })
+        }),
+    },
+    {
+      method: "POST",
+      path: SPEECH_PATHS.speak,
+      allow: { scope: "speech:use" },
+      handle: (context) =>
+        audited(context, "speech.speak", async () => {
+          const { request, actor, user } = context
+          appOnly(actor, "/api/speak")
+          const credential = credentialOf(actor)
+          await unread(request, () => quota.peek(credential, "speak"))
+          const read = await readBounded(request, SPEAK_BODY_MAX)
+          if (!read.ok) throw bodyError(read, SPEAK_BODY_MAX)
+          let input: unknown
+          try {
+            input = JSON.parse(Buffer.from(read.bytes).toString("utf8"))
+          } catch {
+            throw new AgentError("invalid", "Invalid JSON")
+          }
+          if (typeof input !== "object" || input === null || Array.isArray(input) || typeof (input as { text?: unknown }).text !== "string") {
+            throw new AgentError("invalid", "Body must be {text: string}")
+          }
+          const text = speakable((input as { text: string }).text.replace(CONTROLS, ""))
+          if (!text) throw new AgentError("invalid", "Nothing to speak", { extra: { limit: deps.maxSpeechChars } })
+          if (text.length > deps.maxSpeechChars) throw new AgentError("invalid", `The text is longer than ${deps.maxSpeechChars} characters (after speakable())`, { extra: { limit: deps.maxSpeechChars } })
+          if (!deps.speech.ready(user.id).tts) throw unsupported("tts")
+          await quota.admit(credential, "speak", text.length)
+          let audio: ReadableStream<Uint8Array> | Uint8Array<ArrayBuffer>
+          try {
+            audio = await deps.speech.speak(user.id, text, request.signal)
+          } catch (cause) {
+            throw upstream(cause, "speak")
+          }
+          return new Response(audio, { headers: { "content-type": "audio/mpeg", "cache-control": "no-store" } })
+        }),
+    },
+  ]
+}