switchroom 0.16.28 → 0.16.38

package/telegram-plugin/tests/vault-grant-inbound-builders.test.ts

@@ -15,6 +15,7 @@
 import { describe, it, expect } from 'vitest'
 import {
   buildVaultGrantApprovedInbound,
+  buildVaultGrantApprovedCardText,
   buildVaultGrantDeniedInbound,
   buildVaultSaveCompletedInbound,
   buildVaultSaveFailedInbound,
@@ -22,6 +23,7 @@ import {
   type VaultGrantInboundContext,
   type VaultSaveInboundContext,
 } from '../gateway/vault-grant-inbound-builders.js'
+import { richMessage } from '../rich-send.js'
 
 const FIXED_NOW = 1_700_000_000_000
 
@@ -40,6 +42,58 @@ const CTX_WRITE: VaultGrantInboundContext = {
   ttl_seconds: 7 * 86400,
 }
 
+describe('buildVaultGrantApprovedCardText — the [object Object] regression guard', () => {
+  const BASE = {
+    agentEscaped: 'gymbro',
+    scope: 'read' as const,
+    key: 'fatsecret/credentials',
+    days: 30,
+    grantId: 'vg_a1b2c3',
+  }
+
+  it('renders the full confirmation as ONE markdown string wrapped once — no [object Object]', () => {
+    // This is the whole point of the helper: the card text is built as a
+    // single string and passed to a single richMessage(...) call. The bug
+    // (fixed here) was `"prefix " + richMessage("suffix")`, which coerces
+    // the {markdown} object and prints "[object Object]".
+    const text = buildVaultGrantApprovedCardText(BASE)
+    const rich = richMessage(text)
+    expect(rich.markdown).toBe(text)
+    expect(rich.markdown).not.toContain('[object Object]')
+    expect(rich.markdown).toContain('vg_a1b2c3') // grant id present
+  })
+
+  it('includes agent, scope, key, days, and the grant id', () => {
+    const text = buildVaultGrantApprovedCardText(BASE)
+    expect(text).toContain('**gymbro**')
+    expect(text).toContain('read access')
+    expect(text).toContain('`fatsecret/credentials`')
+    expect(text).toContain('for 30d')
+    expect(text).toContain('(grant `vg_a1b2c3`)')
+  })
+
+  it('appends the footer when provided, omits it otherwise', () => {
+    const withFooter = buildVaultGrantApprovedCardText({
+      ...BASE,
+      footer: '\n_Approver verified by Telegram identity._',
+    })
+    expect(withFooter).toContain('_Approver verified by Telegram identity._')
+    // still one clean string
+    expect(withFooter).not.toContain('[object Object]')
+
+    const noFooter = buildVaultGrantApprovedCardText(BASE)
+    expect(noFooter.endsWith('(grant `vg_a1b2c3`)')).toBe(true)
+  })
+
+  it('DOCUMENTS the original bug: bare-string + richMessage() coerces to [object Object]', () => {
+    // Demonstrates why the fix matters — if a future edit reintroduces the
+    // "concatenate a string onto the richMessage object" pattern, the result
+    // contains the literal "[object Object]". The helper above avoids it.
+    const buggy = '✅ Granted access. ' + (richMessage('(grant `vg_x`)') as unknown as string)
+    expect(buggy).toContain('[object Object]')
+  })
+})
+
 describe('buildVaultGrantApprovedInbound', () => {
   it('emits the canonical envelope (type, chat_id, user, userId, ts, messageId)', () => {
     const msg = buildVaultGrantApprovedInbound({

package/telegram-plugin/tests/vault-request-access-card.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Render-safety pin for the agent-initiated vault-access approval card.
+ *
+ * Bug (card-ux fix 2): the vault key was interpolated into a `code span`
+ * WITHOUT defusing backtick / without leaking backslashes. A key with a
+ * backtick would prematurely close the span; the following `_why_` and
+ * `_footer_` markdown then paired against stray delimiters and the card
+ * rendered on top of itself. Keys with `_` (e.g. `openai/OPENAI_API_KEY`)
+ * must render literally inside the span (no visible `\_`).
+ */
+
+import { describe, it, expect } from 'vitest'
+import { renderVaultRequestAccessCard } from '../gateway/vault-request-access-card.js'
+
+// Zero-width space codeSpanSafe inserts after a backtick to defuse it.
+const ZWSP = '​'
+
+/** Count top-level (outside code spans) markdown emphasis delimiters. */
+function unbalancedOutsideCodeSpans(text: string): {
+  underscores: number
+  asterisks: number
+} {
+  let inSpan = false
+  let underscores = 0
+  let asterisks = 0
+  for (const ch of text) {
+    if (ch === '`') {
+      inSpan = !inSpan
+      continue
+    }
+    if (inSpan) continue
+    if (ch === '_') underscores += 1
+    if (ch === '*') asterisks += 1
+  }
+  return { underscores, asterisks }
+}
+
+describe('renderVaultRequestAccessCard', () => {
+  it('renders an underscore-laden key literally inside the code span (no backslash leak)', () => {
+    const text = renderVaultRequestAccessCard({
+      agent: 'overlord',
+      key: 'openai/OPENAI_API_KEY',
+      scope: 'read',
+      reason: 'call the completions endpoint',
+      ttl_seconds: 7 * 86400,
+    })
+    // The key rides in a code span verbatim — underscores present, NOT escaped.
+    expect(text).toContain('`openai/OPENAI_API_KEY`')
+    // No visible backslash-escaping leaked into the span.
+    expect(text).not.toContain('OPENAI\\_API\\_KEY')
+  })
+
+  it('does not leave unbalanced markdown delimiters outside code spans', () => {
+    const text = renderVaultRequestAccessCard({
+      agent: 'overlord',
+      key: 'openai/OPENAI_API_KEY',
+      scope: 'write',
+      reason: 'rotate the key',
+      ttl_seconds: 3600,
+    })
+    const { underscores, asterisks } = unbalancedOutsideCodeSpans(text)
+    // The `_why_` + `_footer_` italic pairs and `**agent**` bold pair must
+    // each be even outside the spans — an underscore-key leaking out (the bug)
+    // makes this odd.
+    expect(underscores % 2).toBe(0)
+    expect(asterisks % 2).toBe(0)
+  })
+
+  it('defuses a backtick in the key so it cannot close the span early', () => {
+    const text = renderVaultRequestAccessCard({
+      agent: 'overlord',
+      key: 'svc/we`ird',
+      scope: 'read',
+      ttl_seconds: 86400,
+    })
+    // A raw backtick would have closed the span; codeSpanSafe splits it with a
+    // zero-width space so the parser sees `` `we` `` (empty-ish) then literal
+    // text, never an unterminated span breaking the following lines.
+    expect(text).toContain(`we\`${ZWSP}ird`)
+    // Every intentional code-span backtick is immediately followed by
+    // non-backtick content or a ZWSP — no bare `\`\`` that would swallow text.
+    expect(text).not.toContain('``')
+  })
+
+  it('renders "not provided" when reason omitted', () => {
+    const text = renderVaultRequestAccessCard({
+      agent: 'overlord',
+      key: 'svc/key',
+      scope: 'read',
+      ttl_seconds: 86400,
+    })
+    expect(text).toContain('why: _not provided_')
+  })
+})

package/telegram-plugin/tests/voice-normalize-text.test.ts

@@ -0,0 +1,256 @@
+/**
+ * Unit tests for normalizeForSpeech — the speech-normalization pass applied
+ * to a reply BEFORE it is synthesized to a voice note. Covers every case the
+ * operator reported (tilde, asterisks, backticks, headings, links, code
+ * fences) plus the documented behavioural choices.
+ */
+
+import { describe, it, expect } from 'bun:test'
+import { normalizeForSpeech } from '../voice-normalize-text.js'
+
+describe('normalizeForSpeech — reported markdown/symbol cases', () => {
+  it('drops stray tildes (never spoken as "tilde")', () => {
+    expect(normalizeForSpeech('It costs ~5 dollars')).toBe('It costs 5 dollars')
+    expect(normalizeForSpeech('done ~ ok')).toBe('done ok')
+  })
+
+  it('strips bold/italic asterisks and underscores, keeping the words', () => {
+    expect(normalizeForSpeech('This is **bold** text')).toBe('This is bold text')
+    expect(normalizeForSpeech('This is *italic* text')).toBe('This is italic text')
+    expect(normalizeForSpeech('This is _emphasis_ text')).toBe('This is emphasis text')
+    expect(normalizeForSpeech('***all*** three')).toBe('all three')
+  })
+
+  it('strips strikethrough ~~text~~ to plain text', () => {
+    expect(normalizeForSpeech('~~gone~~ kept')).toBe('gone kept')
+  })
+
+  it('removes backticks from inline code but keeps the content', () => {
+    expect(normalizeForSpeech('run `npm test` now')).toBe('run npm test now')
+  })
+
+  it('strips headings markers', () => {
+    expect(normalizeForSpeech('# Summary\nAll good')).toBe('Summary All good')
+    expect(normalizeForSpeech('### Deep heading')).toBe('Deep heading')
+  })
+
+  it('speaks link text and drops the URL', () => {
+    expect(normalizeForSpeech('see [the docs](https://example.com/x) here')).toBe(
+      'see the docs here',
+    )
+  })
+
+  it('drops a fenced code block and leaves a spoken placeholder', () => {
+    const input = 'Here is code:\n```js\nconst x = 1\nconsole.log(x)\n```\nDone.'
+    const out = normalizeForSpeech(input)
+    expect(out).toContain('code block omitted')
+    expect(out).not.toContain('const x')
+    expect(out).not.toContain('```')
+    expect(out).toContain('Done.')
+  })
+})
+
+describe('normalizeForSpeech — additional structures', () => {
+  it('converts list bullets and numbers to prose pauses', () => {
+    const out = normalizeForSpeech('Steps:\n- first\n- second\n1. third')
+    expect(out).not.toMatch(/[-*+]\s/)
+    expect(out).not.toMatch(/^\d+\./)
+    expect(out).toContain('first')
+    expect(out).toContain('second')
+    expect(out).toContain('third')
+  })
+
+  it('strips blockquote markers', () => {
+    expect(normalizeForSpeech('> quoted line')).toBe('quoted line')
+  })
+
+  it('turns tables into prose (no pipes or separator rows)', () => {
+    const table = '| A | B |\n| --- | --- |\n| 1 | 2 |'
+    const out = normalizeForSpeech(table)
+    expect(out).not.toContain('|')
+    expect(out).not.toContain('---')
+    expect(out).toContain('A')
+    expect(out).toContain('B')
+  })
+
+  it('converts arrows to the word "to"', () => {
+    expect(normalizeForSpeech('build -> deploy')).toBe('build to deploy')
+    expect(normalizeForSpeech('a => b')).toBe('a to b')
+    expect(normalizeForSpeech('x → y')).toBe('x to y')
+  })
+
+  it('replaces bare and autolink URLs with "a link"', () => {
+    expect(normalizeForSpeech('go to https://example.com now')).toBe('go to a link now')
+    expect(normalizeForSpeech('go to <https://example.com>')).toBe('go to a link')
+  })
+
+  it('drops images to their alt text', () => {
+    expect(normalizeForSpeech('![a cat](x.png) sits')).toBe('a cat sits')
+  })
+
+  it('collapses newlines and whitespace into sentence flow', () => {
+    expect(normalizeForSpeech('Line one.\n\nLine two.')).toBe('Line one. Line two.')
+    expect(normalizeForSpeech('a   b\nc')).toBe('a b c')
+  })
+
+  it('expands a minimal, safe set of abbreviations', () => {
+    expect(normalizeForSpeech('use it, e.g. here')).toBe('use it, for example, here')
+    expect(normalizeForSpeech('the tool, i.e. the interface')).toBe(
+      'the tool, that is, the interface',
+    )
+    expect(normalizeForSpeech('cats, dogs, etc.')).toBe('cats, dogs, and so on')
+  })
+
+  it('collapses excessive punctuation', () => {
+    expect(normalizeForSpeech('really?!?!')).toBe('really!')
+    expect(normalizeForSpeech('wow!!!')).toBe('wow!')
+  })
+})
+
+describe('normalizeForSpeech — emoji & pictographs', () => {
+  it('strips emoji and collapses the resulting whitespace', () => {
+    expect(normalizeForSpeech('done 🚀 shipping')).toBe('done shipping')
+    expect(normalizeForSpeech('great 👍🏽 job')).toBe('great job')
+    expect(normalizeForSpeech('🎉')).toBe('')
+  })
+
+  it('drops :shortcode: emoji forms', () => {
+    expect(normalizeForSpeech('nice :rocket: work')).toBe('nice work')
+  })
+
+  it('leaves ordinary colon usage alone', () => {
+    expect(normalizeForSpeech('note: this is fine')).toBe('note: this is fine')
+  })
+})
+
+describe('normalizeForSpeech — numbers, units & symbols', () => {
+  it('speaks percent', () => {
+    expect(normalizeForSpeech('up 20% today')).toBe('up 20 percent today')
+  })
+
+  it('speaks currency amounts', () => {
+    expect(normalizeForSpeech('costs $5')).toBe('costs five dollars')
+    expect(normalizeForSpeech('costs $5.50')).toBe('costs five dollars fifty')
+    expect(normalizeForSpeech('just $1')).toBe('just one dollar')
+  })
+
+  it('speaks standalone & as "and"', () => {
+    expect(normalizeForSpeech('cats & dogs')).toBe('cats and dogs')
+    expect(normalizeForSpeech('R&D team')).toBe('R and D team')
+  })
+
+  it('speaks + between words as "plus" and = as "equals"', () => {
+    expect(normalizeForSpeech('speed + power')).toBe('speed plus power')
+    expect(normalizeForSpeech('x = y')).toBe('x equals y')
+  })
+
+  it('speaks × / x multipliers as "times"', () => {
+    expect(normalizeForSpeech('12× faster')).toBe('twelve times faster')
+    expect(normalizeForSpeech('a 12x speedup')).toBe('a twelve times speedup')
+  })
+
+  it('speaks temperature degrees', () => {
+    expect(normalizeForSpeech('it is 30°C outside')).toBe(
+      'it is 30 degrees outside',
+    )
+    expect(normalizeForSpeech('72°F')).toBe('72 degrees')
+  })
+
+  it('expands number + time/size unit suffixes', () => {
+    expect(normalizeForSpeech('waited 2s')).toBe('waited two seconds')
+    expect(normalizeForSpeech('took 500ms')).toBe('took five hundred milliseconds')
+    expect(normalizeForSpeech('run 5m')).toBe('run five minutes')
+    expect(normalizeForSpeech('run 5min')).toBe('run five minutes')
+    expect(normalizeForSpeech('wait 2h')).toBe('wait two hours')
+    expect(normalizeForSpeech('wait 2hr')).toBe('wait two hours')
+    expect(normalizeForSpeech('in 3d')).toBe('in three days')
+    expect(normalizeForSpeech('10kb file')).toBe('ten kilobytes file')
+    expect(normalizeForSpeech('10KB file')).toBe('ten kilobytes file')
+    expect(normalizeForSpeech('a 5MB image')).toBe('a five megabytes image')
+    expect(normalizeForSpeech('a 2GB dump')).toBe('a two gigabytes dump')
+    expect(normalizeForSpeech('1s ping')).toBe('one second ping')
+  })
+
+  it('expands the "k" thousands shorthand', () => {
+    expect(normalizeForSpeech('100k users')).toBe('one hundred thousand users')
+  })
+
+  it('leaves number-glued-to-word identifiers alone', () => {
+    expect(normalizeForSpeech('my5thing works')).toBe('my5thing works')
+    expect(normalizeForSpeech('class5 room')).toBe('class5 room')
+  })
+})
+
+describe('normalizeForSpeech — abbreviations (phase 2)', () => {
+  it('expands vs / approx / w/', () => {
+    expect(normalizeForSpeech('cats vs dogs')).toBe('cats versus dogs')
+    expect(normalizeForSpeech('cats vs. dogs')).toBe('cats versus dogs')
+    expect(normalizeForSpeech('approx 10 items')).toBe('approximately 10 items')
+    expect(normalizeForSpeech('tea w/ milk')).toBe('tea with milk')
+  })
+})
+
+describe('normalizeForSpeech — acronyms', () => {
+  it('spells curated initialisms letter-by-letter', () => {
+    expect(normalizeForSpeech('the CI passed')).toBe('the C I passed')
+    expect(normalizeForSpeech('open a PR')).toBe('open a P R')
+    expect(normalizeForSpeech('call the API via HTTP')).toBe(
+      'call the A P I via H T T P',
+    )
+    expect(normalizeForSpeech('GPU and CPU load')).toBe('G P U and C P U load')
+    expect(normalizeForSpeech('parse the JSON')).toBe('parse the J S O N')
+  })
+
+  it('leaves word-style acronyms and unknown caps alone', () => {
+    expect(normalizeForSpeech('NASA launch')).toBe('NASA launch')
+    expect(normalizeForSpeech('the FBI report')).toBe('the FBI report')
+  })
+
+  it('does not touch caps inside a larger word', () => {
+    expect(normalizeForSpeech('myAPIkey stays')).toBe('myAPIkey stays')
+  })
+})
+
+describe('normalizeForSpeech — times & dates', () => {
+  it('speaks clock times', () => {
+    expect(normalizeForSpeech('meet at 12:45')).toBe('meet at twelve forty-five')
+    expect(normalizeForSpeech('at 09:05')).toBe('at nine oh five')
+    expect(normalizeForSpeech('at 14:00')).toBe("at fourteen o'clock")
+  })
+
+  it('speaks ISO dates', () => {
+    expect(normalizeForSpeech('on 2026-07-01 we ship')).toBe(
+      'on July first two thousand twenty-six we ship',
+    )
+    expect(normalizeForSpeech('2026-12-25')).toBe(
+      'December twenty-fifth two thousand twenty-six',
+    )
+  })
+})
+
+describe('normalizeForSpeech — conservative, does not mangle real words', () => {
+  it('leaves plain prose untouched', () => {
+    expect(normalizeForSpeech('The quick brown fox jumps.')).toBe(
+      'The quick brown fox jumps.',
+    )
+  })
+
+  it('leaves lowercase day/word tokens and a symbol-free sentence alone', () => {
+    expect(normalizeForSpeech('see you wednesday afternoon')).toBe(
+      'see you wednesday afternoon',
+    )
+    expect(normalizeForSpeech('The report covers three main areas.')).toBe(
+      'The report covers three main areas.',
+    )
+  })
+
+  it('preserves an underscore inside an identifier-like word', () => {
+    // A lone mid-word underscore is not emphasis; keep the token intact.
+    expect(normalizeForSpeech('the my_var name')).toBe('the my_var name')
+  })
+
+  it('returns empty for empty/whitespace input', () => {
+    expect(normalizeForSpeech('')).toBe('')
+    expect(normalizeForSpeech('   \n  ')).toBe('')
+  })
+})

package/telegram-plugin/tests/voice-ondemand.test.ts

@@ -0,0 +1,202 @@
+/**
+ * On-demand voice-out (reply_mode='on-demand') unit tests.
+ *
+ * gateway.ts is a 25k-line module with import-time side effects, so the
+ * on-demand primitives live in ../voice-ondemand.ts (imported by the gateway).
+ * These tests exercise those real primitives + reproduce the exact gateway
+ * decisions (button injection gate, no-synth-at-reply-time, callback routing)
+ * so the observable contract is covered without importing the gateway.
+ */
+
+import { describe, it, expect } from 'bun:test'
+import {
+  VoiceOnDemandCache,
+  VOICE_ONDEMAND_CALLBACK_PREFIX,
+  mintVoiceOnDemandToken,
+  isVoiceOnDemandCallback,
+  parseVoiceOnDemandToken,
+  buildListenKeyboard,
+  mayInjectListenButton,
+} from '../voice-ondemand.js'
+import { parseAgentCallback } from '../inline-keyboard-callbacks.js'
+
+describe('on-demand: token + reserved callback prefix', () => {
+  it('mints an 8-hex-char token', () => {
+    const t = mintVoiceOnDemandToken()
+    expect(t).toMatch(/^[0-9a-f]{8}$/)
+  })
+
+  it('builds a single-button Listen keyboard with a voice: callback', () => {
+    const kb = buildListenKeyboard('deadbeef')
+    expect(kb.inline_keyboard).toHaveLength(1)
+    expect(kb.inline_keyboard[0]).toHaveLength(1)
+    const btn = kb.inline_keyboard[0]![0]!
+    expect(btn.text).toBe('🔊 Listen')
+    expect(btn.callback_data).toBe('voice:deadbeef')
+    expect(btn.callback_data.length).toBeLessThanOrEqual(64) // Telegram cap
+  })
+
+  it('recognises + parses voice: callbacks, rejects others', () => {
+    expect(isVoiceOnDemandCallback('voice:abc123')).toBe(true)
+    expect(isVoiceOnDemandCallback('agent:foo')).toBe(false)
+    expect(parseVoiceOnDemandToken('voice:abc123')).toBe('abc123')
+    expect(parseVoiceOnDemandToken('voice:')).toBeNull() // empty token
+    expect(parseVoiceOnDemandToken('agent:foo')).toBeNull()
+  })
+})
+
+describe('on-demand: callback routes internally, NOT to the agent inbound path', () => {
+  it('a voice: callback is NOT parsed as an agent callback', () => {
+    // The gateway checks isVoiceOnDemandCallback() BEFORE parseAgentCallback().
+    const data = `${VOICE_ONDEMAND_CALLBACK_PREFIX}${mintVoiceOnDemandToken()}`
+    expect(isVoiceOnDemandCallback(data)).toBe(true)
+    // Even if it reached agent routing, the raw voice: data must not be a
+    // valid agent callback (which requires the agent: prefix).
+    expect(parseAgentCallback(data)).toBeNull()
+  })
+})
+
+describe('on-demand: bounded TTL LRU cache', () => {
+  it('stores and retrieves a payload by token', () => {
+    const cache = new VoiceOnDemandCache()
+    cache.put('tok', { text: 'hello world', voice: 'af_bella', speed: 1.1 })
+    expect(cache.get('tok')).toEqual({ text: 'hello world', voice: 'af_bella', speed: 1.1 })
+  })
+
+  it('cache MISS returns null gracefully (no throw)', () => {
+    const cache = new VoiceOnDemandCache()
+    expect(() => cache.get('never-stored')).not.toThrow()
+    expect(cache.get('never-stored')).toBeNull()
+  })
+
+  it('expires entries past the TTL (miss → graceful null)', () => {
+    let now = 1_000
+    const cache = new VoiceOnDemandCache(100 /* ttl */, 500, () => now)
+    cache.put('tok', { text: 'x', speed: 1 })
+    now = 1_050
+    expect(cache.get('tok')).not.toBeNull() // still fresh
+    now = 1_200
+    expect(cache.get('tok')).toBeNull() // expired → graceful miss
+  })
+
+  it('evicts the oldest entry past the size cap (LRU)', () => {
+    const cache = new VoiceOnDemandCache(60_000, 2 /* cap */)
+    cache.put('a', { text: 'a', speed: 1 })
+    cache.put('b', { text: 'b', speed: 1 })
+    cache.put('c', { text: 'c', speed: 1 }) // evicts 'a'
+    expect(cache.size).toBe(2)
+    expect(cache.get('a')).toBeNull()
+    expect(cache.get('b')).not.toBeNull()
+    expect(cache.get('c')).not.toBeNull()
+  })
+})
+
+describe('on-demand: reply-time behaviour (gate + no synthesis)', () => {
+  it('reply_mode=on-demand + local engine → Listen button, no synth at reply time', () => {
+    // Reproduce the gateway reply path decision for reply_mode='on-demand':
+    // the voiceOgg synth loop is guarded to SKIP when replyMode==='on-demand',
+    // and a Listen button is injected instead.
+    const replyMode = 'on-demand' as 'voice+text' | 'voice-only' | 'on-demand'
+
+    let synthCalls = 0
+    const fakeSynth = () => {
+      synthCalls++
+    }
+    // gateway guard: `if (plan != null && plan.replyMode !== 'on-demand')`
+    if (replyMode !== 'on-demand') fakeSynth()
+    expect(synthCalls).toBe(0) // ZERO GPU/sidecar work at reply time
+
+    // No agent buttons → the Listen button is injected.
+    const rawKeyboard: unknown[][] | undefined = undefined
+    expect(mayInjectListenButton(rawKeyboard)).toBe(true)
+    const kb = buildListenKeyboard(mintVoiceOnDemandToken())
+    expect(kb.inline_keyboard[0]![0]!.callback_data.startsWith('voice:')).toBe(true)
+  })
+
+  it('ENGINE GATE: openai + on-demand does NOT inject a Listen button (falls back to immediate synth)', () => {
+    // The gateway computes:
+    //   useOnDemandButton = plan != null && replyMode==='on-demand' && engine==='kokoro'
+    // and both the reply-time synth-skip AND the button injection key on it.
+    // So an openai on-demand config must (a) NOT defer synthesis and (b) NOT
+    // mint a Listen button — its taps would dead-end on the local sidecar.
+    const useOnDemandButton = (
+      engine: 'kokoro' | 'openai',
+      replyMode: 'voice+text' | 'voice-only' | 'on-demand',
+    ) => replyMode === 'on-demand' && engine === 'kokoro'
+
+    // openai + on-demand: no button, immediate synth path runs.
+    expect(useOnDemandButton('openai', 'on-demand')).toBe(false)
+    // kokoro + on-demand: button injected, synth deferred.
+    expect(useOnDemandButton('kokoro', 'on-demand')).toBe(true)
+    // openai non-on-demand modes are unaffected (normal synth).
+    expect(useOnDemandButton('openai', 'voice+text')).toBe(false)
+    expect(useOnDemandButton('openai', 'voice-only')).toBe(false)
+
+    // Reproduce the reply-time synth guard: `if (plan != null && !useOnDemandButton)`.
+    // For openai on-demand it MUST enter the synth loop (fall back), unlike
+    // kokoro on-demand which skips it.
+    let openaiSynthRan = false
+    if (!useOnDemandButton('openai', 'on-demand')) openaiSynthRan = true
+    expect(openaiSynthRan).toBe(true)
+
+    let kokoroSynthRan = false
+    if (!useOnDemandButton('kokoro', 'on-demand')) kokoroSynthRan = true
+    expect(kokoroSynthRan).toBe(false)
+  })
+
+  it('GATE: agent-supplied inline_keyboard present → NO voice button injected', () => {
+    const agentKeyboard = [[{ text: 'Approve', callback_data: 'yes' }]]
+    expect(mayInjectListenButton(agentKeyboard)).toBe(false)
+
+    // An empty keyboard (no rows / empty rows) does not count as agent buttons.
+    expect(mayInjectListenButton([])).toBe(true)
+    expect(mayInjectListenButton([[]])).toBe(true)
+    expect(mayInjectListenButton(undefined)).toBe(true)
+  })
+})
+
+describe('on-demand: single-use — strip the Listen keyboard on success only', () => {
+  // Reproduce the callback handler's control flow. Each terminal branch in the
+  // gateway either returns EARLY (leaving the button intact so the user can
+  // retry) or falls through to the successful sendVoice + keyboard strip.
+  //
+  //   expired cache entry           → answerCallbackQuery + return (no strip)
+  //   sidecar unavailable           → answerCallbackQuery + return (no strip)
+  //   synth failure (!result.ok)    → answerCallbackQuery + return (no strip)
+  //   sendVoice success             → strip keyboard
+  //
+  // We model that as a pure decision so the observable contract — strip iff the
+  // audio was actually delivered — is pinned without importing the gateway.
+  type Outcome = 'expired' | 'sidecar-unavailable' | 'synth-failed' | 'sent'
+  const shouldStripListenKeyboard = (outcome: Outcome, cbMessageId: number | undefined): boolean =>
+    outcome === 'sent' && cbMessageId != null
+
+  it('strips the keyboard after a successful sendVoice', () => {
+    expect(shouldStripListenKeyboard('sent', 42)).toBe(true)
+  })
+
+  it('does NOT strip when the cache entry expired (user can retry)', () => {
+    expect(shouldStripListenKeyboard('expired', 42)).toBe(false)
+  })
+
+  it('does NOT strip when the voice sidecar is unavailable (user can retry)', () => {
+    expect(shouldStripListenKeyboard('sidecar-unavailable', 42)).toBe(false)
+  })
+
+  it('does NOT strip when synthesis failed (user can retry)', () => {
+    expect(shouldStripListenKeyboard('synth-failed', 42)).toBe(false)
+  })
+
+  it('cannot strip without a callback message id even on success', () => {
+    // The gateway guards the strip on `cbMessageId != null` (no message → no
+    // keyboard to edit).
+    expect(shouldStripListenKeyboard('sent', undefined)).toBe(false)
+  })
+
+  it('strips by clearing the inline keyboard (empty rows)', () => {
+    // The strip payload the handler sends: reply_markup with an empty
+    // inline_keyboard — the same shape the agent-button single_use strip uses.
+    const stripMarkup = { reply_markup: { inline_keyboard: [] as unknown[][] } }
+    expect(stripMarkup.reply_markup.inline_keyboard).toHaveLength(0)
+  })
+})