@phuetz/code-buddy 1.6.1 → 2.1.0

package/dist/sensory/voice-loop.d.ts

@@ -0,0 +1,635 @@
+/**
+ * Voice loop — closes the perception→cognition→action loop into speech. Given a
+ * transcript of what the robot HEARD (the `onHeard` hook of `speech-reaction.ts`),
+ * THINK a short reply with a LOCAL LLM ($0, Ollama) and SPEAK it with a real neural
+ * voice (Pocket by default, optional budget-guarded ElevenLabs, Piper fallback).
+ * The result is a thing you can talk to:
+ * hear → think → speak.
+ *
+ * Everything is INJECTABLE (reply / synth / play) so the loop is deterministically
+ * testable with no model, no audio device. Opt-in (`CODEBUDDY_SENSORY_SPEAK=true`,
+ * gated by the caller), NEVER-THROWS (a failure is silence, not a crash).
+ *
+ * The default `replyFn` is a lightweight companion reply. To make the robot *act* on
+ * spoken commands (run tools, code), inject a `replyFn` that drives a full agent turn —
+ * the loop itself is unchanged.
+ *
+ * @module sensory/voice-loop
+ */
+import { type AvatarEvent } from '../avatar/avatar-protocol.js';
+import type { ConversationTurn } from '../conversation/types.js';
+import { type LocalTtsEngine } from '../voice/local-tts.js';
+import { type TwoSpeedTtsRouteHint } from '../voice/two-speed-voice.js';
+export type { TwoSpeedTtsRouteHint } from '../voice/two-speed-voice.js';
+import type { PermissionMode } from '../security/permission-modes.js';
+import { type ResponseDecider } from './respond-decider.js';
+import { type VoiceDeliveryProfile, type VoiceTurnContext } from './voice-entrainment.js';
+import { type VisualGroundingFn } from '../companion/visual-grounding.js';
+import type { CameraShareOptions, CameraShareResult } from '../companion/camera-share.js';
+import type { ConversationCueRequest } from './conversation-cues.js';
+/** Derive relational prosody without changing the bare voice-loop default. */
+export declare function deriveSpokenDeliveryProfile(heard: string, context?: VoiceTurnContext, env?: NodeJS.ProcessEnv): VoiceDeliveryProfile;
+/**
+ * Cancellation handle threaded into the two interruptible steps of a spoken turn: the
+ * LLM/agent "think" (`ReplyFn`) and the TTS "play" (`PlayFn`). When the signal aborts
+ * (barge-in / programmatic `interrupt()`), the think step's HTTP request is aborted and
+ * the play step kills its audio child. Optional + additive — a step that ignores it keeps
+ * its previous (non-interruptible) behavior.
+ */
+export interface VoiceStepOptions {
+    /** Abort the in-flight step (barge-in / cancellation). */
+    signal?: AbortSignal;
+    /** Frozen gain measured from the first audio segment of this spoken turn. */
+    ttsNormalizationFactor?: number;
+    /** Per-segment reason that forces the opt-in two-speed policy onto Kyutai. */
+    ttsRouteHint?: TwoSpeedTtsRouteHint;
+    /** Insert the pipeline-owned fixed gap before a non-first sentence. */
+    prependInterSentenceSilence?: boolean;
+    /** The producer already applied the shared loudness law to this WAV. */
+    alreadyNormalized?: boolean;
+    /** Exact current utterance when the grounded agent input also carries history. */
+    introspectionText?: string;
+    /** Internal routing receipt used to keep post-processing on the exact provider. */
+    onProviderResolved?: (route: {
+        model: string;
+        apiKey: string;
+        baseURL?: string;
+    }) => void;
+    /** Raw-free cadence/length profile derived from the human's current spoken turn. */
+    delivery?: VoiceDeliveryProfile;
+    /** Internal handoff: an outer reply router already applied relational drift for this turn. */
+    relationshipEvolutionHandled?: boolean;
+    /** The previous spoken answer was cut; use it to continue without repeating it. */
+    interruption?: VoiceInterruptionContext;
+    /**
+     * Route-aware, transactional cognitive context. The caller is responsible
+     * for enforcing the route's real egress clearance before returning a lease.
+     */
+    acquireCognitiveContext?: (route: {
+        model: string;
+        apiKey: string;
+        baseURL?: string;
+    }, heard: string) => VoiceCognitiveContextLease | null;
+    /** Gives the semantic reviewer the same evidence block used by the answering model. */
+    onCognitiveContextResolved?: (context: {
+        turnContext: string;
+        evidence: string;
+    }) => void;
+    /**
+     * Complete opening sentence already accepted for speech. Continuation generators must
+     * advance the answer without repeating this text.
+     */
+    spokenPrefix?: string;
+    /** Raw-free internal phase telemetry for the end-to-end spoken-turn clock. */
+    onReplyTimingPhase?: (phase: VoiceReplyTimingPhase) => void;
+    /** Raw-free pilot telemetry. Never carries the transcript or generated candidate. */
+    onSpokenPrefixTelemetry?: (cause: SpokenPrefixTelemetryCause) => void;
+    /** Register a non-blocking semantic correction for playback after the initial answer. */
+    onSemanticCorrection?: (correction: Promise<string>) => void;
+    /** Opt-in contract owned by the fast chitchat route. */
+    shortFirst?: VoiceShortFirstConfig;
+    /** Tell the outer audio pipeline that the fast route accepted the short-first contract. */
+    onShortFirstReady?: (config: VoiceShortFirstConfig) => void;
+    /** Decision from respond-decider if already evaluated */
+    respondDecision?: {
+        respond: boolean;
+        reason: string;
+    };
+    /** Injected response decider for conversational continuity */
+    responseDecider?: ResponseDecider;
+    /** Explicit override for whether the robot was named or in engagement window */
+    robotNamed?: boolean;
+}
+export interface VoiceShortFirstConfig {
+    /** Total number of spoken answer sentences, including the first useful sentence. */
+    maxSentences: number;
+}
+export type VoiceReplyTimingPhase = 'prompt_ready' | 'provider_first_delta' | 'generation_complete' | 'semantic_review_complete' | 'prefix_prompt_ready' | 'prefix_provider_first_delta' | 'prefix_generation_complete' | 'prefix_semantic_review_complete' | 'continuation_prompt_ready' | 'continuation_provider_first_delta' | 'continuation_generation_complete' | 'continuation_semantic_review_complete';
+export type SpokenPrefixTelemetryCause = 'ineligible' | 'empty' | 'too_long' | 'missing_terminal' | 'multi_sentence' | 'relationship_intervened' | 'review_rejected' | 'review_unavailable' | 'post_review_invalid' | 'accepted' | 'final_guard_invalid';
+export interface VoiceCognitiveContextLease {
+    turnContext: string;
+    evidence?: string;
+    commit(): void;
+    release(): void;
+}
+export interface VoiceInterruptionContext {
+    interruptedTurnId: string;
+    /** One-based phrase number active when Lisa was cut. */
+    phraseNumber: number;
+    /** Only the phrases that fully reached the player; bounded and ephemeral. */
+    spokenText: string;
+}
+/** Think: turn what was heard into a short spoken reply ('' → stay silent). */
+export type ReplyFn = (heard: string, opts?: VoiceStepOptions) => Promise<string>;
+/**
+ * Streaming think: yield the reply as token deltas so the voice can be PIPELINED (spoken
+ * sentence-by-sentence as the LLM streams). Yielding nothing signals "not applicable" (a
+ * phatic reply, an unreachable model) — the caller then falls back to the blocking `ReplyFn`.
+ */
+export type StreamReplyFn = (heard: string, opts?: VoiceStepOptions) => AsyncIterable<string>;
+/** Produce one independently useful, semantically reviewed opening sentence. */
+export type SpokenPrefixFn = (heard: string, opts?: VoiceStepOptions) => Promise<string>;
+/** Synthesize: turn reply text into a playable WAV file, return its path. */
+export type SynthFn = (text: string, opts?: VoiceStepOptions) => Promise<string>;
+/** Speak: play a WAV file to the speakers (blocking until done). */
+export type PlayFn = (wav: string, opts?: VoiceStepOptions) => Promise<void>;
+/** Options for Pocket's native chunked WAV → player path. */
+export interface StreamSpeakOptions extends VoiceStepOptions {
+    /** Fired when the first PCM-bearing chunk has been accepted by the player. */
+    onFirstAudio?: () => void;
+    /** Optional live copy of normalized WAV bytes for a remote avatar renderer. */
+    onAudioChunk?: (chunk: Uint8Array) => void;
+    /** Cumulative PCM accepted by the local player, excluding the WAV header. */
+    onAudioProgress?: (progress: {
+        pcmBytes: number;
+        byteRate: number;
+    }) => void;
+    /** Publishes the first measured gain so WAV fallback can preserve the turn level. */
+    onTtsNormalizationFactor?: (factor: number) => void;
+}
+/** Synthesize and play one text segment progressively; false requests the WAV fallback. */
+export type StreamSpeakFn = ((text: string, opts?: StreamSpeakOptions) => Promise<boolean>) & {
+    /**
+     * Optional look-ahead: open the network/billed stream of the NEXT segment while the
+     * current one is still playing, so the gap between two sentences is the 280 ms breath
+     * and not a full TTS round trip (measured at 1.3–1.4 s per sentence on 2026-09-02, the
+     * "voix hachée"). Only engines that accept concurrent requests expose it (ElevenLabs);
+     * Pocket is single-request and never does. Never throws; a stale prefetch is cancelled.
+     */
+    prefetch?: (text: string, opts?: {
+        signal?: AbortSignal;
+    }) => void;
+};
+export interface VoiceReplyTiming {
+    mode: 'streamed' | 'blocking' | 'silent' | 'interrupted' | 'failed';
+    /** One-based phrase number that was active when barge-in interrupted playback. */
+    interruptedAtSentence?: number;
+    /** Delay until routing, persona and prompt augmentation are ready for the provider. */
+    promptReadyMs?: number;
+    /** True provider TTFT, measured before any semantic buffering or safety release. */
+    providerFirstDeltaMs?: number;
+    /** Delay until the answering provider has completed its draft generation. */
+    generationCompleteMs?: number;
+    /** Delay until a required semantic audit/revision has completed. */
+    semanticReviewCompleteMs?: number;
+    /** Raw-free metrics for the opt-in spoken-prefix pilot. */
+    spokenPrefix?: {
+        outcome: SpokenPrefixTelemetryCause;
+        causes: SpokenPrefixTelemetryCause[];
+        promptReadyMs?: number;
+        providerFirstDeltaMs?: number;
+        generationCompleteMs?: number;
+        semanticReviewCompleteMs?: number;
+    };
+    /** Provider/review phases of the answer that follows an accepted prefix. */
+    continuation?: {
+        promptReadyMs?: number;
+        providerFirstDeltaMs?: number;
+        generationCompleteMs?: number;
+        semanticReviewCompleteMs?: number;
+    };
+    /** Delay until the relationship gate first releases model/shortcut content. */
+    firstSafeReleaseMs?: number;
+    /** Delay until the reply stream yields its first text (including an instant backchannel). */
+    firstTextMs?: number;
+    /** Delay until a complete safe text segment is ready for TTS. */
+    firstSegmentMs?: number;
+    /** Delay from reply-handler entry until playback of the first sentence/clip begins. */
+    firstAudioMs?: number;
+    /** Primary perceived-response SLA: delay until non-backchannel answer audio begins. */
+    firstContentAudioMs?: number;
+    /** Number of streamed segments recovered through WAV synthesis after native TTS failed. */
+    streamFallbackSegments?: number;
+    /** Full handler duration, including playback. */
+    totalMs: number;
+    spoke: boolean;
+    /** Blocking-path stage details (streamed synthesis/playback overlap by design). */
+    replyMs?: number;
+    synthMs?: number;
+    playMs?: number;
+    /** Raw-free delivery profile applied to cognition and supported TTS renderers. */
+    delivery?: VoiceDeliveryProfile;
+}
+export interface VoiceReplyOptions {
+    /** Injectable "think" step. Default: a short companion reply from a local LLM ($0). */
+    replyFn?: ReplyFn;
+    /**
+     * Injectable STREAMING "think" step (token deltas) — enables the pipeline that speaks from
+     * the first sentence. When present and it yields content, the reply is spoken
+     * sentence-by-sentence; otherwise the blocking `replyFn` is used. Default: the LLM stream
+     * (`defaultStreamReply`) UNLESS a blocking `replyFn` was injected (then the caller's
+     * blocking contract is honored and no default stream is used).
+     */
+    streamFn?: StreamReplyFn;
+    /** Later-segment safety cap for punctuation-less text (streaming). Default 160. */
+    sentenceCap?: number;
+    /** Injectable "synthesize" step. Default: resident Pocket TTS, Piper fallback. */
+    synth?: SynthFn;
+    /** Injectable "speak" step. Default: one aplay / ffplay backend per turn. */
+    play?: PlayFn;
+    /**
+     * Injectable progressive synth+play path. This is also the diagnostic seam
+     * used to measure first PCM without opening a real audio device.
+     */
+    streamSpeak?: StreamSpeakFn;
+    /** Optional Piper fallback model (.onnx); Pocket uses CODEBUDDY_POCKET_VOICE. */
+    voice?: string;
+    /** Where synth WAVs are written (cleaned up after playback). Default: cwd. */
+    rootDir?: string;
+    /** Test hook: called with the reply text right after it is spoken. */
+    onSpoke?: (text: string) => void;
+    /** Shared-thread hook for mirroring voice turns to Telegram/another configured channel. */
+    onConversationTurn?: (turn: ConversationTurn) => void | Promise<void>;
+    /** Correlated local cognitive copy; kept separate so channel adapters retain their stable shape. */
+    onCorrelatedConversationTurn?: (turn: ConversationTurn & {
+        turnId: string;
+    }) => void | Promise<void>;
+    /** Performance hook consumed by Unreal/MetaHuman or a test renderer. */
+    onAvatarEvent?: (event: AvatarEvent) => void;
+    /** Explicitly enable/disable avatar publication for this handler. Default: env/renderer hook. */
+    avatarEnabled?: boolean;
+    /** Observability hook fired once per turn, including silence/failure/interruption. */
+    onTiming?: (timing: VoiceReplyTiming) => void;
+    /** Environment snapshot used by readiness checks. Injectable for deterministic diagnostics. */
+    env?: NodeJS.ProcessEnv;
+    /** Route seam used only to diagnose an empty generated reply. */
+    resolveRoute?: (heard: string) => Promise<VoiceModelRoute>;
+    /**
+     * Explicit one-shot visual grounding. It runs before streaming, phatic
+     * shortcuts, and ACT routing, so camera questions work in every voice mode.
+     * Injectable for tests or an alternate local camera bridge.
+     */
+    visualGrounding?: VisualGroundingFn;
+    /**
+     * On-demand room/camera share (« qu'est-ce que tu vois ? »). Runs before
+     * object-level visual grounding so a bare look does not ask for confirmation.
+     * Injectable for tests with a fake camera / fake Telegram client.
+     */
+    cameraShare?: (heard: string, options?: CameraShareOptions) => Promise<CameraShareResult | null>;
+}
+export interface VoiceReadiness {
+    /** Text model the default replyFn will try, or 'auto' when latency-routed at call time. */
+    model: string;
+    /** True when the reply model is chosen by the latency router (no explicit override). */
+    routed: boolean;
+    /** Selected TTS engine. */
+    ttsEngine: LocalTtsEngine;
+    /** Selected Pocket voice, Voicebox profile, or Piper model path. */
+    voice?: string;
+    /** True when speech-out has a configured primary path. */
+    speakReady: boolean;
+    /** False when a resolved voice route fell back to the possibly-unpulled default model. */
+    modelReady: boolean;
+    /** Combined cognition + speech readiness signal. */
+    ready: boolean;
+    /** True when CODEBUDDY_SENSORY_SPEAK_ACT is on (spoken commands drive a real agent turn). */
+    act: boolean;
+    /** Voice ACT permission posture when act is on. Resident legacy `plan` migrates to `default`. */
+    permissionMode?: PermissionMode;
+    /** Actionable, loud-by-design warnings naming the env to set. */
+    warnings: string[];
+}
+/**
+ * Resident speech used to persist `plan` as its default, which made even safe
+ * repository inspection fail when the model chose `bash`. A plan posture still
+ * exists for an explicitly launched code/voice session (`buddy voice --mode
+ * plan`), but it is not inherited by the always-on conversational assistant.
+ */
+export declare function resolveResidentVoicePermissionMode(env?: NodeJS.ProcessEnv): PermissionMode;
+/** Pure prereq check (testable) — what the default `makeVoiceReply()` needs to actually
+ *  SPEAK. The robot still HEARS without these; it just stays silent. Used by the server to
+ *  fail LOUD (name the env) instead of being mutely wired. */
+export declare function describeVoiceReadiness(env?: NodeJS.ProcessEnv, route?: Pick<VoiceModelRoute, 'reason'>): VoiceReadiness;
+export declare const SPEAK_SYSTEM_PROMPT: string;
+export declare const DEFAULT_SENSORY_REPLY_MAX_SENTENCES = 3;
+/** The pilot is deliberately exact opt-in; every other value preserves the established route. */
+export declare function sensoryShortFirstEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** Bound the complete fast spoken answer. Invalid input falls back to the documented default. */
+export declare function sensoryReplyMaxSentences(env?: NodeJS.ProcessEnv): number;
+/** Model-facing contract for the fast route only. */
+export declare function buildShortFirstPrompt(config: VoiceShortFirstConfig): string;
+export declare const IMMEDIATE_THINKING_ACKNOWLEDGEMENTS: readonly ["Alors…", "Voyons ça."];
+export declare const MAX_SPOKEN_PREFIX_CHARS = 180;
+/** True only for a valid non-loopback HTTP(S) route. Invalid/unknown routes fail local. */
+export declare function isRemoteVoiceRoute(baseURL: string | undefined): boolean;
+/** Cloud text routes trade a small bounded startup buffer for continuous sentence playback. */
+export declare function voiceAudioPrebufferMs(env?: NodeJS.ProcessEnv): number;
+/** Real-time network stream jitter buffer duration before writing to audio player stdin. */
+export declare function resolveVoiceJitterBufferMs(env?: NodeJS.ProcessEnv): number;
+/** Explicit true/false wins; otherwise latency buffers follow the resolved route. */
+export declare function voiceLatencyBufferEnabled(configured: string | undefined, baseURL: string | undefined): boolean;
+/**
+ * Last-mile structural and relationship gate for a generated opening proposition. Invalid
+ * candidates fail closed; truncating one could silently change the claim being spoken.
+ */
+export declare function prepareSpokenPrefixCandidate(candidate: string, onCause?: (cause: SpokenPrefixTelemetryCause) => void): string;
+/** Resolve a pre-synthesized instant acknowledgement for the native Pocket
+ * streaming path. Streaming used to bypass the TTS cache entirely, making the
+ * same “Alors…” pay synthesis latency on every turn despite startup prewarm. */
+export declare function lookupInstantBackchannelWav(text: string, env?: NodeJS.ProcessEnv, lookup?: (text: string, voice: string) => string | null, cacheVoice?: string): Promise<string | null>;
+/**
+ * A tiny deterministic backchannel for non-emotional questions. It is yielded
+ * immediately after route selection and is prewarmed in the TTS cache, so the
+ * user gets an early conversational response while remote generation starts.
+ */
+export declare function immediateThinkingAcknowledgement(heard: string, env?: NodeJS.ProcessEnv, baseURL?: string): string | null;
+/** Static knowledge deserves a slightly larger local model than social chat. */
+export declare function isFactualVoiceQuestion(heard: string): boolean;
+/**
+ * How many tokens the spoken reply may use.
+ *
+ * `CODEBUDDY_VOICE_MAX_TOKENS` is the operator saying how long the robot should
+ * talk, so an explicit value is the CEILING. It used to be only a lower bound
+ * outside the 'concise' style: `Math.max(64, min(512, max(base, planned)))` turned
+ * a deliberate 48 into at least 64 and, on any real exchange, into the 512 cap.
+ *
+ * Measured on Patrice's robot, 2026-09-02: he had set 48 and heard replies with a
+ * 479-character median, delivered as a dozen phrases with a silence between each
+ * — the gaps are what a listener calls choppy. Every one of those turns took the
+ * chitchat route, so this function, not the agent summary, is the one he hears.
+ *
+ * Unset, both the style handling and the automatic budget behave exactly as before.
+ */
+declare function voiceMaxTokens(heard: string, history?: VoiceHistoryTurn[], env?: NodeJS.ProcessEnv): number;
+/** Exposed for tests: the spoken-length budget is a user-visible contract. */
+export declare const __testVoiceMaxTokens: typeof voiceMaxTokens;
+export declare function fastCompanionReply(heard: string): string | null;
+export declare const DEFAULT_TTS_PREWARM_PHRASES: string[];
+export declare function getDefaultVoicePrewarmPhrases(limit?: number): string[];
+export declare function prewarmVoiceReplyCache(options?: {
+    phrases?: string[];
+    limit?: number;
+    voice?: string;
+    rootDir?: string;
+    synth?: SynthFn;
+}): Promise<{
+    attempted: number;
+    cached: number;
+}>;
+/** A resolved text model for the spoken reply. */
+export interface VoiceModelRoute {
+    model: string;
+    apiKey: string;
+    baseURL: string;
+    /** Diagnostic — how this model was chosen (router rationale or 'pinned'/'fallback'). */
+    reason: string;
+}
+/** Test seam — clear the routing cache. */
+export declare function resetVoiceModelCache(): void;
+export interface VoiceModelResolverDeps {
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
+    /** Recent shared/local dialogue, oldest first, used to keep follow-up depth stable. */
+    history?: ConversationTurn[];
+    /** Summaries/utility calls stay on the fast lane even if their transcript looks factual. */
+    forceFastLane?: boolean;
+    /** Test seam: whether ChatGPT/Codex OAuth creds exist (default: checks ~/.codebuddy/codex-auth.json). */
+    hasCodexOAuth?: () => boolean;
+    selectFastestModel?: (heard: string, options: {
+        taskType: string;
+        localOnly: boolean;
+        env: NodeJS.ProcessEnv;
+    }) => Promise<{
+        model: string;
+        apiKey?: string;
+        baseURL?: string;
+        reason: string;
+    } | null>;
+    /** Test/embedding seam for the reviewed cross-surface companion route. */
+    resolveCompanionRoute?: (options: {
+        surface: 'voice';
+        text: string;
+        history: ConversationTurn[];
+        requireLocal: boolean;
+        env: NodeJS.ProcessEnv;
+    }) => Promise<VoiceModelRoute | null>;
+}
+/**
+ * When a pinned voice model is a ChatGPT/Codex subscription model (gpt-5.6-luna,
+ * o-series, codex-*), route it through the OAuth Codex backend so the spoken
+ * reply is served $0 via the subscription — instead of the local Ollama endpoint
+ * (which does not have it). Returns the OAuth apiKey/baseURL when creds exist,
+ * else null → the caller keeps the local route (offline / not logged in).
+ * Luna is the intended low-latency voice model: faster + smarter than local.
+ */
+export declare function codexOAuthVoiceRoute(model: string, hasOAuth?: () => boolean): {
+    apiKey: string;
+    baseURL: string;
+} | null;
+/**
+ * Resolve which LLM answers a spoken utterance. Fluidity is everything for a
+ * companion (a 16s reply breaks the spell), so by default we route to the
+ * LOWEST-LATENCY capable LLM via the shared selector — the same "which LLM is
+ * best for this task" system the council uses, but with a latency objective.
+ *
+ * `CODEBUDDY_SENSORY_SPEAK_MODEL` stays authoritative: set it (to anything but
+ * 'auto') to pin a model. `CODEBUDDY_SENSORY_SPEAK_LOCAL_ONLY=true` prefers the
+ * local runtime endpoints. The routed result is cached briefly (see
+ * `CODEBUDDY_SENSORY_SPEAK_ROUTE_TTL_MS`). Never-throws — on any miss we fall
+ * back to a reachable local default.
+ */
+export declare function resolveVoiceModel(heard: string, deps?: VoiceModelResolverDeps): Promise<VoiceModelRoute>;
+export interface VoiceModelPrewarmResult {
+    attempted: boolean;
+    warmed: boolean;
+    model: string;
+    durationMs: number;
+    reason?: string;
+}
+export interface VoiceRuntimePrewarmResult {
+    route: {
+        model: string;
+        baseURL: string;
+        reason: string;
+    };
+    routeMs: number;
+    model: VoiceModelPrewarmResult;
+    tts: {
+        attempted: number;
+        cached: number;
+        durationMs: number;
+    };
+}
+/**
+ * Load the selected Ollama voice model without generating text and extend its residency.
+ * Cloud/OpenAI-compatible routes are deliberately skipped: prewarming must never create a
+ * paid or user-visible generation.
+ */
+export declare function prewarmVoiceModel(options?: {
+    route?: VoiceModelRoute;
+    heard?: string;
+    env?: NodeJS.ProcessEnv;
+    fetchFn?: typeof fetch;
+    resolveRoute?: (heard: string) => Promise<VoiceModelRoute>;
+    now?: () => number;
+}): Promise<VoiceModelPrewarmResult>;
+/** Prewarm route selection, the local model, and the highest-frequency TTS phrases. */
+export declare function prewarmVoiceRuntime(options?: {
+    env?: NodeJS.ProcessEnv;
+    resolveRoute?: (heard: string) => Promise<VoiceModelRoute>;
+    warmModel?: (route: VoiceModelRoute) => Promise<VoiceModelPrewarmResult>;
+    warmTts?: (limit: number) => Promise<{
+        attempted: number;
+        cached: number;
+    }>;
+    now?: () => number;
+}): Promise<VoiceRuntimePrewarmResult>;
+/** One prior spoken exchange, oldest-first, fed back as conversational memory. */
+export interface VoiceHistoryTurn {
+    role: 'user' | 'assistant';
+    content: string;
+}
+export interface SpokenPromptAugmentationOptions {
+    /**
+     * A/B seam: true restores the legacy duplicate `<recent_dialogue>` block.
+     * Default false because voice already sends the bounded raw history.
+     */
+    includeRecentDialogue?: boolean;
+    /** Injectable environment for feature-gate tests. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Injectable latency-bounded relational snapshot. */
+    relationalContext?: () => Promise<string>;
+    /** Ephemeral context from the previous interrupted spoken turn. */
+    interruption?: VoiceInterruptionContext;
+}
+/** Only continuation/correction requests deserve an explicit interruption acknowledgement. */
+export declare function shouldAcknowledgeVoiceInterruption(heard: string): boolean;
+export declare function buildVoiceInterruptionGuidance(heard: string, interruption?: VoiceInterruptionContext): string;
+/** Explicit override, otherwise expressive text follows the existing relational opt-in. */
+export declare function isExpressiveVoiceTextEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** Deterministically replace a repeated opening before it reaches any synthesizer. */
+export declare function rewriteRepeatedVoiceOpener(text: string, recentOpeners?: readonly string[]): string;
+/**
+ * Build the per-turn prompt additions for a spoken reply.
+ *
+ * Emotion matching and opener variation are deliberately always-on: both are local,
+ * deterministic, and contain no personal memory. The richer facts/episode/personality
+ * block remains separately opt-in behind `CODEBUDDY_COMPANION_RELATIONAL`.
+ *
+ * Exported as a narrow test seam so the privacy boundary and default emotional behaviour
+ * can be proven without starting a model.
+ */
+export declare function buildSpokenPromptAugmentation(heard: string, history?: VoiceHistoryTurn[], spokenPrefix?: string, delivery?: VoiceDeliveryProfile, options?: SpokenPromptAugmentationOptions): Promise<string>;
+export declare function getVoiceResponseDecider(): ResponseDecider;
+export declare function setVoiceResponseDecider(decider: ResponseDecider | undefined): void;
+/**
+ * Determine if the utterance addresses the robot by name or takes place inside
+ * an active engagement window, consulting the respond-decider.
+ */
+export declare function resolveVoiceRobotNamed(heard: string, replyOpts?: VoiceStepOptions): Promise<boolean>;
+export declare function defaultReply(heard: string, history?: VoiceHistoryTurn[], replyOpts?: VoiceStepOptions): Promise<string>;
+/**
+ * Fast first proposition for an eligible developed/deliberative turn. Eligibility and
+ * semantic acceptance belong to the hybrid brain; this primitive only generates a candidate.
+ */
+export declare function defaultSpokenPrefix(heard: string, history?: VoiceHistoryTurn[], replyOpts?: VoiceStepOptions): Promise<string>;
+/**
+ * Default STREAMING think: the same short companion reply as `defaultReply`, but yielded as
+ * token deltas so the voice pipeline can speak from the first sentence. Phatic small talk is
+ * NOT streamed — it is answered by the instant canned reply on the blocking path, so this
+ * generator yields nothing for it (the caller falls back). Any failure (unreachable model,
+ * stream error) also yields nothing → graceful fallback to the blocking reply. Never-throws.
+ */
+export declare function defaultStreamReply(heard: string, replyOpts?: VoiceStepOptions): AsyncGenerator<string, void, unknown>;
+/**
+ * History-aware streaming companion reply used by the hybrid brain. Keeping this separate
+ * from the `StreamReplyFn` adapter above lets small talk stream while preserving the same
+ * recent exchanges as the blocking hybrid path.
+ */
+export declare function streamCompanionReply(heard: string, history?: VoiceHistoryTurn[], replyOpts?: VoiceStepOptions): AsyncGenerator<string, void, unknown>;
+/**
+ * Default synth for the assistant's voice. Active engine picked from
+ * Pocket TTS is the realtime default. Voicebox can render a more expressive
+ * voice locally or on GPU node; Pocket and Piper remain fail-open fallbacks.
+ */
+declare function resolveBaseCacheVoice(engine: LocalTtsEngine, voice?: string, env?: NodeJS.ProcessEnv): string;
+declare function makeDefaultSynth(voice?: string, rootDir?: string, engine?: LocalTtsEngine): SynthFn;
+interface VoiceAudioPlayer {
+    cmd: string;
+    stdinArgs: string[];
+    fileArgs: (file: string) => string[];
+}
+declare function resolveVoiceAudioPlayer(): Promise<VoiceAudioPlayer | null>;
+/**
+ * Pocket and Voicebox expose WAV response streams; ElevenLabs exposes a raw
+ * PCM `/stream` endpoint that `openElevenLabsAudioStream` wraps in a streaming
+ * WAV header. Pipe the selected one into a stdin-capable player so the first
+ * PCM frame is heard while the engine is still generating the rest, instead of
+ * calling `arrayBuffer()` and waiting for the complete clip. Any setup/runtime
+ * failure returns false and the caller uses the established temporary-WAV
+ * fallback (which itself falls back Pocket/Piper — never silence).
+ */
+declare function makeDefaultStreamSpeak(playerPromise?: Promise<VoiceAudioPlayer | null>, engine?: LocalTtsEngine): StreamSpeakFn | undefined;
+/** Resume on a lexical boundary after the PCM duration already accepted by the player. */
+declare function resumeTextAfterStreamFailure(text: string, progress: {
+    pcmBytes: number;
+    byteRate: number;
+} | undefined): string;
+/** Select one provider per segment while retaining the pre-DARK3 path verbatim when disabled. */
+declare function makeRoutedSynth(voice?: string, rootDir?: string, engine?: LocalTtsEngine, env?: NodeJS.ProcessEnv): SynthFn;
+/** Progressive Kyutai → ElevenLabs → Pocket chain without replaying accepted local PCM. */
+declare function makeRoutedStreamSpeak(playerPromise?: Promise<VoiceAudioPlayer | null>, engine?: LocalTtsEngine, env?: NodeJS.ProcessEnv): StreamSpeakFn | undefined;
+/** Default speak: play a WAV with the first available local player, blocking until done.
+ *  Interruptible: when `opts.signal` aborts (barge-in), the audio child is SIGKILLed and
+ *  the play resolves immediately so the ear can re-open. */
+declare function defaultPlay(wav: string, opts?: VoiceStepOptions, playerPromise?: Promise<VoiceAudioPlayer | null>): Promise<void>;
+/** Narrow test seam for verifying the shared per-turn player contract. */
+export declare const __voiceAudioPlayerTest: {
+    resolveVoiceAudioPlayer: typeof resolveVoiceAudioPlayer;
+    resolveVoiceJitterBufferMs: typeof resolveVoiceJitterBufferMs;
+    resolveBaseCacheVoice: typeof resolveBaseCacheVoice;
+    makeDefaultSynth: typeof makeDefaultSynth;
+    makeDefaultStreamSpeak: typeof makeDefaultStreamSpeak;
+    makeRoutedSynth: typeof makeRoutedSynth;
+    makeRoutedStreamSpeak: typeof makeRoutedStreamSpeak;
+    resumeTextAfterStreamFailure: typeof resumeTextAfterStreamFailure;
+    defaultPlay: typeof defaultPlay;
+};
+/**
+ * Speak an arbitrary string aloud RIGHT NOW (proactively), not as a reply to something heard.
+ * The missing primitive for reminders/announcements: synthesize → play → clean up.
+ * Injectable synth/play for tests. Never-throws ($0 with local Pocket/Piper).
+ * Returns true only when the local player actually ran.
+ */
+export declare function sayNow(text: string, options?: VoiceStepOptions & {
+    voice?: string;
+    rootDir?: string;
+    synth?: SynthFn;
+    play?: PlayFn;
+    /** `never` prevents a caller with its own bridge/notification from double-sending. */
+    phoneDelivery?: 'env' | 'never';
+}): Promise<boolean>;
+/**
+ * Play a pre-recorded repository WAV without invoking TTS. The source asset is
+ * copied to a throwaway attenuated WAV so playback never mutates the cache.
+ */
+export declare function playCachedConversationCue(cue: ConversationCueRequest): Promise<boolean>;
+/**
+ * An `onHeard` handler (callable as `(heard) => Promise<void>`) with an added `interrupt()`
+ * method — the foundation of barge-in. It is a plain function so it drops into
+ * `wireSpeechReaction({ onHeard: makeVoiceReply() })` unchanged; `.interrupt()` is an
+ * extra property, not a new call contract.
+ */
+export interface VoiceReplyHandler {
+    (heard: string, context?: VoiceTurnContext): Promise<void>;
+    /** Last completed turn timing (also available through `VoiceReplyOptions.onTiming`). */
+    lastTiming?: VoiceReplyTiming;
+    /**
+     * Cancel the in-flight spoken turn (barge-in): abort the LLM/agent think step (its HTTP
+     * request), kill the TTS playback, and hard-reset the half-duplex guard so the ear re-opens
+     * IMMEDIATELY (no echo tail). The handler promise then resolves, which lets the speech-reaction
+     * queue drain the next utterance with no blocked state. Idempotent, never-throws; a no-op when
+     * nothing is in flight.
+     */
+    interrupt(turnId?: string): void;
+}
+/**
+ * Build an `onHeard` handler that thinks then speaks, with a programmatic `interrupt()`.
+ * Never-throws. Wire it into `wireSpeechReaction({ onHeard: makeVoiceReply() })`.
+ *
+ * Interruption is driven by one correlated `AbortController` per turn: `interrupt(turnId)`
+ * targets it, cancels the think step (signal → provider transport), and kills the TTS child.
+ * Without an `interrupt()` call the controller is never aborted, so the turn runs exactly as
+ * before (tour-par-tour bloquant) — the signal threading is inert.
+ */
+export declare function makeVoiceReply(options?: VoiceReplyOptions): VoiceReplyHandler;