@anam-ai/js-sdk 4.17.0 → 4.18.0

package/dist/main/modules/StreamingClient.d.ts

@@ -14,8 +14,21 @@ export declare class StreamingClient {
     private rtcConfiguration;
     private apiGatewayConfig;
     private peerConnection;
+    private connectionEstablishedEmitted;
+    private iceRestartInProgress;
+    private iceRestartAttempts;
+    private iceRestartAwaitedAnswer;
+    private iceRestartEpisodeStartMs;
+    private iceRestartEpisodeTrigger;
+    private iceRestartStopped;
+    private iceDisconnectedGraceTimer;
+    private iceRestartWatchdogTimer;
+    private pendingWsOpenListener;
+    private pendingWsOpenTimeout;
+    private pendingWsOpenReject;
     private connectionReceivedAnswer;
     private remoteIceCandidateBuffer;
+    private iceRestartCandidateBuffer;
     private inputAudioStream;
     private dataChannel;
     private videoElement;
@@ -83,6 +96,29 @@ export declare class StreamingClient {
      */
     private onIceCandidate;
     private onIceConnectionStateChange;
+    private clearIceDisconnectedGraceTimer;
+    private clearIceRestartWatchdog;
+    private sendIceRestartMetric;
+    private isAwaitingRestartAnswer;
+    private onAnswerAccepted;
+    private clearPendingWsOpenWait;
+    private cancelIceRestart;
+    private flushIceRestartCandidateBuffer;
+    private scheduleIceRestartAfterGrace;
+    /**
+     * Resolve once the signalling WebSocket is open (it auto-reconnects on close),
+     * or reject if it is terminally closed / times out. Restart offers must never
+     * be sent on a dead socket. Timeout + listener are stored so shutdown can clear
+     * them (see clearPendingWsOpenWait).
+     */
+    private ensureSignallingConnected;
+    /**
+     * Automatic ICE restart. Mints a new offer with fresh ICE credentials and
+     * sends it over the existing channel. Bounded retries via a watchdog; on
+     * exhaustion or terminal signalling, falls back to the WebRTC-failure path.
+     */
+    private restartIce;
+    private onIceRestartWatchdog;
     private onConnectionStateChange;
     private handleWebrtcFailure;
     private onTrackEventHandler;

package/dist/main/modules/StreamingClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StreamingClient.d.ts","sourceRoot":"","sources":["../../../src/modules/StreamingClient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"StreamingClient.d.ts","sourceRoot":"","sources":["../../../src/modules/StreamingClient.ts"],"names":[],"mappings":"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"}

package/dist/main/modules/StreamingClient.js

@@ -19,12 +19,34 @@ const ToolCallManager_1 = require("./ToolCallManager");
 const SUCCESS_METRIC_POLLING_TIMEOUT_MS = 15000; // After this time we will stop polling for the first frame and consider the session a failure.
 const STATS_COLLECTION_INTERVAL_MS = 5000;
 const ICE_CANDIDATE_POOL_SIZE = 2; // Optimisation to speed up connection time
+const MAX_ICE_RESTART_ATTEMPTS = 3;
+const ICE_DISCONNECTED_GRACE_MS = 2000;
+const ICE_RESTART_WATCHDOG_MS = 3000;
+const ENSURE_WS_OPEN_TIMEOUT_MS = 5000;
 class StreamingClient {
     constructor(sessionId, options, publicEventEmitter, internalEventEmitter, toolCallManager, connectionMilestones) {
         var _a, _b, _c, _d;
         this.peerConnection = null;
+        this.connectionEstablishedEmitted = false;
+        this.iceRestartInProgress = false;
+        this.iceRestartAttempts = 0;
+        this.iceRestartAwaitedAnswer = false;
+        // Restart-episode telemetry (see sendIceRestartMetric). null = no episode.
+        this.iceRestartEpisodeStartMs = null;
+        this.iceRestartEpisodeTrigger = null;
+        this.iceRestartStopped = false; // set on shutdown; halts all restart activity
+        this.iceDisconnectedGraceTimer = null;
+        this.iceRestartWatchdogTimer = null;
+        this.pendingWsOpenListener = null;
+        this.pendingWsOpenTimeout = null;
+        this.pendingWsOpenReject = null;
         this.connectionReceivedAnswer = false;
         this.remoteIceCandidateBuffer = [];
+        // While a re-offer is being minted and sent, local candidates are buffered here
+        // so they reach the server AFTER the restart offer (which carries the new ICE
+        // credentials); otherwise the engine adds them against the old generation and
+        // drops them. null = not buffering (normal path).
+        this.iceRestartCandidateBuffer = null;
         this.inputAudioStream = null;
         this.dataChannel = null;
         this.videoElement = null;
@@ -431,9 +453,30 @@ class StreamingClient {
                 case types_1.SignalMessageAction.ANSWER: {
                     (_a = this.connectionMilestones) === null || _a === void 0 ? void 0 : _a.record('answer_received');
                     const answer = signalMessage.payload;
-                    yield this.peerConnection.setRemoteDescription(answer);
+                    if (this.peerConnection.signalingState !== 'have-local-offer') {
+                        // Late answer to a superseded / rolled-back restart offer — ignore it so
+                        // it cannot be applied in a stable state or against a different offer.
+                        break;
+                    }
+                    try {
+                        yield this.peerConnection.setRemoteDescription(answer);
+                    }
+                    catch (err) {
+                        console.error('StreamingClient - setRemoteDescription(answer) failed', err);
+                        if (!this.connectionEstablishedEmitted &&
+                            !this.isAwaitingRestartAnswer()) {
+                            // Initial-connection answer: no restart watchdog will retry, so
+                            // surface the failure instead of hanging the connection. Once the
+                            // session has been established, any answer is a restart answer
+                            // (even if ICE recovered on its own and cleared the restart flags
+                            // before it arrived) — ICE-failure handling owns recovery then.
+                            this.handleWebrtcFailure(err);
+                        }
+                        break; // restart answers: let the ICE restart watchdog retry
+                    }
                     (_b = this.connectionMilestones) === null || _b === void 0 ? void 0 : _b.record('remote_description_set');
                     this.connectionReceivedAnswer = true;
+                    this.onAnswerAccepted();
                     // flush the remote buffer
                     yield this.flushRemoteIceCandidateBuffer();
                     break;
@@ -455,6 +498,8 @@ class StreamingClient {
                 }
                 case types_1.SignalMessageAction.END_SESSION:
                     const reason = signalMessage.payload;
+                    // Server-ended session mid-restart counts as aborted; user hang-up doesn't.
+                    this.sendIceRestartMetric('aborted');
                     (_d = this.connectionMilestones) === null || _d === void 0 ? void 0 : _d.publishFailure({
                         failureStage: 'server_closed_connection',
                     });
@@ -546,6 +591,11 @@ class StreamingClient {
                 this.firstLocalIceCandidateSent = true;
                 (_a = this.connectionMilestones) === null || _a === void 0 ? void 0 : _a.record('first_local_ice_candidate_sent', getIceCandidateMilestoneTags(event.candidate));
             }
+            if (this.iceRestartCandidateBuffer) {
+                // Hold until the re-offer is sent (see restartIce).
+                this.iceRestartCandidateBuffer.push(event.candidate);
+                return;
+            }
             this.signallingClient.sendIceCandidate(event.candidate);
         }
         else {
@@ -553,31 +603,307 @@ class StreamingClient {
         }
     }
     onIceConnectionStateChange() {
-        var _a, _b, _c, _d, _e, _f, _g;
-        const iceConnectionState = (_a = this.peerConnection) === null || _a === void 0 ? void 0 : _a.iceConnectionState;
-        if (iceConnectionState) {
+        var _a, _b, _c;
+        const state = (_a = this.peerConnection) === null || _a === void 0 ? void 0 : _a.iceConnectionState;
+        if (state) {
             (_b = this.connectionMilestones) === null || _b === void 0 ? void 0 : _b.record('ice_connection_state_changed', {
-                iceConnectionState,
+                iceConnectionState: state,
             });
         }
-        if (((_c = this.peerConnection) === null || _c === void 0 ? void 0 : _c.iceConnectionState) === 'connected' ||
-            ((_d = this.peerConnection) === null || _d === void 0 ? void 0 : _d.iceConnectionState) === 'completed') {
-            if (!this.connectionEstablishedMilestoneRecorded) {
-                this.connectionEstablishedMilestoneRecorded = true;
-                (_e = this.connectionMilestones) === null || _e === void 0 ? void 0 : _e.record('client_connection_established', {
-                    iceConnectionState: this.peerConnection.iceConnectionState,
-                });
+        switch (state) {
+            case 'connected':
+            case 'completed':
+                this.clearIceDisconnectedGraceTimer();
+                this.clearIceRestartWatchdog();
+                this.iceRestartInProgress = false;
+                this.sendIceRestartMetric('recovered'); // before the attempts reset below
+                this.iceRestartAttempts = 0;
+                this.signallingClient.endIceRestartReconnect();
+                if (!this.connectionEstablishedMilestoneRecorded) {
+                    this.connectionEstablishedMilestoneRecorded = true;
+                    (_c = this.connectionMilestones) === null || _c === void 0 ? void 0 : _c.record('client_connection_established', {
+                        iceConnectionState: state,
+                    });
+                }
+                if (!this.connectionEstablishedEmitted) {
+                    this.connectionEstablishedEmitted = true;
+                    this.publicEventEmitter.emit(types_1.AnamEvent.CONNECTION_ESTABLISHED);
+                }
+                this.startStatsCollection(); // idempotent (guards on statsCollectionInterval)
+                break;
+            case 'disconnected':
+                this.scheduleIceRestartAfterGrace();
+                break;
+            case 'failed':
+                this.clearIceDisconnectedGraceTimer();
+                void this.restartIce();
+                break;
+        }
+    }
+    clearIceDisconnectedGraceTimer() {
+        if (this.iceDisconnectedGraceTimer) {
+            clearTimeout(this.iceDisconnectedGraceTimer);
+            this.iceDisconnectedGraceTimer = null;
+        }
+    }
+    clearIceRestartWatchdog() {
+        if (this.iceRestartWatchdogTimer) {
+            clearTimeout(this.iceRestartWatchdogTimer);
+            this.iceRestartWatchdogTimer = null;
+        }
+    }
+    // One metric per restart episode, sent at episode end. No-op when no
+    // episode is active; deliberately silent on user shutdown mid-episode.
+    sendIceRestartMetric(outcome) {
+        var _a;
+        if (this.iceRestartEpisodeStartMs === null) {
+            return;
+        }
+        const durationMs = Math.round(performance.now() - this.iceRestartEpisodeStartMs);
+        const trigger = (_a = this.iceRestartEpisodeTrigger) !== null && _a !== void 0 ? _a : 'unknown';
+        this.iceRestartEpisodeStartMs = null;
+        this.iceRestartEpisodeTrigger = null;
+        // durationMs is the value, not a tag: near-unique tag values explode
+        // InfluxDB series cardinality. Episode count = count of points.
+        (0, ClientMetrics_1.sendClientMetric)(ClientMetrics_1.ClientMetricMeasurement.CLIENT_METRIC_MEASUREMENT_ICE_RESTART, durationMs, {
+            outcome,
+            attempts: this.iceRestartAttempts,
+            trigger,
+        });
+    }
+    // True while a restart offer is outstanding (in-progress gate, awaited-answer
+    // grace cycle, or armed watchdog) — i.e. an incoming answer belongs to an ICE
+    // restart rather than the initial connection.
+    isAwaitingRestartAnswer() {
+        return (this.iceRestartInProgress ||
+            this.iceRestartAwaitedAnswer ||
+            this.iceRestartWatchdogTimer !== null);
+    }
+    onAnswerAccepted() {
+        var _a;
+        const wasAwaitingRestartAnswer = this.isAwaitingRestartAnswer();
+        this.clearIceRestartWatchdog();
+        this.iceRestartAwaitedAnswer = false;
+        if (!wasAwaitingRestartAnswer) {
+            return;
+        }
+        this.iceRestartInProgress = false;
+        const state = (_a = this.peerConnection) === null || _a === void 0 ? void 0 : _a.iceConnectionState;
+        if (state === 'disconnected' || state === 'failed') {
+            this.scheduleIceRestartAfterGrace();
+        }
+    }
+    // Clears the pending ensureSignallingConnected wait (timeout + listener).
+    clearPendingWsOpenWait() {
+        if (this.pendingWsOpenTimeout) {
+            clearTimeout(this.pendingWsOpenTimeout);
+            this.pendingWsOpenTimeout = null;
+        }
+        if (this.pendingWsOpenListener) {
+            this.internalEventEmitter.removeListener(types_1.InternalEvent.WEB_SOCKET_OPEN, this.pendingWsOpenListener);
+            this.pendingWsOpenListener = null;
+        }
+        this.pendingWsOpenReject = null;
+    }
+    // Stops all restart activity: timers, pending WS wait, and the in-progress gate.
+    cancelIceRestart() {
+        this.clearIceDisconnectedGraceTimer();
+        this.clearIceRestartWatchdog();
+        const reject = this.pendingWsOpenReject;
+        this.clearPendingWsOpenWait();
+        if (reject)
+            reject(new Error('ice restart cancelled'));
+        this.iceRestartCandidateBuffer = null;
+        this.iceRestartInProgress = false;
+        // End the metric episode: a late END_SESSION after shutdown must not
+        // count the hang-up as an aborted restart.
+        this.iceRestartEpisodeStartMs = null;
+        this.iceRestartEpisodeTrigger = null;
+        this.signallingClient.endIceRestartReconnect();
+    }
+    // Send any candidates buffered while the re-offer was minted+sent, then stop
+    // buffering (see restartIce/onIceCandidate).
+    flushIceRestartCandidateBuffer() {
+        const buffered = this.iceRestartCandidateBuffer;
+        this.iceRestartCandidateBuffer = null;
+        if (!buffered)
+            return;
+        for (const candidate of buffered) {
+            this.signallingClient.sendIceCandidate(candidate);
+        }
+    }
+    scheduleIceRestartAfterGrace() {
+        if (this.iceRestartStopped ||
+            this.iceRestartInProgress ||
+            this.iceDisconnectedGraceTimer) {
+            return;
+        }
+        this.iceDisconnectedGraceTimer = setTimeout(() => {
+            var _a;
+            this.iceDisconnectedGraceTimer = null;
+            if (this.iceRestartStopped)
+                return;
+            const state = (_a = this.peerConnection) === null || _a === void 0 ? void 0 : _a.iceConnectionState;
+            if (state === 'disconnected' || state === 'failed') {
+                void this.restartIce();
             }
-            this.publicEventEmitter.emit(types_1.AnamEvent.CONNECTION_ESTABLISHED);
-            // Start collecting stats every 5 seconds
-            this.startStatsCollection();
+        }, ICE_DISCONNECTED_GRACE_MS);
+    }
+    /**
+     * Resolve once the signalling WebSocket is open (it auto-reconnects on close),
+     * or reject if it is terminally closed / times out. Restart offers must never
+     * be sent on a dead socket. Timeout + listener are stored so shutdown can clear
+     * them (see clearPendingWsOpenWait).
+     */
+    ensureSignallingConnected() {
+        if (this.signallingClient.isConnected()) {
+            return Promise.resolve();
         }
-        else if (((_f = this.peerConnection) === null || _f === void 0 ? void 0 : _f.iceConnectionState) === 'failed') {
-            (_g = this.connectionMilestones) === null || _g === void 0 ? void 0 : _g.publishFailure({
-                failureStage: 'ice_connection',
-                iceConnectionState: this.peerConnection.iceConnectionState,
-            });
+        if (this.signallingClient.isPermanentlyClosed()) {
+            return Promise.reject(new Error('signalling permanently closed'));
         }
+        return new Promise((resolve, reject) => {
+            this.pendingWsOpenReject = reject;
+            this.pendingWsOpenTimeout = setTimeout(() => {
+                this.clearPendingWsOpenWait();
+                reject(new Error('timed out waiting for signalling WebSocket'));
+            }, ENSURE_WS_OPEN_TIMEOUT_MS);
+            const onOpen = () => {
+                this.clearPendingWsOpenWait();
+                resolve();
+            };
+            this.pendingWsOpenListener = onOpen;
+            this.internalEventEmitter.addListener(types_1.InternalEvent.WEB_SOCKET_OPEN, onOpen);
+        });
+    }
+    /**
+     * Automatic ICE restart. Mints a new offer with fresh ICE credentials and
+     * sends it over the existing channel. Bounded retries via a watchdog; on
+     * exhaustion or terminal signalling, falls back to the WebRTC-failure path.
+     */
+    restartIce() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            if (!this.peerConnection ||
+                this.iceRestartInProgress ||
+                this.iceRestartStopped) {
+                return;
+            }
+            if (this.signallingClient.isPermanentlyClosed()) {
+                // Session is already ending via the signalling layer; stop spinning.
+                this.sendIceRestartMetric('aborted');
+                this.cancelIceRestart();
+                return;
+            }
+            if (this.iceRestartAttempts >= MAX_ICE_RESTART_ATTEMPTS) {
+                console.error('StreamingClient - restartIce: exhausted attempts');
+                (_a = this.connectionMilestones) === null || _a === void 0 ? void 0 : _a.publishFailure({
+                    failureStage: 'ice_connection',
+                    iceConnectionState: (_b = this.peerConnection) === null || _b === void 0 ? void 0 : _b.iceConnectionState,
+                });
+                this.sendIceRestartMetric('exhausted');
+                this.cancelIceRestart();
+                this.handleWebrtcFailure('The connection to our servers was lost. Please try again.');
+                return;
+            }
+            if (this.iceRestartAttempts === 0) {
+                this.iceRestartEpisodeStartMs = performance.now();
+                this.iceRestartEpisodeTrigger = this.peerConnection.iceConnectionState;
+            }
+            // Set the in-progress gate BEFORE any await so a concurrent trigger
+            // (watchdog retry + ICE 'failed' event) cannot start a second restart.
+            this.iceRestartInProgress = true;
+            this.iceRestartAttempts += 1;
+            try {
+                // Avoid offer glare: only start a fresh offer from a stable signalling state.
+                if (this.peerConnection.signalingState !== 'stable') {
+                    yield this.peerConnection.setLocalDescription({ type: 'rollback' });
+                }
+                // On the first attempt of a restart episode, force a fresh signalling
+                // socket. A network switch can leave the old one half-open (readyState
+                // still OPEN, no close event), so the offer would be sent into a dead
+                // socket and never reach the server. Retries (attempt > 1) reuse the
+                // now-live socket so an in-flight answer isn't dropped.
+                if (this.iceRestartAttempts === 1) {
+                    this.signallingClient.reconnectForIceRestart();
+                }
+                yield this.ensureSignallingConnected();
+                if (this.iceRestartStopped)
+                    return;
+                // ICE may have recovered on its own while we waited for signalling.
+                const currentIceState = this.peerConnection.iceConnectionState;
+                if (currentIceState === 'connected' || currentIceState === 'completed') {
+                    this.iceRestartInProgress = false;
+                    // No-ops if the connected handler already closed the episode.
+                    this.sendIceRestartMetric('recovered');
+                    this.signallingClient.endIceRestartReconnect();
+                    return;
+                }
+                this.connectionReceivedAnswer = false;
+                this.remoteIceCandidateBuffer = [];
+                const offer = yield this.peerConnection.createOffer({ iceRestart: true });
+                // Buffer local candidates that gather from setLocalDescription until the
+                // re-offer is sent. The engine queues remote candidates only while it has
+                // no remote description; during a restart it still holds the OLD ICE
+                // credentials, so a candidate arriving before the re-offer is applied would
+                // be added against the old generation and dropped. WS messages are handled
+                // in order, so sending the offer first pins the new credentials server-side.
+                this.iceRestartCandidateBuffer = [];
+                yield this.peerConnection.setLocalDescription(offer);
+                if (!this.peerConnection.localDescription) {
+                    throw new Error('null local description after ICE restart offer');
+                }
+                yield this.signallingClient.sendOffer(this.peerConnection.localDescription);
+                this.flushIceRestartCandidateBuffer();
+                this.iceRestartAwaitedAnswer = false;
+                this.clearIceRestartWatchdog();
+                this.iceRestartWatchdogTimer = setTimeout(() => this.onIceRestartWatchdog(), ICE_RESTART_WATCHDOG_MS);
+            }
+            catch (err) {
+                // The offer never made it out; drop candidates buffered for it (a retry
+                // mints a fresh offer and gathers again).
+                this.iceRestartCandidateBuffer = null;
+                console.error('StreamingClient - restartIce: error', err);
+                this.iceRestartInProgress = false;
+                if (this.iceRestartStopped) {
+                    this.cancelIceRestart();
+                    return;
+                }
+                if (this.signallingClient.isPermanentlyClosed()) {
+                    this.sendIceRestartMetric('aborted');
+                    this.cancelIceRestart();
+                    return; // signalling layer already emitted CONNECTION_CLOSED
+                }
+                this.clearIceRestartWatchdog();
+                this.iceRestartWatchdogTimer = setTimeout(() => {
+                    this.iceRestartWatchdogTimer = null;
+                    void this.restartIce();
+                }, ICE_RESTART_WATCHDOG_MS);
+            }
+        });
+    }
+    // Watchdog for an outstanding restart offer. Only rolls back and re-offers
+    // once the current offer is resolved, so a second offer is never minted while
+    // the first offer's answer is still in flight (the ANSWER handler could
+    // otherwise apply it against the wrong offer).
+    onIceRestartWatchdog() {
+        var _a;
+        this.iceRestartWatchdogTimer = null;
+        this.iceRestartInProgress = false;
+        if (this.iceRestartStopped)
+            return;
+        const state = (_a = this.peerConnection) === null || _a === void 0 ? void 0 : _a.iceConnectionState;
+        if (state === 'connected' || state === 'completed')
+            return;
+        if (!this.connectionReceivedAnswer && !this.iceRestartAwaitedAnswer) {
+            // Offer still unanswered: give the in-flight answer one more cycle before
+            // rolling it back and re-offering.
+            this.iceRestartAwaitedAnswer = true;
+            this.iceRestartInProgress = true;
+            this.iceRestartWatchdogTimer = setTimeout(() => this.onIceRestartWatchdog(), ICE_RESTART_WATCHDOG_MS);
+            return;
+        }
+        void this.restartIce();
     }
     onConnectionStateChange() {
         var _a, _b, _c, _d, _e;
@@ -587,11 +913,21 @@ class StreamingClient {
                 connectionState,
             });
         }
-        if (((_c = this.peerConnection) === null || _c === void 0 ? void 0 : _c.connectionState) === 'failed') {
-            (_d = this.connectionMilestones) === null || _d === void 0 ? void 0 : _d.publishFailure({
-                failureStage: 'webrtc_connection',
-                connectionState: this.peerConnection.connectionState,
-            });
+        if (connectionState === 'failed') {
+            const iceState = (_c = this.peerConnection) === null || _c === void 0 ? void 0 : _c.iceConnectionState;
+            const recovering = !this.iceRestartStopped &&
+                (iceState === 'disconnected' || iceState === 'failed');
+            // A recoverable ICE failure also flips the aggregate state to 'failed'.
+            // The recorder is first-call-wins, so don't finalize failure telemetry
+            // while the ICE restart is still recovering; the terminal publish comes
+            // from restartIce (exhausted) or the 'closed' branch below. A genuine
+            // non-ICE failure (e.g. DTLS with ICE still connected) still publishes.
+            if (!recovering) {
+                (_d = this.connectionMilestones) === null || _d === void 0 ? void 0 : _d.publishFailure({
+                    failureStage: 'webrtc_connection',
+                    connectionState,
+                });
+            }
         }
         if (((_e = this.peerConnection) === null || _e === void 0 ? void 0 : _e.connectionState) === 'closed') {
             console.error('StreamingClient - onConnectionStateChange: Connection closed');
@@ -854,6 +1190,8 @@ class StreamingClient {
     shutdown() {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
+            this.iceRestartStopped = true;
+            this.cancelIceRestart();
             if (this.showPeerConnectionStatsReport) {
                 const stats = yield ((_a = this.peerConnection) === null || _a === void 0 ? void 0 : _a.getStats());
                 if (stats) {