@framers/agentos 0.1.74 → 0.1.76

package/dist/voice-pipeline/VoicePipelineOrchestrator.js

@@ -0,0 +1,317 @@
+/**
+ * @module voice-pipeline/VoicePipelineOrchestrator
+ *
+ * Central state machine that wires together transport, STT, endpoint detection,
+ * TTS, barge-in handling, and the agent session into a coordinated real-time
+ * voice conversation loop.
+ *
+ * State transitions:
+ * ```
+ * IDLE → startSession() → LISTENING
+ * LISTENING → turn_complete → PROCESSING
+ * PROCESSING → LLM tokens start → SPEAKING
+ * SPEAKING → TTS complete → LISTENING
+ * SPEAKING → barge-in → INTERRUPTING → LISTENING
+ * ANY → transport disconnect → CLOSED
+ * ```
+ */
+import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
+/**
+ * VoicePipelineOrchestrator is the central state machine for the AgentOS
+ * streaming voice pipeline. It coordinates audio capture, speech recognition,
+ * endpoint detection, agent inference, text-to-speech synthesis, and barge-in
+ * handling into a seamless real-time conversation loop.
+ *
+ * Emits:
+ * - `'state_changed'` ({ from: PipelineState, to: PipelineState })
+ */
+export class VoicePipelineOrchestrator extends EventEmitter {
+    /** Current pipeline state (read-only). */
+    get state() {
+        return this._state;
+    }
+    constructor(config) {
+        super();
+        this.config = config;
+        /** Current pipeline state. */
+        this._state = 'idle';
+        /** Active sub-sessions and components, set during startSession. */
+        this._sttSession = null;
+        this._ttsSession = null;
+        this._endpointDetector = null;
+        this._bargeinHandler = null;
+        this._transport = null;
+        this._agentSession = null;
+        /** Watchdog timer ID for max turn duration. */
+        this._watchdogTimer = null;
+        /** Tracks cumulative TTS text for barge-in context. */
+        this._currentTTSText = '';
+        /** Tracks cumulative played duration for barge-in context. */
+        this._currentPlayedMs = 0;
+    }
+    /**
+     * Start a voice session. Accepts pre-built components via overrides for testing.
+     * In production, components are resolved from ExtensionManager (future task).
+     *
+     * @param transport - The bidirectional audio/text stream transport.
+     * @param agentSession - The agent session adapter for turn-based conversation.
+     * @param overrides - Optional pre-built components (for testing or manual wiring).
+     * @returns A live VoicePipelineSession object.
+     */
+    async startSession(transport, agentSession, overrides) {
+        if (this._state !== 'idle') {
+            throw new Error(`Cannot start session in state '${this._state}'; expected 'idle'.`);
+        }
+        this._transport = transport;
+        this._agentSession = agentSession;
+        const stt = overrides?.streamingSTT;
+        const tts = overrides?.streamingTTS;
+        const endpointDetector = overrides?.endpointDetector;
+        const bargeinHandler = overrides?.bargeinHandler;
+        if (!stt)
+            throw new Error('streamingSTT is required (pass via overrides or wait for ExtensionManager support).');
+        if (!tts)
+            throw new Error('streamingTTS is required (pass via overrides or wait for ExtensionManager support).');
+        if (!endpointDetector)
+            throw new Error('endpointDetector is required.');
+        if (!bargeinHandler)
+            throw new Error('bargeinHandler is required.');
+        // Create sub-sessions
+        const sttSession = await stt.startSession({ language: this.config.language });
+        const ttsSession = await tts.startSession({
+            voice: this.config.voice,
+            format: this.config.format,
+        });
+        this._sttSession = sttSession;
+        this._ttsSession = ttsSession;
+        this._endpointDetector = endpointDetector;
+        this._bargeinHandler = bargeinHandler;
+        // Wire everything up
+        this._wireTransportToSTT(transport, sttSession);
+        this._wireSTTToEndpoint(sttSession, endpointDetector, transport);
+        this._wireTurnComplete(endpointDetector, transport, agentSession, ttsSession);
+        this._wireTTSToTransport(ttsSession, transport);
+        this._wireBargein(sttSession, ttsSession, bargeinHandler, transport, agentSession);
+        this._wireDisconnect(transport, sttSession, ttsSession);
+        // Transition to listening
+        this._setState('listening');
+        // Start watchdog
+        this._resetWatchdog();
+        // Build and return the VoicePipelineSession object
+        const sessionId = randomUUID();
+        const orchestrator = this;
+        const session = Object.assign(new EventEmitter(), {
+            sessionId,
+            get state() {
+                return orchestrator._state;
+            },
+            transport,
+            async close(reason) {
+                await orchestrator.stopSession(reason);
+            },
+        });
+        // Forward state_changed events to the session
+        this.on('state_changed', (evt) => session.emit('state_change', evt.to));
+        return session;
+    }
+    /**
+     * Stop the current session, tearing down all sub-sessions and timers.
+     *
+     * @param reason - Optional human-readable reason for diagnostics.
+     */
+    async stopSession(reason) {
+        if (this._state === 'closed')
+            return;
+        this._clearWatchdog();
+        this._sttSession?.close();
+        this._ttsSession?.close();
+        this._transport?.close(1000, reason);
+        this._setState('closed');
+        // Clean up references
+        this._sttSession = null;
+        this._ttsSession = null;
+        this._endpointDetector = null;
+        this._bargeinHandler = null;
+        this._transport = null;
+        this._agentSession = null;
+    }
+    // --------------------------------------------------------------------------
+    // Wiring helpers
+    // --------------------------------------------------------------------------
+    /**
+     * Forward audio frames from transport to STT session.
+     */
+    _wireTransportToSTT(transport, sttSession) {
+        transport.on('audio', (frame) => {
+            sttSession.pushAudio(frame);
+        });
+    }
+    /**
+     * Forward STT transcript events to endpoint detector and transport.
+     */
+    _wireSTTToEndpoint(sttSession, endpointDetector, transport) {
+        sttSession.on('transcript', (transcript) => {
+            endpointDetector.pushTranscript(transcript);
+            transport.sendControl({
+                type: 'transcript',
+                text: transcript.text,
+                isFinal: transcript.isFinal,
+                confidence: transcript.confidence,
+            });
+        });
+    }
+    /**
+     * Handle turn_complete from endpoint detector — transition through
+     * PROCESSING → SPEAKING → LISTENING.
+     */
+    _wireTurnComplete(endpointDetector, transport, agentSession, ttsSession) {
+        endpointDetector.on('turn_complete', async (event) => {
+            if (this._state !== 'listening')
+                return;
+            this._clearWatchdog();
+            this._setState('processing');
+            transport.sendControl({ type: 'agent_thinking' });
+            const metadata = {
+                speakers: [],
+                endpointReason: event.reason,
+                speechDurationMs: event.durationMs,
+                wasInterrupted: false,
+                transcriptConfidence: event.confidence,
+            };
+            const tokenStream = agentSession.sendText(event.transcript, metadata);
+            this._setState('speaking');
+            this._currentTTSText = '';
+            this._currentPlayedMs = 0;
+            transport.sendControl({ type: 'agent_speaking', text: '' });
+            for await (const token of tokenStream) {
+                if (this._state !== 'speaking')
+                    break; // barge-in happened
+                this._currentTTSText += token;
+                ttsSession.pushTokens(token);
+            }
+            if (this._state === 'speaking') {
+                await ttsSession.flush();
+            }
+        });
+    }
+    /**
+     * Forward TTS audio chunks to the transport and handle utterance completion.
+     */
+    _wireTTSToTransport(ttsSession, transport) {
+        ttsSession.on('audio', (chunk) => {
+            if (this._state === 'speaking') {
+                this._currentPlayedMs += chunk.durationMs;
+                transport.sendAudio(chunk);
+            }
+        });
+        ttsSession.on('flush_complete', () => {
+            if (this._state === 'speaking') {
+                this._setState('listening');
+                transport.sendControl({
+                    type: 'agent_done',
+                    text: this._currentTTSText,
+                    durationMs: this._currentPlayedMs,
+                });
+                this._endpointDetector?.reset();
+                this._resetWatchdog();
+            }
+        });
+    }
+    /**
+     * Wire barge-in detection: when speech is detected during SPEAKING state,
+     * consult the barge-in handler and act accordingly.
+     */
+    _wireBargein(sttSession, ttsSession, bargeinHandler, transport, agentSession) {
+        sttSession.on('speech_start', async () => {
+            // Also push VAD event to endpoint detector
+            this._endpointDetector?.pushVadEvent({
+                type: 'speech_start',
+                timestamp: Date.now(),
+                source: 'stt',
+            });
+            if (this._state === 'speaking') {
+                const action = await bargeinHandler.handleBargein({
+                    speechDurationMs: 0,
+                    interruptedText: this._currentTTSText,
+                    playedDurationMs: this._currentPlayedMs,
+                });
+                if (action.type === 'cancel') {
+                    this._setState('interrupting');
+                    ttsSession.cancel();
+                    agentSession.abort?.();
+                    transport.sendControl({ type: 'barge_in', action });
+                    this._setState('listening');
+                    this._endpointDetector?.reset();
+                    this._resetWatchdog();
+                }
+                else if (action.type === 'pause') {
+                    transport.sendControl({ type: 'barge_in', action });
+                }
+                // 'ignore' and 'resume' — do nothing
+            }
+        });
+        sttSession.on('speech_end', () => {
+            this._endpointDetector?.pushVadEvent({
+                type: 'speech_end',
+                timestamp: Date.now(),
+                source: 'stt',
+            });
+        });
+    }
+    /**
+     * Handle transport disconnect — close everything.
+     */
+    _wireDisconnect(transport, sttSession, ttsSession) {
+        transport.on('close', () => {
+            this._clearWatchdog();
+            this._setState('closed');
+            sttSession.close();
+            ttsSession.close();
+        });
+    }
+    // --------------------------------------------------------------------------
+    // State management
+    // --------------------------------------------------------------------------
+    /**
+     * Transition to a new pipeline state, emitting a `state_changed` event.
+     */
+    _setState(state) {
+        const from = this._state;
+        if (from === state)
+            return;
+        this._state = state;
+        this.emit('state_changed', { from, to: state });
+    }
+    // --------------------------------------------------------------------------
+    // Watchdog timer
+    // --------------------------------------------------------------------------
+    /**
+     * Reset the watchdog timer for max turn duration. If the pipeline stays in
+     * LISTENING for longer than `maxTurnDurationMs` (default 30s) without a
+     * turn_complete, force a timeout.
+     */
+    _resetWatchdog() {
+        this._clearWatchdog();
+        const maxMs = this.config.maxTurnDurationMs ?? 30000;
+        this._watchdogTimer = setTimeout(() => {
+            if (this._state === 'listening') {
+                this._endpointDetector?.pushVadEvent({
+                    type: 'speech_end',
+                    timestamp: Date.now(),
+                    source: 'vad',
+                });
+            }
+        }, maxMs);
+    }
+    /**
+     * Clear the watchdog timer if active.
+     */
+    _clearWatchdog() {
+        if (this._watchdogTimer !== null) {
+            clearTimeout(this._watchdogTimer);
+            this._watchdogTimer = null;
+        }
+    }
+}
+//# sourceMappingURL=VoicePipelineOrchestrator.js.map

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

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

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

