@agfpd/voicetalk-runtime 0.3.0 → 0.3.1

package/README.md

@@ -61,11 +61,17 @@ runs the same router text-only, with no microphone at all. Configuration details
 - **Modality framing for a naive agent.** An agent has no senses — only envelope text. voicetalk marks the inbound envelope so a peer with no knowledge of the system answers in the right modality ("spoken, live — reply by voice, briefly").
 - **Voice stays out of the core.** Speech-to-text and text-to-speech live in the shared `voice-connect` service (multi-provider, one place to configure), not inside this runtime and not inside the iapeer foundation.
 - **Conversational turn-taking.** A wake-word only opens a conversation; after a reply, an open-mic window lets the next utterance continue without re-triggering. Endpointing and earcons are owned here, inside the audio session — the agent only sees the next message.
+- **Wake evidence fails closed.** Configured names are never injected into Whisper's
+  decoder prompt: only an exact leading name heard in the unprimed transcript can open
+  a dialogue, and repeated-name decoder loops are discarded before IAP delivery.
 
 ## What it does not do (yet)
 
 - No barge-in: the owner cannot interrupt a spoken answer by talking over it (that needs acoustic echo cancellation plus a neural VAD). While the runtime speaks, it does not listen.
-- Wake detection runs on the transcript, not on an acoustic wake-word model — so a wake word costs one line of config and no training, at the price of transcribing every voiced segment. An acoustic pre-gate is the Фаза-4 latency upgrade.
+- Wake detection runs on an unprimed transcript, not on an acoustic wake-word model —
+  so a wake word costs one line of config and no training, at the price of transcribing
+  every voiced segment. A bounded private ring retains wake-candidate segments for
+  replayable diagnostics; an acoustic pre-gate remains the stronger future upgrade.
 - Single host, single owner, local microphone and speaker. Multi-device and multi-owner are out of scope for the MVP.
 
 ## Roadmap

package/docs/README.md

@@ -41,6 +41,11 @@ self-config hook. `voicetalk-runtime devices` lists the host's inputs;
 `voicetalk-runtime doctor` reports the whole contour (binding, wake map,
 voice-connect, microphone).
 
+Wake evidence is fail-closed. The configured vocabulary is never passed as a Whisper
+decoder prompt, because prompt text can be generated back on unrelated audio. A closed
+dialogue opens only on an exact leading address in the unprimed transcript; repeated
+token loops and name-only echoes are rejected before an IAP envelope exists.
+
 ## How a turn works
 
 1. The microphone runs always-on; energy endpointing cuts an utterance when the
@@ -69,7 +74,14 @@ Everything is tunable by env: `VOICETALK_AUDIO=0` (text-only, no microphone),
 `VOICETALK_FOLLOWUP_MS`, `VOICETALK_HANGOVER_MS`, `VOICETALK_VAD_MIN_RMS`,
 `VOICETALK_VAD_RATIO`, `VOICETALK_STT_LANG`, `VOICETALK_STT_ENGINE`,
 `VOICETALK_TTS_MAX_CHARS`, `VOICETALK_EARCONS=0`, `VOICETALK_COMPOSE_MS`,
