@framers/agentos 0.1.112 → 0.1.114

package/dist/orchestration/runtime/VoiceNodeExecutor.js

@@ -1,22 +1,35 @@
 /**
  * @file VoiceNodeExecutor.ts
  * @description Executes voice nodes in the orchestration graph by managing a voice
- * pipeline session, collecting turns via {@link VoiceTurnCollector}, and racing
+ * pipeline session, collecting turns via `VoiceTurnCollector`, and racing
  * multiple exit conditions (hangup, turns exhausted, keyword, silence timeout,
  * barge-in abort) to determine when the voice node completes.
  *
+ * ## Design rationale
+ *
  * The executor follows the standard 2-arg `execute(node, state)` contract used by
- * {@link NodeExecutor}. It creates an internal `AbortController` for barge-in
+ * {@link NodeExecutor}. Internally it creates an `AbortController` for barge-in
  * support and optionally merges a parent abort signal from `state.scratch.abortSignal`.
  *
+ * Exit conditions are modelled as a **single `Promise.race`** rather than a state
+ * machine because the conditions are orthogonal and any one of them can fire at any
+ * time. The `settled` flag inside {@link raceExitConditions} guards against
+ * double-resolution when two conditions fire within the same microtask.
+ *
+ * ## State contract
+ *
  * 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
+ * - `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.
+ *
+ * See `VoiceTurnCollector` for transcript buffering and event bridging.
+ * See `VoiceTransportAdapter` for how graph I/O is wrapped at the transport level.
+ * @see {@link VoiceInterruptError} for the structured barge-in error type.
  */
 import { EventEmitter } from 'events';
 import { VoiceTurnCollector } from './VoiceTurnCollector.js';
@@ -29,25 +42,33 @@ import { VoiceInterruptError } from '../../voice-pipeline/VoiceInterruptError.js
  * 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
