@rimelabs/sdk 0.1.0-alpha.22 → 0.1.0-alpha.24

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.1.0-alpha.24](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.23...typescript-v0.1.0-alpha.24) (2026-10-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* Python and TypeScript SessionEvent payload unions now include ItemTruncated. Update exhaustive event handlers to accept ItemTruncated or the item.truncated kind. Handle unavailable retained text separately from an empty string. Rust's event enum remains non-exhaustive.
+
+### Features
+
+* expose realtime truncation events and summaries ([#112](https://github.com/rimelabs/rime-sdk/issues/112)) ([15d6802](https://github.com/rimelabs/rime-sdk/commit/15d6802f71c849ce08b1d0b46e78bd44d5dfc3b7))
+
+## [0.1.0-alpha.23](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.22...typescript-v0.1.0-alpha.23) (2026-10-27)
+
+
+### Bug Fixes
+
+* preserve Prism handshake error categories and diagnostics ([#110](https://github.com/rimelabs/rime-sdk/issues/110)) ([75568b2](https://github.com/rimelabs/rime-sdk/commit/75568b278afddd265a0a4f2c26c716ccb6b29514))
+
 ## [0.1.0-alpha.22](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.21...typescript-v0.1.0-alpha.22) (2026-10-24)
 
 

package/README.md

@@ -28,6 +28,12 @@ STT use the SDK and Node.js built-ins.
 
 ## Prism: send recorded speech
 
+If Prism refuses the connection with HTTP 429, `realtime.connect()` throws
+`RimeResourceLimitError`. HTTP 503 throws `RimeUnavailableError`. Handshake
+errors include the HTTP status, the server request ID when supplied, and a
+short server explanation when available. Missing or invalid error bodies use
+a default message. The SDK does not retry the connection automatically.
+
 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.

package/dist/realtime/protocol.d.ts

@@ -76,15 +76,10 @@ export interface ItemDeleted {
 export interface AudioCleared {
     kind: "audio.cleared";
 }
-export interface ItemTruncated {
-    kind: "item.truncated";
-    itemId: string;
-    contentIndex: number;
-}
 export interface ResponseEnded extends t.ResponseEnded {
     drainToken: string | null;
 }
-export type Acknowledgment = SessionUpdated | HistoryListed | ItemDeleted | ItemCreated | ToolResultCreated | AudioCleared | ItemTruncated | t.ResponseStarted | ResponseEnded;
+export type Acknowledgment = SessionUpdated | HistoryListed | ItemDeleted | ItemCreated | ToolResultCreated | AudioCleared | t.ItemTruncated | t.ResponseStarted | ResponseEnded;
 export type ServerPayload = SessionCreated | Acknowledgment | t.InputEvent<t.NormalizedRealtimeFault> | t.MessageStarted | t.TextDelta | t.TextDone | t.AudioDelta | t.AudioDone | t.ToolCall | t.FaultEvent<t.NormalizedRealtimeFault>;
 export interface ServerEvent {
     eventId: string;
@@ -113,7 +108,7 @@ export declare const requests: {
     text: Request<t.ResponseStarted>;
     cancel: Request<ResponseEnded>;
     clear: Request<AudioCleared>;
-    truncate: Request<ItemTruncated>;
+    truncate: Request<t.ItemTruncated>;
 };
 export declare function truncationSettings(value: t.Truncation): NonNullable<SessionSettings["truncation"]>;
 export declare function decode(raw: string, sessionId: string | null): ServerEvent | null;

package/dist/realtime/protocol.js

@@ -77,6 +77,20 @@ function revision(value) {
         ? null
         : integer(value.prism_settings_revision, "prism_settings_revision");
 }
+function responseTruncation(response) {
+    if (response.prism_truncation === undefined)
+        return null;
+    const value = object(response.prism_truncation, "response.prism_truncation");
+    const count = integer(value.items_left_out, "prism_truncation.items_left_out");
+    if (count === 0)
+        return invalid("prism_truncation.items_left_out");
+    return Object.freeze({
+        itemsLeftOut: count,
+        firstKeptItemId: value.first_kept_item_id === undefined
+            ? null
+            : string(value.first_kept_item_id, "prism_truncation.first_kept_item_id"),
+    });
+}
 function duration(value, field) {
     if (value == null)
         return null;
@@ -281,6 +295,10 @@ function decodeValue(value, sessionId) {
                 kind: "item.truncated",
                 itemId: id(event.item_id, "item_id"),
                 contentIndex: integer(event.content_index, "content_index"),
+                audioEndMs: integer(event.audio_end_ms, "audio_end_ms"),
+                keptText: event.prism_kept_text === undefined
+                    ? null
+                    : string(event.prism_kept_text, "prism_kept_text"),
             };
             break;
         case "prism.typed_input.ready":
@@ -396,6 +414,7 @@ function decodeValue(value, sessionId) {
             payload = {
                 kind: "response.ended",
                 settingsRevision: revision(response),
+                truncation: responseTruncation(response),
                 response: ref(response.id),
                 status: status === "completed" ||
                     status === "cancelled" ||

package/dist/realtime/session.js

@@ -752,7 +752,7 @@ export class RealtimeSession {
                         pending.target === payload.itemId &&
                         payload.contentIndex === 0)
                         this.settle(key, payload);
-                return;
+                break;
             case "input.ready":
                 this.readyEpoch++;
                 this.ready.set();

package/dist/realtime/transport.d.ts

@@ -6,6 +6,8 @@ export declare class RealtimeConnection {
     private readonly ended;
     private closing;
     private connected;
+    private failed;
+    private refusal;
     readonly ready: Promise<void>;
     onMessage: (raw: string) => void;
     onFailure: (error: RimeError) => void;

package/dist/realtime/transport.js

@@ -1,6 +1,42 @@
 import WebSocket from "ws";
-import { RimeAuthenticationError, RimeStreamError, RimeUnavailableError, } from "../errors.js";
+import { RimeAuthenticationError, RimeResourceLimitError, RimeStreamError, RimeUnavailableError, } from "../errors.js";
 import { Deferred } from "./async.js";
+function handshakeError(status, body, requestId) {
+    let errorType = RimeUnavailableError;
+    let reason = "Realtime endpoint rejected the connection";
+    if ([401, 403].includes(status)) {
+        errorType = RimeAuthenticationError;
+        reason = "Realtime endpoint rejected credentials";
+    }
+    else if (status === 429) {
+        errorType = RimeResourceLimitError;
+        reason = "Realtime connection or rate limit reached";
+    }
+    else if (status === 503) {
+        reason = "Realtime endpoint is unavailable";
+    }
+    let message = `${reason} (HTTP ${status})`;
+    if (body.length > 0 && body.length < 1024) {
+        try {
+            let detail = new TextDecoder("utf-8", { fatal: true })
+                .decode(body)
+                .trim();
+            if (typeof detail === "string" && /^[{[]/.test(detail))
+                detail = JSON.parse(detail)?.error?.message;
+            if (typeof detail === "string" &&
+                !detail.trimStart().startsWith("<") &&
+                !/[\x00-\x08\x0b\x0c\x0e-\x1f]/.test(detail)) {
+                detail = detail.trim().replace(/\s+/gu, " ");
+                if (detail)
+                    message += `: ${detail}`;
+            }
+        }
+        catch {
+            // Invalid response bodies do not change the HTTP error category.
+        }
+    }
+    return new errorType(message, requestId);
+}
 /** Private transport. The public declarations do not require ws types. */
 export class RealtimeConnection {
     socket;
@@ -8,6 +44,8 @@ export class RealtimeConnection {
     ended = new Deferred();
     closing = null;
     connected = false;
+    failed = false;
+    refusal;
     ready = this.opened.promise;
     onMessage = () => { };
     onFailure = () => { };
@@ -26,17 +64,39 @@ export class RealtimeConnection {
             this.opened.resolve();
         });
         this.socket.on("unexpected-response", (request, response) => {
-            const error = [401, 403].includes(response.statusCode ?? 0)
-                ? new RimeAuthenticationError("Realtime endpoint rejected credentials")
-                : new RimeUnavailableError("Realtime endpoint rejected the connection");
-            this.failure(error);
-            response.destroy();
-            request.destroy();
-            this.socket.terminate();
+            const chunks = [];
+            let size = 0;
+            let finished = false;
+            const finish = (complete = false) => {
+                if (finished)
+                    return;
+                finished = true;
+                clearTimeout(timer);
+                this.refusal = undefined;
+                const id = response.headers["x-request-id"];
+                this.failure(handshakeError(response.statusCode ?? 0, complete ? Buffer.concat(chunks) : Buffer.alloc(0), typeof id === "string" ? id : null));
+                response.destroy();
+                request.destroy();
+                this.socket.terminate();
+            };
+            const timer = setTimeout(finish, 1000);
+            this.refusal = finish;
+            response.on("data", (chunk) => {
+                size += chunk.length;
+                if (size >= 1024)
+                    finish();
+                else
+                    chunks.push(chunk);
+            });
+            response.on("end", () => finish(true));
+            response.on("error", () => finish());
+            response.on("aborted", () => finish());
         });
-        this.socket.on("error", () => this.failure(!this.connected
-            ? new RimeUnavailableError("Realtime handshake failed")
-            : new RimeStreamError("Invalid event or lost realtime connection")));
+        this.socket.on("error", () => this.refusal
+            ? this.refusal()
+            : this.failure(!this.connected
+                ? new RimeUnavailableError("Realtime handshake failed")
+                : new RimeStreamError("Invalid event or lost realtime connection")));
         this.socket.on("message", (data, binary) => {
             if (binary) {
                 this.failure(new RimeStreamError("Expected a JSON text event"));
@@ -45,11 +105,15 @@ export class RealtimeConnection {
             this.onMessage(data.toString());
         });
         this.socket.on("close", () => {
+            this.refusal?.();
             this.ended.resolve();
             this.failure(new RimeStreamError("Realtime connection closed; reconnect is not automatic"));
         });
     }
     failure(error) {
+        if (this.failed)
+            return;
+        this.failed = true;
         this.opened.reject(error);
         this.onFailure(error);
     }
@@ -66,6 +130,7 @@ export class RealtimeConnection {
     close() {
         if (!this.closing) {
             this.closing = (async () => {
+                this.refusal?.();
                 if (this.socket.readyState === WebSocket.CLOSED)
                     return;
                 const timer = setTimeout(() => this.socket.terminate(), 2000);

package/dist/realtime/types.d.ts

@@ -288,10 +288,20 @@ export interface ResponseAbandoned {
     readonly kind: "response.abandoned";
     readonly response: ResponseRef;
 }
+/** History items excluded from this reply's prompt, not deleted from history. */
+export interface ResponseTruncation {
+    /** Number of excluded items, not turns. Already hidden items are not counted. */
+    readonly itemsLeftOut: number;
+    /** Oldest retained item; null when no earlier item was retained. */
+    readonly firstKeptItemId: string | null;
+}
 export interface ResponseEnded {
     /** Settings revision published by the server; null when unavailable.
      * Optional on caller-created values for compatibility. */
     readonly settingsRevision?: number | null;
+    /** Null when the server reports no exclusions or the information is unavailable.
+     * Optional on caller-created values for compatibility. */
+    readonly truncation?: ResponseTruncation | null;
     readonly kind: "response.ended";
     readonly response: ResponseRef;
     readonly status: "completed" | "cancelled" | "failed" | "unknown";
@@ -303,11 +313,21 @@ export interface FaultEvent<Fault extends RealtimeFault = RealtimeFault> {
 }
 export type InputEvent<Fault extends RealtimeFault = RealtimeFault> = InputReady | SpeechHint | SpeechStarted | SpeechStopped | InputCommitted | TranscriptDelta | TranscriptFinal | TranscriptFailed<Fault>;
 export type ResponseEvent = ResponseStarted | ResponseAbandoned | MessageStarted | TextDelta | TextDone | AudioDelta | AudioDone | ToolCall | ResponseEnded;
+/** A playback report was recorded. Retained history text can differ from audible
+ * text: replies with tool calls retain all words. */
+export interface ItemTruncated {
+    readonly kind: "item.truncated";
+    readonly itemId: string;
+    readonly contentIndex: number;
+    readonly audioEndMs: number;
+    /** Null when unavailable, including during generation; empty if no words remain. */
+    readonly keptText: string | null;
+}
 export interface SessionEvent<Fault extends RealtimeFault = RealtimeFault> {
     readonly sessionId: string;
     readonly eventId: string;
     readonly requestId: string | null;
-    readonly payload: InputEvent<Fault> | ResponseEvent | FaultEvent<Fault>;
+    readonly payload: InputEvent<Fault> | ResponseEvent | ItemTruncated | FaultEvent<Fault>;
 }
 export interface PlaybackInterrupted {
     readonly kind: "interrupted";

package/docs/realtime.md

@@ -587,3 +587,52 @@ publish it.
 ```text
 await session.update({ truncation: { retentionRatio: 0.9 } });
 ```
+
+## Retained text after interruption
+
+Available in the next SDK release. A `conversation.item.truncated` acknowledgment
+also appears in `session.events` as `ItemTruncated`, with kind `item.truncated`.
+The conversation runner forwards it to `onEvent`. Playback reporting does not
+wait for event consumption.
+
+Use `itemId`, `contentIndex`, and `audioEndMs` to identify the reported audio.
+`keptText` is the text retained in server history. An empty string means no words
+remain. `null` means unavailable, including older servers and replies still being
+generated. The event does not promise a later text update. Replies with tool calls
+retain all words, so this field can differ from the words heard during playback.
+
+```typescript
+function onEvent(event: SessionEvent) {
+  if (event.payload.kind === "item.truncated") {
+    const cut = event.payload;
+    if (cut.keptText !== null) {
+      console.log("Retained text", cut.itemId, JSON.stringify(cut.keptText));
+    }
+  }
+}
+```
+
+This event can arrive after `response.ended`. It has no response reference and does
+not require the SDK to retain that response. `text.done` still reports generated
+text. Add `item.truncated` to exhaustive switches on `SessionEvent.payload.kind`.
+
+## History excluded from a reply
+
+Available in the next SDK release. `ResponseEnded.truncation` exposes the server's
+`response.prism_truncation` summary. It contains `itemsLeftOut` and nullable
+`firstKeptItemId`. The count refers to conversation items excluded from this
+reply's prompt, not turns or items deleted from history. Already hidden items do
+not count. The first ID is absent when no item from before this turn was retained.
+
+Decoded events have `truncation: null` when the server reports no exclusions or the
+information is unavailable, including older servers or a reply that ended before
+usage was counted. Caller-created events may omit the property. This does not change
+the session's truncation policy. Session events and conversation callbacks expose
+the same immutable summary.
+
+```typescript
+if (event.payload.kind === "response.ended" && event.payload.truncation) {
+  const summary = event.payload.truncation;
+  console.log(summary.itemsLeftOut, summary.firstKeptItemId);
+}
+```

package/package.json

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