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

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [0.1.0-alpha.23](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.22...typescript-v0.1.0-alpha.23) (2026-10-27)
+
+
+### Bug Fixes
+
+* preserve Prism handshake error categories and diagnostics ([#110](https://github.com/rimelabs/rime-sdk/issues/110)) ([75568b2](https://github.com/rimelabs/rime-sdk/commit/75568b278afddd265a0a4f2c26c716ccb6b29514))
+
+## [0.1.0-alpha.22](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.21...typescript-v0.1.0-alpha.22) (2026-10-24)
+
+
+### ⚠ BREAKING CHANGES
+
+* Rust SessionInfo struct literals must add truncation: None. The optional field reports the policy published by the server.
+* Go Prism service faults now match ErrRealtime instead of ErrStream. Rust service faults now use ErrorKind::Realtime instead of Stream. Keep fault inspection for code, scope, and retry classification.
+
+### Features
+
+* add Prism conversation history operations ([#108](https://github.com/rimelabs/rime-sdk/issues/108)) ([1f33051](https://github.com/rimelabs/rime-sdk/commit/1f330517163cd521bd03321a0728295f84da0316))
+* add Prism history truncation controls ([#109](https://github.com/rimelabs/rime-sdk/issues/109)) ([b8b1aa1](https://github.com/rimelabs/rime-sdk/commit/b8b1aa172e69df650bfeda274bb91329f7e5bc52))
+
+
+### Bug Fixes
+
+* distinguish Prism faults and correct SDK release guidance ([#102](https://github.com/rimelabs/rime-sdk/issues/102)) ([b152abb](https://github.com/rimelabs/rime-sdk/commit/b152abb1ac4e5dabb92e747c04a6bc70aa72b60e))
+
 ## [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)
 
 

package/README.md

@@ -28,6 +28,12 @@ STT use the SDK and Node.js built-ins.
 
 ## Prism: send recorded speech
 
+If Prism refuses the connection with HTTP 429, `realtime.connect()` throws
+`RimeResourceLimitError`. HTTP 503 throws `RimeUnavailableError`. Handshake
+errors include the HTTP status, the server request ID when supplied, and a
+short server explanation when available. Missing or invalid error bodies use
+a default message. The SDK does not retry the connection automatically.
+
 With `RIME_API_KEY` set, the SDK connects to
 `wss://prism.api.rime.ai/v1/realtime` and uses the server's default voice.
 Pass `endpoint` or `voice` to select another deployment or voice.

package/dist/realtime/client.js

@@ -4,7 +4,7 @@ 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";
+import { responseMetadata, truncationSettings } from "./protocol.js";
 const DEFAULT_ENDPOINT = "wss://prism.api.rime.ai/v1/realtime";
 function endpoint(value) {
     let url;
@@ -60,6 +60,8 @@ export class Realtime {
             turn_detection: { interrupt_response: options.interruptOnSpeech ?? true },
             tools: toolSettings(options.tools ?? []),
         };
+        if (options.truncation !== undefined)
+            settings.truncation = truncationSettings(options.truncation);
         if (options.turnDetection !== undefined) {
             const detection = options.turnDetection;
             if (!detection ||

package/dist/realtime/history.d.ts

@@ -0,0 +1,4 @@
+import type { HistoryItem } from "./types.js";
+export declare function itemSettings(item: HistoryItem): Record<string, string>;
+export declare function historyId(value: string): string;
+export declare function listedItem(value: unknown): HistoryItem;

package/dist/realtime/history.js

@@ -0,0 +1,87 @@
+import { RimeInputError, RimeStreamError } from "../errors.js";
+function utf8(value) {
+    return typeof value === "string" && !/[\uD800-\uDFFF]/u.test(value);
+}
+export function itemSettings(item) {
+    if (!item || typeof item !== "object")
+        throw new RimeInputError("history item must be an object");
+    const value = { type: item.type };
+    if (item.id !== undefined) {
+        if (!utf8(item.id) || [...item.id].length < 1 || [...item.id].length > 32)
+            throw new RimeInputError("item.id must contain 1 to 32 characters");
+        value.id = item.id;
+    }
+    switch (item.type) {
+        case "message":
+            if (!["user", "assistant", "system"].includes(item.role) ||
+                !utf8(item.text) ||
+                [...item.text].length > 4000)
+                throw new RimeInputError("invalid history message");
+            value.role = item.role;
+            value.text = item.text;
+            break;
+        case "function_call":
+            value.call_id = item.callId;
+            value.name = item.name;
+            value.arguments = item.arguments;
+            if (!item.callId || !item.name)
+                throw new RimeInputError("past calls require callId and name");
+            break;
+        case "function_call_output":
+            value.call_id = item.callId;
+            value.output = item.output;
+            if (!item.callId)
+                throw new RimeInputError("tool results require callId");
+            break;
+        default:
+            throw new RimeInputError("invalid history item type");
+    }
+    if (!Object.values(value).every(utf8))
+        throw new RimeInputError("history fields must be valid UTF-8 strings");
+    return value;
+}
+export function historyId(value) {
+    if (!utf8(value) || !value)
+        throw new RimeInputError("history ID must be nonempty valid UTF-8");
+    return value;
+}
+export function listedItem(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new RimeStreamError("invalid history item");
+    const o = value;
+    const field = (name) => {
+        if (typeof o[name] !== "string")
+            throw new RimeStreamError("invalid history field " + name);
+        if ((name === "call_id" || name === "name") && !o[name])
+            throw new RimeStreamError("invalid history identity");
+        return o[name];
+    };
+    const id = field("id");
+    if (!id)
+        throw new RimeStreamError("invalid history item id");
+    switch (o.type) {
+        case "message": {
+            const role = field("role");
+            if (role !== "user" && role !== "assistant" && role !== "system")
+                throw new RimeStreamError("invalid history role");
+            return Object.freeze({ type: o.type, id, role, text: field("text") });
+        }
+        case "function_call":
+            return Object.freeze({
+                type: o.type,
+                id,
+                callId: field("call_id"),
+                name: field("name"),
+                arguments: field("arguments"),
+            });
+        case "function_call_output":
+            return Object.freeze({
+                type: o.type,
+                id,
+                callId: field("call_id"),
+                output: field("output"),
+            });
+        default:
+            throw new RimeStreamError("invalid history item type");
+    }
+}

package/dist/realtime/protocol.d.ts

@@ -1,5 +1,9 @@
 import * as t from "./types.js";
 export interface SessionSettings {
+    truncation?: "auto" | "disabled" | {
+        type: "retention_ratio";
+        retention_ratio: number;
+    };
     modalities: ("text" | "audio")[];
     input_audio_format: "pcm16";
     turn_detection: {
@@ -23,6 +27,7 @@ export interface SessionSettings {
 /** A copy of the client's labels for every reply: keys to strings. */
 export declare function responseMetadata(value: unknown): t.Labels;
 export interface SessionPatch {
+    truncation?: SessionSettings["truncation"];
     voice?: string;
     instructions?: string;
     tools?: SessionSettings["tools"];
@@ -31,6 +36,7 @@ export interface SessionPatch {
     };
 }
 export interface SessionView {
+    truncation: t.Truncation | null;
     settingsRevision: number | null;
     id: string;
     requestId: string | null;
@@ -55,9 +61,18 @@ export interface ItemCreated {
     itemId: string;
 }
 export interface ToolResultCreated {
+    itemId: string | null;
     kind: "tool.result.created";
     callId: string;
 }
+export interface HistoryListed {
+    kind: "history.listed";
+    items: readonly t.HistoryItem[];
+}
+export interface ItemDeleted {
+    kind: "item.deleted";
+    itemId: string;
+}
 export interface AudioCleared {
     kind: "audio.cleared";
 }
@@ -69,14 +84,14 @@ export interface ItemTruncated {
 export interface ResponseEnded extends t.ResponseEnded {
     drainToken: string | null;
 }
-export type Acknowledgment = SessionUpdated | ItemCreated | ToolResultCreated | AudioCleared | ItemTruncated | t.ResponseStarted | ResponseEnded;
+export type Acknowledgment = SessionUpdated | HistoryListed | ItemDeleted | ItemCreated | ToolResultCreated | AudioCleared | ItemTruncated | t.ResponseStarted | ResponseEnded;
 export type ServerPayload = SessionCreated | Acknowledgment | t.InputEvent<t.NormalizedRealtimeFault> | t.MessageStarted | t.TextDelta | t.TextDone | t.AudioDelta | t.AudioDone | t.ToolCall | t.FaultEvent<t.NormalizedRealtimeFault>;
 export interface ServerEvent {
     eventId: string;
     requestId: string | null;
     payload: ServerPayload;
 }
-export type RequestKind = "session.update" | "conversation.item.create" | "response.create" | "response.cancel" | "input_audio_buffer.clear" | "conversation.item.truncate";
+export type RequestKind = "session.update" | "conversation.item.create" | "prism.conversation.get" | "conversation.item.delete" | "response.create" | "response.cancel" | "input_audio_buffer.clear" | "conversation.item.truncate";
 /** A request carries its result type and checks it before exposing the result. */
 export declare class Request<T extends Acknowledgment> {
     readonly kind: RequestKind;
@@ -87,6 +102,10 @@ export declare class Request<T extends Acknowledgment> {
     check(event: Acknowledgment): void;
 }
 export declare const requests: {
+    historyItem: Request<ItemCreated>;
+    historyResult: Request<ToolResultCreated>;
+    history: Request<HistoryListed>;
+    delete: Request<ItemDeleted>;
     update: Request<SessionUpdated>;
     item: Request<ItemCreated>;
     toolResult: Request<ToolResultCreated>;
@@ -96,4 +115,5 @@ export declare const requests: {
     clear: Request<AudioCleared>;
     truncate: Request<ItemTruncated>;
 };
+export declare function truncationSettings(value: t.Truncation): NonNullable<SessionSettings["truncation"]>;
 export declare function decode(raw: string, sessionId: string | null): ServerEvent | null;

package/dist/realtime/protocol.js

@@ -2,6 +2,7 @@
 /** Decode only the protocol fields the SDK uses. Unknown events and fields stay open. */
 import { RimeInputError, RimeStreamError } from "../errors.js";
 import { normalizeFault } from "./faults.js";
+import { listedItem } from "./history.js";
 /** A copy of the client's labels for every reply: keys to strings. */
 export function responseMetadata(value) {
     if (!value ||
@@ -31,6 +32,10 @@ export class Request {
     }
 }
 export const requests = {
+    historyItem: new Request("conversation.item.create", (e) => e.kind === "item.created"),
+    historyResult: new Request("conversation.item.create", (e) => e.kind === "tool.result.created"),
+    history: new Request("prism.conversation.get", (e) => e.kind === "history.listed"),
+    delete: new Request("conversation.item.delete", (e) => e.kind === "item.deleted"),
     update: new Request("session.update", (e) => e.kind === "session.updated"),
     item: new Request("conversation.item.create", (e) => e.kind === "item.created"),
     toolResult: new Request("conversation.item.create", (e) => e.kind === "tool.result.created"),
@@ -79,6 +84,29 @@ function duration(value, field) {
         return invalid(field);
     return value;
 }
+export function truncationSettings(value) {
+    if (value === "auto" || value === "disabled")
+        return value;
+    if (value &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        Object.keys(value).every((key) => key === "retentionRatio") &&
+        typeof value.retentionRatio === "number" &&
+        value.retentionRatio > 0 &&
+        value.retentionRatio <= 1)
+        return { type: "retention_ratio", retention_ratio: value.retentionRatio };
+    throw new RimeInputError("truncation must be auto, disabled, or a retentionRatio above zero and at most one");
+}
+function truncation(value) {
+    if (value === "auto" || value === "disabled")
+        return value;
+    const o = object(value, "session.truncation");
+    if (o.type !== "retention_ratio" ||
+        typeof o.retention_ratio !== "number" ||
+        !(o.retention_ratio > 0 && o.retention_ratio <= 1))
+        return invalid("session.truncation");
+    return Object.freeze({ retentionRatio: o.retention_ratio });
+}
 function session(value) {
     const view = object(value, "session");
     const detection = view.turn_detection === undefined
@@ -116,6 +144,7 @@ function session(value) {
         invalid("session.prism_effective_interrupt_response");
     return {
         settingsRevision: revision(view),
+        truncation: view.truncation === undefined ? null : truncation(view.truncation),
         id: id(view.id, "session.id"),
         requestId: optionalString(view.request_id, "session.request_id"),
         responseMetadata: view.prism_response_metadata === undefined
@@ -221,15 +250,29 @@ function decodeValue(value, sessionId) {
             if (item.type === "function_call_output")
                 payload = {
                     kind: "tool.result.created",
+                    itemId: optionalString(item.id, "item.id"),
                     callId: id(item.call_id, "item.call_id"),
                 };
             else {
-                if (item.type !== undefined && item.type !== "message")
+                if (item.type !== undefined &&
+                    item.type !== "message" &&
+                    item.type !== "function_call")
                     invalid("item.type");
                 payload = { kind: "item.created", itemId: id(item.id, "item.id") };
             }
             break;
         }
+        case "prism.conversation":
+            if (!Array.isArray(event.items))
+                return invalid("items");
+            payload = {
+                kind: "history.listed",
+                items: Object.freeze(event.items.map(listedItem)),
+            };
+            break;
+        case "conversation.item.deleted":
+            payload = { kind: "item.deleted", itemId: id(event.item_id, "item_id") };
+            break;
         case "input_audio_buffer.cleared":
             payload = { kind: "audio.cleared" };
             break;

package/dist/realtime/session.d.ts

@@ -58,6 +58,12 @@ export declare class RealtimeSession {
     update(options?: t.RealtimeUpdateOptions): Promise<t.SessionInfo>;
     sendText(value: string, options?: t.RealtimeOperationOptions): 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[]>;
+    /** Hide an item from future replies. A call and its result are hidden together. */
+    deleteItem(itemId: string, options?: t.RealtimeOperationOptions): Promise<void>;
+    /** Add history without a reply. The server owns placement and identity checks. */
+    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>;

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 { historyId, itemSettings } from "./history.js";
 import { InterruptionPolicies, toolSettings } from "./settings.js";
 const NOT_READY = new Set([
     "typed_turn_busy",
@@ -268,6 +269,15 @@ export class RealtimeSession {
             request,
             result,
             target,
+            requiresItemId: request === p.requests.historyItem ||
+                request === p.requests.historyResult,
+            expectedItemId: body.item?.id,
+            toolOutputDigest: request.kind === "conversation.item.create" &&
+                body.item?.type === "function_call_output"
+                ? createHash("sha256")
+                    .update(body.item.output)
+                    .digest("hex")
+                : undefined,
             interruptOnSpeech: request.kind === "session.update"
                 ? body.session.turn_detection?.interrupt_response
                 : undefined,
@@ -367,6 +377,8 @@ export class RealtimeSession {
      * Cancellation after submission does not undo an accepted update. */
     async update(options = {}) {
         const settings = {};
+        if (options.truncation !== undefined)
+            settings.truncation = p.truncationSettings(options.truncation);
         for (const name of ["instructions", "voice"]) {
             const value = options[name];
             if (value !== undefined) {
@@ -409,18 +421,52 @@ export class RealtimeSession {
         }
         return this.operation(options, (signal) => this.create(body, signal));
     }
-    async addMessage(role, value, options = {}) {
-        if (role !== "user" && role !== "assistant")
-            throw new RimeInputError("History role must be user or assistant");
-        text(value);
+    /** Read the items the next reply would see, in server order. */
+    async getHistory(options = {}) {
+        return this.operation(options, async (signal) => (await this.request(p.requests.history, {}, signal)).items);
+    }
+    /** Hide an item from future replies. A call and its result are hidden together. */
+    async deleteItem(itemId, options = {}) {
+        if (typeof itemId !== "string" || !itemId)
+            throw new RimeInputError("itemId must be nonempty");
+        historyId(itemId);
+        return this.operation(options, async (signal) => {
+            await this.request(p.requests.delete, { item_id: itemId }, signal, itemId);
+        });
+    }
+    /** Add history without a reply. The server owns placement and identity checks. */
+    async createItem(item, options = {}) {
+        const value = itemSettings(item);
+        const body = { item: value };
+        if (options.previousItemId !== undefined) {
+            if (typeof options.previousItemId !== "string" ||
+                !options.previousItemId ||
+                item.type === "function_call_output")
+                throw new RimeInputError("invalid previousItemId for history item");
+            body.previous_item_id = historyId(options.previousItemId);
+        }
         return this.operation(options, async (signal) => {
-            const event = await this.request(p.requests.item, { item: { type: "message", role, text: value } }, signal);
+            const event = value.type === "function_call_output"
+                ? await this.request(p.requests.historyResult, body, signal, value.call_id)
+                : await this.request(p.requests.historyItem, body, signal);
+            if (!event.itemId ||
+                (value.id !== undefined && event.itemId !== value.id)) {
+                const error = new RimeStreamError("history acknowledgment names an invalid item");
+                this.fail(error);
+                throw error;
+            }
             return Object.freeze({
                 sessionId: this.info.sessionId,
                 itemId: event.itemId,
             });
         });
     }
+    async addMessage(role, value, options = {}) {
+        if (role !== "user" && role !== "assistant")
+            throw new RimeInputError("History role must be user or assistant");
+        text(value);
+        return this.createItem({ type: "message", role, text: value }, { signal: options.signal });
+    }
     async submitToolResult(call, output, options = {}) {
         const ref = { ...call };
         this.response(ref);
@@ -609,6 +655,8 @@ export class RealtimeSession {
         const { payload, requestId: echo } = event;
         // Check echoed acknowledgments before changing response or item state.
         if (payload.kind === "session.updated" ||
+            payload.kind === "history.listed" ||
+            payload.kind === "item.deleted" ||
             payload.kind === "item.created" ||
             payload.kind === "tool.result.created" ||
             payload.kind === "response.started") {
@@ -616,6 +664,13 @@ export class RealtimeSession {
             if (pending &&
                 !(payload.kind === "item.created" && pending.request.allowsItemCreated))
                 pending.request.check(payload);
+            if (pending?.requiresItemId &&
+                ((payload.kind !== "item.created" &&
+                    payload.kind !== "tool.result.created") ||
+                    !payload.itemId ||
+                    (pending.expectedItemId !== undefined &&
+                        pending.expectedItemId !== payload.itemId)))
+                throw new RimeStreamError("history acknowledgment names an invalid item");
             if (pending &&
                 payload.kind === "tool.result.created" &&
                 pending.target !== payload.callId)
@@ -645,6 +700,7 @@ export class RealtimeSession {
                     toolContinuationTimeoutS: view.toolContinuationTimeoutS,
                     turnDetection: view.turnDetection,
                     settingsRevision: view.settingsRevision,
+                    truncation: view.truncation,
                     requestId: view.requestId,
                     responseMetadata: view.responseMetadata,
                 });
@@ -652,9 +708,28 @@ export class RealtimeSession {
                 this.settle(echo, { ...payload, info: this.sessionInfo });
                 return;
             }
-            case "tool.result.created":
+            case "history.listed":
+                this.settle(echo, payload);
+                return;
+            case "item.deleted": {
+                const pending = this.pending.get(echo ?? "");
+                if (pending && pending.target !== payload.itemId)
+                    throw new RimeStreamError("deletion acknowledgment names another item");
                 this.settle(echo, payload);
                 return;
+            }
+            case "tool.result.created": {
+                const pending = this.pending.get(echo ?? "");
+                if (pending?.toolOutputDigest !== undefined)
+                    for (const response of this.responses.values()) {
+                        if (response.calls.get(payload.callId) === null) {
+                            response.calls.set(payload.callId, pending.toolOutputDigest);
+                            response.changed.set();
+                        }
+                    }
+                this.settle(echo, payload);
+                return;
+            }
             case "item.created": {
                 const pending = this.pending.get(echo ?? "");
                 if (pending?.request.allowsItemCreated)

package/dist/realtime/transport.d.ts

@@ -6,6 +6,8 @@ export declare class RealtimeConnection {
     private readonly ended;
     private closing;
     private connected;
+    private failed;
+    private refusal;
     readonly ready: Promise<void>;
     onMessage: (raw: string) => void;
     onFailure: (error: RimeError) => void;

package/dist/realtime/transport.js

@@ -1,6 +1,42 @@
 import WebSocket from "ws";
-import { RimeAuthenticationError, RimeStreamError, RimeUnavailableError, } from "../errors.js";
+import { RimeAuthenticationError, RimeResourceLimitError, RimeStreamError, RimeUnavailableError, } from "../errors.js";
 import { Deferred } from "./async.js";
+function handshakeError(status, body, requestId) {
+    let errorType = RimeUnavailableError;
+    let reason = "Realtime endpoint rejected the connection";
+    if ([401, 403].includes(status)) {
+        errorType = RimeAuthenticationError;
+        reason = "Realtime endpoint rejected credentials";
+    }
+    else if (status === 429) {
+        errorType = RimeResourceLimitError;
+        reason = "Realtime connection or rate limit reached";
+    }
+    else if (status === 503) {
+        reason = "Realtime endpoint is unavailable";
+    }
+    let message = `${reason} (HTTP ${status})`;
+    if (body.length > 0 && body.length < 1024) {
+        try {
+            let detail = new TextDecoder("utf-8", { fatal: true })
+                .decode(body)
+                .trim();
+            if (typeof detail === "string" && /^[{[]/.test(detail))
+                detail = JSON.parse(detail)?.error?.message;
+            if (typeof detail === "string" &&
+                !detail.trimStart().startsWith("<") &&
+                !/[\x00-\x08\x0b\x0c\x0e-\x1f]/.test(detail)) {
+                detail = detail.trim().replace(/\s+/gu, " ");
+                if (detail)
+                    message += `: ${detail}`;
+            }
+        }
+        catch {
+            // Invalid response bodies do not change the HTTP error category.
+        }
+    }
+    return new errorType(message, requestId);
+}
 /** Private transport. The public declarations do not require ws types. */
 export class RealtimeConnection {
     socket;
@@ -8,6 +44,8 @@ export class RealtimeConnection {
     ended = new Deferred();
     closing = null;
     connected = false;
+    failed = false;
+    refusal;
     ready = this.opened.promise;
     onMessage = () => { };
     onFailure = () => { };
@@ -26,17 +64,39 @@ export class RealtimeConnection {
             this.opened.resolve();
         });
         this.socket.on("unexpected-response", (request, response) => {
-            const error = [401, 403].includes(response.statusCode ?? 0)
-                ? new RimeAuthenticationError("Realtime endpoint rejected credentials")
-                : new RimeUnavailableError("Realtime endpoint rejected the connection");
-            this.failure(error);
-            response.destroy();
-            request.destroy();
-            this.socket.terminate();
+            const chunks = [];
+            let size = 0;
+            let finished = false;
+            const finish = (complete = false) => {
+                if (finished)
+                    return;
+                finished = true;
+                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));
+                response.destroy();
+                request.destroy();
+                this.socket.terminate();
+            };
+            const timer = setTimeout(finish, 1000);
+            this.refusal = finish;
+            response.on("data", (chunk) => {
+                size += chunk.length;
+                if (size >= 1024)
+                    finish();
+                else
+                    chunks.push(chunk);
+            });
+            response.on("end", () => finish(true));
+            response.on("error", () => finish());
+            response.on("aborted", () => finish());
         });
-        this.socket.on("error", () => this.failure(!this.connected
-            ? new RimeUnavailableError("Realtime handshake failed")
-            : new RimeStreamError("Invalid event or lost realtime connection")));
+        this.socket.on("error", () => this.refusal
+            ? this.refusal()
+            : this.failure(!this.connected
+                ? new RimeUnavailableError("Realtime handshake failed")
+                : new RimeStreamError("Invalid event or lost realtime connection")));
         this.socket.on("message", (data, binary) => {
             if (binary) {
                 this.failure(new RimeStreamError("Expected a JSON text event"));
@@ -45,11 +105,15 @@ export class RealtimeConnection {
             this.onMessage(data.toString());
         });
         this.socket.on("close", () => {
+            this.refusal?.();
             this.ended.resolve();
             this.failure(new RimeStreamError("Realtime connection closed; reconnect is not automatic"));
         });
     }
     failure(error) {
+        if (this.failed)
+            return;
+        this.failed = true;
         this.opened.reject(error);
         this.onFailure(error);
     }
@@ -66,6 +130,7 @@ export class RealtimeConnection {
     close() {
         if (!this.closing) {
             this.closing = (async () => {
+                this.refusal?.();
                 if (this.socket.readyState === WebSocket.CLOSED)
                     return;
                 const timer = setTimeout(() => this.socket.terminate(), 2000);

package/dist/realtime/types.d.ts

@@ -40,6 +40,10 @@ export interface ToolDefinition {
     readonly description?: string;
     readonly prismFiller?: PrismFiller;
 }
+/** History policy when the context fills. The server uses auto when omitted. */
+export type Truncation = "auto" | "disabled" | {
+    readonly retentionRatio: number;
+};
 export type TurnEagerness = "low" | "medium" | "high" | "auto";
 /** Omitted fields use the server's turn timing defaults. */
 export interface TurnDetection {
@@ -54,6 +58,7 @@ export interface TurnDetectionInfo {
     readonly endOfTurnTimeoutMs: number | null;
 }
 export interface RealtimeConnectOptions extends RealtimeOperationOptions {
+    readonly truncation?: Truncation;
     /** Defaults to wss://prism.api.rime.ai/v1/realtime. */
     readonly endpoint?: string;
     readonly model?: "prism";
@@ -64,8 +69,9 @@ export interface RealtimeConnectOptions extends RealtimeOperationOptions {
     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.
+     * `connect` throws `RimeInputError`. Prism replaces IDs longer than 128 characters.
+     * A gateway can replace shorter IDs too. `info.requestId` reports the ID Prism
+     * actually used.
      * Omitted or `null` sends none. */
     readonly requestId?: string | null;
     /** Labels every reply's `response.started` carries in `metadata`, such as
@@ -75,6 +81,7 @@ export interface RealtimeConnectOptions extends RealtimeOperationOptions {
 }
 /** Omitted fields keep their values. Empty instructions or tools clear them. */
 export interface RealtimeUpdateOptions extends RealtimeOperationOptions {
+    readonly truncation?: Truncation;
     readonly instructions?: string;
     readonly tools?: readonly ToolDefinition[];
     readonly voice?: string;
@@ -88,6 +95,28 @@ export interface AudioChunk {
     readonly data: Uint8Array;
     readonly format?: PCMFormat;
 }
+/** An item without audio. IDs are optional on input and present in history results. */
+export type HistoryItem = {
+    readonly type: "message";
+    readonly id?: string;
+    readonly role: "user" | "assistant" | "system";
+    readonly text: string;
+} | {
+    readonly type: "function_call";
+    readonly id?: string;
+    readonly callId: string;
+    readonly name: string;
+    readonly arguments: string;
+} | {
+    readonly type: "function_call_output";
+    readonly id?: string;
+    readonly callId: string;
+    readonly output: string;
+};
+export interface HistoryCreateOptions extends RealtimeOperationOptions {
+    /** Omit to append, root to insert first, or an item ID to follow its whole turn. */
+    readonly previousItemId?: string;
+}
 export interface ResponseRef {
     readonly sessionId: string;
     readonly responseId: string;
@@ -106,6 +135,8 @@ export interface OutputRef {
     readonly contentIndex: number;
 }
 export interface SessionInfo {
+    /** Null when an older server does not publish its history policy. */
+    readonly truncation?: Truncation | null;
     /** Settings revision published by the server; null when unavailable.
      * Optional on caller-created values for compatibility. */
     readonly settingsRevision?: number | null;

package/docs/realtime.md

@@ -169,7 +169,7 @@ Use `session.setResponseMetadata` to replace reply labels.
 | `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. |
+| `requestId` | No | Sent as `x-request-id`. It must be nonblank printable ASCII, or the SDK throws `RimeInputError`. Prism replaces IDs longer than 128 characters. A gateway can replace shorter IDs too. Read `session.info.requestId` for the ID Prism actually used. |
 | `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. |
 
@@ -276,6 +276,9 @@ Every method returns a promise. Arguments without `?` are required.
 | `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`. |
 | `addMessage(role, text, options?)` | Adds user or assistant history without a reply; returns `ItemRef` after acknowledgment. |
+| `getHistory(options?)` | Returns the ordered `readonly HistoryItem[]` that the next reply would see. |
+| `createItem(item, options?)` | Adds a message, past tool call, or tool result without a reply; returns `ItemRef` after acknowledgment. Options can include `previousItemId`. |
+| `deleteItem(itemId, options?)` | Hides an item from later replies and waits for acknowledgment. |
 | `submitToolResult(call, output, options?)` | Records a string result and waits for acknowledgment. |
 | `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. |
@@ -285,12 +288,17 @@ Every method returns a promise. Arguments without `?` are required.
 | `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 `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;
-it does not replace session instructions.
+instruction, tool call, and signal in one object. `update` returns
+`Promise<SessionInfo>`. `sendText`, `requestReply`, and `continueReply` return
+`Promise<ResponseRef>`. `addMessage` and `createItem` return `Promise<ItemRef>`.
+`getHistory` returns `Promise<readonly HistoryItem[]>`. The other methods return
+`Promise<void>`.
+
+`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
+length limit. A reply instruction applies to one response; it does not replace
+session instructions.
 
 A returned `ResponseRef` means generation started. Read `response.ended` for the
 terminal status. Generation can finish before cancellation takes effect, so a
@@ -502,8 +510,7 @@ 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`.
+session with shorter context. Use the history deletion method to remove items before retrying.
 
 Malformed fields in known events and mismatched request acknowledgments close
 the session with `RimeStreamError`. Unknown event kinds and extra fields remain
@@ -535,3 +542,48 @@ 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.
+
+## Conversation history operations
+
+Available in the next SDK release. The Prism server must support history operations.
+Read history to obtain the items the next reply would see, in server order.
+Create messages with user, assistant, or system roles, past function calls, and
+function results. Creating an item does not start a reply or execute a tool.
+Message text is limited to 4000 Unicode characters. Optional client item IDs have
+1 to 32 characters. Tool arguments and results preserve the supplied strings.
+
+Omit the insertion anchor to append, use `root` to insert first, or give an item
+ID to insert after its whole turn. Results go after their calls and cannot take
+an anchor. Add a past call before adding its result.
+
+Deletion hides items from subsequent replies and keeps the conversation record.
+Deleting a call or its result hides both. An active reply keeps its original
+context. A deleted active call still needs a result and continuation through the
+existing tool APIs. Deleting an already deleted item succeeds; an unknown ID fails.
+History excludes replies still running and their inputs until those replies end.
+Requests work without typed-turn readiness. A canceled submitted request can still
+take effect; the SDK tracks its acknowledgment and does not replay it.
+
+```text
+const item = await session.createItem({ type: "message", role: "system", text: "Transferred to billing." }, { previousItemId: "root" });
+const items = await session.getHistory();
+await session.deleteItem(item.itemId);
+```
+
+## History truncation
+
+Available in the next SDK release. Set `truncation` at connection setup or during
+an existing session. Omit it to preserve compatibility with older Prism servers.
+The server must support truncation before you send this setting.
+
+`auto` drops the oldest turns and retains 0.8 of the available history capacity.
+`disabled` keeps all history and reports `context_length_exceeded` when it no
+longer fits. A retention ratio above zero and at most one selects how much history
+capacity to retain. Instructions and tools remain. This setting does not delete
+items from the conversation record. Session information reports the acknowledged
+policy in `session.info.truncation`, or `null` when an older server does not
+publish it.
+
+```text
+await session.update({ truncation: { retentionRatio: 0.9 } });
+```

package/package.json

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