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

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.1.0-alpha.20](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.19...typescript-v0.1.0-alpha.20) (2026-10-22)
+
+
+### Features
+
+* add Prism tool filler controls for Python and TypeScript ([#93](https://github.com/rimelabs/rime-sdk/issues/93)) ([c6d1344](https://github.com/rimelabs/rime-sdk/commit/c6d13445b565cf62b4dd0e7e630c4b86182d6a82))
+* **realtime:** report what ended the user's turn ([#92](https://github.com/rimelabs/rime-sdk/issues/92)) ([88eb9f2](https://github.com/rimelabs/rime-sdk/commit/88eb9f20d9c9943a67b809452493cc27744b794e))
+
 ## [0.1.0-alpha.19](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.18...typescript-v0.1.0-alpha.19) (2026-10-21)
 
 

package/dist/realtime/client.js

@@ -48,6 +48,34 @@ function copyJson(value) {
         return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, copyJson(item)]));
     throw new RimeInputError("Tool schemas must contain finite JSON values");
 }
+function fillerSettings(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new RimeInputError("prismFiller must be a filler object");
+    const kind = value.type;
+    if (!["none", "text", "auto"].includes(kind))
+        throw new RimeInputError("Prism filler type must be none, text, or auto");
+    const field = kind === "text" ? "text" : kind === "auto" ? "instructions" : null;
+    if (Object.entries(value).some(([key, item]) => item !== undefined && key !== "type" && key !== field))
+        throw new RimeInputError("Prism filler has fields not allowed for its type");
+    const text = field === null ? undefined : value[field];
+    if (kind === "text" || text !== undefined) {
+        // Rust str::trim uses Unicode White_Space, which differs from JS trim.
+        if (typeof text !== "string" ||
+            !/\P{White_Space}/u.test(text) ||
+            [...text].length > 500)
+            throw new RimeInputError("Prism filler text must be nonblank and at most 500 characters");
+        // Unicode mode matches lone surrogates but preserves valid UTF-16 pairs.
+        if (/[\uD800-\uDFFF]/u.test(text))
+            throw new RimeInputError("Prism filler text must be valid UTF-8");
+    }
+    if (kind === "text")
+        return { type: "text", text: text };
+    if (kind === "auto")
+        return text === undefined
+            ? { type: "auto" }
+            : { type: "auto", instructions: text };
+    return { type: "none" };
+}
 export class Realtime {
     credentials;
     checkOpen;
@@ -96,6 +124,9 @@ export class Realtime {
                     throw new RimeInputError("Tool parameters must be an object");
                 return {
                     type: "function",
+                    ...(tool.prismFiller === undefined
+                        ? {}
+                        : { prism_filler: fillerSettings(tool.prismFiller) }),
                     function: {
                         name: tool.name,
                         description: tool.description ?? "",

package/dist/realtime/protocol.d.ts

@@ -14,6 +14,7 @@ export interface SessionSettings {
             description: string;
             parameters: t.JsonObject;
         };
+        prism_filler?: t.PrismFiller;
     }[];
     voice?: string;
     instructions?: string;

package/dist/realtime/protocol.js

@@ -230,13 +230,25 @@ function decodeValue(value, sessionId) {
                 audioStartMs: integer(event.audio_start_ms, "audio_start_ms"),
             };
             break;
-        case "input_audio_buffer.speech_stopped":
+        case "input_audio_buffer.speech_stopped": {
+            const reason = event.prism_end_reason === undefined
+                ? null
+                : string(event.prism_end_reason, "prism_end_reason");
             payload = {
                 kind: "speech.stopped",
                 itemId: id(event.item_id, "item_id"),
                 audioEndMs: integer(event.audio_end_ms, "audio_end_ms"),
+                endReason: reason === null ||
+                    reason === "semantic" ||
+                    reason === "timeout" ||
+                    reason === "silence" ||
+                    reason === "max_duration" ||
+                    reason === "detector_changed"
+                    ? reason
+                    : "unknown",
             };
             break;
+        }
         case "input_audio_buffer.committed":
             payload = {
                 kind: "input.committed",

package/dist/realtime/types.d.ts

@@ -14,10 +14,27 @@ export interface RealtimeTimeouts {
 export interface RealtimeOperationOptions {
     readonly signal?: AbortSignal;
 }
+/** Speech while a tool runs. Text and instructions must be nonblank and at
+ * most 500 Unicode scalar values. Invalid UTF-8 is rejected.
+ * Omit the setting to use the server default. */
+export type PrismFiller = {
+    readonly type: "none";
+    readonly text?: never;
+    readonly instructions?: never;
+} | {
+    readonly type: "text";
+    readonly text: string;
+    readonly instructions?: never;
+} | {
+    readonly type: "auto";
+    readonly instructions?: string;
+    readonly text?: never;
+};
 export interface ToolDefinition {
     readonly name: string;
     readonly parameters: JsonObject;
     readonly description?: string;
+    readonly prismFiller?: PrismFiller;
 }
 export type TurnEagerness = "low" | "medium" | "high" | "auto";
 /** Omitted fields use the server's turn timing defaults. */
@@ -109,10 +126,24 @@ export interface SpeechStarted {
     readonly itemId: string;
     readonly audioStartMs: number;
 }
+/** What ended the user's turn:
+ * - `semantic`: Prism judged from the user's speech that they had finished;
+ *   `eagerness` sets how readily it does.
+ * - `timeout`: the user was silent for `endOfTurnTimeoutMs`, and the timeout
+ *   ended the turn before Prism judged that they had finished.
+ * - `silence`: Prism's backup turn detection ended the turn at a short pause;
+ *   it does not apply `eagerness` or `endOfTurnTimeoutMs`.
+ * - `max_duration`: the user spoke for the longest turn Prism takes; what
+ *   they say next starts a new turn.
+ * - `detector_changed`: Prism switched between its main and backup turn
+ *   detection while the user spoke; nothing the user did ended the turn. */
+export type SpeechEndReason = "semantic" | "timeout" | "silence" | "max_duration" | "detector_changed";
 export interface SpeechStopped {
     readonly kind: "speech.stopped";
     readonly itemId: string;
     readonly audioEndMs: number;
+    /** Null means the server did not publish the field. */
+    readonly endReason: SpeechEndReason | "unknown" | null;
 }
 export interface InputCommitted {
     readonly kind: "input.committed";

package/docs/realtime.md

@@ -275,6 +275,37 @@ Declare tools with plain `ToolDefinition` objects. Names must be nonblank and
 unique; schemas must contain finite JSON values. The SDK copies schemas before
 connection setup, so later caller changes cannot alter initialization.
 
+Set `prismFiller` to control what Prism says while the tool runs:
+
+```ts
+import type { ToolDefinition } from "@rimelabs/sdk";
+
+const pressDigits: ToolDefinition = {
+  name: "press_digits",
+  parameters: { type: "object", properties: { digits: { type: "string" } } },
+  prismFiller: { type: "none" },
+};
+```
+
+| Setting | Behavior |
+| --- | --- |
+| Omitted | Use the server default, currently `auto`. |
+| `{ type: "none" }` | Suppress filler for this tool. |
+| `{ type: "text", text: "One moment." }` | Speak the supplied text. |
+| `{ type: "auto" }` | Let Prism write a line from the tool description. |
+| `{ type: "auto", instructions: "Say you are checking the order." }` | Guide the generated line. |
+
+Text and instructions must be valid UTF-8, contain at most 500 Unicode scalar
+values, and contain a character outside the Unicode `White_Space` set. This
+matches the engine's validation. The SDK preserves the supplied text and copies
+filler settings before connection setup. Invalid settings raise `RimeInputError` before opening a
+connection, including for JavaScript callers. The exported `PrismFiller` union
+also checks TypeScript callers.
+
+Filler applies when the reply has said nothing before calling a tool. If a reply
+calls several tools, the first call's tool controls the filler. `none` suppresses
+filler only; it does not silence other speech. Settings are fixed for the session.
+
 Execute a tool once for each `tool.call` event. Validate its parsed `arguments`,
 then submit a string result with `submitToolResult(payload.call, output)`.
 Use `JSON.stringify(...)` for a structured result. Call
@@ -301,7 +332,8 @@ are exported from `@rimelabs/sdk`.
 | --- | --- |
 | `input.ready` | No data fields. Turn methods handle the readiness wait. |
 | `speech.hint` | `audioStartMs`; the user may have started speaking over a playing reply. It can be a false alarm: lower playback, do not stop it. |
-| `speech.started`, `speech.stopped` | `itemId` and `audioStartMs` or `audioEndMs` |
+| `speech.started` | `itemId`, `audioStartMs` |
+| `speech.stopped` | `itemId`, `audioEndMs`, `endReason`: what ended the turn (`semantic`, `timeout`, `silence`, `max_duration` or `detector_changed`), `unknown` for a newer value, or null from a server that does not send it |
 | `input.committed` | `itemId` |
 | `transcript.delta`, `transcript.final` | `itemId` and `delta` or `text` |
 | `transcript.failed` | `itemId`, `error` |

package/package.json

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