@framers/agentos 0.13.3 → 0.13.4

package/dist/io/hearing/LiveKitTranscriptionOutput.js

@@ -0,0 +1,108 @@
+/**
+ * @module hearing/LiveKitTranscriptionOutput
+ * Writes a speech-to-text session's transcripts into a LiveKit room the way
+ * LiveKit's own transcription output does, so a page's standard handler of the
+ * `lk.transcription` topic shows them: each interim and each final as a text
+ * stream holding the line's whole text, with `lk.segment_id` (the transcript's
+ * `itemId`), `lk.transcription_final` and `lk.transcribed_track_id`. Writes go
+ * out in the order they were asked for. The finals are kept in a
+ * {@link TranscriptLedger}, so a participant that reconnects can be sent again
+ * the finals after the last line it holds, a line taken back among them.
+ *
+ * The room is described by a structural type, so this module and its typings
+ * carry no dependency on `@livekit/rtc-node`; a connected rtc-node `Room` is
+ * passed as it is.
+ *
+ * @example
+ * ```typescript
+ * const output = new LiveKitTranscriptionOutput({ room, trackSid: () => heardTrack?.sid });
+ * sttSession.on('transcript', (event) => {
+ *   output.write(event).catch((error) => console.warn('transcript not sent', error));
+ * });
+ * // when the page says the last line it holds:
+ * await output.replayAfter(lastItemId, participantIdentity);
+ * ```
+ */
+import { LIVEKIT_TRANSCRIPTION_ATTRIBUTES, LIVEKIT_TRANSCRIPTION_TOPIC, TRANSCRIPTION_FAILED_ATTRIBUTE, TranscriptLedger, } from '../voice-pipeline/transcriptLedger.js';
+/** Transcripts written into a LiveKit room as transcription text streams. */
+export class LiveKitTranscriptionOutput {
+    constructor(options) {
+        this.options = options;
+        this.chain = Promise.resolve();
+        this.ledger = options.ledger ?? new TranscriptLedger();
+        this.topic = options.topic ?? LIVEKIT_TRANSCRIPTION_TOPIC;
+    }
+    /**
+     * Writes one transcript to every participant. Resolves `true` once it is
+     * sent, `false` when the ledger already held it (a repeated final, or an
+     * interim after the final), which sends nothing.
+     *
+     * The ledger takes the line before it is sent, so a send that fails leaves
+     * the line there: writing the same transcript again sends nothing, and
+     * {@link LiveKitTranscriptionOutput.replayAfter} sends a final again to a
+     * participant, as it does for one that rejoins.
+     *
+     * @param extra - `itemId` when the transcript carries none; `failed`, a short
+     *   reason, for a line the provider could not transcribe.
+     * @throws {RangeError} When neither the transcript nor `extra` gives a line id.
+     * @throws {Error} When the room has no local participant, or the send fails.
+     */
+    write(event, extra = {}) {
+        const itemId = extra.itemId ?? event.itemId;
+        if (!itemId) {
+            return Promise.reject(new RangeError('LiveKitTranscriptionOutput: the transcript has no itemId; pass one in the second argument'));
+        }
+        const changed = this.ledger.apply({
+            itemId,
+            text: event.text,
+            isFinal: event.isFinal,
+            ...(event.startMs !== undefined ? { startMs: event.startMs } : {}),
+            ...(event.endMs !== undefined ? { endMs: event.endMs } : {}),
+            ...(event.language !== undefined ? { language: event.language } : {}),
+            ...(extra.failed !== undefined ? { failed: extra.failed } : {}),
+        });
+        if (!changed)
+            return Promise.resolve(false);
+        const line = this.ledger.get(itemId);
+        return this.enqueue(() => this.send(line, undefined)).then(() => true);
+    }
+    /**
+     * Sends again, to one participant, the final lines after the line with the
+     * id, in order, a line taken back among them as its empty final, so a page
+     * that missed the retraction drops the line; every one of them when the id
+     * is `undefined` or unknown. Resolves how many were sent.
+     */
+    replayAfter(itemId, participantIdentity) {
+        const finals = this.ledger.finalsAfter(itemId, { takenBack: true });
+        return this.enqueue(async () => {
+            for (const line of finals)
+                await this.send(line, [participantIdentity]);
+            return finals.length;
+        });
+    }
+    enqueue(work) {
+        const next = this.chain.then(work, work);
+        this.chain = next.catch(() => undefined);
+        return next;
+    }
+    async send(line, destinationIdentities) {
+        const local = this.options.room.localParticipant;
+        if (!local)
+            throw new Error('LiveKitTranscriptionOutput: the room has no local participant; connect it first');
+        const attributes = {
+            [LIVEKIT_TRANSCRIPTION_ATTRIBUTES.segmentId]: line.itemId,
+            [LIVEKIT_TRANSCRIPTION_ATTRIBUTES.final]: line.isFinal ? 'true' : 'false',
+        };
+        const sid = this.options.trackSid?.();
+        if (sid)
+            attributes[LIVEKIT_TRANSCRIPTION_ATTRIBUTES.trackId] = sid;
+        if (line.failed)
+            attributes[TRANSCRIPTION_FAILED_ATTRIBUTE] = line.failed;
+        await local.sendText(line.text, {
+            topic: this.topic,
+            attributes,
+            ...(destinationIdentities ? { destinationIdentities } : {}),
+        });
+    }
+}
+//# sourceMappingURL=LiveKitTranscriptionOutput.js.map

