@framers/agentos 0.1.112 → 0.1.113

package/dist/orchestration/runtime/VoiceTurnCollector.js

@@ -3,22 +3,28 @@
  * @description Subscribes to voice pipeline session events and maintains a
  * running transcript buffer, turn counter, and last-speaker tracker.
  *
+ * ## Event bridging strategy
+ *
  * 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.
+ * | Session event        | GraphEvent emitted       | Buffered? | Why                                                    |
+ * |----------------------|--------------------------|-----------|--------------------------------------------------------|
+ * | `interim_transcript` | `voice_transcript`       | No        | Partials are noisy and would duplicate final entries.   |
+ * | `final_transcript`   | `voice_transcript`       | Yes       | Confirmed utterances form the canonical transcript.     |
+ * | `turn_complete`      | `voice_turn_complete`    | N/A       | Marks endpoint detection; advances the turn counter.    |
+ * | `barge_in`           | `voice_barge_in`         | N/A       | Signals user interruption for downstream handlers.      |
+ *
+ * ## Checkpoint restore
  *
  * 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.
+ * from where the session left off rather than resetting to zero. This is
+ * critical for `maxTurns` enforcement across graph suspensions.
+ *
+ * @see {@link VoiceNodeExecutor} -- creates and owns the collector during voice node execution.
+ * @see {@link VoiceNodeCheckpoint} -- persists `turnIndex` and `transcript` across suspensions.
  */
 // ---------------------------------------------------------------------------
 // VoiceTurnCollector
@@ -27,6 +33,11 @@
  * Stateful collector that subscribes to a voice pipeline session and routes
  * session events into the AgentOS `GraphEvent` stream.
  *
+ * The collector is designed to be short-lived -- created at the start of a
+ * voice node execution and discarded when the node completes. Its state
+ * (transcript, turn count, last speaker) is captured into a
+ * {@link VoiceNodeCheckpoint} by the executor before disposal.
+ *
  * @example
  * ```ts
  * const collector = new VoiceTurnCollector(
@@ -40,25 +51,49 @@
  * console.log(collector.getTranscript());  // full buffered transcript
  * console.log(collector.getLastSpeaker()); // last identified speaker
  * ```
