@schlessera/brain-ui-server 0.4.0

package/src/routes/voice.ts

@@ -0,0 +1,80 @@
+import { Hono } from "hono";
+import type {
+  VoiceKeytermsResponse,
+  VoiceTokenResponse,
+  VoiceSessionResponse,
+} from "@schlessera/brain-ui-sdk/protocol";
+import { mintDeepgramToken } from "../voice/deepgram-token.js";
+import { getKeyterms } from "../voice/keyterm-builder.js";
+import { pickSpeechProvider } from "../voice/speech-providers.js";
+
+export const voiceRoutes = new Hono()
+  .post("/voice/session", async (c) => {
+    try {
+      const provider = pickSpeechProvider();
+      // Only fetch domain keyterms when the provider can use them.
+      const keyterms = provider.capabilities.keyterms
+        ? getKeyterms(false).keyterms
+        : [];
+      const session = await provider.createSession({ keyterms });
+      const body: VoiceSessionResponse = {
+        providerId: provider.id,
+        url: session.url,
+        ...(session.token !== undefined ? { token: session.token } : {}),
+        ...(session.params !== undefined ? { params: session.params } : {}),
+        expiresAt: session.expiresAt,
+        capabilities: provider.capabilities,
+      };
+      return c.json(body);
+    } catch (err) {
+      return c.json(
+        { error: err instanceof Error ? err.message : "Voice session failed" },
+        500
+      );
+    }
+  })
+
+  // Deprecated alias, kept for client transition. Returns the old token shape
+  // by minting a Deepgram token directly; new clients use /voice/session.
+  .post("/voice/token", async (c) => {
+    try {
+      const { token, expiresAt } = await mintDeepgramToken(60);
+      const body: VoiceTokenResponse = { token, expiresAt };
+      return c.json(body);
+    } catch (err) {
+      return c.json(
+        { error: err instanceof Error ? err.message : "Token mint failed" },
+        500
+      );
+    }
+  })
+
+  .get("/voice/keyterms", async (c) => {
+    const force = c.req.query("rebuild") === "1";
+    try {
+      const cache = getKeyterms(force);
+      const body: VoiceKeytermsResponse = {
+        keyterms: cache.keyterms,
+        generatedAt: cache.generatedAt,
+        count: cache.count,
+      };
+      return c.json(body);
+    } catch (err) {
+      return c.json(
+        { error: err instanceof Error ? err.message : "Keyterms failed" },
+        500
+      );
+    }
+  })
+
+  .get("/voice/overrides", async (c) => {
+    try {
+      const cache = getKeyterms(false);
+      return c.json({ overrides: cache.overrides });
+    } catch (err) {
+      return c.json(
+        { error: err instanceof Error ? err.message : "Overrides failed" },
+        500
+      );
+    }
+  });

package/src/voice/deepgram-token.ts