package/dist/io/hearing/LiveKitTranscriptionOutput.js.map

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

package/dist/io/hearing/livekit.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @module hearing/livekit
+ *
+ * LiveKit for the hearing layer: transcripts written into a LiveKit room as
+ * LiveKit's own transcription text streams, by an agent that joined the room
+ * as a participant. It takes the host's connected `@livekit/rtc-node` `Room`,
+ * described by a structural type, so this entry imports no LiveKit package.
+ *
+ * @example
+ * ```typescript
+ * import { LiveKitTranscriptionOutput } from './livekit.js';
+ * ```
+ */
+export { LiveKitTranscriptionOutput, type LiveKitTranscriptionOutputOptions, type LiveKitTranscriptionRoomLike, } from './LiveKitTranscriptionOutput.js';
+//# sourceMappingURL=livekit.d.ts.map

package/dist/io/hearing/livekit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"livekit.d.ts","sourceRoot":"","sources":["../../../src/io/hearing/livekit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,0BAA0B,EAC1B,KAAK,iCAAiC,EACtC,KAAK,4BAA4B,GAClC,MAAM,iCAAiC,CAAC"}

package/dist/io/hearing/livekit.js

@@ -0,0 +1,15 @@
+/**
+ * @module hearing/livekit
+ *
+ * LiveKit for the hearing layer: transcripts written into a LiveKit room as
+ * LiveKit's own transcription text streams, by an agent that joined the room
+ * as a participant. It takes the host's connected `@livekit/rtc-node` `Room`,
+ * described by a structural type, so this entry imports no LiveKit package.
+ *
+ * @example
+ * ```typescript
+ * import { LiveKitTranscriptionOutput } from './livekit.js';
+ * ```
+ */
+export { LiveKitTranscriptionOutput, } from './LiveKitTranscriptionOutput.js';
+//# sourceMappingURL=livekit.js.map

package/dist/io/hearing/livekit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"livekit.js","sourceRoot":"","sources":["../../../src/io/hearing/livekit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,0BAA0B,GAG3B,MAAM,iCAAiC,CAAC"}

package/dist/io/voice-pipeline/browser.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @module @framers/agentos/io/voice-pipeline/browser
+ *
+ * The voice pipeline's browser entry: modules that import no Node built-in and
+ * no package, so a browser bundle can take them. The Node entry,
+ * `@framers/agentos/io/voice-pipeline`, carries all of this as well, with the
+ * providers, transports and orchestrator that run on a server.
+ *
+ * A test walks this entry's built module graph and fails on any import that
+ * is not one of the library's own modules, so a module added here keeps to
+ * that.
+ *
+ * @example
+ * ```typescript
+ * import { TranscriptLedger, transcriptEventFromLiveKit } from './browser.js';
+ * ```
+ */
+export { LIVEKIT_TRANSCRIPTION_ATTRIBUTES, LIVEKIT_TRANSCRIPTION_TOPIC, TRANSCRIPTION_FAILED_ATTRIBUTE, TranscriptLedger, transcriptEventFromLiveKit, type LedgerEvent, type LedgerItem, type TranscriptLedgerOptions, } from './transcriptLedger.js';
+//# sourceMappingURL=browser.d.ts.map

package/dist/io/voice-pipeline/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../src/io/voice-pipeline/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EACL,gCAAgC,EAChC,2BAA2B,EAC3B,8BAA8B,EAC9B,gBAAgB,EAChB,0BAA0B,EAC1B,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,uBAAuB,GAC7B,MAAM,uBAAuB,CAAC"}

