@framers/agentos 0.1.112 → 0.1.114

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

@@ -22,7 +22,7 @@ export interface LoopConfig {
     maxIterations: number;
     /**
      * When `true`, all tool calls within a single iteration are dispatched in
-     * parallel via `Promise.allSettled`. When `false`, they execute sequentially.
+     * parallel via `Promise.allSettled()`. When `false`, they execute sequentially.
      */
     parallelTools: boolean;
     /**
@@ -45,7 +45,7 @@ export interface LoopConfig {
 export interface LoopContext {
     /**
      * Async generator that streams chunks during a single LLM inference pass.
-     * Must return a {@link LoopOutput} as its generator return value (the value
+     * Must return a `LoopOutput` as its generator return value (the value
      * passed to the final `done: true` result from `.next()`).
      */
     generateStream: () => AsyncGenerator<LoopChunk, LoopOutput, undefined>;
@@ -76,7 +76,7 @@ export interface LoopToolCallRequest {
  * The outcome of executing a {@link LoopToolCallRequest}.
  */
 export interface LoopToolCallResult {
-    /** Matches the originating {@link LoopToolCallRequest.id}. */
+    /** Matches the originating `LoopToolCallRequest.id`. */
     id: string;
     /** Name of the tool that was called. */
     name: string;

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

@@ -1 +1 @@
-{"version":3,"file":"LoopController.d.ts","sourceRoot":"","sources":["../../../src/orchestration/runtime/LoopController.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,iFAAiF;IACjF,aAAa,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAC;IAEvB;;;;OAIG;IACH,WAAW,EAAE,WAAW,GAAG,aAAa,CAAC;IAEzC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,cAAc,EAAE,MAAM,cAAc,CAAC,SAAS,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IAEvE;;;;OAIG;IACH,WAAW,EAAE,CAAC,QAAQ,EAAE,mBAAmB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAE5E;;;OAGG;IACH,cAAc,EAAE,CAAC,OAAO,EAAE,kBAAkB,EAAE,KAAK,IAAI,CAAC;CACzD;AAMD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,wFAAwF;IACxF,EAAE,EAAE,MAAM,CAAC;IAEX,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IAEb,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IAEX,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IAEb,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IAEjB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,IAAI,EAAE,YAAY,GAAG,mBAAmB,CAAC;IAEzC,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,mDAAmD;IACnD,SAAS,CAAC,EAAE,mBAAmB,EAAE,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,qDAAqD;IACrD,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,SAAS,EAAE,mBAAmB,EAAE,CAAC;IAEjC;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAMD;;;GAGG;AACH,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,SAAS,EAAE,mBAAmB,EAAE,CAAA;CAAE,GAC/D;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,GACrE;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,wBAAwB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAAC;AAMvD;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAc;IACzB;;;;;;;OAOG;IACI,OAAO,CACZ,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,WAAW,GACnB,cAAc,CAAC,SAAS,CAAC;CAuG7B"}
+{"version":3,"file":"LoopController.d.ts","sourceRoot":"","sources":["../../../src/orchestration/runtime/LoopController.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,iFAAiF;IACjF,aAAa,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAC;IAEvB;;;;OAIG;IACH,WAAW,EAAE,WAAW,GAAG,aAAa,CAAC;IAEzC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,cAAc,EAAE,MAAM,cAAc,CAAC,SAAS,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IAEvE;;;;OAIG;IACH,WAAW,EAAE,CAAC,QAAQ,EAAE,mBAAmB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAE5E;;;OAGG;IACH,cAAc,EAAE,CAAC,OAAO,EAAE,kBAAkB,EAAE,KAAK,IAAI,CAAC;CACzD;AAMD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,wFAAwF;IACxF,EAAE,EAAE,MAAM,CAAC;IAEX,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IAEb,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IAEX,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IAEb,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IAEjB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,IAAI,EAAE,YAAY,GAAG,mBAAmB,CAAC;IAEzC,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,mDAAmD;IACnD,SAAS,CAAC,EAAE,mBAAmB,EAAE,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,qDAAqD;IACrD,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,SAAS,EAAE,mBAAmB,EAAE,CAAC;IAEjC;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAMD;;;GAGG;AACH,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,SAAS,EAAE,mBAAmB,EAAE,CAAA;CAAE,GAC/D;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,GACrE;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,wBAAwB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAAC;AAMvD;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAc;IACzB;;;;;;;OAOG;IACI,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,GAAG,cAAc,CAAC,SAAS,CAAC;CAmGpF"}

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

@@ -1 +1 @@
-{"version":3,"file":"LoopController.js","sourceRoot":"","sources":["../../../src/orchestration/runtime/LoopController.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"LoopController.js","sourceRoot":"","sources":["../../../src/orchestration/runtime/LoopController.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAiKH,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,cAAc;IACzB;;;;;;;OAOG;IACH,KAAK,CAAC,CAAC,OAAO,CAAC,MAAkB,EAAE,OAAoB;QACrD,IAAI,SAAS,GAAG,CAAC,CAAC;QAElB,OAAO,SAAS,GAAG,MAAM,CAAC,aAAa,EAAE,CAAC;YACxC,SAAS,EAAE,CAAC;YAEZ,qEAAqE;YACrE,kEAAkE;YAClE,oEAAoE;YACpE,qDAAqD;YACrD,qEAAqE;YACrE,MAAM,GAAG,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;YACrC,IAAI,SAAiC,CAAC;YAEtC,OAAO,IAAI,EAAE,CAAC;gBACZ,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;gBAEzC,IAAI,IAAI,EAAE,CAAC;oBACT,0DAA0D;oBAC1D,SAAS,GAAG,KAAmB,CAAC;oBAChC,MAAM;gBACR,CAAC;gBAED,oCAAoC;gBACpC,MAAM,KAAK,GAAG,KAAkB,CAAC;gBAEjC,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;oBACjD,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;gBACvD,CAAC;gBAED,IAAI,KAAK,CAAC,IAAI,KAAK,mBAAmB,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;oBAC1D,MAAM,EAAE,IAAI,EAAE,mBAAmB,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;gBAClE,CAAC;YACH,CAAC;YAED,gDAAgD;YAChD,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACnD,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,eAAe,EAAE,SAAS,EAAE,CAAC;gBAC5D,OAAO;YACT,CAAC;YAED,qEAAqE;YACrE,0DAA0D;YAC1D,qEAAqE;YACrE,MAAM,SAAS,GAAG,SAAS,CAAC,SAAS,CAAC;YACtC,IAAI,OAA6B,CAAC;YAElC,IAAI,MAAM,CAAC,aAAa,EAAE,CAAC;gBACzB,oEAAoE;gBACpE,6DAA6D;gBAC7D,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;gBAEzF,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;oBAC7B,IAAI,CAAC,CAAC,MAAM,KAAK,WAAW;wBAAE,OAAO,CAAC,CAAC,KAAK,CAAC;oBAE7C,iEAAiE;oBACjE,kCAAkC;oBAClC,OAAO;wBACL,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE;wBACnB,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI;wBACvB,OAAO,EAAE,KAAK;wBACd,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;qBACxB,CAAC;gBACJ,CAAC,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,4DAA4D;gBAC5D,wDAAwD;gBACxD,OAAO,GAAG,EAAE,CAAC;gBACb,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;oBAC3B,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;oBAC7C,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACvB,CAAC;YACH,CAAC;YAED,qEAAqE;YACrE,iEAAiE;YACjE,qEAAqE;YACrE,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;oBACnB,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;gBAC/D,CAAC;qBAAM,CAAC;oBACN,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,IAAI,eAAe,CAAC;oBACjD,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;oBAErE,IAAI,MAAM,CAAC,WAAW,KAAK,aAAa,EAAE,CAAC;wBACzC,MAAM,IAAI,KAAK,CAAC,QAAQ,MAAM,CAAC,IAAI,0BAA0B,QAAQ,EAAE,CAAC,CAAC;oBAC3E,CAAC;oBACD,4DAA4D;gBAC9D,CAAC;YACH,CAAC;YAED,uEAAuE;YACvE,qDAAqD;YACrD,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QAClC,CAAC;QAED,iDAAiD;QACjD,MAAM,EAAE,IAAI,EAAE,wBAAwB,EAAE,SAAS,EAAE,MAAM,CAAC,aAAa,EAAE,CAAC;IAC5E,CAAC;CACF"}

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

@@ -35,13 +35,13 @@ export declare class StateManager {
     /**
      * @param reducers - Field-level reducer configuration keyed by dot-notation paths
      *                   (e.g. `'scratch.messages'`).  Determines how conflicting values
-     *                   are merged during {@link updateScratch} and {@link mergeParallelBranches}.
+     *                   are merged during `updateScratch()` and `mergeParallelBranches()`.
      */
     constructor(reducers: StateReducers);
     /**
      * Create a clean initial {@link GraphState} from the caller-supplied `input` value.
      *
-     * The `input` partition is frozen with {@link Object.freeze} so that no node can
+     * The `input` partition is frozen with `Object.freeze()` so that no node can
      * accidentally mutate it.  All other partitions start empty.
      *
      * @param input - Arbitrary value provided by the graph caller; becomes `state.input`.
@@ -67,7 +67,7 @@ export declare class StateManager {
      *
      * Artifact fields are intended for caller-facing outputs and are not subject to
      * reducer logic in this method.  If you need reducer-aware artifact merging, use
-     * {@link mergeParallelBranches} instead.
+     * `mergeParallelBranches()` instead.
      *
      * @param state - Current graph state (not mutated).
      * @param patch - Partial artifacts update emitted by a completed node.

package/dist/orchestration/runtime/StateManager.js

@@ -36,7 +36,7 @@ export class StateManager {
     /**
      * @param reducers - Field-level reducer configuration keyed by dot-notation paths
      *                   (e.g. `'scratch.messages'`).  Determines how conflicting values
-     *                   are merged during {@link updateScratch} and {@link mergeParallelBranches}.
+     *                   are merged during `updateScratch()` and `mergeParallelBranches()`.
      */
     constructor(reducers) {
         this.reducers = reducers;
@@ -47,7 +47,7 @@ export class StateManager {
     /**
      * Create a clean initial {@link GraphState} from the caller-supplied `input` value.
      *
-     * The `input` partition is frozen with {@link Object.freeze} so that no node can
+     * The `input` partition is frozen with `Object.freeze()` so that no node can
      * accidentally mutate it.  All other partitions start empty.
      *
      * @param input - Arbitrary value provided by the graph caller; becomes `state.input`.
@@ -99,7 +99,7 @@ export class StateManager {
      *
      * Artifact fields are intended for caller-facing outputs and are not subject to
      * reducer logic in this method.  If you need reducer-aware artifact merging, use
-     * {@link mergeParallelBranches} instead.
+     * `mergeParallelBranches()` instead.
      *
      * @param state - Current graph state (not mutated).
      * @param patch - Partial artifacts update emitted by a completed node.

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

@@ -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 type { GraphNode, GraphState, VoiceNodeConfig } from '../ir/types.js';
 import type { GraphEvent } from '../events/GraphEvent.js';
@@ -27,21 +40,44 @@ import type { NodeExecutionResult } from './NodeExecutor.js';
  * The graph runtime persists this structure so that a subsequent invocation of the
  * same voice node (e.g. after a graph loop or checkpoint restore) can continue the
  * conversation from `turnIndex` rather than resetting to zero.
+ *
+ * @example
+ * ```ts
+ * // Restoring from a checkpoint:
+ * const checkpoint = state.scratch['voice-1'] as VoiceNodeCheckpoint;
+ * const resumedTurnIndex = checkpoint.turnIndex; // e.g. 5
+ * ```
  */
 export interface VoiceNodeCheckpoint {
     /** Number of turns completed when the checkpoint was captured. */
     turnIndex: number;
-    /** Full transcript buffer at the time of checkpoint. */
+    /**
+     * Full transcript buffer at the time of checkpoint.
+     *
+     * Each entry records a confirmed (final) utterance with its speaker label
+     * and wall-clock timestamp, preserving the full conversation history for
+     * downstream summarisation or analytics.
+     */
     transcript: Array<{
         speaker: string;
         text: string;
         timestamp: number;
     }>;
-    /** Exit reason that caused the voice node to complete (`null` if still in progress). */
+    /**
+     * Exit reason that caused the voice node to complete.
+     * `null` when the checkpoint was captured mid-session (e.g. process crash).
+     */
     lastExitReason: string | null;
-    /** Maps diarization speaker labels to human-readable names (reserved for future use). */
+    /**
+     * Maps diarization speaker labels to human-readable names.
+     * Reserved for future use -- populated as an empty object today.
+     */
     speakerMap: Record<string, string>;
-    /** The voice config that was active when this checkpoint was created. */
+    /**
+     * The voice config that was active when this checkpoint was created.
+     * Stored so that a resumed session can verify config compatibility before
+     * continuing from the persisted turn index.
+     */
     sessionConfig: VoiceNodeConfig;
 }
 /**
@@ -49,55 +85,96 @@ export interface VoiceNodeCheckpoint {
  * 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 declare class VoiceNodeExecutor {
     private readonly eventSink;
     /**
+     * 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: (event: GraphEvent) => void);
     /**
      * 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.
      */
     execute(node: GraphNode, state: Partial<GraphState>): Promise<NodeExecutionResult>;
     /**
      * 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.
      */
     private raceExitConditions;

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

@@ -1 +1 @@
-{"version":3,"file":"VoiceNodeExecutor.d.ts","sourceRoot":"","sources":["../../../src/orchestration/runtime/VoiceNodeExecutor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAQ7D;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,UAAU,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxE,wFAAwF;IACxF,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,yFAAyF;IACzF,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,yEAAyE;IACzE,aAAa,EAAE,eAAe,CAAC;CAChC;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,iBAAiB;IAM1B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAL5B;;;OAGG;gBAEgB,SAAS,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI;IAGzD;;;;;;;;;;;OAWG;IACG,OAAO,CACX,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,GACzB,OAAO,CAAC,mBAAmB,CAAC;IA0G/B;;;;;;;;;;;;;;;OAeG;YACW,kBAAkB;CA2EjC"}
+{"version":3,"file":"VoiceNodeExecutor.d.ts","sourceRoot":"","sources":["../../../src/orchestration/runtime/VoiceNodeExecutor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAQ7D;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;;OAMG;IACH,UAAU,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAExE;;;OAGG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9B;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEnC;;;;OAIG;IACH,aAAa,EAAE,eAAe,CAAC;CAChC;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,iBAAiB;IAShB,OAAO,CAAC,QAAQ,CAAC,SAAS;IARtC;;;;;;;OAOG;gBAC0B,SAAS,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI;IAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAkJxF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;YACW,kBAAkB;CAmGjC"}