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

package/src/services/task/TaskManager.ts

@@ -27,6 +27,8 @@ import {
   shouldAutoAnswerTask,
 } from './TaskUtils';
 import TaskFactory from './TaskFactory';
+import AnswerCallOnWebexService from '../AnswerCallOnWebexService';
+import {getWebexCallingDeviceDetailsForAgent} from './WebexCallingUtils';
 import WebRTC from './voice/WebRTC';
 import {TaskEvent, type TaskEventPayload} from './state-machine';
 import {normalizeTaskData} from './taskDataNormalizer';
@@ -34,6 +36,11 @@ import {ApiAIAssistant} from '../ApiAiAssistant';
 
 const CC_EVENT_SET = new Set<CC_EVENTS>(Object.values(CC_EVENTS) as CC_EVENTS[]);
 
+const MAIN_INTERACTION_CORRELATED_EVENTS = new Set<CC_EVENTS>([
+  CC_EVENTS.AGENT_CONSULT_ENDED,
+  CC_EVENTS.PARTICIPANT_LEFT_CONFERENCE,
+]);
+
 const isCcEvent = (value: string): value is CC_EVENTS => CC_EVENT_SET.has(value as CC_EVENTS);
 
 /** @internal */
@@ -55,6 +62,7 @@ export default class TaskManager extends EventEmitter {
   private wrapupData: WrapupData;
   private agentId: string;
   private webRtcEnabled: boolean;
+  private answerCallOnWebexService?: AnswerCallOnWebexService;
   private apiAIAssistant?: ApiAIAssistant;
   /**
    * @param contact - Routing Contact layer. Talks to AQMReq layer to convert events to promises
@@ -148,6 +156,10 @@ export default class TaskManager extends EventEmitter {
     this.webRtcEnabled = webRtcEnabled;
   }
 
+  public setAnswerCallOnWebexService(answerCallOnWebexService: AnswerCallOnWebexService) {
+    this.answerCallOnWebexService = answerCallOnWebexService;
+  }
+
   private handleIncomingWebCall = (call: ICall) => {
     const currentTask = Object.values(this.taskCollection).find(
       (task) =>
@@ -187,12 +199,15 @@ export default class TaskManager extends EventEmitter {
    * @param ccEvent - The CC_EVENT type from WebSocket
    * @param payload - The event payload
    * @param agentId - Optional agent ID for state detection (needed for HYDRATE)
+   * @param task - Optional task instance for state-aware CONTACT_ENDED mapping
    * @returns TaskEventPayload for state machine or null if no mapping
    */
   private static mapEventToTaskStateMachineEvent(
     ccEvent: CC_EVENTS,
     payload: WebSocketPayload,
-    agentId?: string
+    agentId?: string,
+    task?: ITask,
+    enableWxBetterTogether?: boolean
   ): TaskEventPayload | null {
     const mediaResourceId =
       payload.mediaResourceId ||
@@ -299,16 +314,39 @@ export default class TaskManager extends EventEmitter {
       case CC_EVENTS.AGENT_CONFERENCE_TRANSFER_FAILED:
         return {type: TaskEvent.TRANSFER_FAILED, taskData: payload};
 
-      case CC_EVENTS.CONTACT_ENDED:
+      case CC_EVENTS.CONTACT_ENDED: {
+        const wrapUpRequired = isCampaignPreviewTask(payload)
+          ? false
+          : payload.agentsPendingWrapUp?.includes(agentId || '') || false;
+
+        // Post-accept wxApp outdial agent-end delivers ContactEnded instead of
+        // AgentOutboundFailed. Normalize to OUTBOUND_FAILED so state machine
+        // enters WRAPPING_UP and emits TASK_OUTDIAL_FAILED (AGENT_ENDS).
+        // Pre-accept cancelTask decline stays CONTACT_ENDED → TERMINATED (no wrapup).
+        if (
+          TaskManager.isAgentTerminatedOutdialWrapup(
+            payload,
+            wrapUpRequired,
+            task,
+            agentId,
+            enableWxBetterTogether
+          )
+        ) {
+          return {
+            type: TaskEvent.OUTBOUND_FAILED,
+            reason: 'AGENT_ENDS',
+            taskData: {...payload, wrapUpRequired: true},
+          };
+        }
+
         return {
           type: TaskEvent.CONTACT_ENDED,
           taskData: {
             ...payload,
-            wrapUpRequired: isCampaignPreviewTask(payload)
-              ? false
-              : payload.agentsPendingWrapUp?.includes(agentId || '') || false,
+            wrapUpRequired,
           },
         };
+      }
 
       case CC_EVENTS.AGENT_INVITE_FAILED:
         return {type: TaskEvent.INVITE_FAILED, reason: payload.reason};
@@ -319,8 +357,23 @@ export default class TaskManager extends EventEmitter {
       case CC_EVENTS.AGENT_CONTACT_OFFER_RONA:
         return {type: TaskEvent.RONA, taskData: payload, reason: payload.reason};
 
-      case CC_EVENTS.AGENT_OUTBOUND_FAILED:
-        return {type: TaskEvent.OUTBOUND_FAILED, taskData: payload, reason: payload.reason};
+      case CC_EVENTS.AGENT_OUTBOUND_FAILED: {
+        const isAgentTerminatedOutdial =
+          payload.interaction?.outboundType === 'OUTDIAL' &&
+          (payload.terminatingParty === 'Agent' || payload.reason === 'AGENT_ENDS');
+
+        const suppressOutdialFailedPopup =
+          isAgentTerminatedOutdial &&
+          !TaskManager.isWxAppManagedOutdialTask(agentId, payload, task, enableWxBetterTogether);
+
+        return {
+          type: TaskEvent.OUTBOUND_FAILED,
+          taskData: suppressOutdialFailedPopup
+            ? {...payload, suppressOutdialFailedPopup: true}
+            : payload,
+          reason: payload.reason,
+        };
+      }
 
       case CC_EVENTS.CAMPAIGN_PREVIEW_ACCEPT_FAILED:
         return {type: TaskEvent.CAMPAIGN_PREVIEW_ACCEPT_FAILED, taskData: payload};
@@ -371,6 +424,68 @@ export default class TaskManager extends EventEmitter {
     }
   }
 
+  /**
+   * True when the current agent's task is a wxApp-managed outdial (thick-client telephony).
+   */
+  private static isWxAppManagedOutdialTask(
+    agentId: string | undefined,
+    payload: WebSocketPayload,
+    task: ITask | undefined,
+    enableWxBetterTogether?: boolean
+  ): boolean {
+    const wxAppEnabled =
+      (task as {uiControlConfig?: {enableWxBetterTogether?: boolean}})?.uiControlConfig
+        ?.enableWxBetterTogether ??
+      enableWxBetterTogether ??
+      false;
+
+    if (!wxAppEnabled) {
+      return false;
+    }
+
+    const effectiveAgentId = agentId ?? task?.data?.agentId;
+    const participants = payload.interaction?.participants ?? task?.data?.interaction?.participants;
+    const details = getWebexCallingDeviceDetailsForAgent(effectiveAgentId, participants);
+
+    return details?.deviceType === 'wxApp';
+  }
+
+  /**
+   * True when ContactEnded represents an agent-terminated wxApp outdial that should
+   * enter wrapup with an outdial-failed popup (legacy AgentOutboundFailed parity).
+   */
+  private static isAgentTerminatedOutdialWrapup(
+    payload: WebSocketPayload,
+    wrapUpRequired: boolean,
+    task?: ITask,
+    agentId?: string,
+    enableWxBetterTogether?: boolean
+  ): boolean {
+    const isOutdial = payload.interaction?.outboundType === 'OUTDIAL';
+    const agentTerminated = payload.terminatingParty === 'Agent';
+
+    if (!isOutdial || !agentTerminated) {
+      return false;
+    }
+
+    if (!TaskManager.isWxAppManagedOutdialTask(agentId, payload, task, enableWxBetterTogether)) {
+      return false;
+    }
+
+    const wxAppAnswerPending =
+      (task as {uiControlConfig?: {wxAppAnswerPending?: boolean}})?.uiControlConfig
+        ?.wxAppAnswerPending ?? false;
+
+    // Pre-accept decline: decline() clears wxAppAnswerPending; backend may still send state wrapUp.
+    if (!wxAppAnswerPending && !wrapUpRequired) {
+      return false;
+    }
+
+    const interactionWrapUp = payload.interaction?.state === 'wrapUp';
+
+    return wrapUpRequired || interactionWrapUp || wxAppAnswerPending;
+  }
+
   /**
    * Register WebSocket message listeners for task events
    *
@@ -482,6 +597,10 @@ export default class TaskManager extends EventEmitter {
       }
     }
 
+    if (!task && MAIN_INTERACTION_CORRELATED_EVENTS.has(eventType)) {
+      task = this.findUniqueTaskByRelatedInteraction(message.data);
+    }
+
     const wasConsultedTask = Boolean(task?.data?.isConsulted);
     const computeWrapUpRequired = () => {
       if (message.data.wrapUpRequired !== undefined) {
@@ -507,7 +626,9 @@ export default class TaskManager extends EventEmitter {
     const stateMachineEvent = TaskManager.mapEventToTaskStateMachineEvent(
       eventType,
       adjustedPayload,
-      this.agentId
+      this.agentId,
+      task,
+      this.configFlags?.enableWxBetterTogether
     );
 
     LoggerProxy.info(`Handling task event ${eventType}`, {
@@ -524,6 +645,62 @@ export default class TaskManager extends EventEmitter {
     };
   }
 
+  /**
+   * 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.
+   */
+  private findUniqueTaskByRelatedInteraction(payload: WebSocketPayload): ITask | undefined {
+    const payloadInteractionIds = new Set(
+      [
+        payload.interactionId,
+        payload.interaction?.interactionId,
+        payload.interaction?.mainInteractionId,
+        payload.interaction?.parentInteractionId,
+        payload.interaction?.callProcessingDetails?.parentInteractionId,
+      ].filter((interactionId): interactionId is string => 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)
+          );
+        })
+      ),
+    ];
+
+    if (candidates.length === 1) {
+      return candidates[0];
+    }
+
+    if (candidates.length > 1) {
+      LoggerProxy.warn('Unable to correlate task event to a unique main interaction task', {
+        module: TASK_MANAGER_FILE,
+        method: 'findUniqueTaskByRelatedInteraction',
+        interactionId:
+          payload.interaction?.mainInteractionId ||
+          payload.interaction?.parentInteractionId ||
+          payload.interaction?.callProcessingDetails?.parentInteractionId ||
+          payload.interactionId,
+      });
+    }
+
+    return undefined;
+  }
+
   /**
    * Handle task lifecycle events and determine required actions
    *
@@ -647,7 +824,8 @@ export default class TaskManager extends EventEmitter {
         },
         this.configFlags,
         this.wrapupData,
-        this.agentId
+        this.agentId,
+        this.answerCallOnWebexService
       );
       this.setupTaskListeners(task);
       this.taskCollection[payload.interactionId] = task;
@@ -685,7 +863,8 @@ export default class TaskManager extends EventEmitter {
       taskData,
       this.configFlags,
       this.wrapupData,
-      this.agentId
+      this.agentId,
+      this.answerCallOnWebexService
     );
 
     this.setupTaskListeners(task);
@@ -725,7 +904,8 @@ export default class TaskManager extends EventEmitter {
         taskData,
         this.configFlags,
         this.wrapupData,
-        this.agentId
+        this.agentId,
+        this.answerCallOnWebexService
       );
       this.setupTaskListeners(task);
       this.taskCollection[payload.interactionId] = task;
@@ -753,6 +933,14 @@ export default class TaskManager extends EventEmitter {
       : taskData;
 
     task.updateTaskData(updateTaskData);
+
+    // A main-interaction lifecycle event can re-key a child consult task. Remove
+    // any aliases first so consumers never observe duplicate task entries.
+    Object.entries(this.taskCollection).forEach(([taskId, candidate]) => {
+      if (candidate === task && taskId !== taskData.interactionId) {
+        delete this.taskCollection[taskId];
+      }
+    });
     this.taskCollection[taskData.interactionId] = task;
 
     return task;
@@ -798,8 +986,10 @@ export default class TaskManager extends EventEmitter {
     task.on(TASK_EVENTS.TASK_CLEANUP, (t: ITask, options?: {removeFromCollection?: boolean}) => {
       this.handleTaskCleanup(t);
       if (options?.removeFromCollection) {
-        const interactionId = t?.data?.interactionId;
-        if (interactionId && this.taskCollection[interactionId]) {
+        const taskIsStillCollected = Object.values(this.taskCollection).some(
+          (candidate) => candidate === t
+        );
+        if (taskIsStillCollected) {
           this.removeTaskFromCollection(t);
         }
       }
@@ -811,7 +1001,11 @@ export default class TaskManager extends EventEmitter {
       task.cancelAutoWrapupTimer();
     }
     if (task?.data?.interactionId) {
-      delete this.taskCollection[task.data.interactionId];
+      Object.entries(this.taskCollection).forEach(([taskId, candidate]) => {
+        if (candidate === task) {
+          delete this.taskCollection[taskId];
+        }
+      });
       LoggerProxy.info(`Task removed from collection`, {
         module: TASK_MANAGER_FILE,
         method: METHODS.REMOVE_TASK_FROM_COLLECTION,
@@ -864,7 +1058,8 @@ export default class TaskManager extends EventEmitter {
         taskData,
         this.configFlags,
         this.wrapupData,
-        this.agentId
+        this.agentId,
+        this.answerCallOnWebexService
       );
       this.taskCollection[payload.interactionId] = task;
 
@@ -956,6 +1151,50 @@ export default class TaskManager extends EventEmitter {
     return {...this.taskCollection};
   }
 
+  /**
+   * Propagate runtime enableWxBetterTogether changes to config flags and active tasks.
+   */
+  public applyEnableWxBetterTogether(enabled: boolean): void {
+    if (this.configFlags) {
+      this.configFlags = {...this.configFlags, enableWxBetterTogether: enabled};
+    }
+
+    Object.values(this.taskCollection).forEach((task) => {
+      task.setEnableWxBetterTogether(enabled);
+      if (enabled) {
+        TaskManager.syncWxAppMuteFromCallDetailsForTask(task);
+      }
+    });
+  }
+
+  /**
+   * Propagate wxApp mute state from Mercury sync to active voice tasks.
+   */
+  public applyWxAppMuteStateFromSync(callId: string, muted: boolean): void {
+    Object.values(this.taskCollection).forEach((task) => {
+      task.applyWxAppMuteStateFromSync(callId, muted);
+    });
+  }
+
+  /**
+   * Re-seeds wxApp mute state from GET telephony/calls/{callId} for one task.
+   */
+  public static syncWxAppMuteFromCallDetailsForTask(task: ITask): void {
+    const sync = task.syncWxAppMuteFromCallDetails?.bind(task);
+    if (typeof sync === 'function') {
+      sync().catch(() => undefined);
+    }
+  }
+
+  /**
+   * Re-seeds wxApp mute for all engaged voice tasks (reload / runtime enable backfill).
+   */
+  public syncWxAppMuteFromCallDetailsForAllTasks(): void {
+    Object.values(this.taskCollection).forEach((task) => {
+      TaskManager.syncWxAppMuteFromCallDetailsForTask(task);
+    });
+  }
+
   public static getTaskManager(
     apiAIAssistant: ApiAIAssistant,
     contact: ReturnType<typeof routingContact>,

package/src/services/task/WebexCallingUtils.ts

@@ -0,0 +1,136 @@
+import {TaskState} from './state-machine/constants';
+
+export type WebexCallingDeviceDetails = {
+  deviceType: string;
+  deviceId: string;
+  deviceCallId: string;
+};
+
+type WebexCallingParticipant = {
+  id?: unknown;
+  deviceType?: unknown;
+  deviceCallId?: unknown;
+  deviceId?: unknown;
+};
+
+const normalizeId = (id: unknown): string | undefined => {
+  if (typeof id !== 'string') {
+    return undefined;
+  }
+
+  const normalizedId = id.trim();
+
+  return normalizedId === '' ? undefined : normalizedId;
+};
+
+const isParticipantsById = (participants: unknown): participants is Record<string, unknown> =>
+  Boolean(participants) &&
+  typeof participants === 'object' &&
+  !Array.isArray(participants) &&
+  !(participants instanceof Map);
+
+const hasWebexCallingDeviceDetails = (
+  participant: unknown
+): participant is WebexCallingParticipant &
+  Pick<WebexCallingDeviceDetails, 'deviceCallId' | 'deviceId'> => {
+  const participantDetails = participant as WebexCallingParticipant | undefined;
+
+  return (
+    typeof participantDetails?.deviceCallId === 'string' &&
+    participantDetails.deviceCallId.trim() !== '' &&
+    typeof participantDetails?.deviceId === 'string' &&
+    participantDetails.deviceId.trim() !== ''
+  );
+};
+
+const isWebexCallingParticipantForAgent = (
+  participant: unknown,
+  agentId: string
+): participant is WebexCallingParticipant &
+  Pick<WebexCallingDeviceDetails, 'deviceCallId' | 'deviceId'> => {
+  const participantDetails = participant as WebexCallingParticipant | undefined;
+
+  return (
+    normalizeId(participantDetails?.id) === agentId && hasWebexCallingDeviceDetails(participant)
+  );
+};
+
+const getWebexCallingDeviceDetails = (
+  participant: WebexCallingParticipant &
+    Pick<WebexCallingDeviceDetails, 'deviceCallId' | 'deviceId'>
+): WebexCallingDeviceDetails => ({
+  deviceType: typeof participant.deviceType === 'string' ? participant.deviceType : '',
+  deviceId: participant.deviceId,
+  deviceCallId: participant.deviceCallId,
+});
+
+export function getWebexCallingDeviceDetailsForAgent(
+  agentId: string | undefined,
+  participants: unknown
+): WebexCallingDeviceDetails | undefined {
+  const normalizedAgentId = normalizeId(agentId);
+  if (!normalizedAgentId || !isParticipantsById(participants)) {
+    return undefined;
+  }
+
+  const agentParticipant = participants[normalizedAgentId];
+  const matchingAgentParticipant = hasWebexCallingDeviceDetails(agentParticipant)
+    ? agentParticipant
+    : Object.values(participants).find((participant) =>
+        isWebexCallingParticipantForAgent(participant, normalizedAgentId)
+      );
+
+  if (!matchingAgentParticipant || !hasWebexCallingDeviceDetails(matchingAgentParticipant)) {
+    return undefined;
+  }
+
+  return getWebexCallingDeviceDetails(matchingAgentParticipant);
+}
+
+export function isWebexCallingCallForAgent(
+  agentId: string | undefined,
+  participants: unknown
+): boolean {
+  return Boolean(getWebexCallingDeviceDetailsForAgent(agentId, participants));
+}
+
+/** Matches wxAppVoiceMethods.getWebexCallingCallId engaged semantics for uiControls. */
+export function isWxAppEngagedForControls(
+  enableWxBetterTogether: boolean,
+  agentId: string | undefined,
+  participants: unknown,
+  state: TaskState
+): boolean {
+  if (!enableWxBetterTogether) {
+    return false;
+  }
+
+  if (
+    !state ||
+    state === TaskState.OFFERED ||
+    state === TaskState.IDLE ||
+    state === TaskState.WRAPPING_UP ||
+    state === TaskState.TERMINATED ||
+    state === TaskState.COMPLETED
+  ) {
+    return false;
+  }
+
+  const details = getWebexCallingDeviceDetailsForAgent(agentId, participants);
+
+  return details?.deviceType === 'wxApp';
+}
+
+export function decodedLineOwnerId(lineOwnerId?: string): string | undefined {
+  if (!lineOwnerId) {
+    return undefined;
+  }
+
+  try {
+    const decoded = atob(lineOwnerId);
+
+    return decoded.split('/').pop();
+  } catch {
+    return undefined;
+  }
+}

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

@@ -35,6 +35,7 @@
 - `state?: SnapshotFrom<TaskStateMachine>`
 - `autoWrapup?: AutoWrapup`
 - `uiControls: TaskUIControls` (getter)
+  - includes ordered, action-specific `consultTransferDestinations` computed from Task profile configuration and live interaction data
 
 **Methods**