@framers/agentos-ext-endpoint-semantic 0.2.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 Framers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+

package/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: endpoint-semantic
+description: Semantic endpoint detection — uses an LLM to classify whether the user's utterance is a complete thought, reducing false turn boundaries on mid-sentence pauses
+category: voice
+---
+
+# Semantic Endpoint Detector Extension Pack
+
+LLM-powered turn-boundary detection for the AgentOS voice pipeline. Extends the heuristic detector's punctuation and backchannel rules with a fast LLM classifier that decides whether an ambiguous utterance is complete or still in progress.
+
+## How it works
+
+1. **Punctuation (immediate)** — If the final transcript ends with `.`, `?`, or `!`, `turn_complete` fires immediately with reason `punctuation`, identical to the heuristic detector.
+2. **Backchannel suppression** — Short acknowledgement phrases (`"uh huh"`, `"yeah"`, etc.) are emitted as `backchannel_detected` and do not advance the turn.
+3. **LLM classification (ambiguous)** — On silence without terminal punctuation, after `minSilenceBeforeCheckMs` (default 500 ms), a small LLM prompt is sent asking whether the utterance is a complete thought. Results are LRU-cached keyed on the first 100 characters of the transcript.
+   - `COMPLETE` → emit `turn_complete` with reason `semantic_model`.
+   - `INCOMPLETE` → keep waiting; eventual silence timeout acts as the final fallback.
+   - `TIMEOUT` (LLM call exceeds `timeoutMs`) → fall back to silence timeout.
+
+## Setup
+
+No API key is bundled — supply an `llmCall` function when constructing the detector directly, or configure an LLM provider in the AgentOS runtime.
+
+## Configuration
+
+```json
+{
+  "voice": {
+    "endpointing": "semantic",
+    "endpointingOptions": {
+      "model": "gpt-4o-mini",
+      "timeoutMs": 500,
+      "minSilenceBeforeCheckMs": 500,
+      "silenceTimeoutMs": 2000
+    }
+  }
+}
+```
+
+### Options
+
+| Option                    | Type     | Default | Description                                                         |
+|---------------------------|----------|---------|---------------------------------------------------------------------|
+| `model`                   | `string` | —       | LLM model identifier forwarded to the runtime LLM provider          |
+| `timeoutMs`               | `number` | `500`   | Max ms to wait for the LLM before falling back to silence timeout   |
+| `minSilenceBeforeCheckMs` | `number` | `500`   | Silence duration after speech_end before the LLM is queried         |
+| `silenceTimeoutMs`        | `number` | `1500`  | Hard silence fallback after speech_end if LLM returns INCOMPLETE    |
+
+## Events
+
+| Event                 | Payload              | Description                                                  |
+|-----------------------|----------------------|--------------------------------------------------------------|
+| `turn_complete`       | `TurnCompleteEvent`  | User turn has ended; `reason` is `punctuation`, `semantic_model`, or `silence_timeout` |
+| `backchannel_detected`| `{ text: string }`  | A backchannel phrase was recognised; accumulation suppressed |
+
+## Programmatic usage
+
+```ts
+import { createSemanticEndpointDetector } from '@framers/agentos-ext-endpoint-semantic';
+
+const detector = createSemanticEndpointDetector(
+  async (prompt) => {
+    const res = await openai.chat.completions.create({
+      model: 'gpt-4o-mini',
+      messages: [{ role: 'user', content: prompt }],
+      max_tokens: 32,
+    });
+    return res.choices[0].message.content ?? '';
+  },
+  { timeoutMs: 400, minSilenceBeforeCheckMs: 600 }
+);
+
+detector.on('turn_complete', (evt) => console.log('Turn done:', evt.reason));
+```

package/dist/SemanticEndpointDetector.d.ts

