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

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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)
+
+
+### Features
+
+* add realtime conversation runners ([#89](https://github.com/rimelabs/rime-sdk/issues/89)) ([5447be7](https://github.com/rimelabs/rime-sdk/commit/5447be7713896ac8f68191cc957d82c58228296c))
+
 ## [0.1.0-alpha.18](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.17...typescript-v0.1.0-alpha.18) (2026-10-21)
 
 

package/dist/index.d.ts

@@ -8,3 +8,5 @@ export { RealtimeSession } from "./realtime/session.js";
 export * from "./realtime/types.js";
 export { TranscriptStream } from "./stt/stream.js";
 export type { AudioSource, TranscribeOptions, Transcription, TranscriptionOptions, TranscriptionMode, TranscriptionPartial, TranscriptionDelta, TranscriptionOutputContract, TranscriptionFinal, TranscriptionUpdate, } from "./stt/types.js";
+export { runConversation } from "./realtime/conversation.js";
+export type { ConversationSource, ConversationOutput, ConversationPlayback, ConversationOptions, } from "./realtime/conversation.js";

package/dist/index.js

@@ -5,3 +5,4 @@ export * from "./errors.js";
 export { RealtimeSession } from "./realtime/session.js";
 export * from "./realtime/types.js";
 export { TranscriptStream } from "./stt/stream.js";
+export { runConversation } from "./realtime/conversation.js";

package/dist/realtime/conversation.d.ts

@@ -0,0 +1,47 @@
+import type { RealtimeSession } from "./session.js";
+import type { AudioChunk, OutputRef, SessionEvent } from "./types.js";
+export interface ConversationSource {
+    /** Return one chunk, or null at EOF. Abort must release a pending read. */
+    read(signal: AbortSignal): Promise<AudioChunk | null>;
+}
+export interface ConversationOutput {
+    /** Queue audio without blocking. Raise on overflow; never silently drop audio. */
+    write(chunk: AudioChunk): void;
+    /** Seal this output; completion still waits for the device to drain. */
+    end(): void;
+    /** Measured played milliseconds. Reject on measurement failure or abort.
+     * Abort stops the wait, without cancelling the device receipt. */
+    completion(signal: AbortSignal): Promise<number>;
+}
+export interface ConversationPlayback {
+    /** Queue an output in open order; audible playback must be FIFO.
+     * Keep completion and interruption state separate for each output.
+     * Do not mix outputs or play a later output ahead of an earlier one. */
+    open(output: OutputRef): ConversationOutput;
+    /** Stop selected outputs as one batch, including outputs after end().
+     * Discard their unplayed audio before starting any remaining output.
+     * Resume remaining outputs in FIFO order without waiting for new audio.
+     * Repeated interruptions are harmless; each receipt remains independent. */
+    interrupt(outputs: readonly OutputRef[]): void;
+    /** Confirm all playback has stopped and queued audio is discarded.
+     * Caller resources stay open. Reject and release the wait on abort.
+     * The runner supplies a separate signal with a five-second deadline and
+     * waits for cancellation cleanup before returning. */
+    stop(signal: AbortSignal): Promise<void>;
+}
+export interface ConversationOptions {
+    readonly source: ConversationSource;
+    readonly playback: ConversationPlayback;
+    /** Called inline for every event. Must be synchronous and nonblocking.
+     * Scheduled application work remains the caller's responsibility. */
+    readonly onEvent?: (event: SessionEvent) => void;
+    readonly signal?: AbortSignal;
+}
+/** Run until input EOF, session closure, failure, or abort.
+ * Owns the session's active lifetime and closes it on exit. The caller owns
+ * adapter resource contexts. Do not consume session.events or report playback
+ * elsewhere. Adapter operations must settle on abort. No input or callback
+ * queue is added. Limits: 64 responses, 128 outputs, 256 pending operations.
+ * Overflow fails the run. Callback and adapter failures reach the caller.
+ */
+export declare function runConversation(session: RealtimeSession, { source, playback, onEvent, signal }: ConversationOptions): Promise<void>;

package/dist/realtime/conversation.js

@@ -0,0 +1,309 @@
+import { abortable, scope } from "../cancellation.js";
+import { RimeCancelledError, RimeInputError, RimeResourceLimitError, RimeTimeoutError, } from "../errors.js";
+import { Deferred } from "./async.js";
+import { isSessionCloseError } from "./session.js";
+import { RimeRealtimeError } from "./types.js";
+/** Run until input EOF, session closure, failure, or abort.
+ * Owns the session's active lifetime and closes it on exit. The caller owns
+ * adapter resource contexts. Do not consume session.events or report playback
+ * elsewhere. Adapter operations must settle on abort. No input or callback
+ * queue is added. Limits: 64 responses, 128 outputs, 256 pending operations.
+ * Overflow fails the run. Callback and adapter failures reach the caller.
+ */
+export async function runConversation(session, { source, playback, onEvent, signal }) {
+    const controller = new AbortController();
+    const running = controller.signal;
+    const receipts = new AbortController();
+    const abort = () => controller.abort(signal?.reason);
+    if (signal?.aborted)
+        abort();
+    else
+        signal?.addEventListener("abort", abort, { once: true });
+    const replies = new Map();
+    const parents = new Map();
+    const interrupted = new Set();
+    const tasks = new Set();
+    let fail;
+    let failed = false;
+    let failureReason;
+    const failure = new Promise((_, reject) => {
+        fail = (error) => {
+            if (!failed) {
+                failed = true;
+                failureReason = error;
+                reject(error);
+            }
+        };
+    });
+    void failure.catch(() => { });
+    function start(work, local) {
+        if (tasks.size >= 256)
+            throw new RimeResourceLimitError("Conversation pending operation limit exceeded");
+        const task = work();
+        tasks.add(task);
+        void task.then(() => tasks.delete(task), (error) => {
+            tasks.delete(task);
+            const expected = [local, running, receipts.signal].some((signal) => signal?.aborted &&
+                (error === signal.reason ||
+                    error instanceof RimeCancelledError ||
+                    (error instanceof DOMException && error.name === "AbortError")));
+            if (!expected && !isSessionCloseError(error))
+                fail(error);
+        });
+        return task;
+    }
+    async function measure(stream) {
+        const value = await stream.completion(receipts.signal);
+        if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+            throw new RimeInputError("Playback measurement must be finite nonnegative milliseconds");
+        return value;
+    }
+    function end(output) {
+        if (!output.sealed) {
+            output.sealed = true;
+            output.stream.end();
+        }
+    }
+    function cut(output) {
+        if (output.report)
+            return;
+        end(output);
+        output.report = start(async () => {
+            const played = await output.receipt;
+            running.throwIfAborted();
+            try {
+                await session.reportPlayback({
+                    kind: "interrupted",
+                    output: output.ref,
+                    audioEndMs: Math.floor(played),
+                }, { signal: running });
+            }
+            catch (error) {
+                // The session also forwards the refusal to the application callback.
+                if (!(error instanceof RimeRealtimeError) ||
+                    error.fault.scope !== "event" ||
+                    error.fault.code !== "truncate_not_current")
+                    throw error;
+            }
+        });
+    }
+    function finish(reply) {
+        const earlier = [];
+        for (const previous of replies.values()) {
+            if (previous === reply)
+                break;
+            earlier.push(previous.drained.promise);
+        }
+        const finishing = new AbortController();
+        reply.finish = finishing;
+        const cancel = () => finishing.abort(running.reason);
+        if (running.aborted)
+            cancel();
+        else
+            running.addEventListener("abort", cancel, { once: true });
+        start(async () => {
+            try {
+                let played = 0;
+                for (const output of reply.outputs.values())
+                    played += await abortable(output.receipt, finishing.signal);
+                reply.drained.resolve();
+                if (reply.interrupted) {
+                    for (const output of reply.outputs.values())
+                        if (output.report)
+                            await abortable(output.report, finishing.signal);
+                }
+                else {
+                    // Prism's latest drain token clears all earlier playback too.
+                    for (const drained of earlier)
+                        await abortable(drained, finishing.signal);
+                    await session.reportPlayback({ kind: "finished", response: reply.ref, playedMs: played }, { signal: finishing.signal });
+                }
+                finishing.signal.throwIfAborted();
+                replies.delete(reply.ref.responseId);
+            }
+            finally {
+                running.removeEventListener("abort", cancel);
+            }
+        }, finishing.signal);
+    }
+    function wasInterrupted(responseId) {
+        let current = responseId;
+        // The session retains at most 128 response references.
+        for (let count = 0; current !== undefined && count < 128; count++) {
+            if (interrupted.has(current))
+                return true;
+            current = parents.get(current);
+        }
+        return false;
+    }
+    function interrupt(selected) {
+        const affected = selected.filter((reply) => !reply.interrupted);
+        const outputs = affected.flatMap((reply) => [...reply.outputs.values()]);
+        for (const reply of affected) {
+            reply.interrupted = true;
+            if (parents.has(reply.ref.responseId))
+                interrupted.add(reply.ref.responseId);
+            reply.finish?.abort();
+        }
+        if (outputs.length)
+            playback.interrupt(outputs.map((output) => output.ref));
+        for (const output of outputs)
+            cut(output);
+        for (const reply of affected)
+            if (reply.ended)
+                finish(reply);
+    }
+    function outputFor(ref) {
+        const reply = replies.get(ref.response.responseId);
+        if (!reply || reply.ended)
+            return;
+        const key = JSON.stringify([ref.itemId, ref.outputIndex, ref.contentIndex]);
+        let output = reply.outputs.get(key);
+        if (!output) {
+            let count = 0;
+            for (const value of replies.values())
+                count += value.outputs.size;
+            if (count >= 128)
+                throw new RimeResourceLimitError("Conversation output limit exceeded");
+            const stream = playback.open(ref);
+            output = {
+                ref,
+                stream,
+                receipt: start(() => measure(stream)),
+                sealed: false,
+            };
+            reply.outputs.set(key, output);
+            if (reply.interrupted) {
+                playback.interrupt([ref]);
+                cut(output);
+            }
+        }
+        return output;
+    }
+    async function send() {
+        while (!running.aborted) {
+            const chunk = await source.read(running);
+            if (chunk === null)
+                return;
+            await session.sendAudio(chunk, { signal: running });
+        }
+        running.throwIfAborted();
+    }
+    async function read() {
+        for await (const event of session.events) {
+            running.throwIfAborted();
+            const payload = event.payload;
+            switch (payload.kind) {
+                case "response.started": {
+                    if (replies.size >= 64)
+                        throw new RimeResourceLimitError("Conversation response limit exceeded");
+                    const id = payload.response.responseId;
+                    parents.set(id, payload.parent?.responseId);
+                    if (parents.size > 128) {
+                        const expired = parents.keys().next().value;
+                        parents.delete(expired);
+                        interrupted.delete(expired);
+                    }
+                    const blocked = wasInterrupted(id);
+                    if (blocked)
+                        interrupted.add(id);
+                    replies.set(id, {
+                        ref: payload.response,
+                        outputs: new Map(),
+                        interrupted: blocked,
+                        ended: false,
+                        drained: new Deferred(),
+                    });
+                    break;
+                }
+                case "message.started":
+                case "audio.delta":
+                case "audio.done": {
+                    const output = outputFor(payload.output);
+                    if (output) {
+                        const reply = replies.get(payload.output.response.responseId);
+                        if (payload.kind === "audio.delta" && !reply.interrupted)
+                            output.stream.write(payload.audio);
+                        else if (payload.kind === "audio.done")
+                            end(output);
+                    }
+                    break;
+                }
+                case "speech.started":
+                    if (session.info.interruptOnSpeech)
+                        interrupt([...replies.values()]);
+                    break;
+                case "response.abandoned": {
+                    if (parents.has(payload.response.responseId))
+                        interrupted.add(payload.response.responseId);
+                    interrupt([...replies.values()].filter((reply) => wasInterrupted(reply.ref.responseId)));
+                    break;
+                }
+                case "response.ended": {
+                    const reply = replies.get(payload.response.responseId);
+                    if (reply) {
+                        reply.ended = true;
+                        for (const output of reply.outputs.values())
+                            end(output);
+                        finish(reply);
+                    }
+                    break;
+                }
+            }
+            const result = onEvent?.(event);
+            if (result &&
+                typeof result.then === "function") {
+                void Promise.resolve(result).catch(() => { });
+                throw new RimeInputError("onEvent must be synchronous and nonblocking");
+            }
+        }
+    }
+    let original = false;
+    try {
+        running.throwIfAborted();
+        await abortable(Promise.race([start(send), start(read), failure]), running);
+        if (failed)
+            throw failureReason;
+    }
+    catch (error) {
+        if (!isSessionCloseError(error)) {
+            original = true;
+            throw error;
+        }
+    }
+    finally {
+        let cleanupError;
+        // Stop input, event processing and reports, but keep receipt waits alive
+        // until the adapter confirms playback has stopped or the deadline expires.
+        controller.abort();
+        const shutdown = scope([], 5, new RimeTimeoutError("Playback shutdown confirmation timed out"));
+        try {
+            // Await the adapter itself, including cleanup after the deadline aborts.
+            // Racing this promise against abort would leave that cleanup running.
+            await playback.stop(shutdown.signal);
+            shutdown.signal.throwIfAborted();
+        }
+        catch (error) {
+            cleanupError = error;
+        }
+        finally {
+            shutdown.dispose();
+        }
+        receipts.abort();
+        try {
+            await session.close();
+        }
+        catch (error) {
+            cleanupError ??= error;
+        }
+        await Promise.allSettled(tasks);
+        signal?.removeEventListener("abort", abort);
+        if (!original) {
+            if (failed)
+                throw failureReason;
+            signal?.throwIfAborted();
+            if (cleanupError !== undefined)
+                throw cleanupError;
+        }
+    }
+}

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 Recognize only failures created by intentional session closure. */
+export declare function isSessionCloseError(error: unknown): boolean;
 /** One conversation. Consume events concurrently with session operations. */
 export declare class RealtimeSession {
     private readonly socket;

package/dist/realtime/session.js

@@ -16,6 +16,11 @@ const NOT_READY = new Set([
     "proactive_unavailable",
 ]);
 const LIMIT = 128;
+const closeErrors = new WeakSet();
+/** @internal Recognize only failures created by intentional session closure. */
+export function isSessionCloseError(error) {
+    return error instanceof Error && closeErrors.has(error);
+}
 class ResponseState {
     ref;
     done = new Flag();
@@ -152,8 +157,13 @@ export class RealtimeSession {
     check() {
         if (this.failure)
             throw this.failure;
-        if (this.closed)
-            throw new RimeInputError("The realtime session is closed");
+        if (this.closed) {
+            // Reports can start after intentional close, before runner cleanup.
+            // Failed sessions retain failure and take the branch above.
+            const error = new RimeInputError("The realtime session is closed");
+            closeErrors.add(error);
+            throw error;
+        }
     }
     response(ref) {
         this.check();
@@ -717,7 +727,9 @@ export class RealtimeSession {
         if (!this.closing) {
             this.closing = (async () => {
                 if (!this.closed) {
-                    this.fail(new RimeStreamError("Realtime session closed"));
+                    const error = new RimeStreamError("Realtime session closed");
+                    closeErrors.add(error);
+                    this.fail(error);
                     this.failure = null;
                 }
                 await this.socket.close();

package/docs/realtime.md

@@ -10,10 +10,145 @@ microphone capture, tool execution, and playback.
 Start with the [recorded-speech quick start](../README.md#prism-send-recorded-speech)
 to save a spoken reply without audio hardware.
 
-For live conversations, keep the session open after normal cancellation and
-report playback from the output clock. Saving a file is not playback.
+For live conversations, keep the session open after a response is cancelled.
+Report playback from the output clock. Saving a file is not playback.
 Typed turns also support mixed text and voice applications.
 
+## Optional conversation runner
+
+Use `runConversation` to connect your audio adapters once. It sends input,
+queues output, handles interruption, reports measured playback, and stops its
+operations when the conversation ends. The direct session methods remain available.
+
+```ts
+import { Rime, runConversation } from "@rimelabs/sdk";
+
+const client = new Rime();
+const controller = new AbortController();
+try {
+  const session = await client.realtime.connect();
+  // microphone and speaker are adapters owned by your application.
+  await runConversation(session, {
+    source: microphone,
+    playback: speaker,
+    onEvent(event) {
+      if (event.payload.kind === "transcript.final")
+        console.log(event.payload.text);
+    },
+    signal: controller.signal,
+  });
+} finally {
+  await client.close();
+}
+```
+
+The input adapter implements `ConversationSource`.
+`read(signal: AbortSignal): Promise<AudioChunk | null>` returns one chunk,
+with an optional format, or `null` at EOF. An omitted format uses 16 kHz mono
+PCM16. Abort must reject and release a pending
+read. The runner awaits each `session.sendAudio` call before reading again. It
+uses the session's existing PCM conversion and transport backpressure. Input
+continues during output playback.
+
+The playback adapter implements `ConversationPlayback`:
+
+| Method | Contract |
+| --- | --- |
+| `open(output: OutputRef): ConversationOutput` | Queue this output after previously opened outputs. It can be opened before the first audio chunk. |
+| `interrupt(outputs: readonly OutputRef[]): void` | Stop the selected outputs as one batch, discard their unplayed audio, then resume remaining output in queue order. |
+| `stop(signal: AbortSignal): Promise<void>` | Confirm all playback has stopped and queued audio is discarded. Keep caller-owned resources open. |
+
+Each `ConversationOutput` implements:
+
+| Method | Contract |
+| --- | --- |
+| `write(chunk: AudioChunk): void` | Queue 24 kHz mono PCM16 without blocking. Bound the queue and throw on overflow. |
+| `end(): void` | Accept no more audio. Let queued and device audio drain. |
+| `completion(signal: AbortSignal): Promise<number>` | Return actual played milliseconds after drain or interruption. Reject if measurement fails or the signal aborts. |
+
+All synchronous adapter methods must return promptly. Completion can be awaited
+before `end()`. Keep receipts separate for each `OutputRef`, even when a new
+response starts before an old receipt completes. Play outputs in the order they
+were opened, using one FIFO audio queue. Do not mix outputs, interleave their
+audio, or play later outputs before earlier outputs finish or are interrupted.
+Prism assumes that interrupting a partially played reply leaves later replies
+in the same turn unheard. Independent concurrent playback violates that assumption.
+The runner passes all affected output references in one `interrupt` call. Stop
+them and discard their queued audio before starting any remaining output. Then
+resume valid output in queue order, without waiting for another chunk or event.
+Interruption must work after `end()` and tolerate repeated calls. A remote
+adapter must preserve the batch, for example with one message containing all
+selected output IDs. Shutdown stops all output and must not resume playback.
+Receipt delivery can be delayed or arrive out of order; audible playback cannot.
+A receipt includes the device buffer where device timing is available. Bytes
+received or queued do not measure playback. Zero is valid for an output that
+played no audio.
+
+Abort must release each pending adapter operation and remove its listeners.
+Cancellation of a completion wait must not cancel the device receipt. The runner
+stops input, event processing, and report submission on exit. It then awaits
+`stop(signal)` before aborting remaining receipt waits. The stop signal is
+independent of caller cancellation and has a five-second deadline. `stop` must
+resolve only after local or remote playback has stopped, including device
+buffers. Sending a stop command is not confirmation. It must reject and release
+its wait when the stop signal aborts. The runner awaits this cancellation cleanup
+before it returns, so cleanup can extend beyond the deadline. A missing confirmation raises
+`RimeTimeoutError`; disconnects and other shutdown failures must reject too.
+The caller opens and closes the adapter resources. The runner does not open
+audio devices or host a browser.
+
+`onEvent` is optional. It receives every event read from `session.events`, in
+order, after the runner applies audio coordination. It must be synchronous and
+nonblocking. Returning a promise is rejected. Callback exceptions reach the
+caller. The callback can schedule application work. Continue to use
+`submitToolResult` and `continueReply`; the runner neither registers nor executes
+tools. The application must cancel and await its own tool tasks. Response
+failures and nonterminal faults are forwarded for application handling. Session
+failures reject the runner promise.
+
+The runner is the only event reader. Do not consume `session.events` at the same
+time, call `reportPlayback` independently, or send a second audio source. Other
+session methods remain available for manual tools and application actions.
+
+On confirmed `speech.started`, the runner uses the effective
+`session.info.interruptOnSpeech` setting. It stops affected output, waits for the
+interrupted receipt, and reports the measured position. It ignores late audio
+for that response. A `speech.hint` alone does not stop playback. A server
+`truncate_not_current` refusal is forwarded as an event; it does not stop a newer
+response. Finished reports wait for generation completion and every output
+receipt, including outstanding playback from earlier responses. Prism treats
+the latest drain token as confirmation that all earlier playback has stopped.
+An abandoned response also stops its dependent tool continuations, identified
+by response parent references. Unrelated later turns remain eligible to play.
+Late audio from an interrupted response or its continuations is discarded.
+The runner retains at most 128 response parent references.
+A report retains the measured duration of its own response. Waiting for earlier
+playback does not block events or input, and does not wait for later responses.
+
+Once called, the runner owns the session's active lifetime. Input EOF, explicit
+session closure, abort, or failure stops all runner operations and closes the
+session. EOF stops remaining playback and waits for shutdown confirmation.
+Abort, including an abort received during cleanup, waits for playback shutdown
+confirmation or its five-second deadline, then awaits adapter cancellation cleanup
+before rejecting with `signal.reason`.
+Explicit session closure ends normally even with playback reports pending;
+remote connection failures reject with the session error.
+Expected cancellation errors during cleanup are ignored. Other cleanup errors
+reach the caller if there is no original failure. They do not replace an
+existing failure or caller abort. The signal is optional. Use
+an application deadline if an adapter can wait indefinitely.
+
+The runner adds no input or callback queue. It retains at most 64 responses,
+128 output streams, and 256 pending operations. Exceeding a limit throws
+`RimeResourceLimitError`. The adapters must also bound their audio queues.
+
+The [live voice example](https://github.com/rimelabs/rime-sdk/blob/main/typescript/examples/realtime/conversation.ts) supplies the
+[browser audio adapter](https://github.com/rimelabs/rime-sdk/blob/main/typescript/examples/common/browser-audio.ts). Browser hosting
+stays in the example. Its player uses `AudioContext.getOutputTimestamp()` for
+receipts and shutdown confirmation. A disconnect cannot confirm a remote stop.
+The [manual tool example](https://github.com/rimelabs/rime-sdk/blob/main/typescript/examples/realtime/manual-tools.ts) keeps
+tool execution outside the runner.
+
 ## Connect
 
 Use `await client.realtime.connect()` with `RIME_API_KEY` set. It opens a WebSocket,

package/package.json

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