+ *
+ * @see {@link TranscriptEntry} -- shape of each buffered transcript entry.
+ * @see {@link VoiceNodeExecutor} -- the executor that creates and queries the collector.
  */
 export class VoiceTurnCollector {
     /**
+     * Creates a new VoiceTurnCollector and immediately subscribes to session events.
+     *
+     * Subscription is performed in the constructor (rather than a separate `init()`
+     * method) because the collector has no meaningful state before subscription and
+     * there is no cleanup/unsubscribe lifecycle -- the session EventEmitter is
+     * short-lived and garbage-collected with the collector.
+     *
      * @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.
+     *                           Must emit `interim_transcript`, `final_transcript`,
+     *                           `turn_complete`, and `barge_in` events.
+     * @param eventSink        - Callback invoked synchronously for every emitted
+     *                           `GraphEvent`. Must not throw -- exceptions would
+     *                           propagate into the session event loop.
+     * @param nodeId           - Identifies the owning graph node in every emitted
+     *                           event, enabling consumers to filter events by node.
+     * @param initialTurnCount - Seed value for `turnCount`; pass a persisted value
+     *                           to resume from a checkpoint rather than starting at
+     *                           zero. Defaults to `0`.
      */
     constructor(session, eventSink, nodeId, initialTurnCount = 0) {
         this.eventSink = eventSink;
         this.nodeId = nodeId;
-        /** Buffered confirmed utterances in chronological order. */
+        /** Buffered confirmed utterances in chronological order. Append-only. */
         this.transcript = [];
-        /** Speaker identifier from the most recent `final_transcript` event. */
+        /**
+         * Speaker identifier from the most recent `final_transcript` event.
+         * Empty string until the first final transcript arrives.
+         */
         this.lastSpeaker = '';
         this.turnCount = initialTurnCount;
         // ------------------------------------------------------------------
-        // interim_transcript — partial STT result, forwarded but not buffered
+        // interim_transcript -- partial STT result, forwarded but NOT buffered.
+        //
+        // Why not buffer? Interim transcripts are speculative and frequently
+        // revised by the STT engine. Buffering them would produce duplicate
+        // or contradictory entries. They are forwarded as events so that UIs
+        // can show live typing indicators.
         // ------------------------------------------------------------------
         session.on('interim_transcript', (evt) => {
             this.eventSink({
@@ -71,17 +106,26 @@ export class VoiceTurnCollector {
             });
         });
         // ------------------------------------------------------------------
-        // final_transcript — confirmed utterance, buffered and forwarded
+        // final_transcript -- confirmed utterance, buffered AND forwarded.
+        //
+        // This is the canonical source of truth for what was said. Every
+        // confirmed utterance is appended to the transcript buffer and the
+        // last-speaker tracker is updated.
         // ------------------------------------------------------------------
         session.on('final_transcript', (evt) => {
+            // Default speaker to 'user' when the STT service doesn't provide
+            // diarization labels. This matches the most common single-speaker
+            // scenario where the only speaker is the human user.
             const speaker = evt.speaker ?? 'user';
-            // Buffer the confirmed entry for downstream consumers.
+            // Buffer the confirmed entry for downstream consumers (checkpoint,
+            // summarisation, analytics).
             this.transcript.push({
                 speaker,
                 text: evt.text ?? '',
                 timestamp: Date.now(),
             });
-            // Track the most recent speaker for quick access without iterating the buffer.
+            // Track the most recent speaker for quick access without iterating
+            // the entire buffer. Used by the executor to populate the result.
             this.lastSpeaker = speaker;
             this.eventSink({
                 type: 'voice_transcript',
@@ -93,10 +137,14 @@ export class VoiceTurnCollector {
             });
         });
         // ------------------------------------------------------------------
-        // turn_complete — endpoint detection fired; advance the turn counter
+        // turn_complete -- endpoint detection fired; advance the turn counter.
+        //
+        // The counter is incremented BEFORE emitting the event so that the
+        // turnIndex in the emitted event reflects the new (post-increment)
+        // count. This matches the semantics expected by VoiceNodeExecutor's
+        // maxTurns check, which reads getTurnCount() after the event fires.
         // ------------------------------------------------------------------
         session.on('turn_complete', (evt) => {
-            // Increment before emitting so that turnIndex reflects the new count.
             this.turnCount++;
             this.eventSink({
                 type: 'voice_turn_complete',
@@ -107,7 +155,13 @@ export class VoiceTurnCollector {
             });
         });
         // ------------------------------------------------------------------
-        // barge_in — user interrupted agent mid-speech
+        // barge_in -- user interrupted agent mid-speech.
+        //
+        // This event does not affect the turn count or transcript buffer
+        // because the interruption itself is not a complete utterance. The
+        // interrupted text (what the agent was saying) and the user's speech
+        // (what triggered the interruption) are forwarded for downstream
+        // handlers to process.
         // ------------------------------------------------------------------
         session.on('barge_in', (evt) => {
             this.eventSink({
@@ -124,6 +178,8 @@ export class VoiceTurnCollector {
     /**
      * Returns the total number of completed turns since construction (or since the
      * provided `initialTurnCount` when restoring from a checkpoint).
+     *
+     * @returns The current turn count. Always >= `initialTurnCount`.
      */
     getTurnCount() {
         return this.turnCount;
@@ -132,7 +188,10 @@ export class VoiceTurnCollector {
      * 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.
+     * buffer -- entries are append-only and must remain in chronological order
+     * for correct checkpoint persistence.
+     *
+     * @returns A new array containing all confirmed transcript entries in order.
      */
     getTranscript() {
         return [...this.transcript];
@@ -140,6 +199,8 @@ export class VoiceTurnCollector {
     /**
      * Returns the speaker identifier from the most recent `final_transcript` event,
      * or an empty string if no final transcript has been received yet.
+     *
+     * @returns The last speaker label, or `''` if none.
      */
     getLastSpeaker() {
         return this.lastSpeaker;

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@framers/agentos",
-  "version": "0.1.112",
+  "version": "0.1.113",
   "description": "Modular AgentOS orchestration library",
   "type": "module",
   "main": "dist/index.js",