@kaltura-sdk/avatars 1.21.1 → 1.21.3-hotfix.0

package/index.esm.js

@@ -6170,12 +6170,24 @@ const clientConfigurationSchema = z$1.object({
     isWebSearchEnabled: z$1.boolean(),
     isScreenShareEnabled: z$1.boolean(),
     isCameraAnalysisEnabled: z$1.boolean(),
-    youtubeUrl: z$1.string(),
-    audioMode: z$1.boolean(),
-    phoneMode: z$1.boolean(),
     initialHtml: z$1.string(),
     visualPhotos: z$1.array(z$1.unknown()),
-    visualVideos: z$1.array(z$1.unknown())
+    visualVideos: z$1.array(z$1.unknown()),
+    youtubeUrl: z$1.optional(z$1.string()),
+    audioMode: z$1.optional(z$1.boolean()),
+    phoneMode: z$1.optional(z$1.boolean()),
+    forwardLoopMode: z$1.optional(z$1.boolean()),
+    imaginativeAiMode: z$1.optional(z$1.boolean()),
+    interruptionsEnabled: z$1.optional(z$1.boolean()),
+    pauseConversationEnabled: z$1.optional(z$1.boolean()),
+    showTranscription: z$1.optional(z$1.boolean()),
+    shouldAggregateCurrentTurn: z$1.optional(z$1.boolean()),
+    agentPersonaName: z$1.optional(z$1.nullable(z$1.string())),
+    userName: z$1.optional(z$1.nullable(z$1.string())),
+    asr: z$1.optional(z$1.object({
+      provider: z$1.string(),
+      language: z$1.string()
+    }))
   })
 });
 const joinCompleteSchema = z$1.object({});
@@ -23829,6 +23841,11 @@ const avatarConnectionMachine = setup({
 });
 
 const ACTIVE_SESSION_STORE_ID = 'agenticExperienceAvatar';
+const PROBE_STORE_ID = 'agenticExperienceAvatarProbe';
+const HEARTBEAT_INTERVAL_MS = 2000;
+const HEARTBEAT_STALE_AFTER_MS = 6000;
+// A live owner answers within one postMessage round trip; this only has to outlast a busy main thread.
+const PROBE_TIMEOUT_MS = 1000;
 function createId() {
   return typeof crypto !== 'undefined' && crypto.randomUUID ? crypto.randomUUID() : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 }
@@ -23837,18 +23854,29 @@ function createId() {
  * just overwriting the shared record: the previous owner sees an id that is
  * no longer its own and ends its own call (a close callback could not cross
  * frames).
+ *
+ * `pagehide` can't be trusted to release (crashed/frozen tabs, an iframe the
+ * host removes while the avatar is mid-call), so the owner also refreshes
+ * `heartbeatAt` and everyone else ignores a record that stopped refreshing.
+ * `verifyConflictOwner()` shortcuts that wait: a removed iframe can't answer a ping.
  */
 class ActiveSessionCoordinator {
   constructor(_options) {
     this._options = _options;
     this.id = createId();
     this._owns = false;
+    // Heartbeats change every record, so only `id`/`preventDisconnections` count as a change.
     this._conflict = new TinyDataStore({
       initialValue: null,
-      compare: 'deep'
+      compare: (a, b) => (a === null || a === void 0 ? void 0 : a.id) === (b === null || b === void 0 ? void 0 : b.id) && (a === null || a === void 0 ? void 0 : a.preventDisconnections) === (b === null || b === void 0 ? void 0 : b.preventDisconnections)
     });
+    // Owners that failed a probe, keyed to the heartbeat they were last seen with; a newer heartbeat revives them.
+    this._abandoned = new Map();
+    this._pendingProbe = null;
     this._win = window;
     this._onPageHide = () => this.release();
+    this._heartbeatTimer = null;
+    this._expiryTimer = null;
     this._logger = _options.logger;
     this._global = getOrCreateGlobalTinyDataStore({
       id: ACTIVE_SESSION_STORE_ID,
@@ -23856,6 +23884,14 @@ class ActiveSessionCoordinator {
       logger: _options.logger
     });
     this._unsubscribe = this._global.onChanges(value => this._handle(value));
+    this._probe = getOrCreateGlobalTinyDataStore({
+      id: PROBE_STORE_ID,
+      initialValue: null,
+      logger: _options.logger
+    });
+    this._unsubscribeProbe = this._probe.onChanges(probe => this._handleProbe(probe), {
+      replayLastValue: false
+    });
     // A closed iframe must not leave the page locked.
     this._win.addEventListener('pagehide', this._onPageHide);
   }
@@ -23875,25 +23911,57 @@ class ActiveSessionCoordinator {
         preventDisconnections
       }
     });