-`VOICETALK_COMPOSE_UNFINISHED_MS`, `VOICETALK_TURN_MAX_MS`.
+`VOICETALK_COMPOSE_UNFINISHED_MS`, `VOICETALK_TURN_MAX_MS`,
+`VOICETALK_WAKE_CAPTURE=0` (disable the default diagnostic ring), and
+`VOICETALK_WAKE_CAPTURE_MAX` (default 16).
+
+Every transcript that resembles a configured wake is retained as a mode-0600 WAV plus
+JSON verdict under `<IAPEER_ROOT>/runtimes/voicetalk/tmp/wake-captures`. The ring is
+bounded and contains candidate utterances only, not continuous room audio. Replay a
+disputed segment through the same paced microphone path described below.
 
 Two seams exist for testing turn-taking without touching a live channel:
 `VOICETALK_MIC_FILE=<pcm>` replays a recording through the microphone path (paced in

package/docs/ru/README.md

@@ -41,6 +41,11 @@ self-config-хука (`VOICETALK_WAKE_WORDS`, `VOICETALK_DEFAULT_TARGET`,
 `voicetalk-runtime doctor` — весь контур целиком (привязка, карта, voice-connect,
 микрофон).
 
+Wake-сигнал работает fail-closed. Настроенные имена не передаются Whisper как decoder
+prompt: такой контекст способен сам породить имя на постороннем аудио. Закрытый диалог
+открывает только точное имя в начале непримированного транскрипта; циклы повторяющихся
+токенов и тело из одних настроенных имён отбрасываются до появления IAP-конверта.
+
 ## Как устроен ход разговора
 
 1. Микрофон слушает постоянно; энергетический эндпойнтер закрывает реплику по паузе
@@ -68,7 +73,14 @@ Earcon'ы размечают состояния: восходящий — мик
 `VOICETALK_FOLLOWUP_MS`, `VOICETALK_HANGOVER_MS`, `VOICETALK_VAD_MIN_RMS`,
 `VOICETALK_VAD_RATIO`, `VOICETALK_STT_LANG`, `VOICETALK_STT_ENGINE`,
 `VOICETALK_TTS_MAX_CHARS`, `VOICETALK_EARCONS=0`, `VOICETALK_COMPOSE_MS`,
-`VOICETALK_COMPOSE_UNFINISHED_MS`, `VOICETALK_TURN_MAX_MS`.
+`VOICETALK_COMPOSE_UNFINISHED_MS`, `VOICETALK_TURN_MAX_MS`,
+`VOICETALK_WAKE_CAPTURE=0` (отключить диагностическое кольцо) и
+`VOICETALK_WAKE_CAPTURE_MAX` (по умолчанию 16).
+
+Каждый транскрипт, похожий на настроенный wake, сохраняется как WAV с правами 0600 и
+JSON-вердикт в `<IAPEER_ROOT>/runtimes/voicetalk/tmp/wake-captures`. Кольцо ограничено
+и хранит только сегменты-кандидаты, не непрерывную запись комнаты. Спорный сегмент
+можно прогнать через тот же микрофонный путь способом ниже.
 
 Для проверки turn-taking, не трогая живой канал, есть два шва: `VOICETALK_MIC_FILE=<pcm>`
 проигрывает запись через тот же путь, что и микрофон (в реальном темпе), а

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/voicetalk-runtime",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Voice runtime-router for IAP peers.",
   "license": "Apache-2.0",
   "type": "module",

package/src/voiceConnect.ts

@@ -114,13 +114,15 @@ export type TranscribeOptions = {
   lang?: string
   /** Force an STT engine (`mlx-whisper` keeps it fully local); default = service cascade. */
   engine?: string
-  /** Decoder-priming prompt — biases spelling of fleet names so the wake matcher sees
-   *  «Борис», not «Барис». */
-  prompt?: string
   timeoutMs?: number
 }
 
-/** Transcribe a local audio file. Returns the raw transcript (may be empty). */
+/** Transcribe a local audio file. Returns the raw transcript (may be empty).
+ *
+ * Deliberately no `prompt` option: this client feeds a presence detector, so configured
+ * wake words must never be injected into the decoder and then mistaken for acoustic
+ * evidence. voice-connect supports prompts for other consumers; voicetalk's door does not.
+ */
 export async function transcribe(audioPath: string, opts: TranscribeOptions = {}): Promise<string> {
   const ep = resolveVoiceEndpoint()
   const form = new FormData()
@@ -128,7 +130,6 @@ export async function transcribe(audioPath: string, opts: TranscribeOptions = {}
   form.append('file', new Blob([new Uint8Array(bytes)], { type: 'audio/wav' }), audioPath.split('/').pop() ?? 'audio.wav')
   if (opts.lang) form.append('language', opts.lang)
   if (opts.engine) form.append('engine', opts.engine)
-  if (opts.prompt) form.append('prompt', opts.prompt)
   form.append('response_format', 'json')
   const res = await fetch(ep.stt, {
     method: 'POST',

package/src/voiceSession.ts

@@ -30,9 +30,9 @@
 // which exists here yet. Mic gating during playback is the honest substitute — the
 // runtime simply does not listen while it talks.
 
-import { mkdirSync, rmSync } from 'fs'
+import { copyFileSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'fs'
 import { join } from 'path'
-import { randomUUID } from 'crypto'
+import { createHash, randomUUID } from 'crypto'
 import {
   Microphone,
   Segmenter,
@@ -45,16 +45,16 @@ import {
 import { synthesize, transcribe } from './voiceConnect.ts'
 import {
   buildAddressBook,
-  isLikelyHallucination,
+  hallucinationReason,
   matchWake,
+  objectionToActivation,
   objectionToSwitch,
   readFleetPeers,
-  sttPrompt,
   type Address,
   type FleetPeer,
   type VoicetalkBinding,
+  type WakeMatch,
 } from './wake.ts'
-import { writeFileSync } from 'fs'
 
 const num = (v: string | undefined, d: number) => (v && Number(v) > 0 ? Number(v) : d)
 
@@ -98,6 +98,12 @@ const STT_ENGINE = process.env.VOICETALK_STT_ENGINE?.trim() || undefined
  *  real voice channel is in use by its owner. */
 const MIC_FILE = process.env.VOICETALK_MIC_FILE?.trim() || undefined
 const PLAYBACK_ENABLED = process.env.VOICETALK_PLAYBACK !== '0'
+/** Keep a small, private ring of audio segments whose transcript looked like a wake.
+ *  A false wake cannot be diagnosed from text alone: the audio is the evidence of what
+ *  the owner actually said. Only candidate segments are retained, never room audio; files
+ *  are mode 0600 under the runtime scratch dir and the oldest pair is evicted. */
+const WAKE_CAPTURE_ENABLED = process.env.VOICETALK_WAKE_CAPTURE !== '0'
+const WAKE_CAPTURE_MAX = Math.min(100, num(process.env.VOICETALK_WAKE_CAPTURE_MAX, 16))
 
 export type DeliverFn = (target: string, text: string) => Promise<{ ok: boolean; detail?: string }>
 export type LogFn = (evt: string, fields: Record<string, unknown>) => void
@@ -112,6 +118,12 @@ export type VoiceSessionOptions = {
   peers?: FleetPeer[]
 }
 
+type WakeRoutingDecision = {
+  candidate: WakeMatch
+  accepted: boolean
+  reason?: string
+}
+
 /** State sounds, per the earcon convention in the research: `open` = the microphone is
  *  yours (rising, ≤300 ms), `end` = turn captured, processing (short descending,
  *  ≤200 ms), `close` = the open-mic window expired, a name is needed again (low, soft),
@@ -126,7 +138,6 @@ export class VoiceSession {
     minRms: num(process.env.VOICETALK_VAD_MIN_RMS, 700),
   })
   private book: Address[] = []
-  private prompt = ''
   private earcons: Earcons | null = null
   private busy = false
   private queue: Array<Segment & { speechEndedAt: number }> = []
@@ -181,7 +192,6 @@ export class VoiceSession {
       binding: this.opts.binding,
       peers: this.opts.peers ?? readFleetPeers(),
     })
-    this.prompt = sttPrompt(this.book)
   }
 
   private writeEarcons(): Earcons {
@@ -269,21 +279,37 @@ export class VoiceSession {
         transcript = await transcribe(wav, {
           lang: STT_LANG || undefined,
           engine: STT_ENGINE,
-          prompt: this.prompt || undefined,
         })
       } catch (err) {
         this.opts.log('stt.error', { ms: segment.ms, detail: err instanceof Error ? err.message : String(err) })
         return
       }
       const sttMs = Date.now() - started
-      if (isLikelyHallucination(transcript)) {
+      const candidate = matchWake(transcript, this.book)
+      const hallucination = hallucinationReason(transcript)
+      if (hallucination) {
         this.opts.log('stt.ignored', {
           ms: segment.ms,
           sttMs,
           peak: Math.round(segment.peakRms),
           floor: Math.round(segment.noiseFloor),
+          reason: hallucination,
           text: transcript,
         })
+        if (candidate) {
+          this.opts.log('wake.rejected', {
+            target: candidate.target,
+            alias: candidate.alias,
+            exact: candidate.exact,
+            reason: hallucination,
+            text: transcript,
+          })
+          this.captureWakeCandidate(wav, segment, transcript, {
+            candidate,
+            accepted: false,
+            reason: hallucination,
+          })
+        }
         return
       }
       this.opts.log('stt.text', {
@@ -295,12 +321,79 @@ export class VoiceSession {
         text: transcript,
       })
 
-      this.absorb(transcript)
+      const decision = this.absorb(transcript, candidate)
+      if (decision) this.captureWakeCandidate(wav, segment, transcript, decision)
     } finally {
       rmSync(wav, { force: true })
     }
   }
 
+  /** Persist the evidence for an apparent wake in a bounded private ring. Text-only logs
+   *  cannot distinguish a spoken name from a decoder invention; this seam makes the next
+   *  disputed activation replayable through VOICETALK_MIC_FILE without recording the room
+   *  continuously. */
+  private captureWakeCandidate(
+    wav: string,
+    segment: Segment,
+    transcript: string,
+    decision: WakeRoutingDecision,
+  ): void {
+    if (!WAKE_CAPTURE_ENABLED) return
+    const dir = join(this.opts.tmpDir, 'wake-captures')
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+    const stem = `wake-${stamp}-${randomUUID()}`
+    const audioPath = join(dir, `${stem}.wav`)
+    const metaPath = join(dir, `${stem}.json`)
+    try {
+      mkdirSync(dir, { recursive: true, mode: 0o700 })
+      copyFileSync(wav, audioPath)
+      writeFileSync(
+        metaPath,
+        JSON.stringify(
+          {
+            capturedAt: new Date().toISOString(),
+            audio: `${stem}.wav`,
+            pcmSha256: createHash('sha256').update(segment.pcm).digest('hex'),
+            segment: {
+              ms: segment.ms,
+              peakRms: Math.round(segment.peakRms),
+              noiseFloor: Math.round(segment.noiseFloor),
+              threshold: segment.threshold,
+              truncated: segment.truncated,
+            },
+            transcript,
+            wake: {
+              target: decision.candidate.target,
+              alias: decision.candidate.alias,
+              exact: decision.candidate.exact,
+              accepted: decision.accepted,
+              ...(decision.reason ? { reason: decision.reason } : {}),
+            },
+          },
+          null,
+          2,
+        ) + '\n',
+        { mode: 0o600 },
+      )
+
+      const records = readdirSync(dir).filter(name => /^wake-.*\.json$/.test(name)).sort()
+      for (const oldMeta of records.slice(0, Math.max(0, records.length - WAKE_CAPTURE_MAX))) {
+        const oldStem = oldMeta.slice(0, -'.json'.length)
+        rmSync(join(dir, oldMeta), { force: true })
+        rmSync(join(dir, `${oldStem}.wav`), { force: true })
+      }
+      this.opts.log('wake.capture', {
+        target: decision.candidate.target,
+        accepted: decision.accepted,
+        path: audioPath,
+      })
+    } catch (err) {
+      rmSync(audioPath, { force: true })
+      rmSync(metaPath, { force: true })
+      this.opts.log('wake.capture-error', { detail: err instanceof Error ? err.message : String(err) })
+    }
+  }
+
   /** Route one recognized fragment into the turn being composed.
    *
    *  The decision is deliberately conservative in one direction: an unaddressed fragment
@@ -309,9 +402,30 @@ export class VoiceSession {
    *  when no conversation is open. Mid-dialogue, the cheap error (one more line to the
    *  peer already listening) is far cheaper than the expensive one (the conversation
    *  silently handed to another agent). */
-  private absorb(transcript: string): void {
+  private absorb(transcript: string, candidate = matchWake(transcript, this.book)): WakeRoutingDecision | null {
     const active = this.pending?.target ?? (this.followTarget && Date.now() < this.followUntil ? this.followTarget : null)
-    const match = matchWake(transcript, this.book)
+    if (candidate) {
+      const decline = objectionToActivation(candidate, this.book)
+      if (decline) {
+        this.opts.log('wake.rejected', {
+          target: candidate.target,
+          alias: candidate.alias,
+          exact: candidate.exact,
+          reason: decline,
+          text: transcript,
+        })
+        // An open dialogue intentionally needs no wake word. If its next fragment merely
+        // resembles a name, preserve it as ordinary continuation rather than dropping or
+        // stripping a word from the owner's thought.
+        if (active && decline === 'inexact name match') {
+          this.opts.log('turn.continue', { target: active, reason: this.pending ? 'compose' : 'follow-up' })
+          this.append(active, transcript.trim())
+        }
+        return { candidate, accepted: false, reason: decline }
+      }
+    }
+
+    const match = candidate
     const switching = !!match && !!active && match.target !== active
 
     if (switching) {
@@ -319,14 +433,14 @@ export class VoiceSession {
       if (decline) {
         this.opts.log('wake.switch-declined', { from: active, to: match!.target, reason: decline, text: transcript })
         this.append(active!, transcript.trim())
-        return
+        return { candidate: match!, accepted: false, reason: decline }
       }
       // A deliberate switch: the thought in flight belongs to the previous peer, so it
       // goes out before the new one starts.
       this.opts.log('wake.switch', { from: active, to: match!.target })
       this.flush('switch')
       this.append(match!.target, match!.body)
-      return
+      return { candidate: match!, accepted: true }
     }
 
     if (match) {
@@ -336,19 +450,20 @@ export class VoiceSession {
         this.openWindow(match.target)
         this.opts.log('wake.await-body', { target: match.target, alias: match.alias })
         void this.earcon('open')
-        return
+        return { candidate: match, accepted: true }
       }
       this.append(match.target, match.body)
-      return
+      return { candidate: match, accepted: true }
     }
 
     if (active) {
       this.opts.log('turn.continue', { target: active, reason: this.pending ? 'compose' : 'follow-up' })
       this.append(active, transcript.trim())
-      return
+      return null
     }
 
     this.opts.log('wake.no-match', { text: transcript })
+    return null
   }
 
   /** Add a fragment to the turn in flight and (re)arm the compose timer. */

package/src/wake.ts

@@ -10,15 +10,13 @@
 // enrich them with their own human name («наталья» → «наталья вячеславовна»).
 //
 // Why the address is matched on the TRANSCRIPT rather than by an acoustic wake-word model
-// (openWakeWord et al.): an acoustic detector needs a trained model per phrase, and Фаза 3
-// is proving the pipeline end to end — transcript matching gives the same routing with
-// zero training and no per-name asset to maintain. Privacy is preserved by the property
-// that made an on-device detector attractive in the first place: the recognizer is the
-// LOCAL floor of voice-connect (mlx-whisper on this host), so no audio leaves the machine
-// to decide whether a name was spoken. The cost is running the recognizer on every voiced
-// segment; endpointing keeps that to actual speech, and an acoustic pre-gate (openWakeWord
-// on the curated map — cheap in parallel, one shared feature backbone) is the natural
-// Фаза-4 latency upgrade behind this same interface.
+// (openWakeWord et al.): an acoustic detector needs a trained model per phrase, while
+// transcript matching needs no per-name asset. That transcript MUST be decoded without a
+// name prompt. Whisper's `initial_prompt` is generative context, not evidence: priming it
+// with «дарвин, борис, линус» made unrelated audio decode as those names and woke agents
+// in a quiet conversation (live defect, 23–24.07). The address layer therefore accepts
+// only an exact, unprimed name at the start and rejects decoder loops before routing.
+// A dedicated acoustic gate remains the stronger future upgrade behind this interface.
 
 import { readFileSync } from 'fs'
 import { homedir } from 'os'
@@ -205,9 +203,8 @@ export type WakeMatch = {
   /** The utterance with the address (and any leading filler) stripped. */
   body: string
   alias: string
-  /** True when every word of the address matched letter for letter. A match that only
-   *  survived the one-edit tolerance is good enough to START a conversation, but not to
-   *  TAKE one away from the peer already in it — see the switch bar in voiceSession. */
+  /** True when every word of the address matched letter for letter. Inexact candidates
+   *  remain observable for diagnostics, but may never activate or retarget a dialogue. */
   exact: boolean
 }
 
@@ -266,9 +263,28 @@ export function objectionToSwitch(match: WakeMatch): string | null {
   return null
 }
 
-/** Whisper-family recognizers emit stock phrases on near-silence («Продолжение
- *  следует…», «Субтитры сделал…»). They are not speech; drop them before matching so a
- *  quiet room cannot fabricate an utterance. */
+/** May this candidate START a dialogue?
+ *
+ * The recognizer is allowed to suggest an inexact name so the diagnostic seam can retain
+ * the audio, but a suggestion is not presence evidence. The initial address must be exact.
+ * Likewise, a transcript made only from configured names is decoder echo, not a request:
+ * the live failures were «Дарвин» followed by dozens of «борис» tokens. A bare exact name
+ * remains valid — it opens the short awaiting-body window without sending an envelope. */
+export function objectionToActivation(match: WakeMatch, book: Address[]): string | null {
+  if (!match.exact) return 'inexact name match'
+  const body = normalizeSpoken(match.body)
+  if (!body) return null
+  const addressTokens = new Set(
+    book.flatMap(address => address.aliases.flatMap(alias => normalizeSpoken(alias).split(' '))).filter(Boolean),
+  )
+  const words = body.split(' ')
+  if (words.every(word => addressTokens.has(word))) return 'body only echoes configured names'
+  return null
+}
+
+/** Whisper-family recognizers emit both stock captions on near-silence and low-entropy
+ * token loops. They are decoder output, not speech; identify them before wake matching so
+ * a recognizer cannot fabricate presence from its own repeated hypothesis. */
 const HALLUCINATIONS = [
   'продолжение следует',
   'субтитры',
@@ -282,16 +298,33 @@ const HALLUCINATIONS = [
   'you',
 ]
 
-export function isLikelyHallucination(transcript: string): boolean {
+export function hallucinationReason(transcript: string): string | null {
   const n = normalizeSpoken(transcript)
-  if (!n) return true
-  if (n.length <= 2) return true
-  return HALLUCINATIONS.some(h => n === h || n.startsWith(h))
+  if (!n) return 'empty transcript'
+  if (n.length <= 2) return 'transcript too short'
+  if (HALLUCINATIONS.some(h => n === h || n.startsWith(h))) return 'stock whisper caption'
+
+  const words = n.split(' ')
+  if (words.length >= 3) {
+    let longestRun = 1
+    let run = 1
+    for (let i = 1; i < words.length; i++) {
+      run = words[i] === words[i - 1] ? run + 1 : 1
+      longestRun = Math.max(longestRun, run)
+    }
+    // Three repeats can be a human correcting or emphasizing themselves («нет, нет,
+    // нет»). Five identical consecutive tokens are outside ordinary turn-taking and
+    // still far below the 10/70-token loops observed live.
+    if (longestRun >= 5) return 'repeated-token decoder loop'
+
+    const counts = new Map<string, number>()
+    for (const word of words) counts.set(word, (counts.get(word) ?? 0) + 1)
+    const dominant = Math.max(...counts.values())
+    if (words.length >= 6 && dominant / words.length >= 0.75) return 'low-entropy decoder loop'
+  }
+  return null
 }
 
-/** Names spoken to the recognizer as a decoder prompt — biases spelling toward the
- *  fleet's own vocabulary so the matcher sees «Борис», not «Барис». */
-export function sttPrompt(book: Address[]): string {
-  const names = book.flatMap(a => a.aliases).slice(0, 40)
-  return names.length ? `Обращение к ассистенту по имени: ${names.join(', ')}.` : ''
+export function isLikelyHallucination(transcript: string): boolean {
+  return hallucinationReason(transcript) !== null
 }