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

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.1.0-alpha.25](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.24...typescript-v0.1.0-alpha.25) (2026-10-28)
+
+
+### Features
+
+* expose Prism reply labels and response data ([#114](https://github.com/rimelabs/rime-sdk/issues/114)) ([4a303a1](https://github.com/rimelabs/rime-sdk/commit/4a303a1b545019dea389f30d0c696e8f7e6cc6b1))
+
+## [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

@@ -26,6 +26,8 @@ export interface SessionSettings {
 }
 /** A copy of the client's labels for every reply: keys to strings. */
 export declare function responseMetadata(value: unknown): t.Labels;
+/** Copy caller labels before combining them with the SDK's protocol fields. */
+export declare function requestMetadata(value: t.Labels | null | undefined, reserved: Record<string, string>): Record<string, string>;
 export interface SessionPatch {
     truncation?: SessionSettings["truncation"];
     voice?: string;
@@ -76,16 +78,15 @@ export interface ItemDeleted {
 export interface AudioCleared {
     kind: "audio.cleared";
 }
-export interface ItemTruncated {
-    kind: "item.truncated";
-    itemId: string;
-    contentIndex: number;
+export interface SessionIdleTimeout {
+    kind: "session.idle_timeout";
+    idleTimeoutS: 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 ServerPayload = SessionCreated | Acknowledgment | t.InputEvent<t.NormalizedRealtimeFault> | t.MessageStarted | t.TextDelta | t.TextDone | t.AudioDelta | t.AudioDone | t.ToolCall | t.FaultEvent<t.NormalizedRealtimeFault>;
+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> | SessionIdleTimeout;
 export interface ServerEvent {
     eventId: string;
     requestId: string | null;
@@ -113,7 +114,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

@@ -12,6 +12,13 @@ export function responseMetadata(value) {
         throw new RimeInputError("responseMetadata must map keys to strings");
     return Object.freeze({ ...value });
 }
+/** Copy caller labels before combining them with the SDK's protocol fields. */
+export function requestMetadata(value, reserved) {
+    const labels = value == null ? {} : responseMetadata(value);
+    if (Object.keys(labels).some((key) => key.startsWith("prism_")))
+        throw new RimeInputError("request metadata keys cannot start with prism_");
+    return { ...labels, ...reserved };
+}
 /** A request carries its result type and checks it before exposing the result. */
 export class Request {
     kind;
@@ -67,6 +74,9 @@ function id(value, field) {
 function optionalString(value, field) {
     return value == null ? null : string(value, field);
 }
+function optionalId(value, field) {
+    return value == null ? null : id(value, field);
+}
 function integer(value, field) {
     if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
         return invalid(field);
@@ -77,6 +87,31 @@ 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 responseUsage(response) {
+    if (response.usage == null)
+        return null;
+    const usage = object(response.usage, "response.usage");
+    return Object.freeze({
+        inputTokens: integer(usage.input_tokens, "response.usage.input_tokens"),
+        outputTokens: integer(usage.output_tokens, "response.usage.output_tokens"),
+        totalTokens: integer(usage.total_tokens, "response.usage.total_tokens"),
+        contextWindow: integer(usage.context_window, "response.usage.context_window"),
+    });
+}
 function duration(value, field) {
     if (value == null)
         return null;
@@ -273,6 +308,15 @@ function decodeValue(value, sessionId) {
         case "conversation.item.deleted":
             payload = { kind: "item.deleted", itemId: id(event.item_id, "item_id") };
             break;
+        case "session.idle_timeout": {
+            if (event.reason !== "idle_timeout")
+                return invalid("reason");
+            const timeout = duration(event.idle_timeout_s, "idle_timeout_s");
+            if (timeout === null || timeout < 1)
+                return invalid("idle_timeout_s");
+            payload = { kind: "session.idle_timeout", idleTimeoutS: timeout };
+            break;
+        }
         case "input_audio_buffer.cleared":
             payload = { kind: "audio.cleared" };
             break;
@@ -281,6 +325,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":
@@ -380,6 +428,7 @@ function decodeValue(value, sessionId) {
                                 : "unknown",
                 parent: parent === null ? null : ref(parent),
                 inputItemId,
+                instructionItemId: optionalId(metadata.prism_instruction_item_id, "prism_instruction_item_id"),
                 metadata: clientMetadata(metadata),
                 inputItemIds: Object.freeze(inputItemIds.map((value) => id(value, "prism_input_item_ids"))),
             };
@@ -396,6 +445,8 @@ function decodeValue(value, sessionId) {
             payload = {
                 kind: "response.ended",
                 settingsRevision: revision(response),
+                truncation: responseTruncation(response),
+                usage: responseUsage(response),
                 response: ref(response.id),
                 status: status === "completed" ||
                     status === "cancelled" ||

package/dist/realtime/session.d.ts

@@ -56,7 +56,7 @@ export declare class RealtimeSession {
      * complete list. Replies already started keep their original settings.
      * Cancellation after submission does not undo an accepted update. */
     update(options?: t.RealtimeUpdateOptions): Promise<t.SessionInfo>;
-    sendText(value: string, options?: t.RealtimeOperationOptions): Promise<t.ResponseRef>;
+    sendText(value: string, options?: t.ReplyRequestOptions): Promise<t.ResponseRef>;
     requestReply(options?: t.ReplyOptions): Promise<t.ResponseRef>;
     /** Read the items the next reply would see, in server order. */
     getHistory(options?: t.RealtimeOperationOptions): Promise<readonly t.HistoryItem[]>;
@@ -66,7 +66,7 @@ export declare class RealtimeSession {
     createItem(item: t.HistoryItem, options?: t.HistoryCreateOptions): Promise<t.ItemRef>;
     addMessage(role: "user" | "assistant", value: string, options?: t.RealtimeOperationOptions): Promise<t.ItemRef>;
     submitToolResult(call: t.ToolCallRef, output: string, options?: t.RealtimeOperationOptions): Promise<void>;
-    continueReply(parent: t.ResponseRef, options?: t.RealtimeOperationOptions): Promise<t.ResponseRef>;
+    continueReply(parent: t.ResponseRef, options?: t.ReplyRequestOptions): Promise<t.ResponseRef>;
     cancel(response: t.ResponseRef, options?: t.RealtimeOperationOptions): Promise<void>;
     /** Replaces the labels later replies carry; a reply already started keeps
      * its own. Resolves once Prism confirms the change. */

package/dist/realtime/session.js

@@ -403,11 +403,19 @@ export class RealtimeSession {
     }
     async sendText(value, options = {}) {
         text(value);
-        return this.operation(options, (signal) => this.create({ prism_input_text: value, metadata: { prism_cause: "user_text" } }, signal, p.requests.text));
+        const metadata = p.requestMetadata(options.metadata, {
+            prism_cause: "user_text",
+        });
+        return this.operation(options, (signal) => this.create({
+            prism_input_text: value,
+            metadata,
+        }, signal, p.requests.text));
     }
     async requestReply(options = {}) {
         const body = {
-            metadata: { prism_cause: "proactive" },
+            metadata: p.requestMetadata(options.metadata, {
+                prism_cause: "proactive",
+            }),
         };
         if (options.instruction != null) {
             text(options.instruction);
@@ -498,6 +506,10 @@ export class RealtimeSession {
     }
     async continueReply(parent, options = {}) {
         const ref = { ...parent };
+        const metadata = p.requestMetadata(options.metadata, {
+            prism_cause: "tool_continuation",
+            prism_parent_response_id: ref.responseId,
+        });
         const state = this.response(ref);
         return this.operation(options, async (signal) => {
             const ready = scope([signal], this.timeouts.readyS, new t.RealtimeAdmissionTimeout("Tool results or parent completion did not arrive before readyS expired"));
@@ -522,10 +534,7 @@ export class RealtimeSession {
             }
             return (await this.request(p.requests.create, {
                 response: {
-                    metadata: {
-                        prism_cause: "tool_continuation",
-                        prism_parent_response_id: ref.responseId,
-                    },
+                    metadata,
                 },
             }, signal, undefined, state)).response;
         });
@@ -677,6 +686,9 @@ export class RealtimeSession {
                 throw new RimeStreamError("Tool result acknowledgment names another call");
         }
         switch (payload.kind) {
+            case "session.idle_timeout":
+                this.fail(new t.RealtimeIdleTimeout(payload.idleTimeoutS));
+                return;
             case "session.created":
                 if (this.sessionId === null) {
                     this.sessionId = payload.session.id;
@@ -752,7 +764,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

@@ -87,7 +87,11 @@ export interface RealtimeUpdateOptions extends RealtimeOperationOptions {
     readonly voice?: string;
     readonly interruptOnSpeech?: boolean;
 }
-export interface ReplyOptions extends RealtimeOperationOptions {
+export interface ReplyRequestOptions extends RealtimeOperationOptions {
+    /** Labels for this reply. Request labels override matching session labels. */
+    readonly metadata?: Labels | null;
+}
+export interface ReplyOptions extends ReplyRequestOptions {
     readonly instruction?: string | null;
     readonly toolCall?: ToolCallRef | null;
 }
@@ -178,6 +182,11 @@ export interface NormalizedRealtimeFault extends RealtimeFault {
 }
 export declare class RealtimeAdmissionTimeout extends RimeTimeoutError {
 }
+/** Prism closed the conversation after this many idle seconds. */
+export declare class RealtimeIdleTimeout extends RimeTimeoutError {
+    readonly idleTimeoutS: number;
+    constructor(idleTimeoutS: number);
+}
 export declare class RimeRealtimeError extends RimeError {
     readonly fault: NormalizedRealtimeFault;
     constructor(fault: RealtimeFault);
@@ -244,6 +253,8 @@ export interface ResponseStarted {
     readonly cause: "speech" | "text" | "proactive" | "tools" | "unknown";
     readonly parent: ResponseRef | null;
     readonly inputItemId: string | null;
+    /** Saved nudge instruction; pass this ID to deleteItem to remove it. */
+    readonly instructionItemId?: string | null;
     /** The session's labels when the reply began. Prism's `prism_` keys are
      * left out. */
     readonly metadata: Labels;
@@ -288,10 +299,28 @@ 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 ResponseUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly totalTokens: number;
+    readonly contextWindow: number;
+}
 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;
+    /** Null when Prism did not count tokens. */
+    readonly usage?: ResponseUsage | null;
     readonly kind: "response.ended";
     readonly response: ResponseRef;
     readonly status: "completed" | "cancelled" | "failed" | "unknown";
@@ -303,11 +332,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/dist/realtime/types.js

@@ -2,6 +2,14 @@ import { RimeError, RimeTimeoutError } from "../errors.js";
 import { normalizeFault } from "./faults.js";
 export class RealtimeAdmissionTimeout extends RimeTimeoutError {
 }
+/** Prism closed the conversation after this many idle seconds. */
+export class RealtimeIdleTimeout extends RimeTimeoutError {
+    idleTimeoutS;
+    constructor(idleTimeoutS) {
+        super(`Realtime session idle for ${idleTimeoutS} seconds`);
+        this.idleTimeoutS = idleTimeoutS;
+    }
+}
 export class RimeRealtimeError extends RimeError {
     fault;
     constructor(fault) {

package/docs/realtime.md

@@ -294,6 +294,12 @@ instruction, tool call, and signal in one object. `update` returns
 `getHistory` returns `Promise<readonly HistoryItem[]>`. The other methods return
 `Promise<void>`.
 
+Pass `metadata: { step: "3" }` in the options for `sendText`, `requestReply`, or
+`continueReply` to label only that reply. Request labels replace matching
+session labels in Prism's response. The SDK adds the required `prism_` fields;
+caller keys cannot use that prefix. Omitting `metadata` keeps the existing
+request shape. Replies to speech use the session labels.
+
 `sendText` and `addMessage` require nonblank text of at most 4,000 Unicode
 characters. `addMessage` accepts `"user"` and `"assistant"` roles. `createItem`
 also accepts `"system"` messages and allows blank message text, with the same
@@ -397,12 +403,12 @@ are exported from `@rimelabs/sdk`.
 | `input.committed` | `itemId` |
 | `transcript.delta`, `transcript.final` | `itemId` and `delta` or `text` |
 | `transcript.failed` | `itemId`, `error` |
-| `response.started` | `response`, `cause`, nullable `parent` and `inputItemId`, `inputItemIds` (the user items it answers), `metadata` (your own keys) |
+| `response.started` | `response`, `cause`, nullable `parent`, `inputItemId`, and `instructionItemId`, `inputItemIds` (the user items it answers), `metadata` (your own keys) |
 | `message.started` | `output` |
 | `text.delta`, `text.done` | `output` and `delta` or `text` |
 | `audio.delta`, `audio.done` | `output`; a delta also has `audio.data` and a complete `audio.format` |
 | `tool.call` | `call`, `itemId`, `name`, parsed `arguments` |
-| `response.ended` | `response`, `status`, nullable `reason` |
+| `response.ended` | `response`, `status`, nullable `reason` and `usage` |
 | `response.abandoned` | `response`; the SDK requests cancellation after the requesting caller aborted. |
 | `error` | `error`, a `RealtimeFault` |
 
@@ -460,6 +466,10 @@ the session remains usable. An unknown request outcome closes the connection and
 is never replayed. The SDK retries typed-turn admission only after named refusals
 that confirm the request made no change.
 
+`RealtimeIdleTimeout` means Prism closed an idle session. Its `idleTimeoutS`
+is the limit reported by Prism. Pending methods and the event iterator reject
+with this error. Reconnect to start a new conversation.
+
 Protocol faults appear as `error` events and can also reject an affected method
 with `RimeRealtimeError`. Its `.fault` has `code`, `message`, `scope`, nullable
 `requestId`, `responseId`, `itemId`, `correlationId`, `parameter`, and a `callIds`
@@ -587,3 +597,60 @@ 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`.
+
+## Response usage and saved nudge instructions
+
+`ResponseEnded.usage` contains `inputTokens`, `outputTokens`, `totalTokens`,
+and `contextWindow` when Prism counted the reply's tokens. It is `null` when
+the count is unavailable. For a nudge with an instruction,
+`ResponseStarted.instructionItemId` names the saved instruction. Pass that ID
+to `deleteItem` to remove it from later history.
+
+## 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.25",
   "description": "Rime streaming TTS, STT and Prism realtime SDK for Node.js",
   "license": "MIT",
   "type": "module",