@webex/contact-center 3.12.0-llmrefactor.7 → 3.12.0-llmrefactor.9

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

@@ -78,7 +78,7 @@ See root `CONTRACTS.md` for the package-level state-control export.
 | TASK_STATE_MACHINE-R-005 | Keep authentication and credentials outside the state-machine layer; it receives typed Task data/events and never invokes authenticated transport. | Pure transition logic remains reusable and cannot leak or mutate host authentication state. | `src/services/task/state-machine/TaskStateMachine.ts`, `src/services/task/state-machine/types.ts` | `test/unit/spec/services/task/state-machine/TaskStateMachine.ts` | None; security/auth applicability is explicitly N/A. | PRESENT |
 | TASK_STATE_MACHINE-R-006 | Treat `UIControlConfig` values as Task-supplied capability configuration, not rollout flags evaluated or owned by the state machine. | Rollout and profile policy must be resolved before actor construction so transitions remain deterministic. | `src/services/task/state-machine/types.ts`, `src/services/task/Task.ts` | `test/unit/spec/services/task/Task.ts` | None; rollout ownership is explicit. | PRESENT |
 | TASK_STATE_MACHINE-R-007 | Keep logging and metrics in Task/TaskManager integration; the state-machine implementation has no LoggerProxy or MetricsManager dependency. | Separating observability side effects from guards/actions preserves deterministic transition tests. | `src/services/task/state-machine/TaskStateMachine.ts`, `src/services/task/Task.ts` | `test/unit/spec/services/task/state-machine/TaskStateMachine.ts`, `test/unit/spec/services/task/Task.ts` | None; observability ownership is explicit. | PRESENT |
