switchroom 0.16.29 → 0.16.46

package/telegram-plugin/voice-ondemand.ts

@@ -0,0 +1,289 @@
+/**
+ * On-demand voice-out (reply_mode='on-demand').
+ *
+ * Instead of synthesizing at reply time, the gateway appends a single
+ * "🔊 Listen" inline button carrying a reserved `voice:<token>` callback_data;
+ * the voice note is synthesized + sent only when the user taps it. Zero
+ * GPU/sidecar work happens unless requested — which keeps the voice pipeline
+ * subscription-honest and visible: nothing is generated behind the user's back
+ * (see reference/vision.md outcome 3, jobs/keep-my-subscription-honest.md and
+ * the local-sidecar voice path).
+ *
+ * This module owns the reserved callback prefix, the token mint, the bounded
+ * TTL LRU cache (keyed by TOKEN because the message_id is not known at send
+ * time), the Listen-button builder, and the collision gate that decides
+ * whether the button may be injected. It is deliberately dependency-free so it
+ * can be unit-tested without importing the 25k-line gateway module.
+ */
+
+import { randomBytes } from 'crypto'
+import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'fs'
+import { dirname } from 'path'
+
+/** Reserved callback_data prefix for on-demand Listen buttons. Handled
+ *  INTERNALLY by the gateway's callback dispatcher (never routed to the agent
+ *  as an inbound), so it must NOT overlap the agent: / auth: / op: families. */
+export const VOICE_ONDEMAND_CALLBACK_PREFIX = 'voice:'
+
+/** Cache entry TTL. A button tapped after this degrades to an "expired" toast
+ *  rather than pinning reply text in memory forever.
+ *
+ *  7 days since #2763 (was 1h): eager pre-synthesis keeps the spoken file on
+ *  disk for 7 days, and the acceptance bar is "tapping Listen on any message
+ *  <7 days old plays instantly" — which needs the ENTRY alive that long too
+ *  (the lazy fallback also reads it). Memory stays bounded by
+ *  VOICE_ONDEMAND_MAX_ENTRIES; the entry is a few hundred bytes of text. */
+export const VOICE_ONDEMAND_TTL_MS = 7 * 24 * 60 * 60 * 1000 // 7 days
+
+/** Bounded cache size; oldest entries are evicted past this. */
+export const VOICE_ONDEMAND_MAX_ENTRIES = 500
+
+export type VoiceOnDemandPayload = {
+  /** Speech-normalized text to synthesize (normalizeForSpeech(reply)). */
+  text: string
+  /** Optional engine-specific voice id. */
+  voice?: string
+  /** Resolved + clamped playback speed. */
+  speed: number
+  /** Absolute path of the eagerly pre-synthesized audio file (#2763), set by
+   *  the pre-synth queue after a successful background synth. Absent on
+   *  pre-feature entries, on kill-switched gateways, and until the job runs. */
+  filePath?: string
+  /** Epoch ms the entry was stored (put time) — recorded alongside filePath
+   *  per #2763 so the sweep/introspection can reason about entry age. */
+  createdAt?: number
+}
+
+type StoredEntry = VoiceOnDemandPayload & { expiresAt: number }
+
+/** On-disk shape of the persisted cache: a versioned envelope around the
+ *  token→entry map. Versioned so a future schema change can be detected and
+ *  discarded rather than mis-parsed. */
+type PersistedCache = {
+  version: 1
+  entries: Record<string, StoredEntry>
+}
+
+/**
+ * Options for {@link VoiceOnDemandCache}. `persistPath`, when set, backs the
+ * cache with a JSON file so Listen tokens survive a gateway restart — a button
+ * tapped after a restart still synthesizes instead of degrading to "Voice
+ * expired". Omit it (the default) for a pure in-memory cache.
+ */
+export type VoiceOnDemandCacheOptions = {
+  ttlMs?: number
+  maxEntries?: number
+  now?: () => number
+  /** Absolute path to the JSON persistence file (e.g. under TELEGRAM_STATE_DIR,
+   *  which lives on a volume that survives container recreation). When set, the
+   *  cache loads existing (non-expired) entries on construction and rewrites the
+   *  file on every mutation. */
+  persistPath?: string
+}
+
+/**
+ * Bounded, TTL'd LRU cache from Listen token → synthesis payload. Keyed by
+ * token (not message_id) because the message_id isn't known when the button
+ * is sent. A Map preserves insertion order, so the first key is the oldest.
+ *
+ * Optionally durable: pass `persistPath` to back the store with a JSON file so
+ * tokens survive a gateway restart. Persistence uses a synchronous
+ * write-to-temp + atomic rename on each mutation — the store is small (≤
+ * maxEntries) and writes are infrequent (one per reply that offers a Listen
+ * button), so the cost is negligible and the module stays dependency-free.
+ * Any load/write error is swallowed (logged to stderr): a broken persistence
+ * file must never take the gateway down — the cache simply degrades to the old
+ * in-memory behaviour.
+ */
+export class VoiceOnDemandCache {
+  private readonly store = new Map<string, StoredEntry>()
+  private readonly ttlMs: number
+  private readonly maxEntries: number
+  private readonly now: () => number
+  private readonly persistPath: string | undefined
+
+  constructor(options: VoiceOnDemandCacheOptions = {}) {
+    this.ttlMs = options.ttlMs ?? VOICE_ONDEMAND_TTL_MS
+    this.maxEntries = options.maxEntries ?? VOICE_ONDEMAND_MAX_ENTRIES
+    this.now = options.now ?? Date.now
+    this.persistPath = options.persistPath
+    if (this.persistPath !== undefined) this.load()
+  }
+
+  /** Store a payload under `token`, evicting the oldest entries past the cap. */
+  put(token: string, payload: VoiceOnDemandPayload): void {
+    // Re-insert to move an existing key to the newest (most-recent) position.
+    this.store.delete(token)
+    this.store.set(token, {
+      createdAt: this.now(),
+      ...payload,
+      expiresAt: this.now() + this.ttlMs,
+    })
+    while (this.store.size > this.maxEntries) {
+      const oldest = this.store.keys().next().value
+      if (oldest === undefined) break
+      this.store.delete(oldest)
+    }
+    this.flush()
+  }
+
+  /** Look up a payload; returns null on miss or expiry (and evicts expired). */
+  get(token: string): VoiceOnDemandPayload | null {
+    const entry = this.store.get(token)
+    if (entry == null) return null
+    if (entry.expiresAt <= this.now()) {
+      this.store.delete(token)
+      this.flush()
+      return null
+    }
+    const { text, voice, speed, filePath } = entry
+    // createdAt stays internal (persisted for sweep/introspection) so the
+    // returned shape only grows when a pre-synth file actually exists —
+    // pre-#2763 callers and tests see the exact old payload.
+    return {
+      text,
+      speed,
+      ...(voice !== undefined ? { voice } : {}),
+      ...(filePath !== undefined ? { filePath } : {}),
+    }
+  }
+
+  /** Record the pre-synthesized audio file path on an existing entry (#2763).
+   *  No-op if the entry has expired or been evicted meanwhile (the file will
+   *  simply age out via the sweep). Does NOT bump LRU position or TTL — the
+   *  entry's lifetime is anchored at put time. */
+  setFilePath(token: string, filePath: string): void {
+    const entry = this.store.get(token)
+    if (entry == null || entry.expiresAt <= this.now()) return
+    entry.filePath = filePath
+    this.flush()
+  }
+
+  /** Drop entries whose pre-synth files the sweep deleted (#2763). Unknown
+   *  tokens are ignored (file may belong to an already-evicted entry). */
+  prune(tokens: Iterable<string>): void {
+    let changed = false
+    for (const token of tokens) {
+      if (this.store.delete(token)) changed = true
+    }
+    if (changed) this.flush()
+  }
+
+  /** Current entry count (test/introspection aid). */
+  get size(): number {
+    return this.store.size
+  }
+
+  /** Load persisted entries, dropping any already expired. Best-effort: a
+   *  missing or corrupt file leaves the cache empty (fresh-start). */
+  private load(): void {
+    if (this.persistPath === undefined) return
+    let raw: string
+    try {
+      raw = readFileSync(this.persistPath, 'utf8')
+    } catch {
+      // No file yet (first boot) — nothing to load.
+      return
+    }
+    try {
+      const parsed = JSON.parse(raw) as PersistedCache
+      if (parsed == null || parsed.version !== 1 || typeof parsed.entries !== 'object') return
+      const nowMs = this.now()
+      // Object.entries preserves insertion order for string keys, which is the
+      // insertion order we wrote — so LRU ordering survives the round-trip.
+      for (const [token, entry] of Object.entries(parsed.entries)) {
+        if (
+          entry == null ||
+          typeof entry.expiresAt !== 'number' ||
+          typeof entry.text !== 'string' ||
+          typeof entry.speed !== 'number'
+        ) {
+          continue
+        }
+        if (entry.expiresAt <= nowMs) continue // already expired — drop
+        this.store.set(token, entry)
+      }
+      // Honour the cap in case the file predates a smaller maxEntries.
+      while (this.store.size > this.maxEntries) {
+        const oldest = this.store.keys().next().value
+        if (oldest === undefined) break
+        this.store.delete(oldest)
+      }
+    } catch (err) {
+      process.stderr.write(
+        `voice-ondemand: failed to parse persisted cache ${this.persistPath}: ${String(err)}\n`,
+      )
+    }
+  }
+
+  /** Write the current store to disk atomically. No-op when not persisting. */
+  private flush(): void {
+    if (this.persistPath === undefined) return
+    const doc: PersistedCache = {
+      version: 1,
+      entries: Object.fromEntries(this.store),
+    }
+    const tmp = `${this.persistPath}.tmp`
+    try {
+      mkdirSync(dirname(this.persistPath), { recursive: true })
+      writeFileSync(tmp, JSON.stringify(doc), 'utf8')
+      renameSync(tmp, this.persistPath)
+    } catch (err) {
+      process.stderr.write(
+        `voice-ondemand: failed to persist cache ${this.persistPath}: ${String(err)}\n`,
+      )
+    }
+  }
+}
+
+/** Mint a short, unguessable Listen token (8 hex chars). */
+export function mintVoiceOnDemandToken(): string {
+  return randomBytes(4).toString('hex')
+}
+
+/** True iff `data` is an on-demand Listen callback (must be routed
+ *  internally, before agent: routing). */
+export function isVoiceOnDemandCallback(data: string): boolean {
+  return data.startsWith(VOICE_ONDEMAND_CALLBACK_PREFIX)
+}
+
+/** Extract the token from a `voice:<token>` callback_data, or null. */
+export function parseVoiceOnDemandToken(data: string): string | null {
+  if (!isVoiceOnDemandCallback(data)) return null
+  const token = data.slice(VOICE_ONDEMAND_CALLBACK_PREFIX.length)
+  return token.length > 0 ? token : null
+}
+
+/** Build the single-row Listen keyboard for a token. Effectively single-use:
+ *  the callback handler strips this keyboard after a SUCCESSFUL synth+send, so
+ *  a delivered voice note can't be re-tapped. On expiry / synth-failure /
+ *  sidecar-unavailable the button is left intact so the user can retry. */
+export function buildListenKeyboard(token: string): {
+  inline_keyboard: Array<Array<{ text: string; callback_data: string }>>
+} {
+  return {
+    inline_keyboard: [
+      [{ text: '🔊 Listen', callback_data: `${VOICE_ONDEMAND_CALLBACK_PREFIX}${token}` }],
+    ],
+  }
+}
+
+/**
+ * Collision gate: the Listen button may be injected ONLY when the reply
+ * carries no agent-authored buttons.
+ *
+ * Why: the callback dispatcher's single_use strip (keyboardIsSingleUse)
+ * governs the WHOLE message's keyboard, keyed off the agent-button metadata.
+ * The Listen button strips its own keyboard independently (on successful
+ * send, in the voice-on-demand callback handler) and carries no agent-button
+ * meta; mixing it alongside agent buttons would put two independent strip
+ * regimes on one message and could defeat the agent's double-fire protection.
+ * So if the agent supplied any button, we skip the Listen button for this
+ * message.
+ */
+export function mayInjectListenButton(
+  rawKeyboard: unknown[][] | undefined | null,
+): boolean {
+  if (rawKeyboard == null) return true
+  return !rawKeyboard.some((row) => Array.isArray(row) && row.length > 0)
+}

