@framers/agentos 0.1.82 → 0.1.84

package/dist/orchestration/runtime/VoiceNodeExecutor.js

@@ -0,0 +1,232 @@
+/**
+ * @file VoiceNodeExecutor.ts
+ * @description Executes voice nodes in the orchestration graph by managing a voice
+ * pipeline session, collecting turns via {@link VoiceTurnCollector}, and racing
+ * multiple exit conditions (hangup, turns exhausted, keyword, silence timeout,
+ * barge-in abort) to determine when the voice node completes.
+ *
+ * The executor follows the standard 2-arg `execute(node, state)` contract used by
+ * {@link NodeExecutor}. It creates an internal `AbortController` for barge-in
+ * support and optionally merges a parent abort signal from `state.scratch.abortSignal`.
+ *
+ * Voice transport and session references are expected in `state.scratch`:
+ * - `voiceTransport` — the bidirectional transport EventEmitter (emits `close` / `disconnected`).
+ * - `voiceTransport._voiceSession` — the voice pipeline session EventEmitter that fires
+ *   `final_transcript`, `turn_complete`, `speech_start`, and `barge_in` events.
+ *
+ * Checkpoint data is stored in `state.scratch[nodeId]` as a {@link VoiceNodeCheckpoint},
+ * enabling the graph runtime to resume a voice session from the exact turn index where
+ * it was previously suspended.
+ */
+import { EventEmitter } from 'events';
+import { VoiceTurnCollector } from './VoiceTurnCollector.js';
+import { VoiceInterruptError } from '../../voice-pipeline/VoiceInterruptError.js';
+// ---------------------------------------------------------------------------
+// VoiceNodeExecutor
+// ---------------------------------------------------------------------------
+/**
+ * Executes voice-type graph nodes by running a voice pipeline session and racing
+ * multiple exit conditions to determine when the node is done.
+ *
+ * Exit conditions are evaluated concurrently via a single `Promise` race:
+ * - **Hangup** — transport emits `close` or `disconnected`.
+ * - **Turns exhausted** — session emits `turn_complete` and the collector's count
+ *   reaches `config.maxTurns`.
+ * - **Keyword** — a `final_transcript` event contains one of `config.exitKeywords`.
+ * - **Silence timeout** — no speech activity for 30 seconds (when `exitOn: 'silence-timeout'`).
+ * - **Abort/barge-in** — the internal `AbortController` is signalled, either by a
+ *   parent abort signal or a `VoiceInterruptError`.
+ *
+ * @example
+ * ```ts
+ * const executor = new VoiceNodeExecutor((event) => emitter.emit(event));
+ * const result = await executor.execute(voiceNode, graphState);
+ * console.log(result.output.exitReason); // 'turns-exhausted' | 'hangup' | 'keyword:goodbye' | ...
+ * ```
+ */
+export class VoiceNodeExecutor {
+    /**
+     * @param eventSink - Callback invoked synchronously for every emitted {@link GraphEvent}.
+     *                     Typically bound to the graph runtime's event emitter.
+     */
+    constructor(eventSink) {
+        this.eventSink = eventSink;
+    }
+    /**
+     * Execute a voice node. Matches the standard 2-arg `execute(node, state)` signature
+     * used throughout the orchestration runtime.
+     *
+     * Creates an internal `AbortController` for barge-in, wires up a
+     * {@link VoiceTurnCollector} on the session, and races exit conditions to
+     * determine when the node completes.
+     *
+     * @param node  - Immutable voice node descriptor from the compiled graph IR.
+     * @param state - Current (partial) graph state threaded from the runtime.
+     * @returns A {@link NodeExecutionResult} with transcript, exit reason, and optional route target.
+     */
+    async execute(node, state) {
+        const config = node.executorConfig;
+        if (config.type !== 'voice') {
+            return { success: false, error: 'VoiceNodeExecutor received non-voice node' };
+        }
+        const voiceConfig = config.voiceConfig;
+        // Internal AbortController for barge-in or parent cancellation.
+        const controller = new AbortController();
+        // If a parent abort signal exists in scratch, forward its abort to ours.
+        const parentSignal = state?.scratch?.abortSignal;
+        if (parentSignal) {
+            parentSignal.addEventListener('abort', () => controller.abort(parentSignal.reason), { once: true });
+        }
+        // Voice transport must be pre-placed in state.scratch by the graph runtime.
+        const transport = state?.scratch?.voiceTransport;
+        if (!transport) {
+            return { success: false, error: 'Voice node requires voiceTransport in state.scratch' };
+        }
+        // Check for checkpoint restore — continue from a prior turn index.
+        const checkpoint = state?.scratch?.[node.id];
+        const initialTurnCount = checkpoint?.turnIndex ?? 0;
+        // Emit session lifecycle event: started.
+        this.eventSink({ type: 'voice_session', nodeId: node.id, action: 'started' });
+        try {
+            // The voice session EventEmitter is expected on transport._voiceSession.
+            // In production this is the VoicePipelineSession; in tests it can be a plain EventEmitter.
+            const session = transport._voiceSession ?? new EventEmitter();
+            // Create the turn collector — it subscribes to session events and buffers transcript.
+            const collector = new VoiceTurnCollector(session, this.eventSink, node.id, initialTurnCount);
+            // Race all exit conditions against each other.
+            const result = await this.raceExitConditions(session, collector, voiceConfig, controller, transport);
+            // Resolve exitReason → routeTarget from node edges.
+            const edges = node.edges ?? {};
+            const routeTarget = typeof edges === 'object' ? edges[result.reason] : undefined;
+            // Build checkpoint for scratch so the runtime can persist/restore later.
+            const voiceCheckpoint = {
+                turnIndex: collector.getTurnCount(),
+                transcript: collector.getTranscript(),
+                lastExitReason: result.reason,
+                speakerMap: {},
+                sessionConfig: voiceConfig,
+            };
+            // Emit session lifecycle event: ended.
+            this.eventSink({ type: 'voice_session', nodeId: node.id, action: 'ended', exitReason: result.reason });
+            return {
+                success: true,
+                output: {
+                    transcript: collector.getTranscript(),
+                    turns: collector.getTurnCount(),
+                    exitReason: result.reason,
+                    lastSpeaker: collector.getLastSpeaker(),
+                    interruptedText: result.interruptedText,
+                },
+                routeTarget,
+                scratchUpdate: { [node.id]: voiceCheckpoint },
+            };
+        }
+        catch (err) {
+            // VoiceInterruptError is a structured barge-in — treat as a successful exit
+            // with exitReason: 'interrupted' so the graph can route accordingly.
+            if (err instanceof VoiceInterruptError) {
+                const edges = node.edges ?? {};
+                const routeTarget = edges['interrupted'];
+                this.eventSink({ type: 'voice_session', nodeId: node.id, action: 'ended', exitReason: 'interrupted' });
+                return {
+                    success: true,
+                    output: {
+                        transcript: [],
+                        turns: 0,
+                        exitReason: 'interrupted',
+                        interruptedText: err.interruptedText,
+                        userSpeech: err.userSpeech,
+                    },
+                    routeTarget,
+                };
+            }
+            // Unhandled error — surface as a failed result.
+            this.eventSink({ type: 'voice_session', nodeId: node.id, action: 'ended', exitReason: 'error' });
+            return { success: false, error: String(err) };
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Races all configured exit conditions against each other and resolves with
+     * the first one that fires.
+     *
+     * Listeners are attached to the session and transport EventEmitters. The
+     * `AbortController` signal is also monitored — if it fires with a
+     * {@link VoiceInterruptError} the Promise rejects (handled by the caller),
+     * otherwise it resolves with `{ reason: 'interrupted' }`.
+     *
+     * @param session    - Voice pipeline session EventEmitter.
+     * @param collector  - Active turn collector tracking turn count.
+     * @param config     - Voice node configuration with exit settings.
+     * @param controller - Internal AbortController for barge-in signalling.
+     * @param transport  - Bidirectional transport EventEmitter.
+     * @returns The winning exit condition's reason string and optional interrupted text.
+     */
+    async raceExitConditions(session, collector, config, controller, transport) {
+        return new Promise((resolve, reject) => {
+            /** Prevent double-resolution from multiple conditions firing simultaneously. */
+            let settled = false;
+            /**
+             * Settle the promise with a resolve value, guarding against double-settle.
+             * @param result - The exit condition result.
+             */
+            const settleWith = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(result);
+            };
+            // -- Hangup: transport disconnects -----------------------------------
+            const onDisconnect = () => settleWith({ reason: 'hangup' });
+            transport.on('close', onDisconnect);
+            transport.on('disconnected', onDisconnect);
+            // -- Turns exhausted -------------------------------------------------
+            if (config.maxTurns && config.maxTurns > 0) {
+                session.on('turn_complete', () => {
+                    if (collector.getTurnCount() >= config.maxTurns) {
+                        settleWith({ reason: 'turns-exhausted' });
+                    }
+                });
+            }
+            // -- Keyword detection -----------------------------------------------
+            if (config.exitOn === 'keyword' && config.exitKeywords?.length) {
+                session.on('final_transcript', (evt) => {
+                    const text = (evt.text ?? '').toLowerCase();
+                    for (const kw of config.exitKeywords) {
+                        if (text.includes(kw.toLowerCase())) {
+                            settleWith({ reason: `keyword:${kw}` });
+                            return;
+                        }
+                    }
+                });
+            }
+            // -- Silence timeout (default 30 s) ----------------------------------
+            if (config.exitOn === 'silence-timeout') {
+                let silenceTimer = null;
+                const timeoutMs = 30000;
+                /** Reset the silence watchdog — called on any speech activity. */
+                const resetTimer = () => {
+                    if (silenceTimer)
+                        clearTimeout(silenceTimer);
+                    silenceTimer = setTimeout(() => settleWith({ reason: 'silence-timeout' }), timeoutMs);
+                };
+                session.on('speech_start', resetTimer);
+                session.on('turn_complete', resetTimer);
+                resetTimer(); // Start the initial timer immediately.
+            }
+            // -- Abort signal (barge-in or parent cancellation) ------------------
+            controller.signal.addEventListener('abort', () => {
+                const reason = controller.signal.reason;
+                if (reason instanceof VoiceInterruptError) {
+                    reject(reason);
+                }
+                else {
+                    settleWith({ reason: 'interrupted' });
+                }
+            }, { once: true });
+        });
+    }
+}
+//# sourceMappingURL=VoiceNodeExecutor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VoiceNodeExecutor.js","sourceRoot":"","sources":["../../../src/orchestration/runtime/VoiceNodeExecutor.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.
      */