-| TASK_STATE_MACHINE-R-008 | `CONTACT_OWNER_CHANGED` must synchronize task/context data and emit `task:hydrate` without transitioning state. A TaskManager-recovered promoted-Agent task first receives an internal IDLE `HYDRATE` before listener installation, then the original owner-change event produces exactly one external hydrate and no incoming event. TaskManager maps an owner-changing `ContactUpdated` for an existing task to that owner-change event, while same-owner or owner-less updates remain `CONTACT_UPDATED`; missing-task `ContactUpdated` does not create a task. It also preserves an already confirmed active owner from a late participant-left snapshot that still names the departed owner. Participant Drop must rely on the existing `ParticipantLeftConference` mapping rather than adding an initiating state event. From every active call-control state, `PARTICIPANT_LEAVE` terminates or wraps the current Agent only when the event names that Agent, marks that Agent `hasLeft`, or removes a previously active Agent from the participant map; an event naming another participant cannot infer self-departure from a partial media roster. `CONSULT_END` evaluates the same explicit evidence before initiator recovery and additionally supports the narrow from-conference nested-consult race where a previously main-leg Agent is absent from the updated `mainCall` but remains active in the participant map and present on the consult leg. Removed accepted Agents emit `task:consultEnd` plus `task:end`, surviving initiators recover to their main call, and an unaccepted OFFERED consultee emits only `task:consultEnd`. Missing, partial, contradictory, or ordinary CONNECTED/HELD media membership is non-terminal, and starting Consult must preserve the prior task snapshot used by the guard. | Owner-sensitive consumers must rerender promptly while owner selection, participant removal, consult removal, and narrowly scoped desynchronization recovery remain backend-authoritative and compatible with existing incoming-task callback behavior. | `src/services/task/state-machine/TaskStateMachine.ts`, `src/services/task/state-machine/actions.ts`, `src/services/task/state-machine/guards.ts`, `src/services/task/TaskManager.ts` | `test/unit/spec/services/task/Task.ts`, `test/unit/spec/services/task/TaskManager.ts`, `test/unit/spec/services/task/state-machine/TaskStateMachine.ts`, `test/unit/spec/services/task/state-machine/guards.ts` | Backend ownership-successor selection and delivery of complete recovery payloads are outside this module. | PRESENT |
+| TASK_STATE_MACHINE-R-008 | `CONTACT_OWNER_CHANGED` must synchronize task/context data and emit `task:hydrate` without transitioning state. A TaskManager-recovered promoted-Agent task first receives an internal IDLE `HYDRATE` before listener installation, then the original owner-change event produces exactly one external hydrate and no incoming event. TaskManager maps an owner-changing `ContactUpdated` for an existing task to that owner-change event, while same-owner or owner-less updates remain `CONTACT_UPDATED`; missing-task `ContactUpdated` does not create a task. It also preserves an already confirmed active owner from a late participant-left snapshot that still names the departed owner. Participant Drop must rely on the existing `ParticipantLeftConference` mapping rather than adding an initiating state event. `PARTICIPANT_LEAVE` is handled in `HELD`, `RESUME_INITIATING`, `CONSULTING`, `CONSULT_INITIATING`, and `CONFERENCING`; `CONNECTED`, `HOLD_INITIATING`, and `CONF_INITIATING` ignore the event. The current Agent is treated as departed only when the event names that Agent or the updated participants map omits that Agent (EP-DN removal). Remaining in the map with `hasLeft`, or disappearing only from `mainCall` media, is non-terminal. `CONSULT_END` does not use mainCall membership as self-departure evidence. Removed accepted Agents emit `task:consultEnd` plus `task:end`, surviving initiators recover to their main call, and an unaccepted OFFERED consultee emits only `task:consultEnd`. Starting Consult must preserve the prior task snapshot used by the guard. | Owner-sensitive consumers must rerender promptly while owner selection, participant removal, consult removal, and narrowly scoped desynchronization recovery remain backend-authoritative and compatible with existing incoming-task callback behavior. | `src/services/task/state-machine/TaskStateMachine.ts`, `src/services/task/state-machine/actions.ts`, `src/services/task/state-machine/guards.ts`, `src/services/task/TaskManager.ts` | `test/unit/spec/services/task/Task.ts`, `test/unit/spec/services/task/TaskManager.ts`, `test/unit/spec/services/task/state-machine/TaskStateMachine.ts`, `test/unit/spec/services/task/state-machine/guards.ts` | Backend ownership-successor selection and delivery of complete recovery payloads are outside this module. | PRESENT |
 
 ## Design Overview
 TaskManager maps Contact Center notifications to `TaskEvent` values. Each Task sends those events to its XState actor built by `createTaskStateMachine()`. The configuration applies guards and named actions, updates `TaskContext`, and computes UI controls. Task supplies the integration-specific `syncTaskDataFromEvent` implementation through machine options; it is not a default action in `actions.ts`.
@@ -524,10 +524,8 @@ didCurrentAgentLeaveMainInteraction(context, event) {
   const participantIdFromEvent = 'participantId' in event ? event.participantId : undefined;
   const participantId = participantIdFromEvent ?? event.taskData?.participantId;
   if (Boolean(participantId) && participantId === selfAgentId) return true;
-  // Explicit hasLeft or removal of a previously active self from the participant map is terminal.
-  // PARTICIPANT_LEAVE naming another participant does not infer self departure from media.
-  // Only a from-conference CONSULT_END may compare mainCall membership, and only when self
-  // remains active in the participant map and on the consult leg. Partial ordinary calls are false.
+  // Self missing from the updated participants map is terminal (EP-DN removal).
+  // Remaining in the map with hasLeft, or disappearing only from mainCall media, is not.
 }
 
 // True when this agent initiated the conference transfer (widgets or desktop).
@@ -1791,7 +1789,7 @@ Complete mapping from backend CC_EVENTS to internal TaskEvent types.
 | `PARTICIPANT_JOINED_CONFERENCE`    | `CONFERENCE_START`            | `CONSULTING` / `CONF_INITIATING` / `CONFERENCING`    | `CONFERENCING` / same                                                         | Conference participant joined     |
 | `AGENT_CONSULT_CONFERENCE_FAILED`  | `CONFERENCE_FAILED`           | `CONF_INITIATING`                                    | `CONSULTING`                                                                  | Merge fail fallback               |
 | `AGENT_CONSULT_CONFERENCE_ENDED`   | `CONFERENCE_END`              | `CONFERENCING`                                       | `WRAPPING_UP` / `CONNECTED` / `TERMINATED`                                    | Guard-driven                      |
