@huynle/hub 0.6.1 → 0.7.1

package/src/central/say-stream.ts

@@ -0,0 +1,128 @@
+// Speak while it writes: cuts a root session's streamed assistant text into sentences as soon as each one is
+// complete, so the phone can synthesize and play the first sentence while the rest is still being written.
+// Sentences are raw slices of the text (Markdown and code kept): /api/speak runs speakable() on each, and the
+// slices joined make up the streamed text, so the phone can merge them with the bubble streamed from deltas.
+
+/** Tokens ending in "." that rarely end a sentence (compared lowercase). */
+const ABBREVIATIONS = new Set(["e.g.", "i.e.", "mr.", "mrs.", "ms.", "dr.", "st.", "vs.", "cf.", "prof.", "jr.", "sr.", "approx.", "no.", "fig.", "etc."])
+/** A line break, or sentence-ending punctuation with closing quotes/brackets. */
+const BOUNDARY = /\n|[.?!…]+["'”’)\]]*/g
+const CLOSING_FENCE = /\n[ \t]*```/g
+const WORDY = /[\p{L}\p{N}]/u
+
+export interface SentenceStreamOptions {
+  /** A run this long without a sentence end is cut at a comma or space. */
+  readonly maxChars?: number
+}
+
+export class SentenceStream {
+  private buf = ""
+  /** Everything before this offset was emitted. */
+  private pos = 0
+  private maxChars: number
+
+  constructor({ maxChars = 300 }: SentenceStreamOptions = {}) {
+    this.maxChars = maxChars
+  }
+
+  /** Appends streamed text; returns the sentences it completed. */
+  push(delta: string): string[] {
+    this.buf += String(delta ?? "")
+    return this.drain(false)
+  }
+
+  /**
+   * The text ended: returns the remaining sentences. `full` (the final text) is authoritative: missed deltas
+   * are recovered, and when only a later part was streamed, speech continues after what was already emitted.
+   */
+  end(full?: string): string[] {
+    if (typeof full === "string") this.adopt(full)
+    return this.drain(true)
+  }
+
+  private adopt(full: string): void {
+    const done = this.buf.slice(0, this.pos)
+    if (full.startsWith(done)) {
+      this.buf = full
+      return
+    }
+    const spoken = done.trim()
+    const at = full.indexOf(spoken)
+    if (at >= 0) {
+      this.buf = full
+      this.pos = at + spoken.length
+    }
+    // Otherwise the texts diverged: only what was streamed is spoken.
+  }
+
+  private drain(final: boolean): string[] {
+    const out: string[] = []
+    for (;;) {
+      while (this.pos < this.buf.length && /\s/.test(this.buf[this.pos]!)) this.pos++
+      if (this.pos >= this.buf.length) break
+      const end = this.next(this.pos, final)
+      if (end === undefined) break
+      const sentence = this.buf.slice(this.pos, end).trim()
+      this.pos = end
+      if (WORDY.test(sentence)) out.push(sentence)
+    }
+    return out
+  }
+
+  /** End offset of the next piece starting at `start`, or undefined to wait for more text. */
+  private next(start: number, final: boolean): number | undefined {
+    const buf = this.buf
+    if (buf.startsWith("```", start)) {
+      CLOSING_FENCE.lastIndex = start + 3
+      const close = CLOSING_FENCE.exec(buf)
+      if (close) return close.index + close[0].length
+      return final ? buf.length : undefined
+    }
+    BOUNDARY.lastIndex = start
+    for (let match = BOUNDARY.exec(buf); match; match = BOUNDARY.exec(buf)) {
+      const at = match.index
+      const after = at + match[0].length
+      let end: number | undefined
+      if (match[0] === "\n") end = at
+      else {
+        const verdict = this.sentenceEnd(start, at, after, final)
+        if (verdict === "wait") return this.cutLong(start, final)
+        if (verdict) end = after
+      }
+      if (end === undefined) continue
+      // Pieces without words ("---", "**") join the next sentence, unless a code block comes next (then
+      // they are dropped: drain skips pieces without words).
+      if (WORDY.test(buf.slice(start, end)) || /^\n[ \t]*```/.test(buf.slice(at))) return end
+    }
+    return this.cutLong(start, final)
+  }
+
+  /** Whether punctuation at `at`..`after` ends a sentence; "wait" when the text after it has not arrived. */
+  private sentenceEnd(start: number, at: number, after: number, final: boolean): boolean | "wait" {
+    const buf = this.buf
+    if (after >= buf.length) return final ? true : "wait"
+    if (!/\s/.test(buf[after]!)) return false // 3.5, config.ts, v1.2
+    const rest = /^[ \t]*([\s\S])?/.exec(buf.slice(after))!
+    const next = rest[1]
+    if (next === undefined) return final ? true : "wait"
+    if (next === "\n" || /\s/.test(next)) return true
+    if (/[?!]/.test(buf.slice(at, after))) return true
+    const lineStart = Math.max(start, buf.lastIndexOf("\n", at) + 1)
+    const tokenStart = Math.max(lineStart, buf.lastIndexOf(" ", at) + 1)
+    const token = buf.slice(tokenStart, after).toLowerCase()
+    if (ABBREVIATIONS.has(token.replace(/["'”’)\]]+$/, ""))) return false
+    if (tokenStart === lineStart && /^\d+[.)]$/.test(token)) return false // "1." list marker
+    return !/\p{Ll}/u.test(next)
+  }
+
+  /** No sentence end yet: a run longer than maxChars is cut at a comma or space; at the end, all of it. */
+  private cutLong(start: number, final: boolean): number | undefined {
+    const buf = this.buf
+    if (final) return buf.length
+    if (buf.length - start <= this.maxChars) return undefined
+    const window = buf.slice(start, start + this.maxChars)
+    let at = Math.max(window.lastIndexOf(", "), window.lastIndexOf("; "))
+    at = at > this.maxChars / 2 ? at + 1 : window.lastIndexOf(" ")
+    return start + (at > 0 ? at : this.maxChars)
+  }
+}

package/src/central/session-token-push.ts

@@ -0,0 +1,233 @@
+// Delivers hub-minted session tokens (./agent/session-tokens.ts) to the spokes that report the sessions, with
+// the sessionTokens op (feature "sessionTokens"; older spokes get nothing).
+//
+// On every sessions frame of a connection, the hub sends tokens for the sessions it reports for its own tenant
+// (subagents included) that have none yet on that connection, whose token has less than a third of its lifetime
+// left, or whose machine stamp changed (user or machine epoch, active key). Unchanged tokens are not resent. A
+// reconnect is a new connection, so it gets every token again (the spoke drops its tokens when its connection
+// changes). Tokens the spoke skipped, and tokens of a failed send, are retried on the next frame or sweep. A
+// periodic sweep refreshes tokens nearing expiry and forgets connections that are gone.
+//
+// Act tokens (typ "act", decision #1 of phase 3) follow the same rules in a lane of their own: the actTokens op,
+// sent only to connections announcing "actTokens" (never inside a sessionTokens frame, which older spokes hand to
+// shells), without a hub URL, deduped and retried separately from the shell tokens. Launch-bound connections (a
+// spoke in a sandbox, phase 5 decision #5) get session tokens but never act tokens.
+// Tokens are never logged.
+import {
+  batchActTokens,
+  batchSessionTokens,
+  type ActTokensRequest,
+  type ResultFor,
+  type SessionToken,
+  type SessionTokensRequest,
+  type SpokeFeature,
+} from "../protocol"
+import type { Timers } from "./registry"
+
+/** How often the sweep looks for tokens to refresh (well under a third of their lifetime). */
+export const SESSION_TOKEN_SWEEP_MS = 10 * 60 * 1000
+/** A token is refreshed when less than this fraction of its lifetime remains. */
+export const SESSION_TOKEN_REFRESH_FRACTION = 1 / 3
+
+/** What the push reads from the registry. */
+export interface PushRegistry {
+  supports(connID: string, feature: SpokeFeature): boolean
+  connMachine(connID: string): string | undefined
+  /** Sessions the connection reports for its own tenant. */
+  reportedSessions(connID: string): string[]
+  /** The launch a connection is bound to (a sandboxed spoke, phase 5): such connections get no act tokens. */
+  launchOf?(connID: string): string | undefined
+}
+
+/** Mints tokens (SessionTokens). */
+export interface TokenMinter {
+  readonly lifetimeMs: number
+  stamp(machineID: string): string | undefined
+  mint(machineID: string, sessionID: string): { token: string; exp: number; stamp: string } | undefined
+  /** An act token (typ "act"); without it no act tokens are sent. */
+  mintAct?(machineID: string, sessionID: string): { token: string; exp: number; stamp: string } | undefined
+}
+
+export interface SessionTokenPushOptions {
+  readonly registry: PushRegistry
+  readonly tokens: TokenMinter
+  /** Sends a sessionTokens request to a connection (SpokeHub.request). */
+  send(connID: string, req: SessionTokensRequest | ActTokensRequest): Promise<ResultFor["sessionTokens"]>
+  /** The URL sessions' shells reach the hub at. */
+  readonly hubURL: string
+  readonly now?: () => number
+  readonly timers?: Timers
+  readonly sweepMs?: number
+  /** Largest request JSON (default: what fits in a frame). */
+  readonly maxChars?: number
+  log?(message: string): void
+}
+
+/** What a connection was sent for a session. */
+interface Sent {
+  readonly exp: number
+  readonly stamp: string
+}
+
+/** One kind of token: the feature a connection must announce, how to mint one and how to batch them. */
+interface Lane {
+  readonly feature: SpokeFeature
+  /** Launch-bound connections are left out of this lane. */
+  readonly skipLaunchBound?: boolean
+  mint(machineID: string, sessionID: string): { token: string; exp: number; stamp: string } | undefined
+  batch(tokens: readonly SessionToken[]): Array<SessionTokensRequest | ActTokensRequest>
+  /** connID → sessionID → the token last sent (or being sent). */
+  readonly sent: Map<string, Map<string, Sent>>
+}
+
+const realTimers: Timers = {
+  set: (fn, ms) => {
+    const handle = setTimeout(fn, ms)
+    ;(handle as { unref?: () => void }).unref?.()
+    return handle
+  },
+  clear: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+}
+
+const reason = (cause: unknown) => (cause instanceof Error ? cause.message : String(cause))
+
+export class SessionTokenPush {
+  readonly #lanes: readonly Lane[]
+  readonly #inflight = new Set<Promise<unknown>>()
+  readonly #now: () => number
+  readonly #timers: Timers
+  #timer: unknown
+  #stopped = false
+
+  constructor(private readonly options: SessionTokenPushOptions) {
+    this.#now = options.now ?? Date.now
+    this.#timers = options.timers ?? realTimers
+    const { tokens, hubURL, maxChars } = options
+    const max = maxChars !== undefined ? { maxChars } : {}
+    const session: Lane = {
+      feature: "sessionTokens",
+      mint: (machineID, sessionID) => tokens.mint(machineID, sessionID),
+      batch: (batch) => batchSessionTokens(batch, { hubURL, ...max }),
+      sent: new Map(),
+    }
+    const mintAct = tokens.mintAct?.bind(tokens)
+    const act: Lane | undefined = mintAct && { feature: "actTokens", skipLaunchBound: true, mint: mintAct, batch: (batch) => batchActTokens(batch, max), sent: new Map() }
+    this.#lanes = act ? [session, act] : [session]
+  }
+
+  /** Handles a sessions frame of a connection: sends what is new or due. Resolves when the sends settle. */
+  sessions(connID: string): Promise<void> {
+    return this.#track(this.#sync(connID))
+  }
+
+  /** Refreshes tokens nearing expiry on every known connection; forgets connections that are gone. */
+  sweep(): Promise<void> {
+    return this.#track(this.#sweepAll())
+  }
+
+  /** Resolves when every send started so far has settled (tests). */
+  async idle(): Promise<void> {
+    while (this.#inflight.size > 0) await Promise.allSettled([...this.#inflight])
+  }
+
+  /** Arms the periodic sweep. */
+  start(): void {
+    this.#stopped = false
+    this.#arm()
+  }
+
+  stop(): void {
+    this.#stopped = true
+    if (this.#timer !== undefined) this.#timers.clear(this.#timer)
+    this.#timer = undefined
+  }
+
+  #arm(): void {
+    if (this.#stopped) return
+    this.#timer = this.#timers.set(() => {
+      void this.#track(this.#sweepAll().finally(() => this.#arm()))
+    }, this.options.sweepMs ?? SESSION_TOKEN_SWEEP_MS)
+  }
+
+  async #sweepAll(): Promise<void> {
+    const conns = new Set(this.#lanes.flatMap((lane) => [...lane.sent.keys()]))
+    await Promise.all([...conns].map((connID) => this.#track(this.#sync(connID))))
+  }
+
+  /** Tracks work for idle(); failures (e.g. an unreadable key file) are logged, never thrown. */
+  #track(work: Promise<void>): Promise<void> {
+    const safe = work.catch((cause) => this.options.log?.(`[hub] session tokens: ${reason(cause)}`))
+    this.#inflight.add(safe)
+    return safe.finally(() => this.#inflight.delete(safe))
+  }
+
+  async #sync(connID: string): Promise<void> {
+    await Promise.all(this.#lanes.map((lane) => this.#syncLane(lane, connID)))
+  }
+
+  async #syncLane(lane: Lane, connID: string): Promise<void> {
+    const { registry, tokens } = this.options
+    const machineID = registry.connMachine(connID)
+    const excluded = lane.skipLaunchBound === true && registry.launchOf?.(connID) !== undefined
+    if (machineID === undefined || excluded || !registry.supports(connID, lane.feature)) {
+      lane.sent.delete(connID)
+      return
+    }
+    const stamp = tokens.stamp(machineID)
+    if (stamp === undefined) {
+      lane.sent.delete(connID)
+      return
+    }
+    let sent = lane.sent.get(connID)
+    if (!sent) lane.sent.set(connID, (sent = new Map()))
+    const reported = new Set(registry.reportedSessions(connID))
+    for (const sessionID of sent.keys()) if (!reported.has(sessionID)) sent.delete(sessionID)
+
+    const now = this.#now()
+    const refreshAt = tokens.lifetimeMs * SESSION_TOKEN_REFRESH_FRACTION
+    const due: SessionToken[] = []
+    const records = new Map<string, Sent>()
+    for (const sessionID of reported) {
+      const last = sent.get(sessionID)
+      if (last && last.stamp === stamp && last.exp - now >= refreshAt) continue
+      const minted = lane.mint(machineID, sessionID)
+      if (!minted) continue
+      const entry = { sessionID, token: minted.token, exp: minted.exp }
+      if (!this.#fits(lane, entry)) {
+        this.options.log?.(`[hub] ${lane.feature === "actTokens" ? "act" : "session"} token for ${sessionID} does not fit in a frame; not sent`)
+        continue
+      }
+      const record = { exp: minted.exp, stamp: minted.stamp }
+      sent.set(sessionID, record)
+      records.set(sessionID, record)
+      due.push(entry)
+    }
+    if (due.length === 0) return
+
+    const forget = (sessionID: string) => {
+      if (records.has(sessionID) && sent.get(sessionID) === records.get(sessionID)) sent.delete(sessionID)
+    }
+    const requests = lane.batch(due)
+    await Promise.all(
+      requests.map(async (req) => {
+        try {
+          const result = await this.options.send(connID, req)
+          for (const { sessionID } of result.skipped) forget(sessionID)
+        } catch (cause) {
+          for (const { sessionID } of req.tokens) forget(sessionID)
+          this.options.log?.(`[hub] sending ${lane.feature === "actTokens" ? "act" : "session"} tokens failed: ${reason(cause)}`)
+        }
+      }),
+    )
+  }
+
+  /** Whether a token fits in a request on its own. */
+  #fits(lane: Lane, entry: SessionToken): boolean {
+    try {
+      lane.batch([entry])
+      return true
+    } catch {
+      return false
+    }
+  }
+}

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 { audioMime, SpeechError, upstreamDetail, withSpeedRetry, type SpeechProvider } from "./provider"
+import { audioBody, audioMime, collect, SpeechError, transcriptText, upstreamDetail, wantsVerbose, withSpeedRetry, withVerboseRetry, type SpeechProvider } from "./provider"
 
 export interface OpenAICompatibleOptions {
   /** Base URL including the version path, e.g. https://api.openai.com/v1 (no trailing slash). */
@@ -17,28 +17,35 @@ export interface OpenAICompatibleOptions {
 
 export class OpenAICompatible implements SpeechProvider {
   private readonly fetch: typeof globalThis.fetch
+  /** Ask for verbose_json (a Whisper model whose server has not refused it). */
+  private verbose: boolean
 
   constructor(private readonly options: OpenAICompatibleOptions) {
     this.fetch = options.fetch ?? globalThis.fetch
+    this.verbose = wantsVerbose(options.sttModel)
   }
 
   async transcribe(audio: Uint8Array, format: string, signal?: AbortSignal): Promise<string> {
-    const form = new FormData()
-    form.append("file", new File([new Uint8Array(audio)], `audio.${format}`, { type: audioMime(format) }))
-    form.append("model", this.options.sttModel)
-    if (this.options.language) form.append("language", this.options.language)
-    const response = await this.fetch(`${this.options.baseURL}/audio/transcriptions`, {
-      method: "POST",
-      headers: await this.headers(),
-      body: form,
-      signal,
-    })
+    const headers = await this.headers()
+    const send = (verbose: boolean) => {
+      const form = new FormData()
+      form.append("file", new File([new Uint8Array(audio)], `audio.${format}`, { type: audioMime(format) }))
+      form.append("model", this.options.sttModel)
+      if (this.options.language) form.append("language", this.options.language)
+      // Whisper's verbose_json rates each segment's no_speech_prob: noise transcribed as "Thank you." is dropped.
+      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))
     if (!response.ok) throw await failure("transcription", response)
-    const body = (await response.json()) as { text?: unknown }
-    return String(body.text ?? "").trim()
+    return transcriptText(await response.json())
   }
 
   async speak(text: string, speed?: number, signal?: AbortSignal): Promise<Uint8Array<ArrayBuffer>> {
+    return collect(await this.speakStream(text, speed, signal))
+  }
+
+  async speakStream(text: string, speed?: number, signal?: AbortSignal): Promise<ReadableStream<Uint8Array>> {
     const { ttsModel: model, voice } = this.options
     const headers = { ...(await this.headers()), "content-type": "application/json" }
     const response = await withSpeedRetry(
@@ -52,7 +59,7 @@ export class OpenAICompatible implements SpeechProvider {
       speed,
     )
     if (!response.ok) throw await failure("speech", response)
-    return new Uint8Array(await response.arrayBuffer())
+    return audioBody(response)
   }
 
   private async headers(): Promise<Record<string, string>> {

package/src/central/speech/openrouter.ts

@@ -1,6 +1,6 @@
-// OpenRouter speech-to-text (/audio/transcriptions, JSON with base64 input_audio) and text-to-speech
-// (/audio/speech).
-import { SpeechError, upstreamDetail, withSpeedRetry, type SpeechProvider } from "./provider"
+// 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"
 
 export const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
 
@@ -24,22 +24,37 @@ export class OpenRouterError extends SpeechError {
 export class OpenRouter implements SpeechProvider {
   private readonly baseURL: string
   private readonly fetch: typeof globalThis.fetch
+  /** Ask for verbose_json (a Whisper model whose provider has not refused it). */
+  private verbose: boolean
 
   constructor(private readonly options: OpenRouterOptions) {
     this.baseURL = options.baseURL ?? OPENROUTER_BASE_URL
     this.fetch = options.fetch ?? globalThis.fetch
+    this.verbose = wantsVerbose(options.sttModel)
   }
 
   async transcribe(audio: Uint8Array, format: string, signal?: AbortSignal): Promise<string> {
     const { sttModel: model, language } = this.options
-    const input_audio = { data: Buffer.from(audio).toString("base64"), format }
-    const response = await this.post("/audio/transcriptions", { model, input_audio, ...(language ? { language } : {}) }, signal)
+    // 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.
+    const send = (verbose: boolean) => {
+      const form = new FormData()
+      form.append("file", new File([new Uint8Array(audio)], `audio.${format}`, { type: audioMime(format) }))
+      form.append("model", model)
+      if (language) form.append("language", language)
+      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))
     if (!response.ok) throw await failure("transcription", response)
-    const body = (await response.json()) as { text?: unknown }
-    return String(body.text ?? "").trim()
+    return transcriptText(await response.json())
   }
 
   async speak(text: string, speed?: number, signal?: AbortSignal): Promise<Uint8Array<ArrayBuffer>> {
+    return collect(await this.speakStream(text, speed, signal))
+  }
+
+  async speakStream(text: string, speed?: number, signal?: AbortSignal): Promise<ReadableStream<Uint8Array>> {
     const { ttsModel: model, voice } = this.options
     const response = await withSpeedRetry(
       (s) =>
@@ -47,9 +62,10 @@ export class OpenRouter implements SpeechProvider {
       speed,
     )
     if (!response.ok) throw await failure("speech", response)
-    return new Uint8Array(await response.arrayBuffer())
+    return audioBody(response)
   }
 
+  /** POSTs JSON, or a form as multipart (fetch sets its content type with the boundary). */
   private async post(path: string, body: unknown, signal?: AbortSignal): Promise<Response> {
     const key = await this.options.apiKey()
     if (!key) {
@@ -57,10 +73,11 @@ export class OpenRouter implements SpeechProvider {
         "No OpenRouter API key: set one in the speech settings, set OPENROUTER_API_KEY, or connect OpenRouter in OpenCode",
       )
     }
+    const form = body instanceof FormData
     return this.fetch(`${this.baseURL}${path}`, {
       method: "POST",
-      headers: { authorization: `Bearer ${key}`, "content-type": "application/json" },
-      body: JSON.stringify(body),
+      headers: { authorization: `Bearer ${key}`, ...(form ? {} : { "content-type": "application/json" }) },
+      body: form ? body : JSON.stringify(body),
       signal,
     })
   }

package/src/central/speech/provider.ts

@@ -6,6 +6,18 @@ export interface SpeechProvider {
   transcribe(audio: Uint8Array, format: string, signal?: AbortSignal): 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>>
+}
+
+/** 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() })
+}
+
+/** Reads a whole audio stream into one buffer. */
+export async function collect(stream: ReadableStream<Uint8Array>): Promise<Uint8Array<ArrayBuffer>> {
+  return new Uint8Array(await new Response(stream).arrayBuffer())
 }
 
 /** The speech provider refused or failed a request (or is not configured). Never carries the API key. */
@@ -72,3 +84,45 @@ export async function withSpeedRetry(send: (speed?: number) => Promise<Response>
   await response.body?.cancel().catch(() => {})
   return send(undefined)
 }
+
+/** Whisper segments rated more likely than this to hold no speech are dropped (Whisper's own no-speech threshold). */
+export const NO_SPEECH_MAX = 0.6
+
+/** Whisper models report no_speech_prob per segment in verbose_json; other speech-to-text models do not take it. */
+export function wantsVerbose(model: string): boolean {
+  return /whisper/i.test(model)
+}
+
+interface TranscriptBody {
+  text?: unknown
+  segments?: Array<{ text?: unknown; no_speech_prob?: unknown }>
+}
+
+/**
+ * The transcript of a json or verbose_json response. With segments that carry no_speech_prob, the ones above
+ * NO_SPEECH_MAX (noise Whisper turned into "Thank you." and the like) are left out.
+ */
+export function transcriptText(body: unknown): string {
+  const { text, segments } = (body ?? {}) as TranscriptBody
+  if (Array.isArray(segments) && segments.some((s) => typeof s?.no_speech_prob === "number")) {
+    return segments
+      .filter((s) => !(typeof s?.no_speech_prob === "number" && s.no_speech_prob > NO_SPEECH_MAX))
+      .map((s) => String(s?.text ?? "").trim())
+      .filter(Boolean)
+      .join(" ")
+  }
+  return String(text ?? "").trim()
+}
+
+/**
+ * Sends a transcription, verbose (verbose_json) when asked; a 400 to the verbose request is retried once plain,
+ * and when the plain one works the provider is told (`refused`) not to ask for verbose_json again.
+ */
+export async function withVerboseRetry(send: (verbose: boolean) => Promise<Response>, verbose: boolean, refused: () => void): Promise<Response> {
+  const response = await send(verbose)
+  if (!verbose || response.status !== 400) return response
+  await response.body?.cancel().catch(() => {})
+  const plain = await send(false)
+  if (plain.ok) refused()
+  return plain
+}

package/src/central/speech/service.ts

@@ -24,16 +24,18 @@ const MODELS_TIMEOUT_MS = 10_000
 export interface SpeechSettingsStore {
   /** The server default. */
   speechSettings(): StoredSpeech
-  setSpeechSettings(settings: StoredSpeech): void
+  setSpeechSettings(settings: StoredSpeech): void | Promise<void>
   /** A user's own settings (multi-user hubs). */
   userSpeech?(userID: string): StoredSpeech
-  setUserSpeech?(userID: string, settings: StoredSpeech): void
+  setUserSpeech?(userID: string, settings: StoredSpeech): void | Promise<void>
 }
 
 /** 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>
   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>>
 }
 
 export interface SpeechServiceOptions {
@@ -67,17 +69,24 @@ export class SpeechService {
     return userSpeechView(stored, this.options.defaults, this.userSettings(userID) ?? {})
   }
 
-  /** Partial update of the server default, or of a user's own settings; throws ValidationError without saving anything. */
-  update(input: unknown, userID?: string): SpeechView | UserSpeechView {
+  /**
+   * Partial update of the server default, or of a user's own settings; throws ValidationError (synchronously)
+   * without saving anything. Resolves with the new view once saved.
+   */
+  update(input: unknown, userID?: string): Promise<SpeechView | UserSpeechView> {
     const { store, defaults } = this.options
-    if (userID === undefined) store.setSpeechSettings(updateSpeech(store.speechSettings(), input, defaults.file))
+    let saved: void | Promise<void>
+    if (userID === undefined) saved = store.setSpeechSettings(updateSpeech(store.speechSettings(), input, defaults.file))
     else {
       if (!store.setUserSpeech) throw new Error("per-user speech settings are not supported by this store")
       // Validated against (and keys dropped relative to) the layers below: server default and hub.json.
-      store.setUserSpeech(userID, updateSpeech(this.userSettings(userID) ?? {}, input, lowerLayers(store.speechSettings(), defaults)))
+      saved = store.setUserSpeech(userID, updateSpeech(this.userSettings(userID) ?? {}, input, lowerLayers(store.speechSettings(), defaults)))
     }
     this.cache.clear()
-    return this.view(userID)
+    return Promise.resolve(saved).then(() => {
+      this.cache.clear()
+      return this.view(userID)
+    })
   }
 
   /** Speech with a user's effective settings (undefined: the server default). */
@@ -85,6 +94,7 @@ export class SpeechService {
     return {
       transcribe: (audio, format) => this.transcribe(audio, format, undefined, userID),
       speak: (text) => this.speak(text, undefined, userID),
+      speakStream: (text, signal) => this.speakStream(text, signal, userID),
     }
   }
 
@@ -97,6 +107,11 @@ export class SpeechService {
     return this.provider("tts", userID).speak(text, tts.speed, signal)
   }
 
+  speakStream(text: string, signal?: AbortSignal, userID?: string): Promise<ReadableStream<Uint8Array>> {
+    const tts = resolveTts(this.options.store.speechSettings(), this.options.defaults, this.userSettings(userID))
+    return this.provider("tts", userID).speakStream(text, tts.speed, signal)
+  }
+
   /**
    * Models offered by the configured provider for `kind` (a user's effective provider when given), the
    * configured model first and marked `current`. OpenRouter filters by output modality; other providers list