@phuetz/code-buddy 1.6.0 → 2.0.0

package/dist/voice/local-whisper.d.ts

@@ -3,7 +3,18 @@ export interface LocalWhisperOptions {
     model?: string;
     timeoutMs?: number;
 }
+export interface LocalWhisperSegment {
+    startSeconds: number;
+    endSeconds: number;
+    text: string;
+}
+export interface LocalWhisperDetailedResult {
+    text: string;
+    segments: LocalWhisperSegment[];
+}
 /** Transcribe an audio file (wav/ogg/mp3/webm…) to text via local faster-whisper. */
 export declare function transcribeFile(audioPath: string, options?: LocalWhisperOptions): Promise<string>;
+/** Transcribe with local timestamps so downstream diarization can label real turns. */
+export declare function transcribeFileDetailed(audioPath: string, options?: LocalWhisperOptions): Promise<LocalWhisperDetailedResult>;
 /** True if a local faster-whisper interpreter looks available. */
 export declare function localWhisperAvailable(): boolean;

package/dist/voice/local-whisper.js

@@ -38,10 +38,15 @@ from faster_whisper import WhisperModel
 audio, model, lang = sys.argv[1], sys.argv[2], (sys.argv[3] or None)
 m = WhisperModel(model, device="cpu", compute_type="int8")
 segs, _info = m.transcribe(audio, language=lang, vad_filter=True, beam_size=1)