-| `PARTICIPANT_LEFT_CONFERENCE`      | `PARTICIPANT_LEAVE`           | `CONSULTING` / `CONFERENCING`                        | `WRAPPING_UP` / `TERMINATED` / `CONNECTED` / same                             | Ownership + downgrade guards      |
+| `PARTICIPANT_LEFT_CONFERENCE`      | `PARTICIPANT_LEAVE`           | `HELD` / `RESUME_INITIATING` / `CONSULTING` / `CONSULT_INITIATING` / `CONFERENCING` | `WRAPPING_UP` / `TERMINATED` / `CONNECTED` / same | Named self or omitted from participant map; `CONNECTED` / `HOLD_INITIATING` / `CONF_INITIATING` ignore |
 | `AGENT_CONFERENCE_TRANSFERRED`     | `TRANSFER_CONFERENCE_SUCCESS` | `CONSULTING` / `CONFERENCING`                        | `WRAPPING_UP` / `CONFERENCING` / `TERMINATED` / same                          | Initiator/receiver dependent      |
 
 - `AGENT_CONTACT_UNASSIGNED` -> returns `null` in mapper (`TaskManager.mapEventToTaskStateMachineEvent`)
@@ -1840,7 +1838,7 @@ Complete mapping from backend CC_EVENTS to internal TaskEvent types.
 | API `task.dropConferenceParticipant()` | None                    | No direct state transition                                 | AQM waits for backend `ParticipantLeftConference`; that event follows the existing `PARTICIPANT_LEAVE` path |
 | `AgentConsultConferenced`        | `CONFERENCE_START`            | CONSULTING/CONF_INITIATING → CONFERENCING                  | `handleConferenceStarted` path                                                                |
 | `ParticipantJoinedConference`    | `CONFERENCE_START`            | CONFERENCING → CONFERENCING                                | Refresh + emit conference started                                                             |
-| `ParticipantLeftConference`      | `PARTICIPANT_LEAVE`           | Any active call-control state → WRAPPING_UP / TERMINATED / CONNECTED / stay | Uses `didCurrentAgentLeaveMainInteraction`, `shouldWrapUp`, `shouldDowngradeConferenceToConnected` |
+| `ParticipantLeftConference`      | `PARTICIPANT_LEAVE`           | HELD / RESUME_INITIATING / CONSULTING / CONSULT_INITIATING / CONFERENCING → WRAPPING_UP / TERMINATED / CONNECTED / stay; CONNECTED / HOLD_INITIATING / CONF_INITIATING ignore | Uses `didCurrentAgentLeaveMainInteraction` (named self or omitted from participant map), `shouldWrapUp`, `shouldDowngradeConferenceToConnected` |
 | `AgentConsultConferenceEnded`    | `CONFERENCE_END`              | CONFERENCING → WRAPPING_UP / CONNECTED / TERMINATED        | Guard-based branch                                                                            |
 | `AgentConsultConferenceFailed`   | `CONFERENCE_FAILED`           | CONF_INITIATING → CONSULTING                               | Merge failed fallback                                                                         |
 | `AgentConferenceTransferred`     | `TRANSFER_CONFERENCE_SUCCESS` | CONSULTING/CONFERENCING branch logic                       | Initiator/receiver dependent                                                                  |

package/src/services/task/state-machine/guards.ts

