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

package/CHANGELOG.md

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

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,11 +78,15 @@ export interface ItemDeleted {
 export interface AudioCleared {
     kind: "audio.cleared";
 }
+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 | 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 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;

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);
@@ -91,6 +101,17 @@ function responseTruncation(response) {
             : 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;
@@ -287,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;
@@ -398,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"))),
             };
@@ -415,6 +446,7 @@ function decodeValue(value, sessionId) {
                 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;

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;
@@ -295,6 +306,12 @@ export interface ResponseTruncation {
     /** 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. */
@@ -302,6 +319,8 @@ export interface ResponseEnded {
     /** 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";

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`
@@ -616,6 +626,14 @@ This event can arrive after `response.ended`. It has no response reference and d
 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

package/package.json

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