@kaltura-sdk/avatars 1.19.0 → 1.21.0

package/README.md

@@ -34,7 +34,7 @@ manager.stop(); // full teardown, unsubscribes everything
 - **Pause/resume**: `pause()`, `resume()`, `pauseAfterSpeaking()`, `isPaused`
 - **Chat & content**: `askViaText()`, `chatLog`, `content`, `setLocalContent()`, `clearContent()`, `agentData`
 - **Screen share**: `startScreenShare()`, `stopScreenShare()`, `screenShareInfo`
-- **Tap-to-talk**: `tapToTalkStart(options?)` (`options.enrichAudio` asks the server to analyze the recording), `tapToTalkEnd()`, `toggleTapToTalkMode()`, `tapToTalkInfo`
+- **Tap-to-talk**: `tapToTalkStart(options?)` (`options.enrichAudio` asks the server to analyze the recording; `options.referenceText` is the text being read, sent with `enrichAudio`), `tapToTalkEnd()`, `toggleTapToTalkMode()`, `tapToTalkInfo`
 - **Captions**: `captions` (state + `toggle`/`setReplacements`/`setFilter`)
 - **Kaltura context**: `kalturaContext`, `toggleKalturaContext()`, `updateDynamicVariables()`
 - **Client tools**: `registerClientTools()`, `unregisterClientTools()`, `registeredClientTools`, `clientToolCallLog`

package/index.esm.js

@@ -1,4 +1,4 @@
-import { UnisphereLoggerFactory, TinyDataStore, TinyPubSub, performanceMonitor } from '@unisphere/core';
+import { UnisphereLoggerFactory, TinyDataStore, TinyPubSub, performanceMonitor, getOrCreateGlobalUnisphere } from '@unisphere/core';
 import { getPartnerIdFromKs } from '@unisphere/runtime-js';
 import { DisconnectReasons, getAvatarDefaultCapabilities, resolveActiveContextType, AvatarConnectionStatus } from '@unisphere/genie-types';
 import { z as z$1 } from 'zod/mini';
@@ -1920,6 +1920,18 @@ PERFORMANCE OF THIS SOFTWARE.
 /* global Reflect, Promise, SuppressedError, Symbol, Iterator */
 
 