-print(json.dumps({"text": " ".join(s.text.strip() for s in segs).strip()}))
+segments = [{"startSeconds": float(s.start), "endSeconds": float(s.end), "text": s.text.strip()} for s in segs if s.text.strip()]
+print(json.dumps({"text": " ".join(s["text"] for s in segments).strip(), "segments": segments}))
 `;
 /** Transcribe an audio file (wav/ogg/mp3/webm…) to text via local faster-whisper. */
 export async function transcribeFile(audioPath, options = {}) {
+    return (await transcribeFileDetailed(audioPath, options)).text;
+}
+/** Transcribe with local timestamps so downstream diarization can label real turns. */
+export async function transcribeFileDetailed(audioPath, options = {}) {
     const language = options.language ?? 'fr';
     const model = options.model ||
         process.env.CODEBUDDY_WHISPER_MODEL ||
@@ -77,7 +82,18 @@ export async function transcribeFile(audioPath, options = {}) {
             try {
                 const line = stdout.trim().split('\n').filter(Boolean).pop() || '{}';
                 const parsed = JSON.parse(line);
-                resolve((parsed.text || '').trim());
+                const segments = Array.isArray(parsed.segments)
+                    ? parsed.segments.filter((segment) => (Number.isFinite(segment.startSeconds)
+                        && Number.isFinite(segment.endSeconds)
+                        && segment.endSeconds >= segment.startSeconds
+                        && typeof segment.text === 'string'
+                        && segment.text.trim().length > 0)).map((segment) => ({
+                        startSeconds: segment.startSeconds,
+                        endSeconds: segment.endSeconds,
+                        text: segment.text.trim(),
+                    }))
+                    : [];
+                resolve({ text: (parsed.text || '').trim(), segments });
             }
             catch (e) {
                 reject(new Error(`local-whisper: bad output: ${String(e)} :: ${stdout.slice(-200)}`));

package/dist/voice/pcm-edges.d.ts

@@ -0,0 +1,43 @@
+/** Trim quasi-silent PCM16 head/tail while retaining 20 ms of natural margin. */
+export declare function trimSilence(pcm16: Uint8Array, sampleRate: number, thresholdDbfs?: number): Buffer;
+/** Apply symmetric linear PCM16 fades without mutating the input buffer. */
+export declare function applyEdgeFades(pcm16: Uint8Array, sampleRate: number, fadeMs?: number): Buffer;
+/** Produce deterministic mono PCM16 silence for the gap between two sentences. */
+export declare function makeInterSentenceSilence(sampleRate: number, ms?: number): Buffer;
+/** Condition a complete PCM16 WAV, optionally inserting a fixed leading sentence gap. */
+export declare function conditionPcm16Wav(input: Uint8Array, options?: {
+    prependSilenceMs?: number;
+    thresholdDbfs?: number;
+    fadeMs?: number;
+}): Buffer;
+/**
+ * Progressive counterpart of `conditionPcm16Wav`. It releases the spoken body
+ * as chunks arrive while retaining only the leading silence and a small tail
+ * needed for trimming/fade-out.
+ */
+export declare class Pcm16WavStreamEdges {
+    private mode;
+    private prefix;
+    private leading;
+    private tail;
+    private sampleRate;
+    private started;
+    private outputAudio;
+    private readonly thresholdDbfs;
+    private readonly fadeMs;
+    private readonly prependSilenceMs;
+    constructor(options?: {
+        prependSilenceMs?: number;
+        thresholdDbfs?: number;
+        fadeMs?: number;
+    });
+    push(chunk: Uint8Array): Buffer[];
+    flush(): Buffer[];
+    hasOutputAudio(): boolean;
+    private processPayload;
+    private bufferTail;
+    private firstLoudSample;
+    private lastLoudSample;
+    private fadeIn;
+    private fadeOut;
+}

package/dist/voice/pcm-edges.js

@@ -0,0 +1,210 @@
+import { probePcm16Wav } from './tts-volume.js';
+const PCM16_MAX = 32_767;
+const EDGE_MARGIN_MS = 20;
+function paired(buffer) {
+    const source = Buffer.from(buffer);
+    return source.subarray(0, source.length - (source.length & 1));
+}
+function thresholdAmplitude(thresholdDbfs) {
+    return PCM16_MAX * 10 ** (thresholdDbfs / 20);
+}
+/** Trim quasi-silent PCM16 head/tail while retaining 20 ms of natural margin. */
+export function trimSilence(pcm16, sampleRate, thresholdDbfs = -50) {
+    const source = paired(pcm16);
+    if (source.length === 0 || sampleRate <= 0)
+        return Buffer.alloc(0);
+    const threshold = thresholdAmplitude(thresholdDbfs);
+    const sampleCount = source.length / 2;
+    let first = -1;
+    let last = -1;
+    for (let index = 0; index < sampleCount; index++) {
+        if (Math.abs(source.readInt16LE(index * 2)) >= threshold) {
+            if (first < 0)
+                first = index;
+            last = index;
+        }
+    }
+    if (first < 0 || last < 0)
+        return Buffer.alloc(0);
+    const margin = Math.max(0, Math.round(sampleRate * EDGE_MARGIN_MS / 1_000));
+    const start = Math.max(0, first - margin);
+    const end = Math.min(sampleCount, last + 1 + margin);
+    return Buffer.from(source.subarray(start * 2, end * 2));
+}
+/** Apply symmetric linear PCM16 fades without mutating the input buffer. */
+export function applyEdgeFades(pcm16, sampleRate, fadeMs = 5) {
+    const output = Buffer.from(paired(pcm16));
+    const sampleCount = output.length / 2;
+    const fadeSamples = Math.min(Math.floor(sampleCount / 2), Math.max(0, Math.round(sampleRate * fadeMs / 1_000)));
+    for (let index = 0; index < fadeSamples; index++) {
+        const factor = index / fadeSamples;
+        const endIndex = sampleCount - 1 - index;
+        output.writeInt16LE(Math.round(output.readInt16LE(index * 2) * factor), index * 2);
+        output.writeInt16LE(Math.round(output.readInt16LE(endIndex * 2) * factor), endIndex * 2);
+    }
+    return output;
+}
+/** Produce deterministic mono PCM16 silence for the gap between two sentences. */
+export function makeInterSentenceSilence(sampleRate, ms = 280) {
+    if (sampleRate <= 0 || ms <= 0)
+        return Buffer.alloc(0);
+    return Buffer.alloc(Math.max(0, Math.round(sampleRate * ms / 1_000)) * 2);
+}
+/** Condition a complete PCM16 WAV, optionally inserting a fixed leading sentence gap. */
+export function conditionPcm16Wav(input, options = {}) {
+    const source = Buffer.from(input);
+    const probe = probePcm16Wav(source);
+    if (probe.status !== 'ready')
+        return Buffer.from(source);
+    const { dataOffset, sampleRate } = probe.layout;
+    const trimmed = trimSilence(source.subarray(dataOffset), sampleRate, options.thresholdDbfs);
+    const faded = applyEdgeFades(trimmed, sampleRate, options.fadeMs);
+    const silence = makeInterSentenceSilence(sampleRate, options.prependSilenceMs ?? 0);
+    const payload = Buffer.concat([silence, faded]);
+    const header = Buffer.from(source.subarray(0, dataOffset));
+    if (dataOffset >= 8)
+        header.writeUInt32LE(payload.length, dataOffset - 4);
+    if (header.length >= 8)
+        header.writeUInt32LE(header.length + payload.length - 8, 4);
+    return Buffer.concat([header, payload]);
+}
+/**
+ * Progressive counterpart of `conditionPcm16Wav`. It releases the spoken body
+ * as chunks arrive while retaining only the leading silence and a small tail
+ * needed for trimming/fade-out.
+ */
+export class Pcm16WavStreamEdges {
+    mode = 'probing';
+    prefix = Buffer.alloc(0);
+    leading = Buffer.alloc(0);
+    tail = Buffer.alloc(0);
+    sampleRate = 0;
+    started = false;
+    outputAudio = false;
+    thresholdDbfs;
+    fadeMs;
+    prependSilenceMs;
+    constructor(options = {}) {
+        this.thresholdDbfs = options.thresholdDbfs ?? -50;
+        this.fadeMs = options.fadeMs ?? 5;
+        this.prependSilenceMs = options.prependSilenceMs ?? 0;
+    }
+    push(chunk) {
+        const input = Buffer.from(chunk);
+        if (input.length === 0)
+            return [];
+        if (this.mode === 'passthrough')
+            return [input];
+        if (this.mode === 'pcm')
+            return this.processPayload(input);
+        this.prefix = Buffer.concat([this.prefix, input]);
+        const probe = probePcm16Wav(this.prefix);
+        if (probe.status === 'incomplete' && this.prefix.length <= 1024 * 1024)
+            return [];
+        if (probe.status !== 'ready') {
+            this.mode = 'passthrough';
+            const output = this.prefix;
+            this.prefix = Buffer.alloc(0);
+            return [output];
+        }
+        this.mode = 'pcm';
+        this.sampleRate = probe.layout.sampleRate;
+        const header = Buffer.from(this.prefix.subarray(0, probe.layout.dataOffset));
+        // Streaming bodies may be trimmed or prefixed, so advertise an open-ended
+        // data chunk and let EOF terminate playback.
+        header.writeUInt32LE(0xffff_ffff, probe.layout.dataOffset - 4);
+        header.writeUInt32LE(0xffff_ffff, 4);
+        const payload = this.prefix.subarray(probe.layout.dataOffset);
+        this.prefix = Buffer.alloc(0);
+        const silence = makeInterSentenceSilence(this.sampleRate, this.prependSilenceMs);
+        return [header, silence, ...this.processPayload(payload)].filter((part) => part.length > 0);
+    }
+    flush() {
+        if (this.mode === 'probing') {
+            const output = this.prefix;
+            this.prefix = Buffer.alloc(0);
+            this.mode = 'passthrough';
+            return output.length > 0 ? [output] : [];
+        }
+        if (this.mode !== 'pcm' || !this.started)
+            return [];
+        const trimmedTail = trimSilence(this.tail, this.sampleRate, this.thresholdDbfs);
+        this.tail = Buffer.alloc(0);
+        if (trimmedTail.length === 0)
+            return [];
+        const fadedTail = this.fadeOut(trimmedTail);
+        this.outputAudio = true;
+        return [fadedTail];
+    }
+    hasOutputAudio() {
+        return this.outputAudio;
+    }
+    processPayload(input) {
+        let payload = paired(input);
+        if (payload.length === 0)
+            return [];
+        if (!this.started) {
+            this.leading = Buffer.concat([this.leading, payload]);
+            const first = this.firstLoudSample(this.leading);
+            if (first < 0)
+                return [];
+            const margin = Math.round(this.sampleRate * EDGE_MARGIN_MS / 1_000);
+            payload = Buffer.from(this.leading.subarray(Math.max(0, first - margin) * 2));
+            this.leading = Buffer.alloc(0);
+            this.started = true;
+            payload = this.fadeIn(payload);
+        }
+        return this.bufferTail(payload);
+    }
+    bufferTail(payload) {
+        const combined = Buffer.concat([this.tail, payload]);
+        const last = this.lastLoudSample(combined);
+        if (last < 0) {
+            this.tail = combined;
+            return [];
+        }
+        const fadeSamples = Math.max(1, Math.round(this.sampleRate * this.fadeMs / 1_000));
+        const emitSamples = Math.max(0, last - fadeSamples);
+        const output = Buffer.from(combined.subarray(0, emitSamples * 2));
+        this.tail = Buffer.from(combined.subarray(emitSamples * 2));
+        if (output.length === 0)
+            return [];
+        this.outputAudio = true;
+        return [output];
+    }
+    firstLoudSample(buffer) {
+        const threshold = thresholdAmplitude(this.thresholdDbfs);
+        for (let index = 0; index < buffer.length / 2; index++) {
+            if (Math.abs(buffer.readInt16LE(index * 2)) >= threshold)
+                return index;
+        }
+        return -1;
+    }
+    lastLoudSample(buffer) {
+        const threshold = thresholdAmplitude(this.thresholdDbfs);
+        for (let index = buffer.length / 2 - 1; index >= 0; index--) {
+            if (Math.abs(buffer.readInt16LE(index * 2)) >= threshold)
+                return index;
+        }
+        return -1;
+    }
+    fadeIn(buffer) {
+        const output = Buffer.from(buffer);
+        const samples = Math.min(output.length / 2, Math.max(0, Math.round(this.sampleRate * this.fadeMs / 1_000)));
+        for (let index = 0; index < samples; index++) {
+            output.writeInt16LE(Math.round(output.readInt16LE(index * 2) * index / samples), index * 2);
+        }
+        return output;
+    }
+    fadeOut(buffer) {
+        const output = Buffer.from(buffer);
+        const sampleCount = output.length / 2;
+        const samples = Math.min(sampleCount, Math.max(0, Math.round(this.sampleRate * this.fadeMs / 1_000)));
+        for (let index = 0; index < samples; index++) {
+            const sampleIndex = sampleCount - 1 - index;
+            output.writeInt16LE(Math.round(output.readInt16LE(sampleIndex * 2) * index / samples), sampleIndex * 2);
+        }
+        return output;
+    }
+}
+//# sourceMappingURL=pcm-edges.js.map

package/dist/voice/perceived-latency-benchmark.d.ts

@@ -0,0 +1,56 @@
+import { type VoiceReplyTiming } from '../sensory/voice-loop.js';
+export type PerceivedLatencyEngine = 'voicebox' | 'pocket';
+export declare const DEFAULT_PERCEIVED_VOICE_QUERY = "Lisa, quelles sont les actualit\u00E9s importantes aujourd'hui ?";
+export interface PerceivedLatencyAttempt {
+    run: number;
+    success: boolean;
+    mode: VoiceReplyTiming['mode'];
+    firstTextMs?: number;
+    firstSegmentMs?: number;
+    firstByteMs?: number;
+    firstAudioMs?: number;
+    totalMs: number;
+    streamRequests: number;
+    audioChunks: number;
+    audioBytes: number;
+    spokenSegments: number;
+    error?: string;
+}
+export interface PerceivedLatencyResult {
+    engine: PerceivedLatencyEngine;
+    attempts: PerceivedLatencyAttempt[];
+    successes: number;
+    averageFirstAudioMs?: number;
+    bestFirstAudioMs?: number;
+    averageTotalMs?: number;
+}
+export interface PerceivedVoiceLatencyReport {
+    generatedAt: string;
+    query: string;
+    cacheHit: boolean;
+    cacheFreshness?: 'fresh' | 'stale';
+    cacheAgeMs?: number;
+    answerChars: number;
+    sentenceCap: number;
+    runs: number;
+    results: PerceivedLatencyResult[];
+}
+export type BenchmarkAudioOpener = (text: string, env: NodeJS.ProcessEnv, options: {
+    signal?: AbortSignal;
+}) => Promise<ReadableStream<Uint8Array> | null>;
+export interface PerceivedVoiceLatencyOptions {
+    runs?: number;
+    engines?: PerceivedLatencyEngine[];
+    /** Text characters per progressive TTS segment (32–240). */
+    sentenceCap?: number;
+    /** Deterministic test/diagnostic override. undefined loads the real prefetch cache. */
+    prefetchAnswer?: string | null;
+    pocketOpener?: BenchmarkAudioOpener;
+    voiceboxOpener?: BenchmarkAudioOpener;
+}
+/**
+ * Measure the real cached-answer voice path sequentially for each renderer.
+ * Sequential runs avoid GPU/CPU contention and make cold-vs-warm attempts easy
+ * to interpret. This function never opens an audio device and never publishes.
+ */
+export declare function runPerceivedVoiceLatencyBenchmark(env?: NodeJS.ProcessEnv, query?: string, options?: PerceivedVoiceLatencyOptions): Promise<PerceivedVoiceLatencyReport>;

package/dist/voice/perceived-latency-benchmark.js

@@ -0,0 +1,218 @@
+/**
+ * End-to-end perceived voice latency benchmark.
+ *
+ * Unlike the whole-WAV renderer benchmark, this exercises the same instant
+ * prefetch → hybrid stream → sentence assembler → progressive TTS boundary as
+ * Lisa's resident voice loop. Audio is consumed into a null sink: no speakers,
+ * Telegram message, or avatar event is produced, but first byte / first PCM and
+ * full generation are measured from the real HTTP response.
+ */
+import { defaultPrefetchCachePath, loadPrefetchCache, matchPrefetchedDetailed, } from '../companion/prefetch-engine.js';
+import { defaultPrefetchItemsPath, loadPrefetchItems, } from '../companion/prefetch-config.js';
+import { makeHybridReply } from '../sensory/hybrid-reply.js';
+import { DEFAULT_SENTENCE_CAP } from '../sensory/voice-stream.js';
+import { makeVoiceReply, } from '../sensory/voice-loop.js';
+import { openPocketAudioStream } from './local-tts.js';
+import { openVoiceboxAudioStream } from './voicebox-tts.js';
+export const DEFAULT_PERCEIVED_VOICE_QUERY = "Lisa, quelles sont les actualités importantes aujourd'hui ?";
+const MAX_BENCHMARK_AUDIO_BYTES = 128 * 1024 * 1024;
+function roundAverage(values) {
+    if (values.length === 0)
+        return undefined;
+    return Math.round(values.reduce((sum, value) => sum + value, 0) / values.length);
+}
+function summarize(engine, attempts) {
+    const successful = attempts.filter((attempt) => attempt.success);
+    const firstAudio = successful.flatMap((attempt) => attempt.firstAudioMs === undefined ? [] : [attempt.firstAudioMs]);
+    const averageFirstAudioMs = roundAverage(firstAudio);
+    const averageTotalMs = roundAverage(successful.map((attempt) => attempt.totalMs));
+    return {
+        engine,
+        attempts,
+        successes: successful.length,
+        ...(averageFirstAudioMs === undefined ? {} : { averageFirstAudioMs }),
+        ...(firstAudio.length === 0 ? {} : { bestFirstAudioMs: Math.min(...firstAudio) }),
+        ...(averageTotalMs === undefined ? {} : { averageTotalMs }),
+    };
+}
+function cachedAnswerFor(env, query, override, hasOverride) {
+    if (hasOverride)
+        return { answer: override?.trim() || null };
+    const items = loadPrefetchItems(defaultPrefetchItemsPath(env));
+    const cache = loadPrefetchCache(defaultPrefetchCachePath(env));
+    const match = matchPrefetchedDetailed(query, {
+        items,
+        cache,
+        now: Date.now(),
+        allowStale: true,
+    });
+    if (!match)
+        return { answer: null };
+    return {
+        answer: match.answer,
+        freshness: match.freshness,
+        ageMs: match.ageMs,
+    };
+}
+function streamSpeakIntoNull(opener, env, startedAt, metrics) {
+    return async (text, options = {}) => {
+        metrics.streamRequests += 1;
+        let reader;
+        let requestBytes = 0;
+        let firstPcm = false;
+        try {
+            const stream = await opener(text, env, { signal: options.signal });
+            if (!stream || options.signal?.aborted)
+                return false;
+            reader = stream.getReader();
+            while (!options.signal?.aborted) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (metrics.firstByteMs === undefined) {
+                    metrics.firstByteMs = Math.max(0, Date.now() - startedAt);
+                }
+                metrics.audioChunks += 1;
+                metrics.audioBytes += value.byteLength;
+                requestBytes += value.byteLength;
+                if (metrics.audioBytes > MAX_BENCHMARK_AUDIO_BYTES) {
+                    metrics.error = 'audio-size-limit';
+                    await reader.cancel('benchmark audio size limit');
+                    return false;
+                }
+                options.onAudioChunk?.(value);
+                // A canonical WAV header occupies 44 bytes. Voicebox may deliver the
+                // whole file in one chunk; Pocket normally crosses this threshold while
+                // the HTTP body is still being generated.
+                if (!firstPcm && requestBytes > 44) {
+                    firstPcm = true;
+                    options.onFirstAudio?.();
+                }
+            }
+            return firstPcm && !options.signal?.aborted;
+        }
+        catch (error) {
+            if (!options.signal?.aborted) {
+                metrics.error = error instanceof Error ? error.message : String(error);
+            }
+            return false;
+        }
+        finally {
+            if (reader) {
+                try {
+                    await reader.cancel();
+                }
+                catch {
+                    /* already consumed/cancelled */
+                }
+                reader.releaseLock();
+            }
+        }
+    };
+}
+/**
+ * Measure the real cached-answer voice path sequentially for each renderer.
+ * Sequential runs avoid GPU/CPU contention and make cold-vs-warm attempts easy
+ * to interpret. This function never opens an audio device and never publishes.
+ */
+export async function runPerceivedVoiceLatencyBenchmark(env = process.env, query = DEFAULT_PERCEIVED_VOICE_QUERY, options = {}) {
+    const cleanQuery = query.trim().slice(0, 1_000) || DEFAULT_PERCEIVED_VOICE_QUERY;
+    const runs = Math.max(1, Math.min(5, Math.round(options.runs ?? 2)));
+    const configuredCap = Number(options.sentenceCap ?? env.CODEBUDDY_VOICE_SENTENCE_CAP);
+    const sentenceCap = Number.isFinite(configuredCap)
+        ? Math.max(32, Math.min(240, Math.floor(configuredCap)))
+        : DEFAULT_SENTENCE_CAP;
+    const engines = [...new Set(options.engines ?? ['voicebox', 'pocket'])]
+        .filter((engine) => engine === 'voicebox' || engine === 'pocket');
+    const selectedEngines = engines.length > 0 ? engines : ['pocket'];
+    const cache = cachedAnswerFor(env, cleanQuery, options.prefetchAnswer, Object.prototype.hasOwnProperty.call(options, 'prefetchAnswer'));
+    const answer = cache.answer;
+    const results = [];
+    for (const engine of selectedEngines) {
+        const attempts = [];
+        for (let run = 1; run <= runs; run += 1) {
+            if (!answer) {
+                attempts.push({
+                    run,
+                    success: false,
+                    mode: 'silent',
+                    totalMs: 0,
+                    streamRequests: 0,
+                    audioChunks: 0,
+                    audioBytes: 0,
+                    spokenSegments: 0,
+                    error: 'prefetch-cache-miss',
+                });
+                continue;
+            }
+            const startedAt = Date.now();
+            const metrics = { streamRequests: 0, audioChunks: 0, audioBytes: 0 };
+            const opener = engine === 'voicebox'
+                ? options.voiceboxOpener ?? ((text, activeEnv, requestOptions) => openVoiceboxAudioStream(text, activeEnv, requestOptions))
+                : options.pocketOpener ?? ((text, activeEnv, requestOptions) => openPocketAudioStream(text, activeEnv, requestOptions));
+            let timing;
+            const hybrid = makeHybridReply({
+                fastReply: () => null,
+                prefetch: () => answer,
+                jokes: () => null,
+                classify: () => false,
+                chitchat: async () => '',
+                // eslint-disable-next-line require-yield -- the prefetch route must make this unreachable
+                chitchatStream: async function* () {
+                    // The prefetch route must make this unreachable.
+                },
+                agentReply: async () => '',
+            });
+            const voiceReply = makeVoiceReply({
+                replyFn: hybrid,
+                streamSpeak: streamSpeakIntoNull(opener, env, startedAt, metrics),
+                // Empty deterministic fallbacks ensure the benchmark reports a failed
+                // progressive renderer rather than writing or playing temporary audio.
+                synth: async () => '',
+                play: async () => undefined,
+                sentenceCap,
+                avatarEnabled: false,
+                onTiming: (value) => {
+                    timing = value;
+                },
+            });
+            try {
+                await voiceReply(cleanQuery);
+            }
+            catch (error) {
+                metrics.error = error instanceof Error ? error.message : String(error);
+            }
+            const measured = timing ?? voiceReply.lastTiming;
+            attempts.push({
+                run,
+                success: measured?.spoke === true && measured.firstAudioMs !== undefined,
+                mode: measured?.mode ?? 'failed',
+                ...(measured?.firstTextMs === undefined ? {} : { firstTextMs: measured.firstTextMs }),
+                ...(measured?.firstSegmentMs === undefined
+                    ? {}
+                    : { firstSegmentMs: measured.firstSegmentMs }),
+                ...(metrics.firstByteMs === undefined ? {} : { firstByteMs: metrics.firstByteMs }),
+                ...(measured?.firstAudioMs === undefined ? {} : { firstAudioMs: measured.firstAudioMs }),
+                totalMs: measured?.totalMs ?? Math.max(0, Date.now() - startedAt),
+                streamRequests: metrics.streamRequests,
+                audioChunks: metrics.audioChunks,
+                audioBytes: metrics.audioBytes,
+                spokenSegments: measured?.spoke ? metrics.streamRequests : 0,
+                ...(metrics.error ? { error: metrics.error } : {}),
+            });
+        }
+        results.push(summarize(engine, attempts));
+    }
+    return {
+        generatedAt: new Date().toISOString(),
+        query: cleanQuery,
+        cacheHit: Boolean(answer),
+        ...(cache.freshness ? { cacheFreshness: cache.freshness } : {}),
+        ...(cache.ageMs === undefined ? {} : { cacheAgeMs: cache.ageMs }),
+        answerChars: answer?.length ?? 0,
+        sentenceCap,
+        runs,
+        results,
+    };
+}
+//# sourceMappingURL=perceived-latency-benchmark.js.map

package/dist/voice/tts-bank.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Precomputed fixed-phrase bank for the resident voice.
+ *
+ * The project contributes `.codebuddy/tts-bank.txt`; the default corpus also
+ * includes existing arrival openers and conversational cues. Dynamic phrases
+ * are rejected before synthesis so stale dates, times, names or counters can
+ * never be frozen into a reusable audio asset.
+ */
+export type TtsBankProvider = 'local' | 'elevenlabs';
+export interface RejectedTtsBankPhrase {
+    text: string;
+    reason: string;
+    source: 'project' | 'builtin';
+}
+export interface TtsBankCorpus {
+    phrases: string[];
+    rejected: RejectedTtsBankPhrase[];
+}
+interface TtsBankCache {
+    has(text: string, voice?: string): boolean;
+    store(text: string, voice: string | undefined, srcWav: string): void;
+}
+export interface TtsBankOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    provider?: TtsBankProvider;
+    cache?: TtsBankCache;
+    /** Test/embedder seam; omitted means the real existing corpus. */
+    builtinPhrases?: string[];
+}
+export interface TtsBankBuildOptions extends TtsBankOptions {
+    synthesize?: (text: string, wavPath: string, provider: TtsBankProvider) => Promise<boolean>;
+}
+export interface TtsBankBuildResult {
+    provider: TtsBankProvider;
+    expected: number;
+    attempted: number;
+    built: number;
+    present: number;
+    failed: number;
+    rejected: RejectedTtsBankPhrase[];
+}
+export interface TtsBankListEntry {
+    text: string;
+    present: boolean;
+}
+export interface TtsBankListResult {
+    provider: TtsBankProvider;
+    voice: string;
+    entries: TtsBankListEntry[];
+    rejected: RejectedTtsBankPhrase[];
+}
+export interface TtsBankVerifyResult {
+    provider: TtsBankProvider;
+    expected: number;
+    present: number;
+    missing: string[];
+    rejected: RejectedTtsBankPhrase[];
+}
+export declare function validateFixedTtsBankPhrase(input: string): {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+export declare function getBuiltinTtsBankPhrases(env?: NodeJS.ProcessEnv): string[];
+export declare function loadTtsBankCorpus(options?: TtsBankOptions): TtsBankCorpus;
+export declare function resolveTtsBankVoice(provider: TtsBankProvider, env?: NodeJS.ProcessEnv): string;
+export declare function listTtsBank(options?: TtsBankOptions): TtsBankListResult;
+export declare function verifyTtsBank(options?: TtsBankOptions): TtsBankVerifyResult;
+export declare function buildTtsBank(options?: TtsBankBuildOptions): Promise<TtsBankBuildResult>;
+export {};