@zhivex-ai/core 1.3.0 → 1.4.0

package/dist/realtime.js

@@ -1,5 +1,19 @@
 import { BoundedReplayBroadcast, StreamBufferOverflowError } from "./bounded-broadcast.js";
-import { ConfigurationError, UnsupportedFeatureError, ValidationError } from "./errors.js";
+import { ConfigurationError, ConflictError, UnsupportedFeatureError, ValidationError } from "./errors.js";
+const asError = (error) => error instanceof Error ? error : new Error(String(error));
+const canonicalRealtimeValue = (value) => {
+    if (value === undefined)
+        return "undefined";
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? String(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalRealtimeValue).join(",")}]`;
+    return `{${Object.keys(value)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalRealtimeValue(value[key])}`)
+        .join(",")}}`;
+};
+const realtimeToolCallFingerprint = (event) => `${JSON.stringify(event.toolCall.name)}:${canonicalRealtimeValue(event.toolCall.input)}`;
 export class CallbackRealtimeSession {
     provider;
     modelId;
@@ -7,9 +21,17 @@ export class CallbackRealtimeSession {
     config;
     connection;
     callbacks;
+    initializationTimeoutMs;
     broadcast = new BoundedReplayBroadcast();
-    receiverPromise;
-    closed = false;
+    seenToolCalls = new Map();
+    state = "new";
+    initializationPromise;
+    terminationPromise;
+    terminationError;
+    readyPromise;
+    resolveReady;
+    rejectReady;
+    ready = false;
     ended = false;
     constructor(options) {
         this.provider = options.provider;
@@ -18,80 +40,158 @@ export class CallbackRealtimeSession {
         this.config = options.config;
         this.connection = options.connection;
         this.callbacks = options.callbacks;
+        if (options.initializationTimeoutMs !== undefined &&
+            (!Number.isSafeInteger(options.initializationTimeoutMs) || options.initializationTimeoutMs <= 0)) {
+            throw new ConfigurationError("Realtime initialization timeout must be a positive safe integer.");
+        }
+        this.initializationTimeoutMs = options.initializationTimeoutMs;
+        if (this.callbacks.isReadyPayload) {
+            this.readyPromise = new Promise((resolve, reject) => {
+                this.resolveReady = resolve;
+                this.rejectReady = reject;
+            });
+        }
     }
-    async initialize() {
-        if (this.callbacks.buildInitialPayloads) {
-            await this.sendPayloads(this.callbacks.buildInitialPayloads(this.config, this.config));
+    initialize() {
+        if (this.state === "open") {
+            return Promise.resolve();
         }
-        const event = {
-            type: "realtime-start"
-        };
-        await this.broadcast.publish(event);
-        if (!this.receiverPromise) {
-            this.receiverPromise = this.receiveLoop();
+        if (this.initializationPromise) {
+            return this.initializationPromise;
         }
+        if (this.state !== "new") {
+            return Promise.reject(new ConfigurationError("Realtime session is already closing or closed."));
+        }
+        this.state = "initializing";
+        this.initializationPromise = this.start();
+        return this.initializationPromise;
     }
     async sendAudio(frame) {
-        await this.sendPayloads(this.callbacks.buildAudioPayloads(frame, this.config));
+        this.assertOpen();
+        await this.sendBuiltPayloads(() => this.callbacks.buildAudioPayloads(frame, this.config));
     }
     async sendMedia(frame) {
+        this.assertOpen();
         if (frame.mediaType.startsWith("audio/")) {
-            await this.sendAudio(frame);
+            await this.sendBuiltPayloads(() => this.callbacks.buildAudioPayloads(frame, this.config));
             return;
         }
         if (!this.callbacks.buildMediaPayloads) {
             throw new UnsupportedFeatureError(`Realtime media input is not supported for provider "${this.provider}" with media type "${frame.mediaType}".`);
         }
-        await this.sendPayloads(this.callbacks.buildMediaPayloads(frame, this.config));
+        await this.sendBuiltPayloads(() => this.callbacks.buildMediaPayloads(frame, this.config));
     }
     async sendText(text) {
-        await this.sendPayloads(this.callbacks.buildTextPayloads(text, this.config));
+        this.assertOpen();
+        await this.sendBuiltPayloads(() => this.callbacks.buildTextPayloads(text, this.config));
     }
     async sendToolResult(result) {
-        await this.sendPayloads(this.callbacks.buildToolResultPayloads(result, this.config));
-        if (!this.broadcast.isClosed) {
+        this.assertOpen();
+        const payloads = this.callbacks.buildToolResultPayloads(result, this.config);
+        try {
+            await this.sendPayloads(payloads);
             await this.broadcast.publish({
                 type: "realtime-tool-result",
                 toolResult: result
             });
         }
+        catch (error) {
+            await this.terminate({ reason: "error", error });
+            throw error;
+        }
     }
     async update(config) {
-        this.config = {
+        this.assertOpen();
+        const nextConfig = {
             ...this.config,
             ...config
         };
-        await this.sendPayloads(this.callbacks.buildUpdatePayloads(this.config, this.config));
+        await this.sendBuiltPayloads(() => this.callbacks.buildUpdatePayloads(nextConfig, nextConfig));
+        this.config = nextConfig;
     }
     eventStream() {
         return this.broadcast.stream();
     }
     async close() {
-        if (this.closed) {
+        if (this.state === "closed") {
             return;
         }
-        this.closed = true;
+        const initiatedTermination = !this.terminationPromise;
+        const sendClosePayloads = this.state === "open";
+        await this.terminate({
+            reason: "client-close",
+            sendClosePayloads
+        });
+        if (initiatedTermination && this.terminationError) {
+            throw this.terminationError;
+        }
+    }
+    async start() {
         try {
-            if (this.callbacks.buildClosePayloads) {
-                await this.sendPayloads(this.callbacks.buildClosePayloads(this.config, this.config));
+            if (this.callbacks.buildInitialPayloads) {
+                await this.sendPayloads(this.callbacks.buildInitialPayloads(this.config, this.config));
             }
-        }
-        finally {
-            await this.connection.close();
-            try {
-                await this.receiverPromise;
+            if (this.state !== "initializing") {
+                throw new ConfigurationError("Realtime session was closed during initialization.");
             }
-            catch {
-                // ignore connection shutdown errors
+            if (this.readyPromise) {
+                this.state = "handshaking";
+                void this.receiveLoop();
+                if (this.initializationTimeoutMs === undefined) {
+                    await this.readyPromise;
+                }
+                else {
+                    let timer;
+                    try {
+                        await Promise.race([
+                            this.readyPromise,
+                            new Promise((_, reject) => {
+                                timer = setTimeout(() => reject(new Error(`Realtime provider setup timed out after ${this.initializationTimeoutMs}ms.`)), this.initializationTimeoutMs);
+                            })
+                        ]);
+                    }
+                    finally {
+                        if (timer)
+                            clearTimeout(timer);
+                    }
+                }
+                if (this.state !== "handshaking") {
+                    throw this.terminationError ?? new ConfigurationError("Realtime session was closed during initialization.");
+                }
+                this.state = "open";
             }
-            if (!this.ended) {
-                this.ended = true;
-                await this.broadcast.publish({
-                    type: "realtime-end",
-                    reason: "client-close"
-                }, { terminal: true });
+            const event = {
+                type: "realtime-start"
+            };
+            await this.broadcast.publish(event);
+            if (!this.readyPromise) {
+                if (this.state !== "initializing") {
+                    throw new ConfigurationError("Realtime session was closed during initialization.");
+                }
+                this.state = "open";
+                void this.receiveLoop();
+            }
+        }
+        catch (error) {
+            if (this.state !== "closing" && this.state !== "closed") {
+                await this.terminate({ reason: "error", error });
             }
-            await this.broadcast.close();
+            throw error;
+        }
+    }
+    assertOpen() {
+        if (this.state !== "open") {
+            throw new ConfigurationError("Realtime session is not open.");
+        }
+    }
+    async sendBuiltPayloads(build) {
+        const payloads = build();
+        try {
+            await this.sendPayloads(payloads);
+        }
+        catch (error) {
+            await this.terminate({ reason: "error", error });
+            throw error;
         }
     }
     async sendPayloads(payloads) {
@@ -101,131 +201,285 @@ export class CallbackRealtimeSession {
     }
     async receiveLoop() {
         try {
-            while (true) {
+            while (this.state === "open" || this.state === "handshaking") {
                 const payload = await this.connection.recvJson();
+                if (this.state !== "open" && this.state !== "handshaking") {
+                    return;
+                }
                 if (payload == null) {
-                    break;
+                    await this.terminate({ reason: "connection-closed" });
+                    return;
                 }
-                for (const event of this.callbacks.parseEvent((payload ?? {}))) {
-                    if (event.type === "realtime-end") {
-                        this.ended = true;
+                const record = (payload ?? {});
+                if (!this.ready && this.callbacks.isReadyPayload?.(record)) {
+                    this.ready = true;
+                    this.resolveReady?.();
+                }
+                for (const event of this.callbacks.parseEvent(record)) {
+                    if (event.type === "realtime-tool-call") {
+                        const fingerprint = realtimeToolCallFingerprint(event);
+                        const previous = this.seenToolCalls.get(event.toolCall.id);
+                        if (previous !== undefined) {
+                            if (previous !== fingerprint) {
+                                await this.terminate({
+                                    reason: "error",
+                                    error: new ConflictError(`Realtime tool call id "${event.toolCall.id}" was reused with a different payload.`)
+                                });
+                                return;
+                            }
+                            continue;
+                        }
+                        this.seenToolCalls.set(event.toolCall.id, fingerprint);
+                    }
+                    if (event.type === "realtime-error") {
+                        await this.terminate({
+                            reason: "error",
+                            errorEvent: event
+                        });
+                        return;
                     }
-                    await this.broadcast.publish(event, { terminal: event.type === "realtime-end" });
                     if (event.type === "realtime-end") {
-                        await this.broadcast.close();
+                        await this.terminate({
+                            reason: event.reason ?? "connection-closed",
+                            endEvent: event
+                        });
+                        return;
+                    }
+                    if (this.state !== "open" && this.state !== "handshaking") {
                         return;
                     }
+                    await this.broadcast.publish(event);
                 }
             }
-            if (!this.ended) {
-                this.ended = true;
-                await this.broadcast.publish({
-                    type: "realtime-end",
-                    reason: "connection-closed"
-                }, { terminal: true });
-            }
         }
         catch (error) {
-            if (error instanceof StreamBufferOverflowError) {
-                this.closed = true;
-                this.ended = true;
-                this.broadcast.fail(error);
-                await this.connection.close();
+            if (this.state === "closing" || this.state === "closed") {
                 return;
             }
-            const event = {
+            await this.terminate({ reason: "error", error });
+        }
+    }
+    terminate(options) {
+        if (this.terminationPromise) {
+            return this.terminationPromise;
+        }
+        this.state = "closing";
+        this.terminationPromise = this.finishTermination(options);
+        return this.terminationPromise;
+    }
+    async finishTermination(options) {
+        let errorEvent = options.errorEvent;
+        let failure = options.error === undefined ? undefined : asError(options.error);
+        if (options.sendClosePayloads && this.callbacks.buildClosePayloads) {
+            try {
+                await this.sendPayloads(this.callbacks.buildClosePayloads(this.config, this.config));
+            }
+            catch (error) {
+                failure = asError(error);
+            }
+        }
+        try {
+            await this.connection.close();
+        }
+        catch (error) {
+            failure ??= asError(error);
+        }
+        if (!errorEvent && failure) {
+            errorEvent = {
                 type: "realtime-error",
-                error: error instanceof Error ? error : new Error(String(error)),
-                message: error instanceof Error ? error.message : String(error)
+                error: failure,
+                message: failure.message
             };
-            await this.broadcast.publish(event, { terminal: true });
-            if (!this.ended) {
-                this.ended = true;
-                const ended = {
-                    type: "realtime-end",
-                    reason: "error",
-                    providerMetadata: {
-                        message: event.message ?? ""
+        }
+        if (!this.ready && this.readyPromise) {
+            const readinessError = failure ?? errorEvent?.error ?? new ConfigurationError(`Realtime session ended before provider "${this.provider}" acknowledged setup.`);
+            this.rejectReady?.(asError(readinessError));
+        }
+        const terminalEvents = [];
+        if (errorEvent) {
+            terminalEvents.push(errorEvent);
+        }
+        if (!this.ended) {
+            this.ended = true;
+            terminalEvents.push(options.endEvent ?? {
+                type: "realtime-end",
+                reason: errorEvent ? "error" : options.reason,
+                ...(errorEvent
+                    ? {
+                        providerMetadata: {
+                            message: errorEvent.message ?? errorEvent.error?.message ?? ""
+                        }
                     }
-                };
-                await this.broadcast.publish(ended, { terminal: true });
+                    : {})
+            });
+        }
+        try {
+            for (const event of terminalEvents) {
+                await this.broadcast.publish(event, { terminal: true });
+            }
+        }
+        catch (error) {
+            const publishFailure = asError(error);
+            failure ??= publishFailure;
+            if (!this.broadcast.isClosed) {
+                this.broadcast.fail(publishFailure);
             }
         }
         finally {
-            await this.broadcast.close();
+            this.broadcast.close();
+            this.state = "closed";
         }
+        this.terminationError = failure;
     }
 }
 class BrowserRealtimeConnection {
     socket;
     queue = [];
-    resolvers = [];
+    waiters = [];
     closed = false;
     queueFailure;
     maxIncomingFrameBytes;
-    constructor(socket, maxIncomingFrameBytes) {
+    signal;
+    onAbort;
+    constructor(socket, maxIncomingFrameBytes, signal) {
         this.socket = socket;
         this.maxIncomingFrameBytes = maxIncomingFrameBytes;
+        this.signal = signal;
+        this.onAbort = () => {
+            this.fail(signal?.reason instanceof Error
+                ? signal.reason
+                : new DOMException("The realtime connection was aborted.", "AbortError"));
+        };
         socket.onmessage = (event) => {
+            if (this.closed) {
+                return;
+            }
             const value = event.data;
             if (incomingFrameBytes(value) > this.maxIncomingFrameBytes) {
-                this.queueFailure = new ValidationError(`Realtime frame exceeds the ${this.maxIncomingFrameBytes}-byte limit.`);
-                this.closed = true;
-                while (this.resolvers.length > 0) {
-                    this.resolvers.shift()(undefined);
-                }
-                this.socket.close();
+                this.fail(new ValidationError(`Realtime frame exceeds the ${this.maxIncomingFrameBytes}-byte limit.`));
                 return;
             }
-            if (this.resolvers.length > 0) {
-                this.resolvers.shift()(value);
+            if (this.waiters.length > 0) {
+                this.waiters.shift().resolve(value);
             }
             else {
                 if (this.queue.length >= 256) {
-                    this.queueFailure = new StreamBufferOverflowError(256);
-                    this.closed = true;
-                    this.socket.close();
+                    this.fail(new StreamBufferOverflowError(256));
                     return;
                 }
                 this.queue.push(value);
             }
         };
-        socket.onclose = () => {
-            this.closed = true;
-            while (this.resolvers.length > 0) {
-                this.resolvers.shift()(undefined);
+        socket.onclose = (event) => {
+            if (!this.closed &&
+                ((typeof event.code === "number" && event.code !== 1_000) || event.wasClean === false)) {
+                const details = [
+                    typeof event.code === "number" ? `code ${event.code}` : undefined,
+                    event.reason?.trim() || undefined
+                ].filter(Boolean).join(": ");
+                this.fail(new Error(`Realtime WebSocket closed unexpectedly${details ? ` (${details})` : ""}.`));
+                return;
             }
+            this.finish();
         };
         socket.onerror = () => {
-            this.closed = true;
-            while (this.resolvers.length > 0) {
-                this.resolvers.shift()(undefined);
-            }
+            this.fail(new Error("Realtime WebSocket connection failed."));
         };
+        if (signal?.aborted) {
+            this.onAbort();
+        }
+        else {
+            signal?.addEventListener("abort", this.onAbort, { once: true });
+        }
     }
     async sendJson(payload) {
-        this.socket.send(JSON.stringify(payload));
+        if (this.queueFailure) {
+            throw this.queueFailure;
+        }
+        if (this.closed) {
+            throw new Error("Realtime connection is closed.");
+        }
+        try {
+            this.socket.send(JSON.stringify(payload));
+        }
+        catch (error) {
+            const failure = asError(error);
+            this.fail(failure);
+            throw failure;
+        }
     }
     async recvJson() {
         if (this.queueFailure) {
             throw this.queueFailure;
         }
         if (this.queue.length > 0) {
-            return parseIncoming(this.queue.shift(), this.maxIncomingFrameBytes);
+            return this.parseFrame(this.queue.shift());
         }
         if (this.closed) {
             return undefined;
         }
-        const next = await new Promise((resolve) => {
-            this.resolvers.push(resolve);
+        const next = await new Promise((resolve, reject) => {
+            this.waiters.push({ resolve, reject });
         });
         if (this.queueFailure) {
             throw this.queueFailure;
         }
-        return parseIncoming(next, this.maxIncomingFrameBytes);
+        return this.parseFrame(next);
     }
     async close() {
-        this.socket.close();
+        if (this.closed) {
+            return;
+        }
+        this.finish();
+        try {
+            this.socket.close();
+        }
+        catch (error) {
+            const failure = asError(error);
+            this.queueFailure = failure;
+            throw failure;
+        }
+    }
+    async parseFrame(value) {
+        try {
+            return await parseIncoming(value, this.maxIncomingFrameBytes);
+        }
+        catch (error) {
+            const failure = asError(error);
+            this.fail(failure);
+            throw failure;
+        }
+    }
+    finish() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.cleanupSignal();
+        while (this.waiters.length > 0) {
+            this.waiters.shift().resolve(undefined);
+        }
+    }
+    fail(error) {
+        if (this.queueFailure || this.closed) {
+            return;
+        }
+        this.queueFailure = error;
+        this.closed = true;
+        this.queue.length = 0;
+        this.cleanupSignal();
+        while (this.waiters.length > 0) {
+            this.waiters.shift().reject(error);
+        }
+        try {
+            this.socket.close();
+        }
+        catch {
+            // The original transport error remains the actionable failure.
+        }
+    }
+    cleanupSignal() {
+        this.signal?.removeEventListener("abort", this.onAbort);
     }
 }
 const incomingFrameBytes = (value) => {
@@ -298,6 +552,9 @@ const waitForOpen = (socket, signal, timeoutMs) => new Promise((resolve, reject)
     socket.onerror = () => {
         fail("Realtime connection failed.");
     };
+    socket.onclose = () => {
+        fail("Realtime connection closed before opening.");
+    };
     if (signal?.aborted) {
         onAbort();
     }
@@ -317,9 +574,13 @@ export const openWebSocketConnection = async (url, headers, options) => {
     if (!Number.isSafeInteger(maxIncomingFrameBytes) || maxIncomingFrameBytes <= 0) {
         throw new ConfigurationError('The realtime "maxIncomingFrameBytes" option must be a positive safe integer.');
     }
+    if (options?.timeoutMs !== undefined &&
+        (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0)) {
+        throw new ConfigurationError('The realtime "timeoutMs" option must be a positive safe integer.');
+    }
     const socket = new WebSocketCtor(url, options?.subprotocols);
     await waitForOpen(socket, options?.signal, options?.timeoutMs);
-    return new BrowserRealtimeConnection(socket, maxIncomingFrameBytes);
+    return new BrowserRealtimeConnection(socket, maxIncomingFrameBytes, options?.signal);
 };
 export const unsupportedBrowserToken = async () => {
     throw new UnsupportedFeatureError("This realtime model does not support browser session tokens.");
@@ -329,7 +590,25 @@ const encodeRealtimeFrameData = (data) => {
         return data;
     }
     const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
-    return Buffer.from(bytes).toString("base64");
+    const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+    const chunks = [];
+    const inputChunkBytes = 12 * 1024;
+    for (let chunkStart = 0; chunkStart < bytes.length; chunkStart += inputChunkBytes) {
+        const chunkEnd = Math.min(chunkStart + inputChunkBytes, bytes.length);
+        let encodedChunk = "";
+        for (let index = chunkStart; index < chunkEnd; index += 3) {
+            const first = bytes[index] ?? 0;
+            const second = bytes[index + 1];
+            const third = bytes[index + 2];
+            const value = (first << 16) | ((second ?? 0) << 8) | (third ?? 0);
+            encodedChunk += alphabet[(value >>> 18) & 0x3f];
+            encodedChunk += alphabet[(value >>> 12) & 0x3f];
+            encodedChunk += second === undefined ? "=" : alphabet[(value >>> 6) & 0x3f];
+            encodedChunk += third === undefined ? "=" : alphabet[value & 0x3f];
+        }
+        chunks.push(encodedChunk);
+    }
+    return chunks.join("");
 };
 export const encodeAudioFrame = (frame) => encodeRealtimeFrameData(frame.data);
 export const encodeMediaFrame = (frame) => encodeRealtimeFrameData(frame.data);