switchroom 0.18.32 → 0.19.0

package/telegram-plugin/gateway/turn-start-surfaces.ts

@@ -0,0 +1,298 @@
+/**
+ * turn-start-surfaces.ts — the turn-START surfaces block (#2996 P8 PR-D).
+ *
+ * Extracted VERBATIM from gateway.ts `handleInbound` (the status-reaction
+ * controller install + fresh-turn init + progress-card `startTurn`): the
+ * steer/queue ack reactions, the fresh-turn StatusReactionController install
+ * (incl. the #472-finding-17 prior-draft finalize await — load-bearing, kept
+ * at the same await point), the silence-poke / signal-tracker / typing-loop
+ * arming, and the progress-card `startTurn`.
+ *
+ * Why a single extracted surface, called ONCE on the shared tail: P7's inbound
+ * router (`SWITCHROOM_INBOUND_ROUTER_V2`) branches only at the intercept
+ * gauntlet (the v2 chain in inbound-router.ts vs the retained legacy inline
+ * arm) and both arms re-converge BEFORE this block. Extracting it and calling
+ * it from that shared convergence point means the v2 and legacy routing modes
+ * run byte-identical turn-start surfaces — the design's "called from both
+ * arms" acceptance criterion, satisfied structurally (a flip of the router
+ * flag cannot fork turn-start behaviour because there is one implementation).
+ *
+ * DI contract (the turn-end.ts / stream-render precedent): STATE stays in
+ * gateway.ts; this module owns only the logic. Mutable stores, live singletons
+ * and gateway-bound helpers arrive through `TurnStartSurfacesDeps`
+ * (`gatewayTurnStartSurfacesDeps()` in gateway.ts — exact-by-construction via
+ * `ReturnType`). The volatile `currentTurn` read (the mid-turn auto-classify
+ * shadow) crosses as `getCurrentTurn()` so it sees the live value (the P9
+ * getter funnel, cluster for turn-start reads). Pure imports
+ * (`StatusReactionController`, `autoClassifyMidTurnInbound`) come in directly.
+ */
+import type { ReactionTypeEmoji } from 'grammy/types'
+import type { Access, TurnStartSurfacesDeps } from './gateway.js'
+import { StatusReactionController } from '../status-reactions.js'
+import { autoClassifyMidTurnInbound } from './auto-classify-mid-turn.js'
+
+/** At-call captured facts the turn-start surfaces need. Every field is a
+ *  value snapshotted at the handler's convergence point (never a live getter);
+ *  the one live read (`currentTurn`) is funnelled through the deps getter. */
+export interface TurnStartSurfacesParams {
+  chat_id: string
+  msgId: number | undefined
+  messageThreadId: number | undefined
+  text: string
+  effectiveText: string
+  access: Access
+  inboundReceivedAt: number
+  isSteerPrefix: boolean
+  isQueuedPrefix: boolean
+}
+
+/** What the block computes for the downstream envelope/delivery path:
+ *  `isSteering` (explicit /steer or /s) and `priorTurnStartedAt` (the prior
+ *  in-flight turn's start, undefined on a fresh turn). */
+export interface TurnStartSurfacesResult {
+  isSteering: boolean
+  priorTurnStartedAt: number | undefined
+}
+
+export function createTurnStartSurfaces(deps: TurnStartSurfacesDeps) {
+  const {
+    AUTOCLASSIFY_MIDTURN_SHADOW,
+    getCurrentTurn,
+    statusKey,
+    streamKey,
+    isDmChatId,
+    sendReaction,
+    logStreamingEvent,
+    probeAvailableReactions,
+    startTurnTypingLoop,
+    emitRuntimeMetric,
+    classifyInbound,
+    resolveAgentDirFromEnv,
+    addActiveReaction,
+    signalTracker,
+    silencePoke,
+    pendingProgress,
+    progressDriver,
+    activeStatusReactions,
+    activeTurnStartedAt,
+    lastAgentOutputAt,
+    activeDraftStreams,
+    suppressPtyPreview,
+    chatAvailableReactions,
+    reactionTransitionCounts,
+    activeReactionMsgIds,
+    progressUpdateTurnCount,
+  } = deps
+
+  async function armTurnStartSurfaces(
+    p: TurnStartSurfacesParams,
+  ): Promise<TurnStartSurfacesResult> {
+    const { chat_id, msgId, messageThreadId, text, effectiveText, access, inboundReceivedAt, isSteerPrefix, isQueuedPrefix } = p
+    // Status reaction controller
+    let isSteering = false
+    let priorTurnStartedAt: number | undefined
+    if (msgId != null) {
+      const key = statusKey(chat_id, messageThreadId)
+      const priorActive = activeStatusReactions.get(key)
+      const priorTurnInFlight = priorActive != null
+      // New default: mid-turn messages are queued unless the user explicitly
+      // steers. isSteering is true only when the steer prefix is present.
+      // (Legacy: without any prefix the old behavior was isSteering=true; now
+      // it's false so the message goes through as queued="true".)
+      isSteering = priorTurnInFlight && isSteerPrefix
+      if (priorTurnInFlight) priorTurnStartedAt = activeTurnStartedAt.get(key)
+
+      // Mid-turn auto-classify SHADOW: compute what a topic+recency classifier
+      // WOULD decide and log it — behaviour is UNCHANGED (isSteering above is
+      // untouched). Gathers the real-world distribution (same-topic continuation
+      // vs cross-topic, recency spread) to tune auto-steer before it ever acts.
+      // No-op unless the shadow flag is on AND a turn is in flight (the only case
+      // a steer-vs-queue decision is meaningful).
+      if (AUTOCLASSIFY_MIDTURN_SHADOW && priorTurnInFlight) {
+        const lastOut = lastAgentOutputAt.get(key)
+        const msSinceOut = lastOut != null ? Date.now() - lastOut : null
+        const shadow = autoClassifyMidTurnInbound({
+          isSteerPrefix,
+          isQueuePrefix: isQueuedPrefix,
+          priorTurnInFlight,
+          isDm: isDmChatId(chat_id),
+          incomingThreadId: messageThreadId ?? null,
+          activeTurnThreadId: getCurrentTurn()?.sessionThreadId ?? null,
+          msSinceLastAgentOutput: msSinceOut,
+          dmSteerWindowMs: 0, // DM auto-steer stays off (the April regime)
+          topicSteerWindowMs: 8_000, // candidate window — what we're tuning
+        })
+        process.stderr.write(
+          `telegram gateway: autoclassify-shadow chat_id=${chat_id} ` +
+          `would=${shadow.decision} reason=${shadow.reason} same_topic=${shadow.sameTopic ?? '-'} ` +
+          `ms_since_out=${msSinceOut ?? '-'} actual=${isSteering ? 'steer' : 'queue'}\n`,
+        )
+      }
+
+      if (access.statusReactions !== false) {
+        if (isSteering) {
+          // Explicit steer: mark with 🤝 on the inbound message; leave the
+          // existing StatusReactionController running for the in-flight turn.
+          void sendReaction(chat_id, msgId, '🤝').catch(() => {})
+        } else if (priorTurnInFlight) {
+          // Queued mid-turn message (new default): don't touch the existing
+          // controller; just ack the inbound message with 👀 so the user
+          // knows we received it, without disrupting the in-flight reaction.
+          void sendReaction(chat_id, msgId, '👀').catch(() => {})
+          // #203: time-to-ack metric — measure gateway-receive → ack-post delta.
+          logStreamingEvent({ kind: 'inbound_ack', chatId: chat_id, messageId: msgId, ackDelayMs: Date.now() - inboundReceivedAt })
+        } else {
+          // Fresh turn — priorTurnInFlight is false, so priorActive is
+          // provably undefined. Earlier `if (priorActive)` block was dead
+          // code, removed in the same first-paint cleanup pass.
+          const sKey = streamKey(chat_id, messageThreadId)
+          const priorStream = activeDraftStreams.get(sKey)
+          if (priorStream && !priorStream.isFinal()) {
+            // Closes #472 finding #17 — pre-fix this finalize was
+            // fire-and-forget. The new turn's reply tool would then create
+            // a fresh stream and send its first chunk while the prior
+            // stream's terminal sendMessage was still in flight. The
+            // late-materialise landed AFTER the new turn's content,
+            // visible to the user as a stale "Done" message followed by
+            // the new reply (or worse — duplicate content).
+            //
+            // Awaiting here costs the few hundred ms the final API call
+            // takes, but only on rapid follow-ups where the prior turn
+            // hadn't yet flushed. The latency hit beats the duplicate-
+            // content bug. Delete from the map FIRST so any concurrent
+            // reads can't see the stale stream while we await.
+            activeDraftStreams.delete(sKey)
+            await priorStream.finalize().catch(() => {})
+          }
+          suppressPtyPreview.delete(sKey)
+
+          // #542 fix: pass the cached chat-level allowed-reactions filter
+          // so the controller's resolveEmoji can fall through to a permitted
+          // variant instead of attempting an emoji Telegram will reject.
+          // First message in a chat sees `null` (cache miss) — kicks off
+          // the probe for next time.
+          const allowedReactions = chatAvailableReactions.get(chat_id) ?? null
+          if (!chatAvailableReactions.has(chat_id)) {
+            probeAvailableReactions(chat_id)
+          }
+          // #2527: use inbound msgId as a stable per-turn reaction identifier.
+          // The controller is created before currentTurn.turnId is assigned
+          // (that happens in handleSessionEvent's enqueue branch), so we capture
+          // msgId here and use it as the reaction-session token in log events.
+          const ctrlTurnToken = `${chat_id}:${msgId}`
+          const ctrl = new StatusReactionController(async (emoji) => {
+            await sendReaction(chat_id, msgId, emoji as ReactionTypeEmoji['emoji'])
+            // #203: every status-reaction transition is a user-visible signal.
+            signalTracker.noteSignal(key, Date.now())
+          }, allowedReactions, {
+            // #2527: emit a structured transition event on each emoji change so
+            // the reaction lifecycle is visible in streaming-metrics logs. Also
+            // increment the per-key counter for the turn_no_reply_warn metric.
+            onTransition: (emoji) => {
+              reactionTransitionCounts.set(key, (reactionTransitionCounts.get(key) ?? 0) + 1)
+              logStreamingEvent({
+                kind: 'status_reaction_transition',
+                chatId: chat_id,
+                turnId: ctrlTurnToken,
+                emoji,
+              })
+            },
+          })
+          activeStatusReactions.set(key, ctrl)
+          activeReactionMsgIds.set(key, { chatId: chat_id, messageId: msgId })
+          activeTurnStartedAt.set(key, Date.now())
+          progressUpdateTurnCount.set(key, 0)  // Reset turn counter
+          // #2527: log controller install so the lifecycle start is observable.
+          logStreamingEvent({
+            kind: 'status_reaction_install',
+            chatId: chat_id,
+            turnId: ctrlTurnToken,
+            messageId: msgId,
+          })
+          ctrl.setQueued()
+          // #203: time-to-ack metric — setQueued() triggers the initial 👀 reaction
+          // asynchronously through the controller chain.
+          logStreamingEvent({ kind: 'inbound_ack', chatId: chat_id, messageId: msgId, ackDelayMs: Date.now() - inboundReceivedAt })
+          // #203: signal tracker — start tracking silent gaps for this fresh turn.
+          signalTracker.reset(statusKey(chat_id, messageThreadId), Date.now())
+          // #1122 silence-poke: start the silence clock for this turn so
+          // the framework can nudge the model if it goes quiet past the
+          // soft / firm thresholds.
+          silencePoke.startTurn(statusKey(chat_id, messageThreadId), Date.now())
+          // Ack-first gate clear is centralised in handleSessionEvent's
+          // `enqueue` branch — that fires for EVERY fresh turn atom
+          // (real inbound, cron, subagent-handback, vault-grant wake,
+          // restart marker) so cron/handback turns also re-arm the gate.
+          // See the call site under `case 'enqueue'` (~line 6794).
+          // #1445 cross-turn pending-async ambient. A new turn starting
+          // (user inbound, synthesised wake, or handback channel) is the
+          // signal that the model is about to re-engage — clear any
+          // pending-progress edits anchored to the *prior* turn's
+          // outbound so the framework stops talking over the new turn.
+          // clearPending drops the per-key state outright, so the new
+          // turn's `tool_use(Agent|Task|Bash bg)` + outbound capture
+          // afresh via `noteAsyncDispatch` / `noteOutbound`.
+          pendingProgress.clearPending(
+            statusKey(chat_id, messageThreadId),
+            'inbound',
+          )
+          // Human-feel UX: hold a continuous `typing…` indicator for the
+          // WHOLE turn, not just the split-second a reply is transmitted.
+          // A person you message shows as typing the entire time they
+          // compose; switchroom used to fire only one-shot ~5s pings, so
+          // any turn that read a file or thought for a moment went dark
+          // after 5s. Self-renews every 4s; stopped at the canonical
+          // turn-end (`purgeReactionTracking → stopTurnTypingLoop`).
+          // Deterministic, framework-owned, no prose — the mechanical
+          // ambient layer of the pacing contract.
+          // PR3 supergroup-mode: pass thread so the indicator lands in
+          // this turn's topic (otherwise topic A's turn-end would kill
+          // topic B's typing indicator on shared chat_id keying).
+          startTurnTypingLoop(chat_id, messageThreadId ?? null)
+          // #1122 KPI: emit turn_started so dashboards can compute funnel
+          // start counts + correlate to turn_ended for duration / TTFO.
+          emitRuntimeMetric({
+            kind: 'turn_started',
+            chat_id,
+            message_id: msgId,
+            thread_id: messageThreadId ?? null,
+            inbound_classified_as_status_query: classifyInbound(text).isStatusQuery,
+          })
+          const agentDir = resolveAgentDirFromEnv()
+          if (agentDir != null) {
+            addActiveReaction(agentDir, { chatId: chat_id, messageId: msgId, threadId: messageThreadId ?? null, reactedAt: Date.now() })
+          }
+        }
+      } else if (access.ackReaction) {
+        void sendReaction(chat_id, msgId, access.ackReaction as ReactionTypeEmoji['emoji']).catch(() => {})
+        // #203: time-to-ack metric for the custom-ack-reaction path.
+        logStreamingEvent({ kind: 'inbound_ack', chatId: chat_id, messageId: msgId, ackDelayMs: Date.now() - inboundReceivedAt })
+      }
+    }
+
+    // Start a new progress card only for fresh turns (no prior turn in flight).
+    // Queued mid-turn messages piggyback on the existing card; steer messages
+    // also don't start a new card (the in-flight turn owns it).
+    if (!isSteering && priorTurnStartedAt == null) {
+      try {
+        progressDriver?.startTurn({
+          chatId: chat_id,
+          threadId: messageThreadId != null ? String(messageThreadId) : undefined,
+          userText: effectiveText,
+          replyToMessageId: msgId != null ? msgId : undefined,
+        })
+      } catch (err) {
+        process.stderr.write(`telegram gateway: progress-card startTurn failed: ${(err as Error).message}\n`)
+      }
+
+      // Pre-allocated draft + forum-topic placeholder send removed in
+      // #553 PR 5. The 👀 status reaction (#568) and
+      // sendChatAction('typing') indicator (#585) now bridge the
+      // ~1s gap between inbound and the agent's first real text.
+    }
+
+    return { isSteering, priorTurnStartedAt }
+  }
+
+  return { armTurnStartSurfaces }
+}

