@framers/agentos 0.1.74 → 0.1.76

package/dist/voice-pipeline/HeuristicEndpointDetector.js

@@ -0,0 +1,240 @@
+/**
+ * @module voice-pipeline/HeuristicEndpointDetector
+ *
+ * A lightweight, rule-based endpoint detector that combines terminal punctuation
+ * analysis with a configurable silence timeout to determine when the user has
+ * finished speaking. Suitable for low-latency deployments where an LLM-based
+ * semantic detector would add unacceptable round-trip overhead.
+ *
+ * Detection strategy:
+ *   1. On `speech_end`, if the accumulated final transcript ends with `.`, `?`, or `!`,
+ *      fire `turn_complete` immediately with reason `'punctuation'`.
+ *   2. Otherwise, start a silence timer (default 1 500 ms). If speech does not
+ *      resume before the timer fires, emit `turn_complete` with reason `'silence_timeout'`.
+ *   3. Backchannel phrases (e.g. "uh huh", "yeah") are recognised, suppressed from
+ *      accumulation, and re-emitted as `'backchannel_detected'` events so the
+ *      pipeline can decide whether to suppress an agent response.
+ */
+import { EventEmitter } from 'node:events';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * Default silence duration (ms) after speech stops before firing `turn_complete`.
+ */
+const DEFAULT_SILENCE_TIMEOUT_MS = 1500;
+/**
+ * Terminal punctuation characters that signal sentence completion.
+ */
+const TERMINAL_PUNCTUATION = /[.?!]$/;
+/**
+ * Normalised backchannel phrases that indicate the listener is acknowledging
+ * but not taking a full conversational turn. Compared after `.trim().toLowerCase()`.
+ */
+const BACKCHANNEL_PHRASES = new Set([
+    'uh huh',
+    'yeah',
+    'okay',
+    'ok',
+    'mm hmm',
+    'mmhmm',
+    'mhm',
+    'mm-hmm',
+    'right',
+    'sure',
+    'yep',
+    'yup',
+    'gotcha',
+]);
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Heuristic endpoint detector that uses terminal punctuation and a silence
+ * timeout to decide when the user's turn is complete.
+ *
+ * Emits:
+ * - `'turn_complete'` ({@link TurnCompleteEvent}) — user turn has ended.
+ * - `'backchannel_detected'` (`{ text: string }`) — a backchannel phrase was
+ *   recognised; accumulation is suppressed for this utterance.
+ *
+ * @example
+ * ```typescript
+ * const detector = new HeuristicEndpointDetector({ silenceTimeoutMs: 1000 });
+ * detector.on('turn_complete', (event) => console.log('Turn done:', event));
+ * detector.pushTranscript({ text: 'Hello there.', isFinal: true, confidence: 0.95, words: [] });
+ * detector.pushVadEvent({ type: 'speech_end', timestamp: Date.now(), source: 'vad' });
+ * // → 'turn_complete' fires immediately with reason 'punctuation'
+ * ```
+ */
+export class HeuristicEndpointDetector extends EventEmitter {
+    // ---------------------------------------------------------------------------
+    // Constructor
+    // ---------------------------------------------------------------------------
+    /**
+     * Create a new {@link HeuristicEndpointDetector}.
+     *
+     * @param options — Optional configuration overrides.
+     */
+    constructor(options = {}) {
+        super();
+        /**
+         * Active detection strategy label.
+         * Typed as `'hybrid'` to satisfy {@link IEndpointDetector.mode}; consumers
+         * that need to distinguish heuristic detectors may inspect `instanceof`.
+         */
+        this.mode = 'heuristic';
+        /** The latest final transcript text accumulated for the current turn. */
+        this.accumulatedText = '';
+        /** Whether the VAD currently reports active speech. */
+        this.speechActive = false;
+        /** Handle to a pending silence timeout, or `null` if none is running. */
+        this.silenceTimer = null;
+        /** Wall-clock timestamp (ms) when the current turn's speech started. */
+        this.turnStartMs = null;
+        /** Confidence of the most recent final transcript. */
+        this.lastConfidence = 1;
+        this.silenceTimeoutMs = options.silenceTimeoutMs ?? DEFAULT_SILENCE_TIMEOUT_MS;
+    }
+    // ---------------------------------------------------------------------------
+    // IEndpointDetector — pushTranscript
+    // ---------------------------------------------------------------------------
+    /**
+     * Ingest a transcript event from the upstream STT session.
+     *
+     * Only final events (`isFinal: true`) affect internal state. Interim results
+     * are silently ignored — they may arrive very frequently and their text is
+     * unstable.
+     *
+     * If the final text is a recognised backchannel phrase the detector emits
+     * `'backchannel_detected'` and returns without accumulating the text, so that
+     * a subsequent `speech_end` event does not trigger `turn_complete`.
+     *
+     * @param transcript — Transcript event from the STT session.
+     */
+    pushTranscript(transcript) {
+        if (!transcript.isFinal) {
+            // Ignore partial/interim hypotheses — they will be superseded.
+            return;
+        }
+        const text = transcript.text;
+        const normalised = text.trim().toLowerCase();
+        // Detect backchannel acknowledgements before accumulating.
+        if (BACKCHANNEL_PHRASES.has(normalised)) {
+            this.emit('backchannel_detected', { text });
+            return;
+        }
+        // Accumulate the final transcript and store the confidence score.
+        this.accumulatedText = text;
+        this.lastConfidence = transcript.confidence;
+    }
+    // ---------------------------------------------------------------------------
+    // IEndpointDetector — pushVadEvent
+    // ---------------------------------------------------------------------------
+    /**
+     * Ingest a VAD (voice activity detection) event.
+     *
+     * - `speech_start`: marks the turn as active and cancels any pending silence
+     *   timer (the user resumed speaking before the timeout elapsed).
+     * - `speech_end`: if accumulated text is available, either fires
+     *   `turn_complete` immediately (punctuation) or starts the silence timer.
+     * - `silence`: heartbeat events are ignored; only explicit `speech_end`
+     *   drives the timeout logic.
+     *
+     * @param event — VAD transition event.
+     */
+    pushVadEvent(event) {
+        switch (event.type) {
+            case 'speech_start': {
+                this.speechActive = true;
+                this._clearSilenceTimer();
+                if (this.turnStartMs === null) {
+                    this.turnStartMs = event.timestamp;
+                }
+                break;
+            }
+            case 'speech_end': {
+                this.speechActive = false;
+                if (!this.accumulatedText) {
+                    // Nothing to flush — no transcript arrived yet.
+                    break;
+                }
+                if (TERMINAL_PUNCTUATION.test(this.accumulatedText)) {
+                    // Sentence-terminal punctuation → fire immediately.
+                    this._emitTurnComplete('punctuation', event.timestamp);
+                }
+                else {
+                    // No punctuation → wait for silence timeout.
+                    this._startSilenceTimer(event.timestamp);
+                }
+                break;
+            }
+            case 'silence': {
+                // Periodic heartbeat — no action required; the silence timer already
+                // handles the delayed fire if one is pending.
+                break;
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // IEndpointDetector — reset
+    // ---------------------------------------------------------------------------
+    /**
+     * Reset all internal state, cancel pending timers, and prepare the detector
+     * for the next user turn. Should be called by the pipeline after each
+     * `turn_complete` event before audio for the next turn begins to arrive.
+     */
+    reset() {
+        this._clearSilenceTimer();
+        this.accumulatedText = '';
+        this.speechActive = false;
+        this.turnStartMs = null;
+        this.lastConfidence = 1;
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Emit `turn_complete` with the currently accumulated transcript and then
+     * reset internal state so the detector is ready for the next turn.
+     *
+     * @param reason — The semantic reason driving this completion.
+     * @param speechEndTimestamp — Unix epoch ms timestamp of the `speech_end` event,
+     *   used to compute `durationMs`.
+     */
+    _emitTurnComplete(reason, speechEndTimestamp) {
+        const durationMs = this.turnStartMs !== null ? speechEndTimestamp - this.turnStartMs : 0;
+        const event = {
+            transcript: this.accumulatedText,
+            confidence: this.lastConfidence,
+            durationMs,
+            reason,
+        };
+        // Reset before emitting so that any re-entrant listeners see clean state.
+        this.reset();
+        this.emit('turn_complete', event);
+    }
+    /**
+     * Start the silence-timeout timer. If the user does not resume speaking
+     * within {@link silenceTimeoutMs} ms the detector fires `turn_complete`.
+     *
+     * @param speechEndTimestamp — Timestamp passed through to `_emitTurnComplete`.
+     */
+    _startSilenceTimer(speechEndTimestamp) {
+        this._clearSilenceTimer();
+        this.silenceTimer = setTimeout(() => {
+            this.silenceTimer = null;
+            this._emitTurnComplete('silence_timeout', speechEndTimestamp);
+        }, this.silenceTimeoutMs);
+    }
+    /**
+     * Cancel a pending silence timer without any side effects.
+     */
+    _clearSilenceTimer() {
+        if (this.silenceTimer !== null) {
+            clearTimeout(this.silenceTimer);
+            this.silenceTimer = null;
+        }
+    }
+}
+//# sourceMappingURL=HeuristicEndpointDetector.js.map

package/dist/voice-pipeline/HeuristicEndpointDetector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HeuristicEndpointDetector.js","sourceRoot":"","sources":["../../src/voice-pipeline/HeuristicEndpointDetector.ts"],"names":[],"mappings":"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"}

package/dist/voice-pipeline/SoftFadeBargeinHandler.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @module voice-pipeline/SoftFadeBargeinHandler
+ *
+ * Implements a three-tier soft-fade barge-in policy.
+ *
+ * Very short speech detections (< `ignoreMs`) are dismissed as noise.
+ * Medium-length detections trigger a fade-out pause so the user can speak
+ * without an abrupt cut. Long detections (>= `cancelMs`) stop playback
+ * outright and inject a conversation marker.
+ */
+import type { BargeinAction, BargeinContext, IBargeinHandler } from './types.js';
+/**
+ * Construction options for {@link SoftFadeBargeinHandler}.
+ */
+export interface SoftFadeBargeinHandlerOptions {
+    /**
+     * Speech duration threshold in milliseconds below which the barge-in is
+     * treated as accidental noise and ignored.
+     *
+     * @defaultValue 100
+     */
+    ignoreMs?: number;
+    /**
+     * Speech duration threshold in milliseconds at or above which the barge-in
+     * triggers an immediate cancel rather than a fade-out pause. Must be greater
+     * than `ignoreMs` for the fade region to exist.
+     *
+     * @defaultValue 2000
+     */
+    cancelMs?: number;
+    /**
+     * Duration of the TTS fade-out in milliseconds applied when the speech
+     * duration falls in the range `[ignoreMs, cancelMs)`.
+     *
+     * @defaultValue 200
+     */
+    fadeMs?: number;
+}
+/**
+ * Barge-in handler that applies a three-tier soft-fade strategy.
+ *
+ * The handler maps the confirmed speech duration to one of three actions:
+ *
+ * | Speech duration          | Action                                      |
+ * |--------------------------|---------------------------------------------|
+ * | `< ignoreMs`             | `ignore` — noise, continue TTS uninterrupted |
+ * | `>= ignoreMs < cancelMs` | `pause` with `fadeMs` fade-out               |
+ * | `>= cancelMs`            | `cancel` with `'[interrupted]'` marker       |
+ *
+ * @example
+ * ```ts
+ * const handler = new SoftFadeBargeinHandler({ ignoreMs: 80, cancelMs: 1500, fadeMs: 150 });
+ * handler.handleBargein({ speechDurationMs: 500, ... }); // { type: 'pause', fadeMs: 150 }
+ * handler.handleBargein({ speechDurationMs: 1600, ... }); // { type: 'cancel', injectMarker: '[interrupted]' }
+ * handler.handleBargein({ speechDurationMs: 30, ... });  // { type: 'ignore' }
+ * ```
+ */
+export declare class SoftFadeBargeinHandler implements IBargeinHandler {
+    /**
+     * The interruption strategy implemented by this handler.
+     * Always `'soft-fade'`.
+     */
+    readonly mode: "soft-fade";
+    /**
+     * Speech duration below which the barge-in is dismissed as noise.
+     */
+    private readonly ignoreMs;
+    /**
+     * Speech duration at or above which the barge-in escalates to a full cancel.
+     */
+    private readonly cancelMs;
+    /**
+     * Duration of the TTS audio fade-out applied during a `'pause'` action.
+     */
+    private readonly fadeMs;
+    /**
+     * Constructs a new {@link SoftFadeBargeinHandler}.
+     *
+     * @param options - Optional configuration. Defaults to
+     *   `{ ignoreMs: 100, cancelMs: 2000, fadeMs: 200 }`.
+     */
+    constructor(options?: SoftFadeBargeinHandlerOptions);
+    /**
+     * Evaluate the barge-in context and return the pipeline action.
+     *
+     * Decision tree (evaluated in order):
+     * 1. `speechDurationMs < ignoreMs` → `{ type: 'ignore' }`
+     * 2. `speechDurationMs >= cancelMs` → `{ type: 'cancel', injectMarker: '[interrupted]' }`
+     * 3. Otherwise → `{ type: 'pause', fadeMs }`
+     *
+     * @param context - Snapshot of the barge-in state at the moment of detection.
+     * @returns The pipeline action to execute.
+     */
+    handleBargein(context: BargeinContext): BargeinAction;
+}
+//# sourceMappingURL=SoftFadeBargeinHandler.d.ts.map

package/dist/voice-pipeline/SoftFadeBargeinHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SoftFadeBargeinHandler.d.ts","sourceRoot":"","sources":["../../src/voice-pipeline/SoftFadeBargeinHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEjF;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,sBAAuB,YAAW,eAAe;IAC5D;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAG,WAAW,CAAU;IAErC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC;;;;;OAKG;gBACS,OAAO,GAAE,6BAAkC;IAMvD;;;;;;;;;;OAUG;IACH,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa;CAatD"}

package/dist/voice-pipeline/SoftFadeBargeinHandler.js

@@ -0,0 +1,69 @@
+/**
+ * @module voice-pipeline/SoftFadeBargeinHandler
+ *
+ * Implements a three-tier soft-fade barge-in policy.
+ *
+ * Very short speech detections (< `ignoreMs`) are dismissed as noise.
+ * Medium-length detections trigger a fade-out pause so the user can speak
+ * without an abrupt cut. Long detections (>= `cancelMs`) stop playback
+ * outright and inject a conversation marker.
+ */
+/**
+ * Barge-in handler that applies a three-tier soft-fade strategy.
+ *
+ * The handler maps the confirmed speech duration to one of three actions:
+ *
+ * | Speech duration          | Action                                      |
+ * |--------------------------|---------------------------------------------|
+ * | `< ignoreMs`             | `ignore` — noise, continue TTS uninterrupted |
+ * | `>= ignoreMs < cancelMs` | `pause` with `fadeMs` fade-out               |
+ * | `>= cancelMs`            | `cancel` with `'[interrupted]'` marker       |
+ *
+ * @example
+ * ```ts
+ * const handler = new SoftFadeBargeinHandler({ ignoreMs: 80, cancelMs: 1500, fadeMs: 150 });
+ * handler.handleBargein({ speechDurationMs: 500, ... }); // { type: 'pause', fadeMs: 150 }
+ * handler.handleBargein({ speechDurationMs: 1600, ... }); // { type: 'cancel', injectMarker: '[interrupted]' }
+ * handler.handleBargein({ speechDurationMs: 30, ... });  // { type: 'ignore' }
+ * ```
+ */
+export class SoftFadeBargeinHandler {
+    /**
+     * Constructs a new {@link SoftFadeBargeinHandler}.
+     *
+     * @param options - Optional configuration. Defaults to
+     *   `{ ignoreMs: 100, cancelMs: 2000, fadeMs: 200 }`.
+     */
+    constructor(options = {}) {
+        /**
+         * The interruption strategy implemented by this handler.
+         * Always `'soft-fade'`.
+         */
+        this.mode = 'soft-fade';
+        this.ignoreMs = options.ignoreMs ?? 100;
+        this.cancelMs = options.cancelMs ?? 2000;
+        this.fadeMs = options.fadeMs ?? 200;
+    }
+    /**
+     * Evaluate the barge-in context and return the pipeline action.
+     *
+     * Decision tree (evaluated in order):
+     * 1. `speechDurationMs < ignoreMs` → `{ type: 'ignore' }`
+     * 2. `speechDurationMs >= cancelMs` → `{ type: 'cancel', injectMarker: '[interrupted]' }`
+     * 3. Otherwise → `{ type: 'pause', fadeMs }`
+     *
+     * @param context - Snapshot of the barge-in state at the moment of detection.
+     * @returns The pipeline action to execute.
+     */
+    handleBargein(context) {
+        const { speechDurationMs } = context;
+        if (speechDurationMs < this.ignoreMs) {
+            return { type: 'ignore' };
+        }
+        if (speechDurationMs >= this.cancelMs) {
+            return { type: 'cancel', injectMarker: '[interrupted]' };
+        }
+        return { type: 'pause', fadeMs: this.fadeMs };
+    }
+}
+//# sourceMappingURL=SoftFadeBargeinHandler.js.map

package/dist/voice-pipeline/SoftFadeBargeinHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SoftFadeBargeinHandler.js","sourceRoot":"","sources":["../../src/voice-pipeline/SoftFadeBargeinHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAkCH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,sBAAsB;IAsBjC;;;;;OAKG;IACH,YAAY,UAAyC,EAAE;QA3BvD;;;WAGG;QACM,SAAI,GAAG,WAAoB,CAAC;QAwBnC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,GAAG,CAAC;QACxC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC;QACzC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,GAAG,CAAC;IACtC,CAAC;IAED;;;;;;;;;;OAUG;IACH,aAAa,CAAC,OAAuB;QACnC,MAAM,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC;QAErC,IAAI,gBAAgB,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YACrC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QAC5B,CAAC;QAED,IAAI,gBAAgB,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACtC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,eAAe,EAAE,CAAC;QAC3D,CAAC;QAED,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;IAChD,CAAC;CACF"}

package/dist/voice-pipeline/VoicePipelineOrchestrator.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @module voice-pipeline/VoicePipelineOrchestrator
+ *
+ * Central state machine that wires together transport, STT, endpoint detection,
+ * TTS, barge-in handling, and the agent session into a coordinated real-time
+ * voice conversation loop.
+ *
+ * State transitions:
+ * ```
+ * IDLE → startSession() → LISTENING
+ * LISTENING → turn_complete → PROCESSING
+ * PROCESSING → LLM tokens start → SPEAKING
+ * SPEAKING → TTS complete → LISTENING
+ * SPEAKING → barge-in → INTERRUPTING → LISTENING
+ * ANY → transport disconnect → CLOSED
+ * ```
+ */
+import { EventEmitter } from 'node:events';
+import type { IBargeinHandler, IDiarizationEngine, IEndpointDetector, IStreamTransport, IStreamingSTT, IStreamingTTS, IVoicePipelineAgentSession, PipelineState, VoicePipelineConfig, VoicePipelineSession } from './types.js';
+/**
+ * Overrides for injecting pre-built components (primarily for testing).
+ * In production, components would be resolved from ExtensionManager.
+ */
+export interface VoicePipelineOverrides {
+    /** Pre-built streaming STT provider. */
+    streamingSTT?: IStreamingSTT;
+    /** Pre-built streaming TTS provider. */
+    streamingTTS?: IStreamingTTS;
+    /** Pre-built endpoint detector. */
+    endpointDetector?: IEndpointDetector;
+    /** Pre-built barge-in handler. */
+    bargeinHandler?: IBargeinHandler;
+    /** Pre-built diarization engine. */
+    diarizationEngine?: IDiarizationEngine;
+}
+/**
+ * VoicePipelineOrchestrator is the central state machine for the AgentOS
+ * streaming voice pipeline. It coordinates audio capture, speech recognition,
+ * endpoint detection, agent inference, text-to-speech synthesis, and barge-in
+ * handling into a seamless real-time conversation loop.
+ *
+ * Emits:
+ * - `'state_changed'` ({ from: PipelineState, to: PipelineState })
+ */
+export declare class VoicePipelineOrchestrator extends EventEmitter {
+    private readonly config;
+    /** Current pipeline state. */
+    private _state;
+    /** Active sub-sessions and components, set during startSession. */
+    private _sttSession;
+    private _ttsSession;
+    private _endpointDetector;
+    private _bargeinHandler;
+    private _transport;
+    private _agentSession;
+    /** Watchdog timer ID for max turn duration. */
+    private _watchdogTimer;
+    /** Tracks cumulative TTS text for barge-in context. */
+    private _currentTTSText;
+    /** Tracks cumulative played duration for barge-in context. */
+    private _currentPlayedMs;
+    /** Current pipeline state (read-only). */
+    get state(): PipelineState;
+    constructor(config: VoicePipelineConfig);
+    /**
+     * Start a voice session. Accepts pre-built components via overrides for testing.
+     * In production, components are resolved from ExtensionManager (future task).
+     *
+     * @param transport - The bidirectional audio/text stream transport.
+     * @param agentSession - The agent session adapter for turn-based conversation.
+     * @param overrides - Optional pre-built components (for testing or manual wiring).
+     * @returns A live VoicePipelineSession object.
+     */
+    startSession(transport: IStreamTransport, agentSession: IVoicePipelineAgentSession, overrides?: VoicePipelineOverrides): Promise<VoicePipelineSession>;
+    /**
+     * Stop the current session, tearing down all sub-sessions and timers.
+     *
+     * @param reason - Optional human-readable reason for diagnostics.
+     */
+    stopSession(reason?: string): Promise<void>;
+    /**
+     * Forward audio frames from transport to STT session.
+     */
+    private _wireTransportToSTT;
+    /**
+     * Forward STT transcript events to endpoint detector and transport.
+     */
+    private _wireSTTToEndpoint;
+    /**
+     * Handle turn_complete from endpoint detector — transition through
+     * PROCESSING → SPEAKING → LISTENING.
+     */
+    private _wireTurnComplete;
+    /**
+     * Forward TTS audio chunks to the transport and handle utterance completion.
+     */
+    private _wireTTSToTransport;
+    /**
+     * Wire barge-in detection: when speech is detected during SPEAKING state,
+     * consult the barge-in handler and act accordingly.
+     */
+    private _wireBargein;
+    /**
+     * Handle transport disconnect — close everything.
+     */
+    private _wireDisconnect;
+    /**
+     * Transition to a new pipeline state, emitting a `state_changed` event.
+     */
+    private _setState;
+    /**
+     * Reset the watchdog timer for max turn duration. If the pipeline stays in
+     * LISTENING for longer than `maxTurnDurationMs` (default 30s) without a
+     * turn_complete, force a timeout.
+     */
+    private _resetWatchdog;
+    /**
+     * Clear the watchdog timer if active.
+     */
+    private _clearWatchdog;
+}
+//# sourceMappingURL=VoicePipelineOrchestrator.d.ts.map

package/dist/voice-pipeline/VoicePipelineOrchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VoicePipelineOrchestrator.d.ts","sourceRoot":"","sources":["../../src/voice-pipeline/VoicePipelineOrchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,KAAK,EAGV,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,0BAA0B,EAC1B,aAAa,EAKb,mBAAmB,EACnB,oBAAoB,EAErB,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,wCAAwC;IACxC,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,wCAAwC;IACxC,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,mCAAmC;IACnC,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;IACrC,kCAAkC;IAClC,cAAc,CAAC,EAAE,eAAe,CAAC;IACjC,oCAAoC;IACpC,iBAAiB,CAAC,EAAE,kBAAkB,CAAC;CACxC;AAED;;;;;;;;GAQG;AACH,qBAAa,yBAA0B,SAAQ,YAAY;IA0B7C,OAAO,CAAC,QAAQ,CAAC,MAAM;IAzBnC,8BAA8B;IAC9B,OAAO,CAAC,MAAM,CAAyB;IAEvC,mEAAmE;IACnE,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,iBAAiB,CAAkC;IAC3D,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,UAAU,CAAiC;IACnD,OAAO,CAAC,aAAa,CAA2C;IAEhE,+CAA+C;IAC/C,OAAO,CAAC,cAAc,CAA8C;IAEpE,uDAAuD;IACvD,OAAO,CAAC,eAAe,CAAM;IAE7B,8DAA8D;IAC9D,OAAO,CAAC,gBAAgB,CAAK;IAE7B,0CAA0C;IAC1C,IAAI,KAAK,IAAI,aAAa,CAEzB;gBAE4B,MAAM,EAAE,mBAAmB;IAIxD;;;;;;;;OAQG;IACG,YAAY,CAChB,SAAS,EAAE,gBAAgB,EAC3B,YAAY,EAAE,0BAA0B,EACxC,SAAS,CAAC,EAAE,sBAAsB,GACjC,OAAO,CAAC,oBAAoB,CAAC;IAgEhC;;;;OAIG;IACG,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBjD;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAS3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAgB1B;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAuCzB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAyB3B;;;OAGG;IACH,OAAO,CAAC,YAAY;IA8CpB;;OAEG;IACH,OAAO,CAAC,eAAe;IAiBvB;;OAEG;IACH,OAAO,CAAC,SAAS;IAWjB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IActB;;OAEG;IACH,OAAO,CAAC,cAAc;CAMvB"}