@webex/internal-plugin-voicea 3.12.0-llmrefactor.7 → 3.12.0-llmrefactor.9

package/dist/types/voicea-plugin.d.ts

@@ -9,15 +9,15 @@ import { VoiceaChannel } from './voicea';
 export declare class VoiceaPlugin extends WebexPlugin {
     namespace: string;
     /**
-     * Creates a VoiceaChannel bound to the given LLMChannel.
+     * Creates a VoiceaChannel, optionally bound to an LLMChannel.
      *
      * Note: VoiceaChannel does not take ownership of the LLMChannel.
      * The caller retains ownership and is responsible for the LLMChannel's
      * lifecycle (connection, disconnection, cleanup).
      *
-     * @param {LLMChannel} llmChannel - The LLM channel to use for voicea
+     * @param {LLMChannel} [llmChannel] - The LLM channel to use for voicea (optional)
      * @returns {VoiceaChannel} A new VoiceaChannel instance
      */
-    createChannel(llmChannel: LLMChannel): VoiceaChannel;
+    createChannel(llmChannel?: LLMChannel): VoiceaChannel;
 }
 export default VoiceaPlugin;

package/dist/types/voicea.d.ts

@@ -11,7 +11,7 @@ import { IVoiceaChannel } from './voicea.types';
  */
 export declare class VoiceaChannel extends EventEmitter implements IVoiceaChannel {
     private request;
-    private llmChannel;
+    private llmChannel?;
     private seqNum;
     private areCaptionsEnabled;
     private hasSubscribedToEvents;
@@ -23,16 +23,27 @@ export declare class VoiceaChannel extends EventEmitter implements IVoiceaChanne
     private currentSpokenLanguage?;
     private spokenLanguages;
     private currentCaptionLanguage?;
+    private targetLLMChannel?;
+    private _pendingOnlineListener?;
+    private _pendingCaptionRestore;
     /**
-     * Creates a VoiceaChannel bound to the given LLMChannel
-     * @param {LLMChannel} llmChannel - The LLM channel to use
+     * Creates a VoiceaChannel, optionally bound to an LLMChannel.
+     * If no llmChannel is provided, call switchLLMChannel() later to attach one.
+     * @param {LLMChannel} [llmChannel] - The LLM channel to use (optional)
      * @param {Function} request - The request function for making API calls (typically webex.request bound to webex)
      */
-    constructor(llmChannel: LLMChannel, request: (options: {
+    constructor(llmChannel: LLMChannel | undefined, request: (options: {
         method: string;
         url: string;
         body?: object;
     }) => Promise<any>);
+    /**
+     * Returns the LLM channel, throwing if not available.
+     * @private
+     * @returns {LLMChannel}
+     * @throws {Error} If LLM channel is not available
+     */
+    private requireLLMChannel;
     /**
      * Process events from LLM channel
      * @param {Object} e - Event data
@@ -44,12 +55,39 @@ export declare class VoiceaChannel extends EventEmitter implements IVoiceaChanne
      * @returns {void}
      */
     deregisterEvents(): void;
+    /**
+     * Attach a pending 'online' listener to a channel for deferred reconciliation.
+     * Detaches any existing listener first.
+     * @param {LLMChannel} channel - The channel to attach to
+     * @param {Function} callback - The callback to run when 'online' fires
+     * @private
+     * @returns {void}
+     */
+    private attachPendingOnline;
+    /**
+     * Detach any pending 'online' listener.
+     * @private
+     * @returns {void}
+     */
+    private detachPendingOnline;
+    /**
+     * Reset announcement state for a new connection.
+     * @private
+     * @returns {void}
+     */
+    private resetAnnounceState;
+    /**
+     * Reconcile voicea binding and caption state to match the desired target.
+     * This is idempotent - always re-reads targetLLMChannel and current state.
+     * A deferred 'online' callback that fires late self-corrects automatically.
+     * @private
+     * @returns {Promise<void>}
+     */
+    private reconcile;
     /**
      * Switch to a different LLM channel while preserving caption state.
      * Used when transitioning between main meeting and practice session.
-     * - Preserves keepTranscriptionSubscribed and spokenLanguage state
-     * - Unsubscribes from old channel, subscribes to new channel
-     * - Re-announces and re-enables captions if they were on
+     * This is a thin intent-setter - actual binding happens in reconcile().
      * @param {LLMChannel} newLLMChannel - The new LLM channel to switch to
      * @returns {Promise<void>}
      */

package/dist/voicea-plugin.js

@@ -39,13 +39,13 @@ var VoiceaPlugin = exports.VoiceaPlugin = /*#__PURE__*/function (_WebexPlugin) {
     key: "createChannel",
     value:
     /**
-     * Creates a VoiceaChannel bound to the given LLMChannel.
+     * Creates a VoiceaChannel, optionally bound to an LLMChannel.
      *
      * Note: VoiceaChannel does not take ownership of the LLMChannel.
      * The caller retains ownership and is responsible for the LLMChannel's
      * lifecycle (connection, disconnection, cleanup).
      *
-     * @param {LLMChannel} llmChannel - The LLM channel to use for voicea
+     * @param {LLMChannel} [llmChannel] - The LLM channel to use for voicea (optional)
      * @returns {VoiceaChannel} A new VoiceaChannel instance
      */
     function createChannel(llmChannel) {

package/dist/voicea-plugin.js.map

@@ -1 +1 @@
-{"version":3,"names":["_webexCore","require","_voicea","_constants","_callSuper","t","o","e","_getPrototypeOf2","default","_possibleConstructorReturn2","_isNativeReflectConstruct","_Reflect$construct","constructor","apply","Boolean","prototype","valueOf","call","VoiceaPlugin","exports","_WebexPlugin","_this","_classCallCheck2","_len","arguments","length","args","Array","_key","concat","_defineProperty2","VOICEA","_inherits2","_createClass2","key","value","createChannel","llmChannel","channel","VoiceaChannel","webex","request","bind","WebexPlugin","_default"],"sources":["voicea-plugin.ts"],"sourcesContent":["import {WebexPlugin} from '@webex/webex-core';\nimport type LLMChannel from '@webex/internal-plugin-llm';\n\nimport {VoiceaChannel} from './voicea';\nimport {VOICEA} from './constants';\n\n/**\n * VoiceaPlugin - factory for creating VoiceaChannel instances\n * @export\n * @class VoiceaPlugin\n */\nexport class VoiceaPlugin extends WebexPlugin {\n  namespace = VOICEA;\n\n  /**\n   * Creates a VoiceaChannel bound to the given LLMChannel.\n   *\n   * Note: VoiceaChannel does not take ownership of the LLMChannel.\n   * The caller retains ownership and is responsible for the LLMChannel's\n   * lifecycle (connection, disconnection, cleanup).\n   *\n   * @param {LLMChannel} llmChannel - The LLM channel to use for voicea\n   * @returns {VoiceaChannel} A new VoiceaChannel instance\n   */\n  public createChannel(llmChannel: LLMChannel): VoiceaChannel {\n    // @ts-ignore - webex is available on WebexPlugin\n    const channel = new VoiceaChannel(llmChannel, this.webex.request.bind(this.webex));\n\n    return channel;\n  }\n}\n\nexport default VoiceaPlugin;\n"],"mappings":";;;;;;;;;;;;;;;AAAA,IAAAA,UAAA,GAAAC,OAAA;AAGA,IAAAC,OAAA,GAAAD,OAAA;AACA,IAAAE,UAAA,GAAAF,OAAA;AAAmC,SAAAG,WAAAC,CAAA,EAAAC,CAAA,EAAAC,CAAA,WAAAD,CAAA,OAAAE,gBAAA,CAAAC,OAAA,EAAAH,CAAA,OAAAI,2BAAA,CAAAD,OAAA,EAAAJ,CAAA,EAAAM,yBAAA,KAAAC,kBAAA,CAAAN,CAAA,EAAAC,CAAA,YAAAC,gBAAA,CAAAC,OAAA,EAAAJ,CAAA,EAAAQ,WAAA,IAAAP,CAAA,CAAAQ,KAAA,CAAAT,CAAA,EAAAE,CAAA;AAAA,SAAAI,0BAAA,cAAAN,CAAA,IAAAU,OAAA,CAAAC,SAAA,CAAAC,OAAA,CAAAC,IAAA,CAAAN,kBAAA,CAAAG,OAAA,iCAAAV,CAAA,aAAAM,yBAAA,YAAAA,0BAAA,aAAAN,CAAA;AAEnC;AACA;AACA;AACA;AACA;AAJA,IAKac,YAAY,GAAAC,OAAA,CAAAD,YAAA,0BAAAE,YAAA;EAAA,SAAAF,aAAA;IAAA,IAAAG,KAAA;IAAA,IAAAC,gBAAA,CAAAd,OAAA,QAAAU,YAAA;IAAA,SAAAK,IAAA,GAAAC,SAAA,CAAAC,MAAA,EAAAC,IAAA,OAAAC,KAAA,CAAAJ,IAAA,GAAAK,IAAA,MAAAA,IAAA,GAAAL,IAAA,EAAAK,IAAA;MAAAF,IAAA,CAAAE,IAAA,IAAAJ,SAAA,CAAAI,IAAA;IAAA;IAAAP,KAAA,GAAAlB,UAAA,OAAAe,YAAA,KAAAW,MAAA,CAAAH,IAAA;IAAA,IAAAI,gBAAA,CAAAtB,OAAA,EAAAa,KAAA,eACXU,iBAAM;IAAA,OAAAV,KAAA;EAAA;EAAA,IAAAW,UAAA,CAAAxB,OAAA,EAAAU,YAAA,EAAAE,YAAA;EAAA,WAAAa,aAAA,CAAAzB,OAAA,EAAAU,YAAA;IAAAgB,GAAA;IAAAC,KAAA;IAElB;AACF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;IACE,SAAOC,aAAaA,CAACC,UAAsB,EAAiB;MAC1D;MACA,IAAMC,OAAO,GAAG,IAAIC,qBAAa,CAACF,UAAU,EAAE,IAAI,CAACG,KAAK,CAACC,OAAO,CAACC,IAAI,CAAC,IAAI,CAACF,KAAK,CAAC,CAAC;MAElF,OAAOF,OAAO;IAChB;EAAC;AAAA,EAlB+BK,sBAAW;AAAA,IAAAC,QAAA,GAAAzB,OAAA,CAAAX,OAAA,GAqB9BU,YAAY","ignoreList":[]}
+{"version":3,"names":["_webexCore","require","_voicea","_constants","_callSuper","t","o","e","_getPrototypeOf2","default","_possibleConstructorReturn2","_isNativeReflectConstruct","_Reflect$construct","constructor","apply","Boolean","prototype","valueOf","call","VoiceaPlugin","exports","_WebexPlugin","_this","_classCallCheck2","_len","arguments","length","args","Array","_key","concat","_defineProperty2","VOICEA","_inherits2","_createClass2","key","value","createChannel","llmChannel","channel","VoiceaChannel","webex","request","bind","WebexPlugin","_default"],"sources":["voicea-plugin.ts"],"sourcesContent":["import {WebexPlugin} from '@webex/webex-core';\nimport type LLMChannel from '@webex/internal-plugin-llm';\n\nimport {VoiceaChannel} from './voicea';\nimport {VOICEA} from './constants';\n\n/**\n * VoiceaPlugin - factory for creating VoiceaChannel instances\n * @export\n * @class VoiceaPlugin\n */\nexport class VoiceaPlugin extends WebexPlugin {\n  namespace = VOICEA;\n\n  /**\n   * Creates a VoiceaChannel, optionally bound to an LLMChannel.\n   *\n   * Note: VoiceaChannel does not take ownership of the LLMChannel.\n   * The caller retains ownership and is responsible for the LLMChannel's\n   * lifecycle (connection, disconnection, cleanup).\n   *\n   * @param {LLMChannel} [llmChannel] - The LLM channel to use for voicea (optional)\n   * @returns {VoiceaChannel} A new VoiceaChannel instance\n   */\n  public createChannel(llmChannel?: LLMChannel): VoiceaChannel {\n    // @ts-ignore - webex is available on WebexPlugin\n    const channel = new VoiceaChannel(llmChannel, this.webex.request.bind(this.webex));\n\n    return channel;\n  }\n}\n\nexport default VoiceaPlugin;\n"],"mappings":";;;;;;;;;;;;;;;AAAA,IAAAA,UAAA,GAAAC,OAAA;AAGA,IAAAC,OAAA,GAAAD,OAAA;AACA,IAAAE,UAAA,GAAAF,OAAA;AAAmC,SAAAG,WAAAC,CAAA,EAAAC,CAAA,EAAAC,CAAA,WAAAD,CAAA,OAAAE,gBAAA,CAAAC,OAAA,EAAAH,CAAA,OAAAI,2BAAA,CAAAD,OAAA,EAAAJ,CAAA,EAAAM,yBAAA,KAAAC,kBAAA,CAAAN,CAAA,EAAAC,CAAA,YAAAC,gBAAA,CAAAC,OAAA,EAAAJ,CAAA,EAAAQ,WAAA,IAAAP,CAAA,CAAAQ,KAAA,CAAAT,CAAA,EAAAE,CAAA;AAAA,SAAAI,0BAAA,cAAAN,CAAA,IAAAU,OAAA,CAAAC,SAAA,CAAAC,OAAA,CAAAC,IAAA,CAAAN,kBAAA,CAAAG,OAAA,iCAAAV,CAAA,aAAAM,yBAAA,YAAAA,0BAAA,aAAAN,CAAA;AAEnC;AACA;AACA;AACA;AACA;AAJA,IAKac,YAAY,GAAAC,OAAA,CAAAD,YAAA,0BAAAE,YAAA;EAAA,SAAAF,aAAA;IAAA,IAAAG,KAAA;IAAA,IAAAC,gBAAA,CAAAd,OAAA,QAAAU,YAAA;IAAA,SAAAK,IAAA,GAAAC,SAAA,CAAAC,MAAA,EAAAC,IAAA,OAAAC,KAAA,CAAAJ,IAAA,GAAAK,IAAA,MAAAA,IAAA,GAAAL,IAAA,EAAAK,IAAA;MAAAF,IAAA,CAAAE,IAAA,IAAAJ,SAAA,CAAAI,IAAA;IAAA;IAAAP,KAAA,GAAAlB,UAAA,OAAAe,YAAA,KAAAW,MAAA,CAAAH,IAAA;IAAA,IAAAI,gBAAA,CAAAtB,OAAA,EAAAa,KAAA,eACXU,iBAAM;IAAA,OAAAV,KAAA;EAAA;EAAA,IAAAW,UAAA,CAAAxB,OAAA,EAAAU,YAAA,EAAAE,YAAA;EAAA,WAAAa,aAAA,CAAAzB,OAAA,EAAAU,YAAA;IAAAgB,GAAA;IAAAC,KAAA;IAElB;AACF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;IACE,SAAOC,aAAaA,CAACC,UAAuB,EAAiB;MAC3D;MACA,IAAMC,OAAO,GAAG,IAAIC,qBAAa,CAACF,UAAU,EAAE,IAAI,CAACG,KAAK,CAACC,OAAO,CAACC,IAAI,CAAC,IAAI,CAACF,KAAK,CAAC,CAAC;MAElF,OAAOF,OAAO;IAChB;EAAC;AAAA,EAlB+BK,sBAAW;AAAA,IAAAC,QAAA,GAAAzB,OAAA,CAAAX,OAAA,GAqB9BU,YAAY","ignoreList":[]}

package/dist/voicea.js

@@ -12,6 +12,7 @@ _Object$defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = exports.VoiceaChannel = void 0;
+var _promise = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/promise"));
 var _regenerator = _interopRequireDefault(require("@babel/runtime-corejs2/regenerator"));
 var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime-corejs2/helpers/asyncToGenerator"));
 var _classCallCheck2 = _interopRequireDefault(require("@babel/runtime-corejs2/helpers/classCallCheck"));
@@ -39,8 +40,9 @@ function _isNativeReflectConstruct() { try { var t = !Boolean.prototype.valueOf.
  */
 var VoiceaChannel = exports.VoiceaChannel = /*#__PURE__*/function (_EventEmitter) {
   /**
-   * Creates a VoiceaChannel bound to the given LLMChannel
-   * @param {LLMChannel} llmChannel - The LLM channel to use
+   * Creates a VoiceaChannel, optionally bound to an LLMChannel.
+   * If no llmChannel is provided, call switchLLMChannel() later to attach one.
+   * @param {LLMChannel} [llmChannel] - The LLM channel to use (optional)
    * @param {Function} request - The request function for making API calls (typically webex.request bound to webex)
    */
   function VoiceaChannel(llmChannel, request) {
@@ -60,6 +62,12 @@ var VoiceaChannel = exports.VoiceaChannel = /*#__PURE__*/function (_EventEmitter
     (0, _defineProperty2.default)(_this, "currentSpokenLanguage", void 0);
     (0, _defineProperty2.default)(_this, "spokenLanguages", []);
     (0, _defineProperty2.default)(_this, "currentCaptionLanguage", void 0);
+    // Target channel for reconciler pattern - the channel voicea WANTS to be bound to
+    (0, _defineProperty2.default)(_this, "targetLLMChannel", void 0);
+    // Single pending 'online' listener for deferred reconciliation
+    (0, _defineProperty2.default)(_this, "_pendingOnlineListener", void 0);
+    // Tracks whether caption restoration is pending (set on switch, cleared on restore)
+    (0, _defineProperty2.default)(_this, "_pendingCaptionRestore", false);
     /**
      * Process events from LLM channel
      * @param {Object} e - Event data
@@ -218,7 +226,8 @@ var VoiceaChannel = exports.VoiceaChannel = /*#__PURE__*/function (_EventEmitter
      * @returns {boolean}
      */
     (0, _defineProperty2.default)(_this, "isLLMConnected", function () {
-      return _this.llmChannel.isConnected();
+      var _this$llmChannel$isCo, _this$llmChannel;
+      return (_this$llmChannel$isCo = (_this$llmChannel = _this.llmChannel) === null || _this$llmChannel === void 0 ? void 0 : _this$llmChannel.isConnected()) !== null && _this$llmChannel$isCo !== void 0 ? _this$llmChannel$isCo : false;
     });
     (0, _defineProperty2.default)(_this, "getKeepTranscriptionSubscribed", function () {
       return _this.keepTranscriptionSubscribed;
@@ -228,9 +237,10 @@ var VoiceaChannel = exports.VoiceaChannel = /*#__PURE__*/function (_EventEmitter
      * @returns {void}
      */
     (0, _defineProperty2.default)(_this, "sendAnnouncement", function () {
+      var llm = _this.requireLLMChannel();
       _this.announceStatus = _constants.ANNOUNCE_STATUS.JOINING;
-      var socket = _this.llmChannel.getSocket();
-      var binding = _this.llmChannel.getBinding();
+      var socket = llm.getSocket();
+      var binding = llm.getBinding();
       var payload = {
         id: "".concat(_this.seqNum),
         type: 'publishRequest',
@@ -262,7 +272,7 @@ var VoiceaChannel = exports.VoiceaChannel = /*#__PURE__*/function (_EventEmitter
     (0, _defineProperty2.default)(_this, "setSpokenLanguage", function (languageCode, languageAssignment) {
       return _this.request({
         method: 'PUT',
-        url: "".concat(_this.llmChannel.getLocusUrl(), "/controls/"),
+        url: "".concat(_this.requireLLMChannel().getLocusUrl(), "/controls/"),
         body: {
           transcribe: _objectSpread({
             spokenLanguage: languageCode
@@ -285,8 +295,9 @@ var VoiceaChannel = exports.VoiceaChannel = /*#__PURE__*/function (_EventEmitter
       if (!_this.isLLMConnected()) {
         return;
       }
-      var socket = _this.llmChannel.getSocket();
-      var binding = _this.llmChannel.getBinding();
+      var llm = _this.requireLLMChannel();
+      var socket = llm.getSocket();
+      var binding = llm.getBinding();
       socket.send({
         id: "".concat(_this.seqNum),
         type: 'publishRequest',
@@ -321,8 +332,9 @@ var VoiceaChannel = exports.VoiceaChannel = /*#__PURE__*/function (_EventEmitter
       if (!_this.isLLMConnected()) {
         return;
       }
-      var socket = _this.llmChannel.getSocket();
-      var binding = _this.llmChannel.getBinding();
+      var llm = _this.requireLLMChannel();
+      var socket = llm.getSocket();
+      var binding = llm.getBinding();
       socket === null || socket === void 0 ? void 0 : socket.send({
         id: "".concat(_this.seqNum),
         type: 'publishRequest',
@@ -356,7 +368,7 @@ var VoiceaChannel = exports.VoiceaChannel = /*#__PURE__*/function (_EventEmitter
      */
     (0, _defineProperty2.default)(_this, "requestTurnOnCaptions", function (languageCode) {
       _this.captionStatus = _constants.TURN_ON_CAPTION_STATUS.SENDING;
-      var locusUrl = _this.llmChannel.getLocusUrl();
+      var locusUrl = _this.requireLLMChannel().getLocusUrl();
       var body = {
         transcribe: {
           caption: true
@@ -377,7 +389,9 @@ var VoiceaChannel = exports.VoiceaChannel = /*#__PURE__*/function (_EventEmitter
         }, true);
       }).catch(function (error) {
         _this.captionStatus = _constants.TURN_ON_CAPTION_STATUS.IDLE;
-        throw new Error('turn on captions fail');
+        throw new Error('turn on captions fail', {
+          cause: error
+        });
       });
     });
     /**
@@ -424,7 +438,7 @@ var VoiceaChannel = exports.VoiceaChannel = /*#__PURE__*/function (_EventEmitter
         return _regenerator.default.wrap(function (_context) {
           while (1) switch (_context.prev = _context.next) {
             case 0:
-              if (!(_this.captionStatus === _constants.TURN_ON_CAPTION_STATUS.SENDING)) {
+              if (!_this.isCaptionProcessing()) {
                 _context.next = 1;
                 break;
               }
@@ -456,7 +470,7 @@ var VoiceaChannel = exports.VoiceaChannel = /*#__PURE__*/function (_EventEmitter
     (0, _defineProperty2.default)(_this, "toggleTranscribing", function (activate, spokenLanguage) {
       return _this.request({
         method: 'PUT',
-        url: "".concat(_this.llmChannel.getLocusUrl(), "/controls/"),
+        url: "".concat(_this.requireLLMChannel().getLocusUrl(), "/controls/"),
         body: {
           transcribe: {
             transcribing: activate
@@ -480,7 +494,7 @@ var VoiceaChannel = exports.VoiceaChannel = /*#__PURE__*/function (_EventEmitter
       _this.toggleManualCaptionStatus = _constants.TOGGLE_MANUAL_CAPTION_STATUS.SENDING;
       return _this.request({
         method: 'PUT',
-        url: "".concat(_this.llmChannel.getLocusUrl(), "/controls/"),
+        url: "".concat(_this.requireLLMChannel().getLocusUrl(), "/controls/"),
         body: {
           manualCaption: {
             enable: enable
@@ -550,6 +564,7 @@ var VoiceaChannel = exports.VoiceaChannel = /*#__PURE__*/function (_EventEmitter
         subscribe,
         _ref3$unsubscribe,
         unsubscribe,
+        llm,
         isDataChannelTokenEnabled,
         socket,
         datachannelUrl,
@@ -564,8 +579,9 @@ var VoiceaChannel = exports.VoiceaChannel = /*#__PURE__*/function (_EventEmitter
             }
             return _context2.abrupt("return");
           case 1:
+            llm = _this.requireLLMChannel();
             _context2.next = 2;
-            return _this.llmChannel.isDataChannelTokenEnabled();
+            return llm.isDataChannelTokenEnabled();
           case 2:
             isDataChannelTokenEnabled = _context2.sent;
             if (isDataChannelTokenEnabled) {
@@ -574,8 +590,8 @@ var VoiceaChannel = exports.VoiceaChannel = /*#__PURE__*/function (_EventEmitter
             }
             return _context2.abrupt("return");
           case 3:
-            socket = _this.llmChannel.getSocket();
-            datachannelUrl = _this.llmChannel.getDatachannelUrl();
+            socket = llm.getSocket();
+            datachannelUrl = llm.getDatachannelUrl();
             socket.send({
               id: "".concat(_this.seqNum),
               type: 'subchannelSubscriptionRequest',
@@ -623,13 +639,30 @@ var VoiceaChannel = exports.VoiceaChannel = /*#__PURE__*/function (_EventEmitter
     _this.currentCaptionLanguage = undefined;
     _this.keepTranscriptionSubscribed = false;
 
-    // Subscribe to relay events from the LLM channel
-    _this.llmChannel.on('event:relay.event', _this.eventProcessor);
-    _this.hasSubscribedToEvents = true;
+    // Subscribe to relay events from the LLM channel if provided
+    if (_this.llmChannel) {
+      _this.llmChannel.on('event:relay.event', _this.eventProcessor);
+      _this.hasSubscribedToEvents = true;
+    }
     return _this;
   }
+
+  /**
+   * Returns the LLM channel, throwing if not available.
+   * @private
+   * @returns {LLMChannel}
+   * @throws {Error} If LLM channel is not available
+   */
   (0, _inherits2.default)(VoiceaChannel, _EventEmitter);
   return (0, _createClass2.default)(VoiceaChannel, [{
+    key: "requireLLMChannel",
+    value: function requireLLMChannel() {
+      if (!this.llmChannel) {
+        throw new Error('VoiceaChannel: LLM channel not available');
+      }
+      return this.llmChannel;
+    }
+  }, {
     key: "deregisterEvents",
     value:
     /**
@@ -640,8 +673,14 @@ var VoiceaChannel = exports.VoiceaChannel = /*#__PURE__*/function (_EventEmitter
       this.areCaptionsEnabled = false;
       this.keepTranscriptionSubscribed = false;
       this.captionServiceId = undefined;
+      this.targetLLMChannel = undefined;
+      this._pendingCaptionRestore = false;
+
+      // Remove any pending online listener
+      this.detachPendingOnline();
       if (this.hasSubscribedToEvents) {
-        this.llmChannel.off('event:relay.event', this.eventProcessor);
+        var _this$llmChannel2;
+        (_this$llmChannel2 = this.llmChannel) === null || _this$llmChannel2 === void 0 ? void 0 : _this$llmChannel2.off('event:relay.event', this.eventProcessor);
         this.hasSubscribedToEvents = false;
       }
       this.announceStatus = _constants.ANNOUNCE_STATUS.IDLE;
@@ -652,61 +691,109 @@ var VoiceaChannel = exports.VoiceaChannel = /*#__PURE__*/function (_EventEmitter
     }
 
     /**
-     * Switch to a different LLM channel while preserving caption state.
-     * Used when transitioning between main meeting and practice session.
-     * - Preserves keepTranscriptionSubscribed and spokenLanguage state
-     * - Unsubscribes from old channel, subscribes to new channel
-     * - Re-announces and re-enables captions if they were on
-     * @param {LLMChannel} newLLMChannel - The new LLM channel to switch to
-     * @returns {Promise<void>}
+     * Attach a pending 'online' listener to a channel for deferred reconciliation.
+     * Detaches any existing listener first.
+     * @param {LLMChannel} channel - The channel to attach to
+     * @param {Function} callback - The callback to run when 'online' fires
+     * @private
+     * @returns {void}
      */
   }, {
-    key: "switchLLMChannel",
-    value: (function () {
-      var _switchLLMChannel = (0, _asyncToGenerator2.default)(/*#__PURE__*/_regenerator.default.mark(function _callee3(newLLMChannel) {
-        var captionsWereOn, spokenLanguage;
-        return _regenerator.default.wrap(function (_context3) {
-          while (1) switch (_context3.prev = _context3.next) {
-            case 0:
-              // Save current state
-              captionsWereOn = this.keepTranscriptionSubscribed;
-              spokenLanguage = this.currentSpokenLanguage; // Unsubscribe from old channel
-              if (this.hasSubscribedToEvents && this.llmChannel) {
-                this.llmChannel.off('event:relay.event', this.eventProcessor);
-                this.hasSubscribedToEvents = false;
-              }
+    key: "attachPendingOnline",
+    value: function attachPendingOnline(channel, callback) {
+      this.detachPendingOnline();
+      this._pendingOnlineListener = callback;
+      channel.once('online', this._pendingOnlineListener);
+    }
 
-              // Switch to new channel
-              this.llmChannel = newLLMChannel;
+    /**
+     * Detach any pending 'online' listener.
+     * @private
+     * @returns {void}
+     */
+  }, {
+    key: "detachPendingOnline",
+    value: function detachPendingOnline() {
+      if (this._pendingOnlineListener && this.llmChannel) {
+        this.llmChannel.off('online', this._pendingOnlineListener);
+      }
+      this._pendingOnlineListener = undefined;
+    }
 
-              // Subscribe to new channel
-              this.llmChannel.on('event:relay.event', this.eventProcessor);
-              this.hasSubscribedToEvents = true;
+    /**
+     * Reset announcement state for a new connection.
+     * @private
+     * @returns {void}
+     */
+  }, {
+    key: "resetAnnounceState",
+    value: function resetAnnounceState() {
+      this.announceStatus = _constants.ANNOUNCE_STATUS.IDLE;
+      this.captionStatus = _constants.TURN_ON_CAPTION_STATUS.IDLE;
+      this.captionServiceId = undefined;
+      this.areCaptionsEnabled = false;
+    }
 
-              // Reset announcement state for new connection
-              this.announceStatus = _constants.ANNOUNCE_STATUS.IDLE;
-              this.captionStatus = _constants.TURN_ON_CAPTION_STATUS.IDLE;
-              this.captionServiceId = undefined;
-              this.areCaptionsEnabled = false;
+    /**
+     * Reconcile voicea binding and caption state to match the desired target.
+     * This is idempotent - always re-reads targetLLMChannel and current state.
+     * A deferred 'online' callback that fires late self-corrects automatically.
+     * @private
+     * @returns {Promise<void>}
+     */
+  }, {
+    key: "reconcile",
+    value: function reconcile() {
+      var _this2 = this;
+      var target = this.targetLLMChannel;
+      if (!target) return _promise.default.resolve();
 
-              // Re-announce and re-enable captions if they were on
-              if (!captionsWereOn) {
-                _context3.next = 1;
-                break;
-              }
-              _context3.next = 1;
-              return this.turnOnCaptions(spokenLanguage);
-            case 1:
-            case "end":
-              return _context3.stop();
-          }
-        }, _callee3, this);
-      }));
-      function switchLLMChannel(_x2) {
-        return _switchLLMChannel.apply(this, arguments);
+      // 1. Rebind relay-event subscription if actual != desired
+      if (this.llmChannel !== target) {
+        if (this.hasSubscribedToEvents && this.llmChannel) {
+          this.llmChannel.off('event:relay.event', this.eventProcessor);
+        }
+        this.detachPendingOnline();
+        this.llmChannel = target;
+        this.llmChannel.on('event:relay.event', this.eventProcessor);
+        this.hasSubscribedToEvents = true;
+        this.resetAnnounceState();
+        // Mark caption restoration as pending if captions were subscribed
+        this._pendingCaptionRestore = this.keepTranscriptionSubscribed;
       }
-      return switchLLMChannel;
-    }())
+
+      // 2. Restore captions if pending
+      if (!this._pendingCaptionRestore) return _promise.default.resolve();
+      if (this.isLLMConnected()) {
+        // Channel is connected, restore captions immediately
+        this._pendingCaptionRestore = false;
+        return this.turnOnCaptions(this.currentSpokenLanguage).then(function () {
+          return undefined;
+        }).catch(function () {
+          // Best-effort restoration
+        });
+      }
+      // Channel not yet connected - defer until 'online' then re-reconcile.
+      // If target changes meanwhile, reconcile() self-corrects.
+      this.attachPendingOnline(target, function () {
+        _this2.reconcile();
+      });
+      return _promise.default.resolve();
+    }
+
+    /**
+     * Switch to a different LLM channel while preserving caption state.
+     * Used when transitioning between main meeting and practice session.
+     * This is a thin intent-setter - actual binding happens in reconcile().
+     * @param {LLMChannel} newLLMChannel - The new LLM channel to switch to
+     * @returns {Promise<void>}
+     */
+  }, {
+    key: "switchLLMChannel",
+    value: function switchLLMChannel(newLLMChannel) {
+      this.targetLLMChannel = newLLMChannel;
+      return this.reconcile();
+    }
   }]);
 }(_events.default);
 var _default = exports.default = VoiceaChannel;