switchroom 0.16.29 → 0.16.46

package/telegram-plugin/tests/voice-synthesize-sidecar.test.ts

@@ -0,0 +1,352 @@
+/**
+ * Unit tests for the LOCAL TTS sidecar synthesis path (voice PR-C2):
+ *   - synthesizeViaSidecar (HTTP POST to /tts, mocked fetch)
+ *
+ * The OUTBOUND mirror of voice-transcribe-sidecar.test.ts: every error
+ * reason is pinned so a refactor can't silently change the contract the
+ * gateway depends on (any non-ok → null → text-only fallback). The /tts
+ * endpoint returns RAW OGG bytes on success (not JSON), so the happy-path
+ * asserts on arrayBuffer + the audio/ogg-style meta headers.
+ */
+
+import { describe, it, expect } from 'bun:test'
+import {
+  synthesizeViaSidecar,
+  chunkTtsText,
+  clampTtsSpeed,
+  SIDECAR_TTS_MAX_CHARS,
+  DEFAULT_SIDECAR_BASE_URL,
+} from '../voice-synthesize-sidecar.js'
+
+const OGG_BYTES = new Uint8Array([0x4f, 0x67, 0x67, 0x53]) // OggS magic
+
+/** Mock a 200 audio/ogg response carrying `bytes`. */
+function makeOggFetch(
+  bytes: Uint8Array,
+  headers: Record<string, string> = {},
+): typeof fetch {
+  return (async () => ({
+    ok: true,
+    status: 200,
+    arrayBuffer: async () => bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength),
+    text: async () => '',
+    headers: new Headers(headers),
+  })) as unknown as typeof fetch
+}
+
+/** Mock a non-2xx JSON error response. */
+function makeErrFetch(status: number, body: unknown): typeof fetch {
+  return (async () => ({
+    ok: false,
+    status,
+    arrayBuffer: async () => new ArrayBuffer(0),
+    text: async () => (typeof body === 'string' ? body : JSON.stringify(body)),
+    headers: new Headers(),
+  })) as unknown as typeof fetch
+}
+
+describe('synthesizeViaSidecar — pre-flight checks', () => {
+  it('returns no-token when token is empty', async () => {
+    const r = await synthesizeViaSidecar({
+      token: '',
+      text: 'hello',
+      fetchImpl: makeOggFetch(OGG_BYTES),
+    })
+    expect(r).toMatchObject({ ok: false, reason: 'no-token' })
+  })
+
+  it('returns empty-text on whitespace-only text', async () => {
+    const r = await synthesizeViaSidecar({ token: 't', text: '   ' })
+    expect(r).toMatchObject({ ok: false, reason: 'empty-text' })
+  })
+
+  it('returns text-too-long above the cap', async () => {
+    const r = await synthesizeViaSidecar({
+      token: 't',
+      text: 'x'.repeat(SIDECAR_TTS_MAX_CHARS + 1),
+    })
+    expect(r).toMatchObject({ ok: false, reason: 'text-too-long' })
+  })
+})
+
+describe('synthesizeViaSidecar — happy path', () => {
+  it('returns OGG bytes + meta on 200 audio/ogg', async () => {
+    const r = await synthesizeViaSidecar({
+      token: 't',
+      text: 'Hello world',
+      fetchImpl: makeOggFetch(OGG_BYTES, {
+        'X-Voice-Duration-Ms': '1234',
+        'X-Voice-Audio-Seconds': '2.5',
+        'X-Voice-Voice': 'af_heart',
+      }),
+    })
+    expect(r.ok).toBe(true)
+    if (r.ok) {
+      expect(Array.from(r.audio)).toEqual(Array.from(OGG_BYTES))
+      expect(r.durationMs).toBe(1234)
+      expect(r.audioSeconds).toBe(2.5)
+      expect(r.voice).toBe('af_heart')
+    }
+  })
+
+  it('POSTs JSON {text,voice,format:ogg} + X-Voice-Token to <base>/tts', async () => {
+    let receivedUrl = ''
+    let receivedToken: string | null = null
+    let receivedBody: string | null = null
+    const fakeFetch: typeof fetch = (async (url: string, init?: RequestInit) => {
+      receivedUrl = url
+      receivedToken = (init?.headers as Record<string, string>)['X-Voice-Token']
+      receivedBody = init?.body as string
+      return {
+        ok: true,
+        status: 200,
+        arrayBuffer: async () => OGG_BYTES.buffer.slice(0),
+        text: async () => '',
+        headers: new Headers(),
+      }
+    }) as unknown as typeof fetch
+
+    const r = await synthesizeViaSidecar({
+      token: 'secret-token',
+      text: 'bonjour',
+      voice: 'af_sky',
+      fetchImpl: fakeFetch,
+    })
+    expect(r.ok).toBe(true)
+    expect(receivedUrl).toBe(`${DEFAULT_SIDECAR_BASE_URL}/tts`)
+    expect(receivedToken).toBe('secret-token')
+    const parsed = JSON.parse(receivedBody!)
+    expect(parsed.text).toBe('bonjour')
+    expect(parsed.voice).toBe('af_sky')
+    expect(parsed.format).toBe('ogg')
+  })
+
+  it('omits the voice field when none is supplied', async () => {
+    let receivedBody: string | null = null
+    const fakeFetch: typeof fetch = (async (_url: string, init?: RequestInit) => {
+      receivedBody = init?.body as string
+      return {
+        ok: true,
+        status: 200,
+        arrayBuffer: async () => OGG_BYTES.buffer.slice(0),
+        text: async () => '',
+        headers: new Headers(),
+      }
+    }) as unknown as typeof fetch
+    await synthesizeViaSidecar({ token: 't', text: 'hi', fetchImpl: fakeFetch })
+    const parsed = JSON.parse(receivedBody!)
+    expect('voice' in parsed).toBe(false)
+  })
+
+  it('omits the speed field when none is supplied (sidecar defaults to 1.0)', async () => {
+    let receivedBody: string | null = null
+    const fakeFetch: typeof fetch = (async (_url: string, init?: RequestInit) => {
+      receivedBody = init?.body as string
+      return {
+        ok: true,
+        status: 200,
+        arrayBuffer: async () => OGG_BYTES.buffer.slice(0),
+        text: async () => '',
+        headers: new Headers(),
+      }
+    }) as unknown as typeof fetch
+    await synthesizeViaSidecar({ token: 't', text: 'hi', fetchImpl: fakeFetch })
+    const parsed = JSON.parse(receivedBody!)
+    expect('speed' in parsed).toBe(false)
+  })
+
+  it('includes speed in the /tts body when supplied', async () => {
+    let receivedBody: string | null = null
+    const fakeFetch: typeof fetch = (async (_url: string, init?: RequestInit) => {
+      receivedBody = init?.body as string
+      return {
+        ok: true,
+        status: 200,
+        arrayBuffer: async () => OGG_BYTES.buffer.slice(0),
+        text: async () => '',
+        headers: new Headers(),
+      }
+    }) as unknown as typeof fetch
+    await synthesizeViaSidecar({ token: 't', text: 'hi', speed: 1.1, fetchImpl: fakeFetch })
+    const parsed = JSON.parse(receivedBody!)
+    expect(parsed.speed).toBe(1.1)
+  })
+
+  it('clamps an out-of-range speed before putting it on the wire', async () => {
+    const cap = async (speed: number): Promise<number> => {
+      let receivedBody: string | null = null
+      const fakeFetch: typeof fetch = (async (_url: string, init?: RequestInit) => {
+        receivedBody = init?.body as string
+        return {
+          ok: true,
+          status: 200,
+          arrayBuffer: async () => OGG_BYTES.buffer.slice(0),
+          text: async () => '',
+          headers: new Headers(),
+        }
+      }) as unknown as typeof fetch
+      await synthesizeViaSidecar({ token: 't', text: 'hi', speed, fetchImpl: fakeFetch })
+      return JSON.parse(receivedBody!).speed
+    }
+    expect(await cap(5.0)).toBe(2.0) // above max → 2.0
+    expect(await cap(0.1)).toBe(0.5) // below min → 0.5
+  })
+})
+
+describe('clampTtsSpeed', () => {
+  it('passes in-range values through', () => {
+    for (const v of [0.5, 0.75, 1.0, 1.1, 1.5, 2.0]) {
+      expect(clampTtsSpeed(v)).toBe(v)
+    }
+  })
+
+  it('clamps out-of-range numbers to the nearest bound', () => {
+    expect(clampTtsSpeed(0.1)).toBe(0.5)
+    expect(clampTtsSpeed(-3)).toBe(0.5)
+    expect(clampTtsSpeed(2.5)).toBe(2.0)
+    expect(clampTtsSpeed(100)).toBe(2.0)
+  })
+
+  it('falls back to the default for non-finite / non-numeric input', () => {
+    expect(clampTtsSpeed(undefined)).toBe(1.0)
+    expect(clampTtsSpeed(null)).toBe(1.0)
+    expect(clampTtsSpeed(NaN)).toBe(1.0)
+    expect(clampTtsSpeed('fast')).toBe(1.0)
+    expect(clampTtsSpeed(undefined, 1.1)).toBe(1.1) // custom fallback
+  })
+
+  it('falls back to wall-clock durationMs when headers are absent', async () => {
+    const r = await synthesizeViaSidecar({
+      token: 't',
+      text: 'hi',
+      fetchImpl: makeOggFetch(OGG_BYTES),
+    })
+    expect(r.ok).toBe(true)
+    if (r.ok) {
+      expect(r.durationMs).toBeGreaterThanOrEqual(0)
+      expect(r.audioSeconds).toBeNull()
+      expect(r.voice).toBeNull()
+    }
+  })
+})
+
+describe('synthesizeViaSidecar — error paths', () => {
+  it('echoes the sidecar reason from a non-2xx JSON body', async () => {
+    const r = await synthesizeViaSidecar({
+      token: 't',
+      text: 'hi',
+      fetchImpl: makeErrFetch(413, { ok: false, reason: 'text-too-long', detail: '9999 > 1200' }),
+    })
+    expect(r).toMatchObject({ ok: false, reason: 'text-too-long', detail: '9999 > 1200' })
+  })
+
+  it('falls back to http-<n> when the error body is not JSON', async () => {
+    const r = await synthesizeViaSidecar({
+      token: 't',
+      text: 'hi',
+      fetchImpl: makeErrFetch(503, 'service unavailable'),
+    })
+    expect(r).toMatchObject({ ok: false, reason: 'http-503' })
+  })
+
+  it('returns empty-audio on a 200 with no bytes', async () => {
+    const r = await synthesizeViaSidecar({
+      token: 't',
+      text: 'hi',
+      fetchImpl: makeOggFetch(new Uint8Array(0)),
+    })
+    expect(r).toMatchObject({ ok: false, reason: 'empty-audio' })
+  })
+
+  it('returns fetch-failed on a network error', async () => {
+    const boom: typeof fetch = (async () => {
+      throw new Error('ECONNREFUSED')
+    }) as unknown as typeof fetch
+    const r = await synthesizeViaSidecar({ token: 't', text: 'hi', fetchImpl: boom })
+    expect(r).toMatchObject({ ok: false, reason: 'fetch-failed' })
+  })
+
+  it('returns timeout when the fetch aborts', async () => {
+    const aborted: typeof fetch = (async () => {
+      throw new Error('The operation was aborted')
+    }) as unknown as typeof fetch
+    const r = await synthesizeViaSidecar({ token: 't', text: 'hi', fetchImpl: aborted })
+    expect(r).toMatchObject({ ok: false, reason: 'timeout' })
+  })
+})
+
+describe('chunkTtsText — long-reply voice chunking (PR-C2)', () => {
+  it('returns a single chunk when text fits the cap', () => {
+    expect(chunkTtsText('Short answer.', 600)).toEqual(['Short answer.'])
+  })
+
+  it('returns no chunks for empty text', () => {
+    expect(chunkTtsText('', 600)).toEqual([])
+    expect(chunkTtsText('   ', 600)).toEqual([])
+  })
+
+  it('splits a long reply into multiple chunks, each under the cap', () => {
+    const sentence = 'This is a sentence that is reasonably long. '
+    const text = sentence.repeat(20).trim() // ~880 chars
+    const chunks = chunkTtsText(text, 200)
+    expect(chunks.length).toBeGreaterThan(1)
+    for (const c of chunks) expect(c.length).toBeLessThanOrEqual(200)
+    // No text is lost: every sentence's words survive across the chunks.
+    const rejoined = chunks.join(' ')
+    expect(rejoined).toContain('reasonably long')
+    expect(rejoined.split('reasonably long').length - 1).toBe(20)
+  })
+
+  it('prefers sentence boundaries — does not cut mid-sentence', () => {
+    const text =
+      'First sentence here. Second sentence here. Third sentence here. Fourth one too.'
+    const chunks = chunkTtsText(text, 45)
+    // Each chunk should end at a sentence terminator (no dangling fragment).
+    for (const c of chunks) expect(/[.!?]$/.test(c)).toBe(true)
+  })
+
+  it('hard-slices a single sentence longer than the cap (no boundary fits)', () => {
+    const longWord = 'a'.repeat(50)
+    const text = `${longWord} ${longWord} ${longWord}` // one boundary-less-ish run
+    const chunks = chunkTtsText(text, 60)
+    expect(chunks.length).toBeGreaterThan(1)
+    for (const c of chunks) expect(c.length).toBeLessThanOrEqual(60)
+  })
+
+  it('never emits a chunk over the cap even with a giant tokenless blob', () => {
+    const blob = 'x'.repeat(5000)
+    const chunks = chunkTtsText(blob, 1200)
+    expect(chunks.length).toBeGreaterThan(1)
+    for (const c of chunks) expect(c.length).toBeLessThanOrEqual(1200)
+  })
+})
+
+describe('synthesizeViaSidecar — multi-chunk send path (PR-C2)', () => {
+  it('synthesizes each chunk independently (one POST per chunk)', async () => {
+    const text = 'Sentence one is here. '.repeat(40).trim() // long → many chunks
+    const chunks = chunkTtsText(text, 200)
+    expect(chunks.length).toBeGreaterThan(1)
+
+    let calls = 0
+    const fakeFetch: typeof fetch = (async () => {
+      calls++
+      return {
+        ok: true,
+        status: 200,
+        arrayBuffer: async () => OGG_BYTES.buffer.slice(0),
+        text: async () => '',
+        headers: new Headers(),
+      }
+    }) as unknown as typeof fetch
+
+    // Mirror the gateway's per-chunk synthesis loop.
+    const oggs: Uint8Array[] = []
+    for (const c of chunks) {
+      const r = await synthesizeViaSidecar({ token: 't', text: c, fetchImpl: fakeFetch })
+      expect(r.ok).toBe(true)
+      if (r.ok) oggs.push(r.audio)
+    }
+    expect(calls).toBe(chunks.length)
+    expect(oggs.length).toBe(chunks.length)
+  })
+})

