@framers/agentos 0.1.75 → 0.1.76

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

@@ -0,0 +1,67 @@
+/**
+ * @module voice-pipeline/HardCutBargeinHandler
+ *
+ * Implements a hard-cut barge-in policy: when the user speaks over TTS output
+ * for at least `minSpeechMs` milliseconds, playback is stopped immediately with
+ * no fade-out. Short detections below the threshold are treated as accidental
+ * noise and ignored.
+ */
+import type { BargeinAction, BargeinContext, IBargeinHandler } from './types.js';
+/**
+ * Construction options for {@link HardCutBargeinHandler}.
+ */
+export interface HardCutBargeinHandlerOptions {
+    /**
+     * Minimum confirmed speech duration (in milliseconds) required before a
+     * barge-in is treated as intentional. Detections shorter than this value are
+     * returned as `{ type: 'ignore' }` to avoid reacting to background noise.
+     *
+     * @defaultValue 300
+     */
+    minSpeechMs?: number;
+}
+/**
+ * Barge-in handler that applies a hard-cut strategy.
+ *
+ * When the user speaks over an active TTS stream, this handler immediately
+ * cancels playback if the detected speech exceeds `minSpeechMs`. Below that
+ * threshold the interruption is considered noise and playback continues
+ * uninterrupted.
+ *
+ * @example
+ * ```ts
+ * const handler = new HardCutBargeinHandler({ minSpeechMs: 250 });
+ * const action = handler.handleBargein({ speechDurationMs: 400, ... });
+ * // action.type === 'cancel'
+ * ```
+ */
+export declare class HardCutBargeinHandler implements IBargeinHandler {
+    /**
+     * The interruption strategy implemented by this handler.
+     * Always `'hard-cut'`.
+     */
+    readonly mode: "hard-cut";
+    /**
+     * Minimum speech duration in milliseconds before the interruption is
+     * considered intentional.
+     */
+    private readonly minSpeechMs;
+    /**
+     * Constructs a new {@link HardCutBargeinHandler}.
+     *
+     * @param options - Optional configuration. Defaults to `{ minSpeechMs: 300 }`.
+     */
+    constructor(options?: HardCutBargeinHandlerOptions);
+    /**
+     * Evaluate the barge-in context and return the action the pipeline should take.
+     *
+     * - If `context.speechDurationMs >= minSpeechMs`, returns
+     *   `{ type: 'cancel', injectMarker: '[interrupted]' }` to immediately halt TTS.
+     * - Otherwise returns `{ type: 'ignore' }` to continue playback.
+     *
+     * @param context - Snapshot of the barge-in state at the moment of detection.
+     * @returns The pipeline action to execute.
+     */
+    handleBargein(context: BargeinContext): BargeinAction;
+}
+//# sourceMappingURL=HardCutBargeinHandler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"HardCutBargeinHandler.d.ts","sourceRoot":"","sources":["../../src/voice-pipeline/HardCutBargeinHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEjF;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,qBAAsB,YAAW,eAAe;IAC3D;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAG,UAAU,CAAU;IAEpC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC;;;;OAIG;gBACS,OAAO,GAAE,4BAAiC;IAItD;;;;;;;;;OASG;IACH,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa;CAMtD"}

package/dist/voice-pipeline/HardCutBargeinHandler.js