package/telegram-plugin/gateway/vault-request-access-card.ts

@@ -63,3 +63,19 @@ export function renderVaultRequestAccessCard(
   // direct via richMessage, bypassing the switchroomReply chokepoint.
   return hardenCardBreaks(lines.join('\n'))
 }
+
+/**
+ * Inline keyboard for the vault-access request card (#1012). Callback prefix
+ * `vra:`, handled by handleVaultRequestAccessCallback in
+ * callback-query-handlers.ts. Extracted verbatim from gateway.ts (#2996 P5).
+ */
+export function buildVaultRequestAccessKeyboard(stageId: string): { inline_keyboard: Array<Array<{ text: string; callback_data: string }>> } {
+  return {
+    inline_keyboard: [
+      [
+        { text: '✅ Approve', callback_data: `vra:approve:${stageId}` },
+        { text: '🚫 Deny', callback_data: `vra:deny:${stageId}` },
+      ],
+    ],
+  }
+}

package/telegram-plugin/gateway/vault-request-save-card.test.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect } from 'vitest'
+import {
+  renderVaultRequestSaveCard,
+  buildVaultRequestSaveKeyboard,
+} from './vault-request-save-card.js'
+
+describe('vault-request-save-card (#2996 P5 extraction — verbatim from gateway.ts)', () => {
+  describe('renderVaultRequestSaveCard', () => {
+    it('renders the title, key field, why line, and footer', () => {
+      const out = renderVaultRequestSaveCard(
+        { key: 'openai/api_key', why: 'to call the API' },
+        'worker',
+      )
+      expect(out).toContain('🔐 **worker** wants to save a secret')
+      expect(out).toContain('key: `openai/api_key`')
+      expect(out).toContain('why: _to call the API_')
+      expect(out).toContain('Tap Save to write to the host vault')
+    })
+
+    it('omits the why line when no rationale is given', () => {
+      const out = renderVaultRequestSaveCard({ key: 'openai/api_key' }, 'worker')
+      expect(out).not.toContain('why:')
+    })
+
+    it('markdown-escapes the why text (not the code-span key)', () => {
+      const out = renderVaultRequestSaveCard(
+        { key: 'a/b_c', why: 'has_underscore' },
+        'worker',
+      )
+      // escapeHtmlForTg backslash-escapes emphasis chars in the why line…
+      expect(out).toContain('why: _has\\_underscore_')
+      // …but the key rides in a code span verbatim (literal underscore kept).
+      expect(out).toContain('key: `a/b_c`')
+    })
+  })
+
+  describe('buildVaultRequestSaveKeyboard', () => {
+    it('carries the vrs:* callback_data contract', () => {
+      const kb = buildVaultRequestSaveKeyboard('abcd1234')
+      const flat = kb.inline_keyboard.flat()
+      expect(flat.map((b) => b.callback_data)).toEqual([
+        'vrs:save:abcd1234',
+        'vrs:discard:abcd1234',
+        'vrs:rename:abcd1234',
+      ])
+      expect(flat.map((b) => b.text)).toEqual(['✅ Save once', '🚫 Discard', '✏️ Rename'])
+    })
+  })
+})

