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

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [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,4 @@ 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";

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/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.js

@@ -109,6 +109,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() {

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

@@ -16,17 +16,18 @@ Typed turns also support mixed text and voice applications.
 
 ## 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 +37,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 +47,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.18",
   "description": "Rime streaming TTS, STT and Prism realtime SDK for Node.js",
   "license": "MIT",
   "type": "module",