+ * - **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
+ * - **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' | ...
+ * console.log(result.output.exitReason);
+ * // 'turns-exhausted' | 'hangup' | 'keyword:goodbye' | 'silence-timeout' | 'interrupted'
  * ```
+ *
+ * See `VoiceTurnCollector` for session subscription and transcript buffering.
+ * @see {@link VoiceInterruptError} -- structured barge-in error that triggers the `interrupted` path.
  */
 export class VoiceNodeExecutor {
     /**
+     * Creates a new VoiceNodeExecutor.
+     *
      * @param eventSink - Callback invoked synchronously for every emitted {@link GraphEvent}.
-     *                     Typically bound to the graph runtime's event emitter.
+     *                     Typically bound to the graph runtime's event emitter so that
+     *                     voice lifecycle events (`voice_session`, `voice_transcript`, etc.)
+     *                     are visible to all graph event consumers.
      */
     constructor(eventSink) {
         this.eventSink = eventSink;
@@ -56,49 +77,87 @@ export class VoiceNodeExecutor {
      * 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.
+     * ## Lifecycle
+     *
+     * 1. Validates that `node.executorConfig.type` is `'voice'`.
+     * 2. Creates an internal `AbortController` for barge-in, wiring it to any parent
+     *    abort signal in `state.scratch.abortSignal`.
+     * 3. Extracts the `voiceTransport` from `state.scratch` (must be pre-placed by
+     *    the graph runtime or `VoiceTransportAdapter`).
+     * 4. Checks for a {@link VoiceNodeCheckpoint} to resume from.
+     * 5. Emits a `voice_session` started event.
+     * 6. Wires a `VoiceTurnCollector` onto the session and races exit conditions.
+     * 7. Resolves the exit reason to a route target via the node's edge map.
+     * 8. Returns a {@link NodeExecutionResult} with transcript, exit reason, checkpoint,
+     *    and optional route target.
      *
      * @param node  - Immutable voice node descriptor from the compiled graph IR.
+     *                Must have `executorConfig.type === 'voice'`.
      * @param state - Current (partial) graph state threaded from the runtime.
+     *                Must contain `scratch.voiceTransport` for the voice session.
      * @returns A {@link NodeExecutionResult} with transcript, exit reason, and optional route target.
+     *          On success, `output` contains `{ transcript, turns, exitReason, lastSpeaker, interruptedText }`.
+     *          `scratchUpdate` carries the {@link VoiceNodeCheckpoint} keyed by node id.
+     * @throws Never -- all errors are caught and returned as `{ success: false, error }`.
+     *         {@link VoiceInterruptError} is caught and mapped to `exitReason: 'interrupted'`.
+     *
+     * @see {@link raceExitConditions} for the concurrent exit condition implementation.
      */
     async execute(node, state) {
         const config = node.executorConfig;
+        // Guard: only voice nodes should reach this executor.
         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.
+        // Create an internal AbortController so barge-in events or parent cancellation
+        // can terminate the exit condition race without waiting for a session event.
         const controller = new AbortController();
-        // If a parent abort signal exists in scratch, forward its abort to ours.
+        // If a parent abort signal exists in scratch (e.g. from a graph-level timeout
+        // or manual cancellation), forward its abort to our internal controller so that
+        // the voice session is cancelled when the parent cancels.
         const parentSignal = state?.scratch?.abortSignal;
         if (parentSignal) {
-            parentSignal.addEventListener('abort', () => controller.abort(parentSignal.reason), { once: true });
+            parentSignal.addEventListener('abort', () => controller.abort(parentSignal.reason), {
+                once: true,
+            });
         }
-        // Voice transport must be pre-placed in state.scratch by the graph runtime.
+        // The voice transport must be pre-placed in state.scratch by the graph runtime
+        // or VoiceTransportAdapter before executing a voice node. Without it we cannot
+        // receive session events or detect hangup.
         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.
+        // Check for checkpoint restore -- if the node was previously executed and the
+        // graph was suspended/restored, the prior turn count is in the checkpoint.
+        // This lets the turn counter continue from where it left off rather than
+        // resetting to zero, which would cause premature exits on maxTurns.
         const checkpoint = state?.scratch?.[node.id];
         const initialTurnCount = checkpoint?.turnIndex ?? 0;
-        // Emit session lifecycle event: started.
+        // Signal that the voice session is now active for this node.
         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.
+            // In production this is the VoicePipelineSession; in tests it can be a
+            // plain EventEmitter. Fallback to a fresh emitter avoids null dereferences
+            // when the transport doesn't have an attached session.
             const session = transport._voiceSession ?? new EventEmitter();
-            // Create the turn collector — it subscribes to session events and buffers transcript.
+            // Create the turn collector -- it subscribes to session events (interim_transcript,
+            // final_transcript, turn_complete, barge_in) and bridges them into GraphEvents
+            // while maintaining a running transcript buffer and turn counter.
             const collector = new VoiceTurnCollector(session, this.eventSink, node.id, initialTurnCount);
-            // Race all exit conditions against each other.
+            // Race all exit conditions against each other. The first condition to fire
+            // determines exitReason and ends the voice node.
             const result = await this.raceExitConditions(session, collector, voiceConfig, controller, transport);
-            // Resolve exitReason → routeTarget from node edges.
+            // Map the exitReason string to a target node id using the edge map.
+            // This is how voice nodes implement conditional routing: different exit
+            // conditions route to different downstream nodes.
             const edges = node.edges ?? {};
             const routeTarget = typeof edges === 'object' ? edges[result.reason] : undefined;
-            // Build checkpoint for scratch so the runtime can persist/restore later.
+            // Build the checkpoint so the runtime can persist and restore later.
+            // This is written into scratchUpdate and merged back into state.scratch
+            // by the graph runtime after execution completes.
             const voiceCheckpoint = {
                 turnIndex: collector.getTurnCount(),
                 transcript: collector.getTranscript(),
@@ -106,8 +165,13 @@ export class VoiceNodeExecutor {
                 speakerMap: {},
                 sessionConfig: voiceConfig,
             };
-            // Emit session lifecycle event: ended.
-            this.eventSink({ type: 'voice_session', nodeId: node.id, action: 'ended', exitReason: result.reason });
+            // Signal that the voice session has ended for this node.
+            this.eventSink({
+                type: 'voice_session',
+                nodeId: node.id,
+                action: 'ended',
+                exitReason: result.reason,
+            });
             return {
                 success: true,
                 output: {
@@ -122,12 +186,19 @@ export class VoiceNodeExecutor {
             };
         }
         catch (err) {
-            // VoiceInterruptError is a structured barge-in — treat as a successful exit
-            // with exitReason: 'interrupted' so the graph can route accordingly.
+            // VoiceInterruptError is a structured barge-in -- the user spoke over the
+            // agent. This is not an error condition; it's a valid exit path that the
+            // graph should be able to route on. We convert it to a successful result
+            // with exitReason: 'interrupted' so edge routing works as expected.
             if (err instanceof VoiceInterruptError) {
                 const edges = node.edges ?? {};
                 const routeTarget = edges['interrupted'];
-                this.eventSink({ type: 'voice_session', nodeId: node.id, action: 'ended', exitReason: 'interrupted' });
+                this.eventSink({
+                    type: 'voice_session',
+                    nodeId: node.id,
+                    action: 'ended',
+                    exitReason: 'interrupted',
+                });
                 return {
                     success: true,
                     output: {
@@ -140,8 +211,14 @@ export class VoiceNodeExecutor {
                     routeTarget,
                 };
             }
-            // Unhandled error — surface as a failed result.
-            this.eventSink({ type: 'voice_session', nodeId: node.id, action: 'ended', exitReason: 'error' });
+            // Unhandled error -- surface as a failed result so the graph runtime can
+            // decide whether to retry, reroute, or halt.
+            this.eventSink({
+                type: 'voice_session',
+                nodeId: node.id,
+                action: 'ended',
+                exitReason: 'error',
+            });
             return { success: false, error: String(err) };
         }
     }
@@ -152,25 +229,42 @@ export class VoiceNodeExecutor {
      * 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' }`.