@@ -0,0 +1,186 @@
+/**
+ * @file SemanticEndpointDetector.ts
+ * @description IEndpointDetector implementation that combines the heuristic
+ * detector's punctuation and backchannel rules with LLM-based turn-completeness
+ * classification for ambiguous cases.
+ *
+ * Detection strategy (in priority order):
+ *  1. **Backchannel** — recognised phrases emitted as `backchannel_detected`
+ *     without advancing the turn.
+ *  2. **Terminal punctuation** — immediate `turn_complete` with reason
+ *     `'punctuation'`.
+ *  3. **LLM classification** — invoked after `minSilenceBeforeCheckMs` of
+ *     silence; `COMPLETE` fires `turn_complete` with reason `'semantic_model'`.
+ *     `INCOMPLETE` defers to the hard silence timeout.
+ *  4. **Silence timeout** — hard fallback after `silenceTimeoutMs`, reason
+ *     `'silence_timeout'`.
+ *
+ * @module endpoint-semantic/SemanticEndpointDetector
+ */
+import { EventEmitter } from 'node:events';
+import type { SemanticEndpointConfig } from './types.js';
+/**
+ * Minimal VAD event shape required by this detector.
+ * Mirrors `VadEvent` from `@framers/agentos` voice-pipeline types.
+ */
+interface VadEvent {
+    /** Type of the VAD transition. */
+    type: 'speech_start' | 'speech_end' | 'silence';
+    /** Unix epoch millisecond timestamp of the transition. */
+    timestamp: number;
+    /** Optional raw energy level (implementation-defined). */
+    energyLevel?: number;
+    /** Origin of the VAD event. */
+    source?: 'vad' | 'stt';
+}
+/**
+ * Minimal transcript event shape required by this detector.
+ * Mirrors `TranscriptEvent` from `@framers/agentos` voice-pipeline types.
+ */
+interface TranscriptEvent {
+    /** Full transcript text for this event. */
+    text: string;
+    /** Aggregate confidence score in the range [0, 1]. */
+    confidence: number;
+    /** Word-level tokens (may be empty for interim events). */
+    words: unknown[];
+    /** `true` when this hypothesis is stable and will not be revised. */
+    isFinal: boolean;
+    /** Duration of the recognised speech segment, ms (final events only). */
+    durationMs?: number;
+}
+/**
+ * Minimal IEndpointDetector interface required by this pack.
+ * Mirrors `IEndpointDetector` from `@framers/agentos` voice-pipeline types.
+ */
+interface IEndpointDetector extends EventEmitter {
+    readonly mode: 'acoustic' | 'heuristic' | 'semantic';
+    pushVadEvent(event: VadEvent): void;
+    pushTranscript(event: TranscriptEvent): void;
+    reset(): void;
+}
+/**
+ * Semantic endpoint detector that augments heuristic rules with LLM-based
+ * turn-completeness classification.
+ *
+ * ### Events emitted
+ * - `'turn_complete'` ({@link TurnCompleteEvent}) — user turn has ended.
+ * - `'backchannel_detected'` (`{ text: string }`) — backchannel phrase
+ *   recognised; accumulation suppressed.
+ *
+ * @example
+ * ```ts
+ * const detector = new SemanticEndpointDetector(
+ *   async (prompt) => callMyLLM(prompt),
+ *   { minSilenceBeforeCheckMs: 600, silenceTimeoutMs: 2000 }
+ * );
+ * detector.on('turn_complete', (e) => console.log(e.reason));
+ * ```
+ */
+export declare class SemanticEndpointDetector extends EventEmitter implements IEndpointDetector {
+    /** Active detection strategy label. */
+    readonly mode: IEndpointDetector['mode'];
+    /** LLM-backed completeness classifier. */
+    private readonly classifier;
+    /** Resolved silence timeout (ms) — hard fallback. */
+    private readonly silenceTimeoutMs;
+    /** Silence duration (ms) before invoking the LLM classifier. */
+    private readonly minSilenceBeforeCheckMs;
+    /** Accumulated final transcript text for the current turn. */
+    private accumulatedText;
+    /** Whether VAD reports active speech. */
+    private speechActive;
+    /**
+     * Handle to the "check" timer — fires after `minSilenceBeforeCheckMs` and
+     * invokes the LLM classifier.
+     */
+    private checkTimer;
+    /**
+     * Handle to the hard silence-timeout timer — fires after `silenceTimeoutMs`.
+     */
+    private silenceTimer;
+    /** Wall-clock timestamp (ms) when speech began for the current turn. */
+    private turnStartMs;
+    /** Confidence score from the most recent final STT transcript. */
+    private lastConfidence;
+    /**
+     * @param llmCall — Async function that sends a prompt to an LLM and resolves
+     *                  with the raw response text.
+     * @param config  — Optional configuration overrides.
+     */
+    constructor(llmCall: (prompt: string) => Promise<string>, config?: SemanticEndpointConfig);
+    /**
+     * Ingest a transcript event from the upstream STT session.
+     *
+     * Only final events (`isFinal: true`) affect state. Interim results are
+     * silently ignored as they are unstable and arrive at high frequency.
+     *
+     * Recognised backchannel phrases are emitted as `'backchannel_detected'`
+     * without being accumulated, preventing a subsequent `speech_end` from
+     * triggering `turn_complete` for an acknowledgement.
+     *
+     * @param transcript — Transcript event from the upstream STT session.
+     */
+    pushTranscript(transcript: TranscriptEvent): void;
+    /**
+     * Ingest a VAD (voice activity detection) event.
+     *
+     * - `speech_start` — marks the turn as active, cancels pending timers.
+     * - `speech_end`   — if text has been accumulated, either fires immediately
+     *                    on terminal punctuation, or schedules the LLM check
+     *                    timer + hard silence-timeout timer.
+     * - `silence`      — periodic heartbeats; no action required.
+     *
+     * @param event — VAD transition event.
+     */
+    pushVadEvent(event: VadEvent): void;
+    /**
+     * Cancel all pending timers and clear accumulated state so the detector is
+     * ready for the next turn.  Should be called by the pipeline after each
+     * `turn_complete` event.
+     */
+    reset(): void;
+    /**
+     * Schedule the LLM completeness check after `minSilenceBeforeCheckMs`.
+     *
+     * If the LLM returns `COMPLETE`, `turn_complete` is emitted with reason
+     * `'semantic_model'` and both timers are cancelled.  If the LLM returns
+     * `INCOMPLETE` or `TIMEOUT`, the check timer is done and the hard silence
+     * timer (already running) continues as the fallback.
+     *
+     * @param speechEndTimestamp — Timestamp of the triggering `speech_end` event.
+     */
+    private _startCheckTimer;
+    /**
+     * Start the hard silence-timeout timer.  When it fires, `turn_complete` is
+     * emitted with reason `'silence_timeout'` regardless of the LLM result.
+     *
+     * @param speechEndTimestamp — Timestamp of the triggering `speech_end` event.
+     */
+    private _startSilenceTimer;
+    /**
+     * Emit `turn_complete` with the currently accumulated transcript and reset
+     * internal state so the detector is clean for the next turn.
+     *
+     * State is reset **before** emitting so that re-entrant listeners see a
+     * clean detector.
+     *
+     * @param reason             — Semantic reason driving turn completion.
+     * @param speechEndTimestamp — Timestamp used to compute `durationMs`.
+     */
+    private _emitTurnComplete;
+    /**
+     * Cancel the LLM check timer without any other side effects.
+     */
+    private _clearCheckTimer;
+    /**
+     * Cancel the hard silence timer without any other side effects.
+     */
+    private _clearSilenceTimer;
+    /**
+     * Cancel both the check timer and the silence timer.
+     */
+    private _clearAllTimers;
+}
+export {};
+//# sourceMappingURL=SemanticEndpointDetector.d.ts.map