@@ -0,0 +1,148 @@
+/**
+ * @module voice-pipeline/WebSocketStreamTransport
+ *
+ * A concrete {@link IStreamTransport} implementation that wraps a WebSocket
+ * connection (or any WebSocket-compatible object). Binary messages are decoded
+ * 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.
+ */
+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.
+ */
+export interface WebSocketLike extends NodeJS.EventEmitter {
+    /** WebSocket ready-state constant for the OPEN state (= 1). */
+    readonly OPEN?: number;
+    /** WebSocket ready-state constant for the CLOSED state (= 3). */
+    readonly CLOSED?: number;
+    /** Current ready state of the socket. */
+    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.
+     */
+    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.
+     */
+    close(code?: number, reason?: string): void;
+}
+/**
+ * Constructor options for {@link WebSocketStreamTransport}.
+ */
+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.
+     * @example 16000
+     */
+    sampleRate: number;
+}
+/**
+ * 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.
+ *
+ * ### 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`)
+ * | 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.
+ */
+export declare class WebSocketStreamTransport extends EventEmitter implements IStreamTransport {
+    /** Stable UUID assigned at construction time. */
+    readonly id: string;
+    /** Current connection state. Updated in response to WebSocket events. */
+    private _state;
+    /** The underlying WebSocket connection. */
+    private readonly _ws;
+    /** Audio sample rate propagated into every decoded {@link AudioFrame}. */
+    private readonly _sampleRate;
+    /**
+     * Create a new transport wrapping an existing WebSocket connection.
+     *
+     * The constructor inspects `ws.readyState` to determine the initial
+     * {@link state}: if the socket is already OPEN (readyState === 1) the state
+     * 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.
+     */
+    constructor(ws: WebSocketLike, config: WebSocketStreamTransportConfig);
+    /**
+     * Current connection state of the underlying WebSocket.
+     * Read-only from the outside; updated internally by WS event handlers.
+     */
+    get state(): 'connecting' | 'open' | 'closing' | 'closed';
+    /**
+     * 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.
+     *
+     * @param chunk — Encoded audio chunk or raw PCM frame to deliver.
+     * @returns Resolves once the data has been handed to the OS socket buffer.
+     */
+    sendAudio(chunk: EncodedAudioChunk | AudioFrame): Promise<void>;
+    /**
+     * Send a JSON control message to the remote client.
+     *
+     * The message is JSON-stringified before transmission. Both
+     * {@link TransportControlMessage} and {@link ServerTextMessage} are accepted
+     * since they share the same serialisation path.
+     *
+     * @param msg — Server-side protocol message.
+     * @returns Resolves once the message has been handed to the OS socket buffer.
+     */
+    sendControl(msg: TransportControlMessage | ServerTextMessage): Promise<void>;
+    /**
+     * Initiate a graceful close of the transport.
+     *
+     * Sets internal state to `'closing'` immediately, then delegates to the
+     * 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.
+     */
+    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.
+     */
+    private _attachWsListeners;
+}
+//# sourceMappingURL=WebSocketStreamTransport.d.ts.map

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

@@ -0,0 +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"}