package/telegram-plugin/voice-presynth.ts

@@ -0,0 +1,242 @@
+/**
+ * Eager voice pre-synthesis + rolling voice-cache cleanup (issue #2763).
+ *
+ * When an outbound reply becomes Listen-eligible (a voiceOnDemandCache entry
+ * is persisted for its 🔊 Listen button), the gateway ALSO kicks an async
+ * background synthesis of the normalized text via the LOCAL sidecar (kokoro
+ * only — never the cloud engine, which costs money and stays lazy-only). The
+ * resulting OGG lands on disk under TELEGRAM_STATE_DIR/voice-cache/ and its
+ * path is recorded on the cache entry, so a Listen tap attaches the pre-made
+ * file instantly instead of synthesizing on demand.
+ *
+ * This module owns the two dependency-free primitives:
+ *
+ *   - {@link PreSynthQueue} — a bounded FIFO (concurrency 1, drop-oldest past
+ *     the backlog cap) so message bursts can't pile up GPU synth jobs.
+ *   - {@link sweepVoiceCacheDir} — the 7-day TTL + size-budget sweep that
+ *     keeps the voice-cache directory from growing unbounded.
+ *
+ * Kill switch: SWITCHROOM_DISABLE_EAGER_VOICE=1 reverts to lazy-only synth
+ * (no pre-synth jobs, no new files). The sweep still runs under the kill
+ * switch so previously written files age out.
+ *
+ * Strictly off the reply critical path: enqueue is a synchronous array push;
+ * the drain is async and never awaited by the reply flow; every job failure
+ * is swallowed (logged) — a synth failure can never affect message delivery.
+ */
+
+import { readdirSync, statSync, unlinkSync, mkdirSync, writeFileSync, renameSync } from 'fs'
+import { join } from 'path'
+
+/** Voice files older than this are deleted by the rolling sweep. */
+export const VOICE_FILE_TTL_MS = 7 * 24 * 60 * 60 * 1000 // 7 days
+
+/** Size budget for the voice-cache dir; oldest files are deleted first when
+ *  the directory exceeds this (defence in depth if the timer dies and the
+ *  boot sweep is far away). ~500MB per the #2763 design notes. */
+export const VOICE_CACHE_MAX_BYTES = 500 * 1024 * 1024
+
+/** Backlog cap for the pre-synth FIFO. Past this, the OLDEST pending job is
+ *  dropped (newer replies are the ones the user is most likely to tap). */
+export const PRESYNTH_MAX_PENDING = 50
+
+/** Sweep cadence: hourly, plus one sweep at gateway boot. */
+export const VOICE_SWEEP_INTERVAL_MS = 60 * 60 * 1000
+
+/** True unless the operator flipped the kill switch. Same env shape as
+ *  SWITCHROOM_DISABLE_TTS_NORMALIZE / SWITCHROOM_DISABLE_VOICE_SCRUB. */
+export function eagerVoiceEnabled(): boolean {
+  const kill = process.env.SWITCHROOM_DISABLE_EAGER_VOICE
+  return !(kill === '1' || kill === 'true')
+}
+
+export type PreSynthJob = {
+  /** Listen token — doubles as the on-disk filename stem (`<token>.ogg`). */
+  token: string
+  /** Speech-normalized text to synthesize (same payload the lazy path uses). */
+  text: string
+  voice?: string
+  speed?: number
+}
+
+export type PreSynthQueueOptions = {
+  /** Runs ONE job: synthesize + persist + record. Errors are swallowed. */
+  runJob: (job: PreSynthJob) => Promise<void>
+  maxPending?: number
+  /** Injected scheduler (tests). Defaults to setTimeout(fn, 0). */
+  defer?: (fn: () => void) => void
+  log?: (line: string) => void
+}
+
+/**
+ * Bounded FIFO pre-synth queue, concurrency 1. Jobs are drained strictly in
+ * order; past `maxPending` queued jobs the oldest pending job is dropped
+ * (drop-oldest). Enqueue is synchronous and never throws; the drain kicks off
+ * via a deferred callback so the reply flow that enqueued is never blocked.
+ */
+export class PreSynthQueue {
+  private readonly pending: PreSynthJob[] = []
+  private running = false
+  private readonly runJob: (job: PreSynthJob) => Promise<void>
+  private readonly maxPending: number
+  private readonly defer: (fn: () => void) => void
+  private readonly log: (line: string) => void
+
+  constructor(options: PreSynthQueueOptions) {
+    this.runJob = options.runJob
+    this.maxPending = options.maxPending ?? PRESYNTH_MAX_PENDING
+    this.defer = options.defer ?? ((fn) => setTimeout(fn, 0))
+    this.log = options.log ?? ((line) => process.stderr.write(line + '\n'))
+  }
+
+  /** Number of queued (not yet started) jobs — test/introspection aid. */
+  get size(): number {
+    return this.pending.length
+  }
+
+  /** True while a job is in flight. */
+  get busy(): boolean {
+    return this.running
+  }
+
+  /** Enqueue a job. Never throws; never blocks the caller. */
+  enqueue(job: PreSynthJob): void {
+    this.pending.push(job)
+    while (this.pending.length > this.maxPending) {
+      const dropped = this.pending.shift()
+      if (dropped != null) {
+        this.log(
+          `voice-presynth: backlog over ${this.maxPending} — dropped oldest job token=${dropped.token}`,
+        )
+      }
+    }
+    if (!this.running) {
+      this.running = true
+      this.defer(() => void this.drain())
+    }
+  }
+
+  private async drain(): Promise<void> {
+    for (;;) {
+      const job = this.pending.shift()
+      if (job == null) break
+      try {
+        await this.runJob(job)
+      } catch (err) {
+        // Best-effort by contract: a failed pre-synth only means the Listen
+        // tap falls back to the lazy path. Never propagate.
+        this.log(`voice-presynth: job failed token=${job.token}: ${String(err)}`)
+      }
+    }
+    this.running = false
+  }
+}
+
+/** Absolute path of the pre-synthesized file for a Listen token. */
+export function voiceCacheFilePath(dir: string, token: string): string {
+  return join(dir, `${token}.ogg`)
+}
+
+/** Atomically persist synthesized audio for `token` under `dir`; returns the
+ *  final path. Throws on IO failure (caller — the queue runner — swallows). */
+export function writeVoiceCacheFile(dir: string, token: string, audio: Uint8Array): string {
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const final = voiceCacheFilePath(dir, token)
+  const tmp = `${final}.tmp`
+  writeFileSync(tmp, audio)
+  renameSync(tmp, final)
+  return final
+}
+
+/** Minimal fs facade so the sweep is testable without a real 500MB dir. */
+export type SweepFs = {
+  readdirSync: (dir: string) => string[]
+  statSync: (path: string) => { mtimeMs: number; size: number; isFile(): boolean }
+  unlinkSync: (path: string) => void
+}
+
+export type SweepOptions = {
+  dir: string
+  ttlMs?: number
+  maxBytes?: number
+  now?: () => number
+  fs?: SweepFs
+  log?: (line: string) => void
+}
+
+export type SweepResult = {
+  /** Listen tokens whose files were deleted (filename stem, `.ogg` stripped) —
+   *  the caller prunes the matching voiceOnDemandCache entries. */
+  deletedTokens: string[]
+  /** Total bytes remaining in the dir after the sweep. */
+  remainingBytes: number
+}
+
+/**
+ * Rolling voice-cache sweep: delete files older than `ttlMs` (7 days), then —
+ * if the directory still exceeds `maxBytes` — delete oldest-first down to
+ * budget. Crash-safe: a missing dir yields an empty result; a file that
+ * vanishes mid-sweep (concurrent delete) is tolerated; per-file errors never
+ * abort the sweep.
+ */
+export function sweepVoiceCacheDir(options: SweepOptions): SweepResult {
+  const ttlMs = options.ttlMs ?? VOICE_FILE_TTL_MS
+  const maxBytes = options.maxBytes ?? VOICE_CACHE_MAX_BYTES
+  const now = options.now ?? Date.now
+  const fsx: SweepFs = options.fs ?? { readdirSync, statSync, unlinkSync }
+  const log = options.log ?? ((line: string) => process.stderr.write(line + '\n'))
+
+  let names: string[]
+  try {
+    names = fsx.readdirSync(options.dir)
+  } catch {
+    return { deletedTokens: [], remainingBytes: 0 } // no dir yet — nothing to sweep
+  }
+
+  type Entry = { name: string; path: string; mtimeMs: number; size: number }
+  const files: Entry[] = []
+  for (const name of names) {
+    const path = join(options.dir, name)
+    try {
+      const st = fsx.statSync(path)
+      if (!st.isFile()) continue
+      files.push({ name, path, mtimeMs: st.mtimeMs, size: st.size })
+    } catch {
+      // vanished mid-sweep / unreadable — skip, never abort
+    }
+  }
+
+  const deletedTokens: string[] = []
+  const cutoff = now() - ttlMs
+  const remove = (f: Entry, reason: string): boolean => {
+    try {
+      fsx.unlinkSync(f.path)
+    } catch {
+      // Already gone (concurrent delete) — treat as removed either way; a
+      // truly stuck file just gets retried next sweep.
+    }
+    deletedTokens.push(f.name.replace(/\.(ogg|ogg\.tmp)$/, ''))
+    log(`voice-presynth: sweep removed ${f.name} (${reason})`)
+    return true
+  }
+
+  // Pass 1 — TTL: anything older than 7 days goes (including orphaned .tmp).
+  let kept: Entry[] = []
+  for (const f of files) {
+    if (f.mtimeMs <= cutoff) remove(f, 'ttl')
+    else kept.push(f)
+  }
+
+  // Pass 2 — size budget: oldest-first down to maxBytes.
+  let total = kept.reduce((sum, f) => sum + f.size, 0)
+  if (total > maxBytes) {
+    kept.sort((a, b) => a.mtimeMs - b.mtimeMs)
+    while (total > maxBytes && kept.length > 0) {
+      const oldest = kept.shift()!
+      remove(oldest, 'size-budget')
+      total -= oldest.size
+    }
+  }
+
+  return { deletedTokens, remainingBytes: total }
+}