@breeze.blue/sdk 0.6.3 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.7.0
+
+- Realtime TTS connections can update synthesis instructions between turns
+  with `updateInstructions(...)`. The matching `session.updated` event remains
+  on the existing ordered stream, and managed connections carry confirmed
+  instructions across physical-session rotation and idle reconnects.
+  `BreezeBlueRealtimeError.recoverable` means the same connection remains
+  usable: most recoverable turn-command errors cancel the active turn, while
+  an active-turn `session.update` rejection leaves that turn running and
+  callers continue consuming it on the existing connection.
+
 ## 0.6.3
 
 - Simplified model listings to Breeze-native fields: model ID, name, supported

package/README.md

@@ -152,7 +152,14 @@ a `BreezeBlueRealtimeError`. The `audio()` helper also throws
 `BreezeBlueRealtimeError` for server `error` events and abnormal WebSocket
 closes instead of silently ending.
 
-Events are a typed discriminated union (`session.ready`, `turn.started`,
+When `BreezeBlueRealtimeError.recoverable` is `true`, the same connection
+remains usable. Most recoverable turn-command errors cancel the active turn.
+An active-turn `session.update` rejection is the exception: the turn keeps
+running. If `connection.audio()` throws that error, start a fresh `audio()`
+iterator immediately on the same connection and continue collecting the
+current turn; do not start a replacement turn.
+
+Events are a typed discriminated union (`session.ready`, `session.updated`, `turn.started`,
 `audio.started`, `turn.done`, `turn.cancelled`, `usage.committed`,
 `session.expiring`, `session.closed`, `error`, `pong`), with camelCase fields
 such as `turnId`, `historyItemId`, `expiresAt`, and `ttfaMs`. Treat the union as
@@ -160,6 +167,32 @@ non-exhaustive: the server may add event types, and the SDK delivers unknown
 JSON events unchanged — ignore event types you do not recognize instead of
 switching exhaustively.
 
+Between turns, update the synthesis instructions without replacing the
+WebSocket. `updateInstructions(...)` only sends the request; the matching
+`session.updated` acknowledgement remains on the same ordered iterator. Wait
+for it before starting the next turn:
+
+```ts
+connection.updateInstructions("Speak faster and with more energy.");
+for await (const message of connection) {
+  if (message.type === "session.updated") {
+    if (message.instructions !== "Speak faster and with more energy.") {
+      throw new Error("Unexpected instructions acknowledgement");
+    }
+    break;
+  }
+}
+
+connection.startTurn("turn_2");
+```
+
+Instructions must be a non-empty string of at most 1,000 characters. Only one
+update may await acknowledgement, and updates are accepted only while no turn
+is active. An update attempted during a turn is rejected without interrupting
+that turn. Keep one stream consumer: if a long-lived consumer owns the
+iterator, have it signal your turn producer when `session.updated` arrives
+instead of starting a second iterator.
+
 Send a keepalive ping inside the session's `inactivityTimeoutSeconds` window;
 the server answers with a `pong` event. Keep it running during active turns too:
 a long TTFA or upstream stall with no audio does not pause the idle deadline.
@@ -291,10 +324,18 @@ Honor the factory `signal`: the SDK aborts it when the logical connection closes
 or the physical-epoch timeout expires. A custom callback that ignores the
 signal must still enforce its own bounded request timeout.
 
-Session parameters (`modelId`, `languageCode`, `instructions`, `voiceSettings`,
-`inactivityTimeoutSeconds`, `enableLogging`) are fixed when the session is
-created. `connect` ignores them when `clientSecret` or `websocketUrl` is
-provided and logs a warning.
+After a dynamic instruction update receives `session.updated`, the managed SDK
+carries the confirmed value to later physical epochs. SDK-created replacements
+include it in their session request; factory-created replacements receive an
+automatic `session.update` before their next `session.ready` is exposed to the
+logical iterator.
+
+`modelId`, `languageCode`, `voiceSettings`, `inactivityTimeoutSeconds`, and
+`enableLogging` are fixed when the session is created. The initial
+`instructions` value is also supplied at creation, but it can later be
+replaced between turns with `updateInstructions(...)`. `connect` ignores
+initial session options when `clientSecret` or `websocketUrl` is provided and
+logs a warning.
 
 If a realtime WebSocket is interrupted by a network change, service deployment,
 or upstream realtime worker restart, `connectManaged(...)` handles bounded

package/dist/client.d.ts

@@ -48,6 +48,7 @@ export declare class RealtimeTextToSpeechConnection implements AsyncIterable<Rea
     private closed;
     private queuedBytes;
     private failure;
+    private pendingInstructions;
     private closeEventGraceTimer;
     private constructor();
     static open(socket: BreezeBlueWebSocket, options?: {
@@ -59,6 +60,14 @@ export declare class RealtimeTextToSpeechConnection implements AsyncIterable<Rea
     flush(): void;
     endTurn(): void;
     cancelTurn(): void;
+    /**
+     * Request new synthesis instructions for subsequent turns.
+     *
+     * The matching `session.updated` acknowledgement stays on this
+     * connection's existing message stream. Keep the single consumer running
+     * and wait for that event before starting the next turn.
+     */
+    updateInstructions(instructions: string): void;
     /** Send a keepalive ping. The server answers with a `pong` event. */
     ping(): void;
     close(): void;
@@ -73,6 +82,7 @@ export declare class RealtimeTextToSpeechConnection implements AsyncIterable<Rea
     private fail;
     private finish;
     private clearCloseEventGraceTimer;
+    private handleInstructionsEvent;
 }
 type RealtimeConnectionFactory = (signal: AbortSignal) => Promise<RealtimeTextToSpeechConnection>;
 /**
@@ -88,6 +98,7 @@ type RealtimeConnectionFactory = (signal: AbortSignal) => Promise<RealtimeTextTo
  */
 export declare class ManagedRealtimeTextToSpeechConnection implements AsyncIterable<RealtimeTextToSpeechMessage> {
     private readonly createConnection;
+    private readonly onInstructionsConfirmed;
     private readonly queue;
     private readonly drainingEpochs;
     private readonly openAttempts;
@@ -99,6 +110,7 @@ export declare class ManagedRealtimeTextToSpeechConnection implements AsyncItera
     private readonly maxPhysicalSessionMs;
     private readonly maxReconnectAttempts;
     private readonly reconnectBaseDelayMs;
+    private readonly reapplyInstructionsOnOpen;
     private current;
     private heartbeatTimer;
     private heartbeatAckTimer;
@@ -109,11 +121,13 @@ export declare class ManagedRealtimeTextToSpeechConnection implements AsyncItera
     private epochSequence;
     private queuedBytes;
     private activeTurn;
+    private instructions;
+    private pendingInstructions;
     private rotationPending;
     private closed;
     private failure;
     private constructor();
-    static open(createConnection: RealtimeConnectionFactory, options?: RealtimeTextToSpeechManagedConnectOptions): Promise<ManagedRealtimeTextToSpeechConnection>;
+    static open(createConnection: RealtimeConnectionFactory, options?: RealtimeTextToSpeechManagedConnectOptions, onInstructionsConfirmed?: (instructions: string) => void): Promise<ManagedRealtimeTextToSpeechConnection>;
     startTurn(turnId?: string): void;
     /**
      * Start a turn on the current physical epoch, waiting only when an idle
@@ -129,6 +143,14 @@ export declare class ManagedRealtimeTextToSpeechConnection implements AsyncItera
     flush(): void;
     endTurn(): void;
     cancelTurn(): void;
+    /**
+     * Update the synthesis instructions used by subsequent turns.
+     *
+     * The matching `session.updated` acknowledgement stays on this logical
+     * connection's ordered event stream. Confirmed instructions are carried to
+     * later physical WebSocket epochs.
+     */
+    updateInstructions(instructions: string): void;
     /** Send an immediate ping in addition to the managed keepalive schedule. */
     ping(): void;
     close(): void;

package/dist/client.js

@@ -14,6 +14,7 @@ const DEFAULT_REALTIME_RECONNECT_BASE_DELAY_MS = 250;
 const MAX_REALTIME_RECONNECT_DELAY_MS = 4_000;
 const REALTIME_SETTLEMENT_DRAIN_TIMEOUT_MS = 5_000;
 const REALTIME_CLOSE_EVENT_GRACE_MS = 50;
+const REALTIME_MAX_INSTRUCTIONS_CHARACTERS = 1_000;
 const WEBSOCKET_OPEN = 1;
 export class BreezeBlueClient {
     apiKey;
@@ -131,7 +132,8 @@ class RealtimeTextToSpeechResource {
         if ((options.clientSecret !== undefined || options.websocketUrl !== undefined) && hasRealtimeSessionParams(options)) {
             console.warn("@breeze.blue/sdk: realtime.connect ignores modelId, languageCode, instructions, voiceSettings, " +
                 "inactivityTimeoutSeconds, and enableLogging when clientSecret or websocketUrl is provided. " +
-                "Configure these when creating the realtime session instead.");
+                "Configure these initial values when creating the realtime session instead. " +
+                "To change instructions between turns, call connection.updateInstructions() and wait for session.updated.");
         }
         const websocketUrl = options.websocketUrl ??
             (options.clientSecret
@@ -164,7 +166,8 @@ class RealtimeTextToSpeechResource {
         if (options.sessionFactory !== undefined && hasRealtimeSessionParams(options)) {
             console.warn("@breeze.blue/sdk: realtime.connectManaged cannot apply modelId, languageCode, instructions, " +
                 "voiceSettings, inactivityTimeoutSeconds, or enableLogging when sessionFactory is provided. " +
-                "Configure these when the factory creates each realtime session.");
+                "Configure these when the factory creates each realtime session. After connecting, confirmed " +
+                "updateInstructions() values are carried across managed physical sessions.");
         }
         const sessionRequest = {
             modelId: options.modelId,
@@ -196,6 +199,8 @@ class RealtimeTextToSpeechResource {
         return ManagedRealtimeTextToSpeechConnection.open(createConnection, {
             ...options,
             timeout: connectionTimeout,
+        }, (instructions) => {
+            sessionRequest.instructions = instructions;
         });
     }
 }
@@ -214,6 +219,7 @@ export class RealtimeTextToSpeechConnection {
     closed = false;
     queuedBytes = 0;
     failure;
+    pendingInstructions;
     closeEventGraceTimer;
     constructor(socket) {
         this.socket = socket;
@@ -271,6 +277,9 @@ export class RealtimeTextToSpeechConnection {
         return connection;
     }
     startTurn(turnId) {
+        if (this.pendingInstructions !== undefined) {
+            throw new BreezeBlueRealtimeError("Realtime TTS instructions update is awaiting session.updated; wait for that event before starting the next turn.", { code: "BAD_REQUEST", recoverable: true });
+        }
         this.sendJson({ type: "turn.start", ...(turnId ? { turn_id: turnId } : {}) });
     }
     appendText(text) {
@@ -285,6 +294,29 @@ export class RealtimeTextToSpeechConnection {
     cancelTurn() {
         this.sendJson({ type: "turn.cancel" });
     }
+    /**
+     * Request new synthesis instructions for subsequent turns.
+     *
+     * The matching `session.updated` acknowledgement stays on this
+     * connection's existing message stream. Keep the single consumer running
+     * and wait for that event before starting the next turn.
+     */
+    updateInstructions(instructions) {
+        const validated = validateRealtimeInstructions(instructions);
+        if (this.pendingInstructions !== undefined) {
+            throw new BreezeBlueRealtimeError("Realtime TTS already has an instructions update awaiting session.updated.", { code: "BAD_REQUEST", recoverable: true });
+        }
+        this.pendingInstructions = validated;
+        try {
+            this.sendJson({ type: "session.update", instructions: validated });
+        }
+        catch (error) {
+            if (this.pendingInstructions === validated) {
+                this.pendingInstructions = undefined;
+            }
+            throw error;
+        }
+    }
     /** Send a keepalive ping. The server answers with a `pong` event. */
     ping() {
         this.sendJson({ type: "ping" });
@@ -296,6 +328,7 @@ export class RealtimeTextToSpeechConnection {
         if (this.socket.readyState === WEBSOCKET_OPEN) {
             this.sendJson({ type: "session.close" });
         }
+        this.pendingInstructions = undefined;
         this.socket.close(1000);
         this.finish();
     }
@@ -351,7 +384,10 @@ export class RealtimeTextToSpeechConnection {
                 this.fail(new BreezeBlueRealtimeError("Realtime TTS returned an invalid JSON event.", { cause }));
                 return;
             }
-            this.push(camelizeKeys(parsed), data.length);
+            const message = camelizeKeys(parsed);
+            if (this.handleInstructionsEvent(message)) {
+                this.push(message, data.length);
+            }
             return;
         }
         if (data instanceof ArrayBuffer) {
@@ -363,6 +399,7 @@ export class RealtimeTextToSpeechConnection {
         }
     }
     handleClose(event) {
+        this.pendingInstructions = undefined;
         this.clearCloseEventGraceTimer();
         if (!this.closed && event.code !== 1000) {
             this.push({
@@ -409,6 +446,7 @@ export class RealtimeTextToSpeechConnection {
         this.clearCloseEventGraceTimer();
         this.closed = true;
         this.failure = error;
+        this.pendingInstructions = undefined;
         this.queue.length = 0;
         this.queuedBytes = 0;
         this.socket.close(1000);
@@ -422,6 +460,7 @@ export class RealtimeTextToSpeechConnection {
         }
         this.clearCloseEventGraceTimer();
         this.closed = true;
+        this.pendingInstructions = undefined;
         for (const waiter of this.waiters.splice(0)) {
             waiter.resolve({ value: undefined, done: true });
         }
@@ -432,6 +471,25 @@ export class RealtimeTextToSpeechConnection {
             this.closeEventGraceTimer = undefined;
         }
     }
+    handleInstructionsEvent(message) {
+        if (message.type === "session.updated") {
+            if (this.pendingInstructions === undefined ||
+                message.instructions !== this.pendingInstructions) {
+                this.fail(new BreezeBlueRealtimeError("Realtime TTS returned a session.updated acknowledgement that did not match the pending instructions update.", { code: "GENERATION_INVALID_RESPONSE" }));
+                return false;
+            }
+            this.pendingInstructions = undefined;
+        }
+        else if (message.type === "error" && this.pendingInstructions !== undefined) {
+            if (!realtimeErrorFromEvent(message).reconnect) {
+                this.pendingInstructions = undefined;
+            }
+        }
+        else if (message.type === "session.closed") {
+            this.pendingInstructions = undefined;
+        }
+        return true;
+    }
 }
 /**
  * A logical realtime TTS connection backed by bounded physical WebSocket
@@ -446,6 +504,7 @@ export class RealtimeTextToSpeechConnection {
  */
 export class ManagedRealtimeTextToSpeechConnection {
     createConnection;
+    onInstructionsConfirmed;
     queue = [];
     drainingEpochs = new Set();
     openAttempts = new Set();
@@ -457,6 +516,7 @@ export class ManagedRealtimeTextToSpeechConnection {
     maxPhysicalSessionMs;
     maxReconnectAttempts;
     reconnectBaseDelayMs;
+    reapplyInstructionsOnOpen;
     current;
     heartbeatTimer;
     heartbeatAckTimer;
@@ -467,11 +527,16 @@ export class ManagedRealtimeTextToSpeechConnection {
     epochSequence = 0;
     queuedBytes = 0;
     activeTurn = false;
+    instructions;
+    pendingInstructions;
     rotationPending = false;
     closed = false;
     failure;
-    constructor(createConnection, options) {
+    constructor(createConnection, options, onInstructionsConfirmed) {
         this.createConnection = createConnection;
+        this.onInstructionsConfirmed = onInstructionsConfirmed;
+        this.reapplyInstructionsOnOpen = options.sessionFactory !== undefined;
+        this.instructions = this.reapplyInstructionsOnOpen ? undefined : options.instructions;
         this.readyTimeoutMs = positiveNumber(options.timeout ?? DEFAULT_REALTIME_HANDSHAKE_TIMEOUT_MS, "timeout");
         this.heartbeatIntervalMs = optionalNonNegativeNumber(options.heartbeatIntervalMs, "heartbeatIntervalMs");
         this.heartbeatTimeoutMs = positiveNumber(options.heartbeatTimeoutMs ?? DEFAULT_REALTIME_HEARTBEAT_TIMEOUT_MS, "heartbeatTimeoutMs");
@@ -480,17 +545,22 @@ export class ManagedRealtimeTextToSpeechConnection {
         this.maxReconnectAttempts = nonNegativeInteger(options.maxReconnectAttempts ?? DEFAULT_REALTIME_MAX_RECONNECT_ATTEMPTS, "maxReconnectAttempts");
         this.reconnectBaseDelayMs = nonNegativeNumber(options.reconnectBaseDelayMs ?? DEFAULT_REALTIME_RECONNECT_BASE_DELAY_MS, "reconnectBaseDelayMs");
     }
-    static async open(createConnection, options = {}) {
-        const managed = new ManagedRealtimeTextToSpeechConnection(createConnection, options);
+    static async open(createConnection, options = {}, onInstructionsConfirmed = () => { }) {
+        const managed = new ManagedRealtimeTextToSpeechConnection(createConnection, options, onInstructionsConfirmed);
         const epoch = await managed.openEpoch();
         managed.installEpoch(epoch);
         return managed;
     }
     startTurn(turnId) {
+        if (this.pendingInstructions !== undefined) {
+            throw new BreezeBlueRealtimeError("Realtime TTS instructions update is awaiting session.updated; wait for that event before starting the next turn.", { code: "BAD_REQUEST", recoverable: true });
+        }
         const connection = this.requireCurrentConnection();
+        // Claim the turn before the first WebSocket write so a custom WebSocket
+        // implementation cannot re-enter updateInstructions() from send().
+        this.activeTurn = true;
         try {
             connection.startTurn(turnId);
-            this.activeTurn = true;
         }
         catch (error) {
             this.activeTurn = false;
@@ -536,6 +606,36 @@ export class ManagedRealtimeTextToSpeechConnection {
     cancelTurn() {
         this.requireCurrentConnection().cancelTurn();
     }
+    /**
+     * Update the synthesis instructions used by subsequent turns.
+     *
+     * The matching `session.updated` acknowledgement stays on this logical
+     * connection's ordered event stream. Confirmed instructions are carried to
+     * later physical WebSocket epochs.
+     */
+    updateInstructions(instructions) {
+        const validated = validateRealtimeInstructions(instructions);
+        if (this.activeTurn) {
+            throw new BreezeBlueRealtimeError("Realtime TTS instructions can only be updated between turns.", { code: "BAD_REQUEST", recoverable: true });
+        }
+        if (this.pendingInstructions !== undefined) {
+            throw new BreezeBlueRealtimeError("Realtime TTS already has an instructions update awaiting session.updated.", { code: "BAD_REQUEST", recoverable: true });
+        }
+        if (this.transitionPromise !== undefined) {
+            throw new BreezeBlueRealtimeError("Realtime TTS is rotating its physical session; wait for the next session.ready event before updating instructions.", { code: "BAD_REQUEST", recoverable: true });
+        }
+        const connection = this.requireCurrentConnection();
+        this.pendingInstructions = validated;
+        try {
+            connection.updateInstructions(validated);
+        }
+        catch (error) {
+            if (this.pendingInstructions === validated) {
+                this.pendingInstructions = undefined;
+            }
+            throw error;
+        }
+    }
     /** Send an immediate ping in addition to the managed keepalive schedule. */
     ping() {
         this.requireCurrentConnection().ping();
@@ -545,6 +645,7 @@ export class ManagedRealtimeTextToSpeechConnection {
             return;
         }
         this.closed = true;
+        this.pendingInstructions = undefined;
         this.clearTimers();
         this.cancelRetryDelay();
         this.cancelOpenAttempts();
@@ -636,6 +737,26 @@ export class ManagedRealtimeTextToSpeechConnection {
                 }
                 const message = result.value;
                 if (message.type === "session.ready") {
+                    if (this.reapplyInstructionsOnOpen && this.instructions !== undefined) {
+                        connection.updateInstructions(this.instructions);
+                        while (true) {
+                            const confirmation = await Promise.race([iterator.next(), boundary]);
+                            if (confirmation.done) {
+                                throw new BreezeBlueRealtimeError("Realtime TTS connection closed before confirming the instructions update.", { reconnect: true });
+                            }
+                            const confirmationMessage = confirmation.value;
+                            if (confirmationMessage.type === "session.updated") {
+                                break;
+                            }
+                            if (confirmationMessage.type === "error") {
+                                throw realtimeErrorFromEvent(confirmationMessage);
+                            }
+                            if (confirmationMessage.type === "session.closed") {
+                                throw realtimeErrorFromClose(confirmationMessage);
+                            }
+                            pending.push(confirmationMessage);
+                        }
+                    }
                     this.completeOpenAttempt(attempt);
                     return {
                         id: ++this.epochSequence,
@@ -748,6 +869,17 @@ export class ManagedRealtimeTextToSpeechConnection {
         if (message.type === "turn.started") {
             this.activeTurn = true;
         }
+        else if (message.type === "session.updated") {
+            if (this.pendingInstructions === undefined ||
+                message.instructions !== this.pendingInstructions) {
+                this.fail(new BreezeBlueRealtimeError("Realtime TTS returned a session.updated acknowledgement that did not match the pending instructions update.", { code: "GENERATION_INVALID_RESPONSE" }));
+                return false;
+            }
+            const confirmedInstructions = this.pendingInstructions;
+            this.instructions = confirmedInstructions;
+            this.pendingInstructions = undefined;
+            this.onInstructionsConfirmed(confirmedInstructions);
+        }
         else if (message.type === "turn.done") {
             this.activeTurn = false;
             epoch.pendingUsageHistoryIds.add(message.historyItemId);
@@ -767,13 +899,16 @@ export class ManagedRealtimeTextToSpeechConnection {
                 epoch.retryAfterMs = Math.max(epoch.retryAfterMs, message.meta.retryAfterMs);
             }
             if (error.recoverable) {
+                if (this.pendingInstructions !== undefined && !this.activeTurn) {
+                    this.pendingInstructions = undefined;
+                }
                 if (message.code === "GENERATION_CONCURRENCY_EXCEEDED") {
                     // The server rejected turn.start before establishing an active turn,
                     // so no turn.cancelled event will follow to clear local state.
                     this.activeTurn = false;
                 }
                 this.push(message);
-                if (!this.activeTurn && this.rotationPending) {
+                if (!this.activeTurn && this.pendingInstructions === undefined && this.rotationPending) {
                     this.beginTransition("planned", epoch);
                 }
                 return true;
@@ -805,7 +940,7 @@ export class ManagedRealtimeTextToSpeechConnection {
             return true;
         }
         this.push(message);
-        if (!this.activeTurn && this.rotationPending) {
+        if (!this.activeTurn && this.pendingInstructions === undefined && this.rotationPending) {
             this.beginTransition("planned", epoch);
         }
         return true;
@@ -818,6 +953,7 @@ export class ManagedRealtimeTextToSpeechConnection {
             this.fail(activeTurnInterruptedError());
             return;
         }
+        this.pendingInstructions = undefined;
         if (epoch.reconnectRequested) {
             this.requestUnexpectedReconnect(epoch);
             return;
@@ -834,6 +970,7 @@ export class ManagedRealtimeTextToSpeechConnection {
             this.fail(activeTurnInterruptedError(cause));
             return;
         }
+        this.pendingInstructions = undefined;
         this.clearTimers();
         this.current = undefined;
         epoch.connection.close();
@@ -843,6 +980,10 @@ export class ManagedRealtimeTextToSpeechConnection {
         if (this.closed || this.transitionPromise !== undefined) {
             return;
         }
+        if (kind === "planned" && this.pendingInstructions !== undefined) {
+            this.rotationPending = true;
+            return;
+        }
         this.transitionKind = kind;
         this.transitionPromise = (async () => {
             try {
@@ -855,7 +996,11 @@ export class ManagedRealtimeTextToSpeechConnection {
                 this.transitionPromise = undefined;
                 this.transitionKind = undefined;
                 const current = this.current;
-                if (!this.closed && this.rotationPending && !this.activeTurn && current) {
+                if (!this.closed &&
+                    this.rotationPending &&
+                    !this.activeTurn &&
+                    this.pendingInstructions === undefined &&
+                    current) {
                     this.beginTransition("planned", current);
                 }
             }
@@ -949,7 +1094,7 @@ export class ManagedRealtimeTextToSpeechConnection {
                 return;
             }
             this.rotationPending = true;
-            if (!this.activeTurn) {
+            if (!this.activeTurn && this.pendingInstructions === undefined) {
                 this.beginTransition("planned", epoch);
             }
         }, rotationDelay);
@@ -1050,6 +1195,7 @@ export class ManagedRealtimeTextToSpeechConnection {
             return;
         }
         this.failure = error;
+        this.pendingInstructions = undefined;
         this.closed = true;
         this.clearTimers();
         this.cancelRetryDelay();
@@ -1410,6 +1556,18 @@ function requireWebSocket(WebSocketImpl) {
     }
     return WebSocketImpl;
 }
+function validateRealtimeInstructions(instructions) {
+    if (typeof instructions !== "string") {
+        throw new TypeError("instructions must be a string.");
+    }
+    if (instructions.trim().length === 0) {
+        throw new RangeError("instructions must not be empty.");
+    }
+    if (Array.from(instructions).length > REALTIME_MAX_INSTRUCTIONS_CHARACTERS) {
+        throw new RangeError(`instructions must be at most ${REALTIME_MAX_INSTRUCTIONS_CHARACTERS} characters.`);
+    }
+    return instructions;
+}
 function normalizeBaseUrl(value) {
     return value.replace(/\/+$/, "");
 }

package/dist/errors.d.ts

@@ -16,10 +16,11 @@ export declare class BreezeBlueConfigurationError extends BreezeBlueError {
  * message iterator rejects with this error.
  *
  * `recoverable` mirrors the Python SDK's `RealtimeError.recoverable`: it is
- * `true` only when the failure cancelled just the active turn and the
- * connection stays usable. SDK-detected connection failures are never
- * recoverable. `reconnect` tells you whether opening a new session is
- * expected to succeed.
+ * `true` when the same connection remains usable. Most recoverable
+ * turn-command errors cancel the active turn; a `session.update` rejected
+ * while a turn is active does not, so keep consuming that turn. SDK-detected
+ * connection failures are never recoverable. `reconnect` tells you whether
+ * opening a new session is expected to succeed.
  */
 export declare class BreezeBlueRealtimeError extends BreezeBlueError {
     readonly code: string | undefined;

package/dist/errors.js

@@ -12,10 +12,11 @@ export class BreezeBlueConfigurationError extends BreezeBlueError {
  * message iterator rejects with this error.
  *
  * `recoverable` mirrors the Python SDK's `RealtimeError.recoverable`: it is
- * `true` only when the failure cancelled just the active turn and the
- * connection stays usable. SDK-detected connection failures are never
- * recoverable. `reconnect` tells you whether opening a new session is
- * expected to succeed.
+ * `true` when the same connection remains usable. Most recoverable
+ * turn-command errors cancel the active turn; a `session.update` rejected
+ * while a turn is active does not, so keep consuming that turn. SDK-detected
+ * connection failures are never recoverable. `reconnect` tells you whether
+ * opening a new session is expected to succeed.
  */
 export class BreezeBlueRealtimeError extends BreezeBlueError {
     code;

package/dist/types.d.ts

@@ -134,6 +134,10 @@ export interface RealtimeTextToSpeechSessionReadyEvent {
     inactivityTimeoutSeconds: number;
     maxSessionSeconds: number;
 }
+export interface RealtimeTextToSpeechSessionUpdatedEvent {
+    type: "session.updated";
+    instructions: string;
+}
 export interface RealtimeTextToSpeechSessionExpiringEvent {
     type: "session.expiring";
     sessionId: string;
@@ -209,7 +213,7 @@ export interface RealtimeTextToSpeechErrorEvent {
  * (with camelCase keys). Do not rely on an exhaustive `switch` over `type`;
  * ignore event types you do not recognize.
  */
-export type RealtimeTextToSpeechEvent = RealtimeTextToSpeechSessionReadyEvent | RealtimeTextToSpeechSessionExpiringEvent | RealtimeTextToSpeechPongEvent | RealtimeTextToSpeechTurnStartedEvent | RealtimeTextToSpeechAudioStartedEvent | RealtimeTextToSpeechTurnDoneEvent | RealtimeTextToSpeechTurnCancelledEvent | RealtimeTextToSpeechUsageCommittedEvent | RealtimeTextToSpeechSessionClosedEvent | RealtimeTextToSpeechErrorEvent;
+export type RealtimeTextToSpeechEvent = RealtimeTextToSpeechSessionReadyEvent | RealtimeTextToSpeechSessionUpdatedEvent | RealtimeTextToSpeechSessionExpiringEvent | RealtimeTextToSpeechPongEvent | RealtimeTextToSpeechTurnStartedEvent | RealtimeTextToSpeechAudioStartedEvent | RealtimeTextToSpeechTurnDoneEvent | RealtimeTextToSpeechTurnCancelledEvent | RealtimeTextToSpeechUsageCommittedEvent | RealtimeTextToSpeechSessionClosedEvent | RealtimeTextToSpeechErrorEvent;
 export interface RealtimeTextToSpeechAudioMessage {
     type: "audio";
     audio: Uint8Array;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const SDK_VERSION = "0.6.3";
+export declare const SDK_VERSION = "0.7.0";
 export declare const SDK_NAME = "@breeze.blue/sdk";

package/dist/version.js

@@ -1,2 +1,2 @@
-export const SDK_VERSION = "0.6.3";
+export const SDK_VERSION = "0.7.0";
 export const SDK_NAME = "@breeze.blue/sdk";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@breeze.blue/sdk",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "ESM-first TypeScript SDK for the Breeze Blue Developer API.",
   "license": "MIT",
   "author": "Breeze Blue <support@breeze.blue>",