@webex/contact-center 3.12.0-llmrefactor.3 → 3.12.0-llmrefactor.4

package/.sdd/manifest.json

@@ -309,7 +309,7 @@
       "canonical_spec": "src/services/task/ai-docs/task-spec.md",
       "contracts": {
         "provides": [
-          "Task/Voice/WebRTC/Digital lifecycle APIs; TaskManager; task events/types; ordered action-specific consult/transfer destination controls; call-control and dialer operations including acceptPreviewContact, skipPreviewContact, and removePreviewContact"
+          "Task/Voice/WebRTC/Digital lifecycle APIs; TaskManager lifecycle correlation, narrowly scoped backend-authoritative ContactOwnerChanged recovery, and task-event publication, including routing owner-changing ContactUpdated through the existing task:hydrate event; task events/types; ordered action-specific consult/transfer destination controls; call-control and dialer operations including acceptPreviewContact, skipPreviewContact, and removePreviewContact"
         ],
         "requires": [
           "Contact/dialer AqmReqs; WebSocket managers; @webex/calling; MetricsManager; XState task-state module"

package/ai-docs/CONTRACTS.md

@@ -22,7 +22,7 @@
 | Contract ID | Owner module | Event / topic | Direction | Payload schema link | Delivery guarantees | Compatibility / deprecation | Defined at |
 |---|---|---|---|---|---|---|---|
 | `agent.events` | Agent | `agent:*` | publish to application | agent spec/types | realtime; backend ordering/correlation | additive constants | `src/services/agent/types.ts` |
-| `task.events` | Task | `task:*` | publish to application/task | task spec/types | event-driven; state guarded | additive constants | `src/services/task/types.ts` |
+| `task.events` | Task | `task:*`, including existing `task:hydrate` | consume/map backend task lifecycle events, then publish to application/task | task spec `TASK-R-010` / types | `ContactOwnerChanged` and owner-changing `ContactUpdated` route through `CONTACT_OWNER_CHANGED`; a complete promoted-current-Agent owner change may narrowly recover a missing task; consumers receive one `task:hydrate` and no synthetic `task:incoming` | compatible semantic extension of an existing event; no new event constant; backend `interaction.owner` remains authoritative | `src/services/task/TaskManager.ts`, `src/services/task/Task.ts`, `src/services/task/types.ts` |
 | `task.wxapp-mute.events` | Task | `task:wxapp-mute-state-updated` | publish to application/task | task spec/types | event-driven | additive | `src/services/task/types.ts`, `src/services/task/voice/Voice.ts` |
 | `cc.events` | Config/Core | backend CC_EVENTS | consume/map | config/core specs | remote WebSocket delivery; AQM correlation where configured | backend contract | `src/services/config/types.ts` |
 | `rtd.events` | Task | realtime transcription/suggestion | consume then publish per task | task spec | websocket best-effort according to remote service | additive payloads | `src/services/task/TaskManager.ts` |

package/dist/services/task/TaskManager.js

@@ -17,6 +17,7 @@ var _TaskFactory = _interopRequireDefault(require("./TaskFactory"));
 var _WebexCallingUtils = require("./WebexCallingUtils");
 var _WebRTC = _interopRequireDefault(require("./voice/WebRTC"));
 var _stateMachine = require("./state-machine");
+var _constants3 = require("./state-machine/constants");
 var _taskDataNormalizer = require("./taskDataNormalizer");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 const CC_EVENT_SET = new Set(Object.values(_types2.CC_EVENTS));
@@ -186,6 +187,12 @@ class TaskManager extends _events.default {
           agentId
         };
       case _types2.CC_EVENTS.CONTACT_UPDATED:
+        if (task && typeof payload.interaction?.owner === 'string' && payload.interaction.owner.trim().length > 0 && payload.interaction.owner !== task.data?.interaction?.owner) {
+          return {
+            type: _stateMachine.TaskEvent.CONTACT_OWNER_CHANGED,
+            taskData: payload
+          };
+        }
         return {
           type: _stateMachine.TaskEvent.CONTACT_UPDATED,
           taskData: payload
@@ -561,6 +568,9 @@ class TaskManager extends _events.default {
         this.taskCollection[interactionId] = task;
       }
     }
+    if (!task && eventType === _types2.CC_EVENTS.CONTACT_OWNER_CHANGED) {
+      task = this.findTaskForContactOwnerChange(message.data);
+    }
     if (!task && MAIN_INTERACTION_CORRELATED_EVENTS.has(eventType)) {
       task = this.findUniqueTaskByRelatedInteraction(message.data);
     }
@@ -574,10 +584,16 @@ class TaskManager extends _events.default {
       }
       return !wasConsultedTask;
     };
-    const adjustedPayload = eventType === _types2.CC_EVENTS.AGENT_CONSULT_TRANSFERRED || eventType === _types2.CC_EVENTS.AGENT_BLIND_TRANSFERRED || eventType === _types2.CC_EVENTS.AGENT_VTEAM_TRANSFERRED ? {
+    let adjustedPayload = eventType === _types2.CC_EVENTS.AGENT_CONSULT_TRANSFERRED || eventType === _types2.CC_EVENTS.AGENT_BLIND_TRANSFERRED || eventType === _types2.CC_EVENTS.AGENT_VTEAM_TRANSFERRED ? {
       ...message.data,
       wrapUpRequired: computeWrapUpRequired()
     } : message.data;
+    if (task && eventType === _types2.CC_EVENTS.CONTACT_OWNER_CHANGED) {
+      adjustedPayload = TaskManager.preserveMainTaskIdentity(task, adjustedPayload);
+    }
+    if (task && eventType === _types2.CC_EVENTS.PARTICIPANT_LEFT_CONFERENCE) {
+      adjustedPayload = TaskManager.preserveConfirmedOwner(task, adjustedPayload);
+    }
     const stateMachineEvent = TaskManager.mapEventToTaskStateMachineEvent(eventType, adjustedPayload, this.agentId, task, this.configFlags?.enableWxBetterTogether);
     _loggerProxy.default.info(`Handling task event ${eventType}`, {
       module: _constants.TASK_MANAGER_FILE,
@@ -592,20 +608,108 @@ class TaskManager extends _events.default {
     };
   }
 
+  /**
+   * ContactOwnerChanged can identify the promoted agent's child interaction while
+   * the surviving task is stored under the main interaction. Accept one related
+   * task when its existing snapshot or the authoritative incoming promotion proves
+   * current-agent main-call membership, while excluding non-promoted and ambiguous matches.
+   */
+  findTaskForContactOwnerChange(payload) {
+    const relatedCandidates = this.findRelatedTasks(payload, {
+      includeCollectionKeys: true,
+      includeMainCallMediaKeys: true
+    });
+    const incomingShowsCurrentAgentPromotion = this.isCurrentAgentPromotedOnIncomingMainCall(payload);
+    const eligibleCandidates = relatedCandidates.filter(candidate => this.isCurrentAgentActiveOnMainInteraction(candidate.data) || incomingShowsCurrentAgentPromotion);
+    if (eligibleCandidates.length === 1) {
+      return eligibleCandidates[0];
+    }
+    if (eligibleCandidates.length > 1) {
+      _loggerProxy.default.warn('Unable to correlate task event to a unique main interaction task', {
+        module: _constants.TASK_MANAGER_FILE,
+        method: 'findTaskForContactOwnerChange',
+        interactionId: payload.interaction?.mainInteractionId || payload.interaction?.parentInteractionId || payload.interaction?.callProcessingDetails?.parentInteractionId || payload.interactionId
+      });
+      return undefined;
+    }
+    return undefined;
+  }
+  isCurrentAgentActiveOnMainInteraction(taskData) {
+    const currentAgentId = this.agentId || taskData?.agentId;
+    if (!currentAgentId) return false;
+    return TaskManager.isParticipantActiveOnMainInteraction(taskData, currentAgentId);
+  }
+  static isParticipantActiveOnMainInteraction(taskData, participantId) {
+    const interaction = taskData?.interaction;
+    const participant = interaction?.participants?.[participantId];
+    if (!participant || participant.hasLeft === true) return false;
+    return Object.values(interaction?.media ?? {}).some(media => media?.mType === _constants3.MEDIA_TYPE_MAIN_CALL && media.participants?.includes(participantId));
+  }
+  isCurrentAgentPromotedOnIncomingMainCall(payload) {
+    return Boolean(this.agentId && payload.interaction?.owner === this.agentId && TaskManager.isParticipantActiveOnMainInteraction(payload, this.agentId));
+  }
+  static getMainCallMediaId(interaction) {
+    return Object.entries(interaction?.media ?? {}).find(([, media]) => media?.mType === _constants3.MEDIA_TYPE_MAIN_CALL)?.[0];
+  }
+  static getStableMainInteractionId(payload) {
+    return payload.interaction?.mainInteractionId || TaskManager.getMainCallMediaId(payload.interaction) || payload.interaction?.interactionId || payload.interactionId;
+  }
+  canRecoverTaskFromContactOwnerChanged(payload) {
+    const interaction = payload.interaction;
+    const stableInteractionId = TaskManager.getStableMainInteractionId(payload);
+    return Boolean(this.agentId && stableInteractionId && interaction?.mediaType === _types.MEDIA_CHANNEL.TELEPHONY && interaction.isTerminated !== true && interaction.owner === this.agentId && TaskManager.isParticipantActiveOnMainInteraction(payload, this.agentId));
+  }
+
+  /** Keep a related owner-change event from re-keying the surviving main task to a child ID. */
+  static preserveMainTaskIdentity(task, payload) {
+    const currentMainInteractionId = task.data?.interaction?.mainInteractionId;
+    const payloadMainInteractionId = payload.interaction?.mainInteractionId;
+    const currentMainMediaId = TaskManager.getMainCallMediaId(task.data?.interaction);
+    const payloadMainMediaId = TaskManager.getMainCallMediaId(payload.interaction);
+    const stableInteractionId = currentMainInteractionId || payloadMainInteractionId || currentMainMediaId || payloadMainMediaId || payload.interaction?.interactionId || task.data?.interaction?.interactionId || task.data?.interactionId;
+    if (!stableInteractionId || stableInteractionId === payload.interactionId) {
+      return payload;
+    }
+    return {
+      ...payload,
+      interactionId: stableInteractionId
+    };
+  }
+
+  /**
+   * ParticipantLeftConference may arrive after an owner update while still carrying
+   * the departed owner. Keep the confirmed owner only when the new roster proves that
+   * owner is active on mainCall and identifies the incoming owner as departed.
+   */
+  static preserveConfirmedOwner(task, payload) {
+    const confirmedOwner = task.data?.interaction?.owner;
+    const incomingOwner = payload.interaction?.owner;
+    if (!confirmedOwner || !incomingOwner || confirmedOwner === incomingOwner) {
+      return payload;
+    }
+    const confirmedOwnerIsActive = TaskManager.isParticipantActiveOnMainInteraction(payload, confirmedOwner);
+    const incomingOwnerIsExplicitlyDeparted = payload.participantId === incomingOwner || payload.interaction?.participants?.[incomingOwner]?.hasLeft === true;
+    if (!confirmedOwnerIsActive || !incomingOwnerIsExplicitlyDeparted) {
+      return payload;
+    }
+    return {
+      ...payload,
+      owner: confirmedOwner,
+      interaction: {
+        ...payload.interaction,
+        owner: confirmedOwner
+      }
+    };
+  }
+
   /**
    * Resolve lifecycle events that are emitted for the main interaction while the
    * local task can still be indexed by a child consult interaction. Exact task
    * keys are handled before this fallback. Multiple aliases of the same task are
    * treated as one candidate; genuinely ambiguous matches are intentionally ignored.
    */
-  findUniqueTaskByRelatedInteraction(payload) {
-    const payloadInteractionIds = new Set([payload.interactionId, payload.interaction?.interactionId, payload.interaction?.mainInteractionId, payload.interaction?.parentInteractionId, payload.interaction?.callProcessingDetails?.parentInteractionId].filter(interactionId => Boolean(interactionId)));
-    if (payloadInteractionIds.size === 0) return undefined;
-    const candidates = [...new Set(Object.values(this.taskCollection).filter(candidate => {
-      const taskInteraction = candidate?.data?.interaction;
-      const candidateInteractionIds = [candidate?.data?.interactionId, taskInteraction?.interactionId, taskInteraction?.mainInteractionId, taskInteraction?.parentInteractionId, taskInteraction?.callProcessingDetails?.parentInteractionId];
-      return candidateInteractionIds.some(interactionId => Boolean(interactionId) && payloadInteractionIds.has(interactionId));
-    }))];
+  findUniqueTaskByRelatedInteraction(payload, candidateFilter = () => true) {
+    const candidates = this.findRelatedTasks(payload).filter(candidateFilter);
     if (candidates.length === 1) {
       return candidates[0];
     }
@@ -618,6 +722,19 @@ class TaskManager extends _events.default {
     }
     return undefined;
   }
+  findRelatedTasks(payload, options = {}) {
+    const {
+      includeCollectionKeys = false,
+      includeMainCallMediaKeys = false
+    } = options;
+    const payloadInteractionIds = new Set([payload.interactionId, payload.interaction?.interactionId, payload.interaction?.mainInteractionId, payload.interaction?.parentInteractionId, payload.interaction?.callProcessingDetails?.parentInteractionId, ...(includeMainCallMediaKeys ? [TaskManager.getMainCallMediaId(payload.interaction)] : [])].filter(interactionId => Boolean(interactionId)));
+    if (payloadInteractionIds.size === 0) return [];
+    return [...new Set(Object.entries(this.taskCollection).filter(([taskId, candidate]) => {
+      const taskInteraction = candidate?.data?.interaction;
+      const candidateInteractionIds = [...(includeCollectionKeys ? [taskId] : []), candidate?.data?.interactionId, taskInteraction?.interactionId, taskInteraction?.mainInteractionId, taskInteraction?.parentInteractionId, taskInteraction?.callProcessingDetails?.parentInteractionId, ...(includeMainCallMediaKeys ? [TaskManager.getMainCallMediaId(taskInteraction)] : [])];
+      return candidateInteractionIds.some(interactionId => Boolean(interactionId) && payloadInteractionIds.has(interactionId));
+    }).map(([, candidate]) => candidate))];
+  }
 
   /**
    * Handle task lifecycle events and determine required actions
@@ -642,6 +759,8 @@ class TaskManager extends _events.default {
         return this.handleAgentContact(context);
       case _types2.CC_EVENTS.CONTACT_MERGED:
         return this.handleContactMergedEvent(context);
+      case _types2.CC_EVENTS.CONTACT_OWNER_CHANGED:
+        return this.handleContactOwnerChanged(context);
       case _types2.CC_EVENTS.AGENT_OFFER_CAMPAIGN_RESERVATION:
         return this.handleCampaignPreviewReservation(context);
       case _types2.CC_EVENTS.CAMPAIGN_CONTACT_UPDATED:
@@ -652,6 +771,63 @@ class TaskManager extends _events.default {
         };
     }
   }
+
+  /**
+   * Recover the promoted agent's active voice task when local task state was lost.
+   * Existing related tasks are never replaced: an unresolved or ambiguous relation
+   * is safer to ignore than to create a duplicate task.
+   */
+  handleContactOwnerChanged(context) {
+    if (context.task) {
+      return {
+        task: context.task
+      };
+    }
+    const {
+      payload
+    } = context;
+    if (this.findRelatedTasks(payload, {
+      includeCollectionKeys: true,
+      includeMainCallMediaKeys: true
+    }).length > 0 || !this.canRecoverTaskFromContactOwnerChanged(payload)) {
+      return {};
+    }
+    const stableInteractionId = TaskManager.getStableMainInteractionId(payload);
+    if (!stableInteractionId || this.taskCollection[stableInteractionId]) {
+      return {};
+    }
+    const normalizedPayload = payload.interactionId === stableInteractionId ? payload : {
+      ...payload,
+      interactionId: stableInteractionId
+    };
+    const taskData = {
+      ...normalizedPayload,
+      owner: normalizedPayload.interaction.owner,
+      wrapUpRequired: normalizedPayload.interaction.participants?.[this.agentId]?.isWrapUp || false,
+      isConferenceInProgress: (0, _TaskUtils.getIsConferenceInProgress)(normalizedPayload),
+      isConsulted: false,
+      isAutoAnswering: false
+    };
+    const task = _TaskFactory.default.createTask(this.contact, this.webCallingService, taskData, this.configFlags, this.wrapupData, this.agentId, this.answerCallOnWebexService);
+    this.taskCollection[stableInteractionId] = task;
+
+    // Restore the actor before installing listeners so the internal hydrate does
+    // not leak as a second public hydrate or as an incoming-task notification.
+    task.sendStateMachineEvent({
+      type: _stateMachine.TaskEvent.HYDRATE,
+      taskData,
+      agentId: this.agentId
+    });
+    this.setupTaskListeners(task);
+    context.payload = taskData;
+    context.stateMachineEvent = {
+      type: _stateMachine.TaskEvent.CONTACT_OWNER_CHANGED,
+      taskData
+    };
+    return {
+      task
+    };
+  }
   handleCampaignContactUpdated(context) {
     const {
       payload