@rimelabs/sdk 0.1.0-alpha.20 → 0.1.0-alpha.21

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.1.0-alpha.21](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.20...typescript-v0.1.0-alpha.21) (2026-10-23)
+
+
+### ⚠ BREAKING CHANGES
+
+* Rust RealtimeSession::info returns an owned SessionInfo snapshot instead of a reference so cloned handles can read current settings.
+
+### Features
+
+* expose Prism error retry classification ([#99](https://github.com/rimelabs/rime-sdk/issues/99)) ([c04309c](https://github.com/rimelabs/rime-sdk/commit/c04309c174c2eed82df3b676581c45cab2a95db6))
+* **realtime:** request ids, reply labels, and the items a reply answers ([#95](https://github.com/rimelabs/rime-sdk/issues/95)) ([f33950b](https://github.com/rimelabs/rime-sdk/commit/f33950b2d0fdb960f4701c1a1ec208c0d539d5ec))
+* support mid-session Prism settings updates in all SDKs ([#101](https://github.com/rimelabs/rime-sdk/issues/101)) ([83f5347](https://github.com/rimelabs/rime-sdk/commit/83f534761418217292fbbce8dbdc47454ad5ddb8))
+
 ## [0.1.0-alpha.20](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.19...typescript-v0.1.0-alpha.20) (2026-10-22)
 
 

package/README.md

@@ -324,6 +324,7 @@ See the [TTS guide](https://github.com/rimelabs/rime-sdk/blob/main/typescript/do
 for more examples. Visit [Rime documentation](https://docs.rime.ai/) for service
 information, or report SDK issues on [GitHub](https://github.com/rimelabs/rime-sdk/issues).
 Include the SDK version and the error's `requestId` when available; omit API keys.
+For Prism, include `session.info.requestId`.
 
 SDK code uses the [MIT license](LICENSE). The Prism protocol module uses
 [Apache 2.0](LICENSE-PRISM); see its [notices](NOTICE-PRISM).

package/dist/realtime/client.js

@@ -3,6 +3,8 @@ import { RimeCancelledError, RimeInputError, RimeUnavailableError, } from "../er
 import { cancellation, scope } from "./async.js";
 import { RealtimeSession } from "./session.js";
 import { RealtimeConnection } from "./transport.js";
+import { toolSettings } from "./settings.js";
+import { responseMetadata } from "./protocol.js";
 const DEFAULT_ENDPOINT = "wss://prism.api.rime.ai/v1/realtime";
 function endpoint(value) {
     let url;
@@ -34,48 +36,6 @@ function timeouts(options = {}) {
         throw new RimeInputError("Timeouts must be finite and positive");
     return result;
 }
-/** Reject values that JSON.stringify would silently drop or change. */
-function copyJson(value) {
-    if (value === null || typeof value === "string" || typeof value === "boolean")
-        return value;
-    if (typeof value === "number" && Number.isFinite(value))
-        return value;
-    if (Array.isArray(value))
-        return Array.from(value, copyJson);
-    if (value &&
-        typeof value === "object" &&
-        [Object.prototype, null].includes(Object.getPrototypeOf(value)))
-        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, copyJson(item)]));
-    throw new RimeInputError("Tool schemas must contain finite JSON values");
-}
-function fillerSettings(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        throw new RimeInputError("prismFiller must be a filler object");
-    const kind = value.type;
-    if (!["none", "text", "auto"].includes(kind))
-        throw new RimeInputError("Prism filler type must be none, text, or auto");
-    const field = kind === "text" ? "text" : kind === "auto" ? "instructions" : null;
-    if (Object.entries(value).some(([key, item]) => item !== undefined && key !== "type" && key !== field))
-        throw new RimeInputError("Prism filler has fields not allowed for its type");
-    const text = field === null ? undefined : value[field];
-    if (kind === "text" || text !== undefined) {
-        // Rust str::trim uses Unicode White_Space, which differs from JS trim.
-        if (typeof text !== "string" ||
-            !/\P{White_Space}/u.test(text) ||
-            [...text].length > 500)
-            throw new RimeInputError("Prism filler text must be nonblank and at most 500 characters");
-        // Unicode mode matches lone surrogates but preserves valid UTF-16 pairs.
-        if (/[\uD800-\uDFFF]/u.test(text))
-            throw new RimeInputError("Prism filler text must be valid UTF-8");
-    }
-    if (kind === "text")
-        return { type: "text", text: text };
-    if (kind === "auto")
-        return text === undefined
-            ? { type: "auto" }
-            : { type: "auto", instructions: text };
-    return { type: "none" };
-}
 export class Realtime {
     credentials;
     checkOpen;
@@ -94,46 +54,11 @@ export class Realtime {
         if (options.interruptOnSpeech !== undefined &&
             typeof options.interruptOnSpeech !== "boolean")
             throw new RimeInputError("interruptOnSpeech must be a boolean");
-        const names = new Set();
         const settings = {
             modalities: ["text", "audio"],
             input_audio_format: "pcm16",
             turn_detection: { interrupt_response: options.interruptOnSpeech ?? true },
-            tools: (options.tools ?? []).map((tool) => {
-                if (typeof tool.name !== "string" ||
-                    !tool.name.trim() ||
-                    names.has(tool.name))
-                    throw new RimeInputError("Tool names must be nonblank and unique");
-                names.add(tool.name);
-                if (!tool.parameters ||
-                    Array.isArray(tool.parameters) ||
-                    typeof tool.parameters !== "object" ||
-                    (tool.description !== undefined &&
-                        typeof tool.description !== "string"))
-                    throw new RimeInputError("Tool parameters must be a JSON object and description must be a string");
-                let parameters;
-                try {
-                    parameters = copyJson(tool.parameters);
-                }
-                catch {
-                    throw new RimeInputError("Tool schemas must contain finite JSON values");
-                }
-                if (parameters === null ||
-                    typeof parameters !== "object" ||
-                    Array.isArray(parameters))
-                    throw new RimeInputError("Tool parameters must be an object");
-                return {
-                    type: "function",
-                    ...(tool.prismFiller === undefined
-                        ? {}
-                        : { prism_filler: fillerSettings(tool.prismFiller) }),
-                    function: {
-                        name: tool.name,
-                        description: tool.description ?? "",
-                        parameters,
-                    },
-                };
-            }),
+            tools: toolSettings(options.tools ?? []),
         };
         if (options.turnDetection !== undefined) {
             const detection = options.turnDetection;
@@ -153,6 +78,14 @@ export class Realtime {
                 settings.turn_detection.prism_end_of_turn_timeout_ms = value;
             }
         }
+        if (options.responseMetadata != null)
+            settings.prism_response_metadata = responseMetadata(options.responseMetadata);
+        const requestId = options.requestId ?? undefined;
+        if (requestId !== undefined &&
+            (typeof requestId !== "string" ||
+                !requestId.trim() ||
+                !/^[\x20-\x7e]+$/.test(requestId)))
+            throw new RimeInputError("requestId must be nonblank printable ASCII");
         for (const name of ["voice", "instructions"]) {
             const value = options[name];
             if (value !== undefined && value !== null) {
@@ -170,7 +103,7 @@ export class Realtime {
                 openingScope.signal.throwIfAborted();
                 let socket;
                 try {
-                    socket = new RealtimeConnection(address, this.credentials.realtimeAuthorization());
+                    socket = new RealtimeConnection(address, this.credentials.realtimeAuthorization(), requestId);
                 }
                 catch {
                     throw new RimeUnavailableError("Realtime handshake failed");

package/dist/realtime/conversation.d.ts

@@ -1,5 +1,5 @@
 import type { RealtimeSession } from "./session.js";
-import type { AudioChunk, OutputRef, SessionEvent } from "./types.js";
+import type { AudioChunk, NormalizedRealtimeFault, OutputRef, SessionEvent } from "./types.js";
 export interface ConversationSource {
     /** Return one chunk, or null at EOF. Abort must release a pending read. */
     read(signal: AbortSignal): Promise<AudioChunk | null>;
@@ -34,7 +34,7 @@ export interface ConversationOptions {
     readonly playback: ConversationPlayback;
     /** Called inline for every event. Must be synchronous and nonblocking.
      * Scheduled application work remains the caller's responsibility. */
-    readonly onEvent?: (event: SessionEvent) => void;
+    readonly onEvent?: (event: SessionEvent<NormalizedRealtimeFault>) => void;
     readonly signal?: AbortSignal;
 }
 /** Run until input EOF, session closure, failure, or abort.

package/dist/realtime/conversation.js

@@ -1,7 +1,7 @@
 import { abortable, scope } from "../cancellation.js";
 import { RimeCancelledError, RimeInputError, RimeResourceLimitError, RimeTimeoutError, } from "../errors.js";
 import { Deferred } from "./async.js";
-import { isSessionCloseError } from "./session.js";
+import { isSessionCloseError, responseInterruptsSpeech } from "./session.js";
 import { RimeRealtimeError } from "./types.js";
 /** Run until input EOF, session closure, failure, or abort.
  * Owns the session's active lifetime and closes it on exit. The caller owns
@@ -171,7 +171,12 @@ export async function runConversation(session, { source, playback, onEvent, sign
                 stream,
                 receipt: start(() => measure(stream)),
                 sealed: false,
+                measured: false,
             };
+            const measuredOutput = output;
+            void output.receipt.then(() => {
+                measuredOutput.measured = true;
+            }, () => { });
             reply.outputs.set(key, output);
             if (reply.interrupted) {
                 playback.interrupt([ref]);
@@ -209,6 +214,7 @@ export async function runConversation(session, { source, playback, onEvent, sign
                         interrupted.add(id);
                     replies.set(id, {
                         ref: payload.response,
+                        interruptOnSpeech: responseInterruptsSpeech(session, payload.response),
                         outputs: new Map(),
                         interrupted: blocked,
                         ended: false,
@@ -229,10 +235,16 @@ export async function runConversation(session, { source, playback, onEvent, sign
                     }
                     break;
                 }
-                case "speech.started":
-                    if (session.info.interruptOnSpeech)
-                        interrupt([...replies.values()]);
+                case "speech.started": {
+                    // The newest eligible reply controls the playback batch.
+                    // A pending finished report is no longer physical playback.
+                    const eligible = [...replies.values()].filter((reply) => !reply.interrupted &&
+                        (!reply.ended ||
+                            [...reply.outputs.values()].some((output) => !output.measured)));
+                    if (eligible.at(-1)?.interruptOnSpeech)
+                        interrupt(eligible);
                     break;
+                }
                 case "response.abandoned": {
                     if (parents.has(payload.response.responseId))
                         interrupted.add(payload.response.responseId);

package/dist/realtime/faults.d.ts

@@ -0,0 +1,2 @@
+import type { NormalizedRealtimeFault, RealtimeFault } from "./types.js";
+export declare function normalizeFault(fault: RealtimeFault): NormalizedRealtimeFault;

package/dist/realtime/faults.js

@@ -0,0 +1,25 @@
+// Reuse SDK-normalized faults so events and rejected requests share one object.
+const normalizedFaults = new WeakSet();
+export function normalizeFault(fault) {
+    if (normalizedFaults.has(fault))
+        return fault;
+    const snapshot = {
+        code: fault.code,
+        message: fault.message,
+        scope: fault.scope,
+        requestId: fault.requestId,
+        responseId: fault.responseId,
+        itemId: fault.itemId,
+        callIds: Object.freeze([...(fault.callIds ?? [])]),
+        correlationId: fault.correlationId,
+        parameter: fault.parameter,
+    };
+    const normalized = Object.freeze({
+        ...snapshot,
+        retryable: snapshot.code === "capacity_exceeded" ||
+            snapshot.code === "unavailable" ||
+            snapshot.code === "response_timeout",
+    });
+    normalizedFaults.add(normalized);
+    return normalized;
+}

package/dist/realtime/protocol.d.ts

@@ -18,9 +18,23 @@ export interface SessionSettings {
     }[];
     voice?: string;
     instructions?: string;
+    prism_response_metadata?: t.Labels;
+}
+/** A copy of the client's labels for every reply: keys to strings. */
+export declare function responseMetadata(value: unknown): t.Labels;
+export interface SessionPatch {
+    voice?: string;
+    instructions?: string;
+    tools?: SessionSettings["tools"];
+    turn_detection?: {
+        interrupt_response: boolean;
+    };
 }
 export interface SessionView {
+    settingsRevision: number | null;
     id: string;
+    requestId: string | null;
+    responseMetadata: t.Labels | null;
     voice: string;
     interruptOnSpeech: boolean | null;
     toolResultTimeoutS: number | null;
@@ -32,6 +46,7 @@ export interface SessionCreated {
     session: SessionView;
 }
 export interface SessionUpdated {
+    info?: t.SessionInfo;
     kind: "session.updated";
     session: SessionView;
 }
@@ -55,7 +70,7 @@ export interface ResponseEnded extends t.ResponseEnded {
     drainToken: string | null;
 }
 export type Acknowledgment = SessionUpdated | ItemCreated | ToolResultCreated | AudioCleared | ItemTruncated | t.ResponseStarted | ResponseEnded;
-export type ServerPayload = SessionCreated | Acknowledgment | t.InputEvent | t.MessageStarted | t.TextDelta | t.TextDone | t.AudioDelta | t.AudioDone | t.ToolCall | t.FaultEvent;
+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;
     requestId: string | null;

package/dist/realtime/protocol.js

@@ -1,6 +1,16 @@
 // SPDX-License-Identifier: Apache-2.0
 /** Decode only the protocol fields the SDK uses. Unknown events and fields stay open. */
-import { RimeStreamError } from "../errors.js";
+import { RimeInputError, RimeStreamError } from "../errors.js";
+import { normalizeFault } from "./faults.js";
+/** A copy of the client's labels for every reply: keys to strings. */
+export function responseMetadata(value) {
+    if (!value ||
+        typeof value !== "object" ||
+        ![Object.prototype, null].includes(Object.getPrototypeOf(value)) ||
+        Object.values(value).some((label) => typeof label !== "string"))
+        throw new RimeInputError("responseMetadata must map keys to strings");
+    return Object.freeze({ ...value });
+}
 /** A request carries its result type and checks it before exposing the result. */
 export class Request {
     kind;
@@ -57,6 +67,11 @@ function integer(value, field) {
         return invalid(field);
     return value;
 }
+function revision(value) {
+    return value.prism_settings_revision === undefined
+        ? null
+        : integer(value.prism_settings_revision, "prism_settings_revision");
+}
 function duration(value, field) {
     if (value == null)
         return null;
@@ -100,7 +115,12 @@ function session(value) {
     if (interrupt !== undefined && typeof interrupt !== "boolean")
         invalid("session.prism_effective_interrupt_response");
     return {
+        settingsRevision: revision(view),
         id: id(view.id, "session.id"),
+        requestId: optionalString(view.request_id, "session.request_id"),
+        responseMetadata: view.prism_response_metadata === undefined
+            ? null
+            : clientMetadata(object(view.prism_response_metadata, "session.prism_response_metadata")),
         voice: view.voice === undefined ? "" : string(view.voice, "session.voice"),
         interruptOnSpeech: interrupt ?? null,
         turnDetection: Object.freeze({ eagerness, endOfTurnTimeoutMs }),
@@ -108,6 +128,11 @@ function session(value) {
         toolContinuationTimeoutS: duration(waits.continuation_timeout_s, "continuation_timeout_s"),
     };
 }
+/** The client's labels in `metadata`: its string values under keys that are
+ * not Prism's `prism_` ones. */
+function clientMetadata(metadata) {
+    return Object.freeze(Object.fromEntries(Object.entries(metadata).filter((entry) => !entry[0].startsWith("prism_") && typeof entry[1] === "string")));
+}
 function fault(value) {
     const error = object(value, "error");
     const owner = error.owner == null ? {} : object(error.owner, "error.owner");
@@ -115,8 +140,9 @@ function fault(value) {
     const calls = owner.call_ids ?? [];
     if (!Array.isArray(calls))
         return invalid("error.owner.call_ids");
-    return Object.freeze({
-        code: error.code === undefined ? "unknown" : string(error.code, "error.code"),
+    const code = error.code === undefined ? "unknown" : string(error.code, "error.code");
+    return normalizeFault({
+        code,
         message: error.message === undefined ? "" : string(error.message, "error.message"),
         scope: scope === "event" ||
             scope === "utterance" ||
@@ -128,7 +154,7 @@ function fault(value) {
         requestId: optionalString(owner.event_id, "error.owner.event_id"),
         responseId: optionalString(owner.response_id, "error.owner.response_id"),
         itemId: optionalString(owner.item_id, "error.owner.item_id"),
-        callIds: Object.freeze(calls.map((value) => id(value, "error.owner.call_ids"))),
+        callIds: calls.map((value) => id(value, "error.owner.call_ids")),
         correlationId: optionalString(error.correlation_id, "error.correlation_id"),
         parameter: optionalString(error.param, "error.param"),
     });
@@ -291,8 +317,14 @@ function decodeValue(value, sessionId) {
                 ? undefined
                 : string(metadata.prism_cause, "prism_cause");
             const parent = optionalString(metadata.prism_parent_response_id, "prism_parent_response_id");
+            const inputItemId = optionalString(metadata.prism_input_item_id, "prism_input_item_id");
+            const inputItemIds = response.prism_input_item_ids ??
+                (inputItemId === null ? [] : [inputItemId]);
+            if (!Array.isArray(inputItemIds))
+                return invalid("prism_input_item_ids");
             payload = {
                 kind: "response.started",
+                settingsRevision: revision(response),
                 response: ref(response.id),
                 cause: cause === undefined
                     ? "speech"
@@ -304,7 +336,9 @@ function decodeValue(value, sessionId) {
                                 ? "proactive"
                                 : "unknown",
                 parent: parent === null ? null : ref(parent),
-                inputItemId: optionalString(metadata.prism_input_item_id, "prism_input_item_id"),
+                inputItemId,
+                metadata: clientMetadata(metadata),
+                inputItemIds: Object.freeze(inputItemIds.map((value) => id(value, "prism_input_item_ids"))),
             };
             break;
         }
@@ -318,6 +352,7 @@ function decodeValue(value, sessionId) {
             const status = string(response.status, "response.status");
             payload = {
                 kind: "response.ended",
+                settingsRevision: revision(response),
                 response: ref(response.id),
                 status: status === "completed" ||
                     status === "cancelled" ||

package/dist/realtime/session.d.ts

@@ -1,6 +1,8 @@
 import { RealtimeConnection } from "./transport.js";
 import * as t from "./types.js";
 import * as p from "./protocol.js";
+/** @internal Read the policy captured before queuing the response event. */
+export declare function responseInterruptsSpeech(session: RealtimeSession, response: t.ResponseRef): boolean;
 /** @internal Recognize only failures created by intentional session closure. */
 export declare function isSessionCloseError(error: unknown): boolean;
 /** One conversation. Consume events concurrently with session operations. */
@@ -27,6 +29,7 @@ export declare class RealtimeSession {
     private readonly toolLock;
     private readonly pending;
     private readonly responses;
+    private readonly interruptionPolicies;
     private latest;
     private readonly tasks;
     private converter;
@@ -35,7 +38,7 @@ export declare class RealtimeSession {
     /** @internal */
     initialize(settings: p.SessionSettings, signal: AbortSignal): Promise<void>;
     get info(): t.SessionInfo;
-    get events(): AsyncIterableIterator<t.SessionEvent>;
+    get events(): AsyncIterableIterator<t.SessionEvent<t.NormalizedRealtimeFault>>;
     private readEvents;
     private id;
     private check;
@@ -49,12 +52,19 @@ export declare class RealtimeSession {
     private runRequest;
     private abandon;
     private create;
+    /** Apply supplied settings and wait for acknowledgment. Tools replace the
+     * 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>;
     requestReply(options?: t.ReplyOptions): Promise<t.ResponseRef>;
     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>;
     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. */
+    setResponseMetadata(metadata: t.Labels, options?: t.RealtimeOperationOptions): Promise<void>;
     clearAudio(options?: t.RealtimeOperationOptions): Promise<void>;
     sendAudio(chunk: t.AudioChunk, options?: t.RealtimeOperationOptions): Promise<void>;
     reportPlayback(report: t.PlaybackReport, options?: t.RealtimeOperationOptions): Promise<void>;

package/dist/realtime/session.js

@@ -10,6 +10,7 @@ import { formatOf } from "./audio.js";
 import { InputConverter } from "../pcm.js";
 import * as t from "./types.js";
 import * as p from "./protocol.js";
+import { InterruptionPolicies, toolSettings } from "./settings.js";
 const NOT_READY = new Set([
     "typed_turn_busy",
     "instructions_busy",
@@ -17,6 +18,11 @@ const NOT_READY = new Set([
 ]);
 const LIMIT = 128;
 const closeErrors = new WeakSet();
+const responseInterruptions = new WeakMap();
+/** @internal Read the policy captured before queuing the response event. */
+export function responseInterruptsSpeech(session, response) {
+    return responseInterruptions.get(response) ?? session.info.interruptOnSpeech;
+}
 /** @internal Recognize only failures created by intentional session closure. */
 export function isSessionCloseError(error) {
     return error instanceof Error && closeErrors.has(error);
@@ -70,6 +76,7 @@ export class RealtimeSession {
     toolLock = new Mutex();
     pending = new Map();
     responses = new Map();
+    interruptionPolicies = new InterruptionPolicies();
     latest = null;
     tasks = new Set();
     converter = null;
@@ -106,16 +113,7 @@ export class RealtimeSession {
             deadline.dispose();
         }
         const event = await this.request(p.requests.update, { session: settings }, signal);
-        const view = event.session;
-        this.sessionInfo = Object.freeze({
-            sessionId: this.id(),
-            model: "prism",
-            voice: view.voice ?? "",
-            interruptOnSpeech: view.interruptOnSpeech ?? settings.turn_detection.interrupt_response,
-            toolResultTimeoutS: view.toolResultTimeoutS ?? null,
-            toolContinuationTimeoutS: view.toolContinuationTimeoutS ?? null,
-            turnDetection: view.turnDetection,
-        });
+        this.sessionInfo = event.info;
     }
     get info() {
         if (!this.sessionInfo)
@@ -266,7 +264,14 @@ export class RealtimeSession {
         const kind = request.kind;
         const eventId = `evt_${randomUUID().replaceAll("-", "")}`;
         const result = new Deferred();
-        this.pending.set(eventId, { request, result, target });
+        this.pending.set(eventId, {
+            request,
+            result,
+            target,
+            interruptOnSpeech: request.kind === "session.update"
+                ? body.session.turn_detection?.interrupt_response
+                : undefined,
+        });
         const deadline = scope([this.lifetime.signal], this.timeouts.requestS, new RimeTimeoutError(`${kind}: no acknowledgment; outcome unknown`, eventId));
         let submitted = false;
         // Cancellation can prevent a write. After submission, keep matching its outcome.
@@ -357,6 +362,33 @@ export class RealtimeSession {
             release();
         }
     }
+    /** Apply supplied settings and wait for acknowledgment. Tools replace the
+     * complete list. Replies already started keep their original settings.
+     * Cancellation after submission does not undo an accepted update. */
+    async update(options = {}) {
+        const settings = {};
+        for (const name of ["instructions", "voice"]) {
+            const value = options[name];
+            if (value !== undefined) {
+                if (typeof value !== "string")
+                    throw new RimeInputError(`${name} must be a string`);
+                settings[name] = value;
+            }
+        }
+        if (options.tools !== undefined)
+            settings.tools = toolSettings(options.tools);
+        if (options.interruptOnSpeech !== undefined) {
+            if (typeof options.interruptOnSpeech !== "boolean")
+                throw new RimeInputError("interruptOnSpeech must be a boolean");
+            settings.turn_detection = {
+                interrupt_response: options.interruptOnSpeech,
+            };
+        }
+        return this.operation(options, async (signal) => {
+            const event = await this.request(p.requests.update, { session: settings }, signal);
+            return event.info;
+        });
+    }
     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));
@@ -459,6 +491,14 @@ export class RealtimeSession {
                 await this.request(p.requests.cancel, { response_id: state.ref.responseId }, signal, state.ref.responseId);
         }));
     }
+    /** Replaces the labels later replies carry; a reply already started keeps
+     * its own. Resolves once Prism confirms the change. */
+    async setResponseMetadata(metadata, options = {}) {
+        const labels = p.responseMetadata(metadata);
+        return this.operation(options, async (signal) => {
+            await this.request(p.requests.update, { session: { prism_response_metadata: labels } }, signal);
+        });
+    }
     async clearAudio(options = {}) {
         return this.operation(options, (signal) => this.locked(this.audioLock, signal, async () => {
             await this.request(p.requests.clear, {}, signal);
@@ -588,7 +628,30 @@ export class RealtimeSession {
                     this.created.resolve(payload.session);
                 }
                 return;
-            case "session.updated":
+            case "session.updated": {
+                const view = payload.session;
+                const pending = this.pending.get(echo ?? "");
+                if (!pending)
+                    return;
+                this.sessionInfo = Object.freeze({
+                    sessionId: this.id(),
+                    model: "prism",
+                    voice: view.voice,
+                    interruptOnSpeech: view.interruptOnSpeech ??
+                        pending?.interruptOnSpeech ??
+                        this.sessionInfo?.interruptOnSpeech ??
+                        true,
+                    toolResultTimeoutS: view.toolResultTimeoutS,
+                    toolContinuationTimeoutS: view.toolContinuationTimeoutS,
+                    turnDetection: view.turnDetection,
+                    settingsRevision: view.settingsRevision,
+                    requestId: view.requestId,
+                    responseMetadata: view.responseMetadata,
+                });
+                this.interruptionPolicies.record(view.settingsRevision, this.sessionInfo.interruptOnSpeech);
+                this.settle(echo, { ...payload, info: this.sessionInfo });
+                return;
+            }
             case "tool.result.created":
                 this.settle(echo, payload);
                 return;
@@ -630,6 +693,7 @@ export class RealtimeSession {
                 const ref = payload.response;
                 if (this.responses.has(ref.responseId))
                     throw new RimeStreamError("Duplicate response.created");
+                responseInterruptions.set(ref, this.interruptionPolicies.resolve(payload.settingsRevision));
                 this.responses.set(ref.responseId, new ResponseState(ref));
                 for (const state of this.responses.values())
                     state.changed.set();

package/dist/realtime/settings.d.ts

@@ -0,0 +1,11 @@
+import type { ToolDefinition } from "./types.js";
+import type { SessionSettings } from "./protocol.js";
+export declare function toolSettings(tools: readonly ToolDefinition[]): SessionSettings["tools"];
+/** Bounded policy changes used to resolve each reply's settings revision. */
+export declare class InterruptionPolicies {
+    private changes;
+    private current;
+    private lastRevision;
+    record(revision: number | null, interrupt: boolean): void;
+    resolve(revision: number | null | undefined): boolean;
+}

package/dist/realtime/settings.js

@@ -0,0 +1,142 @@
+import { RimeInputError, RimeResourceLimitError } from "../errors.js";
+function toolString(value) {
+    // Unicode mode matches lone surrogates without rejecting valid UTF-16 pairs.
+    if (/[\uD800-\uDFFF]/u.test(value))
+        throw new RimeInputError("Tool strings must be valid UTF-8");
+    return value;
+}
+/** Reject values that JSON.stringify would silently drop or change. */
+function copyJson(value) {
+    if (typeof value === "string")
+        return toolString(value);
+    if (value === null || typeof value === "boolean")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (Array.isArray(value))
+        return Array.from(value, copyJson);
+    if (value &&
+        typeof value === "object" &&
+        [Object.prototype, null].includes(Object.getPrototypeOf(value)))
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            toolString(key),
+            copyJson(item),
+        ]));
+    throw new RimeInputError("Tool schemas must contain finite JSON values");
+}
+function fillerSettings(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new RimeInputError("prismFiller must be a filler object");
+    const kind = value.type;
+    if (!["none", "text", "auto"].includes(kind))
+        throw new RimeInputError("Prism filler type must be none, text, or auto");
+    const field = kind === "text" ? "text" : kind === "auto" ? "instructions" : null;
+    if (Object.entries(value).some(([key, item]) => item !== undefined && key !== "type" && key !== field))
+        throw new RimeInputError("Prism filler has fields not allowed for its type");
+    const text = field === null ? undefined : value[field];
+    if (kind === "text" || text !== undefined) {
+        // Rust str::trim uses Unicode White_Space, which differs from JS trim.
+        if (typeof text !== "string" ||
+            !/\P{White_Space}/u.test(text) ||
+            [...text].length > 500)
+            throw new RimeInputError("Prism filler text must be nonblank and at most 500 characters");
+        // Unicode mode matches lone surrogates but preserves valid UTF-16 pairs.
+        if (/[\uD800-\uDFFF]/u.test(text))
+            throw new RimeInputError("Prism filler text must be valid UTF-8");
+    }
+    if (kind === "text")
+        return { type: "text", text: text };
+    if (kind === "auto")
+        return text === undefined
+            ? { type: "auto" }
+            : { type: "auto", instructions: text };
+    return { type: "none" };
+}
+export function toolSettings(tools) {
+    if (!Array.isArray(tools))
+        throw new RimeInputError("tools must be an array");
+    const names = new Set();
+    return tools.map((tool) => {
+        if (!tool ||
+            typeof tool !== "object" ||
+            typeof tool.name !== "string" ||
+            !/\P{White_Space}/u.test(tool.name) ||
+            [...tool.name].length > 4000 ||
+            names.has(tool.name))
+            throw new RimeInputError("Tool names must be nonblank, unique, and at most 4000 characters");
+        toolString(tool.name);
+        names.add(tool.name);
+        if (!tool.parameters ||
+            Array.isArray(tool.parameters) ||
+            typeof tool.parameters !== "object" ||
+            (tool.description !== undefined && typeof tool.description !== "string"))
+            throw new RimeInputError("Tool parameters must be a JSON object and description must be a string");
+        let parameters;
+        try {
+            parameters = copyJson(tool.parameters);
+        }
+        catch (error) {
+            if (error instanceof RimeInputError)
+                throw error;
+            throw new RimeInputError("Tool schemas must contain finite JSON values");
+        }
+        if (parameters === null ||
+            typeof parameters !== "object" ||
+            Array.isArray(parameters))
+            throw new RimeInputError("Tool parameters must be an object");
+        return {
+            type: "function",
+            ...(tool.prismFiller === undefined
+                ? {}
+                : { prism_filler: fillerSettings(tool.prismFiller) }),
+            function: {
+                name: tool.name,
+                description: toolString(tool.description ?? ""),
+                parameters,
+            },
+        };
+    });
+}
+/** Bounded policy changes used to resolve each reply's settings revision. */
+export class InterruptionPolicies {
+    changes = [];
+    current = true;
+    lastRevision = null;
+    record(revision, interrupt) {
+        const previous = this.changes.at(-1);
+        if (!previous) {
+            this.changes.push({ revision: revision ?? 0, interrupt });
+        }
+        else if (revision === null) {
+            if (interrupt !== this.current && !previous.unknown) {
+                // Earlier published revisions stay known; later ones are ambiguous
+                // until an acknowledgment supplies the new policy's revision.
+                this.changes.push({
+                    revision: this.lastRevision === null ? 0 : this.lastRevision + 1,
+                    interrupt,
+                    unknown: true,
+                });
+            }
+        }
+        else if (previous.unknown || interrupt !== this.current) {
+            this.changes.push({ revision, interrupt });
+        }
+        if (revision !== null)
+            this.lastRevision = revision;
+        if (this.changes.length > 128)
+            this.changes.shift();
+        this.current = interrupt;
+    }
+    resolve(revision) {
+        if (revision == null || this.changes.length === 0)
+            return this.current;
+        for (let i = this.changes.length - 1; i >= 0; i--) {
+            if (this.changes[i].revision <= revision) {
+                if (this.changes[i].unknown)
+                    throw new RimeResourceLimitError("Reply settings revision crosses an unreported interruption policy change");
+                return this.changes[i].interrupt;
+            }
+        }
+        throw new RimeResourceLimitError("Reply settings revision is no longer retained");
+    }
+}

package/dist/realtime/transport.d.ts

@@ -9,7 +9,7 @@ export declare class RealtimeConnection {
     readonly ready: Promise<void>;
     onMessage: (raw: string) => void;
     onFailure: (error: RimeError) => void;
-    constructor(endpoint: string, authorization: string);
+    constructor(endpoint: string, authorization: string, requestId?: string);
     private failure;
     send(encoded: string): Promise<void>;
     close(): Promise<void>;

package/dist/realtime/transport.js

@@ -11,9 +11,12 @@ export class RealtimeConnection {
     ready = this.opened.promise;
     onMessage = () => { };
     onFailure = () => { };
-    constructor(endpoint, authorization) {
+    constructor(endpoint, authorization, requestId) {
         this.socket = new WebSocket(endpoint, {
-            headers: { Authorization: authorization },
+            headers: {
+                Authorization: authorization,
+                ...(requestId === undefined ? {} : { "x-request-id": requestId }),
+            },
             followRedirects: false,
             perMessageDeflate: false,
             maxPayload: 1024 * 1024,

package/dist/realtime/types.d.ts

@@ -2,6 +2,10 @@ import type { PCMFormat } from "../pcm.js";
 export type { PCMFormat } from "../pcm.js";
 import { RimeError, RimeTimeoutError } from "../errors.js";
 export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
+/** Your labels for replies, keys to strings, such as `{ step: "3" }`. Prism
+ * takes at most 16, keys up to 64 characters and values up to 512, and
+ * refuses keys starting with `prism_`. */
+export type Labels = Readonly<Record<string, string>>;
 export interface JsonObject {
     [key: string]: JsonValue;
 }
@@ -59,6 +63,22 @@ export interface RealtimeConnectOptions extends RealtimeOperationOptions {
     readonly interruptOnSpeech?: boolean;
     readonly turnDetection?: TurnDetection;
     readonly timeouts?: RealtimeTimeouts;
+    /** Sent as the upgrade's `x-request-id`. It must be nonblank printable ASCII, or
+     * `connect` throws `RimeInputError`. Prism uses it if it is at most 128
+     * characters, else makes its own; `info.requestId` reports the one it used.
+     * Omitted or `null` sends none. */
+    readonly requestId?: string | null;
+    /** Labels every reply's `response.started` carries in `metadata`, such as
+     * `{ step: "3" }`; change them with `session.setResponseMetadata`. Prism
+     * refuses keys starting with `prism_`. Omitted or `null` sets none. */
+    readonly responseMetadata?: Labels | null;
+}
+/** Omitted fields keep their values. Empty instructions or tools clear them. */
+export interface RealtimeUpdateOptions extends RealtimeOperationOptions {
+    readonly instructions?: string;
+    readonly tools?: readonly ToolDefinition[];
+    readonly voice?: string;
+    readonly interruptOnSpeech?: boolean;
 }
 export interface ReplyOptions extends RealtimeOperationOptions {
     readonly instruction?: string | null;
@@ -86,7 +106,16 @@ export interface OutputRef {
     readonly contentIndex: number;
 }
 export interface SessionInfo {
+    /** Settings revision published by the server; null when unavailable.
+     * Optional on caller-created values for compatibility. */
+    readonly settingsRevision?: number | null;
     readonly sessionId: string;
+    /** The `x-request-id` Prism's logs name this session by. Null when the
+     * server does not publish it. */
+    readonly requestId: string | null;
+    /** The labels replies carry, as Prism last confirmed them. Null when the
+     * server does not publish them. */
+    readonly responseMetadata: Labels | null;
     readonly model: "prism";
     readonly voice: string;
     readonly interruptOnSpeech: boolean;
@@ -96,6 +125,9 @@ export interface SessionInfo {
 }
 export interface RealtimeFault {
     readonly code: string;
+    /** Optional for compatibility with caller-created faults. The SDK derives
+     * its output classification from the code and ignores supplied values. */
+    readonly retryable?: boolean;
     readonly message: string;
     readonly scope: "event" | "utterance" | "response" | "tool_roundtrip" | "session" | "unknown";
     readonly requestId: string | null;
@@ -105,10 +137,18 @@ export interface RealtimeFault {
     readonly correlationId: string | null;
     readonly parameter: string | null;
 }
+/** An immutable fault produced by the SDK. */
+export interface NormalizedRealtimeFault extends RealtimeFault {
+    /** Whether the same request, unchanged, may succeed on another attempt.
+     * True only for capacity_exceeded, unavailable, and response_timeout.
+     * Unknown codes return false. The application owns retry timing, limits,
+     * and recovery after partial output; this value does not replay a request. */
+    readonly retryable: boolean;
+}
 export declare class RealtimeAdmissionTimeout extends RimeTimeoutError {
 }
 export declare class RimeRealtimeError extends RimeError {
-    readonly fault: RealtimeFault;
+    readonly fault: NormalizedRealtimeFault;
     constructor(fault: RealtimeFault);
 }
 export interface InputReady {
@@ -159,17 +199,26 @@ export interface TranscriptFinal {
     readonly itemId: string;
     readonly text: string;
 }
-export interface TranscriptFailed {
+export interface TranscriptFailed<Fault extends RealtimeFault = RealtimeFault> {
     readonly kind: "transcript.failed";
     readonly itemId: string;
-    readonly error: RealtimeFault;
+    readonly error: Fault;
 }
 export interface ResponseStarted {
+    /** Settings revision published by the server; null when unavailable.
+     * Optional on caller-created values for compatibility. */
+    readonly settingsRevision?: number | null;
     readonly kind: "response.started";
     readonly response: ResponseRef;
     readonly cause: "speech" | "text" | "proactive" | "tools" | "unknown";
     readonly parent: ResponseRef | null;
     readonly inputItemId: string | null;
+    /** The session's labels when the reply began. Prism's `prism_` keys are
+     * left out. */
+    readonly metadata: Labels;
+    /** The user items the reply answers: a spoken reply's committed turns, or
+     * a typed turn's item. Empty when the server names none. */
+    readonly inputItemIds: readonly string[];
 }
 export interface MessageStarted {
     readonly kind: "message.started";
@@ -209,22 +258,25 @@ export interface ResponseAbandoned {
     readonly response: ResponseRef;
 }
 export interface ResponseEnded {
+    /** Settings revision published by the server; null when unavailable.
+     * Optional on caller-created values for compatibility. */
+    readonly settingsRevision?: number | null;
     readonly kind: "response.ended";
     readonly response: ResponseRef;
     readonly status: "completed" | "cancelled" | "failed" | "unknown";
     readonly reason: string | null;
 }
-export interface FaultEvent {
+export interface FaultEvent<Fault extends RealtimeFault = RealtimeFault> {
     readonly kind: "error";
-    readonly error: RealtimeFault;
+    readonly error: Fault;
 }
-export type InputEvent = InputReady | SpeechHint | SpeechStarted | SpeechStopped | InputCommitted | TranscriptDelta | TranscriptFinal | TranscriptFailed;
+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;
-export interface SessionEvent {
+export interface SessionEvent<Fault extends RealtimeFault = RealtimeFault> {
     readonly sessionId: string;
     readonly eventId: string;
     readonly requestId: string | null;
-    readonly payload: InputEvent | ResponseEvent | FaultEvent;
+    readonly payload: InputEvent<Fault> | ResponseEvent | FaultEvent<Fault>;
 }
 export interface PlaybackInterrupted {
     readonly kind: "interrupted";

package/dist/realtime/types.js

@@ -1,10 +1,12 @@
 import { RimeError, RimeTimeoutError } from "../errors.js";
+import { normalizeFault } from "./faults.js";
 export class RealtimeAdmissionTimeout extends RimeTimeoutError {
 }
 export class RimeRealtimeError extends RimeError {
     fault;
     constructor(fault) {
-        super(`${fault.code}: ${fault.message}`, fault.requestId);
-        this.fault = fault;
+        const normalized = normalizeFault(fault);
+        super(`${normalized.code}: ${normalized.message}`, normalized.requestId);
+        this.fault = normalized;
     }
 }

package/docs/realtime.md

@@ -110,10 +110,13 @@ The runner is the only event reader. Do not consume `session.events` at the same
 time, call `reportPlayback` independently, or send a second audio source. Other
 session methods remain available for manual tools and application actions.
 
-On confirmed `speech.started`, the runner uses the effective
-`session.info.interruptOnSpeech` setting. It stops affected output, waits for the
-interrupted receipt, and reports the measured position. It ignores late audio
-for that response. A `speech.hint` alone does not stop playback. A server
+On confirmed `speech.started`, the runner uses the interruption setting of the
+latest reply that is still generating or has unmeasured physical playback. It
+resolves that setting from the reply's revision when the session receives the
+reply. Updates and late event consumption cannot change it. If interruption is
+enabled, the runner stops affected output, waits for the interrupted receipt,
+and reports the measured position. It ignores late audio for that response.
+A `speech.hint` alone does not stop playback. A server
 `truncate_not_current` refusal is forwarded as an event; it does not stop a newer
 response. Finished reports wait for generation completion and every output
 receipt, including outstanding playback from earlier responses. Prism treats
@@ -152,8 +155,9 @@ tool execution outside the runner.
 ## Connect
 
 Use `await client.realtime.connect()` with `RIME_API_KEY` set. It opens a WebSocket,
-initializes one conversation, and returns a `RealtimeSession`. Settings apply
-once. Open a new session to change them.
+initializes one conversation, and returns a `RealtimeSession`. Use
+`session.update` to change instructions, tools, voice, or interruption.
+Use `session.setResponseMetadata` to replace reply labels.
 
 | Option | Required? | Default and behavior |
 | --- | --- | --- |
@@ -165,15 +169,20 @@ once. Open a new session to change them.
 | `turnDetection` | No | Omitted settings use the server's turn timing defaults. |
 | `timeouts` | No | `{ connectS: 10, readyS: 30, requestS: 10 }`. Each field is optional. Units are seconds. |
 | `model` | No | `"prism"`, the only accepted value. |
+| `requestId` | No | Your id for the session. Sent as `x-request-id`. It must be nonblank printable ASCII, or the SDK throws `RimeInputError`. Prism uses it if it is at most 128 characters, else makes its own. |
+| `responseMetadata` | No | Labels every reply carries in `response.started.metadata`, such as `{ step: "3" }`: up to 16 strings, keys up to 64 characters and values up to 512, no key starting with `prism_`. Prism refuses labels that break these limits, or keys starting with `prism_`, with `RimeRealtimeError` code `invalid_session`. |
 | `signal` | No | An `AbortSignal` that cancels connection setup. It does not cancel an established session. |
 
 Credentials come from `new Rime({ apiKey: "..." })` or `RIME_API_KEY`. Prism uses
 `Authorization: Bearer <key>`, without a TTS token exchange. TTS endpoint, model,
 voice, and timeout settings do not apply to Realtime.
 
-After connection, `session.info` contains `sessionId`, `model`, `voice`,
-`interruptOnSpeech`, `turnDetection`, `toolResultTimeoutS`, and
-`toolContinuationTimeoutS`.
+After connection, `session.info` contains `sessionId`, `requestId`, `model`,
+`voice`, `interruptOnSpeech`, `turnDetection`, `responseMetadata`,
+`toolResultTimeoutS`, and `toolContinuationTimeoutS`. `requestId` is the id
+Prism's logs use; include it when you report a problem. It is `null` on servers
+that do not send it. An event's or error's `requestId` names the SDK request
+that caused it instead.
 Check the effective interruption setting there. Tool wait durations are total
 server deadlines, not remaining time. A `null` duration can mean an omitted
 field; it does not prove that no deadline exists.
@@ -215,12 +224,54 @@ server reported in its initialization acknowledgment. A missing field is
 default. An unrecognized server eagerness becomes `"unknown"`.
 `interruptOnSpeech` remains a separate connection option.
 
+## Update session settings
+
+This method is available in the repository source and requires an SDK release
+that includes session updates.
+
+```ts
+const info = await session.update({
+  instructions: "Handle billing. Use only the supplied tools.",
+  tools: [refundTool], // An existing ToolDefinition.
+});
+console.log(info.settingsRevision);
+
+// For a transfer triggered by a tool call:
+await session.submitToolResult(call, "Transferred to billing.");
+await session.continueReply(parent);
+```
+
+`RealtimeUpdateOptions` has optional `instructions`, `tools`, `voice`,
+`interruptOnSpeech`, and `signal` fields. Omitted fields and `undefined` keep
+their values. `null` is not accepted.
+
+Omitted fields keep their values. A supplied tool list replaces the complete
+list. Empty instructions clear the prompt; an empty tool list removes all tools.
+An empty voice selects the deployment default. Instructions and tools supplied
+together change in one request.
+
+The method waits for the matching `session.updated` acknowledgment and returns
+session information. The stored session information changes only after that
+acknowledgment. A rejected update leaves it unchanged and keeps the connection
+open. Cancellation after submission does not undo an accepted update.
+
+Updates do not wait for turn readiness or tool results. Each reply keeps the
+settings it began with. A reply prepared on an early turn-end guess can be
+announced after an update but still use the previous settings revision.
+Modalities, eagerness, and the end-of-turn timeout cannot change mid-session.
+
+`SessionInfo`, `ResponseStarted`, and `ResponseEnded` expose `settingsRevision`.
+It is `null` when the server does not publish it. The field is optional on
+caller-created values. Users do not need to manage it. Use each reply's revision
+to identify its settings, rather than the latest session revision.
+
 ## Choose an operation
 
 Every method returns a promise. Arguments without `?` are required.
 
 | Method | Result and behavior |
 | --- | --- |
+| `update(options?)` | Changes supplied settings without reconnecting; returns `SessionInfo` after acknowledgment. |
 | `sendText(text, options?)` | Starts a typed user turn after readiness; returns `ResponseRef` at response creation. |
 | `sendAudio(chunk, options?)` | Sends microphone audio with transport backpressure. |
 | `requestReply(options?)` | Requests a reply without new user input; returns `ResponseRef`. Options can include `instruction` and `toolCall`. |
@@ -229,12 +280,13 @@ Every method returns a promise. Arguments without `?` are required.
 | `continueReply(parent, options?)` | Waits for parent completion and all tool result acknowledgments, then returns a new `ResponseRef`. |
 | `cancel(response, options?)` | Requests generation cancellation and waits for a terminal response or refusal. |
 | `clearAudio(options?)` | Clears buffered input and resets audio conversion after acknowledgment. |
+| `setResponseMetadata(metadata, options?)` | Replaces the labels for later replies once Prism confirms. |
 | `reportPlayback(report, options?)` | Reports interrupted or finished playback. |
 | `close()` | Closes the session and releases its resources. |
 
 Operation options accept `signal?: AbortSignal`. `requestReply` accepts its
-instruction, tool call, and signal in one object. Methods other than `sendText`,
-`requestReply`, `addMessage`, and `continueReply` return `Promise<void>`.
+instruction, tool call, and signal in one object. Methods other than `update`,
+`sendText`, `requestReply`, `addMessage`, and `continueReply` return `Promise<void>`.
 
 Text must be nonblank and contain at most 4,000 Unicode characters. History
 roles are `"user"` and `"assistant"`. A reply instruction applies to one response;
@@ -304,7 +356,7 @@ also checks TypeScript callers.
 
 Filler applies when the reply has said nothing before calling a tool. If a reply
 calls several tools, the first call's tool controls the filler. `none` suppresses
-filler only; it does not silence other speech. Settings are fixed for the session.
+filler only; it does not silence other speech. Use `session.update({ tools })` to replace tools and their filler settings.
 
 Execute a tool once for each `tool.call` event. Validate its parsed `arguments`,
 then submit a string result with `submitToolResult(payload.call, output)`.
@@ -337,7 +389,7 @@ 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` |
+| `response.started` | `response`, `cause`, nullable `parent` and `inputItemId`, `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` |
@@ -406,6 +458,53 @@ with `RimeRealtimeError`. Its `.fault` has `code`, `message`, `scope`, nullable
 array. A response fault does not itself end generation. Session faults and lost
 connections end the session.
 
+`NormalizedRealtimeFault.retryable` reports whether the same request, unchanged,
+may succeed on another attempt. Read `event.payload.error.retryable` on an `error`
+event or `error.fault.retryable` on `RimeRealtimeError`. The SDK derives this
+value from the code; Prism does not send a retry flag.
+
+`RealtimeFault` accepts the previous fault shape, with an optional `retryable`
+field, for caller-created faults. `RimeRealtimeError` accepts this shape and
+ignores any supplied retry flag. Its `.fault` and SDK-emitted event faults are
+`NormalizedRealtimeFault` values with a required boolean `retryable` field.
+The SDK freezes these faults and their `callIds` arrays. Later changes to a
+constructor input do not change the error's fault.
+
+`TranscriptFailed`, `FaultEvent`, `InputEvent`, and `SessionEvent` default to
+`RealtimeFault`, so existing event literals can omit `retryable`. These types
+also accept a fault type parameter. `session.events` and the `runConversation`
+event callback use `SessionEvent<NormalizedRealtimeFault>`, which gives their
+faults a required boolean `retryable` field. An explicit `SessionEvent`
+annotation uses the default type and makes `retryable` optional.
+
+| Error code | `retryable` |
+| --- | --- |
+| `capacity_exceeded` | `true` |
+| `unavailable` | `true` |
+| `response_timeout` | `true` |
+| `context_length_exceeded` | `false` |
+| All other codes, including unknown codes | `false` |
+
+The application chooses the delay, attempt limit, and recovery operation. This
+value does not start a retry. It does not describe a local `RimeTimeoutError` or
+prove that no output or side effect occurred. The SDK's existing readiness
+retries have separate rules: an explicit refusal such as `typed_turn_busy`
+permits another attempt after a new readiness event, although its `retryable`
+value is `false` under this contract.
+
+For example, Prism can accept a user's question and then report
+`capacity_exceeded`. `sendText()` has already returned a `ResponseRef`; the
+failure arrives through an `error` event. Wait for `response.ended`, then apply
+the application's retry policy. If the question is already in history, use
+`requestReply()` to ask for another reply when appropriate. Repeating
+`sendText()` can add the question twice. A `response_timeout` can follow partial
+text or audio, which the application must handle before another attempt.
+
+For `context_length_exceeded`, the server message contains token counts.
+Unchanged attempts will fail until the conversation is shorter. Start a new
+session with shorter context. The protocol also supports history deletion, but
+this SDK does not yet expose `conversation.item.delete`.
+
 Malformed fields in known events and mismatched request acknowledgments close
 the session with `RimeStreamError`. Unknown event kinds and extra fields remain
 accepted and ignored. The SDK does not replay a request after a protocol failure.
@@ -420,7 +519,19 @@ unknown outcome.
 
 Keep up with the event stream. The queue holds 256 events; incoming messages
 are limited to 1 MiB. A slow consumer ends the session. There is no automatic
-reconnect, history replay, or live configuration update.
+reconnect or history replay.
 
 Local peer tests cover the SDK protocol handling. Validate the gateway handshake
 and endpoint behavior for the deployment you use.
+
+The SDK retains the latest 128 interruption policy changes. Instructions or tools
+updates that keep the same interruption policy do not consume this history.
+If an unannounced reply refers to an older evicted policy, the session fails
+with a resource limit error instead of guessing its policy. A reply already
+received keeps its captured policy even after later settings updates.
+
+If an interruption setting changes without a published revision, later reply
+revisions can be ambiguous. The SDK preserves earlier known settings and raises
+a resource limit error for an ambiguous reply instead of guessing. A later
+acknowledgment with a revision establishes a new known setting. Replies without
+a revision use the current acknowledged setting.

package/package.json

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