package/dist/SemanticEndpointDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SemanticEndpointDetector.d.ts","sourceRoot":"","sources":["../src/SemanticEndpointDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAOzD;;;GAGG;AACH,UAAU,QAAQ;IAChB,kCAAkC;IAClC,IAAI,EAAE,cAAc,GAAG,YAAY,GAAG,SAAS,CAAC;IAChD,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;CACxB;AAED;;;GAGG;AACH,UAAU,eAAe;IACvB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,qEAAqE;IACrE,OAAO,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA6BD;;;GAGG;AACH,UAAU,iBAAkB,SAAQ,YAAY;IAC9C,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW,GAAG,UAAU,CAAC;IACrD,YAAY,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;IACpC,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;IAC7C,KAAK,IAAI,IAAI,CAAC;CACf;AAuCD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,wBAAyB,SAAQ,YAAa,YAAW,iBAAiB;IACrF,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAc;IAEtD,0CAA0C;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IAExD,qDAAqD;IACrD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAE1C,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAS;IAMjD,8DAA8D;IAC9D,OAAO,CAAC,eAAe,CAAM;IAE7B,yCAAyC;IACzC,OAAO,CAAC,YAAY,CAAS;IAE7B;;;OAGG;IACH,OAAO,CAAC,UAAU,CAA8C;IAEhE;;OAEG;IACH,OAAO,CAAC,YAAY,CAA8C;IAElE,wEAAwE;IACxE,OAAO,CAAC,WAAW,CAAuB;IAE1C,kEAAkE;IAClE,OAAO,CAAC,cAAc,CAAK;IAM3B;;;;OAIG;gBAED,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,EAC5C,MAAM,GAAE,sBAA2B;IAerC;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI;IAqBjD;;;;;;;;;;OAUG;IACH,YAAY,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IA2CnC;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAYb;;;;;;;;;OASG;IACH,OAAO,CAAC,gBAAgB;IAoCxB;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;IAgBzB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAOxB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAO1B;;OAEG;IACH,OAAO,CAAC,eAAe;CAIxB"}

