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

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,25 @@ 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>;
+    /** 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>;
     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,8 @@ 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",
     "instructions_busy",
@@ -17,6 +19,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 +77,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 +114,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 +265,23 @@ 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,
+            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,
+        });
         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 +372,35 @@ 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 = {};
+        if (options.truncation !== undefined)
+            settings.truncation = p.truncationSettings(options.truncation);
+        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));
@@ -377,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) => {
-            const event = await this.request(p.requests.item, { item: { type: "message", role, text: value } }, 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 = 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);
@@ -459,6 +537,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);
@@ -569,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") {
@@ -576,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)
@@ -588,10 +683,53 @@ export class RealtimeSession {
                     this.created.resolve(payload.session);
                 }
                 return;
-            case "session.updated":
-            case "tool.result.created":
+            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,
+                    truncation: view.truncation,
+                    requestId: view.requestId,
+                    responseMetadata: view.responseMetadata,
+                });
+                this.interruptionPolicies.record(view.settingsRevision, this.sessionInfo.interruptOnSpeech);
+                this.settle(echo, { ...payload, info: this.sessionInfo });
+                return;
+            }
+            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)
@@ -630,6 +768,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,