@@ -364,10 +364,10 @@ export const guards = {
   /**
    * True when an updated lifecycle event shows that this agent left the main interaction.
    *
-   * Explicit self-participant evidence is authoritative. Main-call membership is used only
-   * for the from-conference nested-consult race where CONSULT_END still represents the agent as
-   * active on the consult leg after removing them from the main leg. Partial or ordinary call
-   * snapshots are not treated as a departure.
+   * Returns true when the event names this agent, or when this agent is absent from the
+   * updated participants map. EP-DN payloads remove the leaving participant instead of
+   * setting hasLeft. Remaining in the map with hasLeft, or disappearing only from
+   * mainCall media, is not treated as departure.
    */
   didCurrentAgentLeaveMainInteraction: ({context, event}: GuardParams): boolean => {
     const taskData = getTaskDataFromEvent(event);
@@ -383,65 +383,9 @@ export const guards = {
     if (Boolean(participantId) && participantId === selfAgentId) {
       return true;
     }
-
-    // Routing represents self-departure either by naming the participant or by retaining the
-    // participant entry with hasLeft set. Agent Desktop treats both representations as terminal.
-    const currentParticipant = taskData?.interaction?.participants?.[selfAgentId];
-    if (currentParticipant?.hasLeft === true) {
-      return true;
-    }
-
-    // A participant-left event that explicitly identifies somebody else must not use a
-    // potentially partial participant or media roster to infer that self also departed.
-    if (
-      event?.type === TaskEvent.PARTICIPANT_LEAVE &&
-      Boolean(participantId) &&
-      participantId !== selfAgentId
-    ) {
-      return false;
-    }
-
-    const previousParticipants = context.taskData?.interaction?.participants;
-    const updatedParticipants = taskData?.interaction?.participants;
-    const wasPreviouslyActive = Boolean(
-      previousParticipants?.[selfAgentId] && previousParticipants[selfAgentId].hasLeft !== true
-    );
-    // Some EP-DN lifecycle payloads remove the participant entry instead of setting hasLeft.
-    // Requiring a previously active entry prevents an incomplete initial snapshot from ending a task.
-    if (updatedParticipants && wasPreviouslyActive && !(selfAgentId in updatedParticipants)) {
-      return true;
-    }
-
-    const previousMainMedia = Object.values(context.taskData?.interaction?.media ?? {}).filter(
-      (media) => media?.mType === 'mainCall'
-    );
-    const updatedMainMedia = Object.values(taskData?.interaction?.media ?? {}).filter(
-      (media) => media?.mType === 'mainCall'
-    );
-    const wasPreviouslyInMainCall = previousMainMedia.some((media) =>
-      media.participants?.includes(selfAgentId)
-    );
-    const remainsInMainCall = updatedMainMedia.some((media) =>
-      media.participants?.includes(selfAgentId)
-    );
-    // A hasLeft participant returned above, so presence here means the updated map keeps self active.
-    const remainsActiveInParticipantMap = Boolean(currentParticipant);
-    const remainsOnConsultLeg = Object.values(taskData?.interaction?.media ?? {}).some(
-      (media) => media?.mType === MEDIA_TYPE_CONSULT && media.participants?.includes(selfAgentId)
-    );
-
-    // Agent Desktop uses mainCall membership for AgentConsultEnded cleanup. Restrict that fallback
-    // to a consult that originated from conference and require corroborating active-map and
-    // consult-leg membership so ordinary partial CONNECTED/HELD payloads cannot terminate a task.
-    if (
-      event?.type === TaskEvent.CONSULT_END &&
-      context.consultFromConference === true &&
-      updatedMainMedia.length > 0 &&
-      wasPreviouslyInMainCall &&
-      !remainsInMainCall &&
-      remainsActiveInParticipantMap &&
-      remainsOnConsultLeg
-    ) {
+    // EP-DN payloads remove the leaving participant from the map instead of setting hasLeft.
+    const participants = taskData?.interaction?.participants;
+    if (participants && !(selfAgentId in participants)) {
       return true;
     }
 

package/src/services/task/voice/Voice.ts

@@ -41,12 +41,20 @@ import {
   isWebexAppInboundCallingOffer as wxIsWebexAppInboundCallingOffer,
   mapWxAppVoiceError,
   runWxAppAccept,
+  runWxAppOutdialDecline,
   runWxAppReject,
   runWxAppToggleMute,
   runWxAppTransmitDtmf,
   WxAppVoiceDependencies,
   WxAppVoiceLifecycle,
 } from './wxAppVoiceMethods';
+import {
+  deriveWxAppAcceptReason,
+  logWxAppMercuryMuteSync,
+  logWxAppOfferDecision,
+  callIdSuffix,
+  WxAppAcceptReason,
+} from '../../wxAppDiagnosticLogging';
 
 export default class Voice extends Task implements IVoice {
   private static readonly WXAPP_MUTE_SYNC_RETRY_DELAY_MS = 50;
@@ -58,7 +66,9 @@ export default class Voice extends Task implements IVoice {
   private wxAppAnswerPending = false;
   private wxAppAcceptInFlight = false;
   private wxAppMuteSyncInFlight?: Promise<boolean | undefined>;
-  private wxAppMuteToggleInFlight?: Promise<void>;
+  private wxAppMuteToggleTail: Promise<void> = Promise.resolve();
+  private wxAppDtmfTail: Promise<void> = Promise.resolve();
+  private lastLoggedWxAppAcceptReason?: WxAppAcceptReason;
 
   constructor(
     contact: ReturnType<typeof routingContact>,
@@ -95,6 +105,7 @@ export default class Voice extends Task implements IVoice {
       enableWxBetterTogether: this.enableWxBetterTogether,
       answerCallOnWebexService: this.answerCallOnWebexService,
       agentId: this.agentId,
+      metricsManager: this.metricsManager,
       getTaskData: () => this.data,
       getTaskState: () => this.stateMachineService?.getSnapshot?.()?.value as TaskState | undefined,
       getWxAppMuted: () => this.wxAppMuted,
@@ -135,17 +146,98 @@ export default class Voice extends Task implements IVoice {
     this.updateUiControls(true);
   }
 
+  protected updateUiControls(forceEmit = false): void {
+    super.updateUiControls(forceEmit);
+    this.logWxAppOfferDecisionIfNeeded();
+  }
+
+  private logWxAppOfferDecisionIfNeeded(): void {
+    if (!this.enableWxBetterTogether) {
+      return;
+    }
+
+    const state = this.stateMachineService?.getSnapshot?.()?.value as TaskState | undefined;
+    if (state !== TaskState.OFFERED) {
+      return;
+    }
+
+    const accept = this.currentUiControls?.main?.accept;
+    if (!accept?.isVisible) {
+      return;
+    }
+
+    const deps = this.getWxAppVoiceDependencies();
+    const isOutdial = this.data?.interaction?.outboundType === 'OUTDIAL';
+    const isWxAppInboundOffer = this.isWebexAppInboundCallingOffer();
+    const isWxAppOutdialOffer = this.isWebexAppCallingOffer() && isOutdial;
+    const deviceDetails = getCallingDeviceDetails(deps);
+    const acceptReason = deriveWxAppAcceptReason({
+      isWxAppInboundOffer,
+      isWxAppOutdialOffer,
+      isWebrtc: this.uiControlConfig.voiceVariant === VOICE_VARIANT.WEBRTC,
+      isOutdial,
+      wxAppAcceptInFlight: this.wxAppAcceptInFlight,
+      wxAppAnswerPending: this.wxAppAnswerPending,
+      enableWxBetterTogether: this.enableWxBetterTogether,
+      hasDeviceCallId: Boolean(deviceDetails?.deviceCallId),
+    });
+
+    if (acceptReason === this.lastLoggedWxAppAcceptReason) {
+      return;
+    }
+
+    this.lastLoggedWxAppAcceptReason = acceptReason;
+
+    logWxAppOfferDecision({
+      interactionId: this.data.interactionId,
+      acceptVisible: accept.isVisible,
+      acceptEnabled: accept.isEnabled,
+      acceptReason,
+      wxAppParticipantDeviceType: deviceDetails?.deviceType,
+      hasDeviceCallId: Boolean(deviceDetails?.deviceCallId),
+    });
+  }
+
   public applyWxAppMuteStateFromSync(incomingCallId: string, muted: boolean): void {
     if (!this.enableWxBetterTogether) {
       return;
     }
 
     const activeCallId = this.getWebexCallingCallId();
-    if (!activeCallId || !incomingCallId.endsWith(activeCallId) || this.wxAppMuted === muted) {
+    const incomingSuffix = callIdSuffix(incomingCallId);
+    const activeSuffix = callIdSuffix(activeCallId);
+
+    if (!activeCallId || !incomingCallId.endsWith(activeCallId)) {
+      logWxAppMercuryMuteSync({
+        phase: 'dropped',
+        muted,
+        callIdSuffix: incomingSuffix,
+        interactionId: this.data.interactionId,
+        dropReason: !activeCallId ? 'no_active_wxApp_call' : 'call_id_mismatch',
+      });
+
+      return;
+    }
+
+    if (this.wxAppMuted === muted) {
+      logWxAppMercuryMuteSync({
+        phase: 'dropped',
+        muted,
+        callIdSuffix: incomingSuffix,
+        interactionId: this.data.interactionId,
+        dropReason: 'mute_state_unchanged',
+      });
+
       return;
     }
 
     this.wxAppMuted = muted;
+    logWxAppMercuryMuteSync({
+      phase: 'applied',
+      muted,
+      callIdSuffix: activeSuffix,
+      interactionId: this.data.interactionId,
+    });
     this.emit(TASK_EVENTS.TASK_WXAPP_MUTE_STATE_UPDATED, {muted});
   }
 
@@ -354,7 +446,9 @@ export default class Voice extends Task implements IVoice {
       ]);
 
       this.setWxAppAnswerPending(false);
-      const response = await this.contact.cancelTask({interactionId});
+      const response = await runWxAppOutdialDecline(this.getWxAppVoiceDependencies(), () =>
+        this.contact.cancelTask({interactionId})
+      );
 
       this.metricsManager.trackEvent(
         METRIC_EVENT_NAMES.TASK_DECLINE_SUCCESS,
@@ -388,25 +482,13 @@ export default class Voice extends Task implements IVoice {
    */
   public async toggleMute(options?: TaskToggleMuteOptions): Promise<void> {
     if (this.enableWxBetterTogether && this.getWebexCallingCallId()) {
-      if (this.wxAppMuteToggleInFlight) {
-        await this.wxAppMuteToggleInFlight.catch(() => undefined);
-      }
-
-      const togglePromise = runWxAppToggleMute(
-        this.getWxAppVoiceDependencies(),
-        this.createWxAppLifecycle(),
-        options
-      );
-
-      this.wxAppMuteToggleInFlight = togglePromise;
-      togglePromise
-        .finally(() => {
-          if (this.wxAppMuteToggleInFlight === togglePromise) {
-            this.wxAppMuteToggleInFlight = undefined;
-          }
-        })
-        .catch(() => undefined);
+      const togglePromise = this.wxAppMuteToggleTail
+        .catch(() => undefined)
+        .then(() =>
+          runWxAppToggleMute(this.getWxAppVoiceDependencies(), this.createWxAppLifecycle(), options)
+        );
 
+      this.wxAppMuteToggleTail = togglePromise.catch(() => undefined);
       await togglePromise;
 
       return;
@@ -420,11 +502,18 @@ export default class Voice extends Task implements IVoice {
    */
   public async transmitDtmf(options: TaskTransmitDtmfOptions): Promise<void> {
     if (this.enableWxBetterTogether && this.getWebexCallingCallId()) {
-      await runWxAppTransmitDtmf(
-        this.getWxAppVoiceDependencies(),
-        this.createWxAppLifecycle(),
-        options
-      );
+      const dtmfPromise = this.wxAppDtmfTail
+        .catch(() => undefined)
+        .then(() =>
+          runWxAppTransmitDtmf(
+            this.getWxAppVoiceDependencies(),
+            this.createWxAppLifecycle(),
+            options
+          )
+        );
+
+      this.wxAppDtmfTail = dtmfPromise.catch(() => undefined);
+      await dtmfPromise;
 
       return;
     }