-    this._global.setData(() => ({
-      id: this.id,
-      preventDisconnections
-    }));
+    this._publish(preventDisconnections);
+    this._startHeartbeat();
   }
   /** Republishes the flag only while this avatar owns the call; never claims an idle one */
   updateFlag(preventDisconnections) {
     var _a, _b;
     if (this._owns && ((_a = this._global.getData()) === null || _a === void 0 ? void 0 : _a.id) === this.id && ((_b = this._global.getData()) === null || _b === void 0 ? void 0 : _b.preventDisconnections) !== preventDisconnections) {
-      this._global.setData(() => ({
-        id: this.id,
-        preventDisconnections
-      }));
+      this._publish(preventDisconnections);
     }
   }
+  /**
+   * Pings the avatar that owns the call. No answer within `PROBE_TIMEOUT_MS`
+   * (removed iframe, crashed tab) marks it abandoned so `conflict` clears
+   * instead of waiting for its heartbeat to go stale.
+   */
+  verifyConflictOwner() {
+    const record = this._global.getData();
+    if (!record || record.id === this.id || this._pendingProbe) {
+      return;
+    }
+    const nonce = createId();
+    const timer = setTimeout(() => {
+      var _a;
+      this._pendingProbe = null;
+      const current = this._global.getData();
+      // A newer heartbeat in the meantime proves the owner is alive.
+      if ((current === null || current === void 0 ? void 0 : current.id) === record.id && current.heartbeatAt === record.heartbeatAt) {
+        (_a = this._logger) === null || _a === void 0 ? void 0 : _a.log('active avatar session owner did not answer, treating it as abandoned', {
+          data: {
+            id: record.id
+          }
+        });
+        this._abandoned.set(record.id, record.heartbeatAt);
+        this._handle(current);
+      }
+    }, PROBE_TIMEOUT_MS);
+    this._pendingProbe = {
+      nonce,
+      timer
+    };
+    this._probe.setData(() => ({
+      nonce,
+      ownerId: record.id,
+      reply: false
+    }));
+  }
   /** Clears the record only if it is still ours, so a taken-over avatar can't wipe the new owner */
   release() {
     var _a, _b;
     this._owns = false;
+    this._stopHeartbeat();
     if (((_a = this._global.getData()) === null || _a === void 0 ? void 0 : _a.id) === this.id) {
       (_b = this._logger) === null || _b === void 0 ? void 0 : _b.log('releasing the active avatar session', {
         data: {
@@ -23906,15 +23974,85 @@ class ActiveSessionCoordinator {
   dispose() {
     this.release();
     this._unsubscribe();
+    this._unsubscribeProbe();
+    this._clearExpiryTimer();
+    this._clearPendingProbe();
     this._win.removeEventListener('pagehide', this._onPageHide);
   }
-  _handle(value) {
+  _publish(preventDisconnections) {
+    this._global.setData(() => ({
+      id: this.id,
+      preventDisconnections,
+      heartbeatAt: Date.now()
+    }));
+  }
+  _startHeartbeat() {
+    if (this._heartbeatTimer) {
+      return;
+    }
+    this._heartbeatTimer = setInterval(() => {
+      const current = this._global.getData();
+      if (this._owns && (current === null || current === void 0 ? void 0 : current.id) === this.id) {
+        this._publish(current.preventDisconnections);
+      }
+    }, HEARTBEAT_INTERVAL_MS);
+  }
+  _stopHeartbeat() {
+    if (this._heartbeatTimer) {
+      clearInterval(this._heartbeatTimer);
+      this._heartbeatTimer = null;
+    }
+  }
+  _clearPendingProbe() {
+    if (this._pendingProbe) {
+      clearTimeout(this._pendingProbe.timer);
+      this._pendingProbe = null;
+    }
+  }
+  _handleProbe(probe) {
     var _a;
-    const other = value && value.id !== this.id ? value : null;
+    if (!probe) {
+      return;
+    }
+    if (!probe.reply && probe.ownerId === this.id && this._owns) {
+      this._probe.setData(() => Object.assign(Object.assign({}, probe), {
+        reply: true
+      }));
+    } else if (probe.reply && probe.nonce === ((_a = this._pendingProbe) === null || _a === void 0 ? void 0 : _a.nonce)) {
+      this._clearPendingProbe();
+    }
+  }
+  _clearExpiryTimer() {
+    if (this._expiryTimer) {
+      clearTimeout(this._expiryTimer);
+      this._expiryTimer = null;
+    }
+  }
+  _handle(value) {
+    var _a, _b, _c;
+    this._clearExpiryTimer();
+    // A record without `heartbeatAt` (older bundle in another frame) never expires.
+    const staleIn = value && typeof value.heartbeatAt === 'number' ? value.heartbeatAt + HEARTBEAT_STALE_AFTER_MS - Date.now() : Infinity;
+    const isAbandoned = !!value && value.heartbeatAt !== undefined && value.heartbeatAt <= ((_a = this._abandoned.get(value.id)) !== null && _a !== void 0 ? _a : -Infinity);
+    const isStale = !!value && (staleIn < 0 || isAbandoned);
+    if (isStale && value.id !== this.id) {
+      (_b = this._logger) === null || _b === void 0 ? void 0 : _b.log('ignoring an abandoned active avatar session', {
+        data: {
+          id: value.id,
+          heartbeatAt: value.heartbeatAt
+        }
+      });
+    }
+    const other = value && value.id !== this.id && !isStale ? value : null;
     this._conflict.setData(() => other);
+    if (other && Number.isFinite(staleIn)) {
+      // Nothing is written when the owner dies, so re-evaluate once its record would go stale.
+      this._expiryTimer = setTimeout(() => this._handle(this._global.getData()), staleIn + 1);
+    }
     if (other && this._owns) {
       this._owns = false;
-      (_a = this._logger) === null || _a === void 0 ? void 0 : _a.log('active avatar session taken over by another avatar', {
+      this._stopHeartbeat();
+      (_c = this._logger) === null || _c === void 0 ? void 0 : _c.log('active avatar session taken over by another avatar', {
         data: {
           id: this.id,
           by: other.id
@@ -24237,6 +24375,19 @@ class AvatarClientManager extends ActorManager {
         preventDisconnections: (_b = (_a = this._config.runtimeSettings.multipleAvatarBehavior) === null || _a === void 0 ? void 0 : _a.preventDisconnections) !== null && _b !== void 0 ? _b : false
       };
     });
+    // The call that held our connect is gone (ended, abandoned): the user already asked to start, so just start.
+    this._activeSession.conflict.onChanges(conflict => {
+      if (conflict || !this._isTakeoverPending.getData()) {
+        return;
+      }
+      const options = this._pendingTakeoverOptions;
+      this._pendingTakeoverOptions = undefined;
+      this._isTakeoverPending.setData(() => false);
+      this._logger.log('Resuming the held connect: the other avatar call is gone');
+      this.connect(options);
+    }, {
+      replayLastValue: false
+    });
     this._status.onChanges(status => {
       if (status === AvatarConnectionStatus.NotConnected || status === AvatarConnectionStatus.Disconnected || status === AvatarConnectionStatus.Error) {
         this._activeSession.release();
@@ -24459,6 +24610,8 @@ class AvatarClientManager extends ActorManager {
       });
       this._pendingTakeoverOptions = options;
       this._isTakeoverPending.setData(() => true);
+      // An owner that is already gone (removed iframe, crashed tab) can't answer, so don't make the user wait out its heartbeat.
+      this._activeSession.verifyConflictOwner();
       return;
     }
     this._activeSession.claim(this._multipleAvatarBehavior.getData().preventDisconnections);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaltura-sdk/avatars",
-  "version": "1.21.1",
+  "version": "1.21.3-hotfix.0",
   "author": "kaltura",
   "license": "AGPL-3.0",
   "repository": {
@@ -12,8 +12,8 @@
     "@kaltura-sdk/rtc-avatar": "^1.33.4",
     "@kaltura-sdk/rtc-core": "^1.26.2",
     "@local/genie-shared-utils": "^1.0.0",
-    "@unisphere/core": "^1.101.1",
-    "@unisphere/genie-types": "^1.47.0",
+    "@unisphere/core": "^1.101.2",
+    "@unisphere/genie-types": "^1.47.1",
     "@unisphere/notifications-core": "^1.25.0",
     "@unisphere/runtime": "^1.98.0",
     "@unisphere/runtime-js": "^1.98.0",

package/src/lib/avatar-client-manager/machines/avatar-connection/types/schemas.d.ts

@@ -14,12 +14,24 @@ export declare const clientConfigurationSchema: z.ZodMiniObject<{
         isWebSearchEnabled: z.ZodMiniBoolean<boolean>;
         isScreenShareEnabled: z.ZodMiniBoolean<boolean>;
         isCameraAnalysisEnabled: z.ZodMiniBoolean<boolean>;
-        youtubeUrl: z.ZodMiniString<string>;
-        audioMode: z.ZodMiniBoolean<boolean>;
-        phoneMode: z.ZodMiniBoolean<boolean>;
         initialHtml: z.ZodMiniString<string>;
         visualPhotos: z.ZodMiniArray<z.ZodMiniUnknown>;
         visualVideos: z.ZodMiniArray<z.ZodMiniUnknown>;
+        youtubeUrl: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        audioMode: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+        phoneMode: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+        forwardLoopMode: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+        imaginativeAiMode: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+        interruptionsEnabled: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+        pauseConversationEnabled: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+        showTranscription: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+        shouldAggregateCurrentTurn: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+        agentPersonaName: z.ZodMiniOptional<z.ZodMiniNullable<z.ZodMiniString<string>>>;
+        userName: z.ZodMiniOptional<z.ZodMiniNullable<z.ZodMiniString<string>>>;
+        asr: z.ZodMiniOptional<z.ZodMiniObject<{
+            provider: z.ZodMiniString<string>;
+            language: z.ZodMiniString<string>;
+        }, z.core.$strip>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export declare const joinCompleteSchema: z.ZodMiniObject<{}, z.core.$strip>;

package/src/lib/avatar-client-manager/utils/active-session-coordinator.d.ts

@@ -1,11 +1,19 @@
 import { UnisphereLoggerType } from '@unisphere/core';
 import type { ActiveAvatarSession } from '@unisphere/genie-types';
 export declare const ACTIVE_SESSION_STORE_ID = "agenticExperienceAvatar";
+export declare const HEARTBEAT_INTERVAL_MS = 2000;
+export declare const HEARTBEAT_STALE_AFTER_MS = 6000;
+export declare const PROBE_TIMEOUT_MS = 1000;
 /**
  * Page-wide "who owns the call" record for one avatar manager. Takeover is
  * just overwriting the shared record: the previous owner sees an id that is
  * no longer its own and ends its own call (a close callback could not cross
  * frames).
+ *
+ * `pagehide` can't be trusted to release (crashed/frozen tabs, an iframe the
+ * host removes while the avatar is mid-call), so the owner also refreshes
+ * `heartbeatAt` and everyone else ignores a record that stopped refreshing.
+ * `verifyConflictOwner()` shortcuts that wait: a removed iframe can't answer a ping.
  */
 export declare class ActiveSessionCoordinator {
     private readonly _options;
@@ -13,10 +21,16 @@ export declare class ActiveSessionCoordinator {
     private _owns;
     private readonly _conflict;
     private readonly _global;
+    private readonly _probe;
     private readonly _unsubscribe;
+    private readonly _unsubscribeProbe;
+    private readonly _abandoned;
+    private _pendingProbe;
     private readonly _win;
     private readonly _onPageHide;
     private readonly _logger?;
+    private _heartbeatTimer;
+    private _expiryTimer;
     constructor(_options: {
         onTakenOver: () => void;
         logger?: UnisphereLoggerType;
@@ -26,8 +40,20 @@ export declare class ActiveSessionCoordinator {
     claim(preventDisconnections: boolean): void;
     /** Republishes the flag only while this avatar owns the call; never claims an idle one */
     updateFlag(preventDisconnections: boolean): void;
+    /**
+     * Pings the avatar that owns the call. No answer within `PROBE_TIMEOUT_MS`
+     * (removed iframe, crashed tab) marks it abandoned so `conflict` clears
+     * instead of waiting for its heartbeat to go stale.
+     */
+    verifyConflictOwner(): void;
     /** Clears the record only if it is still ours, so a taken-over avatar can't wipe the new owner */
     release(): void;
     dispose(): void;
+    private _publish;
+    private _startHeartbeat;
+    private _stopHeartbeat;
+    private _clearPendingProbe;
+    private _handleProbe;
+    private _clearExpiryTimer;
     private _handle;
 }