@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.
- package/CHANGELOG.md +31 -0
- package/README.md +1 -0
- package/dist/realtime/client.js +14 -79
- package/dist/realtime/conversation.d.ts +2 -2
- package/dist/realtime/conversation.js +16 -4
- package/dist/realtime/faults.d.ts +2 -0
- package/dist/realtime/faults.js +25 -0
- package/dist/realtime/history.d.ts +4 -0
- package/dist/realtime/history.js +87 -0
- package/dist/realtime/protocol.d.ts +38 -3
- package/dist/realtime/protocol.js +84 -6
- package/dist/realtime/session.d.ts +17 -1
- package/dist/realtime/session.js +157 -18
- package/dist/realtime/settings.d.ts +11 -0
- package/dist/realtime/settings.js +142 -0
- package/dist/realtime/transport.d.ts +1 -1
- package/dist/realtime/transport.js +5 -2
- package/dist/realtime/types.d.ts +91 -8
- package/dist/realtime/types.js +4 -2
- package/docs/realtime.md +181 -18
- package/package.json +1 -1
package/dist/realtime/types.d.ts
CHANGED
|
@@ -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:
|
|
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:
|
|
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:
|
|
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";
|
package/dist/realtime/types.js
CHANGED
|
@@ -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
|
-
|
|
8
|
-
|
|
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
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
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`.
|
|
156
|
-
|
|
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`, `
|
|
175
|
-
`interruptOnSpeech`, `turnDetection`, `
|
|
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.
|
|
237
|
-
`
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
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.
|
|
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
|
|
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
|
+
```
|