package/telegram-plugin/gateway/vault-request-save-card.ts

@@ -0,0 +1,52 @@
+/**
+ * Pure renderer + inline-keyboard builder for the agent-initiated vault-SAVE
+ * approval card (#969 P1a — the agent HAS a value and asks the operator to
+ * confirm writing it to the host vault). Callback prefix `vrs:`
+ * (vault-request-save), handled by handleVaultRequestSaveCallback in
+ * callback-query-handlers.ts.
+ *
+ * Extracted verbatim from gateway.ts (#2996 P5); the render body is unchanged.
+ * The card is sent via the rich-message (GFM markdown) path, so field lines are
+ * hardened against soft-collapse via hardenCardBreaks (see renderer footer).
+ *
+ * Buttons must fit Telegram's 64-byte callback_data limit. Stage IDs are 8 hex
+ * chars (32 bits), so each callback comfortably fits.
+ */
+
+import { escapeHtmlForTg } from '../shared/bot-runtime.js'
+import { hardenCardBreaks } from '../format.js'
+
+/** Minimal shape the card needs — a subset of PendingVaultRequestSave. */
+export interface VaultRequestSaveCardInput {
+  key: string
+  why?: string
+}
+
+export function renderVaultRequestSaveCard(req: VaultRequestSaveCardInput, agentSlug: string): string {
+  const lines: string[] = []
+  lines.push(`🔐 **${escapeHtmlForTg(agentSlug)}** wants to save a secret`)
+  lines.push(`key: \`${req.key}\``)
+  if (req.why && req.why.length > 0) {
+    lines.push(`why: _${escapeHtmlForTg(req.why)}_`)
+  }
+  lines.push('')
+  lines.push(`_Tap Save to write to the host vault, Rename to change the key name, or Discard to drop it. The value is held in this chat's gateway memory until you decide._`)
+  // hardenCardBreaks: labelled field lines (key: / why:) would soft-collapse
+  // into one blob under the GFM rich renderer; this card is sent direct via
+  // richMessage, bypassing the switchroomReply chokepoint.
+  return hardenCardBreaks(lines.join('\n'))
+}
+
+export function buildVaultRequestSaveKeyboard(stageId: string): { inline_keyboard: Array<Array<{ text: string; callback_data: string }>> } {
+  return {
+    inline_keyboard: [
+      [
+        { text: '✅ Save once', callback_data: `vrs:save:${stageId}` },
+        { text: '🚫 Discard', callback_data: `vrs:discard:${stageId}` },
+      ],
+      [
+        { text: '✏️ Rename', callback_data: `vrs:rename:${stageId}` },
+      ],
+    ],
+  }
+}

