@breeze.blue/sdk 0.6.3 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+## 0.8.0
+
+- Realtime TTS sessions prefer the optional query-free direct WebSocket URL
+  and authenticate with a non-echoed token-bearing subprotocol. Existing
+  public session URLs remain the fallback for older deployments and clients.
+
+## 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.
@@ -245,9 +278,15 @@ const session = await client.textToSpeech.realtime.createSession("voc_...", {
 // Later, when the first text is ready:
 const connection = await client.textToSpeech.realtime.connect("voc_...", {
   clientSecret: session.clientSecret,
+  websocketUrl: session.websocketUrl,
+  directWebsocketUrl: session.directWebsocketUrl,
 });
 ```
 
+When the session response includes `directWebsocketUrl`, the SDK prefers its
+query-free origin and authenticates with the WebSocket subprotocol. It falls
+back to `websocketUrl` for services that have not enabled the direct transport.
+
 The same `clientSecret` handoff lets a browser connect without ever seeing your
 API key: create the session on your server, hand `session.clientSecret` to the
 page, and build a key-less client there:
@@ -282,7 +321,7 @@ const connection = await browserClient.textToSpeech.realtime.connectManaged("voc
         reconnect,
       });
     }
-    return response.json(); // { clientSecret, websocketUrl? }
+    return response.json(); // { clientSecret, websocketUrl?, directWebsocketUrl? }
   },
 });
 ```
@@ -291,10 +330,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,17 +48,27 @@ export declare class RealtimeTextToSpeechConnection implements AsyncIterable<Rea
     private closed;
     private queuedBytes;
     private failure;
+    private pendingInstructions;
     private closeEventGraceTimer;
     private constructor();
     static open(socket: BreezeBlueWebSocket, options?: {
         timeout?: number;
         signal?: AbortSignal;
+        requiredSubprotocol?: string;
     }): Promise<RealtimeTextToSpeechConnection>;
     startTurn(turnId?: string): void;
     appendText(text: string): void;
     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 +83,7 @@ export declare class RealtimeTextToSpeechConnection implements AsyncIterable<Rea
     private fail;
     private finish;
     private clearCloseEventGraceTimer;
+    private handleInstructionsEvent;
 }
 type RealtimeConnectionFactory = (signal: AbortSignal) => Promise<RealtimeTextToSpeechConnection>;
 /**
@@ -88,6 +99,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 +111,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 +122,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 +144,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,10 @@ 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 REALTIME_SAFE_SUBPROTOCOL = "breeze-realtime-v1";
+const REALTIME_TOKEN_SUBPROTOCOL_PREFIX = "breeze-realtime-token.";
+const REALTIME_MAX_TOKEN_SUBPROTOCOL_LENGTH = 7 * 1024;
 const WEBSOCKET_OPEN = 1;
 export class BreezeBlueClient {
     apiKey;
@@ -128,30 +132,55 @@ class RealtimeTextToSpeechResource {
         return this.client.requestJson("POST", `/v1/text-to-speech/${encodeURIComponent(voiceId)}/realtime-sessions`, undefined, request, options);
     }
     async connect(voiceId, options = {}) {
-        if ((options.clientSecret !== undefined || options.websocketUrl !== undefined) && hasRealtimeSessionParams(options)) {
+        if ((options.clientSecret !== undefined ||
+            options.websocketUrl !== undefined ||
+            options.directWebsocketUrl !== 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.");
-        }
-        const websocketUrl = options.websocketUrl ??
-            (options.clientSecret
-                ? buildUrl(this.client.baseUrl.replace(/^http/i, "ws"), `/v1/text-to-speech/${encodeURIComponent(voiceId)}/stream-input`, { client_secret: options.clientSecret })
-                : (await this.createSession(voiceId, {
-                    modelId: options.modelId,
-                    languageCode: options.languageCode,
-                    instructions: options.instructions,
-                    voiceSettings: options.voiceSettings,
-                    inactivityTimeoutSeconds: options.inactivityTimeoutSeconds,
-                    enableLogging: options.enableLogging,
-                }, {
-                    signal: options.signal,
-                    timeout: options.timeout,
-                })).websocketUrl);
+                "inactivityTimeoutSeconds, and enableLogging when session credentials are provided. " +
+                "Configure these initial values when creating the realtime session instead. " +
+                "To change instructions between turns, call connection.updateInstructions() and wait for session.updated.");
+        }
+        let clientSecret = options.clientSecret;
+        let websocketUrl = options.websocketUrl;
+        let directWebsocketUrl = options.directWebsocketUrl;
+        if (!clientSecret && !websocketUrl && !directWebsocketUrl) {
+            const session = await this.createSession(voiceId, {
+                modelId: options.modelId,
+                languageCode: options.languageCode,
+                instructions: options.instructions,
+                voiceSettings: options.voiceSettings,
+                inactivityTimeoutSeconds: options.inactivityTimeoutSeconds,
+                enableLogging: options.enableLogging,
+            }, {
+                signal: options.signal,
+                timeout: options.timeout,
+            });
+            clientSecret = session.clientSecret;
+            websocketUrl = session.websocketUrl;
+            directWebsocketUrl = session.directWebsocketUrl;
+        }
+        if (!websocketUrl && clientSecret) {
+            websocketUrl = buildUrl(this.client.baseUrl.replace(/^http/i, "ws"), `/v1/text-to-speech/${encodeURIComponent(voiceId)}/stream-input`, { client_secret: clientSecret });
+        }
+        let protocols;
+        let requiredSubprotocol;
+        if (directWebsocketUrl) {
+            if (!clientSecret) {
+                throw new BreezeBlueConfigurationError("realtime directWebsocketUrl requires a clientSecret.");
+            }
+            protocols = realtimeClientSecretSubprotocols(clientSecret);
+            requiredSubprotocol = REALTIME_SAFE_SUBPROTOCOL;
+            websocketUrl = directWebsocketUrl;
+        }
+        if (!websocketUrl) {
+            throw new BreezeBlueConfigurationError("realtime.connect requires session credentials or an API-created session.");
+        }
         const WebSocketImpl = requireWebSocket(options.webSocket ?? this.client.webSocket);
-        const socket = new WebSocketImpl(websocketUrl);
+        const socket = new WebSocketImpl(websocketUrl, protocols);
         return RealtimeTextToSpeechConnection.open(socket, {
             timeout: options.timeout ?? this.client.timeout ?? DEFAULT_REALTIME_HANDSHAKE_TIMEOUT_MS,
             signal: options.signal,
+            requiredSubprotocol,
         });
     }
     /**
@@ -164,7 +193,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,
@@ -188,6 +218,7 @@ class RealtimeTextToSpeechResource {
             return this.connect(voiceId, {
                 clientSecret: credentials.clientSecret,
                 websocketUrl: credentials.websocketUrl,
+                directWebsocketUrl: credentials.directWebsocketUrl,
                 webSocket: options.webSocket,
                 signal,
                 timeout: connectionTimeout,
@@ -196,6 +227,8 @@ class RealtimeTextToSpeechResource {
         return ManagedRealtimeTextToSpeechConnection.open(createConnection, {
             ...options,
             timeout: connectionTimeout,
+        }, (instructions) => {
+            sessionRequest.instructions = instructions;
         });
     }
 }
@@ -207,6 +240,16 @@ function hasRealtimeSessionParams(options) {
         options.inactivityTimeoutSeconds !== undefined ||
         options.enableLogging !== undefined);
 }
+function realtimeClientSecretSubprotocols(clientSecret) {
+    if (!/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]{43}$/.test(clientSecret)) {
+        throw new BreezeBlueConfigurationError("Realtime clientSecret cannot be encoded as a WebSocket subprotocol token.");
+    }
+    const tokenProtocol = `${REALTIME_TOKEN_SUBPROTOCOL_PREFIX}${clientSecret}`;
+    if (tokenProtocol.length > REALTIME_MAX_TOKEN_SUBPROTOCOL_LENGTH) {
+        throw new BreezeBlueConfigurationError("Realtime clientSecret WebSocket subprotocol is too long.");
+    }
+    return [REALTIME_SAFE_SUBPROTOCOL, tokenProtocol];
+}
 export class RealtimeTextToSpeechConnection {
     socket;
     queue = [];
@@ -214,6 +257,7 @@ export class RealtimeTextToSpeechConnection {
     closed = false;
     queuedBytes = 0;
     failure;
+    pendingInstructions;
     closeEventGraceTimer;
     constructor(socket) {
         this.socket = socket;
@@ -234,6 +278,11 @@ export class RealtimeTextToSpeechConnection {
             const succeed = () => {
                 if (settled)
                     return;
+                if (options.requiredSubprotocol !== undefined &&
+                    socket.protocol !== options.requiredSubprotocol) {
+                    fail(new BreezeBlueRealtimeError(`Realtime TTS WebSocket did not negotiate ${options.requiredSubprotocol}.`, { code: "GENERATION_INVALID_RESPONSE" }));
+                    return;
+                }
                 settled = true;
                 cleanup();
                 resolve();
@@ -271,6 +320,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 +337,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 +371,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 +427,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 +442,7 @@ export class RealtimeTextToSpeechConnection {
         }
     }
     handleClose(event) {
+        this.pendingInstructions = undefined;
         this.clearCloseEventGraceTimer();
         if (!this.closed && event.code !== 1000) {
             this.push({
@@ -409,6 +489,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 +503,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 +514,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 +547,7 @@ export class RealtimeTextToSpeechConnection {
  */
 export class ManagedRealtimeTextToSpeechConnection {
     createConnection;
+    onInstructionsConfirmed;
     queue = [];
     drainingEpochs = new Set();
     openAttempts = new Set();
@@ -457,6 +559,7 @@ export class ManagedRealtimeTextToSpeechConnection {
     maxPhysicalSessionMs;
     maxReconnectAttempts;
     reconnectBaseDelayMs;
+    reapplyInstructionsOnOpen;
     current;
     heartbeatTimer;
     heartbeatAckTimer;
@@ -467,11 +570,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 +588,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 +649,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 +688,7 @@ export class ManagedRealtimeTextToSpeechConnection {
             return;
         }
         this.closed = true;
+        this.pendingInstructions = undefined;
         this.clearTimers();
         this.cancelRetryDelay();
         this.cancelOpenAttempts();
@@ -636,6 +780,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 +912,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 +942,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 +983,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 +996,7 @@ export class ManagedRealtimeTextToSpeechConnection {
             this.fail(activeTurnInterruptedError());
             return;
         }
+        this.pendingInstructions = undefined;
         if (epoch.reconnectRequested) {
             this.requestUnexpectedReconnect(epoch);
             return;
@@ -834,6 +1013,7 @@ export class ManagedRealtimeTextToSpeechConnection {
             this.fail(activeTurnInterruptedError(cause));
             return;
         }
+        this.pendingInstructions = undefined;
         this.clearTimers();
         this.current = undefined;
         epoch.connection.close();
@@ -843,6 +1023,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 +1039,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 +1137,7 @@ export class ManagedRealtimeTextToSpeechConnection {
                 return;
             }
             this.rotationPending = true;
-            if (!this.activeTurn) {
+            if (!this.activeTurn && this.pendingInstructions === undefined) {
                 this.beginTransition("planned", epoch);
             }
         }, rotationDelay);
@@ -1050,6 +1238,7 @@ export class ManagedRealtimeTextToSpeechConnection {
             return;
         }
         this.failure = error;
+        this.pendingInstructions = undefined;
         this.closed = true;
         this.clearTimers();
         this.cancelRetryDelay();
@@ -1410,6 +1599,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

@@ -28,6 +28,7 @@ export type BreezeBlueWebSocketConstructor = new (url: string, protocols?: strin
 export interface BreezeBlueWebSocket {
     binaryType: string;
     readyState: number;
+    readonly protocol?: string;
     onopen: ((event: Event) => void) | null;
     onmessage: ((event: MessageEvent) => void) | null;
     onerror: ((event: Event) => void) | null;
@@ -54,12 +55,14 @@ export interface RealtimeTextToSpeechAudioFormat {
 export interface RealtimeTextToSpeechSession {
     clientSecret: string;
     websocketUrl: string;
+    directWebsocketUrl?: string;
     expiresAt: string;
     audioFormat: RealtimeTextToSpeechAudioFormat;
 }
 export interface RealtimeTextToSpeechConnectOptions extends RealtimeTextToSpeechSessionRequest {
     clientSecret?: string;
     websocketUrl?: string;
+    directWebsocketUrl?: string;
     webSocket?: BreezeBlueWebSocketConstructor;
     signal?: AbortSignal;
     /** Handshake timeout in milliseconds. Defaults to the client `timeout`. */
@@ -68,9 +71,11 @@ export interface RealtimeTextToSpeechConnectOptions extends RealtimeTextToSpeech
 export type RealtimeTextToSpeechSessionCredentials = {
     clientSecret: string;
     websocketUrl?: string;
+    directWebsocketUrl?: string;
 } | {
     clientSecret?: string;
     websocketUrl: string;
+    directWebsocketUrl?: string;
 };
 export interface RealtimeTextToSpeechSessionFactoryContext {
     /**
@@ -134,6 +139,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 +218,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.8.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.8.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.8.0",
   "description": "ESM-first TypeScript SDK for the Breeze Blue Developer API.",
   "license": "MIT",
   "author": "Breeze Blue <support@breeze.blue>",