package/dist/io/voice-pipeline/browser.js

@@ -0,0 +1,20 @@
+/**
+ * @module @framers/agentos/io/voice-pipeline/browser
+ *
+ * The voice pipeline's browser entry: modules that import no Node built-in and
+ * no package, so a browser bundle can take them. The Node entry,
+ * `@framers/agentos/io/voice-pipeline`, carries all of this as well, with the
+ * providers, transports and orchestrator that run on a server.
+ *
+ * A test walks this entry's built module graph and fails on any import that
+ * is not one of the library's own modules, so a module added here keeps to
+ * that.
+ *
+ * @example
+ * ```typescript
+ * import { TranscriptLedger, transcriptEventFromLiveKit } from './browser.js';
+ * ```
+ */
+// A live transcript as lines keyed by item id, and LiveKit's transcription streams read into it.
+export { LIVEKIT_TRANSCRIPTION_ATTRIBUTES, LIVEKIT_TRANSCRIPTION_TOPIC, TRANSCRIPTION_FAILED_ATTRIBUTE, TranscriptLedger, transcriptEventFromLiveKit, } from './transcriptLedger.js';
+//# sourceMappingURL=browser.js.map

package/dist/io/voice-pipeline/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../../src/io/voice-pipeline/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,iGAAiG;AACjG,OAAO,EACL,gCAAgC,EAChC,2BAA2B,EAC3B,8BAA8B,EAC9B,gBAAgB,EAChB,0BAA0B,GAI3B,MAAM,uBAAuB,CAAC"}

package/dist/io/voice-pipeline/index.d.ts

