@webex/contact-center 3.12.0-next.129 → 3.12.0-next.130

package/src/services/task/TaskManager.ts

@@ -778,6 +778,7 @@ export default class TaskManager extends EventEmitter {
     const interactionId = message.data.interactionId;
     const reservationInteractionId = message.data.reservationInteractionId;
     let task = this.taskCollection[interactionId];
+    let ownerChangeResolvedByRelatedInteraction = false;
 
     // When a campaign preview contact is accepted, the assigned event may arrive
     // with a new interactionId while the task is stored under the original
@@ -792,7 +793,66 @@ export default class TaskManager extends EventEmitter {
     }
 
     if (!task && eventType === CC_EVENTS.CONTACT_OWNER_CHANGED) {
-      task = this.findTaskForContactOwnerChange(message.data);
+      const incomingShowsCurrentAgentPromotion = Boolean(
+        this.agentId &&
+          message.data.interaction?.owner === this.agentId &&
+          TaskManager.isParticipantActiveOnMainInteraction(message.data, this.agentId)
+      );
+
+      task = this.findUniqueTaskByRelatedInteraction(
+        message.data,
+        (candidate) => {
+          const currentAgentId = this.agentId || candidate.data?.agentId;
+
+          return Boolean(
+            currentAgentId &&
+              (TaskManager.isParticipantActiveOnMainInteraction(candidate.data, currentAgentId) ||
+                incomingShowsCurrentAgentPromotion)
+          );
+        },
+        {includeCollectionKeys: true, includeMainCallMediaKeys: true}
+      );
+      ownerChangeResolvedByRelatedInteraction = Boolean(task);
+    }
+
+    let ownerChangeMainInteractionId: string | undefined;
+    if (task && eventType === CC_EVENTS.CONTACT_OWNER_CHANGED) {
+      const taskMainInteractionId = task.data?.interaction?.mainInteractionId;
+      const payloadMainInteractionId = message.data.interaction?.mainInteractionId;
+      const hasConflictingMainInteractionIds = Boolean(
+        taskMainInteractionId &&
+          payloadMainInteractionId &&
+          taskMainInteractionId !== payloadMainInteractionId
+      );
+      // A promoted child task can retain stale embedded IDs. Prefer the
+      // authoritative incoming main-call identity before local snapshot IDs.
+      const stableMainInteractionId =
+        payloadMainInteractionId ||
+        TaskManager.getMainCallMediaId(message.data.interaction) ||
+        TaskManager.getMainCallMediaId(task.data?.interaction) ||
+        taskMainInteractionId ||
+        message.data.interaction?.interactionId ||
+        task.data?.interaction?.interactionId ||
+        task.data?.interactionId;
+      const taskAtStableKey = stableMainInteractionId
+        ? this.taskCollection[stableMainInteractionId]
+        : undefined;
+
+      if (
+        !stableMainInteractionId ||
+        hasConflictingMainInteractionIds ||
+        (taskAtStableKey && taskAtStableKey !== task)
+      ) {
+        LoggerProxy.warn('Unable to safely correlate owner change to the main interaction task', {
+          module: TASK_MANAGER_FILE,
+          method: 'prepareEventContext',
+          interactionId:
+            payloadMainInteractionId || taskMainInteractionId || message.data.interactionId,
+        });
+        task = undefined;
+      } else if (ownerChangeResolvedByRelatedInteraction) {
+        ownerChangeMainInteractionId = stableMainInteractionId;
+      }
     }
 
     if (!task && MAIN_INTERACTION_CORRELATED_EVENTS.has(eventType)) {
@@ -821,8 +881,11 @@ export default class TaskManager extends EventEmitter {
           }
         : message.data;
 
-    if (task && eventType === CC_EVENTS.CONTACT_OWNER_CHANGED) {
-      adjustedPayload = TaskManager.preserveMainTaskIdentity(task, adjustedPayload);
+    if (task && ownerChangeMainInteractionId) {
+      adjustedPayload = {
+        ...adjustedPayload,
+        interactionId: ownerChangeMainInteractionId,
+      };
     }
 
     if (task && eventType === CC_EVENTS.PARTICIPANT_LEFT_CONFERENCE) {
@@ -860,53 +923,6 @@ export default class TaskManager extends EventEmitter {
     };
   }
 
-  /**
-   * 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.
-   */
-  private findTaskForContactOwnerChange(payload: WebSocketPayload): ITask | undefined {
-    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.warn('Unable to correlate task event to a unique main interaction task', {
-        module: TASK_MANAGER_FILE,
-        method: 'findTaskForContactOwnerChange',
-        interactionId:
-          payload.interaction?.mainInteractionId ||
-          payload.interaction?.parentInteractionId ||
-          payload.interaction?.callProcessingDetails?.parentInteractionId ||
-          payload.interactionId,
-      });
-
-      return undefined;
-    }
-
-    return undefined;
-  }
-
-  private isCurrentAgentActiveOnMainInteraction(taskData: TaskData | undefined): boolean {
-    const currentAgentId = this.agentId || taskData?.agentId;
-    if (!currentAgentId) return false;
-
-    return TaskManager.isParticipantActiveOnMainInteraction(taskData, currentAgentId);
-  }
-
   private static isParticipantActiveOnMainInteraction(
     taskData: TaskData | WebSocketPayload | undefined,
     participantId: string
@@ -921,14 +937,6 @@ export default class TaskManager extends EventEmitter {
     );
   }
 
-  private isCurrentAgentPromotedOnIncomingMainCall(payload: WebSocketPayload): boolean {
-    return Boolean(
-      this.agentId &&
-        payload.interaction?.owner === this.agentId &&
-        TaskManager.isParticipantActiveOnMainInteraction(payload, this.agentId)
-    );
-  }
-
   private static getMainCallMediaId(
     interaction: TaskData['interaction'] | undefined
   ): string | undefined {
@@ -960,31 +968,6 @@ export default class TaskManager extends EventEmitter {
     );
   }
 
-  /** Keep a related owner-change event from re-keying the surviving main task to a child ID. */
-  private static preserveMainTaskIdentity(
-    task: ITask,
-    payload: WebSocketPayload
-  ): WebSocketPayload {
-    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
@@ -1024,9 +1007,10 @@ export default class TaskManager extends EventEmitter {
    */
   private findUniqueTaskByRelatedInteraction(
     payload: WebSocketPayload,
-    candidateFilter: (task: ITask) => boolean = () => true
+    candidateFilter: (task: ITask) => boolean = () => true,
+    options: {includeCollectionKeys?: boolean; includeMainCallMediaKeys?: boolean} = {}
   ): ITask | undefined {
-    const candidates = this.findRelatedTasks(payload).filter(candidateFilter);
+    const candidates = this.findRelatedTasks(payload, options).filter(candidateFilter);
 
     if (candidates.length === 1) {
       return candidates[0];
@@ -1060,7 +1044,9 @@ export default class TaskManager extends EventEmitter {
         payload.interaction?.parentInteractionId,
         payload.interaction?.callProcessingDetails?.parentInteractionId,
         ...(includeMainCallMediaKeys ? [TaskManager.getMainCallMediaId(payload.interaction)] : []),
-      ].filter((interactionId): interactionId is string => Boolean(interactionId))
+      ].filter((relatedInteractionId): relatedInteractionId is string =>
+        Boolean(relatedInteractionId)
+      )
     );
     if (payloadInteractionIds.size === 0) return [];
 
@@ -1082,7 +1068,8 @@ export default class TaskManager extends EventEmitter {
             ];
 
             return candidateInteractionIds.some(
-              (interactionId) => Boolean(interactionId) && payloadInteractionIds.has(interactionId)
+              (relatedInteractionId) =>
+                Boolean(relatedInteractionId) && payloadInteractionIds.has(relatedInteractionId)
             );
           })
           .map(([, candidate]) => candidate)

package/src/services/task/ai-docs/task-spec.md

@@ -924,15 +924,17 @@ guards. The state-machine transition table lives in
 Primary-Agent promotion remains backend-authoritative and follows the two-event
 desktop contract. `ContactOwnerChanged` updates the promoted Agent; TaskManager
 prefers an exact task, then one unique related task resolved through nested
-main/parent identifiers or the `mainCall` media-map identity. A related
-candidate is eligible when its current
+main/parent identifiers, the task collection key, or the `mainCall` media-map
+identity. A related candidate is eligible when its current
 snapshot contains the current Agent's participant entry with `hasLeft !== true`
 and membership on the `mType: mainCall` leg. The incoming snapshot can provide
 that evidence only when it also names the current Agent as `interaction.owner`;
 this permits an authoritative promotion payload to repair a stale child-keyed
 snapshot while still excluding consult-only tasks. The update keeps the
 surviving main interaction identity even when the notification names a
-promoted-Agent child interaction.
+promoted-Agent child interaction. Conflicting main identifiers, ambiguous
+matches, and a canonical key occupied by a distinct task are ignored rather
+than replacing an existing task.
 
 If no related task exists, TaskManager recovers only the promoted current Agent
 from a non-terminal telephony `ContactOwnerChanged` payload that provides the same

package/test/unit/spec/services/task/TaskManager.ts

@@ -2927,7 +2927,7 @@ describe('TaskManager', () => {
       expect(hydrateHandler).toHaveBeenCalledTimes(1);
     });
 
-    it('reuses a task stored under the incoming main-call media key', () => {
+    it('reuses a task identified by the incoming main-call media key', () => {
       const mainMediaInteractionId = 'main-media-interaction-id';
       const promotedChildId = 'promoted-child-without-main-id';
       const task = installTask(
@@ -2958,6 +2958,41 @@ describe('TaskManager', () => {
       expect(hydrateHandler).toHaveBeenCalledWith(task);
     });
 
+    it('reuses a stale task through its collection key and the incoming main-call media key', () => {
+      const mainMediaInteractionId = 'collection-main-interaction-id';
+      const staleChildId = 'stale-collection-child-id';
+      const promotedChildId = 'promoted-collection-child-id';
+      const staleTaskData = createConferenceTaskData(
+        staleChildId,
+        previousOwnerId,
+        staleChildId
+      );
+      staleTaskData.interaction.media[staleChildId].mType = 'consult';
+      const task = createMockTask(staleTaskData);
+      taskManager.taskCollection = {[mainMediaInteractionId]: task};
+      (taskManager as any).setupTaskListeners(task);
+      const hydrateHandler = jest.fn();
+      taskManager.on(TASK_EVENTS.TASK_HYDRATE, hydrateHandler);
+      const ownerChangeData = createPromotedAgentOwnerChangeData(
+        promotedChildId,
+        mainMediaInteractionId
+      );
+      delete ownerChangeData.interaction.mainInteractionId;
+
+      webSocketManagerMock.emit('message', JSON.stringify({data: ownerChangeData}));
+
+      expectLastStateMachineEvent(task.sendStateMachineEvent, TaskEvent.CONTACT_OWNER_CHANGED);
+      expect(task.data.interactionId).toBe(mainMediaInteractionId);
+      expect(task.data.interaction.owner).toBe(currentAgentId);
+      expect(TaskFactory.createTask).not.toHaveBeenCalled();
+      expect(taskManager.taskCollection[mainMediaInteractionId]).toBe(task);
+      expect(taskManager.taskCollection[staleChildId]).toBeUndefined();
+      expect(taskManager.taskCollection[promotedChildId]).toBeUndefined();
+      expect(Object.values(taskManager.taskCollection)).toEqual([task]);
+      expect(task.listenerCount(TASK_EVENTS.TASK_HYDRATE)).toBe(1);
+      expect(hydrateHandler).toHaveBeenCalledTimes(1);
+    });
+
     it('prefers the exact task for ContactOwnerChanged over related child tasks', () => {
       const exactTask = installTask(createConferenceTaskData(taskId, previousOwnerId));
       const childTaskId = 'related-child-id';
@@ -2980,6 +3015,102 @@ describe('TaskManager', () => {
       expect(childTask.sendStateMachineEvent).not.toHaveBeenCalled();
     });
 
+    it('does not replace a distinct main task when an exact child task also exists', () => {
+      const childTaskId = 'exact-child-id';
+      const mainTask = installTask(createConferenceTaskData(taskId, previousOwnerId));
+      const childTask = createMockTask(
+        createConferenceTaskData(childTaskId, previousOwnerId, taskId)
+      );
+      taskManager.taskCollection[childTaskId] = childTask;
+
+      webSocketManagerMock.emit(
+        'message',
+        JSON.stringify({
+          data: {
+            ...createConferenceTaskData(childTaskId, promotedOwnerId, taskId),
+            type: CC_EVENTS.CONTACT_OWNER_CHANGED,
+          },
+        })
+      );
+
+      expect(childTask.sendStateMachineEvent).not.toHaveBeenCalled();
+      expect(mainTask.sendStateMachineEvent).not.toHaveBeenCalled();
+      expect(taskManager.taskCollection[taskId]).toBe(mainTask);
+      expect(taskManager.taskCollection[childTaskId]).toBe(childTask);
+    });
+
+    it('ignores a related owner change with conflicting explicit main interaction IDs', () => {
+      const childTaskId = 'conflicting-main-child-id';
+      const existingMainId = 'existing-main-id';
+      const incomingMainId = 'incoming-main-id';
+      const sharedParentId = 'shared-parent-id';
+      const taskData = createConferenceTaskData(
+        childTaskId,
+        previousOwnerId,
+        existingMainId
+      );
+      taskData.interaction.parentInteractionId = sharedParentId;
+      const task = installTask(taskData);
+      const ownerChangeData = createConferenceTaskData(
+        'different-child-id',
+        promotedOwnerId,
+        incomingMainId
+      );
+      ownerChangeData.interaction.parentInteractionId = sharedParentId;
+
+      webSocketManagerMock.emit(
+        'message',
+        JSON.stringify({
+          data: {...ownerChangeData, type: CC_EVENTS.CONTACT_OWNER_CHANGED},
+        })
+      );
+
+      expect(task.sendStateMachineEvent).not.toHaveBeenCalled();
+      expect(taskManager.taskCollection[childTaskId]).toBe(task);
+      expect(taskManager.taskCollection[existingMainId]).toBeUndefined();
+      expect(taskManager.taskCollection[incomingMainId]).toBeUndefined();
+      expect(TaskFactory.createTask).not.toHaveBeenCalled();
+    });
+
+    it('does not replace a distinct task already stored at the canonical main key', () => {
+      const childTaskId = 'related-active-child-id';
+      const canonicalMainId = 'occupied-canonical-main-id';
+      const candidate = createMockTask(
+        createConferenceTaskData(childTaskId, previousOwnerId, canonicalMainId)
+      );
+      const occupiedData = createConferenceTaskData(
+        'occupied-task-child-id',
+        previousOwnerId,
+        canonicalMainId
+      );
+      occupiedData.interaction.media[canonicalMainId].mType = 'consult';
+      const occupiedTask = createMockTask(occupiedData);
+      taskManager.taskCollection = {
+        [childTaskId]: candidate,
+        [canonicalMainId]: occupiedTask,
+      };
+
+      webSocketManagerMock.emit(
+        'message',
+        JSON.stringify({
+          data: {
+            ...createConferenceTaskData(
+              'incoming-related-child-id',
+              promotedOwnerId,
+              canonicalMainId
+            ),
+            type: CC_EVENTS.CONTACT_OWNER_CHANGED,
+          },
+        })
+      );
+
+      expect(candidate.sendStateMachineEvent).not.toHaveBeenCalled();
+      expect(occupiedTask.sendStateMachineEvent).not.toHaveBeenCalled();
+      expect(taskManager.taskCollection[childTaskId]).toBe(candidate);
+      expect(taskManager.taskCollection[canonicalMainId]).toBe(occupiedTask);
+      expect(TaskFactory.createTask).not.toHaveBeenCalled();
+    });
+
     it('ignores a related ContactOwnerChanged task whose current agent is consult-only', () => {
       const childTaskId = 'consult-only-child-id';
       const data = createConferenceTaskData(childTaskId, previousOwnerId, taskId);
@@ -3066,7 +3197,43 @@ describe('TaskManager', () => {
       expect(secondTask.sendStateMachineEvent).not.toHaveBeenCalled();
     });
 
-    it('does not recover a new task when multiple stale related tasks become eligible from the payload', () => {
+    it('ignores ambiguous main-call media-key matches without creating a task', () => {
+      const mainMediaInteractionId = 'ambiguous-main-media-id';
+      const createMediaRelatedTask = (interactionId: string) => {
+        const data = createConferenceTaskData(interactionId, previousOwnerId, interactionId);
+        data.interaction.media = {
+          [mainMediaInteractionId]: {
+            mediaResourceId: mainMediaInteractionId,
+            mediaType: 'telephony',
+            mType: 'mainCall',
+            participants: [currentAgentId, previousOwnerId, promotedOwnerId],
+          },
+        };
+
+        return createMockTask(data);
+      };
+      const firstTask = createMediaRelatedTask('first-media-child-id');
+      const secondTask = createMediaRelatedTask('second-media-child-id');
+      taskManager.taskCollection = {
+        'first-media-child-id': firstTask,
+        'second-media-child-id': secondTask,
+      };
+      (TaskFactory.createTask as jest.Mock).mockClear();
+      const ownerChangeData = createPromotedAgentOwnerChangeData(
+        'promoted-media-child-id',
+        mainMediaInteractionId
+      );
+      delete ownerChangeData.interaction.mainInteractionId;
+
+      webSocketManagerMock.emit('message', JSON.stringify({data: ownerChangeData}));
+
+      expect(firstTask.sendStateMachineEvent).not.toHaveBeenCalled();
+      expect(secondTask.sendStateMachineEvent).not.toHaveBeenCalled();
+      expect(TaskFactory.createTask).not.toHaveBeenCalled();
+      expect(Object.values(taskManager.taskCollection)).toEqual([firstTask, secondTask]);
+    });
+
+    it('does not recover a new task when multiple stale related tasks exist', () => {
       const createStaleRelatedTask = (interactionId: string) => {
         const data = createConferenceTaskData(interactionId, previousOwnerId, taskId);
         data.interaction.media[taskId].participants = [previousOwnerId, promotedOwnerId];
@@ -3178,7 +3345,10 @@ describe('TaskManager', () => {
         expect.objectContaining({
           type: TaskEvent.HYDRATE,
           agentId: currentAgentId,
-          taskData: expect.objectContaining({interactionId: taskId}),
+          taskData: expect.objectContaining({
+            interactionId: taskId,
+            interaction: expect.objectContaining({state: 'conference'}),
+          }),
         })
       );
       expect(recoveredTask.sendStateMachineEvent).toHaveBeenNthCalledWith(
@@ -3192,6 +3362,7 @@ describe('TaskManager', () => {
       expect(taskManager.taskCollection['promoted-child-interaction-id']).toBeUndefined();
       expect(Object.values(taskManager.taskCollection)).toEqual([recoveredTask]);
       expect(recoveredTask.data.interaction.owner).toBe(currentAgentId);
+      expect(recoveredTask.listenerCount(TASK_EVENTS.TASK_HYDRATE)).toBe(1);
       expect(hydrateHandler).toHaveBeenCalledTimes(1);
       expect(hydrateHandler).toHaveBeenCalledWith(recoveredTask);
       expect(incomingHandler).not.toHaveBeenCalled();
@@ -3217,6 +3388,21 @@ describe('TaskManager', () => {
           data.interaction.isTerminated = true;
         },
       ],
+      [
+        'the interaction is not telephony',
+        (data) => {
+          data.interaction.mediaType = 'chat';
+        },
+      ],
+      [
+        'the payload has no stable interaction identifier',
+        (data) => {
+          data.interactionId = undefined;
+          data.interaction.interactionId = undefined;
+          delete data.interaction.mainInteractionId;
+          data.interaction.media = {};
+        },
+      ],
     ])('does not create a missing task when %s', (_description, mutatePayload) => {
       clearTasksAndFactoryHistory();
       const ownerChangeData = createPromotedAgentOwnerChangeData();

package/test/unit/spec/services/task/state-machine/TaskStateMachine.ts

@@ -539,6 +539,39 @@ describe('Task state machine', () => {
         } as any,
       });
 
+    it('hydrates a recovered active conference from IDLE to CONFERENCING', () => {
+      const service = startMachine();
+      const taskData = createTaskData({
+        agentId: 'agent-1',
+        interactionId: 'interaction-1',
+        mediaResourceId: 'interaction-1',
+        interaction: {
+          state: 'conference',
+          interactionId: 'interaction-1',
+          mainInteractionId: 'interaction-1',
+          owner: 'agent-1',
+          participants: {
+            'agent-1': {id: 'agent-1', pType: 'Agent', hasLeft: false},
+            'agent-2': {id: 'agent-2', pType: 'Agent', hasLeft: false},
+            'customer-1': {id: 'customer-1', pType: 'Customer', hasLeft: false},
+          },
+          media: {
+            'interaction-1': {
+              mediaResourceId: 'interaction-1',
+              mType: 'mainCall',
+              participants: ['agent-1', 'agent-2', 'customer-1'],
+              isHold: false,
+            },
+          },
+        } as any,
+      });
+
+      service.send({type: TaskEvent.HYDRATE, taskData});
+
+      expect(service.getSnapshot().value).toBe(TaskState.CONFERENCING);
+      expect(service.getSnapshot().context.taskData).toEqual(taskData);
+    });
+
     it('boots from IDLE to CONSULTING on CONSULTING_ACTIVE for split-leg ordering', () => {
       const service = startMachine();
       const taskData = createTaskData({