package/telegram-plugin/gateway/voice-message-handler.ts

@@ -0,0 +1,123 @@
+/**
+ * Voice inbound handler (switchroom#2996 P6 cluster E).
+ *
+ * `message:voice` is the attachment type with the richest branch: when
+ * `voice_in` is enabled in access.json it downloads the audio and transcribes
+ * it (local GPU sidecar or OpenAI cloud, per the host voice-engine verdict)
+ * before surfacing the transcript to the agent as inbound text. Every failure
+ * path falls back to the legacy `(voice message)` envelope so the agent still
+ * gets something — better than a silent drop. Split out of gateway.ts so the
+ * engine-selection + fallback logic is unit-testable against injected
+ * transcribe/access/capability surfaces.
+ *
+ * The registration line stays in gateway.ts (order is a load-bearing invariant
+ * pinned by gateway-handler-registration-wiring.test.ts) and delegates here.
+ * The engine env (`SWITCHROOM_VOICE_ENGINE`) is read directly — it is process
+ * ambient, not a gateway module global. All gateway surfaces (access load,
+ * host-capabilities load, both transcribe entry points, the coalescing
+ * dispatch) are injected (switchroom#2996 Amendment 9).
+ */
+
+import type { Context, Filter } from 'grammy'
+import type { VoiceEngine } from '../../src/setup/gpu-detect.js'
+import type { AttachmentMeta } from './attachment-message-handlers.js'
+
+interface VoiceInConfig {
+  enabled?: boolean
+  provider?: 'openai'
+  language?: string
+  api_key?: string
+}
+
+export interface VoiceHandlerDeps {
+  /** Load the agent's access config (for the `voice_in` block). */
+  loadAccess: () => { voice_in?: VoiceInConfig }
+  /** Load the persisted host voice-engine verdict (null when absent). */
+  loadHostCapabilities: () => { voice: { engine: VoiceEngine } } | null
+  /** Transcribe via the in-fleet local GPU sidecar (no third-party key). */
+  maybeTranscribeVoiceLocal: (
+    fileId: string,
+    mimeType: string | undefined,
+    language: string | undefined,
+  ) => Promise<string | null>
+  /** Transcribe via the OpenAI cloud provider. */
+  maybeTranscribeVoice: (
+    fileId: string,
+    mimeType: string | undefined,
+    language: string | undefined,
+    apiKeyRef: string | undefined,
+  ) => Promise<string | null>
+  /** Normal coalescing inbound pipeline. */
+  handleInboundCoalesced: (
+    ctx: Context,
+    text: string,
+    downloadImage: undefined,
+    attachment?: AttachmentMeta,
+  ) => Promise<void>
+}
+
+export async function handleVoiceMessage(
+  ctx: Filter<Context, 'message:voice'>,
+  deps: VoiceHandlerDeps,
+): Promise<void> {
+  const voice = ctx.message.voice
+  // #578 spike: when voice_in is enabled in access.json, download
+  // the audio and transcribe via Whisper before surfacing to the
+  // agent. The transcript becomes the inbound text; the agent reads
+  // it like a typed message. Failure paths gracefully fall back to
+  // the legacy "(voice message)" envelope so the agent still gets
+  // SOMETHING — better than silent drops.
+  const access = deps.loadAccess()
+  const voiceIn = access.voice_in
+  // Engine selection (PR-B2): the persisted host verdict decides HOW we
+  // transcribe. `local` → the in-fleet GPU sidecar (no third-party key,
+  // vision #3 + #4); anything else → the OpenAI cloud provider. The local
+  // path needs no `provider === 'openai'` gate — it has no API key — so we
+  // route to the sidecar whenever voice_in is enabled AND the host verdict
+  // is `local`. The cloud path keeps its existing openai gate.
+  // Source precedence: the compose-injected SWITCHROOM_VOICE_ENGINE env
+  // (set per-agent by compose-gen from the host verdict — PR-B3) wins,
+  // then the persisted host-capabilities file, then a fail-safe `cloud`.
+  // The env is load-bearing in-fleet: the in-container `~/.switchroom`
+  // is a read-only constructed view that does NOT carry the host's
+  // host-capabilities.json, so without the env the file lookup always
+  // misses and every agent silently falls back to `cloud`. Narrow the
+  // env value to the VoiceEngine union so a bogus value can't leak
+  // through — anything but 'local'/'cloud' is ignored and we fall back.
+  const envVoiceEngine = process.env.SWITCHROOM_VOICE_ENGINE
+  const voiceEngine: VoiceEngine =
+    envVoiceEngine === 'local' || envVoiceEngine === 'cloud'
+      ? envVoiceEngine
+      : deps.loadHostCapabilities()?.voice.engine ?? 'cloud'
+  const localEnabled = voiceIn?.enabled === true && voiceEngine === 'local'
+  const cloudEnabled =
+    voiceIn?.enabled === true && voiceEngine !== 'local' && voiceIn?.provider === 'openai'
+  if (localEnabled || cloudEnabled) {
+    const transcript = localEnabled
+      ? await deps.maybeTranscribeVoiceLocal(
+          voice.file_id,
+          voice.mime_type,
+          voiceIn?.language,
+        )
+      : await deps.maybeTranscribeVoice(
+          voice.file_id,
+          voice.mime_type,
+          voiceIn?.language,
+          voiceIn?.api_key,
+        )
+    if (transcript != null) {
+      const text = ctx.message.caption
+        ? `${ctx.message.caption}\n\n[voice transcript] ${transcript}`
+        : `[voice transcript] ${transcript}`
+      await deps.handleInboundCoalesced(ctx, text, undefined, {
+        kind: 'voice',
+        file_id: voice.file_id,
+        size: voice.file_size,
+        mime: voice.mime_type,
+      })
+      return
+    }
+    // Fall through to the legacy path on transcription failure.
+  }
+  await deps.handleInboundCoalesced(ctx, ctx.message.caption ?? '(voice message)', undefined, { kind: 'voice', file_id: voice.file_id, size: voice.file_size, mime: voice.mime_type })
+}