+function __rest(s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+}
+
 function __awaiter(thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -23112,14 +23124,20 @@ const sendTapToTalkStart = ({
   if (!client) {
     throw new Error('WebSocket client not found');
   }
-  const enrichAudio = (_a = event.options) === null || _a === void 0 ? void 0 : _a.enrichAudio;
+  const {
+    enrichAudio,
+    referenceText
+  } = (_a = event.options) !== null && _a !== void 0 ? _a : {};
   // No payload without options keeps the event identical for servers that predate the flag
   if (enrichAudio === undefined) {
     client.emit('tapToTalkStart');
     return;
   }
-  client.emit('tapToTalkStart', {
+  client.emit('tapToTalkStart', referenceText === undefined ? {
     enrichAudio
+  } : {
+    enrichAudio,
+    referenceText
   });
 };
 
@@ -23822,6 +23840,343 @@ const avatarConnectionMachine = setup({
   }
 });
 
+const NAMESPACE = 'unisphere-global-tiny-data-store';
+const REGISTRY_KEY = 'globalTinyDataStore';
+function getRegistry(logger) {
+  return getOrCreateGlobalUnisphere(REGISTRY_KEY, logger, {
+    windowId: `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`,
+    // null prototype: ids come off the wire, `__proto__`/`constructor` must be plain keys
+    entries: Object.create(null),
+    listening: false,
+    lastTs: 0
+  }).value;
+}
+// `length`/`frames` are readable cross-origin, so this reaches every frame
+// regardless of nesting depth or origin; we can't know which one holds an avatar.
+function collectWindows(root) {
+  const result = [];
+  const visit = w => {
+    result.push(w);
+    let count = 0;
+    try {
+      count = w.length;
+    } catch (_a) {
+      return;
+    }
+    for (let i = 0; i < count; i++) {
+      try {
+        visit(w.frames[i]);
+      } catch (_b) {
+        // frame navigated away or became inaccessible while enumerating
+      }
+    }
+  };
+  visit(root);
+  return result;
+}
+// Cache frames seen by this window so a `pagehide` message dispatched by an iframe
+// just before removal is still recognized even after `contentWindow` detaches from the DOM.
+const knownFrames = new WeakSet();
+function getPageWindows(win) {
+  var _a;
+  const current = collectWindows((_a = win.top) !== null && _a !== void 0 ? _a : win);
+  for (const w of current) {
+    knownFrames.add(w);
+  }
+  return current;
+}
+function isKnownPageWindow(win, source) {
+  if (getPageWindows(win).includes(source)) {
+    return true;
+  }
+  return knownFrames.has(source);
+}
+function post(target, message) {
+  try {
+    // '*' because the host topology (and origins) are unknown. The payload is
+    // non-sensitive and receivers only accept messages from this page's frames.
+    target.postMessage(message, '*');
+  } catch (_a) {
+    // target is gone
+  }
+}
+function broadcast(win, message) {
+  for (const target of getPageWindows(win)) {
+    if (target !== win) {
+      post(target, message);
+    }
+  }
+}
+function compareRevisions(a, b) {
+  if (a.ts !== b.ts) {
+    return a.ts - b.ts;
+  }
+  return a.origin < b.origin ? -1 : a.origin > b.origin ? 1 : 0;
+}
+function isRevision(rev) {
+  return !!rev && typeof rev.ts === 'number' && typeof rev.origin === 'string';
+}
+function handleMessage(win, registry, logger, event) {
+  const data = event.data;
+  if (!data || data.ns !== NAMESPACE || typeof data.id !== 'string') {
+    return;
+  }
+  const source = event.source;
+  if (!source || source === win || !isKnownPageWindow(win, source)) {
+    logger.debug('ignored message from a window outside this page', {
+      data: {
+        id: data.id,
+        kind: data.kind
+      }
+    });
+    return;
+  }
+  const entry = registry.entries[data.id];
+  if (data.kind === 'request-sync') {
+    if (entry === null || entry === void 0 ? void 0 : entry.rev) {
+      logger.debug('answering sync request', {
+        data: {
+          id: data.id
+        }
+      });
+      post(source, {
+        ns: NAMESPACE,
+        from: registry.windowId,
+        kind: 'update',
+        id: data.id,
+        value: entry.store.getData(),
+        rev: entry.rev
+      });
+    }
+    return;
+  }
+  if (data.kind !== 'update' || !isRevision(data.rev)) {
+    return;
+  }
+  // Lamport-style: a write made after observing this one must sort after it,
+  // even within the same millisecond.
+  registry.lastTs = Math.max(registry.lastTs, data.rev.ts);
+  if (!entry) {
+    logger.debug('stored update for an id nobody here listens to yet', {
+      data: {
+        id: data.id,
+        rev: data.rev
+      }
+    });
+    registry.entries[data.id] = {
+      store: new TinyDataStore({
+        initialValue: data.value,
+        compare: 'deep'
+      }),
+      rev: data.rev
+    };
+    return;
+  }
+  // Equal/older revisions are what stops echoes between frames.
+  if (entry.rev && compareRevisions(data.rev, entry.rev) <= 0) {
+    logger.debug('dropped stale or duplicate update', {
+      data: {
+        id: data.id,
+        rev: data.rev
+      }
+    });
+    return;
+  }
+  logger.debug('applied update from another frame', {
+    data: {
+      id: data.id,
+      value: data.value,
+      rev: data.rev
+    }
+  });
+  entry.rev = data.rev;
+  entry.store.setData(() => data.value);
+}
+// The listener is installed once per window by whichever bundle listens first,
+// so it keeps that bundle's logger.
+function ensureListener(win, registry, logger) {
+  if (registry.listening) {
+    return;
+  }
+  registry.listening = true;
+  win.addEventListener('message', event => handleMessage(win, registry, logger, event));
+}
+/**
+ * A `TinyDataStore` shared by id between every workspace in this window and,
+ * via `postMessage`, every other frame on the page (parent, siblings, nested).
+ * Last write wins (timestamp, then window id as tie-break).
+ */
+function listenToGlobalTinyDataStore({
+  id,
+  initialValue,
+  onChanges,
+  logger = avatarClientLoggerFactory.getOrCreateLogger('service', 'global-tiny-data-store')
+}) {
+  const win = window;
+  const registry = getRegistry(logger);
+  ensureListener(win, registry, logger);
+  let entry = registry.entries[id];
+  const isNew = !entry;
+  if (!entry) {
+    entry = registry.entries[id] = {
+      store: new TinyDataStore({
+        initialValue,
+        compare: 'deep'
+      }),
+      rev: null
+    };
+  }
+  const store = entry.store;
+  const unsubscribe = store.onChanges(onChanges, {
+    replayLastValue: false
+  });
+  logger.debug('listening to global store', {
+    data: {
+      id,
+      isNew
+    }
+  });
+  if (isNew) {
+    broadcast(win, {
+      ns: NAMESPACE,
+      from: registry.windowId,
+      kind: 'request-sync',
+      id
+    });
+  }
+  return {
+    unsubscribe,
+    getData: () => store.getData(),
+    setData: value => {
+      const rev = {
+        ts: registry.lastTs = Math.max(Date.now(), registry.lastTs + 1),
+        origin: registry.windowId
+      };
+      logger.debug('updating global store', {
+        data: {
+          id,
+          value,
+          rev
+        }
+      });
+      entry.rev = rev;
+      store.setData(() => value);
+      broadcast(win, {
+        ns: NAMESPACE,
+        from: registry.windowId,
+        kind: 'update',
+        id,
+        value,
+        rev
+      });
+    }
+  };
+}
+
+const ACTIVE_SESSION_STORE_ID = 'agenticExperienceAvatar';
+function createId() {
+  return typeof crypto !== 'undefined' && crypto.randomUUID ? crypto.randomUUID() : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+/**
+ * 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).
+ */
+class ActiveSessionCoordinator {
+  constructor(_options) {
+    this._options = _options;
+    this.id = createId();
+    this._owns = false;
+    this._conflict = new TinyDataStore({
+      initialValue: null,
+      compare: 'deep'
+    });
+    this._win = window;
+    this._onPageHide = () => this.release();
+    const _a = listenToGlobalTinyDataStore({
+        id: ACTIVE_SESSION_STORE_ID,
+        initialValue: null,
+        onChanges: value => this._handle(value),
+        logger: _options.logger
+      }),
+      {
+        unsubscribe
+      } = _a,
+      global = __rest(_a, ["unsubscribe"]);
+    this._logger = _options.logger;
+    this._global = global;
+    this._unsubscribe = unsubscribe;
+    this._handle(global.getData());
+    // A closed iframe must not leave the page locked.
+    this._win.addEventListener('pagehide', this._onPageHide);
+  }
+  /** The active session owned by another avatar, or null */
+  get conflict() {
+    return this._conflict.consumer;
+  }
+  claim(preventDisconnections) {
+    var _a, _b;
+    if (this._owns && ((_a = this._global.getData()) === null || _a === void 0 ? void 0 : _a.preventDisconnections) === preventDisconnections) {
+      return;
+    }
+    this._owns = true;
+    (_b = this._logger) === null || _b === void 0 ? void 0 : _b.log('claiming the active avatar session', {
+      data: {
+        id: this.id,
+        preventDisconnections
+      }
+    });
+    this._global.setData({
+      id: this.id,
+      preventDisconnections
+    });
+  }
+  /** 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
+      });
+    }
+  }
+  /** 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;
+    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: {
+          id: this.id
+        }
+      });
+      this._global.setData(null);
+    }
+  }
+  dispose() {
+    this.release();
+    this._unsubscribe();
+    this._win.removeEventListener('pagehide', this._onPageHide);
+  }
+  _handle(value) {
+    var _a;
+    const other = value && value.id !== this.id ? value : null;
+    this._conflict.setData(() => other);
+    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', {
+        data: {
+          id: this.id,
+          by: other.id
+        }
+      });
+      this._options.onTakenOver();
+    }
+  }
+}
+
 function setIfChanged(store, next, eq = (a, b) => a === b) {
   if (!eq(store.getData(), next)) {
     store.setData(() => next);
@@ -24102,7 +24457,20 @@ class AvatarClientManager extends ActorManager {
     this._contextSelectorVisible = new TinyDataStore({
       initialValue: true
     });
+    this._multipleAvatarBehavior = new TinyDataStore({
+      initialValue: {
+        preventDisconnections: false
+      },
+      compare: 'deep'
+    });
+    this._isTakeoverPending = new TinyDataStore({
+      initialValue: false
+    });
     this._logger = (_a = this._config.logger) !== null && _a !== void 0 ? _a : avatarClientLoggerFactory.getOrCreateLogger('service', 'avatar-client');
+    this._activeSession = new ActiveSessionCoordinator({
+      onTakenOver: () => this.disconnect(),
+      logger: this._logger
+    });
     if (this._config.runtimeSettings.features) {
       this._features.setData(() => this._config.runtimeSettings.features);
     }
@@ -24115,6 +24483,19 @@ class AvatarClientManager extends ActorManager {
       return this._config.runtimeSettings.serverConfig === 'manual' ? (_a = this._config.runtimeSettings.loadingVideoURL) !== null && _a !== void 0 ? _a : null : null;
     });
     this._setupKalturaContext();
+    this._multipleAvatarBehavior.setData(() => {
+      var _a, _b;
+      return {
+        preventDisconnections: (_b = (_a = this._config.runtimeSettings.multipleAvatarBehavior) === null || _a === void 0 ? void 0 : _a.preventDisconnections) !== null && _b !== void 0 ? _b : false
+      };
+    });
+    this._status.onChanges(status => {
+      if (status === AvatarConnectionStatus.NotConnected || status === AvatarConnectionStatus.Disconnected || status === AvatarConnectionStatus.Error) {
+        this._activeSession.release();
+      }
+    }, {
+      replayLastValue: false
+    });
   }
   // ────────────────────────────────────────────────────────────────────────
   // Private: connection engine
@@ -24321,6 +24702,18 @@ class AvatarClientManager extends ActorManager {
       this._logger.log(`Avatar client already connected`);
       return;
     }
+    const conflict = this._activeSession.conflict.getData();
+    if (conflict) {
+      this._logger.log('Connect pending: another avatar is in a call', {
+        data: {
+          preventDisconnections: conflict.preventDisconnections
+        }
+      });
+      this._pendingTakeoverOptions = options;
+      this._isTakeoverPending.setData(() => true);
+      return;
+    }
+    this._activeSession.claim(this._multipleAvatarBehavior.getData().preventDisconnections);
     const connectionId = 'main';
     this._logger.log(`Connecting to avatar client with connection ID: ${connectionId}`);
     timingTracker.runtimeConnectTime = performance.now();
@@ -24376,6 +24769,22 @@ class AvatarClientManager extends ActorManager {
   reconnect() {
     this.connect(this._lastConnectOptions);
   }
+  confirmTakeover() {
+    var _a;
+    if (!this._isTakeoverPending.getData() || ((_a = this._activeSession.conflict.getData()) === null || _a === void 0 ? void 0 : _a.preventDisconnections)) {
+      return;
+    }
+    const options = this._pendingTakeoverOptions;
+    this._pendingTakeoverOptions = undefined;
+    this._isTakeoverPending.setData(() => false);
+    // Overwriting the page-wide record makes the other avatar end its own call.
+    this._activeSession.claim(this._multipleAvatarBehavior.getData().preventDisconnections);
+    this.connect(options);
+  }
+  cancelTakeover() {
+    this._pendingTakeoverOptions = undefined;
+    this._isTakeoverPending.setData(() => false);
+  }
   // ────────────────────────────────────────────────────────────────────────
   // Public API: pause / resume
   // ────────────────────────────────────────────────────────────────────────
@@ -24578,6 +24987,23 @@ class AvatarClientManager extends ActorManager {
   setIsPreviewMode(value) {
     this._isPreviewMode.setData(() => value);
   }
+  get multipleAvatarBehavior() {
+    return this._multipleAvatarBehavior.consumer;
+  }
+  setMultipleAvatarBehavior(value) {
+    var _a;
+    const preventDisconnections = (_a = value === null || value === void 0 ? void 0 : value.preventDisconnections) !== null && _a !== void 0 ? _a : false;
+    this._multipleAvatarBehavior.setData(() => ({
+      preventDisconnections
+    }));
+    this._activeSession.updateFlag(preventDisconnections);
+  }
+  get activeSessionConflict() {
+    return this._activeSession.conflict;
+  }
+  get isTakeoverPending() {
+    return this._isTakeoverPending.consumer;
+  }
   get contextSelectorVisible() {
     return this._contextSelectorVisible.consumer;
   }
@@ -24655,8 +25081,9 @@ class AvatarClientManager extends ActorManager {
     var _a;
     (_a = this._unsubscribeContextActive) === null || _a === void 0 ? void 0 : _a.call(this);
     this._unsubscribeContextActive = null;
+    this._activeSession.dispose();
     this._cleanupConnection();
   }
 }
 
-export { ApplicationFeatures, AvatarClientManager, AvatarConnectionMachineEventTypes, AvatarConnectionMachineId, AvatarNotificationCode, ButtonNames, PageNames, agentRawTextClientToolDeltaSchema, agentRawTextDeltaSchema, agentRawTextSchema, agentTurnToTalkSchema, askPermissionsSchema, avatarClientLoggerFactory, avatarConnectionMachine, avatarRTCClientManager, clientConfigurationSchema, conversationEndedSchema, conversationTimeWarningSchema, createTinyPubsubEventsHandler, createTinyPubsubEventsSource, generatingSpeechSchema, getAvatarDisconnectNotificationVariant, getQueryParam, initializeLogsCollectionIfNeeded, isMappedAvatarDisconnectReason, isMobileDevice, joinCompleteSchema, noAgentSchema, onServerConnectedSchema, pauseExpiryWarningSchema, resetWebsocketClientTeardownState, showAgentSchema, showStartSpeechSchema, stvFinishedTalkingSchema, stvNewSessionSchema, stvSpeechChunkSchema, stvStartedTalkingSchema, timingTracker, unsupportedClientSchema, websocketClientManager, websocketDebugInfo, websocketMessage, websocketNonRecoveredReconnect, websocketRecoveryState, websocketSystemMessage };
+export { ApplicationFeatures, AvatarClientManager, AvatarConnectionMachineEventTypes, AvatarConnectionMachineId, AvatarNotificationCode, ButtonNames, PageNames, agentRawTextClientToolDeltaSchema, agentRawTextDeltaSchema, agentRawTextSchema, agentTurnToTalkSchema, askPermissionsSchema, avatarClientLoggerFactory, avatarConnectionMachine, avatarRTCClientManager, clientConfigurationSchema, conversationEndedSchema, conversationTimeWarningSchema, createTinyPubsubEventsHandler, createTinyPubsubEventsSource, generatingSpeechSchema, getAvatarDisconnectNotificationVariant, getQueryParam, initializeLogsCollectionIfNeeded, isMappedAvatarDisconnectReason, isMobileDevice, joinCompleteSchema, listenToGlobalTinyDataStore, noAgentSchema, onServerConnectedSchema, pauseExpiryWarningSchema, resetWebsocketClientTeardownState, showAgentSchema, showStartSpeechSchema, stvFinishedTalkingSchema, stvNewSessionSchema, stvSpeechChunkSchema, stvStartedTalkingSchema, timingTracker, unsupportedClientSchema, websocketClientManager, websocketDebugInfo, websocketMessage, websocketNonRecoveredReconnect, websocketRecoveryState, websocketSystemMessage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaltura-sdk/avatars",
-  "version": "1.19.0",
+  "version": "1.21.0",
   "author": "kaltura",
   "license": "AGPL-3.0",
   "repository": {
@@ -13,13 +13,14 @@
     "@kaltura-sdk/rtc-core": "^1.26.2",
     "@local/genie-shared-utils": "^1.0.0",
     "@unisphere/core": "^1.99.0",
-    "@unisphere/genie-types": "^1.44.0",
+    "@unisphere/genie-types": "^1.47.0",
     "@unisphere/notifications-core": "^1.25.0",
     "@unisphere/runtime": "^1.98.0",
     "@unisphere/runtime-js": "^1.98.0",
     "immer": "^10.1.1",
     "js-yaml": "^4.1.0",
     "socket.io-client": "^4.8.1",
+    "vitest": "^3.2.7",
     "zod": "^4.2.0"
   },
   "module": "./index.esm.js",

package/src/index.d.ts

@@ -1,5 +1,6 @@
 export * from './lib/avatar-client-manager';
 export * from './lib/server';
+export * from './lib/global-tiny-data-store';
 export * from './lib/timing-tracker';
 export * from './lib/analytics';
 export * from './lib/utils';

package/src/lib/avatar-client-manager/avatar-client-manager.d.ts

@@ -1,6 +1,6 @@
 import { UnisphereLoggerType } from '@unisphere/core';
 import { KalturaAnalyticsServiceType, PubSubServiceType } from '@unisphere/runtime';
-import { AgentData, AgentKalturaContextData, AgentProgressBar, AgentScreenShareInfo, AgentTapToTalkInfo, AvatarClientManagerType, AvatarConnectionProxInternalType, AvatarConnectionProxyType, AvatarConnectionStatus, AvatarContentData, AvatarRuntimeSettings, CaptionConfig, Captions, ChatEntry, ClientToolCallLogEntry, DisconnectReasons, TapToTalkStartOptions } from '@unisphere/genie-types';
+import { AgentData, AgentKalturaContextData, AgentProgressBar, AgentScreenShareInfo, AgentTapToTalkInfo, AvatarClientManagerType, AvatarConnectionProxInternalType, AvatarConnectionProxyType, AvatarConnectionStatus, AvatarContentData, AvatarRuntimeSettings, CaptionConfig, Captions, ChatEntry, ClientToolCallLogEntry, DisconnectReasons, MultipleAvatarBehavior, TapToTalkStartOptions } from '@unisphere/genie-types';
 import { type AvatarClientToolsInput, type AvatarConnectionActor } from './machines/avatar-connection';
 import { AvatarClientManagerActions } from './types';
 import { DeviceType } from '@kaltura-sdk/rtc-core';
@@ -58,6 +58,10 @@ export declare class AvatarClientManager extends ActorManager<AvatarConnectionAc
     private _features;
     private readonly _isPreviewMode;
     private readonly _contextSelectorVisible;
+    private readonly _multipleAvatarBehavior;
+    private readonly _isTakeoverPending;
+    private _pendingTakeoverOptions;
+    private readonly _activeSession;
     constructor(_config: {
         actions?: AvatarClientManagerActions;
         debugMode?: boolean;
@@ -113,6 +117,8 @@ export declare class AvatarClientManager extends ActorManager<AvatarConnectionAc
     }): void;
     disconnect(): void;
     reconnect(): void;
+    confirmTakeover(): void;
+    cancelTakeover(): void;
     get isPaused(): import("@unisphere/core").TinyDataStoreConsumer<boolean>;
     pause(): void;
     resume(): void;
@@ -149,6 +155,10 @@ export declare class AvatarClientManager extends ActorManager<AvatarConnectionAc
     setExternalThreadId(id: string | null): void;
     get isPreviewMode(): import("@unisphere/core").TinyDataStoreConsumer<boolean>;
     setIsPreviewMode(value: boolean): void;
+    get multipleAvatarBehavior(): import("@unisphere/core").TinyDataStoreConsumer<MultipleAvatarBehavior>;
+    setMultipleAvatarBehavior(value: MultipleAvatarBehavior | undefined): void;
+    get activeSessionConflict(): import("@unisphere/core").TinyDataStoreConsumer<import("@unisphere/genie-types").ActiveAvatarSession | null>;
+    get isTakeoverPending(): import("@unisphere/core").TinyDataStoreConsumer<boolean>;
     get contextSelectorVisible(): import("@unisphere/core").TinyDataStoreConsumer<boolean>;
     setContextSelectorVisible(value: boolean): void;
     get features(): import("@unisphere/core").TinyDataStoreConsumer<{

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

@@ -0,0 +1,33 @@
+import { UnisphereLoggerType } from '@unisphere/core';
+import type { ActiveAvatarSession } from '@unisphere/genie-types';
+export declare const ACTIVE_SESSION_STORE_ID = "agenticExperienceAvatar";
+/**
+ * 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).
+ */
+export declare class ActiveSessionCoordinator {
+    private readonly _options;
+    readonly id: string;
+    private _owns;
+    private readonly _conflict;
+    private readonly _global;
+    private readonly _unsubscribe;
+    private readonly _win;
+    private readonly _onPageHide;
+    private readonly _logger?;
+    constructor(_options: {
+        onTakenOver: () => void;
+        logger?: UnisphereLoggerType;
+    });
+    /** The active session owned by another avatar, or null */
+    get conflict(): import("@unisphere/core").TinyDataStoreConsumer<ActiveAvatarSession | null>;
+    claim(preventDisconnections: boolean): void;
+    /** Republishes the flag only while this avatar owns the call; never claims an idle one */
+    updateFlag(preventDisconnections: boolean): 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 _handle;
+}

package/src/lib/global-tiny-data-store/index.d.ts

@@ -0,0 +1 @@
+export * from './listen-to-global-tiny-data-store';

package/src/lib/global-tiny-data-store/listen-to-global-tiny-data-store.d.ts

@@ -0,0 +1,16 @@
+import { UnisphereLoggerType } from '@unisphere/core';
+/**
+ * A `TinyDataStore` shared by id between every workspace in this window and,
+ * via `postMessage`, every other frame on the page (parent, siblings, nested).
+ * Last write wins (timestamp, then window id as tie-break).
+ */
+export declare function listenToGlobalTinyDataStore<T>({ id, initialValue, onChanges, logger, }: {
+    id: string;
+    initialValue: T;
+    onChanges: (value: T) => void;
+    logger?: UnisphereLoggerType;
+}): {
+    unsubscribe: () => void;
+    getData: () => T;
+    setData: (value: T) => void;
+};

package/src/lib/test-utils/create-frame-api.d.ts

@@ -0,0 +1,17 @@
+import type { ActiveSessionCoordinator } from '../avatar-client-manager/utils/active-session-coordinator';
+import type { listenToGlobalTinyDataStore } from '../global-tiny-data-store';
+type CoordinatorOptions = ConstructorParameters<typeof ActiveSessionCoordinator>[0];
+export declare function getRealTopWindow(): Window;
+export declare function addFrame(parent: Window): Window;
+export declare function installBrowserLikePostMessage(windows: Window[]): void;
+export declare function createFrameApi(win: Window): Promise<{
+    listen: (options: Parameters<typeof listenToGlobalTinyDataStore>[0]) => {
+        unsubscribe: () => void;
+        getData: () => unknown;
+        setData: (value: unknown) => void;
+    };
+    createCoordinator: (options: CoordinatorOptions) => ActiveSessionCoordinator;
+    cleanup: () => void;
+}>;
+export declare const flush: () => Promise<unknown>;
+export {};