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

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.1.0-alpha.26](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.25...typescript-v0.1.0-alpha.26) (2026-10-30)
+
+
+### Features
+
+* expose realtime connection diagnostics across SDKs ([#116](https://github.com/rimelabs/rime-sdk/issues/116)) ([da50cf4](https://github.com/rimelabs/rime-sdk/commit/da50cf41b0ca4631c0c71e48ef31cd207ab5e713))
+
+## [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/errors.d.ts

@@ -1,6 +1,18 @@
+/** Optional connection diagnostics. These fields do not initiate retries. */
+export interface RimeErrorOptions extends ErrorOptions {
+    /** Refused HTTP upgrade status, such as 503; null when unavailable. */
+    statusCode?: number | null;
+    /** Received WebSocket close code, such as 1013; null when unavailable. */
+    closeCode?: number | null;
+    /** Server-requested delay in seconds. Zero is valid; null means unavailable. */
+    retryAfterSeconds?: number | null;
+}
 export declare class RimeError extends Error {
     readonly requestId: string | null;
-    constructor(message: string, requestId?: string | null, options?: ErrorOptions);
+    readonly statusCode: number | null;
+    readonly closeCode: number | null;
+    readonly retryAfterSeconds: number | null;
+    constructor(message: string, requestId?: string | null, options?: RimeErrorOptions);
 }
 export declare class RimeAuthenticationError extends RimeError {
 }

package/dist/errors.js

@@ -1,9 +1,15 @@
 export class RimeError extends Error {
     requestId;
+    statusCode;
+    closeCode;
+    retryAfterSeconds;
     constructor(message, requestId = null, options) {
         super(message, options);
         this.name = new.target.name;
         this.requestId = requestId;
+        this.statusCode = options?.statusCode ?? null;
+        this.closeCode = options?.closeCode ?? null;
+        this.retryAfterSeconds = options?.retryAfterSeconds ?? null;
     }
 }
 export class RimeAuthenticationError extends RimeError {

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

@@ -1,7 +1,83 @@
 import WebSocket from "ws";
 import { RimeAuthenticationError, RimeResourceLimitError, RimeStreamError, RimeUnavailableError, } from "../errors.js";
 import { Deferred } from "./async.js";
-function handshakeError(status, body, requestId) {
+const months = "Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec".split(" ");
+const dayName = "(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun)";
+const monthName = `(?:${months.join("|")})`;
+const clock = "([0-9]{2}):([0-9]{2}):([0-9]{2})";
+const imfDate = new RegExp(`^${dayName}, ([0-9]{2}) (${monthName}) ([0-9]{4}) ${clock} GMT$`);
+const rfc850Date = new RegExp(`^(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), ([0-9]{2})-(${monthName})-([0-9]{2}) ${clock} GMT$`);
+const asctimeDate = new RegExp(`^${dayName} (${monthName}) ([0-9]{2}| [0-9]) ${clock} ([0-9]{4})$`);
+function httpDate(value, now) {
+    let parts = imfDate.exec(value);
+    let shortYear = false;
+    if (!parts) {
+        parts = rfc850Date.exec(value);
+        shortYear = parts !== null;
+    }
+    if (!parts) {
+        const legacy = asctimeDate.exec(value);
+        if (!legacy)
+            return null;
+        parts = [
+            legacy[0],
+            legacy[2],
+            legacy[1],
+            legacy[6],
+            legacy[3],
+            legacy[4],
+            legacy[5],
+        ];
+    }
+    const day = Number(parts[1]);
+    const month = months.indexOf(parts[2]);
+    let year = Number(parts[3]);
+    const hour = Number(parts[4]);
+    const minute = Number(parts[5]);
+    const second = Number(parts[6]);
+    if (shortYear) {
+        const current = new Date(now);
+        const limit = [
+            current.getUTCFullYear() + 50,
+            current.getUTCMonth(),
+            current.getUTCDate(),
+            current.getUTCHours(),
+            current.getUTCMinutes(),
+            current.getUTCSeconds(),
+        ];
+        year += Math.floor(limit[0] / 100) * 100;
+        const candidate = [year, month, day, hour, minute, second];
+        const difference = candidate.findIndex((part, index) => part !== limit[index]);
+        if (difference !== -1 && candidate[difference] > limit[difference])
+            year -= 100;
+    }
+    // Use setters so years 0000–0099 aren't silently changed to 1900–1999.
+    const date = new Date(0);
+    date.setUTCFullYear(year, month, day);
+    date.setUTCHours(hour, minute, second, 0);
+    if (year < 1 ||
+        date.getUTCFullYear() !== year ||
+        date.getUTCMonth() !== month ||
+        date.getUTCDate() !== day ||
+        date.getUTCHours() !== hour ||
+        date.getUTCMinutes() !== minute ||
+        date.getUTCSeconds() !== second)
+        return null;
+    return date.getTime();
+}
+function retryAfter(values) {
+    if (values?.length !== 1 || values[0].length > 256)
+        return null;
+    const value = values[0].trim();
+    if (/^[0-9]+$/.test(value)) {
+        const seconds = Number(value);
+        return Number.isFinite(seconds) ? seconds : null;
+    }
+    const now = Date.now();
+    const date = httpDate(value, now);
+    return date === null ? null : Math.max(0, (date - now) / 1000);
+}
+function handshakeError(status, body, requestId, retryAfterSeconds) {
     let errorType = RimeUnavailableError;
     let reason = "Realtime endpoint rejected the connection";
     if ([401, 403].includes(status)) {
@@ -35,7 +111,10 @@ function handshakeError(status, body, requestId) {
             // Invalid response bodies do not change the HTTP error category.
         }
     }
-    return new errorType(message, requestId);
+    return new errorType(message, requestId, {
+        statusCode: status,
+        retryAfterSeconds,
+    });
 }
 /** Private transport. The public declarations do not require ws types. */
 export class RealtimeConnection {
@@ -74,7 +153,7 @@ export class RealtimeConnection {
                 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));
+                this.failure(handshakeError(response.statusCode ?? 0, complete ? Buffer.concat(chunks) : Buffer.alloc(0), typeof id === "string" ? id : null, retryAfter(response.headersDistinct["retry-after"])));
                 response.destroy();
                 request.destroy();
                 this.socket.terminate();
@@ -104,10 +183,10 @@ export class RealtimeConnection {
             }
             this.onMessage(data.toString());
         });
-        this.socket.on("close", () => {
+        this.socket.on("close", (code) => {
             this.refusal?.();
             this.ended.resolve();
-            this.failure(new RimeStreamError("Realtime connection closed; reconnect is not automatic"));
+            this.failure(new RimeStreamError("Realtime connection closed; reconnect is not automatic", null, { closeCode: code === 1005 || code === 1006 ? null : code }));
         });
     }
     failure(error) {

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` |
 
@@ -446,6 +452,20 @@ The voice examples report actual playback.
 
 ## Timeouts and failures
 
+`RimeError` exposes `statusCode` for a refused HTTP upgrade, `closeCode` for a
+received WebSocket close code, and `retryAfterSeconds` for the server's requested
+delay. For example, a busy endpoint can return `statusCode=503` and
+`retryAfterSeconds=2`. Missing values are `null`; zero is a valid delay. The
+existing `requestId` retains the server's request ID on an HTTP refusal.
+Invalid or duplicate `Retry-After` headers are ignored. HTTP dates become a delay
+relative to the client clock, with past dates becoming zero.
+
+Error categories stay the same. A WebSocket closure uses `RimeStreamError`;
+no received close code means `closeCode=null`, including a lost connection or
+an empty close frame. These fields require a release with structured connection
+diagnostics. The SDK does not retry startup automatically. These fields do not
+make replay of an accepted request safe.
+
 Configure positive, finite seconds through `timeouts`. `connectS` bounds the
 WebSocket handshake and initial session event. `readyS` bounds turn admission,
 tool readiness, and waiting for generation to end before a playback report.
@@ -460,6 +480,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 +640,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.26",
   "description": "Rime streaming TTS, STT and Prism realtime SDK for Node.js",
   "license": "MIT",
   "type": "module",