@framers/agentos 0.1.83 → 0.1.85

package/dist/orchestration/runtime/VoiceTransportAdapter.js

@@ -0,0 +1,193 @@
+/**
+ * @file VoiceTransportAdapter.ts
+ * @description Bridges graph I/O to the voice pipeline when a workflow runs in
+ * voice transport mode.
+ *
+ * `VoiceTransportAdapter` wraps a graph's input/output cycle so that:
+ * - **Node input** is obtained by waiting for the user's next speech turn
+ *   (`waitForUserTurn()` on the underlying `VoicePipelineOrchestrator`).
+ * - **Node output** is delivered to the TTS engine (`pushToTTS()` on the
+ *   underlying `VoicePipelineOrchestrator`).
+ *
+ * The adapter is lazy — it does not create a `VoicePipelineOrchestrator` until
+ * `init()` is called.  The pipeline reference is `any` typed to avoid a hard
+ * import cycle with the voice subsystem; callers that want stronger types may
+ * cast.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new VoiceTransportAdapter(
+ *   { stt: 'deepgram', tts: 'openai' },
+ *   transport,
+ *   (event) => eventBus.emit(event),
+ * );
+ *
+ * await adapter.init(state);
+ * const userInput = await adapter.getNodeInput('greet');
+ * await adapter.deliverNodeOutput('greet', 'Hello, how can I help you today?');
+ * await adapter.dispose();
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// VoiceTransportAdapter
+// ---------------------------------------------------------------------------
+/**
+ * Adapts a compiled graph's I/O cycle to the real-time voice pipeline.
+ *
+ * Lifecycle:
+ * 1. Construct with {@link VoiceTransportConfig}, an `IStreamTransport`, and an
+ *    event sink callback.
+ * 2. Call `init()` once before the graph starts running.
+ * 3. Use `getNodeInput()` to obtain the user's transcribed speech for a node.
+ * 4. Use `deliverNodeOutput()` to send the node's response to TTS.
+ * 5. Call `dispose()` to clean up resources when the session ends.
+ */
+export class VoiceTransportAdapter {
+    /**
+     * @param config     - Voice pipeline configuration knobs.
+     * @param transport  - Bidirectional audio/control stream transport (`IStreamTransport`).
+     * @param eventSink  - Callback receiving all `GraphEvent` values emitted by this adapter.
+     */
+    constructor(config, transport, // IStreamTransport
+    eventSink) {
+        this.config = config;
+        this.transport = transport;
+        this.eventSink = eventSink;
+        /**
+         * Lazily-initialised `VoicePipelineOrchestrator` instance.
+         * Typed as `any` to avoid a hard import cycle with the voice subsystem.
+         * In a full implementation this would be `VoicePipelineOrchestrator | null`.
+         */
+        this.pipeline = null; // VoicePipelineOrchestrator (lazy)
+        /** Tracks whether `init()` has been called successfully. */
+        this.initialized = false;
+    }
+    // -------------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------------
+    /**
+     * Initialise the adapter.
+     *
+     * Injects the `IStreamTransport` instance into `state.scratch.voiceTransport` so
+     * that graph nodes can access it if needed, then emits a `voice_session` started
+     * event to signal that the voice session is live.
+     *
+     * Must be called exactly once before {@link getNodeInput} or
+     * {@link deliverNodeOutput}.
+     *
+     * @param state - Mutable `GraphState` (or partial) for the current run.
+     *               `state.scratch` is created lazily if absent.
+     */
+    async init(state) {
+        var _a;
+        // Lazily create the scratch bag if the caller passed a partial state.
+        const scratch = ((_a = state).scratch ?? (_a.scratch = {}));
+        scratch.voiceTransport = this.transport;
+        this.initialized = true;
+        this.eventSink({
+            type: 'voice_session',
+            nodeId: '__transport__',
+            action: 'started',
+        });
+    }
+    /**
+     * Wait for the user's next speech turn and return the transcript text.
+     *
+     * In a full production implementation this delegates to
+     * `VoicePipelineOrchestrator.waitForUserTurn()`.  In the current implementation
+     * it listens for a single `'turn_complete'` event from the underlying transport
+     * and resolves with the transcript text.
+     *
+     * Also emits a {@link GraphEvent} of type `voice_turn_complete` so that the
+     * runtime event bus stays in sync.
+     *
+     * @param nodeId - The id of the graph node requesting input; used to tag the emitted event.
+     * @returns Resolved transcript string from the user's speech turn.
+     * @throws {Error} If called before `init()`.
+     */
+    async getNodeInput(nodeId) {
+        if (!this.initialized) {
+            throw new Error('VoiceTransportAdapter not initialized');
+        }
+        // In real implementation: this.pipeline.waitForUserTurn()
+        // For now, listen directly to transport events.
+        return new Promise((resolve) => {
+            this.transport.once('turn_complete', (evt) => {
+                const transcript = evt?.transcript ?? evt?.text ?? '';
+                this.eventSink({
+                    type: 'voice_turn_complete',
+                    nodeId,
+                    transcript,
+                    turnIndex: 0,
+                    endpointReason: evt?.reason ?? 'unknown',
+                });
+                resolve(transcript);
+            });
+        });
+    }
+    /**
+     * Deliver a node's text output to the TTS engine.
+     *
+     * Accepts either a plain `string` or an `AsyncIterable<string>` of token
+     * chunks (e.g. a streaming LLM response).  In a full production implementation
+     * this delegates to `VoicePipelineOrchestrator.pushToTTS(output)`.
+     *
+     * Emits a {@link GraphEvent} of type `voice_audio` (direction `'outbound'`)
+     * so that the runtime event bus records the TTS delivery.
+     *
+     * @param nodeId - The id of the graph node delivering the output.
+     * @param output - Text or async token stream to synthesise as speech.
+     * @throws {Error} If called before `init()`.
+     */
+    async deliverNodeOutput(nodeId, output) {
+        if (!this.initialized) {
+            throw new Error('VoiceTransportAdapter not initialized');
+        }
+        // In real implementation: this.pipeline.pushToTTS(output)
+        // For now, emit the event to signal delivery.
+        this.eventSink({
+            type: 'voice_audio',
+            nodeId,
+            direction: 'outbound',
+            format: 'tts',
+            durationMs: 0,
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Barge-in
+    // -------------------------------------------------------------------------
+    /**
+     * Handle a user barge-in at the transport level.
+     *
+     * Should be called by the runtime or transport layer when the user starts
+     * speaking while the agent is mid-utterance.  Emits a `voice_barge_in` event
+     * so that graph event consumers can react (e.g. cancel pending tool calls).
+     */
+    handleBargeIn() {
+        this.eventSink({
+            type: 'voice_barge_in',
+            nodeId: '__transport__',
+            interruptedText: '',
+            userSpeech: '',
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Disposal
+    // -------------------------------------------------------------------------
+    /**
+     * Dispose the adapter and emit a `voice_session` ended event.
+     *
+     * Marks the adapter as uninitialised so subsequent calls to `getNodeInput()`
+     * or `deliverNodeOutput()` will throw, preventing accidental use after teardown.
+     */
+    async dispose() {
+        this.eventSink({
+            type: 'voice_session',
+            nodeId: '__transport__',
+            action: 'ended',
+            exitReason: 'transport-disposed',
+        });
+        this.initialized = false;
+    }
+}
+//# sourceMappingURL=VoiceTransportAdapter.js.map

package/dist/orchestration/runtime/VoiceTransportAdapter.js.map

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

package/dist/orchestration/runtime/VoiceTurnCollector.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @file VoiceTurnCollector.ts
+ * @description Subscribes to voice pipeline session events and maintains a
+ * running transcript buffer, turn counter, and last-speaker tracker.
+ *
+ * The collector bridges the raw EventEmitter-based voice pipeline session into
+ * the typed `GraphEvent` stream consumed by the graph runtime. Four session
+ * events are handled:
+ *
+ * - `interim_transcript` — partial STT result; forwarded as a non-final
+ *   `voice_transcript` GraphEvent but **not** buffered (too noisy).
+ * - `final_transcript` — confirmed STT result; buffered in `transcript` and
+ *   forwarded as a final `voice_transcript` GraphEvent.
+ * - `turn_complete` — endpoint detection fired; increments `turnCount` and
+ *   emits a `voice_turn_complete` GraphEvent.
+ * - `barge_in` — user interrupted the agent mid-speech; emits a
+ *   `voice_barge_in` GraphEvent.
+ *
+ * The `initialTurnCount` constructor parameter enables checkpoint restore:
+ * pass the previously persisted count so that `turnIndex` values continue
+ * from where the session left off rather than resetting to zero.
+ */
+import { EventEmitter } from 'events';
+import type { GraphEvent } from '../events/GraphEvent.js';
+/**
+ * A single confirmed (final) utterance captured from the voice pipeline.
+ *
+ * Only `final_transcript` events populate this buffer — interim partials are
+ * discarded to keep the transcript clean and avoid duplicate entries.
+ */
+export interface TranscriptEntry {
+    /** Speaker identifier as reported by the STT service (e.g. `"Speaker_0"`). */
+    speaker: string;
+    /** Recognised text for this utterance. */
+    text: string;
+    /**
+     * Wall-clock timestamp (milliseconds since Unix epoch) recorded at the
+     * moment the `final_transcript` event was processed.
+     */
+    timestamp: number;
+}
+/**
+ * Stateful collector that subscribes to a voice pipeline session and routes
+ * session events into the AgentOS `GraphEvent` stream.
+ *
+ * @example
+ * ```ts
+ * const collector = new VoiceTurnCollector(
+ *   session,
+ *   (evt) => graphEventEmitter.emit(evt),
+ *   'voice-node-1',
+ * );
+ *
+ * // After the conversation:
+ * console.log(collector.getTurnCount());   // number of completed turns
+ * console.log(collector.getTranscript());  // full buffered transcript
+ * console.log(collector.getLastSpeaker()); // last identified speaker
+ * ```
+ */
+export declare class VoiceTurnCollector {
+    private readonly eventSink;
+    private readonly nodeId;
+    /** Buffered confirmed utterances in chronological order. */
+    private transcript;
+    /** Running count of completed turns (endpoint-detected). */
+    private turnCount;
+    /** Speaker identifier from the most recent `final_transcript` event. */
+    private lastSpeaker;
+    /**
+     * @param session          - The voice pipeline `EventEmitter` to subscribe to.
+     * @param eventSink        - Callback invoked synchronously for every emitted `GraphEvent`.
+     * @param nodeId           - Identifies the owning graph node in every emitted event.
+     * @param initialTurnCount - Seed value for `turnCount`; pass a persisted value to
+     *                           resume from a checkpoint rather than starting at zero.
+     */
+    constructor(session: EventEmitter, eventSink: (event: GraphEvent) => void, nodeId: string, initialTurnCount?: number);
+    /**
+     * Returns the total number of completed turns since construction (or since the
+     * provided `initialTurnCount` when restoring from a checkpoint).
+     */
+    getTurnCount(): number;
+    /**
+     * Returns a shallow copy of the buffered transcript entries.
+     *
+     * A copy is returned to prevent external callers from mutating the internal
+     * buffer — entries are append-only and must remain ordered.
+     */
+    getTranscript(): TranscriptEntry[];
+    /**
+     * Returns the speaker identifier from the most recent `final_transcript` event,
+     * or an empty string if no final transcript has been received yet.
+     */
+    getLastSpeaker(): string;
+}
+//# sourceMappingURL=VoiceTurnCollector.d.ts.map

package/dist/orchestration/runtime/VoiceTurnCollector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VoiceTurnCollector.d.ts","sourceRoot":"","sources":["../../../src/orchestration/runtime/VoiceTurnCollector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAM1D;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,kBAAkB;IAmB3B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAnBzB,4DAA4D;IAC5D,OAAO,CAAC,UAAU,CAAyB;IAE3C,4DAA4D;IAC5D,OAAO,CAAC,SAAS,CAAS;IAE1B,wEAAwE;IACxE,OAAO,CAAC,WAAW,CAAM;IAEzB;;;;;;OAMG;gBAED,OAAO,EAAE,YAAY,EACJ,SAAS,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,EACtC,MAAM,EAAE,MAAM,EAC/B,gBAAgB,SAAI;IA6EtB;;;OAGG;IACH,YAAY,IAAI,MAAM;IAItB;;;;;OAKG;IACH,aAAa,IAAI,eAAe,EAAE;IAIlC;;;OAGG;IACH,cAAc,IAAI,MAAM;CAGzB"}

package/dist/orchestration/runtime/VoiceTurnCollector.js

@@ -0,0 +1,148 @@
+/**
+ * @file VoiceTurnCollector.ts
+ * @description Subscribes to voice pipeline session events and maintains a
+ * running transcript buffer, turn counter, and last-speaker tracker.
+ *
+ * The collector bridges the raw EventEmitter-based voice pipeline session into
+ * the typed `GraphEvent` stream consumed by the graph runtime. Four session
+ * events are handled:
+ *
+ * - `interim_transcript` — partial STT result; forwarded as a non-final
+ *   `voice_transcript` GraphEvent but **not** buffered (too noisy).
+ * - `final_transcript` — confirmed STT result; buffered in `transcript` and
+ *   forwarded as a final `voice_transcript` GraphEvent.
+ * - `turn_complete` — endpoint detection fired; increments `turnCount` and
+ *   emits a `voice_turn_complete` GraphEvent.
+ * - `barge_in` — user interrupted the agent mid-speech; emits a
+ *   `voice_barge_in` GraphEvent.
+ *
+ * The `initialTurnCount` constructor parameter enables checkpoint restore:
+ * pass the previously persisted count so that `turnIndex` values continue
+ * from where the session left off rather than resetting to zero.
+ */
+// ---------------------------------------------------------------------------
+// VoiceTurnCollector
+// ---------------------------------------------------------------------------
+/**
+ * Stateful collector that subscribes to a voice pipeline session and routes
+ * session events into the AgentOS `GraphEvent` stream.
+ *
+ * @example
+ * ```ts
+ * const collector = new VoiceTurnCollector(
+ *   session,
+ *   (evt) => graphEventEmitter.emit(evt),
+ *   'voice-node-1',
+ * );
+ *
+ * // After the conversation:
+ * console.log(collector.getTurnCount());   // number of completed turns
+ * console.log(collector.getTranscript());  // full buffered transcript
+ * console.log(collector.getLastSpeaker()); // last identified speaker
+ * ```
+ */
+export class VoiceTurnCollector {
+    /**
+     * @param session          - The voice pipeline `EventEmitter` to subscribe to.
+     * @param eventSink        - Callback invoked synchronously for every emitted `GraphEvent`.
+     * @param nodeId           - Identifies the owning graph node in every emitted event.
+     * @param initialTurnCount - Seed value for `turnCount`; pass a persisted value to
+     *                           resume from a checkpoint rather than starting at zero.
+     */
+    constructor(session, eventSink, nodeId, initialTurnCount = 0) {
+        this.eventSink = eventSink;
+        this.nodeId = nodeId;
+        /** Buffered confirmed utterances in chronological order. */
+        this.transcript = [];
+        /** Speaker identifier from the most recent `final_transcript` event. */
+        this.lastSpeaker = '';
+        this.turnCount = initialTurnCount;
+        // ------------------------------------------------------------------
+        // interim_transcript — partial STT result, forwarded but not buffered
+        // ------------------------------------------------------------------
+        session.on('interim_transcript', (evt) => {
+            this.eventSink({
+                type: 'voice_transcript',
+                nodeId: this.nodeId,
+                text: evt.text ?? '',
+                isFinal: false,
+                speaker: evt.speaker,
+                confidence: evt.confidence ?? 0,
+            });
+        });
+        // ------------------------------------------------------------------
+        // final_transcript — confirmed utterance, buffered and forwarded
+        // ------------------------------------------------------------------
+        session.on('final_transcript', (evt) => {
+            const speaker = evt.speaker ?? 'user';
+            // Buffer the confirmed entry for downstream consumers.
+            this.transcript.push({
+                speaker,
+                text: evt.text ?? '',
+                timestamp: Date.now(),
+            });
+            // Track the most recent speaker for quick access without iterating the buffer.
+            this.lastSpeaker = speaker;
+            this.eventSink({
+                type: 'voice_transcript',
+                nodeId: this.nodeId,
+                text: evt.text ?? '',
+                isFinal: true,
+                speaker,
+                confidence: evt.confidence ?? 0,
+            });
+        });
+        // ------------------------------------------------------------------
+        // turn_complete — endpoint detection fired; advance the turn counter
+        // ------------------------------------------------------------------
+        session.on('turn_complete', (evt) => {
+            // Increment before emitting so that turnIndex reflects the new count.
+            this.turnCount++;
+            this.eventSink({
+                type: 'voice_turn_complete',
+                nodeId: this.nodeId,
+                transcript: evt.transcript ?? '',
+                turnIndex: this.turnCount,
+                endpointReason: evt.reason ?? 'unknown',
+            });
+        });
+        // ------------------------------------------------------------------
+        // barge_in — user interrupted agent mid-speech
+        // ------------------------------------------------------------------
+        session.on('barge_in', (evt) => {
+            this.eventSink({
+                type: 'voice_barge_in',
+                nodeId: this.nodeId,
+                interruptedText: evt.interruptedText ?? '',
+                userSpeech: evt.userSpeech ?? '',
+            });
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Accessors
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns the total number of completed turns since construction (or since the
+     * provided `initialTurnCount` when restoring from a checkpoint).
+     */
+    getTurnCount() {
+        return this.turnCount;
+    }
+    /**
+     * Returns a shallow copy of the buffered transcript entries.
+     *
+     * A copy is returned to prevent external callers from mutating the internal
+     * buffer — entries are append-only and must remain ordered.
+     */
+    getTranscript() {
+        return [...this.transcript];
+    }
+    /**
+     * Returns the speaker identifier from the most recent `final_transcript` event,
+     * or an empty string if no final transcript has been received yet.
+     */
+    getLastSpeaker() {
+        return this.lastSpeaker;
+    }
+}
+//# sourceMappingURL=VoiceTurnCollector.js.map

package/dist/orchestration/runtime/VoiceTurnCollector.js.map

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

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

@@ -0,0 +1,52 @@
+/**
+ * @module voice-pipeline/VoiceInterruptError
+ *
+ * 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.
+ */
+/**
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await voiceNode.run(context);
+ * } catch (err) {
+ *   if (err instanceof VoiceInterruptError) {
+ *     console.log(`Interrupted after ${err.playedDurationMs}ms`);
+ *     await handleBargein(err.userSpeech);
+ *   }
+ * }
+ * ```
+ */
+export declare class VoiceInterruptError extends Error {
+    /** Discriminant name — always `'VoiceInterruptError'` for `instanceof`-free checks. */
+    readonly name = "VoiceInterruptError";
+    /** The text the agent was speaking when interrupted. */
+    readonly interruptedText: string;
+    /** What the user said that caused the interruption. */
+    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.
+     */
+    readonly playedDurationMs: number;
+    /**
+     * @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.
+     */
+    constructor(context: {
+        interruptedText: string;
+        userSpeech: string;
+        playedDurationMs: number;
+    });
+}
+//# sourceMappingURL=VoiceInterruptError.d.ts.map

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

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

package/dist/voice-pipeline/VoiceInterruptError.js

@@ -0,0 +1,43 @@
+/**
+ * @module voice-pipeline/VoiceInterruptError
+ *
+ * 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.
+ */
+/**
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await voiceNode.run(context);
+ * } catch (err) {
+ *   if (err instanceof VoiceInterruptError) {
+ *     console.log(`Interrupted after ${err.playedDurationMs}ms`);
+ *     await handleBargein(err.userSpeech);
+ *   }
+ * }
+ * ```
+ */
+export class VoiceInterruptError extends Error {
+    /**
+     * @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.
+     */
+    constructor(context) {
+        super('Voice session interrupted by user');
+        /** Discriminant name — always `'VoiceInterruptError'` for `instanceof`-free checks. */
+        this.name = 'VoiceInterruptError';
+        this.interruptedText = context.interruptedText;
+        this.userSpeech = context.userSpeech;
+        this.playedDurationMs = context.playedDurationMs;
+    }
+}
+//# sourceMappingURL=VoiceInterruptError.js.map

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

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

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

@@ -16,7 +16,7 @@
  * ```
  */
 import { EventEmitter } from 'node:events';
-import type { IBargeinHandler, IDiarizationEngine, IEndpointDetector, IStreamTransport, IStreamingSTT, IStreamingTTS, IVoicePipelineAgentSession, PipelineState, VoicePipelineConfig, VoicePipelineSession } from './types.js';
+import type { IBargeinHandler, IDiarizationEngine, IEndpointDetector, IStreamTransport, IStreamingSTT, IStreamingTTS, IVoicePipelineAgentSession, PipelineState, TurnCompleteEvent, VoicePipelineConfig, VoicePipelineSession } from './types.js';
 /**
  * Overrides for injecting pre-built components (primarily for testing).
  * In production, components would be resolved from ExtensionManager.
@@ -78,6 +78,49 @@ export declare class VoicePipelineOrchestrator extends EventEmitter {
      * @param reason - Optional human-readable reason for diagnostics.
      */
     stopSession(reason?: string): Promise<void>;
+    /**
+     * Wait for the next user turn to complete.
+     *
+     * Wraps the internal `'turn_complete'` event in a one-shot Promise so that
+     * graph nodes (via VoiceTransportAdapter) can `await` user input without
+     * having to manage raw EventEmitter subscriptions themselves.
+     *
+     * Resolves with the first `TurnCompleteEvent` fired after this call.
+     * If the session is closed before a turn completes, the Promise will never
+     * resolve — callers should race it against a session-close signal if needed.
+     *
+     * @returns A Promise that resolves with the completed turn event.
+     *
+     * @example
+     * ```typescript
+     * const turn = await orchestrator.waitForUserTurn();
+     * console.log('User said:', turn.transcript);
+     * ```
+     */
+    waitForUserTurn(): Promise<TurnCompleteEvent>;
+    /**
+     * Push text to the active TTS session.
+     *
+     * Accepts either a plain string or an `AsyncIterable<string>` of token chunks
+     * (e.g. a streaming LLM response). Calls `pushTokens()` on the active TTS
+     * session for each token, then calls `flush()` to signal end-of-utterance.
+     *
+     * Used by VoiceTransportAdapter to deliver graph node output as speech
+     * without the caller needing a direct reference to the TTS session.
+     *
+     * @param text - A complete string, or an async iterable of string tokens.
+     * @throws {Error} If there is no active TTS session (i.e. session not started).
+     *
+     * @example
+     * ```typescript
+     * // Plain string
+     * await orchestrator.pushToTTS('Hello, how can I help?');
+     *
+     * // Streaming tokens from an LLM
+     * await orchestrator.pushToTTS(llm.streamTokens(prompt));
+     * ```
+     */
+    pushToTTS(text: string | AsyncIterable<string>): Promise<void>;
     /**
      * Forward audio frames from transport to STT session.
      */

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

@@ -1 +1 @@
-{"version":3,"file":"VoicePipelineOrchestrator.d.ts","sourceRoot":"","sources":["../../src/voice-pipeline/VoicePipelineOrchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,KAAK,EAGV,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,0BAA0B,EAC1B,aAAa,EAKb,mBAAmB,EACnB,oBAAoB,EAErB,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,wCAAwC;IACxC,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,wCAAwC;IACxC,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,mCAAmC;IACnC,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;IACrC,kCAAkC;IAClC,cAAc,CAAC,EAAE,eAAe,CAAC;IACjC,oCAAoC;IACpC,iBAAiB,CAAC,EAAE,kBAAkB,CAAC;CACxC;AAED;;;;;;;;GAQG;AACH,qBAAa,yBAA0B,SAAQ,YAAY;IA0B7C,OAAO,CAAC,QAAQ,CAAC,MAAM;IAzBnC,8BAA8B;IAC9B,OAAO,CAAC,MAAM,CAAyB;IAEvC,mEAAmE;IACnE,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,iBAAiB,CAAkC;IAC3D,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,UAAU,CAAiC;IACnD,OAAO,CAAC,aAAa,CAA2C;IAEhE,+CAA+C;IAC/C,OAAO,CAAC,cAAc,CAA8C;IAEpE,uDAAuD;IACvD,OAAO,CAAC,eAAe,CAAM;IAE7B,8DAA8D;IAC9D,OAAO,CAAC,gBAAgB,CAAK;IAE7B,0CAA0C;IAC1C,IAAI,KAAK,IAAI,aAAa,CAEzB;gBAE4B,MAAM,EAAE,mBAAmB;IAIxD;;;;;;;;OAQG;IACG,YAAY,CAChB,SAAS,EAAE,gBAAgB,EAC3B,YAAY,EAAE,0BAA0B,EACxC,SAAS,CAAC,EAAE,sBAAsB,GACjC,OAAO,CAAC,oBAAoB,CAAC;IAiEhC;;;;OAIG;IACG,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBjD;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAS3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAgB1B;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAuCzB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAyB3B;;;OAGG;IACH,OAAO,CAAC,YAAY;IA8CpB;;OAEG;IACH,OAAO,CAAC,eAAe;IAiBvB;;OAEG;IACH,OAAO,CAAC,SAAS;IAWjB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IActB;;OAEG;IACH,OAAO,CAAC,cAAc;CAMvB"}
+{"version":3,"file":"VoicePipelineOrchestrator.d.ts","sourceRoot":"","sources":["../../src/voice-pipeline/VoicePipelineOrchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,KAAK,EAGV,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,0BAA0B,EAC1B,aAAa,EAIb,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EAErB,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,wCAAwC;IACxC,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,wCAAwC;IACxC,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,mCAAmC;IACnC,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;IACrC,kCAAkC;IAClC,cAAc,CAAC,EAAE,eAAe,CAAC;IACjC,oCAAoC;IACpC,iBAAiB,CAAC,EAAE,kBAAkB,CAAC;CACxC;AAED;;;;;;;;GAQG;AACH,qBAAa,yBAA0B,SAAQ,YAAY;IA0B7C,OAAO,CAAC,QAAQ,CAAC,MAAM;IAzBnC,8BAA8B;IAC9B,OAAO,CAAC,MAAM,CAAyB;IAEvC,mEAAmE;IACnE,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,iBAAiB,CAAkC;IAC3D,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,UAAU,CAAiC;IACnD,OAAO,CAAC,aAAa,CAA2C;IAEhE,+CAA+C;IAC/C,OAAO,CAAC,cAAc,CAA8C;IAEpE,uDAAuD;IACvD,OAAO,CAAC,eAAe,CAAM;IAE7B,8DAA8D;IAC9D,OAAO,CAAC,gBAAgB,CAAK;IAE7B,0CAA0C;IAC1C,IAAI,KAAK,IAAI,aAAa,CAEzB;gBAE4B,MAAM,EAAE,mBAAmB;IAIxD;;;;;;;;OAQG;IACG,YAAY,CAChB,SAAS,EAAE,gBAAgB,EAC3B,YAAY,EAAE,0BAA0B,EACxC,SAAS,CAAC,EAAE,sBAAsB,GACjC,OAAO,CAAC,oBAAoB,CAAC;IAiEhC;;;;OAIG;IACG,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBjD;;;;;;;;;;;;;;;;;;OAkBG;IACG,eAAe,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAMnD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBpE;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAS3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAgB1B;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAuCzB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAyB3B;;;OAGG;IACH,OAAO,CAAC,YAAY;IA8CpB;;OAEG;IACH,OAAO,CAAC,eAAe;IAiBvB;;OAEG;IACH,OAAO,CAAC,SAAS;IAWjB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IActB;;OAEG;IACH,OAAO,CAAC,cAAc;CAMvB"}