@framers/agentos 0.1.108 → 0.1.109

package/dist/voice-pipeline/SoftFadeBargeinHandler.js

@@ -1,30 +1,72 @@
 /**
  * @module voice-pipeline/SoftFadeBargeinHandler
  *
- * Implements a three-tier soft-fade barge-in policy.
+ * Implements a three-tier soft-fade barge-in policy that maps detected speech
+ * duration to one of three actions: ignore, pause (with fade-out), or cancel.
  *
- * 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.
+ * ## Three-tier logic
+ *
+ * The handler divides the speech duration axis into three regions:
+ *
+ * ```
+ *   0 ms                ignoreMs              cancelMs
+ *   |-------- ignore --------|-------- pause --------|-------- cancel -------->
+ *          (noise)              (fade-out)              (hard stop)
+ * ```
+ *
+ * | Region                          | Action   | Rationale                                     |
+ * |---------------------------------|----------|-----------------------------------------------|
+ * | `speechDurationMs < ignoreMs`   | `ignore` | Too short to be intentional (noise, breath).  |
+ * | `ignoreMs <= speech < cancelMs` | `pause`  | Probably intentional; fade out gracefully.     |
+ * | `speechDurationMs >= cancelMs`  | `cancel` | Definitely intentional; stop immediately.      |
+ *
+ * ## Configurable thresholds
+ *
+ * - **`ignoreMs`** (default 100 ms): The noise floor. Anything shorter than
+ *   this is dismissed. Set lower in quiet environments, higher in noisy ones.
+ *
+ * - **`cancelMs`** (default 2,000 ms): The hard-stop ceiling. By this point,
+ *   the user has clearly been speaking for a while and wants to take over.
+ *   The pipeline should stop TTS immediately rather than fading.
+ *
+ * - **`fadeMs`** (default 200 ms): The duration of the audio fade-out applied
+ *   during a `'pause'` action. Shorter fades (100 ms) feel snappier; longer
+ *   fades (300+ ms) feel smoother but delay the user's ability to be heard.
+ *
+ * ## When to use soft-fade vs hard-cut
+ *
+ * Soft-fade is preferred when:
+ * - The environment is noisy and false barge-in detections are common.
+ * - The conversation is measured/educational and abrupt cuts feel jarring.
+ * - The TTS voice has long trailing prosody that benefits from a fade.
+ *
+ * Use {@link HardCutBargeinHandler} when:
+ * - The conversation is fast-paced (customer support, command interfaces).
+ * - Audio quality is high and false positives are rare.
+ * - Minimal interruption latency is critical.
+ *
+ * @see {@link HardCutBargeinHandler} for the binary hard-cut alternative.
+ * @see {@link IBargeinHandler} for the interface contract.
  */
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
 /**
  * Barge-in handler that applies a three-tier soft-fade strategy.
  *
- * The handler maps the confirmed speech duration to one of three actions:
+ * The handler is stateless -- each {@link handleBargein} call is evaluated
+ * independently with no memory of previous barge-in events.
  *
- * | Speech duration          | Action                                      |
- * |--------------------------|---------------------------------------------|
- * | `< ignoreMs`             | `ignore` — noise, continue TTS uninterrupted |
- * | `>= ignoreMs < cancelMs` | `pause` with `fadeMs` fade-out               |
- * | `>= cancelMs`            | `cancel` with `'[interrupted]'` marker       |
+ * @see {@link IBargeinHandler} for the interface contract.
+ * @see {@link HardCutBargeinHandler} for the binary hard-cut alternative.
  *
  * @example
- * ```ts
+ * ```typescript
  * 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' }
+ *
+ * handler.handleBargein({ speechDurationMs: 30, ... });   // -> { type: 'ignore' }
+ * handler.handleBargein({ speechDurationMs: 500, ... });  // -> { type: 'pause', fadeMs: 150 }
+ * handler.handleBargein({ speechDurationMs: 1600, ... }); // -> { type: 'cancel', injectMarker: '[interrupted]' }
  * ```
  */
 export class SoftFadeBargeinHandler {
@@ -37,7 +79,7 @@ export class SoftFadeBargeinHandler {
     constructor(options = {}) {
         /**
          * The interruption strategy implemented by this handler.
-         * Always `'soft-fade'`.
+         * Always `'soft-fade'` -- TTS audio is faded out over a configurable window.
          */
         this.mode = 'soft-fade';
         this.ignoreMs = options.ignoreMs ?? 100;
@@ -48,21 +90,33 @@ export class SoftFadeBargeinHandler {
      * 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 }`
+     *
+     * 1. `speechDurationMs < ignoreMs` -> `{ type: 'ignore' }`
+     *    Too short to be intentional. Likely a lip smack, breath, or noise burst.
+     *
+     * 2. `speechDurationMs >= cancelMs` -> `{ type: 'cancel', injectMarker: '[interrupted]' }`
+     *    The user has been speaking long enough that they clearly want to take over.
+     *    Stop TTS immediately and mark the conversation as interrupted.
+     *
+     * 3. Otherwise (ignoreMs <= speech < cancelMs) -> `{ type: 'pause', fadeMs }`
+     *    Probably intentional but not yet certain. Fade out TTS gracefully so the
+     *    user can be heard. If the speech stops, the pipeline can resume playback.
      *
      * @param context - Snapshot of the barge-in state at the moment of detection.
-     * @returns The pipeline action to execute.
+     * @returns The pipeline action to execute. Always synchronous (no Promise).
      */
     handleBargein(context) {
         const { speechDurationMs } = context;
+        // Tier 1: Noise floor -- dismiss as accidental
         if (speechDurationMs < this.ignoreMs) {
             return { type: 'ignore' };
         }
+        // Tier 3: Hard stop -- user has been speaking long enough to be certain.
+        // (Evaluated before Tier 2 to avoid the pause action for long speech.)
         if (speechDurationMs >= this.cancelMs) {
             return { type: 'cancel', injectMarker: '[interrupted]' };
         }
+        // Tier 2: Fade region -- probably intentional, fade out gracefully.
         return { type: 'pause', fadeMs: this.fadeMs };
     }
 }

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

@@ -1 +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"}
+{"version":3,"file":"SoftFadeBargeinHandler.js","sourceRoot":"","sources":["../../src/voice-pipeline/SoftFadeBargeinHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAqDH,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,sBAAsB;IAyBjC;;;;;OAKG;IACH,YAAY,UAAyC,EAAE;QA9BvD;;;WAGG;QACM,SAAI,GAAG,WAAoB,CAAC;QA2BnC,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;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,OAAuB;QACnC,MAAM,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC;QAErC,+CAA+C;QAC/C,IAAI,gBAAgB,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YACrC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QAC5B,CAAC;QAED,yEAAyE;QACzE,uEAAuE;QACvE,IAAI,gBAAgB,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACtC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,eAAe,EAAE,CAAC;QAC3D,CAAC;QAED,oEAAoE;QACpE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;IAChD,CAAC;CACF"}

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

@@ -3,45 +3,103 @@
  *
  * Typed error thrown when a voice session is interrupted by user barge-in.
  * Used by VoiceNodeExecutor to catch barge-in AbortSignal and return
- * a structured result instead of propagating the error.
+ * a structured result instead of propagating a generic Error.
+ *
+ * ## Design rationale
+ *
+ * Using a typed error subclass (rather than a plain Error with a message string)
+ * allows consumers to:
+ * 1. Catch specifically via `instanceof VoiceInterruptError`.
+ * 2. Access structured fields ({@link interruptedText}, {@link userSpeech},
+ *    {@link playedDurationMs}) without parsing an error message.
+ * 3. Distinguish barge-in interruptions from other pipeline errors in
+ *    catch blocks and error boundaries.
+ *
+ * The `name` property is set as a class field (not via the prototype) so that
+ * it survives serialisation and can be used for `instanceof`-free checks when
+ * errors cross process boundaries (e.g. worker threads, RPC).
  */
 /**
  * Structured error representing a user barge-in interruption during TTS playback.
  *
  * Thrown (or returned as a typed sentinel) when the user speaks over the agent.
- * Consumers can inspect `interruptedText`, `userSpeech`, and `playedDurationMs`
- * to decide how to resume or branch the conversation graph.
+ * Consumers can inspect {@link interruptedText}, {@link userSpeech}, and
+ * {@link playedDurationMs} to decide how to resume or branch the conversation graph.
+ *
+ * @see {@link IBargeinHandler} which triggers the barge-in decision.
+ * @see {@link VoicePipelineOrchestrator} which transitions through INTERRUPTING state.
  *
- * @example
+ * @example Catching a barge-in interruption
  * ```typescript
  * try {
  *   await voiceNode.run(context);
  * } catch (err) {
  *   if (err instanceof VoiceInterruptError) {
- *     console.log(`Interrupted after ${err.playedDurationMs}ms`);
+ *     console.log(`Agent was saying: "${err.interruptedText}"`);
+ *     console.log(`User said: "${err.userSpeech}"`);
+ *     console.log(`Played ${err.playedDurationMs}ms before interruption`);
+ *     // Resume conversation from the user's barge-in utterance
  *     await handleBargein(err.userSpeech);
+ *   } else {
+ *     throw err; // Re-throw non-barge-in errors
  *   }
  * }
  * ```
+ *
+ * @example Checking without instanceof (e.g. cross-process)
+ * ```typescript
+ * if (error.name === 'VoiceInterruptError') {
+ *   // Safe to access barge-in fields
+ * }
+ * ```
  */
 export declare class VoiceInterruptError extends Error {
-    /** Discriminant name — always `'VoiceInterruptError'` for `instanceof`-free checks. */
+    /**
+     * Discriminant name -- always `'VoiceInterruptError'`.
+     *
+     * Set as a class field (not via prototype) so it:
+     * - Survives JSON serialisation/deserialisation.
+     * - Can be used for `instanceof`-free type discrimination.
+     * - Overrides the default `Error` name in stack traces.
+     */
     readonly name = "VoiceInterruptError";
-    /** The text the agent was speaking when interrupted. */
+    /**
+     * The full text the agent was speaking when interrupted.
+     * Corresponds to the cumulative TTS text accumulated by the orchestrator
+     * at the point of barge-in detection.
+     */
     readonly interruptedText: string;
-    /** What the user said that caused the interruption. */
+    /**
+     * What the user said that caused the interruption.
+     * Typically the partial or final STT transcript captured during the
+     * barge-in speech detection.
+     */
     readonly userSpeech: string;
     /**
      * How much of the agent's response was already played (ms).
-     * Derived from the cumulative `durationMs` of `EncodedAudioChunk`s sent
-     * to the transport before the barge-in was detected.
+     * Derived from the cumulative `durationMs` of {@link EncodedAudioChunk}s
+     * sent to the transport before the barge-in was detected.
+     *
+     * Combined with {@link interruptedText}, this allows the consumer to
+     * estimate how much of the response the user actually heard.
      */
     readonly playedDurationMs: number;
     /**
+     * Create a new VoiceInterruptError with structured barge-in context.
+     *
      * @param context - Barge-in context captured at the moment of interruption.
      * @param context.interruptedText - Full TTS text the agent was speaking.
      * @param context.userSpeech - Transcript of the user's barge-in utterance.
      * @param context.playedDurationMs - Milliseconds of audio already played.
+     *
+     * @example
+     * ```typescript
+     * throw new VoiceInterruptError({
+     *   interruptedText: 'I was explaining the process of...',
+     *   userSpeech: 'Wait, go back to the first step.',
+     *   playedDurationMs: 2300,
+     * });
+     * ```
      */
     constructor(context: {
         interruptedText: string;

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

@@ -1 +1 @@
-{"version":3,"file":"VoiceInterruptError.d.ts","sourceRoot":"","sources":["../../src/voice-pipeline/VoiceInterruptError.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,uFAAuF;IACvF,QAAQ,CAAC,IAAI,yBAAyB;IAEtC,wDAAwD;IACxD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAEjC,uDAAuD;IACvD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAElC;;;;;OAKG;gBACS,OAAO,EAAE;QACnB,eAAe,EAAE,MAAM,CAAC;QACxB,UAAU,EAAE,MAAM,CAAC;QACnB,gBAAgB,EAAE,MAAM,CAAC;KAC1B;CAMF"}
+{"version":3,"file":"VoiceInterruptError.d.ts","sourceRoot":"","sources":["../../src/voice-pipeline/VoiceInterruptError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,yBAAyB;IAEtC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAEjC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAElC;;;;;;;;;;;;;;;;OAgBG;gBACS,OAAO,EAAE;QACnB,eAAe,EAAE,MAAM,CAAC;QACxB,UAAU,EAAE,MAAM,CAAC;QACnB,gBAAgB,EAAE,MAAM,CAAC;KAC1B;CAMF"}

package/dist/voice-pipeline/VoiceInterruptError.js

@@ -3,37 +3,84 @@
  *
  * Typed error thrown when a voice session is interrupted by user barge-in.
  * Used by VoiceNodeExecutor to catch barge-in AbortSignal and return
- * a structured result instead of propagating the error.
+ * a structured result instead of propagating a generic Error.
+ *
+ * ## Design rationale
+ *
+ * Using a typed error subclass (rather than a plain Error with a message string)
+ * allows consumers to:
+ * 1. Catch specifically via `instanceof VoiceInterruptError`.
+ * 2. Access structured fields ({@link interruptedText}, {@link userSpeech},
+ *    {@link playedDurationMs}) without parsing an error message.
+ * 3. Distinguish barge-in interruptions from other pipeline errors in
+ *    catch blocks and error boundaries.
+ *
+ * The `name` property is set as a class field (not via the prototype) so that
+ * it survives serialisation and can be used for `instanceof`-free checks when
+ * errors cross process boundaries (e.g. worker threads, RPC).
  */
 /**
  * Structured error representing a user barge-in interruption during TTS playback.
  *
  * Thrown (or returned as a typed sentinel) when the user speaks over the agent.
- * Consumers can inspect `interruptedText`, `userSpeech`, and `playedDurationMs`
- * to decide how to resume or branch the conversation graph.
+ * Consumers can inspect {@link interruptedText}, {@link userSpeech}, and
+ * {@link playedDurationMs} to decide how to resume or branch the conversation graph.
+ *
+ * @see {@link IBargeinHandler} which triggers the barge-in decision.
+ * @see {@link VoicePipelineOrchestrator} which transitions through INTERRUPTING state.
  *
- * @example
+ * @example Catching a barge-in interruption
  * ```typescript
  * try {
  *   await voiceNode.run(context);
  * } catch (err) {
  *   if (err instanceof VoiceInterruptError) {
- *     console.log(`Interrupted after ${err.playedDurationMs}ms`);
+ *     console.log(`Agent was saying: "${err.interruptedText}"`);
+ *     console.log(`User said: "${err.userSpeech}"`);
+ *     console.log(`Played ${err.playedDurationMs}ms before interruption`);
+ *     // Resume conversation from the user's barge-in utterance
  *     await handleBargein(err.userSpeech);
+ *   } else {
+ *     throw err; // Re-throw non-barge-in errors
  *   }
  * }
  * ```
+ *
+ * @example Checking without instanceof (e.g. cross-process)
+ * ```typescript
+ * if (error.name === 'VoiceInterruptError') {
+ *   // Safe to access barge-in fields
+ * }
+ * ```
  */
 export class VoiceInterruptError extends Error {
     /**
+     * Create a new VoiceInterruptError with structured barge-in context.
+     *
      * @param context - Barge-in context captured at the moment of interruption.
      * @param context.interruptedText - Full TTS text the agent was speaking.
      * @param context.userSpeech - Transcript of the user's barge-in utterance.
      * @param context.playedDurationMs - Milliseconds of audio already played.
+     *
+     * @example
+     * ```typescript
+     * throw new VoiceInterruptError({
+     *   interruptedText: 'I was explaining the process of...',
+     *   userSpeech: 'Wait, go back to the first step.',
+     *   playedDurationMs: 2300,
+     * });
+     * ```
      */
     constructor(context) {
         super('Voice session interrupted by user');
-        /** Discriminant name — always `'VoiceInterruptError'` for `instanceof`-free checks. */
+        /**
+         * Discriminant name -- always `'VoiceInterruptError'`.
+         *
+         * Set as a class field (not via prototype) so it:
+         * - Survives JSON serialisation/deserialisation.
+         * - Can be used for `instanceof`-free type discrimination.
+         * - Overrides the default `Error` name in stack traces.
+         */
         this.name = 'VoiceInterruptError';
         this.interruptedText = context.interruptedText;
         this.userSpeech = context.userSpeech;

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

@@ -1 +1 @@
-{"version":3,"file":"VoiceInterruptError.js","sourceRoot":"","sources":["../../src/voice-pipeline/VoiceInterruptError.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAiB5C;;;;;OAKG;IACH,YAAY,OAIX;QACC,KAAK,CAAC,mCAAmC,CAAC,CAAC;QA3B7C,uFAAuF;QAC9E,SAAI,GAAG,qBAAqB,CAAC;QA2BpC,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;QAC/C,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IACnD,CAAC;CACF"}
+{"version":3,"file":"VoiceInterruptError.js","sourceRoot":"","sources":["../../src/voice-pipeline/VoiceInterruptError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAmC5C;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,OAIX;QACC,KAAK,CAAC,mCAAmC,CAAC,CAAC;QAxD7C;;;;;;;WAOG;QACM,SAAI,GAAG,qBAAqB,CAAC;QAiDpC,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;QAC/C,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IACnD,CAAC;CACF"}