+     * ## How it works
+     *
+     * Each exit condition is wired as a listener on either the `session` or
+     * `transport` EventEmitter. All listeners call a shared `settleWith()` helper
+     * that resolves the outer Promise exactly once (guarded by a `settled` boolean).
+     *
+     * The `AbortController` signal is also monitored -- if it fires with a
+     * {@link VoiceInterruptError} the Promise rejects (handled by the caller's
+     * catch block), otherwise it resolves with `{ reason: 'interrupted' }`.
+     *
+     * ## Why a Promise race instead of a state machine?
+     *
+     * The exit conditions are independent and asynchronous. A Promise-based race
+     * avoids complex state transitions and lets each condition be a simple
+     * event listener. The `settled` guard handles the only tricky case: two
+     * conditions firing in the same microtask.
      *
-     * @param session    - Voice pipeline session EventEmitter.
-     * @param collector  - Active turn collector tracking turn count.
-     * @param config     - Voice node configuration with exit settings.
+     * @param session    - Voice pipeline session EventEmitter that fires
+     *                     `turn_complete`, `final_transcript`, `speech_start`, `barge_in`.
+     * @param collector  - Active turn collector tracking turn count and transcript.
+     * @param config     - Voice node configuration with exit settings (`maxTurns`,
+     *                     `exitOn`, `exitKeywords`).
      * @param controller - Internal AbortController for barge-in signalling.
-     * @param transport  - Bidirectional transport EventEmitter.
+     * @param transport  - Bidirectional transport EventEmitter that fires `close`
+     *                     and `disconnected` on hangup.
      * @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. */
