@rimelabs/sdk 0.1.0-alpha.17 → 0.1.0-alpha.19

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.1.0-alpha.19](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.18...typescript-v0.1.0-alpha.19) (2026-10-21)
+
+
+### Features
+
+* add realtime conversation runners ([#89](https://github.com/rimelabs/rime-sdk/issues/89)) ([5447be7](https://github.com/rimelabs/rime-sdk/commit/5447be7713896ac8f68191cc957d82c58228296c))
+
+## [0.1.0-alpha.18](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.17...typescript-v0.1.0-alpha.18) (2026-10-21)
+
+
+### ⚠ BREAKING CHANGES
+
+* Rust TranscriptionUpdate and TypeScript TranscriptionUpdate include Delta/delta; exhaustive handlers must handle the new variant.
+
+### Features
+
+* add append-fragment STT streaming across SDKs ([369f04d](https://github.com/rimelabs/rime-sdk/commit/369f04dadfea9d3d8593d14283d64e3a1f36e4d1))
+* default realtime connections to public Prism and add optional turn timing controls ([#86](https://github.com/rimelabs/rime-sdk/issues/86)) ([0e07f68](https://github.com/rimelabs/rime-sdk/commit/0e07f6852bf0cefb60b8a42c48c2b76f95ac2362))
+
 ## [0.1.0-alpha.17](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.16...typescript-v0.1.0-alpha.17) (2026-10-16)
 
 

package/README.md

@@ -28,16 +28,10 @@ STT use the SDK and Node.js built-ins.
 
 ## Prism: send recorded speech
 
-Prism needs a deployment that serves its realtime API. Obtain the endpoint,
-credentials, and voice from your deployment operator. The TTS endpoint does not serve Prism.
-Set `RIME_API_KEY` to the credential for that deployment if it differs from your TTS key.
+With `RIME_API_KEY` set, the SDK connects to
+`wss://prism.api.rime.ai/v1/realtime` and uses the server's default voice.
+Pass `endpoint` or `voice` to select another deployment or voice.
 
-```sh
-export PRISM_URL="wss://your-prism-host/v1/realtime"
-export PRISM_VOICE="your-deployment-voice"
-```
-
-You can omit `PRISM_VOICE` if the deployment has a default voice.
 Record a short question and export it as `question.wav`, using **16 kHz, mono, signed 16-bit PCM WAV**.
 Save the following as `prism.mjs` beside that file. It sends the recording at capture speed,
 then sends silence so Prism can detect the end of speech. The spoken reply goes to `reply.wav`.
@@ -61,9 +55,6 @@ if (
 const data = Buffer.from(input.data.samples);
 if (!data.length || data.length % 2)
   throw new Error("question.wav has no complete PCM16 audio");
-const endpoint = process.env.PRISM_URL;
-if (!endpoint)
-  throw new Error("Set PRISM_URL to your deployment's /v1/realtime URL");
 
 const client = new Rime();
 const stop = new AbortController();
@@ -75,8 +66,6 @@ let sending;
 let reading;
 try {
   const session = await client.realtime.connect({
-    endpoint,
-    voice: process.env.PRISM_VOICE,
     instructions: "Give short, clear answers.",
   });
   sending = (async () => {

package/dist/client.d.ts

@@ -23,7 +23,7 @@ export declare class Rime {
     };
     private readonly realtimeClient;
     readonly realtime: {
-        connect: (options: RealtimeConnectOptions) => Promise<RealtimeSession>;
+        connect: (options?: RealtimeConnectOptions) => Promise<RealtimeSession>;
     };
     private closed;
     private closing;

package/dist/index.d.ts

@@ -7,4 +7,6 @@ export * from "./errors.js";
 export { RealtimeSession } from "./realtime/session.js";
 export * from "./realtime/types.js";
 export { TranscriptStream } from "./stt/stream.js";
-export type { AudioSource, TranscribeOptions, Transcription, TranscriptionOptions, TranscriptionMode, TranscriptionPartial, TranscriptionFinal, TranscriptionUpdate, } from "./stt/types.js";
+export type { AudioSource, TranscribeOptions, Transcription, TranscriptionOptions, TranscriptionMode, TranscriptionPartial, TranscriptionDelta, TranscriptionOutputContract, TranscriptionFinal, TranscriptionUpdate, } from "./stt/types.js";
+export { runConversation } from "./realtime/conversation.js";
+export type { ConversationSource, ConversationOutput, ConversationPlayback, ConversationOptions, } from "./realtime/conversation.js";

package/dist/index.js

@@ -5,3 +5,4 @@ export * from "./errors.js";
 export { RealtimeSession } from "./realtime/session.js";
 export * from "./realtime/types.js";
 export { TranscriptStream } from "./stt/stream.js";
+export { runConversation } from "./realtime/conversation.js";

package/dist/realtime/client.d.ts

@@ -7,6 +7,6 @@ export declare class Realtime {
     private readonly sessions;
     private readonly opening;
     constructor(credentials: Credentials, checkOpen: () => void);
-    connect(options: RealtimeConnectOptions): Promise<RealtimeSession>;
+    connect(options?: RealtimeConnectOptions): Promise<RealtimeSession>;
     close(): Promise<void>;
 }

package/dist/realtime/client.js

@@ -3,6 +3,7 @@ import { RimeCancelledError, RimeInputError, RimeUnavailableError, } from "../er
 import { cancellation, scope } from "./async.js";
 import { RealtimeSession } from "./session.js";
 import { RealtimeConnection } from "./transport.js";
+const DEFAULT_ENDPOINT = "wss://prism.api.rime.ai/v1/realtime";
 function endpoint(value) {
     let url;
     try {
@@ -56,9 +57,9 @@ export class Realtime {
         this.credentials = credentials;
         this.checkOpen = checkOpen;
     }
-    async connect(options) {
+    async connect(options = {}) {
         this.checkOpen();
-        const address = endpoint(options.endpoint);
+        const address = endpoint(options.endpoint === undefined ? DEFAULT_ENDPOINT : options.endpoint);
         const limits = timeouts(options.timeouts);
         if ((options.model ?? "prism") !== "prism")
             throw new RimeInputError("The realtime model must be prism");
@@ -103,6 +104,24 @@ export class Realtime {
                 };
             }),
         };
+        if (options.turnDetection !== undefined) {
+            const detection = options.turnDetection;
+            if (!detection ||
+                typeof detection !== "object" ||
+                Array.isArray(detection))
+                throw new RimeInputError("turnDetection must be an object");
+            if (detection.eagerness !== undefined) {
+                if (!["low", "medium", "high", "auto"].includes(detection.eagerness))
+                    throw new RimeInputError("Turn eagerness must be low, medium, high, or auto");
+                settings.turn_detection.eagerness = detection.eagerness;
+            }
+            if (detection.endOfTurnTimeoutMs !== undefined) {
+                const value = detection.endOfTurnTimeoutMs;
+                if (!Number.isInteger(value) || value < 1000 || value > 10000)
+                    throw new RimeInputError("End-of-turn timeout must be an integer from 1000 to 10000 ms");
+                settings.turn_detection.prism_end_of_turn_timeout_ms = value;
+            }
+        }
         for (const name of ["voice", "instructions"]) {
             const value = options[name];
             if (value !== undefined && value !== null) {

package/dist/realtime/conversation.d.ts

@@ -0,0 +1,47 @@
+import type { RealtimeSession } from "./session.js";
+import type { AudioChunk, OutputRef, SessionEvent } from "./types.js";
+export interface ConversationSource {
+    /** Return one chunk, or null at EOF. Abort must release a pending read. */
+    read(signal: AbortSignal): Promise<AudioChunk | null>;
+}
+export interface ConversationOutput {
+    /** Queue audio without blocking. Raise on overflow; never silently drop audio. */
+    write(chunk: AudioChunk): void;
+    /** Seal this output; completion still waits for the device to drain. */
+    end(): void;
+    /** Measured played milliseconds. Reject on measurement failure or abort.
+     * Abort stops the wait, without cancelling the device receipt. */
+    completion(signal: AbortSignal): Promise<number>;
+}
+export interface ConversationPlayback {
+    /** Queue an output in open order; audible playback must be FIFO.
+     * Keep completion and interruption state separate for each output.
+     * Do not mix outputs or play a later output ahead of an earlier one. */
+    open(output: OutputRef): ConversationOutput;
+    /** Stop selected outputs as one batch, including outputs after end().
+     * Discard their unplayed audio before starting any remaining output.
+     * Resume remaining outputs in FIFO order without waiting for new audio.
+     * Repeated interruptions are harmless; each receipt remains independent. */
+    interrupt(outputs: readonly OutputRef[]): void;
+    /** Confirm all playback has stopped and queued audio is discarded.
+     * Caller resources stay open. Reject and release the wait on abort.
+     * The runner supplies a separate signal with a five-second deadline and
+     * waits for cancellation cleanup before returning. */
+    stop(signal: AbortSignal): Promise<void>;
+}
+export interface ConversationOptions {
+    readonly source: ConversationSource;
+    readonly playback: ConversationPlayback;
+    /** Called inline for every event. Must be synchronous and nonblocking.
+     * Scheduled application work remains the caller's responsibility. */
+    readonly onEvent?: (event: SessionEvent) => void;
+    readonly signal?: AbortSignal;
+}
+/** Run until input EOF, session closure, failure, or abort.
+ * Owns the session's active lifetime and closes it on exit. The caller owns
+ * adapter resource contexts. Do not consume session.events or report playback
+ * elsewhere. Adapter operations must settle on abort. No input or callback
+ * queue is added. Limits: 64 responses, 128 outputs, 256 pending operations.
+ * Overflow fails the run. Callback and adapter failures reach the caller.
+ */
+export declare function runConversation(session: RealtimeSession, { source, playback, onEvent, signal }: ConversationOptions): Promise<void>;

package/dist/realtime/conversation.js

@@ -0,0 +1,309 @@
+import { abortable, scope } from "../cancellation.js";
+import { RimeCancelledError, RimeInputError, RimeResourceLimitError, RimeTimeoutError, } from "../errors.js";
+import { Deferred } from "./async.js";
+import { isSessionCloseError } from "./session.js";
+import { RimeRealtimeError } from "./types.js";
+/** Run until input EOF, session closure, failure, or abort.
+ * Owns the session's active lifetime and closes it on exit. The caller owns
+ * adapter resource contexts. Do not consume session.events or report playback
+ * elsewhere. Adapter operations must settle on abort. No input or callback
+ * queue is added. Limits: 64 responses, 128 outputs, 256 pending operations.
+ * Overflow fails the run. Callback and adapter failures reach the caller.
+ */
+export async function runConversation(session, { source, playback, onEvent, signal }) {
+    const controller = new AbortController();
+    const running = controller.signal;
+    const receipts = new AbortController();
+    const abort = () => controller.abort(signal?.reason);
+    if (signal?.aborted)
+        abort();
+    else
+        signal?.addEventListener("abort", abort, { once: true });
+    const replies = new Map();
+    const parents = new Map();
+    const interrupted = new Set();
+    const tasks = new Set();
+    let fail;
+    let failed = false;
+    let failureReason;
+    const failure = new Promise((_, reject) => {
+        fail = (error) => {
+            if (!failed) {
+                failed = true;
+                failureReason = error;
+                reject(error);
+            }
+        };
+    });
+    void failure.catch(() => { });
+    function start(work, local) {
+        if (tasks.size >= 256)
+            throw new RimeResourceLimitError("Conversation pending operation limit exceeded");
+        const task = work();
+        tasks.add(task);
+        void task.then(() => tasks.delete(task), (error) => {
+            tasks.delete(task);
+            const expected = [local, running, receipts.signal].some((signal) => signal?.aborted &&
+                (error === signal.reason ||
+                    error instanceof RimeCancelledError ||
+                    (error instanceof DOMException && error.name === "AbortError")));
+            if (!expected && !isSessionCloseError(error))
+                fail(error);
+        });
+        return task;
+    }
+    async function measure(stream) {
+        const value = await stream.completion(receipts.signal);
+        if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+            throw new RimeInputError("Playback measurement must be finite nonnegative milliseconds");
+        return value;
+    }
+    function end(output) {
+        if (!output.sealed) {
+            output.sealed = true;
+            output.stream.end();
+        }
+    }
+    function cut(output) {
+        if (output.report)
+            return;
+        end(output);
+        output.report = start(async () => {
+            const played = await output.receipt;
+            running.throwIfAborted();
+            try {
+                await session.reportPlayback({
+                    kind: "interrupted",
+                    output: output.ref,
+                    audioEndMs: Math.floor(played),
+                }, { signal: running });
+            }
+            catch (error) {
+                // The session also forwards the refusal to the application callback.
+                if (!(error instanceof RimeRealtimeError) ||
+                    error.fault.scope !== "event" ||
+                    error.fault.code !== "truncate_not_current")
+                    throw error;
+            }
+        });
+    }
+    function finish(reply) {
+        const earlier = [];
+        for (const previous of replies.values()) {
+            if (previous === reply)
+                break;
+            earlier.push(previous.drained.promise);
+        }
+        const finishing = new AbortController();
+        reply.finish = finishing;
+        const cancel = () => finishing.abort(running.reason);
+        if (running.aborted)
+            cancel();
+        else
+            running.addEventListener("abort", cancel, { once: true });
+        start(async () => {
+            try {
+                let played = 0;
+                for (const output of reply.outputs.values())
+                    played += await abortable(output.receipt, finishing.signal);
+                reply.drained.resolve();
+                if (reply.interrupted) {
+                    for (const output of reply.outputs.values())
+                        if (output.report)
+                            await abortable(output.report, finishing.signal);
+                }
+                else {
+                    // Prism's latest drain token clears all earlier playback too.
+                    for (const drained of earlier)
+                        await abortable(drained, finishing.signal);
+                    await session.reportPlayback({ kind: "finished", response: reply.ref, playedMs: played }, { signal: finishing.signal });
+                }
+                finishing.signal.throwIfAborted();
+                replies.delete(reply.ref.responseId);
+            }
+            finally {
+                running.removeEventListener("abort", cancel);
+            }
+        }, finishing.signal);
+    }
+    function wasInterrupted(responseId) {
+        let current = responseId;
+        // The session retains at most 128 response references.
+        for (let count = 0; current !== undefined && count < 128; count++) {
+            if (interrupted.has(current))
+                return true;
+            current = parents.get(current);
+        }
+        return false;
+    }
+    function interrupt(selected) {
+        const affected = selected.filter((reply) => !reply.interrupted);
+        const outputs = affected.flatMap((reply) => [...reply.outputs.values()]);
+        for (const reply of affected) {
+            reply.interrupted = true;
+            if (parents.has(reply.ref.responseId))
+                interrupted.add(reply.ref.responseId);
+            reply.finish?.abort();
+        }
+        if (outputs.length)
+            playback.interrupt(outputs.map((output) => output.ref));
+        for (const output of outputs)
+            cut(output);
+        for (const reply of affected)
+            if (reply.ended)
+                finish(reply);
+    }
+    function outputFor(ref) {
+        const reply = replies.get(ref.response.responseId);
+        if (!reply || reply.ended)
+            return;
+        const key = JSON.stringify([ref.itemId, ref.outputIndex, ref.contentIndex]);
+        let output = reply.outputs.get(key);
+        if (!output) {
+            let count = 0;
+            for (const value of replies.values())
+                count += value.outputs.size;
+            if (count >= 128)
+                throw new RimeResourceLimitError("Conversation output limit exceeded");
+            const stream = playback.open(ref);
+            output = {
+                ref,
+                stream,
+                receipt: start(() => measure(stream)),
+                sealed: false,
+            };
+            reply.outputs.set(key, output);
+            if (reply.interrupted) {
+                playback.interrupt([ref]);
+                cut(output);
+            }
+        }
+        return output;
+    }
+    async function send() {
+        while (!running.aborted) {
+            const chunk = await source.read(running);
+            if (chunk === null)
+                return;
+            await session.sendAudio(chunk, { signal: running });
+        }
+        running.throwIfAborted();
+    }
+    async function read() {
+        for await (const event of session.events) {
+            running.throwIfAborted();
+            const payload = event.payload;
+            switch (payload.kind) {
+                case "response.started": {
+                    if (replies.size >= 64)
+                        throw new RimeResourceLimitError("Conversation response limit exceeded");
+                    const id = payload.response.responseId;
+                    parents.set(id, payload.parent?.responseId);
+                    if (parents.size > 128) {
+                        const expired = parents.keys().next().value;
+                        parents.delete(expired);
+                        interrupted.delete(expired);
+                    }
+                    const blocked = wasInterrupted(id);
+                    if (blocked)
+                        interrupted.add(id);
+                    replies.set(id, {
+                        ref: payload.response,
+                        outputs: new Map(),
+                        interrupted: blocked,
+                        ended: false,
+                        drained: new Deferred(),
+                    });
+                    break;
+                }
+                case "message.started":
+                case "audio.delta":
+                case "audio.done": {
+                    const output = outputFor(payload.output);
+                    if (output) {
+                        const reply = replies.get(payload.output.response.responseId);
+                        if (payload.kind === "audio.delta" && !reply.interrupted)
+                            output.stream.write(payload.audio);
+                        else if (payload.kind === "audio.done")
+                            end(output);
+                    }
+                    break;
+                }
+                case "speech.started":
+                    if (session.info.interruptOnSpeech)
+                        interrupt([...replies.values()]);
+                    break;
+                case "response.abandoned": {
+                    if (parents.has(payload.response.responseId))
+                        interrupted.add(payload.response.responseId);
+                    interrupt([...replies.values()].filter((reply) => wasInterrupted(reply.ref.responseId)));
+                    break;
+                }
+                case "response.ended": {
+                    const reply = replies.get(payload.response.responseId);
+                    if (reply) {
+                        reply.ended = true;
+                        for (const output of reply.outputs.values())
+                            end(output);
+                        finish(reply);
+                    }
+                    break;
+                }
+            }
+            const result = onEvent?.(event);
+            if (result &&
+                typeof result.then === "function") {
+                void Promise.resolve(result).catch(() => { });
+                throw new RimeInputError("onEvent must be synchronous and nonblocking");
+            }
+        }
+    }
+    let original = false;
+    try {
+        running.throwIfAborted();
+        await abortable(Promise.race([start(send), start(read), failure]), running);
+        if (failed)
+            throw failureReason;
+    }
+    catch (error) {
+        if (!isSessionCloseError(error)) {
+            original = true;
+            throw error;
+        }
+    }
+    finally {
+        let cleanupError;
+        // Stop input, event processing and reports, but keep receipt waits alive
+        // until the adapter confirms playback has stopped or the deadline expires.
+        controller.abort();
+        const shutdown = scope([], 5, new RimeTimeoutError("Playback shutdown confirmation timed out"));
+        try {
+            // Await the adapter itself, including cleanup after the deadline aborts.
+            // Racing this promise against abort would leave that cleanup running.
+            await playback.stop(shutdown.signal);
+            shutdown.signal.throwIfAborted();
+        }
+        catch (error) {
+            cleanupError = error;
+        }
+        finally {
+            shutdown.dispose();
+        }
+        receipts.abort();
+        try {
+            await session.close();
+        }
+        catch (error) {
+            cleanupError ??= error;
+        }
+        await Promise.allSettled(tasks);
+        signal?.removeEventListener("abort", abort);
+        if (!original) {
+            if (failed)
+                throw failureReason;
+            signal?.throwIfAborted();
+            if (cleanupError !== undefined)
+                throw cleanupError;
+        }
+    }
+}

package/dist/realtime/protocol.d.ts

@@ -4,6 +4,8 @@ export interface SessionSettings {
     input_audio_format: "pcm16";
     turn_detection: {
         interrupt_response: boolean;
+        eagerness?: t.TurnEagerness;
+        prism_end_of_turn_timeout_ms?: number;
     };
     tools: {
         type: "function";
@@ -22,6 +24,7 @@ export interface SessionView {
     interruptOnSpeech: boolean | null;
     toolResultTimeoutS: number | null;
     toolContinuationTimeoutS: number | null;
+    turnDetection: t.TurnDetectionInfo;
 }
 export interface SessionCreated {
     kind: "session.created";

package/dist/realtime/protocol.js

@@ -66,6 +66,30 @@ function duration(value, field) {
 }
 function session(value) {
     const view = object(value, "session");
+    const detection = view.turn_detection === undefined
+        ? {}
+        : object(view.turn_detection, "session.turn_detection");
+    let eagerness = null;
+    if (detection.eagerness !== undefined) {
+        const value = string(detection.eagerness, "session.turn_detection.eagerness");
+        eagerness =
+            value === "low" ||
+                value === "medium" ||
+                value === "high" ||
+                value === "auto"
+                ? value
+                : "unknown";
+    }
+    let endOfTurnTimeoutMs = null;
+    if (detection.prism_end_of_turn_timeout_ms !== undefined) {
+        const value = detection.prism_end_of_turn_timeout_ms;
+        if (typeof value !== "number" ||
+            !Number.isInteger(value) ||
+            value < 1000 ||
+            value > 10000)
+            invalid("session.turn_detection.prism_end_of_turn_timeout_ms");
+        endOfTurnTimeoutMs = value;
+    }
     const waits = view.prism_tool_waits === undefined
         ? {}
         : object(view.prism_tool_waits, "session.prism_tool_waits");
@@ -79,6 +103,7 @@ function session(value) {
         id: id(view.id, "session.id"),
         voice: view.voice === undefined ? "" : string(view.voice, "session.voice"),
         interruptOnSpeech: interrupt ?? null,
+        turnDetection: Object.freeze({ eagerness, endOfTurnTimeoutMs }),
         toolResultTimeoutS: duration(waits.result_timeout_s, "result_timeout_s"),
         toolContinuationTimeoutS: duration(waits.continuation_timeout_s, "continuation_timeout_s"),
     };

package/dist/realtime/session.d.ts

@@ -1,6 +1,8 @@
 import { RealtimeConnection } from "./transport.js";
 import * as t from "./types.js";
 import * as p from "./protocol.js";
+/** @internal Recognize only failures created by intentional session closure. */
+export declare function isSessionCloseError(error: unknown): boolean;
 /** One conversation. Consume events concurrently with session operations. */
 export declare class RealtimeSession {
     private readonly socket;

package/dist/realtime/session.js

@@ -16,6 +16,11 @@ const NOT_READY = new Set([
     "proactive_unavailable",
 ]);
 const LIMIT = 128;
+const closeErrors = new WeakSet();
+/** @internal Recognize only failures created by intentional session closure. */
+export function isSessionCloseError(error) {
+    return error instanceof Error && closeErrors.has(error);
+}
 class ResponseState {
     ref;
     done = new Flag();
@@ -109,6 +114,7 @@ export class RealtimeSession {
             interruptOnSpeech: view.interruptOnSpeech ?? settings.turn_detection.interrupt_response,
             toolResultTimeoutS: view.toolResultTimeoutS ?? null,
             toolContinuationTimeoutS: view.toolContinuationTimeoutS ?? null,
+            turnDetection: view.turnDetection,
         });
     }
     get info() {
@@ -151,8 +157,13 @@ export class RealtimeSession {
     check() {
         if (this.failure)
             throw this.failure;
-        if (this.closed)
-            throw new RimeInputError("The realtime session is closed");
+        if (this.closed) {
+            // Reports can start after intentional close, before runner cleanup.
+            // Failed sessions retain failure and take the branch above.
+            const error = new RimeInputError("The realtime session is closed");
+            closeErrors.add(error);
+            throw error;
+        }
     }
     response(ref) {
         this.check();
@@ -716,7 +727,9 @@ export class RealtimeSession {
         if (!this.closing) {
             this.closing = (async () => {
                 if (!this.closed) {
-                    this.fail(new RimeStreamError("Realtime session closed"));
+                    const error = new RimeStreamError("Realtime session closed");
+                    closeErrors.add(error);
+                    this.fail(error);
                     this.failure = null;
                 }
                 await this.socket.close();

package/dist/realtime/types.d.ts

@@ -19,13 +19,28 @@ export interface ToolDefinition {
     readonly parameters: JsonObject;
     readonly description?: string;
 }
+export type TurnEagerness = "low" | "medium" | "high" | "auto";
+/** Omitted fields use the server's turn timing defaults. */
+export interface TurnDetection {
+    /** How readily Prism decides that the user has finished speaking. */
+    readonly eagerness?: TurnEagerness;
+    /** Maximum silence before ending a turn: an integer from 1000 to 10000 ms. */
+    readonly endOfTurnTimeoutMs?: number;
+}
+/** Effective server settings. Null means the server did not publish the field. */
+export interface TurnDetectionInfo {
+    readonly eagerness: TurnEagerness | "unknown" | null;
+    readonly endOfTurnTimeoutMs: number | null;
+}
 export interface RealtimeConnectOptions extends RealtimeOperationOptions {
-    readonly endpoint: string;
+    /** Defaults to wss://prism.api.rime.ai/v1/realtime. */
+    readonly endpoint?: string;
     readonly model?: "prism";
     readonly voice?: string | null;
     readonly instructions?: string | null;
     readonly tools?: readonly ToolDefinition[];
     readonly interruptOnSpeech?: boolean;
+    readonly turnDetection?: TurnDetection;
     readonly timeouts?: RealtimeTimeouts;
 }
 export interface ReplyOptions extends RealtimeOperationOptions {
@@ -60,6 +75,7 @@ export interface SessionInfo {
     readonly interruptOnSpeech: boolean;
     readonly toolResultTimeoutS: number | null;
     readonly toolContinuationTimeoutS: number | null;
+    readonly turnDetection: TurnDetectionInfo;
 }
 export interface RealtimeFault {
     readonly code: string;

package/dist/stt/client.js

@@ -69,6 +69,10 @@ export class STT {
         if (!source || typeof source[Symbol.asyncIterator] !== "function")
             throw new RimeInputError("audio must be an async iterable of Uint8Array chunks");
         validateOptions(options);
+        const outputContract = options.outputContract ?? "revised_hypotheses";
+        if (outputContract !== "revised_hypotheses" &&
+            outputContract !== "append_fragments")
+            throw new RimeInputError("outputContract must be revised_hypotheses or append_fragments");
         const mode = options.mode ?? "written";
         const terms = options.contextTerms ?? [];
         const format = resolvePCMFormat(options.inputFormat);
@@ -79,6 +83,7 @@ export class STT {
             prepare: (signal) => this.prepare(signal, target),
         }, source, {
             language: options.language,
+            outputContract,
             mode,
             contextTerms: [...terms],
             inputFormat: format,

package/dist/stt/policy.js

@@ -5,7 +5,7 @@ export const policy = {
     acceptanceTimeout: 10,
     completionTimeout: 120,
     cleanupTimeout: 2,
-    receiveBytes: 262144,
-    transcriptBytes: 65536,
+    receiveBytes: 1048576 + 65536,
+    transcriptBytes: 1048576,
     queuedUpdates: 16,
 };

package/dist/stt/protocol.d.ts

@@ -1,13 +1,14 @@
 import * as schema from "@rimelabs/api";
-import type { TranscriptionPartial, TranscriptionFinal } from "./types.js";
+import type { TranscriptionPartial, TranscriptionDelta, TranscriptionFinal, TranscriptionOutputContract } from "./types.js";
 /** Validate the wire sequence before exposing any final result. */
 export declare class TranscriptState {
     private readonly textLimit;
+    private readonly outputContract;
     language: string | null;
     private revision;
     private text;
     private final;
-    constructor(textLimit: number);
-    accept(message: schema.StreamingTranscriptionResponse, inputDone: boolean): TranscriptionPartial | null;
+    constructor(textLimit: number, outputContract?: TranscriptionOutputContract);
+    accept(message: schema.StreamingTranscriptionResponse, inputDone: boolean): TranscriptionPartial | TranscriptionDelta | null;
     finish(): TranscriptionFinal;
 }

package/dist/stt/protocol.js

@@ -3,12 +3,14 @@ import { RimeStreamError, RimeResourceLimitError } from "../errors.js";
 /** Validate the wire sequence before exposing any final result. */
 export class TranscriptState {
     textLimit;
+    outputContract;
     language = null;
     revision = 0n;
     text = "";
     final = null;
-    constructor(textLimit) {
+    constructor(textLimit, outputContract = "revised_hypotheses") {
         this.textLimit = textLimit;
+        this.outputContract = outputContract;
     }
     accept(message, inputDone) {
         const payload = message.payload;
@@ -21,7 +23,9 @@ export class TranscriptState {
             if (this.language !== null)
                 throw new RimeStreamError("Received duplicate transcription acceptance");
             if (accepted.outputContract !==
-                schema.StreamingOutputContract.REVISED_HYPOTHESES)
+                (this.outputContract === "append_fragments"
+                    ? schema.StreamingOutputContract.APPEND_FRAGMENTS
+                    : schema.StreamingOutputContract.REVISED_HYPOTHESES))
                 throw new RimeStreamError("The service accepted a different transcript contract");
             if (!accepted.language?.tag || !accepted.language.source)
                 throw new RimeStreamError("The service did not confirm a resolved language");
@@ -30,8 +34,19 @@ export class TranscriptState {
         }
         if (this.language === null)
             throw new RimeStreamError("Received a transcript before acceptance");
+        const append = this.outputContract === "append_fragments";
+        if (payload.case === "delta" && append) {
+            const text = payload.value.text;
+            if (Buffer.byteLength(this.text) + Buffer.byteLength(text) >
+                this.textLimit)
+                throw new RimeResourceLimitError("The transcript exceeds the SDK text limit");
+            this.text += text;
+            return { kind: "delta", text };
+        }
         if (payload.case !== "hypothesis" && payload.case !== "done")
             throw new RimeStreamError("Received an unexpected transcription response");
+        if (payload.case === "hypothesis" && append)
+            throw new RimeStreamError("Received an unexpected transcription response");
         const value = payload.value;
         if (Buffer.byteLength(value.text, "utf8") > this.textLimit)
             throw new RimeResourceLimitError("The transcript exceeds the SDK text limit");
@@ -46,7 +61,7 @@ export class TranscriptState {
         if (!inputDone)
             throw new RimeStreamError("The service completed before input finished");
         if (value.revision !== this.revision || value.text !== this.text)
-            throw new RimeStreamError("Final transcript does not match the last hypothesis");
+            throw new RimeStreamError("Final transcript does not match prior updates");
         const language = payload.value.language;
         if (language?.tag !== this.language || !language.source)
             throw new RimeStreamError("Final language does not match the accepted language");

package/dist/stt/stream.js

@@ -130,7 +130,7 @@ export class TranscriptStream {
         }
     }
     async read() {
-        const state = new TranscriptState(policy.transcriptBytes);
+        const state = new TranscriptState(policy.transcriptBytes, this.options.outputContract);
         for await (const message of this.call.responses()) {
             const update = state.accept(message, this.inputDone);
             if (state.language !== null) {
@@ -149,7 +149,7 @@ export class TranscriptStream {
             this.controller.signal.throwIfAborted();
             this.call = new TranscriptionCall(prepared.client, prepared.metadata, this.controller.signal);
             this.admission = this.deadline(policy.acceptanceTimeout, "Transcription acceptance timed out");
-            await this.call.start(this.options.language, this.options.mode ?? "written", this.options.contextTerms ?? []);
+            await this.call.start(this.options.language, this.options.mode ?? "written", this.options.contextTerms ?? [], this.options.outputContract);
             const producer = this.produce(), reader = this.read();
             tasks = [producer, reader];
             const [, final] = await Promise.all([producer, reader]);

package/dist/stt/transport.d.ts

@@ -10,6 +10,6 @@ export declare const transport: {
 export declare function transcribe(client: grpc.Client, auth: grpc.Metadata, audio: Uint8Array, options: TranscribeOptions, signal: AbortSignal): Promise<Transcription>;
 export declare class TranscriptionCall extends BidiCall<schema.StreamingTranscriptionRequest, schema.StreamingTranscriptionResponse> {
     constructor(client: grpc.Client, auth: grpc.Metadata, signal: AbortSignal);
-    start(language: string, mode: TranscriptionMode, contextTerms: readonly string[]): Promise<void>;
+    start(language: string, mode: TranscriptionMode, contextTerms: readonly string[], outputContract?: import("./types.js").TranscriptionOutputContract): Promise<void>;
     writeAudio(audio: Uint8Array): Promise<void>;
 }

package/dist/stt/transport.js

@@ -69,7 +69,7 @@ export class TranscriptionCall extends BidiCall {
         const method = service.method.transcribeStreaming;
         super(client.makeBidiStreamRequest(`/${service.typeName}/${method.name}`, serializer(method.input), deserializer(method.output), auth), signal);
     }
-    start(language, mode, contextTerms) {
+    start(language, mode, contextTerms, outputContract = "revised_hypotheses") {
         return this.write(create(schema.StreamingTranscriptionRequestSchema, {
             payload: {
                 case: "config",
@@ -79,7 +79,9 @@ export class TranscriptionCall extends BidiCall {
                         ? schema.TranscriptionMode.VERBATIM
                         : schema.TranscriptionMode.WRITTEN,
                     contextTerms: [...contextTerms],
-                    outputContract: schema.StreamingOutputContract.REVISED_HYPOTHESES,
+                    outputContract: outputContract === "append_fragments"
+                        ? schema.StreamingOutputContract.APPEND_FRAGMENTS
+                        : schema.StreamingOutputContract.REVISED_HYPOTHESES,
                 },
             },
         }));

package/dist/stt/types.d.ts

@@ -3,7 +3,16 @@ import type { PCMFormat } from "../pcm.js";
 export type TranscriptionMode = "written" | "verbatim";
 /** One caller-ended utterance of headerless signed PCM16 little-endian audio. */
 export type AudioSource = AsyncIterable<Uint8Array>;
+/** Select replacement hypotheses (default) or permanent append fragments. */
+export type TranscriptionOutputContract = "revised_hypotheses" | "append_fragments";
+export interface TranscriptionDelta {
+    readonly kind: "delta";
+    /** Append exactly, preserving the server's newline separators. */
+    readonly text: string;
+}
 export interface TranscriptionOptions {
+    /** Defaults to revised_hypotheses. Each stream uses one fixed contract. */
+    outputContract?: TranscriptionOutputContract;
     /** Required BCP-47 tag, passed unchanged to the service (for example "en"). */
     language: string;
     /** Formatting intent; defaults to written and does not guarantee exact tokens. */
@@ -31,9 +40,9 @@ export interface TranscriptionFinal {
     /** Canonical BCP-47 tag selected by the service, for example "en". */
     readonly language: string;
 }
-export type TranscriptionUpdate = TranscriptionPartial | TranscriptionFinal;
+export type TranscriptionUpdate = TranscriptionPartial | TranscriptionDelta | TranscriptionFinal;
 /** Options for a complete WAV recording. Audio is sent unchanged. */
-export type TranscribeOptions = Omit<TranscriptionOptions, "inputFormat">;
+export type TranscribeOptions = Omit<TranscriptionOptions, "inputFormat" | "outputContract">;
 /** A successful whole-recording transcription. Silence may produce empty text. */
 export interface Transcription {
     readonly text: string;

package/docs/realtime.md

@@ -10,23 +10,159 @@ microphone capture, tool execution, and playback.
 Start with the [recorded-speech quick start](../README.md#prism-send-recorded-speech)
 to save a spoken reply without audio hardware.
 
-For live conversations, keep the session open after normal cancellation and
-report playback from the output clock. Saving a file is not playback.
+For live conversations, keep the session open after a response is cancelled.
+Report playback from the output clock. Saving a file is not playback.
 Typed turns also support mixed text and voice applications.
 
+## Optional conversation runner
+
+Use `runConversation` to connect your audio adapters once. It sends input,
+queues output, handles interruption, reports measured playback, and stops its
+operations when the conversation ends. The direct session methods remain available.
+
+```ts
+import { Rime, runConversation } from "@rimelabs/sdk";
+
+const client = new Rime();
+const controller = new AbortController();
+try {
+  const session = await client.realtime.connect();
+  // microphone and speaker are adapters owned by your application.
+  await runConversation(session, {
+    source: microphone,
+    playback: speaker,
+    onEvent(event) {
+      if (event.payload.kind === "transcript.final")
+        console.log(event.payload.text);
+    },
+    signal: controller.signal,
+  });
+} finally {
+  await client.close();
+}
+```
+
+The input adapter implements `ConversationSource`.
+`read(signal: AbortSignal): Promise<AudioChunk | null>` returns one chunk,
+with an optional format, or `null` at EOF. An omitted format uses 16 kHz mono
+PCM16. Abort must reject and release a pending
+read. The runner awaits each `session.sendAudio` call before reading again. It
+uses the session's existing PCM conversion and transport backpressure. Input
+continues during output playback.
+
+The playback adapter implements `ConversationPlayback`:
+
+| Method | Contract |
+| --- | --- |
+| `open(output: OutputRef): ConversationOutput` | Queue this output after previously opened outputs. It can be opened before the first audio chunk. |
+| `interrupt(outputs: readonly OutputRef[]): void` | Stop the selected outputs as one batch, discard their unplayed audio, then resume remaining output in queue order. |
+| `stop(signal: AbortSignal): Promise<void>` | Confirm all playback has stopped and queued audio is discarded. Keep caller-owned resources open. |
+
+Each `ConversationOutput` implements:
+
+| Method | Contract |
+| --- | --- |
+| `write(chunk: AudioChunk): void` | Queue 24 kHz mono PCM16 without blocking. Bound the queue and throw on overflow. |
+| `end(): void` | Accept no more audio. Let queued and device audio drain. |
+| `completion(signal: AbortSignal): Promise<number>` | Return actual played milliseconds after drain or interruption. Reject if measurement fails or the signal aborts. |
+
+All synchronous adapter methods must return promptly. Completion can be awaited
+before `end()`. Keep receipts separate for each `OutputRef`, even when a new
+response starts before an old receipt completes. Play outputs in the order they
+were opened, using one FIFO audio queue. Do not mix outputs, interleave their
+audio, or play later outputs before earlier outputs finish or are interrupted.
+Prism assumes that interrupting a partially played reply leaves later replies
+in the same turn unheard. Independent concurrent playback violates that assumption.
+The runner passes all affected output references in one `interrupt` call. Stop
+them and discard their queued audio before starting any remaining output. Then
+resume valid output in queue order, without waiting for another chunk or event.
+Interruption must work after `end()` and tolerate repeated calls. A remote
+adapter must preserve the batch, for example with one message containing all
+selected output IDs. Shutdown stops all output and must not resume playback.
+Receipt delivery can be delayed or arrive out of order; audible playback cannot.
+A receipt includes the device buffer where device timing is available. Bytes
+received or queued do not measure playback. Zero is valid for an output that
+played no audio.
+
+Abort must release each pending adapter operation and remove its listeners.
+Cancellation of a completion wait must not cancel the device receipt. The runner
+stops input, event processing, and report submission on exit. It then awaits
+`stop(signal)` before aborting remaining receipt waits. The stop signal is
+independent of caller cancellation and has a five-second deadline. `stop` must
+resolve only after local or remote playback has stopped, including device
+buffers. Sending a stop command is not confirmation. It must reject and release
+its wait when the stop signal aborts. The runner awaits this cancellation cleanup
+before it returns, so cleanup can extend beyond the deadline. A missing confirmation raises
+`RimeTimeoutError`; disconnects and other shutdown failures must reject too.
+The caller opens and closes the adapter resources. The runner does not open
+audio devices or host a browser.
+
+`onEvent` is optional. It receives every event read from `session.events`, in
+order, after the runner applies audio coordination. It must be synchronous and
+nonblocking. Returning a promise is rejected. Callback exceptions reach the
+caller. The callback can schedule application work. Continue to use
+`submitToolResult` and `continueReply`; the runner neither registers nor executes
+tools. The application must cancel and await its own tool tasks. Response
+failures and nonterminal faults are forwarded for application handling. Session
+failures reject the runner promise.
+
+The runner is the only event reader. Do not consume `session.events` at the same
+time, call `reportPlayback` independently, or send a second audio source. Other
+session methods remain available for manual tools and application actions.
+
+On confirmed `speech.started`, the runner uses the effective
+`session.info.interruptOnSpeech` setting. It stops affected output, waits for the
+interrupted receipt, and reports the measured position. It ignores late audio
+for that response. A `speech.hint` alone does not stop playback. A server
+`truncate_not_current` refusal is forwarded as an event; it does not stop a newer
+response. Finished reports wait for generation completion and every output
+receipt, including outstanding playback from earlier responses. Prism treats
+the latest drain token as confirmation that all earlier playback has stopped.
+An abandoned response also stops its dependent tool continuations, identified
+by response parent references. Unrelated later turns remain eligible to play.
+Late audio from an interrupted response or its continuations is discarded.
+The runner retains at most 128 response parent references.
+A report retains the measured duration of its own response. Waiting for earlier
+playback does not block events or input, and does not wait for later responses.
+
+Once called, the runner owns the session's active lifetime. Input EOF, explicit
+session closure, abort, or failure stops all runner operations and closes the
+session. EOF stops remaining playback and waits for shutdown confirmation.
+Abort, including an abort received during cleanup, waits for playback shutdown
+confirmation or its five-second deadline, then awaits adapter cancellation cleanup
+before rejecting with `signal.reason`.
+Explicit session closure ends normally even with playback reports pending;
+remote connection failures reject with the session error.
+Expected cancellation errors during cleanup are ignored. Other cleanup errors
+reach the caller if there is no original failure. They do not replace an
+existing failure or caller abort. The signal is optional. Use
+an application deadline if an adapter can wait indefinitely.
+
+The runner adds no input or callback queue. It retains at most 64 responses,
+128 output streams, and 256 pending operations. Exceeding a limit throws
+`RimeResourceLimitError`. The adapters must also bound their audio queues.
+
+The [live voice example](https://github.com/rimelabs/rime-sdk/blob/main/typescript/examples/realtime/conversation.ts) supplies the
+[browser audio adapter](https://github.com/rimelabs/rime-sdk/blob/main/typescript/examples/common/browser-audio.ts). Browser hosting
+stays in the example. Its player uses `AudioContext.getOutputTimestamp()` for
+receipts and shutdown confirmation. A disconnect cannot confirm a remote stop.
+The [manual tool example](https://github.com/rimelabs/rime-sdk/blob/main/typescript/examples/realtime/manual-tools.ts) keeps
+tool execution outside the runner.
+
 ## Connect
 
-Use `await client.realtime.connect(options)`. It opens a WebSocket, initializes
-one conversation, and returns a `RealtimeSession`. Settings apply once. Open a
-new session to change them.
+Use `await client.realtime.connect()` with `RIME_API_KEY` set. It opens a WebSocket,
+initializes one conversation, and returns a `RealtimeSession`. Settings apply
+once. Open a new session to change them.
 
 | Option | Required? | Default and behavior |
 | --- | --- | --- |
-| `endpoint` | Yes | Full `wss://host/v1/realtime` URL. Plain `ws://` is allowed only for localhost. |
+| `endpoint` | No | Defaults to `wss://prism.api.rime.ai/v1/realtime`. Overrides must be full URLs; plain `ws://` is allowed only for localhost. |
 | `voice` | If the server has no default voice | Omitted or `null` uses the server default. Supplied strings must be nonblank. |
 | `instructions` | No | Omitted or `null` uses server defaults. Supplied strings must be nonblank. |
 | `tools` | No | `[]`. Each tool requires `name` and a JSON Schema `parameters` object. `description` defaults to `""`. |
 | `interruptOnSpeech` | No | `true`. Requests interruption when the server confirms user speech. |
+| `turnDetection` | No | Omitted settings use the server's turn timing defaults. |
 | `timeouts` | No | `{ connectS: 10, readyS: 30, requestS: 10 }`. Each field is optional. Units are seconds. |
 | `model` | No | `"prism"`, the only accepted value. |
 | `signal` | No | An `AbortSignal` that cancels connection setup. It does not cancel an established session. |
@@ -36,7 +172,8 @@ Credentials come from `new Rime({ apiKey: "..." })` or `RIME_API_KEY`. Prism use
 voice, and timeout settings do not apply to Realtime.
 
 After connection, `session.info` contains `sessionId`, `model`, `voice`,
-`interruptOnSpeech`, `toolResultTimeoutS`, and `toolContinuationTimeoutS`.
+`interruptOnSpeech`, `turnDetection`, `toolResultTimeoutS`, and
+`toolContinuationTimeoutS`.
 Check the effective interruption setting there. Tool wait durations are total
 server deadlines, not remaining time. A `null` duration can mean an omitted
 field; it does not prove that no deadline exists.
@@ -45,6 +182,39 @@ Close the session in `finally` with `await session.close()`. Closing the parent
 client closes all its TTS and Realtime operations. Both objects also support
 `Symbol.asyncDispose`. Repeated close calls are safe.
 
+## Optional turn timing
+
+Pass a `TurnDetection` object to override how readily Prism ends a spoken turn.
+Each field is optional; omitted fields use server defaults.
+
+| Field | Values | Current server default |
+| --- | --- | --- |
+| `eagerness` | `"low"`, `"medium"`, `"high"`, `"auto"` | `"auto"`, equivalent to `"medium"` |
+| `endOfTurnTimeoutMs` | Integer from 1,000 through 10,000 | 5,000 ms |
+
+`"low"` waits for more certainty that the user has finished. `"high"` answers
+sooner, with more risk of cutting in. The timeout is a maximum silence limit,
+not a fixed delay before each reply. If the server falls back to its local
+voice activity detector, it ends turns after 500 ms of silence instead.
+
+```typescript
+const session = await client.realtime.connect({
+  turnDetection: { eagerness: "low", endOfTurnTimeoutMs: 5000 },
+});
+try {
+  console.log(session.info.turnDetection);
+  // Send input and consume session.events here.
+} finally {
+  await session.close();
+}
+```
+
+`session.info.turnDetection` is a `TurnDetectionInfo` with the settings the
+server reported in its initialization acknowledgment. A missing field is
+`null`; the SDK does not substitute a requested value or assume a server
+default. An unrecognized server eagerness becomes `"unknown"`.
+`interruptOnSpeech` remains a separate connection option.
+
 ## Choose an operation
 
 Every method returns a promise. Arguments without `?` are required.

package/docs/stt.md

@@ -63,7 +63,8 @@ try {
   });
   for await (const update of transcript) {
     if (update.kind === "partial") console.log("Current transcript:", update.text);
-    else console.log("Final:", update.text, "Language:", update.language);
+    else if (update.kind === "final")
+      console.log("Final:", update.text, "Language:", update.language);
   }
   console.log("Request:", transcript.requestId);
 } finally {
@@ -76,6 +77,37 @@ without loading it all into memory. Use Node.js 22 or later; browsers are not su
 Open files inside the async generator so file errors are reported through the
 SDK and resources are opened only after the service accepts the utterance.
 
+## Append-fragment streaming
+
+Choose `outputContract: "append_fragments"` on
+`client.stt.stream`. The default is `"revised_hypotheses"`; `transcribe()` does not
+accept an output contract. Both streaming modes use gRPC only.
+
+```javascript
+let text = "";
+const transcript = client.stt.stream(audioChunks(), {
+  language: "en", outputContract: "append_fragments",
+});
+for await (const update of transcript) {
+  if (update.kind === "delta") text += update.text;
+  else if (update.kind === "final") console.log(update.text);
+}
+```
+
+`TranscriptionDelta` is a permanent fragment, not a replacement partial. The
+server recognizes independent five-second audio windows; fragments after the
+first include newline separators. Do not strip, add separators, or drop deltas.
+The final text must match their concatenation. Empty speech can produce no
+updates before an empty final. A final is delivered only after `done` and an OK
+gRPC status, so a connection failure never promotes accumulated fragments to a
+successful result.
+
+Append mode suits longer recordings and consumers that cannot revise text. Send
+recordings as fast as backpressure permits. It does not enable unlimited-length
+streams: the service's 16 MiB audio and 120-second total-call limits still apply.
+Split larger recordings into separate streams. Live voice agents usually prefer
+revised hypotheses for earlier provisional text and corrections across windows.
+
 ## Options
 
 | Option | Meaning |
@@ -83,6 +115,7 @@ SDK and resources are opened only after the service accepts the utterance.
 | `language` | Required spoken BCP-47 tag. Passed unchanged to the service; no detection or SDK language allowlist. The deployed catalog currently supports English and Spanish. |
 | `mode` | `"written"` (default) or `"verbatim"`. Formatting intent, not a guarantee of exact tokens. |
 | `contextTerms` | Sequence of recognition hints, copied unchanged and in order. The service validates terms and prompt budgets. |
+| `outputContract` | `"revised_hypotheses"` (default) or `"append_fragments"`. Streaming only. |
 | `inputFormat` | `PCMFormat`: signed little-endian PCM16 at 8, 16, 24 or 48 kHz, mono or interleaved stereo. Defaults to 16 kHz mono. |
 | `timeout` | Optional positive overall timeout in seconds. Includes connection time, source pauses and consumer pauses. `null` disables this SDK deadline, but not internal or server deadlines. |
 
@@ -98,11 +131,18 @@ There is no STT voice/model selector; the service selects its recognizer.
 
 ## Results and completion
 
-`TranscriptionPartial` and `TranscriptionFinal` are discriminated TypeScript types, exported from `@rimelabs/sdk`. Every update contains the complete current `text`.
+`TranscriptionPartial`, `TranscriptionDelta`, and `TranscriptionFinal` are discriminated types exported from `@rimelabs/sdk`. In the default revised-hypotheses mode, every update contains the complete current `text`.
 **Replace the previous transcript. Do not concatenate partials.** Later partials
 can change earlier words. `TranscriptionFinal.language` is the canonical language
 selected by the service.
 
+When upgrading, `TranscriptionUpdate` now includes `TranscriptionDelta`. Update
+exhaustive handlers to handle `kind: "delta"`, even if you keep the default
+revised-hypotheses contract. Only finals have `language`: check
+`update.kind === "final"` before reading it, rather than assuming every
+non-partial update is final. Append deltas exactly; replace text with partials
+or the confirmed final.
+
 The source is not consumed until the server accepts the configuration. Audio
 upload and transcript reading run concurrently. Decoding currently uses cumulative
 two-second audio windows, so a partial is not promised for each audio packet.
@@ -122,8 +162,12 @@ Pass an `AbortSignal` through the stream's `signal` option to cancel just that
 utterance. Client close cancels all STT, TTS and realtime operations; cancelling
 one stream leaves its siblings running.
 
-The SDK bounds the transcript queue to 16 updates, each with at most 64 KiB of
-UTF-8 text, and bounds gRPC responses to 256 KiB. Slow consumers apply backpressure.
+The SDK bounds the transcript queue to 16 updates. In revised-hypotheses mode,
+each replacement update is limited to 1 MiB of UTF-8 text; sizes are not summed
+across revisions. In append-fragments mode, the concatenated text across all
+deltas is limited to 1 MiB. The final transcript is also limited to 1 MiB in both
+modes. gRPC responses are bounded to 1 MiB plus 64 KiB for the protobuf envelope.
+Slow consumers apply backpressure.
 Internal connection and acceptance waits are 10 seconds; completion after source
 exhaustion is bounded to 120 seconds. The completion timer stops after successful
 gRPC completion. The optional overall timeout remains active until the final

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rimelabs/sdk",
-  "version": "0.1.0-alpha.17",
+  "version": "0.1.0-alpha.19",
   "description": "Rime streaming TTS, STT and Prism realtime SDK for Node.js",
   "license": "MIT",
   "type": "module",