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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -2,6 +2,10 @@ import type { PCMFormat } from "../pcm.js";
2
2
  export type { PCMFormat } from "../pcm.js";
3
3
  import { RimeError, RimeTimeoutError } from "../errors.js";
4
4
  export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
5
+ /** Your labels for replies, keys to strings, such as `{ step: "3" }`. Prism
6
+ * takes at most 16, keys up to 64 characters and values up to 512, and
7
+ * refuses keys starting with `prism_`. */
8
+ export type Labels = Readonly<Record<string, string>>;
5
9
  export interface JsonObject {
6
10
  [key: string]: JsonValue;
7
11
  }
@@ -36,6 +40,10 @@ export interface ToolDefinition {
36
40
  readonly description?: string;
37
41
  readonly prismFiller?: PrismFiller;
38
42
  }
43
+ /** History policy when the context fills. The server uses auto when omitted. */
44
+ export type Truncation = "auto" | "disabled" | {
45
+ readonly retentionRatio: number;
46
+ };
39
47
  export type TurnEagerness = "low" | "medium" | "high" | "auto";
40
48
  /** Omitted fields use the server's turn timing defaults. */
41
49
  export interface TurnDetection {
@@ -50,6 +58,7 @@ export interface TurnDetectionInfo {
50
58
  readonly endOfTurnTimeoutMs: number | null;
51
59
  }
52
60
  export interface RealtimeConnectOptions extends RealtimeOperationOptions {
61
+ readonly truncation?: Truncation;
53
62
  /** Defaults to wss://prism.api.rime.ai/v1/realtime. */
54
63
  readonly endpoint?: string;
55
64
  readonly model?: "prism";
@@ -59,6 +68,24 @@ export interface RealtimeConnectOptions extends RealtimeOperationOptions {
59
68
  readonly interruptOnSpeech?: boolean;
60
69
  readonly turnDetection?: TurnDetection;
61
70
  readonly timeouts?: RealtimeTimeouts;
71
+ /** Sent as the upgrade's `x-request-id`. It must be nonblank printable ASCII, or
72
+ * `connect` throws `RimeInputError`. Prism replaces IDs longer than 128 characters.
73
+ * A gateway can replace shorter IDs too. `info.requestId` reports the ID Prism
74
+ * actually used.
75
+ * Omitted or `null` sends none. */
76
+ readonly requestId?: string | null;
77
+ /** Labels every reply's `response.started` carries in `metadata`, such as
78
+ * `{ step: "3" }`; change them with `session.setResponseMetadata`. Prism
79
+ * refuses keys starting with `prism_`. Omitted or `null` sets none. */
80
+ readonly responseMetadata?: Labels | null;
81
+ }
82
+ /** Omitted fields keep their values. Empty instructions or tools clear them. */
83
+ export interface RealtimeUpdateOptions extends RealtimeOperationOptions {
84
+ readonly truncation?: Truncation;
85
+ readonly instructions?: string;
86
+ readonly tools?: readonly ToolDefinition[];
87
+ readonly voice?: string;
88
+ readonly interruptOnSpeech?: boolean;
62
89
  }
63
90
  export interface ReplyOptions extends RealtimeOperationOptions {
64
91
  readonly instruction?: string | null;
@@ -68,6 +95,28 @@ export interface AudioChunk {
68
95
  readonly data: Uint8Array;
69
96
  readonly format?: PCMFormat;
70
97
  }
98
+ /** An item without audio. IDs are optional on input and present in history results. */
99
+ export type HistoryItem = {
100
+ readonly type: "message";
101
+ readonly id?: string;
102
+ readonly role: "user" | "assistant" | "system";
103
+ readonly text: string;
104
+ } | {
105
+ readonly type: "function_call";
106
+ readonly id?: string;
107
+ readonly callId: string;
108
+ readonly name: string;
109
+ readonly arguments: string;
110
+ } | {
111
+ readonly type: "function_call_output";
112
+ readonly id?: string;
113
+ readonly callId: string;
114
+ readonly output: string;
115
+ };
116
+ export interface HistoryCreateOptions extends RealtimeOperationOptions {
117
+ /** Omit to append, root to insert first, or an item ID to follow its whole turn. */
118
+ readonly previousItemId?: string;
119
+ }
71
120
  export interface ResponseRef {
72
121
  readonly sessionId: string;
73
122
  readonly responseId: string;
@@ -86,7 +135,18 @@ export interface OutputRef {
86
135
  readonly contentIndex: number;
87
136
  }
88
137
  export interface SessionInfo {
138
+ /** Null when an older server does not publish its history policy. */
139
+ readonly truncation?: Truncation | null;
140
+ /** Settings revision published by the server; null when unavailable.
141
+ * Optional on caller-created values for compatibility. */
142
+ readonly settingsRevision?: number | null;
89
143
  readonly sessionId: string;
144
+ /** The `x-request-id` Prism's logs name this session by. Null when the
145
+ * server does not publish it. */
146
+ readonly requestId: string | null;
147
+ /** The labels replies carry, as Prism last confirmed them. Null when the
148
+ * server does not publish them. */
149
+ readonly responseMetadata: Labels | null;
90
150
  readonly model: "prism";
91
151
  readonly voice: string;
92
152
  readonly interruptOnSpeech: boolean;
@@ -96,6 +156,9 @@ export interface SessionInfo {
96
156
  }
97
157
  export interface RealtimeFault {
98
158
  readonly code: string;
159
+ /** Optional for compatibility with caller-created faults. The SDK derives
160
+ * its output classification from the code and ignores supplied values. */
161
+ readonly retryable?: boolean;
99
162
  readonly message: string;
100
163
  readonly scope: "event" | "utterance" | "response" | "tool_roundtrip" | "session" | "unknown";
101
164
  readonly requestId: string | null;
@@ -105,10 +168,18 @@ export interface RealtimeFault {
105
168
  readonly correlationId: string | null;
106
169
  readonly parameter: string | null;
107
170
  }
171
+ /** An immutable fault produced by the SDK. */
172
+ export interface NormalizedRealtimeFault extends RealtimeFault {
173
+ /** Whether the same request, unchanged, may succeed on another attempt.
174
+ * True only for capacity_exceeded, unavailable, and response_timeout.
175
+ * Unknown codes return false. The application owns retry timing, limits,
176
+ * and recovery after partial output; this value does not replay a request. */
177
+ readonly retryable: boolean;
178
+ }
108
179
  export declare class RealtimeAdmissionTimeout extends RimeTimeoutError {
109
180
  }
110
181
  export declare class RimeRealtimeError extends RimeError {
111
- readonly fault: RealtimeFault;
182
+ readonly fault: NormalizedRealtimeFault;
112
183
  constructor(fault: RealtimeFault);
113
184
  }
114
185
  export interface InputReady {
@@ -159,17 +230,26 @@ export interface TranscriptFinal {
159
230
  readonly itemId: string;
160
231
  readonly text: string;
161
232
  }
162
- export interface TranscriptFailed {
233
+ export interface TranscriptFailed<Fault extends RealtimeFault = RealtimeFault> {
163
234
  readonly kind: "transcript.failed";
164
235
  readonly itemId: string;
165
- readonly error: RealtimeFault;
236
+ readonly error: Fault;
166
237
  }
167
238
  export interface ResponseStarted {
239
+ /** Settings revision published by the server; null when unavailable.
240
+ * Optional on caller-created values for compatibility. */
241
+ readonly settingsRevision?: number | null;
168
242
  readonly kind: "response.started";
169
243
  readonly response: ResponseRef;
170
244
  readonly cause: "speech" | "text" | "proactive" | "tools" | "unknown";
171
245
  readonly parent: ResponseRef | null;
172
246
  readonly inputItemId: string | null;
247
+ /** The session's labels when the reply began. Prism's `prism_` keys are
248
+ * left out. */
249
+ readonly metadata: Labels;
250
+ /** The user items the reply answers: a spoken reply's committed turns, or
251
+ * a typed turn's item. Empty when the server names none. */
252
+ readonly inputItemIds: readonly string[];
173
253
  }
174
254
  export interface MessageStarted {
175
255
  readonly kind: "message.started";
@@ -209,22 +289,25 @@ export interface ResponseAbandoned {
209
289
  readonly response: ResponseRef;
210
290
  }
211
291
  export interface ResponseEnded {
292
+ /** Settings revision published by the server; null when unavailable.
293
+ * Optional on caller-created values for compatibility. */
294
+ readonly settingsRevision?: number | null;
212
295
  readonly kind: "response.ended";
213
296
  readonly response: ResponseRef;
214
297
  readonly status: "completed" | "cancelled" | "failed" | "unknown";
215
298
  readonly reason: string | null;
216
299
  }
217
- export interface FaultEvent {
300
+ export interface FaultEvent<Fault extends RealtimeFault = RealtimeFault> {
218
301
  readonly kind: "error";
219
- readonly error: RealtimeFault;
302
+ readonly error: Fault;
220
303
  }
221
- export type InputEvent = InputReady | SpeechHint | SpeechStarted | SpeechStopped | InputCommitted | TranscriptDelta | TranscriptFinal | TranscriptFailed;
304
+ export type InputEvent<Fault extends RealtimeFault = RealtimeFault> = InputReady | SpeechHint | SpeechStarted | SpeechStopped | InputCommitted | TranscriptDelta | TranscriptFinal | TranscriptFailed<Fault>;
222
305
  export type ResponseEvent = ResponseStarted | ResponseAbandoned | MessageStarted | TextDelta | TextDone | AudioDelta | AudioDone | ToolCall | ResponseEnded;
223
- export interface SessionEvent {
306
+ export interface SessionEvent<Fault extends RealtimeFault = RealtimeFault> {
224
307
  readonly sessionId: string;
225
308
  readonly eventId: string;
226
309
  readonly requestId: string | null;
227
- readonly payload: InputEvent | ResponseEvent | FaultEvent;
310
+ readonly payload: InputEvent<Fault> | ResponseEvent | FaultEvent<Fault>;
228
311
  }
229
312
  export interface PlaybackInterrupted {
230
313
  readonly kind: "interrupted";
@@ -1,10 +1,12 @@
1
1
  import { RimeError, RimeTimeoutError } from "../errors.js";
2
+ import { normalizeFault } from "./faults.js";
2
3
  export class RealtimeAdmissionTimeout extends RimeTimeoutError {
3
4
  }
4
5
  export class RimeRealtimeError extends RimeError {
5
6
  fault;
6
7
  constructor(fault) {
7
- super(`${fault.code}: ${fault.message}`, fault.requestId);
8
- this.fault = fault;
8
+ const normalized = normalizeFault(fault);
9
+ super(`${normalized.code}: ${normalized.message}`, normalized.requestId);
10
+ this.fault = normalized;
9
11
  }
10
12
  }
package/docs/realtime.md CHANGED
@@ -110,10 +110,13 @@ The runner is the only event reader. Do not consume `session.events` at the same
110
110
  time, call `reportPlayback` independently, or send a second audio source. Other
111
111
  session methods remain available for manual tools and application actions.
112
112
 
113
- On confirmed `speech.started`, the runner uses the effective
114
- `session.info.interruptOnSpeech` setting. It stops affected output, waits for the
115
- interrupted receipt, and reports the measured position. It ignores late audio
116
- for that response. A `speech.hint` alone does not stop playback. A server
113
+ On confirmed `speech.started`, the runner uses the interruption setting of the
114
+ latest reply that is still generating or has unmeasured physical playback. It
115
+ resolves that setting from the reply's revision when the session receives the
116
+ reply. Updates and late event consumption cannot change it. If interruption is
117
+ enabled, the runner stops affected output, waits for the interrupted receipt,
118
+ and reports the measured position. It ignores late audio for that response.
119
+ A `speech.hint` alone does not stop playback. A server
117
120
  `truncate_not_current` refusal is forwarded as an event; it does not stop a newer
118
121
  response. Finished reports wait for generation completion and every output
119
122
  receipt, including outstanding playback from earlier responses. Prism treats
@@ -152,8 +155,9 @@ tool execution outside the runner.
152
155
  ## Connect
153
156
 
154
157
  Use `await client.realtime.connect()` with `RIME_API_KEY` set. It opens a WebSocket,
155
- initializes one conversation, and returns a `RealtimeSession`. Settings apply
156
- once. Open a new session to change them.
158
+ initializes one conversation, and returns a `RealtimeSession`. Use
159
+ `session.update` to change instructions, tools, voice, or interruption.
160
+ Use `session.setResponseMetadata` to replace reply labels.
157
161
 
158
162
  | Option | Required? | Default and behavior |
159
163
  | --- | --- | --- |
@@ -165,15 +169,20 @@ once. Open a new session to change them.
165
169
  | `turnDetection` | No | Omitted settings use the server's turn timing defaults. |
166
170
  | `timeouts` | No | `{ connectS: 10, readyS: 30, requestS: 10 }`. Each field is optional. Units are seconds. |
167
171
  | `model` | No | `"prism"`, the only accepted value. |
172
+ | `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. |
173
+ | `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`. |
168
174
  | `signal` | No | An `AbortSignal` that cancels connection setup. It does not cancel an established session. |
169
175
 
170
176
  Credentials come from `new Rime({ apiKey: "..." })` or `RIME_API_KEY`. Prism uses
171
177
  `Authorization: Bearer <key>`, without a TTS token exchange. TTS endpoint, model,
172
178
  voice, and timeout settings do not apply to Realtime.
173
179
 
174
- After connection, `session.info` contains `sessionId`, `model`, `voice`,
175
- `interruptOnSpeech`, `turnDetection`, `toolResultTimeoutS`, and
176
- `toolContinuationTimeoutS`.
180
+ After connection, `session.info` contains `sessionId`, `requestId`, `model`,
181
+ `voice`, `interruptOnSpeech`, `turnDetection`, `responseMetadata`,
182
+ `toolResultTimeoutS`, and `toolContinuationTimeoutS`. `requestId` is the id
183
+ Prism's logs use; include it when you report a problem. It is `null` on servers
184
+ that do not send it. An event's or error's `requestId` names the SDK request
185
+ that caused it instead.
177
186
  Check the effective interruption setting there. Tool wait durations are total
178
187
  server deadlines, not remaining time. A `null` duration can mean an omitted
179
188
  field; it does not prove that no deadline exists.
@@ -215,30 +224,81 @@ server reported in its initialization acknowledgment. A missing field is
215
224
  default. An unrecognized server eagerness becomes `"unknown"`.
216
225
  `interruptOnSpeech` remains a separate connection option.
217
226
 
227
+ ## Update session settings
228
+
229
+ This method is available in the repository source and requires an SDK release
230
+ that includes session updates.
231
+
232
+ ```ts
233
+ const info = await session.update({
234
+ instructions: "Handle billing. Use only the supplied tools.",
235
+ tools: [refundTool], // An existing ToolDefinition.
236
+ });
237
+ console.log(info.settingsRevision);
238
+
239
+ // For a transfer triggered by a tool call:
240
+ await session.submitToolResult(call, "Transferred to billing.");
241
+ await session.continueReply(parent);
242
+ ```
243
+
244
+ `RealtimeUpdateOptions` has optional `instructions`, `tools`, `voice`,
245
+ `interruptOnSpeech`, and `signal` fields. Omitted fields and `undefined` keep
246
+ their values. `null` is not accepted.
247
+
248
+ Omitted fields keep their values. A supplied tool list replaces the complete
249
+ list. Empty instructions clear the prompt; an empty tool list removes all tools.
250
+ An empty voice selects the deployment default. Instructions and tools supplied
251
+ together change in one request.
252
+
253
+ The method waits for the matching `session.updated` acknowledgment and returns
254
+ session information. The stored session information changes only after that
255
+ acknowledgment. A rejected update leaves it unchanged and keeps the connection
256
+ open. Cancellation after submission does not undo an accepted update.
257
+
258
+ Updates do not wait for turn readiness or tool results. Each reply keeps the
259
+ settings it began with. A reply prepared on an early turn-end guess can be
260
+ announced after an update but still use the previous settings revision.
261
+ Modalities, eagerness, and the end-of-turn timeout cannot change mid-session.
262
+
263
+ `SessionInfo`, `ResponseStarted`, and `ResponseEnded` expose `settingsRevision`.
264
+ It is `null` when the server does not publish it. The field is optional on
265
+ caller-created values. Users do not need to manage it. Use each reply's revision
266
+ to identify its settings, rather than the latest session revision.
267
+
218
268
  ## Choose an operation
219
269
 
220
270
  Every method returns a promise. Arguments without `?` are required.
221
271
 
222
272
  | Method | Result and behavior |
223
273
  | --- | --- |
274
+ | `update(options?)` | Changes supplied settings without reconnecting; returns `SessionInfo` after acknowledgment. |
224
275
  | `sendText(text, options?)` | Starts a typed user turn after readiness; returns `ResponseRef` at response creation. |
225
276
  | `sendAudio(chunk, options?)` | Sends microphone audio with transport backpressure. |
226
277
  | `requestReply(options?)` | Requests a reply without new user input; returns `ResponseRef`. Options can include `instruction` and `toolCall`. |
227
278
  | `addMessage(role, text, options?)` | Adds user or assistant history without a reply; returns `ItemRef` after acknowledgment. |
279
+ | `getHistory(options?)` | Returns the ordered `readonly HistoryItem[]` that the next reply would see. |
280
+ | `createItem(item, options?)` | Adds a message, past tool call, or tool result without a reply; returns `ItemRef` after acknowledgment. Options can include `previousItemId`. |
281
+ | `deleteItem(itemId, options?)` | Hides an item from later replies and waits for acknowledgment. |
228
282
  | `submitToolResult(call, output, options?)` | Records a string result and waits for acknowledgment. |
229
283
  | `continueReply(parent, options?)` | Waits for parent completion and all tool result acknowledgments, then returns a new `ResponseRef`. |
230
284
  | `cancel(response, options?)` | Requests generation cancellation and waits for a terminal response or refusal. |
231
285
  | `clearAudio(options?)` | Clears buffered input and resets audio conversion after acknowledgment. |
286
+ | `setResponseMetadata(metadata, options?)` | Replaces the labels for later replies once Prism confirms. |
232
287
  | `reportPlayback(report, options?)` | Reports interrupted or finished playback. |
233
288
  | `close()` | Closes the session and releases its resources. |
234
289
 
235
290
  Operation options accept `signal?: AbortSignal`. `requestReply` accepts its
236
- instruction, tool call, and signal in one object. Methods other than `sendText`,
237
- `requestReply`, `addMessage`, and `continueReply` return `Promise<void>`.
238
-
239
- Text must be nonblank and contain at most 4,000 Unicode characters. History
240
- roles are `"user"` and `"assistant"`. A reply instruction applies to one response;
241
- it does not replace session instructions.
291
+ instruction, tool call, and signal in one object. `update` returns
292
+ `Promise<SessionInfo>`. `sendText`, `requestReply`, and `continueReply` return
293
+ `Promise<ResponseRef>`. `addMessage` and `createItem` return `Promise<ItemRef>`.
294
+ `getHistory` returns `Promise<readonly HistoryItem[]>`. The other methods return
295
+ `Promise<void>`.
296
+
297
+ `sendText` and `addMessage` require nonblank text of at most 4,000 Unicode
298
+ characters. `addMessage` accepts `"user"` and `"assistant"` roles. `createItem`
299
+ also accepts `"system"` messages and allows blank message text, with the same
300
+ length limit. A reply instruction applies to one response; it does not replace
301
+ session instructions.
242
302
 
243
303
  A returned `ResponseRef` means generation started. Read `response.ended` for the
244
304
  terminal status. Generation can finish before cancellation takes effect, so a
@@ -304,7 +364,7 @@ also checks TypeScript callers.
304
364
 
305
365
  Filler applies when the reply has said nothing before calling a tool. If a reply
306
366
  calls several tools, the first call's tool controls the filler. `none` suppresses
307
- filler only; it does not silence other speech. Settings are fixed for the session.
367
+ filler only; it does not silence other speech. Use `session.update({ tools })` to replace tools and their filler settings.
308
368
 
309
369
  Execute a tool once for each `tool.call` event. Validate its parsed `arguments`,
310
370
  then submit a string result with `submitToolResult(payload.call, output)`.
@@ -337,7 +397,7 @@ are exported from `@rimelabs/sdk`.
337
397
  | `input.committed` | `itemId` |
338
398
  | `transcript.delta`, `transcript.final` | `itemId` and `delta` or `text` |
339
399
  | `transcript.failed` | `itemId`, `error` |
340
- | `response.started` | `response`, `cause`, nullable `parent` and `inputItemId` |
400
+ | `response.started` | `response`, `cause`, nullable `parent` and `inputItemId`, `inputItemIds` (the user items it answers), `metadata` (your own keys) |
341
401
  | `message.started` | `output` |
342
402
  | `text.delta`, `text.done` | `output` and `delta` or `text` |
343
403
  | `audio.delta`, `audio.done` | `output`; a delta also has `audio.data` and a complete `audio.format` |
@@ -406,6 +466,52 @@ with `RimeRealtimeError`. Its `.fault` has `code`, `message`, `scope`, nullable
406
466
  array. A response fault does not itself end generation. Session faults and lost
407
467
  connections end the session.
408
468
 
469
+ `NormalizedRealtimeFault.retryable` reports whether the same request, unchanged,
470
+ may succeed on another attempt. Read `event.payload.error.retryable` on an `error`
471
+ event or `error.fault.retryable` on `RimeRealtimeError`. The SDK derives this
472
+ value from the code; Prism does not send a retry flag.
473
+
474
+ `RealtimeFault` accepts the previous fault shape, with an optional `retryable`
475
+ field, for caller-created faults. `RimeRealtimeError` accepts this shape and
476
+ ignores any supplied retry flag. Its `.fault` and SDK-emitted event faults are
477
+ `NormalizedRealtimeFault` values with a required boolean `retryable` field.
478
+ The SDK freezes these faults and their `callIds` arrays. Later changes to a
479
+ constructor input do not change the error's fault.
480
+
481
+ `TranscriptFailed`, `FaultEvent`, `InputEvent`, and `SessionEvent` default to
482
+ `RealtimeFault`, so existing event literals can omit `retryable`. These types
483
+ also accept a fault type parameter. `session.events` and the `runConversation`
484
+ event callback use `SessionEvent<NormalizedRealtimeFault>`, which gives their
485
+ faults a required boolean `retryable` field. An explicit `SessionEvent`
486
+ annotation uses the default type and makes `retryable` optional.
487
+
488
+ | Error code | `retryable` |
489
+ | --- | --- |
490
+ | `capacity_exceeded` | `true` |
491
+ | `unavailable` | `true` |
492
+ | `response_timeout` | `true` |
493
+ | `context_length_exceeded` | `false` |
494
+ | All other codes, including unknown codes | `false` |
495
+
496
+ The application chooses the delay, attempt limit, and recovery operation. This
497
+ value does not start a retry. It does not describe a local `RimeTimeoutError` or
498
+ prove that no output or side effect occurred. The SDK's existing readiness
499
+ retries have separate rules: an explicit refusal such as `typed_turn_busy`
500
+ permits another attempt after a new readiness event, although its `retryable`
501
+ value is `false` under this contract.
502
+
503
+ For example, Prism can accept a user's question and then report
504
+ `capacity_exceeded`. `sendText()` has already returned a `ResponseRef`; the
505
+ failure arrives through an `error` event. Wait for `response.ended`, then apply
506
+ the application's retry policy. If the question is already in history, use
507
+ `requestReply()` to ask for another reply when appropriate. Repeating
508
+ `sendText()` can add the question twice. A `response_timeout` can follow partial
509
+ text or audio, which the application must handle before another attempt.
510
+
511
+ For `context_length_exceeded`, the server message contains token counts.
512
+ Unchanged attempts will fail until the conversation is shorter. Start a new
513
+ session with shorter context. Use the history deletion method to remove items before retrying.
514
+
409
515
  Malformed fields in known events and mismatched request acknowledgments close
410
516
  the session with `RimeStreamError`. Unknown event kinds and extra fields remain
411
517
  accepted and ignored. The SDK does not replay a request after a protocol failure.
@@ -420,7 +526,64 @@ unknown outcome.
420
526
 
421
527
  Keep up with the event stream. The queue holds 256 events; incoming messages
422
528
  are limited to 1 MiB. A slow consumer ends the session. There is no automatic
423
- reconnect, history replay, or live configuration update.
529
+ reconnect or history replay.
424
530
 
425
531
  Local peer tests cover the SDK protocol handling. Validate the gateway handshake
426
532
  and endpoint behavior for the deployment you use.
533
+
534
+ The SDK retains the latest 128 interruption policy changes. Instructions or tools
535
+ updates that keep the same interruption policy do not consume this history.
536
+ If an unannounced reply refers to an older evicted policy, the session fails
537
+ with a resource limit error instead of guessing its policy. A reply already
538
+ received keeps its captured policy even after later settings updates.
539
+
540
+ If an interruption setting changes without a published revision, later reply
541
+ revisions can be ambiguous. The SDK preserves earlier known settings and raises
542
+ a resource limit error for an ambiguous reply instead of guessing. A later
543
+ acknowledgment with a revision establishes a new known setting. Replies without
544
+ a revision use the current acknowledged setting.
545
+
546
+ ## Conversation history operations
547
+
548
+ Available in the next SDK release. The Prism server must support history operations.
549
+ Read history to obtain the items the next reply would see, in server order.
550
+ Create messages with user, assistant, or system roles, past function calls, and
551
+ function results. Creating an item does not start a reply or execute a tool.
552
+ Message text is limited to 4000 Unicode characters. Optional client item IDs have
553
+ 1 to 32 characters. Tool arguments and results preserve the supplied strings.
554
+
555
+ Omit the insertion anchor to append, use `root` to insert first, or give an item
556
+ ID to insert after its whole turn. Results go after their calls and cannot take
557
+ an anchor. Add a past call before adding its result.
558
+
559
+ Deletion hides items from subsequent replies and keeps the conversation record.
560
+ Deleting a call or its result hides both. An active reply keeps its original
561
+ context. A deleted active call still needs a result and continuation through the
562
+ existing tool APIs. Deleting an already deleted item succeeds; an unknown ID fails.
563
+ History excludes replies still running and their inputs until those replies end.
564
+ Requests work without typed-turn readiness. A canceled submitted request can still
565
+ take effect; the SDK tracks its acknowledgment and does not replay it.
566
+
567
+ ```text
568
+ const item = await session.createItem({ type: "message", role: "system", text: "Transferred to billing." }, { previousItemId: "root" });
569
+ const items = await session.getHistory();
570
+ await session.deleteItem(item.itemId);
571
+ ```
572
+
573
+ ## History truncation
574
+
575
+ Available in the next SDK release. Set `truncation` at connection setup or during
576
+ an existing session. Omit it to preserve compatibility with older Prism servers.
577
+ The server must support truncation before you send this setting.
578
+
579
+ `auto` drops the oldest turns and retains 0.8 of the available history capacity.
580
+ `disabled` keeps all history and reports `context_length_exceeded` when it no
581
+ longer fits. A retention ratio above zero and at most one selects how much history
582
+ capacity to retain. Instructions and tools remain. This setting does not delete
583
+ items from the conversation record. Session information reports the acknowledged
584
+ policy in `session.info.truncation`, or `null` when an older server does not
585
+ publish it.
586
+
587
+ ```text
588
+ await session.update({ truncation: { retentionRatio: 0.9 } });
589
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rimelabs/sdk",
3
- "version": "0.1.0-alpha.20",
3
+ "version": "0.1.0-alpha.22",
4
4
  "description": "Rime streaming TTS, STT and Prism realtime SDK for Node.js",
5
5
  "license": "MIT",
6
6
  "type": "module",