@framers/agentos 0.1.107 → 0.1.109

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

@@ -6,46 +6,105 @@
  * as Float32Array audio frames; text messages are parsed as
  * {@link ClientTextMessage} control envelopes.
  *
- * The transport is intentionally transport-agnostic: it accepts any object that
- * exposes the `ws` package's `WebSocket` interface (readyState, send, close, and
- * the standard event emitter surface). This makes it trivially testable with a
- * plain `EventEmitter` mock.
+ * ## Wire protocol
+ *
+ * ### Binary frames (inbound)
+ * Every binary WebSocket message is interpreted as a raw Float32Array of PCM
+ * samples. The sender (browser/client) must transmit audio as a `Float32Array`
+ * view serialised to its underlying `ArrayBuffer`. The transport reconstructs
+ * the `Float32Array` from the received `Buffer`, using `byteOffset` and
+ * `byteLength` to handle sliced buffers correctly.
+ *
+ * ### Text frames (inbound)
+ * Every text WebSocket message must be valid JSON conforming to
+ * {@link ClientTextMessage}. Malformed JSON emits an `'error'` event but does
+ * not crash the transport, allowing the session to continue.
+ *
+ * ### Binary frames (outbound)
+ * {@link sendAudio} sends the raw `Buffer` from an {@link EncodedAudioChunk}
+ * (or converts a `Float32Array` to a `Buffer` for raw {@link AudioFrame}s).
+ *
+ * ### Text frames (outbound)
+ * {@link sendControl} JSON-stringifies a {@link ServerTextMessage} and sends
+ * it as a text frame.
+ *
+ * ## Reconnection behaviour
+ * This transport does NOT implement automatic reconnection. If the underlying
+ * WebSocket closes, the transport transitions to `'closed'` and emits
+ * `'disconnected'`. The consumer (typically the orchestrator) is responsible
+ * for creating a new transport and session if reconnection is desired.
+ *
+ * ## Transport-agnostic design
+ * The transport accepts any object satisfying {@link WebSocketLike}, which is
+ * a minimal subset of the `ws` package's `WebSocket` interface. This makes it
+ * trivially testable with a plain `EventEmitter` mock and compatible with
+ * browser-style WebSocket polyfills.
  */
 import { EventEmitter } from 'node:events';
 import type { IStreamTransport, AudioFrame, EncodedAudioChunk, TransportControlMessage, ServerTextMessage } from './types.js';
 /**
  * Subset of the WebSocket API required by {@link WebSocketStreamTransport}.
  * Both the `ws` npm package and the browser's native WebSocket satisfy this.
+ *
+ * By depending on this minimal interface rather than the full `ws.WebSocket`
+ * type, the transport avoids a hard dependency on any specific WebSocket
+ * library and remains easily mockable in tests.
+ *
+ * @see {@link WebSocketStreamTransport} which consumes this interface.
  */
 export interface WebSocketLike extends NodeJS.EventEmitter {
-    /** WebSocket ready-state constant for the OPEN state (= 1). */
+    /**
+     * WebSocket ready-state constant for the OPEN state.
+     * In the `ws` package this is `1`; in browsers it is also `1`.
+     * Optional because some mock implementations may not define it.
+     */
     readonly OPEN?: number;
-    /** WebSocket ready-state constant for the CLOSED state (= 3). */
+    /**
+     * WebSocket ready-state constant for the CLOSED state.
+     * In the `ws` package this is `3`.
+     * Optional because some mock implementations may not define it.
+     */
     readonly CLOSED?: number;
-    /** Current ready state of the socket. */
+    /**
+     * Current ready state of the socket.
+     * - `0` = CONNECTING
+     * - `1` = OPEN
+     * - `2` = CLOSING
+     * - `3` = CLOSED
+     */
     readonly readyState: number;
     /**
      * Send data over the socket.
      *
-     * @param data — Binary `Buffer` or text `string` payload.
-     * @param cb — Optional completion callback used by the `ws` library.
+     * @param data - Binary `Buffer` or text `string` payload.
+     * @param cb - Optional completion callback used by the `ws` library.
+     *   The callback receives an optional `Error` if the send fails.
      */
     send(data: Buffer | string, cb?: (err?: Error) => void): void;
     /**
      * Initiate a graceful close handshake.
      *
-     * @param code — Optional numeric close code (default 1000).
-     * @param reason — Optional human-readable reason string.
+     * @param code - Optional numeric close code (default 1000 = normal closure).
+     * @param reason - Optional human-readable reason string.
      */
     close(code?: number, reason?: string): void;
 }
 /**
  * Constructor options for {@link WebSocketStreamTransport}.
+ *
+ * @example
+ * ```typescript
+ * const config: WebSocketStreamTransportConfig = { sampleRate: 16000 };
+ * const transport = new WebSocketStreamTransport(ws, config);
+ * ```
  */
 export interface WebSocketStreamTransportConfig {
     /**
      * Sample rate (in Hz) used to populate {@link AudioFrame.sampleRate} on
      * inbound binary messages. Must match the rate the remote client is sending.
+     *
+     * Common values: 16000 (telephony/STT), 24000 (TTS output), 48000 (high-fidelity).
+     *
      * @example 16000
      */
     sampleRate: number;
@@ -53,39 +112,64 @@ export interface WebSocketStreamTransportConfig {
 /**
  * Bidirectional voice pipeline transport backed by a WebSocket connection.
  *
- * ### Inbound wire format
- * - **Binary frame** → decoded as a `Float32Array` view, wrapped in an
- *   {@link AudioFrame}, and re-emitted as `'audio_frame'`.
- * - **Text frame** → `JSON.parse()`d and re-emitted as `'control'` carrying
- *   the raw {@link ClientTextMessage} object.
+ * ## Inbound wire format
+ *
+ * | Frame type | Processing                                                |
+ * |------------|-----------------------------------------------------------|
+ * | Binary     | Decoded as `Float32Array` PCM samples, wrapped in an {@link AudioFrame}, emitted as `'audio_frame'`. |
+ * | Text       | `JSON.parse()`d as {@link ClientTextMessage}, emitted as `'control'`. |
+ *
+ * ## Outbound API
+ *
+ * | Method          | Behaviour                                              |
+ * |-----------------|--------------------------------------------------------|
+ * | {@link sendAudio}   | Serialises audio to a binary `Buffer` and calls `ws.send()`. |
+ * | {@link sendControl} | JSON-stringifies the message and calls `ws.send()`.    |
  *
- * ### Outbound API
- * - {@link sendAudio} — serialises an {@link EncodedAudioChunk} or
- *   {@link AudioFrame} to a binary `Buffer` and calls `ws.send()`.
- * - {@link sendControl} — JSON-stringifies a {@link TransportControlMessage}
- *   or {@link ServerTextMessage} and calls `ws.send()`.
+ * ## Lifecycle events (re-emitted on `this`)
  *
- * ### Lifecycle events (re-emitted on `this`)
  * | WS event | Transport emission |
  * |----------|--------------------|
  * | `open`   | `'connected'`      |
  * | `close`  | `'disconnected'`   |
  * | `error`  | `'error'`          |
  *
- * @fires audio_frame — `(frame: AudioFrame)` for every inbound binary message.
- * @fires control — `(msg: ClientTextMessage)` for every inbound text message.
- * @fires connected — Socket transitioned to OPEN state.
- * @fires disconnected — Socket has been fully closed.
- * @fires error — Socket-level error occurred.
+ * @fires audio_frame - `(frame: AudioFrame)` for every inbound binary message.
+ * @fires control - `(msg: ClientTextMessage)` for every inbound text message.
+ * @fires connected - Socket transitioned to OPEN state.
+ * @fires disconnected - Socket has been fully closed.
+ * @fires error - Socket-level error occurred.
+ *
+ * @see {@link IStreamTransport} for the interface contract.
+ * @see {@link VoicePipelineOrchestrator} which consumes this transport.
+ *
+ * @example
+ * ```typescript
+ * import WebSocket from 'ws';
+ * const ws = new WebSocket('ws://localhost:8080/voice');
+ * const transport = new WebSocketStreamTransport(ws, { sampleRate: 16000 });
+ *
+ * transport.on('audio_frame', (frame) => sttSession.pushAudio(frame));
+ * transport.on('control', (msg) => handleClientMessage(msg));
+ * ```
  */
 export declare class WebSocketStreamTransport extends EventEmitter implements IStreamTransport {
-    /** Stable UUID assigned at construction time. */
+    /**
+     * Stable UUID assigned at construction time.
+     * Used as a correlation key in logs and metrics.
+     */
     readonly id: string;
-    /** Current connection state. Updated in response to WebSocket events. */
+    /**
+     * Current connection state. Updated internally by WebSocket event handlers.
+     * Read externally via the {@link state} getter.
+     */
     private _state;
     /** The underlying WebSocket connection. */
     private readonly _ws;
-    /** Audio sample rate propagated into every decoded {@link AudioFrame}. */
+    /**
+     * Audio sample rate propagated into every decoded {@link AudioFrame}.
+     * Configured once at construction and never changed.
+     */
     private readonly _sampleRate;
     /**
      * Create a new transport wrapping an existing WebSocket connection.
@@ -95,8 +179,8 @@ export declare class WebSocketStreamTransport extends EventEmitter implements IS
      * is set to `'open'`; otherwise it is set to `'connecting'` and will
      * transition to `'open'` when the `'open'` event fires.
      *
-     * @param ws — WebSocket connection (or compatible mock).
-     * @param config — Transport-level configuration.
+     * @param ws - WebSocket connection (or compatible mock).
+     * @param config - Transport-level configuration (must include sampleRate).
      */
     constructor(ws: WebSocketLike, config: WebSocketStreamTransportConfig);
     /**
@@ -107,13 +191,15 @@ export declare class WebSocketStreamTransport extends EventEmitter implements IS
     /**
      * Send a synthesised audio chunk to the remote client for playback.
      *
-     * If `chunk` carries an {@link EncodedAudioChunk} (has an `audio` Buffer
-     * property), that buffer is sent directly. If it carries an {@link AudioFrame}
-     * (has a `samples` Float32Array), the samples are copied into a new `Buffer`
-     * and sent.
+     * If the payload is an {@link EncodedAudioChunk} (has an `audio` Buffer
+     * property), that buffer is sent directly as a binary frame. If it is an
+     * {@link AudioFrame} (has a `samples` Float32Array), the samples are copied
+     * into a new `Buffer` and sent.
      *
-     * @param chunk — Encoded audio chunk or raw PCM frame to deliver.
+     * @param chunk - Encoded audio chunk or raw PCM frame to deliver.
      * @returns Resolves once the data has been handed to the OS socket buffer.
+     *
+     * @throws {Error} If the underlying `ws.send()` fails (e.g. socket closed).
      */
     sendAudio(chunk: EncodedAudioChunk | AudioFrame): Promise<void>;
     /**
@@ -123,8 +209,10 @@ export declare class WebSocketStreamTransport extends EventEmitter implements IS
      * {@link TransportControlMessage} and {@link ServerTextMessage} are accepted
      * since they share the same serialisation path.
      *
-     * @param msg — Server-side protocol message.
+     * @param msg - Server-side protocol message.
      * @returns Resolves once the message has been handed to the OS socket buffer.
+     *
+     * @throws {Error} If the underlying `ws.send()` fails (e.g. socket closed).
      */
     sendControl(msg: TransportControlMessage | ServerTextMessage): Promise<void>;
     /**
@@ -134,14 +222,18 @@ export declare class WebSocketStreamTransport extends EventEmitter implements IS
      * underlying WebSocket's `close()` method. The `'disconnected'` event will
      * fire once the socket's `'close'` event is received.
      *
-     * @param code — Optional numeric WebSocket close code (default 1000).
-     * @param reason — Optional human-readable close reason.
+     * @param code - Optional numeric WebSocket close code (default 1000 = normal closure).
+     * @param reason - Optional human-readable close reason.
      */
     close(code?: number, reason?: string): void;
     /**
-     * Attach listeners to the underlying WebSocket for the events that matter to
-     * the voice pipeline. All listener state is contained here; no cleanup method
-     * is currently needed since the transport's lifetime is tied to the socket's.
+     * Attach listeners to the underlying WebSocket for all events relevant to
+     * the voice pipeline.
+     *
+     * All listener state is contained here. No cleanup method is currently
+     * needed because the transport's lifetime is tied to the socket's --
+     * when the socket closes, the transport transitions to `'closed'` and
+     * no further events are expected.
      */
     private _attachWsListeners;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"WebSocketStreamTransport.d.ts","sourceRoot":"","sources":["../../src/voice-pipeline/WebSocketStreamTransport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EACV,gBAAgB,EAChB,UAAU,EACV,iBAAiB,EACjB,uBAAuB,EAEvB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAOpB;;;GAGG;AACH,MAAM,WAAW,aAAc,SAAQ,MAAM,CAAC,YAAY;IACxD,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;IAC9D;;;;;OAKG;IACH,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7C;AAMD;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,wBAAyB,SAAQ,YAAa,YAAW,gBAAgB;IAKpF,iDAAiD;IACjD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,yEAAyE;IACzE,OAAO,CAAC,MAAM,CAA+C;IAM7D,2CAA2C;IAC3C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAgB;IAEpC,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAMrC;;;;;;;;;;OAUG;gBACS,EAAE,EAAE,aAAa,EAAE,MAAM,EAAE,8BAA8B;IAkBrE;;;OAGG;IACH,IAAI,KAAK,IAAI,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAExD;IAED;;;;;;;;;;OAUG;IACH,SAAS,CAAC,KAAK,EAAE,iBAAiB,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAwB/D;;;;;;;;;OASG;IACH,WAAW,CAAC,GAAG,EAAE,uBAAuB,GAAG,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAS5E;;;;;;;;;OASG;IACH,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAS3C;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;CAyD3B"}
+{"version":3,"file":"WebSocketStreamTransport.d.ts","sourceRoot":"","sources":["../../src/voice-pipeline/WebSocketStreamTransport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EACV,gBAAgB,EAChB,UAAU,EACV,iBAAiB,EACjB,uBAAuB,EAEvB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAMpB;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAc,SAAQ,MAAM,CAAC,YAAY;IACxD;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;;;;OAMG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;IAE9D;;;;;OAKG;IACH,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7C;AAMD;;;;;;;;GAQG;AACH,MAAM,WAAW,8BAA8B;IAC7C;;;;;;;OAOG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,wBAAyB,SAAQ,YAAa,YAAW,gBAAgB;IAKpF;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAA+C;IAM7D,2CAA2C;IAC3C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAgB;IAEpC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAMrC;;;;;;;;;;OAUG;gBACS,EAAE,EAAE,aAAa,EAAE,MAAM,EAAE,8BAA8B;IAmBrE;;;OAGG;IACH,IAAI,KAAK,IAAI,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAExD;IAED;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,KAAK,EAAE,iBAAiB,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA0B/D;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,GAAG,EAAE,uBAAuB,GAAG,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAS5E;;;;;;;;;OASG;IACH,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAS3C;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;CAoE3B"}

package/dist/voice-pipeline/WebSocketStreamTransport.js

@@ -6,10 +6,39 @@
  * as Float32Array audio frames; text messages are parsed as
  * {@link ClientTextMessage} control envelopes.
  *
- * The transport is intentionally transport-agnostic: it accepts any object that
- * exposes the `ws` package's `WebSocket` interface (readyState, send, close, and
- * the standard event emitter surface). This makes it trivially testable with a
- * plain `EventEmitter` mock.
+ * ## Wire protocol
+ *
+ * ### Binary frames (inbound)
+ * Every binary WebSocket message is interpreted as a raw Float32Array of PCM
+ * samples. The sender (browser/client) must transmit audio as a `Float32Array`
+ * view serialised to its underlying `ArrayBuffer`. The transport reconstructs
+ * the `Float32Array` from the received `Buffer`, using `byteOffset` and
+ * `byteLength` to handle sliced buffers correctly.
+ *
+ * ### Text frames (inbound)
+ * Every text WebSocket message must be valid JSON conforming to
+ * {@link ClientTextMessage}. Malformed JSON emits an `'error'` event but does
+ * not crash the transport, allowing the session to continue.
+ *
+ * ### Binary frames (outbound)
+ * {@link sendAudio} sends the raw `Buffer` from an {@link EncodedAudioChunk}
+ * (or converts a `Float32Array` to a `Buffer` for raw {@link AudioFrame}s).
+ *
+ * ### Text frames (outbound)
+ * {@link sendControl} JSON-stringifies a {@link ServerTextMessage} and sends
+ * it as a text frame.
+ *
+ * ## Reconnection behaviour
+ * This transport does NOT implement automatic reconnection. If the underlying
+ * WebSocket closes, the transport transitions to `'closed'` and emits
+ * `'disconnected'`. The consumer (typically the orchestrator) is responsible
+ * for creating a new transport and session if reconnection is desired.
+ *
+ * ## Transport-agnostic design
+ * The transport accepts any object satisfying {@link WebSocketLike}, which is
+ * a minimal subset of the `ws` package's `WebSocket` interface. This makes it
+ * trivially testable with a plain `EventEmitter` mock and compatible with
+ * browser-style WebSocket polyfills.
  */
 import { EventEmitter } from 'node:events';
 import { randomUUID } from 'node:crypto';
@@ -19,30 +48,46 @@ import { randomUUID } from 'node:crypto';
 /**
  * Bidirectional voice pipeline transport backed by a WebSocket connection.
  *
- * ### Inbound wire format
- * - **Binary frame** → decoded as a `Float32Array` view, wrapped in an
- *   {@link AudioFrame}, and re-emitted as `'audio_frame'`.
- * - **Text frame** → `JSON.parse()`d and re-emitted as `'control'` carrying
- *   the raw {@link ClientTextMessage} object.
+ * ## Inbound wire format
+ *
+ * | Frame type | Processing                                                |
+ * |------------|-----------------------------------------------------------|
+ * | Binary     | Decoded as `Float32Array` PCM samples, wrapped in an {@link AudioFrame}, emitted as `'audio_frame'`. |
+ * | Text       | `JSON.parse()`d as {@link ClientTextMessage}, emitted as `'control'`. |
+ *
+ * ## Outbound API
  *
- * ### Outbound API
- * - {@link sendAudio} — serialises an {@link EncodedAudioChunk} or
- *   {@link AudioFrame} to a binary `Buffer` and calls `ws.send()`.
- * - {@link sendControl} — JSON-stringifies a {@link TransportControlMessage}
- *   or {@link ServerTextMessage} and calls `ws.send()`.
+ * | Method          | Behaviour                                              |
+ * |-----------------|--------------------------------------------------------|
+ * | {@link sendAudio}   | Serialises audio to a binary `Buffer` and calls `ws.send()`. |
+ * | {@link sendControl} | JSON-stringifies the message and calls `ws.send()`.    |
+ *
+ * ## Lifecycle events (re-emitted on `this`)
  *
- * ### Lifecycle events (re-emitted on `this`)
  * | WS event | Transport emission |
  * |----------|--------------------|
  * | `open`   | `'connected'`      |
  * | `close`  | `'disconnected'`   |
  * | `error`  | `'error'`          |
  *
- * @fires audio_frame — `(frame: AudioFrame)` for every inbound binary message.
- * @fires control — `(msg: ClientTextMessage)` for every inbound text message.
- * @fires connected — Socket transitioned to OPEN state.
- * @fires disconnected — Socket has been fully closed.
- * @fires error — Socket-level error occurred.
+ * @fires audio_frame - `(frame: AudioFrame)` for every inbound binary message.
+ * @fires control - `(msg: ClientTextMessage)` for every inbound text message.
+ * @fires connected - Socket transitioned to OPEN state.
+ * @fires disconnected - Socket has been fully closed.
+ * @fires error - Socket-level error occurred.
+ *
+ * @see {@link IStreamTransport} for the interface contract.
+ * @see {@link VoicePipelineOrchestrator} which consumes this transport.
+ *
+ * @example
+ * ```typescript
+ * import WebSocket from 'ws';
+ * const ws = new WebSocket('ws://localhost:8080/voice');
+ * const transport = new WebSocketStreamTransport(ws, { sampleRate: 16000 });
+ *
+ * transport.on('audio_frame', (frame) => sttSession.pushAudio(frame));
+ * transport.on('control', (msg) => handleClientMessage(msg));
+ * ```
  */
 export class WebSocketStreamTransport extends EventEmitter {
     // -------------------------------------------------------------------------
@@ -56,8 +101,8 @@ export class WebSocketStreamTransport extends EventEmitter {
      * is set to `'open'`; otherwise it is set to `'connecting'` and will
      * transition to `'open'` when the `'open'` event fires.
      *
-     * @param ws — WebSocket connection (or compatible mock).
-     * @param config — Transport-level configuration.
+     * @param ws - WebSocket connection (or compatible mock).
+     * @param config - Transport-level configuration (must include sampleRate).
      */
     constructor(ws, config) {
         super();
@@ -65,13 +110,14 @@ export class WebSocketStreamTransport extends EventEmitter {
         this._sampleRate = config.sampleRate;
         this.id = randomUUID();
         // Determine initial state from the socket's current ready-state value.
-        // The `ws` package uses numeric constants; OPEN = 1, CLOSED = 3.
+        // The `ws` package uses numeric constants: OPEN = 1, CLOSED = 3.
+        // We default to 1 if the OPEN constant is not defined (e.g. in mocks).
         const OPEN_STATE = ws.OPEN ?? 1;
         this._state = ws.readyState === OPEN_STATE ? 'open' : 'connecting';
         this._attachWsListeners();
     }
     // -------------------------------------------------------------------------
-    // IStreamTransport — public surface
+    // IStreamTransport -- public surface
     // -------------------------------------------------------------------------
     /**
      * Current connection state of the underlying WebSocket.
@@ -83,23 +129,27 @@ export class WebSocketStreamTransport extends EventEmitter {
     /**
      * Send a synthesised audio chunk to the remote client for playback.
      *
-     * If `chunk` carries an {@link EncodedAudioChunk} (has an `audio` Buffer
-     * property), that buffer is sent directly. If it carries an {@link AudioFrame}
-     * (has a `samples` Float32Array), the samples are copied into a new `Buffer`
-     * and sent.
+     * If the payload is an {@link EncodedAudioChunk} (has an `audio` Buffer
+     * property), that buffer is sent directly as a binary frame. If it is an
+     * {@link AudioFrame} (has a `samples` Float32Array), the samples are copied
+     * into a new `Buffer` and sent.
      *
-     * @param chunk — Encoded audio chunk or raw PCM frame to deliver.
+     * @param chunk - Encoded audio chunk or raw PCM frame to deliver.
      * @returns Resolves once the data has been handed to the OS socket buffer.
+     *
+     * @throws {Error} If the underlying `ws.send()` fails (e.g. socket closed).
      */
     sendAudio(chunk) {
         return new Promise((resolve, reject) => {
             let binary;
             if ('audio' in chunk) {
-                // EncodedAudioChunk — already a Buffer
+                // EncodedAudioChunk path: the audio property is already a Buffer
                 binary = chunk.audio;
             }
             else {
-                // AudioFrame — convert Float32Array samples to a byte Buffer
+                // AudioFrame path: convert Float32Array samples to a raw byte Buffer.
+                // We must use byteOffset and byteLength because the Float32Array may
+                // be a view into a larger SharedArrayBuffer or sliced Buffer.
                 const frame = chunk;
                 binary = Buffer.from(frame.samples.buffer, frame.samples.byteOffset, frame.samples.byteLength);
             }
@@ -118,8 +168,10 @@ export class WebSocketStreamTransport extends EventEmitter {
      * {@link TransportControlMessage} and {@link ServerTextMessage} are accepted
      * since they share the same serialisation path.
      *
-     * @param msg — Server-side protocol message.
+     * @param msg - Server-side protocol message.
      * @returns Resolves once the message has been handed to the OS socket buffer.
+     *
+     * @throws {Error} If the underlying `ws.send()` fails (e.g. socket closed).
      */
     sendControl(msg) {
         return new Promise((resolve, reject) => {
@@ -138,8 +190,8 @@ export class WebSocketStreamTransport extends EventEmitter {
      * underlying WebSocket's `close()` method. The `'disconnected'` event will
      * fire once the socket's `'close'` event is received.
      *
-     * @param code — Optional numeric WebSocket close code (default 1000).
-     * @param reason — Optional human-readable close reason.
+     * @param code - Optional numeric WebSocket close code (default 1000 = normal closure).
+     * @param reason - Optional human-readable close reason.
      */
     close(code, reason) {
         this._state = 'closing';
@@ -149,36 +201,45 @@ export class WebSocketStreamTransport extends EventEmitter {
     // Private helpers
     // -------------------------------------------------------------------------
     /**
-     * Attach listeners to the underlying WebSocket for the events that matter to
-     * the voice pipeline. All listener state is contained here; no cleanup method
-     * is currently needed since the transport's lifetime is tied to the socket's.
+     * Attach listeners to the underlying WebSocket for all events relevant to
+     * the voice pipeline.
+     *
+     * All listener state is contained here. No cleanup method is currently
+     * needed because the transport's lifetime is tied to the socket's --
+     * when the socket closes, the transport transitions to `'closed'` and
+     * no further events are expected.
      */
     _attachWsListeners() {
-        // `message` — inbound data from the remote peer
+        // `message` -- inbound data from the remote peer
         this._ws.on('message', (data) => {
             if (typeof data === 'string') {
-                // Text frame — parse as ClientTextMessage and propagate as 'control'
+                // Text frame: parse as ClientTextMessage JSON and propagate as 'control'.
+                // Malformed JSON emits an error but does NOT crash the transport,
+                // allowing the session to recover from a single bad message.
                 try {
                     const msg = JSON.parse(data);
                     this.emit('control', msg);
                 }
                 catch (err) {
-                    // Malformed JSON — emit as an error but do not crash the transport
-                    this.emit('error', new Error(`WebSocketStreamTransport: failed to parse text message: ${String(err)}`));
+                    this.emit('error', new Error(`WebSocketStreamTransport: failed to parse inbound text message as JSON: ${String(err)}`));
                 }
             }
             else {
-                // Binary frame — interpret bytes as a Float32Array PCM sample buffer
+                // Binary frame: interpret bytes as a Float32Array PCM sample buffer.
+                // The `ws` package delivers binary as a Node.js Buffer; browser-style
+                // WebSocket polyfills may deliver an ArrayBuffer instead.
                 let buffer;
                 if (Buffer.isBuffer(data)) {
                     buffer = data;
                 }
                 else {
-                    // ArrayBuffer (browser-style)
+                    // ArrayBuffer (browser-style) -- wrap in a Node.js Buffer
                     buffer = Buffer.from(data);
                 }
                 // Create a Float32Array view over the underlying ArrayBuffer.
-                // We use byteOffset/length to handle sliced Buffers correctly.
+                // We use byteOffset and byteLength to handle sliced Buffers correctly,
+                // since Buffer.from() may return a view into Node's internal pool
+                // rather than a fresh allocation.
                 const samples = new Float32Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / Float32Array.BYTES_PER_ELEMENT);
                 const frame = {
                     samples,
@@ -188,17 +249,18 @@ export class WebSocketStreamTransport extends EventEmitter {
                 this.emit('audio_frame', frame);
             }
         });
-        // `open` — socket handshake complete
+        // `open` -- socket handshake complete (fires for late-open connections)
         this._ws.on('open', () => {
             this._state = 'open';
             this.emit('connected');
         });
-        // `close` — socket has been fully closed (either side)
+        // `close` -- socket has been fully closed (either side initiated)
         this._ws.on('close', () => {
             this._state = 'closed';
             this.emit('disconnected');
         });
-        // `error` — transport-level socket error
+        // `error` -- transport-level socket error. Re-emitted verbatim so the
+        // orchestrator can log it and decide whether to tear down the session.
         this._ws.on('error', (err) => {
             this.emit('error', err);
         });

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

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

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

@@ -1,7 +1,40 @@
 /**
+ * @module @framers/agentos/voice-pipeline
+ *
  * Barrel exports for the AgentOS streaming voice pipeline.
  *
- * @module @framers/agentos/voice-pipeline
+ * This module provides all the building blocks needed to assemble a real-time
+ * voice conversation system:
+ *
+ * - **Types** -- All interfaces and type aliases defining the pipeline's contracts
+ *   ({@link AudioFrame}, {@link IStreamTransport}, {@link IEndpointDetector}, etc.).
+ *
+ * - **Orchestrator** -- {@link VoicePipelineOrchestrator} is the central state machine
+ *   that wires transport, STT, endpoint detection, TTS, and barge-in handling into
+ *   a coordinated conversation loop.
+ *
+ * - **Endpoint Detectors** -- Two strategies for detecting turn boundaries:
+ *   - {@link HeuristicEndpointDetector}: Rule-based (punctuation + silence timeout).
+ *   - {@link AcousticEndpointDetector}: Purely acoustic (silence-only, no transcript analysis).
+ *
+ * - **Barge-in Handlers** -- Two strategies for handling user interruptions:
+ *   - {@link HardCutBargeinHandler}: Immediate stop above a speech duration threshold.
+ *   - {@link SoftFadeBargeinHandler}: Three-tier (ignore/pause/cancel) with configurable fade.
+ *
+ * - **Transport** -- {@link WebSocketStreamTransport}: WebSocket-based bidirectional
+ *   audio/text transport implementing {@link IStreamTransport}.
+ *
+ * - **Error** -- {@link VoiceInterruptError}: Typed error for barge-in interruptions.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   VoicePipelineOrchestrator,
+ *   HeuristicEndpointDetector,
+ *   HardCutBargeinHandler,
+ *   WebSocketStreamTransport,
+ * } from '../voice-pipeline';
+ * ```
  */
 export * from './types.js';
 export { HardCutBargeinHandler } from './HardCutBargeinHandler.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/voice-pipeline/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/voice-pipeline/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAIH,cAAc,YAAY,CAAC;AAG3B,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAGrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAGzE,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAGzE,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAG3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC"}