package/telegram-plugin/tests/voice-transcribe-sidecar.test.ts

@@ -0,0 +1,332 @@
+/**
+ * Unit tests for the LOCAL STT sidecar transcription path (voice PR-B2):
+ *   - transcribeViaSidecar (HTTP POST to /stt, mocked fetch)
+ *   - materializeSidecarToken (vault resolution, mocked broker)
+ *
+ * Mirrors the cloud twin's test (voice-transcribe.test.ts): every error
+ * reason is pinned so a refactor can't silently change the contract the
+ * gateway depends on (any non-ok → null → "(voice message)" fallback).
+ */
+
+import { describe, it, expect } from 'bun:test'
+import {
+  transcribeViaSidecar,
+  SIDECAR_MAX_BYTES,
+  DEFAULT_SIDECAR_BASE_URL,
+} from '../voice-transcribe-sidecar.js'
+import {
+  materializeSidecarToken,
+  DEFAULT_VOICE_SIDECAR_TOKEN_REF,
+  VOICE_SIDECAR_TOKEN_KEY,
+} from '../../src/telegram/materialize-sidecar-token.js'
+import type { resolveVaultReferencesViaBroker } from '../../src/vault/resolver.js'
+import type { SwitchroomConfig } from '../../src/config/schema.js'
+
+const SMALL_AUDIO = new Uint8Array([0x4f, 0x67, 0x67, 0x53]) // OggS magic
+
+function makeFetch(status: number, body: unknown): typeof fetch {
+  return (async () => ({
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body,
+    text: async () => (typeof body === 'string' ? body : JSON.stringify(body)),
+    headers: new Headers(),
+  })) as unknown as typeof fetch
+}
+
+describe('transcribeViaSidecar — pre-flight checks', () => {
+  it('returns no-token when token is empty', async () => {
+    const r = await transcribeViaSidecar({
+      token: '',
+      audio: SMALL_AUDIO,
+      filename: 'voice.ogg',
+      fetchImpl: makeFetch(200, { ok: true, text: 'x' }),
+    })
+    expect(r).toMatchObject({ ok: false, reason: 'no-token' })
+  })
+
+  it('returns audio-too-short on empty audio', async () => {
+    const r = await transcribeViaSidecar({
+      token: 't',
+      audio: new Uint8Array(0),
+      filename: 'voice.ogg',
+    })
+    expect(r).toMatchObject({ ok: false, reason: 'audio-too-short' })
+  })
+
+  it('returns audio-too-large above the cap', async () => {
+    const tooBig = new Uint8Array(SIDECAR_MAX_BYTES + 1)
+    const r = await transcribeViaSidecar({
+      token: 't',
+      audio: tooBig,
+      filename: 'voice.ogg',
+    })
+    expect(r).toMatchObject({ ok: false, reason: 'audio-too-large' })
+  })
+})
+
+describe('transcribeViaSidecar — happy path', () => {
+  it('returns transcript on 200 + valid JSON', async () => {
+    const r = await transcribeViaSidecar({
+      token: 't',
+      audio: SMALL_AUDIO,
+      filename: 'voice.ogg',
+      fetchImpl: makeFetch(200, {
+        ok: true,
+        text: 'Hello world',
+        language: 'en',
+        durationMs: 1234,
+        audioSeconds: 3.2,
+      }),
+    })
+    expect(r.ok).toBe(true)
+    if (r.ok) {
+      expect(r.text).toBe('Hello world')
+      expect(r.language).toBe('en')
+      expect(r.durationMs).toBe(1234)
+      expect(r.audioSeconds).toBe(3.2)
+    }
+  })
+
+  it('sends the X-Voice-Token header, audio + language fields, to <base>/stt', async () => {
+    let receivedUrl = ''
+    let receivedToken: string | null = null
+    let receivedForm: FormData | null = null
+    const fakeFetch: typeof fetch = (async (url: string, init?: RequestInit) => {
+      receivedUrl = url
+      receivedToken = (init?.headers as Record<string, string>)['X-Voice-Token']
+      receivedForm = init?.body as FormData
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({ ok: true, text: 'bonjour' }),
+        text: async () => '',
+        headers: new Headers(),
+      }
+    }) as unknown as typeof fetch
+
+    const r = await transcribeViaSidecar({
+      token: 'secret-token',
+      audio: SMALL_AUDIO,
+      filename: 'voice.ogg',
+      language: 'fr',
+      fetchImpl: fakeFetch,
+    })
+    expect(r.ok).toBe(true)
+    expect(receivedUrl).toBe(`${DEFAULT_SIDECAR_BASE_URL}/stt`)
+    expect(receivedToken).toBe('secret-token')
+    expect(receivedForm).not.toBeNull()
+    expect(receivedForm!.get('language')).toBe('fr')
+    expect(receivedForm!.get('audio')).not.toBeNull()
+  })
+
+  it('falls back to wall-clock durationMs when the sidecar omits it', async () => {
+    const r = await transcribeViaSidecar({
+      token: 't',
+      audio: SMALL_AUDIO,
+      filename: 'voice.ogg',
+      fetchImpl: makeFetch(200, { ok: true, text: 'hi' }),
+    })
+    expect(r.ok).toBe(true)
+    if (r.ok) {
+      expect(r.durationMs).toBeGreaterThanOrEqual(0)
+      expect(r.audioSeconds).toBeNull()
+    }
+  })
+})
+
+describe('transcribeViaSidecar — error paths', () => {
+  it('returns http-401 on a wrong/missing token (sidecar rejects)', async () => {
+    const r = await transcribeViaSidecar({
+      token: 't',
+      audio: SMALL_AUDIO,
+      filename: 'voice.ogg',
+      fetchImpl: makeFetch(401, { ok: false, reason: 'unauthorized' }),
+    })
+    expect(r).toMatchObject({ ok: false, reason: 'http-401' })
+  })
+
+  it('surfaces the sidecar reason on a 2xx { ok: false } body', async () => {
+    const r = await transcribeViaSidecar({
+      token: 't',
+      audio: SMALL_AUDIO,
+      filename: 'voice.ogg',
+      fetchImpl: makeFetch(200, { ok: false, reason: 'gpu-timeout', detail: 'busy' }),
+    })
+    expect(r).toMatchObject({ ok: false, reason: 'gpu-timeout' })
+  })
+
+  it('returns malformed-response when 200 body has no text field', async () => {
+    const r = await transcribeViaSidecar({
+      token: 't',
+      audio: SMALL_AUDIO,
+      filename: 'voice.ogg',
+      fetchImpl: makeFetch(200, { ok: true, unexpected: 'shape' }),
+    })
+    expect(r).toMatchObject({ ok: false, reason: 'malformed-response' })
+  })
+
+  it('returns fetch-failed on a thrown network error', async () => {
+    const fakeFetch: typeof fetch = (async () => {
+      throw new Error('ECONNREFUSED')
+    }) as unknown as typeof fetch
+    const r = await transcribeViaSidecar({
+      token: 't',
+      audio: SMALL_AUDIO,
+      filename: 'voice.ogg',
+      fetchImpl: fakeFetch,
+    })
+    expect(r).toMatchObject({ ok: false, reason: 'fetch-failed' })
+    expect(r.detail).toContain('ECONNREFUSED')
+  })
+
+  it('returns timeout when fetch is aborted', async () => {
+    const fakeFetch: typeof fetch = (async () => {
+      throw new Error('The operation was aborted')
+    }) as unknown as typeof fetch
+    const r = await transcribeViaSidecar({
+      token: 't',
+      audio: SMALL_AUDIO,
+      filename: 'voice.ogg',
+      timeoutMs: 5,
+      fetchImpl: fakeFetch,
+    })
+    expect(r).toMatchObject({ ok: false, reason: 'timeout' })
+  })
+})
+
+// ── materializeSidecarToken — vault resolution (mirrors the key helper) ──
+
+const EMPTY_CONFIG = {} as unknown as SwitchroomConfig
+
+function makeBrokerResolver(
+  resolvedRefs: Record<string, string>,
+): typeof resolveVaultReferencesViaBroker {
+  return (async (config: SwitchroomConfig) => {
+    const ref = config.telegram?.bot_token
+    if (ref && resolvedRefs[ref] !== undefined) {
+      return {
+        ok: true,
+        config: {
+          ...config,
+          telegram: { ...config.telegram, bot_token: resolvedRefs[ref] },
+        },
+      }
+    }
+    return { ok: false, reason: 'not_found' as const }
+  }) as unknown as typeof resolveVaultReferencesViaBroker
+}
+
+describe('materializeSidecarToken — vault resolution', () => {
+  it('defaults to vault:voice/sidecar-token', () => {
+    expect(VOICE_SIDECAR_TOKEN_KEY).toBe('voice/sidecar-token')
+    expect(DEFAULT_VOICE_SIDECAR_TOKEN_REF).toBe('vault:voice/sidecar-token')
+  })
+
+  it('resolves the configured vault ref via the broker', async () => {
+    const tok = await materializeSidecarToken({
+      config: EMPTY_CONFIG,
+      env: {},
+      resolveViaBroker: makeBrokerResolver({
+        'vault:voice/sidecar-token': 'deadbeef' + 'cafe',
+      }),
+    })
+    expect(tok).toBe('deadbeef' + 'cafe')
+  })
+
+  it('returns a literal (non-vault) token directly without the broker', async () => {
+    let brokerCalled = false
+    const tok = await materializeSidecarToken({
+      tokenRef: 'raw' + 'token',
+      config: EMPTY_CONFIG,
+      env: {},
+      resolveViaBroker: (async () => {
+        brokerCalled = true
+        return { ok: false, reason: 'not_found' as const }
+      }) as unknown as typeof resolveVaultReferencesViaBroker,
+    })
+    expect(tok).toBe('raw' + 'token')
+    expect(brokerCalled).toBe(false)
+  })
+
+  it('returns null (graceful fallback, no throw) when unresolvable', async () => {
+    const tok = await materializeSidecarToken(
+      {
+        config: EMPTY_CONFIG,
+        env: {},
+        resolveViaBroker: makeBrokerResolver({}),
+      },
+      () => {},
+    )
+    expect(tok).toBeNull()
+  })
+
+  // ── Regression: single-key isolation (voice token bug) ──
+  //
+  // resolveVaultReferencesViaBroker fails the WHOLE batch unless EVERY vault:
+  // ref resolves. Admin-only refs (litellm/master-key,
+  // google/client-secret) are correctly DENIED to a normal agent — so if the
+  // materializer passes the full config, those denials sink the resolution
+  // even though voice/sidecar-token itself is granted. The fix passes a
+  // MINIMAL config carrying only the one ref. These tests fail against the
+  // old `...config` spread.
+
+  function collectRefs(v: unknown, out: Set<string>): void {
+    if (typeof v === 'string' && v.startsWith('vault:')) out.add(v.slice('vault:'.length).split('#')[0])
+    else if (Array.isArray(v)) for (const i of v) collectRefs(i, out)
+    else if (v !== null && typeof v === 'object') for (const val of Object.values(v as Record<string, unknown>)) collectRefs(val, out)
+  }
+
+  /** Resolver stub with the real batch semantics: denies unless every collected ref is granted. */
+  function makeBatchResolver(
+    granted: Record<string, string>,
+    onCall?: (refs: Set<string>) => void,
+  ): typeof resolveVaultReferencesViaBroker {
+    return (async (config: SwitchroomConfig) => {
+      const refs = new Set<string>()
+      collectRefs(config, refs)
+      onCall?.(refs)
+      for (const r of refs) {
+        if (granted[`vault:${r}`] === undefined) {
+          return { ok: false, reason: 'denied' as const }
+        }
+      }
+      const resolved = granted[config.telegram?.bot_token ?? '']
+      return {
+        ok: true,
+        config: { ...config, telegram: { ...config.telegram, bot_token: resolved } },
+      }
+    }) as unknown as typeof resolveVaultReferencesViaBroker
+  }
+
+  const CONFIG_WITH_ADMIN_REFS = {
+    telegram: { bot_token: 'vault:tg/bot' },
+    litellm: { admin_key: 'vault:litellm/master-key' },
+    google_workspace: { google_client_secret: 'vault:google/client-secret' },
+    agents: { klanker: { some_key: 'vault:per-agent/secret' } },
+    vault: { path: '~/.switchroom/vault.enc' },
+  } as unknown as SwitchroomConfig
+
+  it('resolves the sidecar token even when the config carries admin-only vault refs the broker DENIES', async () => {
+    const tok = await materializeSidecarToken({
+      config: CONFIG_WITH_ADMIN_REFS,
+      env: {},
+      resolveViaBroker: makeBatchResolver({ 'vault:voice/sidecar-token': 'deadbeefcafe' }),
+    })
+    expect(tok).toBe('deadbeefcafe')
+  })
+
+  it('invokes the resolver with a config containing exactly ONE vault ref (the sidecar token)', async () => {
+    let seen: Set<string> | null = null
+    await materializeSidecarToken({
+      config: CONFIG_WITH_ADMIN_REFS,
+      env: {},
+      resolveViaBroker: makeBatchResolver(
+        { 'vault:voice/sidecar-token': 'deadbeefcafe' },
+        (refs) => { seen = refs },
+      ),
+    })
+    expect(seen).not.toBeNull()
+    expect([...seen!]).toEqual(['voice/sidecar-token'])
+  })
+})