package/dist/SemanticEndpointDetector.js

@@ -0,0 +1,308 @@
+/**
+ * @file SemanticEndpointDetector.ts
+ * @description IEndpointDetector implementation that combines the heuristic
+ * detector's punctuation and backchannel rules with LLM-based turn-completeness
+ * classification for ambiguous cases.
+ *
+ * Detection strategy (in priority order):
+ *  1. **Backchannel** — recognised phrases emitted as `backchannel_detected`
+ *     without advancing the turn.
+ *  2. **Terminal punctuation** — immediate `turn_complete` with reason
+ *     `'punctuation'`.
+ *  3. **LLM classification** — invoked after `minSilenceBeforeCheckMs` of
+ *     silence; `COMPLETE` fires `turn_complete` with reason `'semantic_model'`.
+ *     `INCOMPLETE` defers to the hard silence timeout.
+ *  4. **Silence timeout** — hard fallback after `silenceTimeoutMs`, reason
+ *     `'silence_timeout'`.
+ *
+ * @module endpoint-semantic/SemanticEndpointDetector
+ */
+import { EventEmitter } from 'node:events';
+import { TurnCompletenessClassifier } from './TurnCompletenessClassifier.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Default silence timeout (ms) — hard fallback if the LLM returns INCOMPLETE. */
+const DEFAULT_SILENCE_TIMEOUT_MS = 1_500;
+/** Default delay (ms) between speech_end and LLM invocation. */
+const DEFAULT_MIN_SILENCE_BEFORE_CHECK_MS = 500;
+/** Terminal punctuation that indicates sentence completion. */
+const TERMINAL_PUNCTUATION = /[.?!]$/;
+/**
+ * Normalised backchannel phrases that indicate acknowledgement without 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
+// ---------------------------------------------------------------------------
+/**
+ * Semantic endpoint detector that augments heuristic rules with LLM-based
+ * turn-completeness classification.
+ *
+ * ### Events emitted
+ * - `'turn_complete'` ({@link TurnCompleteEvent}) — user turn has ended.
+ * - `'backchannel_detected'` (`{ text: string }`) — backchannel phrase
+ *   recognised; accumulation suppressed.
+ *
+ * @example
+ * ```ts
+ * const detector = new SemanticEndpointDetector(
+ *   async (prompt) => callMyLLM(prompt),
+ *   { minSilenceBeforeCheckMs: 600, silenceTimeoutMs: 2000 }
+ * );
+ * detector.on('turn_complete', (e) => console.log(e.reason));
+ * ```
+ */
+export class SemanticEndpointDetector extends EventEmitter {
+    /** Active detection strategy label. */
+    mode = 'semantic';
+    /** LLM-backed completeness classifier. */
+    classifier;
+    /** Resolved silence timeout (ms) — hard fallback. */
+    silenceTimeoutMs;
+    /** Silence duration (ms) before invoking the LLM classifier. */
+    minSilenceBeforeCheckMs;
+    // ---------------------------------------------------------------------------
+    // Mutable state (reset on each turn)
+    // ---------------------------------------------------------------------------
+    /** Accumulated final transcript text for the current turn. */
+    accumulatedText = '';
+    /** Whether VAD reports active speech. */
+    speechActive = false;
+    /**
+     * Handle to the "check" timer — fires after `minSilenceBeforeCheckMs` and
+     * invokes the LLM classifier.
+     */
+    checkTimer = null;
+    /**
+     * Handle to the hard silence-timeout timer — fires after `silenceTimeoutMs`.
+     */
+    silenceTimer = null;
+    /** Wall-clock timestamp (ms) when speech began for the current turn. */
+    turnStartMs = null;
+    /** Confidence score from the most recent final STT transcript. */
+    lastConfidence = 1;
+    // ---------------------------------------------------------------------------
+    // Constructor
+    // ---------------------------------------------------------------------------
+    /**
+     * @param llmCall — Async function that sends a prompt to an LLM and resolves
+     *                  with the raw response text.
+     * @param config  — Optional configuration overrides.
+     */
+    constructor(llmCall, config = {}) {
+        super();
+        this.silenceTimeoutMs = config.silenceTimeoutMs ?? DEFAULT_SILENCE_TIMEOUT_MS;
+        this.minSilenceBeforeCheckMs =
+            config.minSilenceBeforeCheckMs ?? DEFAULT_MIN_SILENCE_BEFORE_CHECK_MS;
+        this.classifier = new TurnCompletenessClassifier(llmCall, config.timeoutMs);
+    }
+    // ---------------------------------------------------------------------------
+    // IEndpointDetector — pushTranscript
+    // ---------------------------------------------------------------------------
+    /**
+     * Ingest a transcript event from the upstream STT session.
+     *
+     * Only final events (`isFinal: true`) affect state. Interim results are
+     * silently ignored as they are unstable and arrive at high frequency.
+     *
+     * Recognised backchannel phrases are emitted as `'backchannel_detected'`
+     * without being accumulated, preventing a subsequent `speech_end` from
+     * triggering `turn_complete` for an acknowledgement.
+     *
+     * @param transcript — Transcript event from the upstream STT session.
+     */
+    pushTranscript(transcript) {
+        if (!transcript.isFinal) {
+            return;
+        }
+        const text = transcript.text;
+        const normalised = text.trim().toLowerCase();
+        if (BACKCHANNEL_PHRASES.has(normalised)) {
+            this.emit('backchannel_detected', { text });
+            return;
+        }
+        this.accumulatedText = text;
+        this.lastConfidence = transcript.confidence;
+    }
+    // ---------------------------------------------------------------------------
+    // IEndpointDetector — pushVadEvent
+    // ---------------------------------------------------------------------------
+    /**
+     * Ingest a VAD (voice activity detection) event.
+     *
+     * - `speech_start` — marks the turn as active, cancels pending timers.
+     * - `speech_end`   — if text has been accumulated, either fires immediately
+     *                    on terminal punctuation, or schedules the LLM check
+     *                    timer + hard silence-timeout timer.
+     * - `silence`      — periodic heartbeats; no action required.
+     *
+     * @param event — VAD transition event.
+     */
+    pushVadEvent(event) {
+        switch (event.type) {
+            case 'speech_start': {
+                this.speechActive = true;
+                this._clearAllTimers();
+                if (this.turnStartMs === null) {
+                    this.turnStartMs = event.timestamp;
+                }
+                break;
+            }
+            case 'speech_end': {
+                this.speechActive = false;
+                if (!this.accumulatedText) {
+                    // No transcript available yet — nothing to evaluate.
+                    break;
+                }
+                if (TERMINAL_PUNCTUATION.test(this.accumulatedText)) {
+                    // Sentence-terminal punctuation: fire immediately, identical to the
+                    // heuristic detector.
+                    this._emitTurnComplete('punctuation', event.timestamp);
+                    break;
+                }
+                // Ambiguous case: schedule the LLM check and the hard silence fallback.
+                this._startCheckTimer(event.timestamp);
+                this._startSilenceTimer(event.timestamp);
+                break;
+            }
+            case 'silence': {
+                // Periodic heartbeat — no action; timers already handle delayed firing.
+                break;
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // IEndpointDetector — reset
+    // ---------------------------------------------------------------------------
+    /**
+     * Cancel all pending timers and clear accumulated state so the detector is
+     * ready for the next turn.  Should be called by the pipeline after each
+     * `turn_complete` event.
+     */
+    reset() {
+        this._clearAllTimers();
+        this.accumulatedText = '';
+        this.speechActive = false;
+        this.turnStartMs = null;
+        this.lastConfidence = 1;
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Schedule the LLM completeness check after `minSilenceBeforeCheckMs`.
+     *
+     * If the LLM returns `COMPLETE`, `turn_complete` is emitted with reason
+     * `'semantic_model'` and both timers are cancelled.  If the LLM returns
+     * `INCOMPLETE` or `TIMEOUT`, the check timer is done and the hard silence
+     * timer (already running) continues as the fallback.
+     *
+     * @param speechEndTimestamp — Timestamp of the triggering `speech_end` event.
+     */
+    _startCheckTimer(speechEndTimestamp) {
+        this._clearCheckTimer();
+        // Capture state at scheduling time so async re-entrancy cannot corrupt it.
+        const transcriptSnapshot = this.accumulatedText;
+        this.checkTimer = setTimeout(async () => {
+            this.checkTimer = null;
+            // Guard: if the user resumed speaking before this timer fired, bail out.
+            if (this.speechActive || this.accumulatedText !== transcriptSnapshot) {
+                return;
+            }
+            let result;
+            try {
+                result = await this.classifier.classify(transcriptSnapshot);
+            }
+            catch {
+                // Unexpected classifier error — let the silence timer handle it.
+                return;
+            }
+            if (result === 'COMPLETE') {
+                // Cancel the hard silence timer — LLM beat it.
+                this._clearSilenceTimer();
+                // Another guard: state may have changed while we awaited the LLM.
+                if (this.accumulatedText === transcriptSnapshot && !this.speechActive) {
+                    this._emitTurnComplete('semantic_model', speechEndTimestamp);
+                }
+            }
+            // INCOMPLETE or TIMEOUT → do nothing; the hard silence timer continues.
+        }, this.minSilenceBeforeCheckMs);
+    }
+    /**
+     * Start the hard silence-timeout timer.  When it fires, `turn_complete` is
+     * emitted with reason `'silence_timeout'` regardless of the LLM result.
+     *
+     * @param speechEndTimestamp — Timestamp of the triggering `speech_end` event.
+     */
+    _startSilenceTimer(speechEndTimestamp) {
+        this._clearSilenceTimer();
+        this.silenceTimer = setTimeout(() => {
+            this.silenceTimer = null;
+            this._clearCheckTimer();
+            this._emitTurnComplete('silence_timeout', speechEndTimestamp);
+        }, this.silenceTimeoutMs);
+    }
+    /**
+     * Emit `turn_complete` with the currently accumulated transcript and reset
+     * internal state so the detector is clean for the next turn.
+     *
+     * State is reset **before** emitting so that re-entrant listeners see a
+     * clean detector.
+     *
+     * @param reason             — Semantic reason driving turn completion.
+     * @param speechEndTimestamp — Timestamp 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,
+        };
+        this.reset();
+        this.emit('turn_complete', event);
+    }
+    /**
+     * Cancel the LLM check timer without any other side effects.
+     */
+    _clearCheckTimer() {
+        if (this.checkTimer !== null) {
+            clearTimeout(this.checkTimer);
+            this.checkTimer = null;
+        }
+    }
+    /**
+     * Cancel the hard silence timer without any other side effects.
+     */
+    _clearSilenceTimer() {
+        if (this.silenceTimer !== null) {
+            clearTimeout(this.silenceTimer);
+            this.silenceTimer = null;
+        }
+    }
+    /**
+     * Cancel both the check timer and the silence timer.
+     */
+    _clearAllTimers() {
+        this._clearCheckTimer();
+        this._clearSilenceTimer();
+    }
+}
+//# sourceMappingURL=SemanticEndpointDetector.js.map

package/dist/SemanticEndpointDetector.js.map

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