@@ -112,6 +112,7 @@ export { type HealthyProvider, type ProviderCapabilities, type HealthCheckResult
 export { CircuitBreaker, type BreakerState, type CircuitBreakerOptions, type StateChangeEvent, } from './CircuitBreaker.js';
 export { AudioRingBuffer, type AudioRingBufferOptions } from './AudioRingBuffer.js';
 export { TranscriptDedupe, type TranscriptObservation, type DedupeResult, } from './TranscriptDedupe.js';
+export { LIVEKIT_TRANSCRIPTION_ATTRIBUTES, LIVEKIT_TRANSCRIPTION_TOPIC, TRANSCRIPTION_FAILED_ATTRIBUTE, TranscriptLedger, transcriptEventFromLiveKit, type LedgerEvent, type LedgerItem, type TranscriptLedgerOptions, } from './transcriptLedger.js';
 export { VoiceMetricsReporter, type VoiceMetricEvent, type VoiceMetricListener, } from './VoiceMetricsReporter.js';
 export { createVoiceProvidersFromEnv, NoVoiceProvidersAvailableError, type VoiceProviderEnvConfig, type VoiceProviderBundle, } from './env-constructor.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/io/voice-pipeline/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/io/voice-pipeline/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AAIH,cAAc,YAAY,CAAC;AAG3B,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAGjF,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAGrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAGzE,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAGzE,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAG1F,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAG3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAG/D,OAAO,EACL,oBAAoB,EACpB,KAAK,0BAA0B,EAC/B,sBAAsB,EACtB,KAAK,4BAA4B,EACjC,sBAAsB,EACtB,KAAK,4BAA4B,EACjC,wBAAwB,EACxB,KAAK,8BAA8B,EACnC,wBAAwB,EACxB,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,GAC9B,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,2BAA2B,EAC3B,KAAK,iCAAiC,EACtC,qBAAqB,EACrB,KAAK,2BAA2B,GACjC,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,GAC5B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,cAAc,EACd,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,GACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EACL,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,YAAY,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,oBAAoB,EACpB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,GACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,2BAA2B,EAC3B,8BAA8B,EAC9B,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,GACzB,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/io/voice-pipeline/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AAIH,cAAc,YAAY,CAAC;AAG3B,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAGjF,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAGrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAGzE,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAGzE,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAG1F,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAG3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAG/D,OAAO,EACL,oBAAoB,EACpB,KAAK,0BAA0B,EAC/B,sBAAsB,EACtB,KAAK,4BAA4B,EACjC,sBAAsB,EACtB,KAAK,4BAA4B,EACjC,wBAAwB,EACxB,KAAK,8BAA8B,EACnC,wBAAwB,EACxB,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,GAC9B,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,2BAA2B,EAC3B,KAAK,iCAAiC,EACtC,qBAAqB,EACrB,KAAK,2BAA2B,GACjC,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,GAC5B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,cAAc,EACd,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,GACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EACL,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,YAAY,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,gCAAgC,EAChC,2BAA2B,EAC3B,8BAA8B,EAC9B,gBAAgB,EAChB,0BAA0B,EAC1B,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,uBAAuB,GAC7B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,oBAAoB,EACpB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,GACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,2BAA2B,EAC3B,8BAA8B,EAC9B,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,GACzB,MAAM,sBAAsB,CAAC"}

package/dist/io/voice-pipeline/index.js

@@ -124,6 +124,7 @@ export { defaultCapabilities, supportsLanguage, } from './HealthyProvider.js';
 export { CircuitBreaker, } from './CircuitBreaker.js';
 export { AudioRingBuffer } from './AudioRingBuffer.js';
 export { TranscriptDedupe, } from './TranscriptDedupe.js';
+export { LIVEKIT_TRANSCRIPTION_ATTRIBUTES, LIVEKIT_TRANSCRIPTION_TOPIC, TRANSCRIPTION_FAILED_ATTRIBUTE, TranscriptLedger, transcriptEventFromLiveKit, } from './transcriptLedger.js';
 export { VoiceMetricsReporter, } from './VoiceMetricsReporter.js';
 export { createVoiceProvidersFromEnv, NoVoiceProvidersAvailableError, } from './env-constructor.js';
 //# sourceMappingURL=index.js.map

package/dist/io/voice-pipeline/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/io/voice-pipeline/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AAEH,wDAAwD;AACxD,8EAA8E;AAC9E,cAAc,YAAY,CAAC;AAE3B,+DAA+D;AAC/D,OAAO,EAAE,iBAAiB,EAA0B,MAAM,sBAAsB,CAAC;AAEjF,4CAA4C;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAErE,6CAA6C;AAC7C,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,2CAA2C;AAC3C,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,oDAAoD;AACpD,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAE1F,gDAAgD;AAChD,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAE3E,yCAAyC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,qCAAqC;AACrC,OAAO,EACL,oBAAoB,EAEpB,sBAAsB,EAEtB,sBAAsB,EAEtB,wBAAwB,EAExB,wBAAwB,EACxB,iBAAiB,EAKjB,iBAAiB,GAKlB,MAAM,sBAAsB,CAAC;AAE9B,iDAAiD;AACjD,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,2BAA2B,EAE3B,qBAAqB,GAEtB,MAAM,sBAAsB,CAAC;AAE9B,wBAAwB;AACxB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,GAGpB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAIL,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,cAAc,GAIf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAA+B,MAAM,sBAAsB,CAAC;AACpF,OAAO,EACL,gBAAgB,GAGjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,oBAAoB,GAGrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,2BAA2B,EAC3B,8BAA8B,GAG/B,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/io/voice-pipeline/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AAEH,wDAAwD;AACxD,8EAA8E;AAC9E,cAAc,YAAY,CAAC;AAE3B,+DAA+D;AAC/D,OAAO,EAAE,iBAAiB,EAA0B,MAAM,sBAAsB,CAAC;AAEjF,4CAA4C;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAErE,6CAA6C;AAC7C,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,2CAA2C;AAC3C,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,oDAAoD;AACpD,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAE1F,gDAAgD;AAChD,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAE3E,yCAAyC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,qCAAqC;AACrC,OAAO,EACL,oBAAoB,EAEpB,sBAAsB,EAEtB,sBAAsB,EAEtB,wBAAwB,EAExB,wBAAwB,EACxB,iBAAiB,EAKjB,iBAAiB,GAKlB,MAAM,sBAAsB,CAAC;AAE9B,iDAAiD;AACjD,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,2BAA2B,EAE3B,qBAAqB,GAEtB,MAAM,sBAAsB,CAAC;AAE9B,wBAAwB;AACxB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,GAGpB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAIL,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,cAAc,GAIf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAA+B,MAAM,sBAAsB,CAAC;AACpF,OAAO,EACL,gBAAgB,GAGjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,gCAAgC,EAChC,2BAA2B,EAC3B,8BAA8B,EAC9B,gBAAgB,EAChB,0BAA0B,GAI3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,oBAAoB,GAGrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,2BAA2B,EAC3B,8BAA8B,GAG/B,MAAM,sBAAsB,CAAC"}

package/dist/io/voice-pipeline/transcriptLedger.d.ts

@@ -0,0 +1,139 @@
+/**
+ * @module voice-pipeline/transcriptLedger
+ * A live transcript as lines keyed by their item id. An interim replaces the
+ * line's earlier interim, a final closes the line, and a final that arrives
+ * again (a replay after a reconnect) or an interim after its final changes
+ * nothing; lines keep the order they were first seen in. An empty final with
+ * no failure takes a line back, and the ledger hides it. LiveKit carries
+ * transcripts as text streams on its `lk.transcription` topic with the
+ * attributes its own transcription output sets: `transcriptEventFromLiveKit()`
+ * reads one, and `LiveKitTranscriptionOutput`
+ * (`@framers/agentos/io/hearing/livekit`) writes them. The module imports
+ * nothing, its types included, so a browser bundle takes it from
+ * `@framers/agentos/io/voice-pipeline/browser` and a type check of it needs no
+ * Node types.
+ */
+/** LiveKit's topic for transcription text streams. */
+export declare const LIVEKIT_TRANSCRIPTION_TOPIC = "lk.transcription";
+/** The attributes LiveKit's own transcription output sets on each stream. */
+export declare const LIVEKIT_TRANSCRIPTION_ATTRIBUTES: {
+    /** The line's id; this library writes the transcript's `itemId` here. */
+    readonly segmentId: "lk.segment_id";
+    /** `'true'` on the line's final stream, `'false'` on an interim. */
+    readonly final: "lk.transcription_final";
+    /** The SID of the audio track the line was heard on. */
+    readonly trackId: "lk.transcribed_track_id";
+};
+/** The attribute this library adds to a line the provider could not transcribe, holding a short reason. */
+export declare const TRANSCRIPTION_FAILED_ATTRIBUTE = "agentos.transcription_failed";
+/** One line of a ledger. */
+export interface LedgerItem {
+    /** The line's id: the provider's item id. */
+    readonly itemId: string;
+    /** The line's text: the newest interim, or the final. */
+    readonly text: string;
+    /** `true` once the final arrived; the line no longer changes. */
+    readonly isFinal: boolean;
+    /** Start of the line on the session's audio clock, when the provider gives it. */
+    readonly startMs?: number;
+    /** End of the line on the session's audio clock, when the provider gives it. */
+    readonly endMs?: number;
+    /** The line's language, when the provider gives it. */
+    readonly language?: string;
+    /** Why the provider could not transcribe the line; its text is then empty. */
+    readonly failed?: string;
+}
+/**
+ * What a ledger takes: a transcript's text, finality and id, with the optional
+ * timing, language and failure. A `TranscriptEvent` fits it as it is; the shape
+ * is declared here so the browser entry's typings import nothing.
+ */
+export interface LedgerEvent {
+    /** The line's id: the provider's item id. An event without one changes nothing. */
+    itemId?: string;
+    /** The line's text: an interim's text so far, or the final text. */
+    text: string;
+    /** `true` on the line's final, `false` on an interim. */
+    isFinal: boolean;
+    /** Start of the line on the session's audio clock, when the provider gives it. */
+    startMs?: number;
+    /** End of the line on the session's audio clock, when the provider gives it. */
+    endMs?: number;
+    /** The line's language, when the provider gives it. */
+    language?: string;
+    /** Why the provider could not transcribe the line; its text is then empty. An empty reason counts as none. */
+    failed?: string;
+}
+/** Options of {@link TranscriptLedger}. */
+export interface TranscriptLedgerOptions {
+    /**
+     * The most lines held, a line taken back among them (it stays, hidden, so a
+     * later event for its id changes nothing and a replay carries it); beyond it
+     * the oldest final lines are dropped, never the line just applied nor a line
+     * still being heard, so while more lines than that are open the ledger holds
+     * them all.
+     * @defaultValue 20000
+     */
+    maxItems?: number;
+}
+/** A live transcript's lines keyed by item id, in the order first seen. */
+export declare class TranscriptLedger {
+    private readonly lines;
+    private readonly retracted;
+    private readonly maxItems;
+    /** @throws {RangeError} When `maxItems` is below 1. */
+    constructor(options?: TranscriptLedgerOptions);
+    /** How many lines the ledger shows. */
+    get size(): number;
+    /**
+     * Applies one transcript. Answers `true` when the ledger changed: a new
+     * line, a new interim text, the final, or a line taken back. An empty final
+     * with no failure takes back the text a line showed so far (a device
+     * session's retraction when it closes), and the line is hidden from then on.
+     * An event with no item id, a final for a line already final, an interim
+     * after the final, an interim with the same text and the retraction of a
+     * line never shown change nothing.
+     */
+    apply(event: LedgerEvent): boolean;
+    /** The line with the id (a line taken back answers its empty final), or `undefined`. */
+    get(itemId: string): LedgerItem | undefined;
+    /** Every line shown, in the order first seen; a line taken back is left out. */
+    items(): LedgerItem[];
+    /** The id of the last final line shown, or `undefined` when none is final. */
+    lastFinalId(): string | undefined;
+    /**
+     * The id a page that rejoins sends, so it is given every final it may lack: the last final line before the first
+     * line not yet final (a final that arrived out of order while the page was away comes after it), the last final
+     * when every line is final, `undefined` when none is. A final the page already holds comes again and is dropped.
+     */
+    resumeAfterId(): string | undefined;
+    /**
+     * The final lines shown after the line with the id, in order; every one of
+     * them when the id is `undefined` or unknown. With `takenBack`, a line taken
+     * back comes too, as its empty final in its place: what a participant that
+     * rejoins is sent again, so a page that missed the retraction drops the line.
+     */
+    finalsAfter(itemId: string | undefined, options?: {
+        takenBack?: boolean;
+    }): LedgerItem[];
+    /** The ledger as plain JSON. */
+    toJSON(): {
+        v: 1;
+        items: LedgerItem[];
+    };
+    /** A ledger from {@link TranscriptLedger.toJSON}'s output; a malformed line is skipped. */
+    static fromJSON(value: unknown, options?: TranscriptLedgerOptions): TranscriptLedger;
+    /**
+     * Drops the oldest final lines while the ledger is over its size, never the
+     * line just applied nor a line still being heard: a later final or
+     * retraction of an open line must find it, so open lines are held over the
+     * size until they close.
+     */
+    private trim;
+}
+/**
+ * Reads one LiveKit transcription stream (its text and attributes) as a
+ * {@link LedgerEvent}, or `null` when it carries no segment id.
+ */
+export declare function transcriptEventFromLiveKit(text: string, attributes: Readonly<Record<string, string>> | undefined): LedgerEvent | null;
+//# sourceMappingURL=transcriptLedger.d.ts.map

package/dist/io/voice-pipeline/transcriptLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcriptLedger.d.ts","sourceRoot":"","sources":["../../../src/io/voice-pipeline/transcriptLedger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,sDAAsD;AACtD,eAAO,MAAM,2BAA2B,qBAAqB,CAAC;AAE9D,6EAA6E;AAC7E,eAAO,MAAM,gCAAgC;IAC3C,yEAAyE;;IAEzE,oEAAoE;;IAEpE,wDAAwD;;CAEhD,CAAC;AAEX,2GAA2G;AAC3G,eAAO,MAAM,8BAA8B,iCAAiC,CAAC;AAE7E,4BAA4B;AAC5B,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,OAAO,EAAE,OAAO,CAAC;IACjB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8GAA8G;IAC9G,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,2CAA2C;AAC3C,MAAM,WAAW,uBAAuB;IACtC;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,2EAA2E;AAC3E,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IACvD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,uDAAuD;gBAC3C,OAAO,GAAE,uBAA4B;IAKjD,uCAAuC;IACvC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;IA0BlC,wFAAwF;IACxF,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI3C,gFAAgF;IAChF,KAAK,IAAI,UAAU,EAAE;IAIrB,8EAA8E;IAC9E,WAAW,IAAI,MAAM,GAAG,SAAS;IAMjC;;;;OAIG;IACH,aAAa,IAAI,MAAM,GAAG,SAAS;IASnC;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,UAAU,EAAE;IAM5F,gCAAgC;IAChC,MAAM,IAAI;QAAE,CAAC,EAAE,CAAC,CAAC;QAAC,KAAK,EAAE,UAAU,EAAE,CAAA;KAAE;IAIvC,2FAA2F;IAC3F,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,uBAA4B,GAAG,gBAAgB;IAqBxF;;;;;OAKG;IACH,OAAO,CAAC,IAAI;CAcb;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,GAAG,WAAW,GAAG,IAAI,CAQrI"}

package/dist/io/voice-pipeline/transcriptLedger.js

@@ -0,0 +1,192 @@
+/**
+ * @module voice-pipeline/transcriptLedger
+ * A live transcript as lines keyed by their item id. An interim replaces the
+ * line's earlier interim, a final closes the line, and a final that arrives
+ * again (a replay after a reconnect) or an interim after its final changes
+ * nothing; lines keep the order they were first seen in. An empty final with
+ * no failure takes a line back, and the ledger hides it. LiveKit carries
+ * transcripts as text streams on its `lk.transcription` topic with the
+ * attributes its own transcription output sets: `transcriptEventFromLiveKit()`
+ * reads one, and `LiveKitTranscriptionOutput`
+ * (`@framers/agentos/io/hearing/livekit`) writes them. The module imports
+ * nothing, its types included, so a browser bundle takes it from
+ * `@framers/agentos/io/voice-pipeline/browser` and a type check of it needs no
+ * Node types.
+ */
+/** LiveKit's topic for transcription text streams. */
+export const LIVEKIT_TRANSCRIPTION_TOPIC = 'lk.transcription';
+/** The attributes LiveKit's own transcription output sets on each stream. */
+export const LIVEKIT_TRANSCRIPTION_ATTRIBUTES = {
+    /** The line's id; this library writes the transcript's `itemId` here. */
+    segmentId: 'lk.segment_id',
+    /** `'true'` on the line's final stream, `'false'` on an interim. */
+    final: 'lk.transcription_final',
+    /** The SID of the audio track the line was heard on. */
+    trackId: 'lk.transcribed_track_id',
+};
+/** The attribute this library adds to a line the provider could not transcribe, holding a short reason. */
+export const TRANSCRIPTION_FAILED_ATTRIBUTE = 'agentos.transcription_failed';
+/** A live transcript's lines keyed by item id, in the order first seen. */
+export class TranscriptLedger {
+    /** @throws {RangeError} When `maxItems` is below 1. */
+    constructor(options = {}) {
+        this.lines = new Map();
+        this.retracted = new Set();
+        this.maxItems = options.maxItems ?? 20000;
+        if (!(this.maxItems >= 1))
+            throw new RangeError('TranscriptLedger: maxItems must be at least 1');
+    }
+    /** How many lines the ledger shows. */
+    get size() {
+        return this.lines.size - this.retracted.size;
+    }
+    /**
+     * Applies one transcript. Answers `true` when the ledger changed: a new
+     * line, a new interim text, the final, or a line taken back. An empty final
+     * with no failure takes back the text a line showed so far (a device
+     * session's retraction when it closes), and the line is hidden from then on.
+     * An event with no item id, a final for a line already final, an interim
+     * after the final, an interim with the same text and the retraction of a
+     * line never shown change nothing.
+     */
+    apply(event) {
+        const itemId = event.itemId;
+        if (!itemId)
+            return false;
+        const held = this.lines.get(itemId);
+        if (held?.isFinal)
+            return false;
+        // An empty reason is no reason: the LiveKit stream carries none, so a reader takes such a line back.
+        const failed = event.failed || undefined;
+        if (event.isFinal && event.text === '' && failed === undefined) {
+            if (held === undefined)
+                return false;
+            this.retracted.add(itemId);
+            this.lines.set(itemId, { itemId, text: '', isFinal: true });
+            this.trim(itemId);
+            return true;
+        }
+        if (!event.isFinal && held !== undefined && held.text === event.text)
+            return false;
+        const line = { itemId, text: event.text, isFinal: event.isFinal };
+        if (event.startMs !== undefined)
+            line.startMs = event.startMs;
+        if (event.endMs !== undefined)
+            line.endMs = event.endMs;
+        if (event.language !== undefined)
+            line.language = event.language;
+        if (failed !== undefined)
+            line.failed = failed;
+        // Setting a key a Map already holds keeps its place, so a line stays where it was first seen.
+        this.lines.set(itemId, line);
+        this.trim(itemId);
+        return true;
+    }
+    /** The line with the id (a line taken back answers its empty final), or `undefined`. */
+    get(itemId) {
+        return this.lines.get(itemId);
+    }
+    /** Every line shown, in the order first seen; a line taken back is left out. */
+    items() {
+        return [...this.lines.values()].filter((line) => !this.retracted.has(line.itemId));
+    }
+    /** The id of the last final line shown, or `undefined` when none is final. */
+    lastFinalId() {
+        let last;
+        for (const line of this.items())
+            if (line.isFinal)
+                last = line.itemId;
+        return last;
+    }
+    /**
+     * The id a page that rejoins sends, so it is given every final it may lack: the last final line before the first
+     * line not yet final (a final that arrived out of order while the page was away comes after it), the last final
+     * when every line is final, `undefined` when none is. A final the page already holds comes again and is dropped.
+     */
+    resumeAfterId() {
+        let last;
+        for (const line of this.items()) {
+            if (!line.isFinal)
+                return last;
+            last = line.itemId;
+        }
+        return last;
+    }
+    /**
+     * The final lines shown after the line with the id, in order; every one of
+     * them when the id is `undefined` or unknown. With `takenBack`, a line taken
+     * back comes too, as its empty final in its place: what a participant that
+     * rejoins is sent again, so a page that missed the retraction drops the line.
+     */
+    finalsAfter(itemId, options = {}) {
+        const lines = options.takenBack ? [...this.lines.values()] : this.items();
+        const index = itemId === undefined ? -1 : lines.findIndex((line) => line.itemId === itemId);
+        return lines.slice(index + 1).filter((line) => line.isFinal);
+    }
+    /** The ledger as plain JSON. */
+    toJSON() {
+        return { v: 1, items: this.items() };
+    }
+    /** A ledger from {@link TranscriptLedger.toJSON}'s output; a malformed line is skipped. */
+    static fromJSON(value, options = {}) {
+        const ledger = new TranscriptLedger(options);
+        const items = value?.items;
+        if (!Array.isArray(items))
+            return ledger;
+        for (const item of items) {
+            if (typeof item !== 'object' || item === null)
+                continue;
+            const line = item;
+            if (typeof line.itemId !== 'string' || typeof line.text !== 'string' || typeof line.isFinal !== 'boolean')
+                continue;
+            ledger.apply({
+                itemId: line.itemId,
+                text: line.text,
+                isFinal: line.isFinal,
+                ...(typeof line.startMs === 'number' ? { startMs: line.startMs } : {}),
+                ...(typeof line.endMs === 'number' ? { endMs: line.endMs } : {}),
+                ...(typeof line.language === 'string' ? { language: line.language } : {}),
+                ...(typeof line.failed === 'string' ? { failed: line.failed } : {}),
+            });
+        }
+        return ledger;
+    }
+    /**
+     * Drops the oldest final lines while the ledger is over its size, never the
+     * line just applied nor a line still being heard: a later final or
+     * retraction of an open line must find it, so open lines are held over the
+     * size until they close.
+     */
+    trim(keep) {
+        while (this.lines.size > this.maxItems) {
+            let drop;
+            for (const line of this.lines.values()) {
+                if (line.isFinal && line.itemId !== keep) {
+                    drop = line.itemId;
+                    break;
+                }
+            }
+            if (drop === undefined)
+                return;
+            this.lines.delete(drop);
+            this.retracted.delete(drop);
+        }
+    }
+}
+/**
+ * Reads one LiveKit transcription stream (its text and attributes) as a
+ * {@link LedgerEvent}, or `null` when it carries no segment id.
+ */
+export function transcriptEventFromLiveKit(text, attributes) {
+    if (attributes === undefined)
+        return null;
+    const itemId = attributes[LIVEKIT_TRANSCRIPTION_ATTRIBUTES.segmentId];
+    if (!itemId)
+        return null;
+    const event = { itemId, text, isFinal: attributes[LIVEKIT_TRANSCRIPTION_ATTRIBUTES.final] === 'true' };
+    const failed = attributes[TRANSCRIPTION_FAILED_ATTRIBUTE];
+    if (failed)
+        event.failed = failed;
+    return event;
+}
+//# sourceMappingURL=transcriptLedger.js.map

package/dist/io/voice-pipeline/transcriptLedger.js.map

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

package/dist/io/voice-pipeline/types.d.ts

@@ -352,6 +352,33 @@ export interface TranscriptEvent {
         /** Confidence score in [0, 1]. */
         confidence: number;
     };
+    /**
+     * Identifier of the provider's input item this hypothesis belongs to, when
+     * the provider keys its results (OpenAI Realtime's `item_id`). Every interim
+     * and the final of one utterance carry the same `itemId`, so a consumer that
+     * shows interim text replaces it by key, and the results of two utterances
+     * whose events interleave never mix. Providers without item keys leave it
+     * undefined.
+     */
+    itemId?: string;
+    /**
+     * Start of the utterance's audio, in milliseconds counted from the first
+     * frame pushed into the session, when the provider reports speech
+     * boundaries.
+     */
+    startMs?: number;
+    /**
+     * End of the utterance's audio, in milliseconds counted from the first
+     * frame pushed into the session, when the provider reports speech
+     * boundaries.
+     */
+    endMs?: number;
+    /**
+     * Language of `text`: the code the provider detected, or the language the
+     * session was configured with (for example `'en'`). Undefined when neither
+     * is known.
+     */
+    language?: string;
 }
 /**
  * An active streaming speech-to-text session. Audio frames are pushed in