@@ -0,0 +1,80 @@
+// Deepgram token mint.
+// Short-lived grant via /v1/auth/grant. The API key used to call grant needs at
+// least *Member* project permission (NOT `keys:write`, which belongs to the
+// older temporary-API-key flow). The minted token is scoped to usage::write on
+// the core voice APIs and expires quickly, so it is safe to hand to the browser.
+//
+// We NEVER fall back to shipping the raw DEEPGRAM_API_KEY: it is full-scope
+// (can create/delete keys, run batch jobs) and never expires, so a fallback
+// would latch a full-power credential into every browser response on the first
+// transient blip. If the grant cannot be minted we fail loudly (the caller
+// 500s) — a temporarily broken voice feature is strictly better than a leaked
+// master key.
+// Docs: https://developers.deepgram.com/reference/token-based-auth-api/grant-token
+
+interface DeepgramGrantResponse {
+  access_token: string;
+  expires_in: number;
+}
+
+// A terminal (non-retryable) grant failure — currently only a 403, meaning the
+// key lacks the required permission. Thrown so it propagates past the retry.
+class DeepgramGrantError extends Error {}
+
+function requestGrant(apiKey: string, ttlSeconds: number): Promise<Response> {
+  return fetch("https://api.deepgram.com/v1/auth/grant", {
+    method: "POST",
+    headers: {
+      Authorization: `Token ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ ttl_seconds: ttlSeconds }),
+  });
+}
+
+export async function mintDeepgramToken(ttlSeconds = 60): Promise<{
+  token: string;
+  expiresAt: number;
+}> {
+  const apiKey = process.env.DEEPGRAM_API_KEY;
+  if (!apiKey) {
+    throw new Error("DEEPGRAM_API_KEY is not set");
+  }
+
+  // One retry for transient failures (5xx / 429 / network). A 403 is a hard
+  // config error and is not retried.
+  let lastError: unknown;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const res = await requestGrant(apiKey, ttlSeconds);
+      if (res.ok) {
+        const data = (await res.json()) as DeepgramGrantResponse;
+        return {
+          token: data.access_token,
+          expiresAt: Date.now() + data.expires_in * 1000,
+        };
+      }
+      if (res.status === 403) {
+        throw new DeepgramGrantError(
+          "Deepgram grant rejected (403): the DEEPGRAM_API_KEY lacks Member " +
+            "permission. Grant it at least Member in the Deepgram console to " +
+            "enable short-lived voice tokens."
+        );
+      }
+      lastError = new Error(
+        `Deepgram grant failed (${res.status}): ${await res
+          .text()
+          .catch(() => "")}`
+      );
+    } catch (err) {
+      if (err instanceof DeepgramGrantError) throw err; // terminal — do not retry
+      lastError = err; // network error — allow one retry
+    }
+  }
+
+  throw new Error(
+    `Deepgram grant unavailable after retry: ${
+      lastError instanceof Error ? lastError.message : String(lastError)
+    }`
+  );
+}

package/src/voice/keyterm-builder.ts

@@ -0,0 +1,426 @@
+import { Database } from "bun:sqlite";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import type { Keyterm, PronunciationOverride } from "@schlessera/brain-ui-sdk/protocol";
+
+const BRAIN_PATH =
+  process.env.BRAIN_PATH || join(process.env.HOME || "/root", "brain");
+
+const DEFAULT_LIMIT = Number(process.env.VOICE_KEYTERM_LIMIT || 500);
+
+const CACHE_PATH = join(
+  process.env.VOICE_CACHE_DIR || join(BRAIN_PATH, ".brain-ui"),
+  "keyterms.json"
+);
+
+// Bump whenever the extractor logic, scoring, or stoplists change so that
+// post-deploy the first request rebuilds the cache instead of serving a
+// stale snapshot baked under the old algorithm.
+const CACHE_VERSION = 2;
+
+const OVERRIDES_PATH = join(BRAIN_PATH, ".voice-overrides.md");
+
+// Common English words to exclude from extracted vocab.
+// Kept short and aggressive — anything ambiguous, drop it.
+const STOPLIST = new Set([
+  "the", "and", "for", "with", "from", "this", "that", "into", "your",
+  "have", "will", "been", "were", "they", "their", "them", "what", "when",
+  "where", "which", "while", "would", "could", "should", "about", "after",
+  "before", "between", "during", "through", "than", "then", "also", "such",
+  "some", "any", "all", "more", "most", "other", "over", "under",
+  "you", "are", "was", "but", "not", "now", "use", "via", "let", "get",
+  "yes", "no", "ok",
+  // common English ALL-CAPS that are not jargon
+  "USA", "UK", "EU", "AM", "PM", "OK", "TV", "DVD", "USB",
+  "NOT", "IT", "JD", "FACTS", "FAQ", "ID", "OS",
+]);
+
+// Generic English nouns/adjectives that frequently appear in tags or
+// document titles but carry no proper-noun signal worth biasing for.
+// Lower-cased compare. A multi-word entry with ANY of these tokens (and no
+// proper-noun tokens) is dropped from titles/tags.
+const GENERIC_TERMS = new Set([
+  "summit", "focus", "schema", "integration", "evolution", "framework",
+  "strategy", "risk", "constraints", "architecture", "development",
+  "interview", "angle", "narrative", "listing", "unique", "key",
+  "takeaways", "title", "options", "core", "recommendation", "practical",
+  "implementation", "technical", "depth", "track", "fit", "reverse", "deep",
+  "dive", "measurement", "challenge", "balanced", "perspective", "global",
+  "relevance", "complexity", "developer", "job", "requisition",
+  "performance", "optimization", "data", "overhaul", "measurement",
+  "managed", "internal", "smart", "search", "vector", "database",
+  "gateway", "engine", "platform", "service", "system", "process",
+  "approach", "method", "concept", "feature", "decision", "summary",
+  "overview", "background", "context", "details", "notes", "content",
+]);
+
+function looksLikeProperNoun(token: string): boolean {
+  if (!token) return false;
+  // ALL-CAPS acronym (>=2 chars)
+  if (/^[A-Z][A-Z0-9-]{1,7}$/.test(token)) return true;
+  // Contains accented/umlaut characters
+  if (/[À-ſ]/.test(token)) return true;
+  // CamelCase (capital after lowercase, e.g. "DiTomaso", "WordPress")
+  if (/[a-z][A-Z]/.test(token)) return true;
+  // Capitalized word that is not a generic common noun
+  if (/^[A-Z][a-z]+$/.test(token) && !GENERIC_TERMS.has(token.toLowerCase())) {
+    return true;
+  }
+  return false;
+}
+
+function hasProperNounSignal(term: string): boolean {
+  const tokens = term.split(/\s+/);
+  return tokens.some(looksLikeProperNoun);
+}
+
+// Stricter check used for multi-word phrases: at least one token must be a
+// real proper-noun-shaped capitalized word (not just an ALL-CAPS acronym),
+// AND no token is a generic common English noun. This rejects phrases like
+// "Listing URL", "Key Takeaways", "Core Narrative" that pass the loose check.
+function isStrongProperNounPhrase(term: string): boolean {
+  const tokens = term.split(/\s+/);
+  if (tokens.length === 1) return looksLikeProperNoun(tokens[0]);
+  let hasNamedToken = false;
+  for (const t of tokens) {
+    if (GENERIC_TERMS.has(t.toLowerCase())) return false;
+    if (
+      /[À-ſ]/.test(t) ||
+      /[a-z][A-Z]/.test(t) ||
+      (/^[A-Z][a-z]{2,}$/.test(t) && !GENERIC_TERMS.has(t.toLowerCase()))
+    ) {
+      hasNamedToken = true;
+    }
+  }
+  return hasNamedToken;
+}
+
+const ALL_CAPS_KEEP = new Set<string>([
+  // Things you DO want even if they look generic
+]);
+
+interface TagRow {
+  name: string;
+}
+
+interface LinkRow {
+  target: string;
+}
+
+export interface BuildOptions {
+  limit?: number;
+  brainPath?: string;
+}
+
+export interface KeytermsCache {
+  version: number;
+  keyterms: string[];
+  generatedAt: number;
+  count: number;
+  overrides: PronunciationOverride[];
+}
+
+function normalize(s: string): string {
+  return s.trim().replace(/\s+/g, " ");
+}
+
+function extractTags(db: Database): Keyterm[] {
+  const rows = db.query("SELECT name FROM tags").all() as TagRow[];
+  const out: Keyterm[] = [];
+  for (const r of rows) {
+    const t = normalize(r.name);
+    if (!t || t.length < 3) continue;
+    if (STOPLIST.has(t.toLowerCase())) continue;
+    if (GENERIC_TERMS.has(t.toLowerCase())) continue;
+    if (!hasProperNounSignal(t)) continue;
+    out.push({ term: t, score: 5, source: "tag" });
+  }
+  return out;
+}
+
+function extractTitles(db: Database): Keyterm[] {
+  const rows = db
+    .query(
+      "SELECT title FROM documents WHERE type IN ('network','project','talk','note','expertise','context')"
+    )
+    .all() as { title: string }[];
+  const out: Keyterm[] = [];
+  for (const { title } of rows) {
+    const t = normalize(title);
+    if (!t || t.length < 4) continue;
+    if (/^(active|archived?|index|key|notable|current)\s/i.test(t)) continue;
+    if (!isStrongProperNounPhrase(t)) continue;
+    out.push({ term: t, score: 4, source: "title" });
+  }
+  return out;
+}
+
+// Curated path hierarchy maps to company/project names. Each subdirectory
+// under these prefixes corresponds to an entity the user actively engages with.
+// These are HUMAN-CURATED whitelists — every entry was added intentionally —
+// so they outrank frequency-derived signals like acronym counts.
+const PATH_PREFIXES: Array<{ prefix: string; score: number }> = [
+  { prefix: "career/opportunities/", score: 14 }, // active interview pipeline
+  { prefix: "projects/active/", score: 13 },
+  { prefix: "projects/catalog/", score: 9 },
+  { prefix: "projects/archive/", score: 5 },
+];
+
+function kebabToTitle(slug: string): string {
+  // Promote known acronym-ish 2-3 char tokens to ALL-CAPS.
+  const acronymHints = new Set([
+    "ai", "ml", "api", "sdk", "cli", "css", "html", "wp", "us", "uk",
+    "eu", "io", "js", "ts", "qa", "hr", "vp",
+  ]);
+  return slug
+    .split("-")
+    .map((tok) => {
+      if (!tok) return tok;
+      if (acronymHints.has(tok.toLowerCase())) return tok.toUpperCase();
+      return tok[0].toUpperCase() + tok.slice(1);
+    })
+    .join(" ");
+}
+
+function extractPaths(db: Database): Keyterm[] {
+  const out: Keyterm[] = [];
+  const seen = new Set<string>();
+  for (const { prefix, score } of PATH_PREFIXES) {
+    const rows = db
+      .query("SELECT DISTINCT path FROM documents WHERE path LIKE ?")
+      .all(`${prefix}%`) as { path: string }[];
+    for (const { path } of rows) {
+      const tail = path.slice(prefix.length);
+      const segment = tail.split("/")[0];
+      if (!segment || segment.startsWith("_")) continue;
+      // Skip files at the prefix root (e.g. an _index.md was filtered above)
+      if (segment.endsWith(".md") || segment.endsWith(".pdf")) continue;
+      const name = kebabToTitle(segment);
+      if (!name || name.length < 2) continue;
+      const key = name.toLowerCase();
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push({ term: name, score, source: "title" });
+    }
+  }
+  return out;
+}
+
+function extractLinks(db: Database): Keyterm[] {
+  const rows = db.query("SELECT DISTINCT target FROM links").all() as LinkRow[];
+  const out: Keyterm[] = [];
+  for (const { target } of rows) {
+    if (!target) continue;
+    if (target.includes("/") || target.startsWith("#")) continue;
+    const t = normalize(target);
+    if (t.length < 3) continue;
+    if (STOPLIST.has(t.toLowerCase())) continue;
+    if (GENERIC_TERMS.has(t.toLowerCase())) continue;
+    if (!hasProperNounSignal(t)) continue;
+    out.push({ term: t, score: 4, source: "link" });
+  }
+  return out;
+}
+
+const BOLD_NAME_RE =
+  /\*\*([A-ZÀ-ſ][\p{L}'.-]+(?:\s+(?:de|von|van|del|la|le|der|den|di)\s+|\s+)[A-ZÀ-ſ][\p{L}'.-]+(?:\s+[A-ZÀ-ſ][\p{L}'.-]+)?)\*\*/gu;
+
+const ACRONYM_RE = /\b([A-Z]{2,8}(?:-[A-Z0-9]{1,4})?)\b/g;
+
+const NETWORK_TYPE = "network";
+// People names from network/ are kept only if they're mentioned this often
+// across the entire brain. Filters out one-off acquaintances, keeps recurring
+// day-job contacts.
+const NETWORK_NAME_MIN_MENTIONS = 3;
+
+interface ContentRow {
+  title: string;
+  content: string;
+  type: string;
+}
+
+function extractFromContent(db: Database): Keyterm[] {
+  const rows = db
+    .query(
+      "SELECT title, content, type FROM documents WHERE asset_type = 'markdown'"
+    )
+    .all() as ContentRow[];
+
+  // Collect bold matches separately by source role
+  const networkNameCandidates = new Set<string>();
+  const otherBoldCounts = new Map<string, number>();
+  const acronymCounts = new Map<string, number>();
+
+  for (const { content, type } of rows) {
+    if (!content) continue;
+
+    for (const m of content.matchAll(BOLD_NAME_RE)) {
+      const name = normalize(m[1]);
+      if (!name) continue;
+      const tokens = name.split(/\s+/);
+      if (tokens.some((t) => STOPLIST.has(t.toLowerCase()))) continue;
+      if (type === NETWORK_TYPE) {
+        networkNameCandidates.add(name);
+      } else {
+        otherBoldCounts.set(name, (otherBoldCounts.get(name) || 0) + 1);
+      }
+    }
+
+    for (const m of content.matchAll(ACRONYM_RE)) {
+      const ac = m[1];
+      if (STOPLIST.has(ac) && !ALL_CAPS_KEEP.has(ac)) continue;
+      acronymCounts.set(ac, (acronymCounts.get(ac) || 0) + 1);
+    }
+  }
+
+  // For each network name candidate, count brain-wide mentions (substring,
+  // word-bounded). Names that don't recur enough are dropped.
+  const networkNameCounts = new Map<string, number>();
+  if (networkNameCandidates.size > 0) {
+    const candidates = [...networkNameCandidates];
+    for (const { content } of rows) {
+      if (!content) continue;
+      for (const name of candidates) {
+        const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const re = new RegExp(`\\b${escaped}\\b`, "g");
+        const matches = content.match(re);
+        if (matches) {
+          networkNameCounts.set(
+            name,
+            (networkNameCounts.get(name) || 0) + matches.length
+          );
+        }
+      }
+    }
+  }
+
+  const out: Keyterm[] = [];
+
+  for (const [term, count] of networkNameCounts) {
+    if (count < NETWORK_NAME_MIN_MENTIONS) continue;
+    if (!isStrongProperNounPhrase(term)) continue;
+    out.push({ term, score: 9 + Math.log2(1 + count), source: "bold" });
+    const tokens = term.split(/\s+/);
+    if (tokens.length >= 2) {
+      const last = tokens[tokens.length - 1];
+      if (
+        last.length >= 4 &&
+        !STOPLIST.has(last.toLowerCase()) &&
+        !GENERIC_TERMS.has(last.toLowerCase()) &&
+        looksLikeProperNoun(last)
+      ) {
+        out.push({
+          term: last,
+          score: 4 + Math.log2(1 + count),
+          source: "bold",
+        });
+      }
+    }
+  }
+
+  for (const [term, count] of otherBoldCounts) {
+    if (count < 1) continue;
+    if (!isStrongProperNounPhrase(term)) continue;
+    out.push({ term, score: 8 + Math.log2(1 + count), source: "bold" });
+  }
+
+  for (const [term, count] of acronymCounts) {
+    if (count < 2) continue;
+    out.push({ term, score: 4 + Math.log2(1 + count), source: "acronym" });
+  }
+  return out;
+}
+
+function dedupeAndRank(terms: Keyterm[], limit: number): string[] {
+  const byTerm = new Map<string, Keyterm>();
+  for (const k of terms) {
+    const key = k.term.toLowerCase();
+    const prev = byTerm.get(key);
+    if (!prev || k.score > prev.score) {
+      byTerm.set(key, k);
+    } else {
+      // accumulate score for repeated finds across sources
+      prev.score += k.score * 0.25;
+    }
+  }
+  const sorted = [...byTerm.values()].sort((a, b) => b.score - a.score);
+  return sorted.slice(0, limit).map((k) => k.term);
+}
+
+export function loadOverrides(): PronunciationOverride[] {
+  if (!existsSync(OVERRIDES_PATH)) return [];
+  try {
+    const md = readFileSync(OVERRIDES_PATH, "utf-8");
+    const out: PronunciationOverride[] = [];
+    for (const line of md.split("\n")) {
+      // Format:  - Doe → DOH   (also accepts "->")
+      const m = line.match(/^\s*-\s+(.+?)\s+(?:→|->)\s+(.+?)\s*$/);
+      if (!m) continue;
+      const match = m[1].trim();
+      const replacement = m[2].trim();
+      if (match && replacement) out.push({ match, replacement });
+    }
+    return out;
+  } catch (err) {
+    console.warn("[voice] Failed to load overrides:", err);
+    return [];
+  }
+}
+
+export function buildKeyterms(opts: BuildOptions = {}): KeytermsCache {
+  const limit = opts.limit ?? DEFAULT_LIMIT;
+  const brainPath = opts.brainPath ?? BRAIN_PATH;
+  const dbPath = join(brainPath, "brain.db");
+
+  if (!existsSync(dbPath)) {
+    throw new Error(`brain.db not found at ${dbPath}`);
+  }
+
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    const all: Keyterm[] = [
+      ...extractTags(db),
+      ...extractTitles(db),
+      ...extractPaths(db),
+      ...extractLinks(db),
+      ...extractFromContent(db),
+    ];
+    const keyterms = dedupeAndRank(all, limit);
+    return {
+      version: CACHE_VERSION,
+      keyterms,
+      generatedAt: Date.now(),
+      count: keyterms.length,
+      overrides: loadOverrides(),
+    };
+  } finally {
+    db.close();
+  }
+}
+
+export function writeCache(cache: KeytermsCache): void {
+  const dir = dirname(CACHE_PATH);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(CACHE_PATH, JSON.stringify(cache, null, 2), "utf-8");
+}
+
+export function readCache(): KeytermsCache | null {
+  if (!existsSync(CACHE_PATH)) return null;
+  try {
+    const cache = JSON.parse(readFileSync(CACHE_PATH, "utf-8")) as KeytermsCache;
+    if (cache.version !== CACHE_VERSION) return null;
+    return cache;
+  } catch {
+    return null;
+  }
+}
+
+export function getKeyterms(forceRebuild = false): KeytermsCache {
+  if (!forceRebuild) {
+    const cached = readCache();
+    if (cached) return cached;
+  }
+  const fresh = buildKeyterms();
+  writeCache(fresh);
+  return fresh;
+}

package/src/voice/speech-providers.ts

@@ -0,0 +1,111 @@
+/**
+ * Server side of the STT seam. A SpeechProvider mints the per-session
+ * connection material the client's matching AsrClient needs. Built-ins:
+ *
+ * - `deepgram`  — mints a short-lived Deepgram token and the full streaming WS
+ *                 URL (base params + domain keyterms baked in).
+ * - `webspeech` — no server session; the browser's SpeechRecognition does the
+ *                 work, so it returns empty url/token.
+ *
+ * VOICE_PROVIDER selects the provider; default is deepgram when
+ * DEEPGRAM_API_KEY is set, else webspeech.
+ */
+
+import type { SpeechProvider } from "@schlessera/brain-ui-sdk/server";
+import { defineSpeechProvider } from "@schlessera/brain-ui-sdk/server";
+import { mintDeepgramToken } from "./deepgram-token.js";
+
+const DEEPGRAM_WS_URL = "wss://api.deepgram.com/v1/listen";
+
+// Match the previous client-side caps: Deepgram nova-3 handles ~500 keyterms
+// semantically, but the WS connect URL has a practical length ceiling.
+const MAX_KEYTERMS = 100;
+const MAX_URL_BYTES = 6000;
+const TOKEN_TTL_SECONDS = 60;
+
+/** Build the full Deepgram streaming URL with base params + capped keyterms. */
+function buildDeepgramUrl(keyterms: string[]): string {
+  const params = new URLSearchParams({
+    model: "nova-3",
+    language: "en",
+    smart_format: "true",
+    interim_results: "true",
+    utterance_end_ms: "1500",
+    vad_events: "true",
+    encoding: "opus",
+    mip_opt_out: "true",
+  });
+  let url = `${DEEPGRAM_WS_URL}?${params.toString()}`;
+  let added = 0;
+  for (const term of keyterms) {
+    if (added >= MAX_KEYTERMS) break;
+    const candidate = `${url}&keyterm=${encodeURIComponent(term)}`;
+    if (candidate.length > MAX_URL_BYTES) break;
+    url = candidate;
+    added++;
+  }
+  return url;
+}
+
+export const deepgramSpeechProvider: SpeechProvider = defineSpeechProvider({
+  id: "deepgram",
+  capabilities: {
+    streaming: true,
+    interimResults: true,
+    keyterms: true,
+    endpointing: true,
+  },
+  async createSession({ keyterms }) {
+    const { token, expiresAt } = await mintDeepgramToken(TOKEN_TTL_SECONDS);
+    return {
+      url: buildDeepgramUrl(keyterms),
+      token,
+      expiresAt,
+    };
+  },
+});
+
+export const webspeechSpeechProvider: SpeechProvider = defineSpeechProvider({
+  id: "webspeech",
+  capabilities: {
+    streaming: true,
+    interimResults: true,
+    keyterms: false,
+    endpointing: false,
+  },
+  async createSession() {
+    // No server session — the browser's SpeechRecognition does everything.
+    return { url: "", expiresAt: 0 };
+  },
+});
+
+/**
+ * Select the active speech provider from env.
+ *
+ * webspeech is OPT-IN ONLY (`VOICE_PROVIDER=webspeech`): on Chromium it streams
+ * microphone audio to Google, so it must never be a silent fallback when the
+ * Deepgram key goes missing. Every other unresolved case throws so the caller
+ * 500s loudly instead of quietly degrading to third-party egress.
+ */
+export function pickSpeechProvider(): SpeechProvider {
+  const configured = process.env.VOICE_PROVIDER?.trim().toLowerCase();
+  if (configured === "webspeech") return webspeechSpeechProvider;
+  if (configured === "deepgram") {
+    if (!process.env.DEEPGRAM_API_KEY) {
+      throw new Error("VOICE_PROVIDER=deepgram but DEEPGRAM_API_KEY is not set.");
+    }
+    return deepgramSpeechProvider;
+  }
+  if (configured) {
+    throw new Error(
+      `Unknown VOICE_PROVIDER="${configured}" (expected "deepgram" or "webspeech").`
+    );
+  }
+  // Auto-detect: Deepgram when its key is present; otherwise fail loudly.
+  if (process.env.DEEPGRAM_API_KEY) return deepgramSpeechProvider;
+  throw new Error(
+    'No speech provider configured. Set DEEPGRAM_API_KEY, or set ' +
+      'VOICE_PROVIDER=webspeech to explicitly opt into the browser speech API ' +
+      "(which streams audio to Google on Chromium)."
+  );
+}