@@ -0,0 +1,55 @@
+/**
+ * @module voice-pipeline/HardCutBargeinHandler
+ *
+ * Implements a hard-cut barge-in policy: when the user speaks over TTS output
+ * for at least `minSpeechMs` milliseconds, playback is stopped immediately with
+ * no fade-out. Short detections below the threshold are treated as accidental
+ * noise and ignored.
+ */
+/**
+ * Barge-in handler that applies a hard-cut strategy.
+ *
+ * When the user speaks over an active TTS stream, this handler immediately
+ * cancels playback if the detected speech exceeds `minSpeechMs`. Below that
+ * threshold the interruption is considered noise and playback continues
+ * uninterrupted.
+ *
+ * @example
+ * ```ts
+ * const handler = new HardCutBargeinHandler({ minSpeechMs: 250 });
+ * const action = handler.handleBargein({ speechDurationMs: 400, ... });
+ * // action.type === 'cancel'
+ * ```
+ */
+export class HardCutBargeinHandler {
+    /**
+     * Constructs a new {@link HardCutBargeinHandler}.
+     *
+     * @param options - Optional configuration. Defaults to `{ minSpeechMs: 300 }`.
+     */
+    constructor(options = {}) {
+        /**
+         * The interruption strategy implemented by this handler.
+         * Always `'hard-cut'`.
+         */
+        this.mode = 'hard-cut';
+        this.minSpeechMs = options.minSpeechMs ?? 300;
+    }
+    /**
+     * Evaluate the barge-in context and return the action the pipeline should take.
+     *
+     * - If `context.speechDurationMs >= minSpeechMs`, returns
+     *   `{ type: 'cancel', injectMarker: '[interrupted]' }` to immediately halt TTS.
+     * - Otherwise returns `{ type: 'ignore' }` to continue playback.
+     *
+     * @param context - Snapshot of the barge-in state at the moment of detection.
+     * @returns The pipeline action to execute.
+     */
+    handleBargein(context) {
+        if (context.speechDurationMs >= this.minSpeechMs) {
+            return { type: 'cancel', injectMarker: '[interrupted]' };
+        }
+        return { type: 'ignore' };
+    }
+}
+//# sourceMappingURL=HardCutBargeinHandler.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"HardCutBargeinHandler.js","sourceRoot":"","sources":["../../src/voice-pipeline/HardCutBargeinHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAkBH;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,qBAAqB;IAahC;;;;OAIG;IACH,YAAY,UAAwC,EAAE;QAjBtD;;;WAGG;QACM,SAAI,GAAG,UAAmB,CAAC;QAclC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,GAAG,CAAC;IAChD,CAAC;IAED;;;;;;;;;OASG;IACH,aAAa,CAAC,OAAuB;QACnC,IAAI,OAAO,CAAC,gBAAgB,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACjD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,eAAe,EAAE,CAAC;QAC3D,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAC5B,CAAC;CACF"}

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

@@ -0,0 +1,128 @@
+/**
+ * @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';
+import type { IEndpointDetector, TranscriptEvent, VadEvent } from './types.js';
+/**
+ * Constructor options for {@link HeuristicEndpointDetector}.
+ */
+export interface HeuristicEndpointDetectorOptions {
+    /**
+     * How long (ms) to wait after `speech_end` before emitting `turn_complete`
+     * when no terminal punctuation is detected.
+     * @defaultValue 1500
+     */
+    silenceTimeoutMs?: number;
+}
+/**
+ * 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 declare class HeuristicEndpointDetector extends EventEmitter implements IEndpointDetector {
+    /**
+     * Active detection strategy label.
+     * Typed as `'hybrid'` to satisfy {@link IEndpointDetector.mode}; consumers
+     * that need to distinguish heuristic detectors may inspect `instanceof`.
+     */
+    readonly mode: IEndpointDetector['mode'];
+    /** Resolved silence timeout in milliseconds. */
+    private readonly silenceTimeoutMs;
+    /** The latest final transcript text accumulated for the current turn. */
+    private accumulatedText;
+    /** Whether the VAD currently reports active speech. */
+    private speechActive;
+    /** Handle to a pending silence timeout, or `null` if none is running. */
+    private silenceTimer;
+    /** Wall-clock timestamp (ms) when the current turn's speech started. */
+    private turnStartMs;
+    /** Confidence of the most recent final transcript. */
+    private lastConfidence;
+    /**
+     * Create a new {@link HeuristicEndpointDetector}.
+     *
+     * @param options — Optional configuration overrides.
+     */
+    constructor(options?: HeuristicEndpointDetectorOptions);
+    /**
+     * 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: TranscriptEvent): void;
+    /**
+     * 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: VadEvent): void;
+    /**
+     * 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(): void;
+    /**
+     * 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`.
+     */
+    private _emitTurnComplete;
+    /**
+     * 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`.
+     */
+    private _startSilenceTimer;
+    /**
+     * Cancel a pending silence timer without any side effects.
+     */
+    private _clearSilenceTimer;
+}
+//# sourceMappingURL=HeuristicEndpointDetector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"HeuristicEndpointDetector.d.ts","sourceRoot":"","sources":["../../src/voice-pipeline/HeuristicEndpointDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,QAAQ,EAET,MAAM,YAAY,CAAC;AAwCpB;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,yBACX,SAAQ,YACR,YAAW,iBAAiB;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAe;IAEvD,gDAAgD;IAChD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAE1C,yEAAyE;IACzE,OAAO,CAAC,eAAe,CAAM;IAE7B,uDAAuD;IACvD,OAAO,CAAC,YAAY,CAAS;IAE7B,yEAAyE;IACzE,OAAO,CAAC,YAAY,CAA8C;IAElE,wEAAwE;IACxE,OAAO,CAAC,WAAW,CAAuB;IAE1C,sDAAsD;IACtD,OAAO,CAAC,cAAc,CAAK;IAM3B;;;;OAIG;gBACS,OAAO,GAAE,gCAAqC;IAS1D;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI;IAwBjD;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAyCnC;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAYb;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAoBzB;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAQ1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;CAM3B"}

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"}