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

package/ai-docs/features/contact-owner-change-refactor.md

@@ -0,0 +1,78 @@
+# Contact Owner Change Refactor
+
+## Scope
+
+This change refactors only the owner-change propagation introduced by
+webex-js-sdk PR #5187. It preserves the behavior required by Participant Drop:
+when the backend promotes a new primary Agent, existing SDK tasks publish the
+updated owner through the existing `task:hydrate` event so widgets immediately
+recompute the Primary label, icon, and Drop permission.
+
+There is no public API, routing-event, state-machine transition, Participant
+Drop request, or widget contract change.
+
+## Retained behavior
+
+| Behavior | Why it remains | Existing-flow impact |
+|---|---|---|
+| Map an owner-changing `ContactUpdated` to `CONTACT_OWNER_CHANGED` | Remaining conference Agents receive `ContactUpdated`, not necessarily `ContactOwnerChanged`. The existing state-machine action synchronizes task data and emits `task:hydrate`. | Preserves immediate owner/Primary UI updates without adding a new public event or state transition. Same-owner and owner-less updates remain data-only. |
+| Resolve `ContactOwnerChanged` by exact ID before related IDs | Exact identity remains the safest and existing lookup contract. | Existing exact task routing is unchanged. |
+| Resolve one unique related task using nested interaction IDs, the collection key, or the `mainCall` media-map key | Some supported owner-change payloads identify the surviving call through a child top-level ID and omit `mainInteractionId`. | Preserves cross-channel promotion across the documented payload variants. Task aliases are deduplicated and ambiguous matches remain ignored. |
+| Accept current-Agent main-leg evidence from the existing task or authoritative incoming promotion | A local child task can be briefly stale when the owner-change payload first proves promotion. | Preserves the stale-snapshot fix while continuing to reject ordinary consult-only tasks. |
+| Recover a missing promoted-Agent task from a complete `ContactOwnerChanged` payload | Reloaded or desynchronized clients may receive the authoritative promotion before normal task creation catches up. Agent Desktop supports the same recovery path. | A complete telephony main-leg payload restores the task under the stable main interaction ID, emits one `task:hydrate`, and emits no synthetic `task:incoming`. |
+| Preserve a confirmed owner across a late `ParticipantLeftConference` snapshot that still names the departed owner | Participant Drop can deliver owner change and participant-left notifications in either order. | Prevents the Primary UI from reverting after it has already received the authoritative new owner. |
+
+## Refactoring and safety constraints
+
+Owner-change correlation and recovery retain the following protections:
+
+- generic lifecycle-event correlation is unchanged; collection-key and media-key
+  matching are enabled only for `ContactOwnerChanged`;
+- only a task selected by the related-interaction fallback may be re-keyed;
+- conflicting task/payload main IDs are ignored;
+- a stable main key already owned by a different Task causes the event to be
+  ignored; and
+- an exact child task is never normalized over a distinct main task;
+- aliases of the same Task object are deduplicated before uniqueness is tested;
+- consult-only and ambiguous matches are rejected; and
+- missing-task recovery is rejected whenever any related task or canonical-key
+  occupant already exists.
+
+This closes the PR review scenario where an exact child task could previously
+be normalized to a main key and silently replace the actual main Task, orphaning
+its listeners and resources.
+
+Recovery is intentionally narrow. It requires a non-terminal telephony payload,
+`interaction.owner` equal to the current Agent, an active participant entry for
+that Agent on an `mType: mainCall` leg, and a stable main interaction ID. It does
+not use `toOwner`, elect an owner locally, or create a task for a missing
+owner-changing `ContactUpdated` event.
+
+## Resulting event flow
+
+1. The backend chooses the new `interaction.owner`.
+2. The promoted Agent receives `ContactOwnerChanged`; other surviving Agents may
+   receive an owner-changing `ContactUpdated`.
+3. TaskManager first uses an exact task match and otherwise accepts one unique,
+   eligible related task.
+4. If the promoted Agent has no related task, a complete authoritative payload
+   may recover the task under its stable main interaction ID. An internal
+   pre-listener `HYDRATE` restores the actor state without publishing an event.
+5. Both notification forms use the existing `CONTACT_OWNER_CHANGED` state-machine
+   event.
+6. The state machine updates task/context data, keeps the current task state, and
+   emits exactly one public `task:hydrate`.
+7. Widget consumers receive the hydrated Task and render the backend-provided
+   owner immediately.
+
+`ParticipantLeftConference` continues through its existing event/state-machine
+path. No client elects a successor and no Drop completion fabricates an owner.
+
+## Verification coverage
+
+The focused TaskManager tests cover owner-changing versus data-only
+`ContactUpdated`, exact and child-keyed correlation, collection-key and
+`mainCall` media-key payloads, stale incoming promotion evidence, consult-only
+and ambiguous rejection, narrow missing-task recovery, listener/alias safety,
+later `AgentContact` and `ContactMerged` reuse, exact-child/main-task collision
+protection, and both owner-change/participant-left orders.

package/dist/services/task/TaskManager.js

@@ -690,6 +690,7 @@ class TaskManager extends _events.default {
     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
@@ -703,7 +704,35 @@ class TaskManager extends _events.default {
       }
     }
     if (!task && eventType === _types2.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;
+    if (task && eventType === _types2.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.default.warn('Unable to safely correlate owner change to the main interaction task', {
+          module: _constants.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)) {
       task = this.findUniqueTaskByRelatedInteraction(message.data);
@@ -722,8 +751,11 @@ class TaskManager extends _events.default {
       ...message.data,
       wrapUpRequired: computeWrapUpRequired()
     } : message.data;
-    if (task && eventType === _types2.CC_EVENTS.CONTACT_OWNER_CHANGED) {
-      adjustedPayload = TaskManager.preserveMainTaskIdentity(task, adjustedPayload);
+    if (task && ownerChangeMainInteractionId) {
+      adjustedPayload = {
+        ...adjustedPayload,
+        interactionId: ownerChangeMainInteractionId
+      };
     }
     if (task && eventType === _types2.CC_EVENTS.PARTICIPANT_LEFT_CONFERENCE) {
       adjustedPayload = TaskManager.preserveConfirmedOwner(task, adjustedPayload);
@@ -744,47 +776,12 @@ class TaskManager extends _events.default {
       stateMachineEvent
     };
   }
-
-  /**
-   * 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];
   }
@@ -797,22 +794,6 @@ class TaskManager extends _events.default {
     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
@@ -845,8 +826,8 @@ class TaskManager extends _events.default {
    * 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, candidateFilter = () => true) {
-    const candidates = this.findRelatedTasks(payload).filter(candidateFilter);
+  findUniqueTaskByRelatedInteraction(payload, candidateFilter = () => true, options = {}) {
+    const candidates = this.findRelatedTasks(payload, options).filter(candidateFilter);
     if (candidates.length === 1) {
       return candidates[0];
     }
@@ -864,12 +845,12 @@ class TaskManager extends _events.default {
       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)));
+    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(relatedInteractionId => Boolean(relatedInteractionId)));
     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));
+      return candidateInteractionIds.some(relatedInteractionId => Boolean(relatedInteractionId) && payloadInteractionIds.has(relatedInteractionId));
     }).map(([, candidate]) => candidate))];
   }