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

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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)
 
 

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/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.23",
+  "version": "0.1.0-alpha.24",
   "description": "Rime streaming TTS, STT and Prism realtime SDK for Node.js",
   "license": "MIT",
   "type": "module",