+            /** Prevents double-resolution when multiple conditions fire simultaneously. */
             let settled = false;
             /**
              * Settle the promise with a resolve value, guarding against double-settle.
-             * @param result - The exit condition result.
+             * Every exit condition calls this instead of `resolve()` directly.
+             *
+             * @param result - The exit condition result containing the reason string.
              */
             const settleWith = (result) => {
                 if (settled)
@@ -179,10 +273,16 @@ export class VoiceNodeExecutor {
                 resolve(result);
             };
             // -- Hangup: transport disconnects -----------------------------------
+            // Both `close` and `disconnected` events indicate the transport is gone.
+            // We listen for both because different transport implementations emit
+            // different event names (WebSocket uses `close`, telephony uses `disconnected`).
             const onDisconnect = () => settleWith({ reason: 'hangup' });
             transport.on('close', onDisconnect);
             transport.on('disconnected', onDisconnect);
             // -- Turns exhausted -------------------------------------------------
+            // Only armed when maxTurns is a positive number. We check the collector's
+            // count (not a local counter) because the collector may have been seeded
+            // with an initialTurnCount from a checkpoint restore.
             if (config.maxTurns && config.maxTurns > 0) {
                 session.on('turn_complete', () => {
                     if (collector.getTurnCount() >= config.maxTurns) {
@@ -191,6 +291,9 @@ export class VoiceNodeExecutor {
                 });
             }
             // -- Keyword detection -----------------------------------------------
+            // Only armed when exitOn is 'keyword' and at least one keyword is provided.
+            // The keyword check is case-insensitive and uses substring matching so that
+            // "goodbye" matches "okay goodbye then".
             if (config.exitOn === 'keyword' && config.exitKeywords?.length) {
                 session.on('final_transcript', (evt) => {
                     const text = (evt.text ?? '').toLowerCase();
@@ -203,20 +306,29 @@ export class VoiceNodeExecutor {
                 });
             }
             // -- Silence timeout (default 30 s) ----------------------------------
+            // Only armed when exitOn is 'silence-timeout'. A watchdog timer is reset
+            // on every speech activity event. If the timer fires without being reset,
+            // the user has been silent for too long and the session ends.
             if (config.exitOn === 'silence-timeout') {
                 let silenceTimer = null;
                 const timeoutMs = 30000;
-                /** Reset the silence watchdog — called on any speech activity. */
+                /** Reset the silence watchdog -- called on any speech activity. */
                 const resetTimer = () => {
                     if (silenceTimer)
                         clearTimeout(silenceTimer);
                     silenceTimer = setTimeout(() => settleWith({ reason: 'silence-timeout' }), timeoutMs);
                 };
+                // Reset on both speech_start (user began talking) and turn_complete
+                // (user finished a turn) to cover all speech activity signals.
                 session.on('speech_start', resetTimer);
                 session.on('turn_complete', resetTimer);
                 resetTimer(); // Start the initial timer immediately.
             }
             // -- Abort signal (barge-in or parent cancellation) ------------------
+            // If the abort reason is a VoiceInterruptError, we reject the Promise
+            // (the caller's catch block converts it to exitReason: 'interrupted').
+            // For any other abort reason (e.g. parent timeout), we resolve normally
+            // with reason: 'interrupted'.
             controller.signal.addEventListener('abort', () => {
                 const reason = controller.signal.reason;
                 if (reason instanceof VoiceInterruptError) {

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

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

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

@@ -3,16 +3,28 @@
  * @description Bridges graph I/O to the voice pipeline when a workflow runs in
  * voice transport mode.
  *
+ * ## Purpose
+ *
  * `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.
+ * ## `getNodeInput` / `deliverNodeOutput` contract
+ *
+ * - `getNodeInput(nodeId)` blocks until the transport emits a `turn_complete`
+ *   event, then resolves with the transcript string. It also emits a
+ *   `voice_turn_complete` GraphEvent so the runtime event bus stays in sync.
+ * - `deliverNodeOutput(nodeId, output)` sends text (or a streaming async
+ *   iterable) to TTS and emits a `voice_audio` outbound GraphEvent.
+ * - Both methods throw if called before `init()`.
+ *
+ * ## Lazy initialisation
+ *
+ * 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
@@ -27,6 +39,9 @@
  * await adapter.deliverNodeOutput('greet', 'Hello, how can I help you today?');
  * await adapter.dispose();
  * ```
+ *
+ * See `VoiceNodeExecutor` for the executor that consumes this adapter's events.
+ * @see {@link VoiceTransportConfig} -- configuration knobs forwarded to the pipeline.
  */
 import type { GraphState } from '../ir/types.js';
 import type { GraphEvent } from '../events/GraphEvent.js';
@@ -34,8 +49,21 @@ import type { GraphEvent } from '../events/GraphEvent.js';
  * Configuration knobs forwarded to the voice pipeline when the adapter
  * initialises its internal `VoicePipelineOrchestrator` instance.
  *
- * All fields are optional — defaults are resolved from agent.config.json or
- * sensible library defaults.
+ * All fields are optional -- defaults are resolved from agent.config.json or
+ * sensible library defaults within the voice pipeline itself.
+ *
+ * @example
+ * ```ts
+ * const config: VoiceTransportConfig = {
+ *   stt: 'deepgram',
+ *   tts: 'elevenlabs',
+ *   voice: 'rachel',
+ *   bargeIn: 'hard-cut',
+ *   endpointing: 'semantic',
+ *   diarization: true,
+ *   language: 'en-US',
+ * };
+ * ```
  */
 export interface VoiceTransportConfig {
     /** STT provider identifier (e.g. `'deepgram'`, `'openai'`). */
@@ -46,16 +74,16 @@ export interface VoiceTransportConfig {
     voice?: string;
     /**
      * Barge-in handling strategy.
-     * - `'hard-cut'`  — interrupt TTS immediately when speech is detected.
-     * - `'soft-fade'` — ramp TTS volume down before cutting.
-     * - `'disabled'`  — ignore user speech while the agent is speaking.
+     * - `'hard-cut'`  -- interrupt TTS immediately when speech is detected.
+     * - `'soft-fade'` -- ramp TTS volume down before cutting.
+     * - `'disabled'`  -- ignore user speech while the agent is speaking.
      */
     bargeIn?: string;
     /**
      * Endpoint detection mode used to decide when the user has finished speaking.
-     * - `'acoustic'`  — energy/VAD-based detection.
-     * - `'heuristic'` — punctuation + silence heuristics.
-     * - `'semantic'`  — LLM-assisted turn boundary detection.
+     * - `'acoustic'`  -- energy/VAD-based detection.
+     * - `'heuristic'` -- punctuation + silence heuristics.
+     * - `'semantic'`  -- LLM-assisted turn boundary detection.
      */
     endpointing?: string;
     /** Whether to enable speaker diarization for multi-speaker sessions. */
@@ -66,13 +94,26 @@ export interface VoiceTransportConfig {
 /**
  * Adapts a compiled graph's I/O cycle to the real-time voice pipeline.
  *
- * Lifecycle:
+ * ## Lifecycle
+ *
  * 1. Construct with {@link VoiceTransportConfig}, an `IStreamTransport`, and an
  *    event sink callback.
- * 2. Call `init()` once before the graph starts running.
+ * 2. Call `init()` once before the graph starts running. This injects the
+ *    transport into `state.scratch.voiceTransport` and emits a `voice_session`
+ *    started event.
  * 3. Use `getNodeInput()` to obtain the user's transcribed speech for a node.
+ *    Blocks until the transport emits a `turn_complete` event.
  * 4. Use `deliverNodeOutput()` to send the node's response to TTS.
  * 5. Call `dispose()` to clean up resources when the session ends.
+ *
+ * ## Error handling
+ *
+ * Both `getNodeInput()` and `deliverNodeOutput()` throw `Error` if called
+ * before `init()`. After `dispose()`, the adapter is marked as uninitialised
+ * so subsequent calls also throw.
+ *
+ * @see {@link VoiceTransportConfig} -- the config shape forwarded to the pipeline.
+ * See `VoiceNodeExecutor` for the executor that interacts with the transport.
  */
 export declare class VoiceTransportAdapter {
     private readonly config;
@@ -84,24 +125,35 @@ export declare class VoiceTransportAdapter {
      * In a full implementation this would be `VoicePipelineOrchestrator | null`.
      */
     private pipeline;
-    /** Tracks whether `init()` has been called successfully. */
+    /**
+     * Tracks whether `init()` has been called successfully.
+     * Set to `false` by `dispose()` to prevent use-after-teardown.
+     */
     private initialized;
     /**
-     * @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.
+     * Creates a new VoiceTransportAdapter.
+     *
+     * @param config     - Voice pipeline configuration knobs. Forwarded to the
+     *                     pipeline when it is initialised.
+     * @param transport  - Bidirectional audio/control stream transport
+     *                     (`IStreamTransport`). Must be an EventEmitter that
+     *                     emits `turn_complete` events for `getNodeInput()`.
+     * @param eventSink  - Callback receiving all `GraphEvent` values emitted by
+     *                     this adapter. Must not throw.
      */
     constructor(config: VoiceTransportConfig, transport: any, // IStreamTransport
     eventSink: (event: GraphEvent) => void);
     /**
      * 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.
+     * Injects the `IStreamTransport` instance into `state.scratch.voiceTransport`
+     * so that voice graph nodes (specifically `VoiceNodeExecutor`) can access
+     * the transport for session event subscription. 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}.
+     * Must be called exactly once before `getNodeInput()` or
+     * `deliverNodeOutput()`. Calling `init()` multiple times is safe but
+     * redundant -- the transport reference is simply overwritten.
      *
      * @param state - Mutable `GraphState` (or partial) for the current run.
      *               `state.scratch` is created lazily if absent.
@@ -111,39 +163,46 @@ export declare class VoiceTransportAdapter {
      * 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
+     * `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.
+     * runtime event bus stays in sync with the transport-level turn lifecycle.
      *
-     * @param nodeId - The id of the graph node requesting input; used to tag the emitted event.
+     * @param nodeId - The id of the graph node requesting input; used to tag the
+     *                emitted event for downstream filtering.
      * @returns Resolved transcript string from the user's speech turn.
-     * @throws {Error} If called before `init()`.
+     * @throws {Error} If called before `init()` or after `dispose()`.
      */
     getNodeInput(nodeId: string): Promise<string>;
     /**
      * 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
+     * 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()`.
+     * @param nodeId - The id of the graph node delivering the output; tags the
+     *                emitted event for downstream filtering.
+     * @param _output - Text or async token stream to synthesise as speech.
+     *                 The underscore prefix indicates it is not yet consumed
+     *                 in the v1 stub implementation.
+     * @throws {Error} If called before `init()` or after `dispose()`.
      */
     deliverNodeOutput(nodeId: string, _output: string | AsyncIterable<string>): Promise<void>;
     /**
      * 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).
+     * 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,
+     * stop TTS playback, or reroute the graph).
+     *
+     * @see {@link VoiceInterruptError} -- the structured error used inside the graph executor.
      */
     handleBargeIn(): void;
     /**
@@ -151,6 +210,9 @@ export declare class VoiceTransportAdapter {
      *
      * Marks the adapter as uninitialised so subsequent calls to `getNodeInput()`
      * or `deliverNodeOutput()` will throw, preventing accidental use after teardown.
+     *
+     * This method is idempotent -- calling it multiple times simply re-emits the
+     * ended event and re-sets the initialised flag.
      */
     dispose(): Promise<void>;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"VoiceTransportAdapter.d.ts","sourceRoot":"","sources":["../../../src/orchestration/runtime/VoiceTransportAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAM1D;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;;;;GAUG;AACH,qBAAa,qBAAqB;IAiB9B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAlB5B;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAoB;IAEpC,4DAA4D;IAC5D,OAAO,CAAC,WAAW,CAAS;IAE5B;;;;OAIG;gBAEgB,MAAM,EAAE,oBAAoB,EAC5B,SAAS,EAAE,GAAG,EAAE,mBAAmB;IACnC,SAAS,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI;IAOzD;;;;;;;;;;;;OAYG;IACG,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAarD;;;;;;;;;;;;;;OAcG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAwBnD;;;;;;;;;;;;;OAaG;IACG,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB/F;;;;;;OAMG;IACH,aAAa,IAAI,IAAI;IAarB;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAS/B"}
+{"version":3,"file":"VoiceTransportAdapter.d.ts","sourceRoot":"","sources":["../../../src/orchestration/runtime/VoiceTransportAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAM1D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,oBAAoB;IACnC,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,wEAAwE;IACxE,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,qBAAqB;IA0B9B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS;IA3B5B;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAoB;IAEpC;;;OAGG;IACH,OAAO,CAAC,WAAW,CAAS;IAE5B;;;;;;;;;;OAUG;gBAEgB,MAAM,EAAE,oBAAoB,EAC5B,SAAS,EAAE,GAAG,EAAE,mBAAmB;IACnC,SAAS,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI;IAOzD;;;;;;;;;;;;;;OAcG;IACG,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAcrD;;;;;;;;;;;;;;;OAeG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA2BnD;;;;;;;;;;;;;;;;OAgBG;IACG,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB/F;;;;;;;;;OASG;IACH,aAAa,IAAI,IAAI;IAarB;;;;;;;;OAQG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAS/B"}