@webex/contact-center 3.12.0-llmrefactor.1 → 3.12.0-llmrefactor.10

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

@@ -52,12 +52,81 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
    * AgentContactHeld          -> TaskEvent.HOLD_SUCCESS
    * AgentContactUnheld        -> TaskEvent.UNHOLD_SUCCESS
    * AgentConsultEnded         -> TaskEvent.CONSULT_END
+   * ParticipantLeftConference -> TaskEvent.PARTICIPANT_LEAVE
    * AgentContactEnded         -> TaskEvent.CONTACT_ENDED
    * AgentWrapup               -> TaskEvent.TASK_WRAPUP (wrapUpRequired)
    * AgentWrappedup            -> TaskEvent.WRAPUP_COMPLETE
    *
    * (See TaskManager.mapEventToTaskStateMachineEvent for the full mapping table.)
    */
+  // XState evaluates these guarded transition arrays in order. Each returned entry is a
+  // complete transition with its own target and actions; sharing them keeps lifecycle-event
+  // handling consistent across active states where ParticipantLeftConference can arrive.
+  const currentAgentParticipantLeaveTransitions = () => [
+    {
+      guard: (params) =>
+        guards.didCurrentAgentLeaveMainInteraction(params) && guards.shouldWrapUp(params),
+      target: TaskState.WRAPPING_UP,
+      actions: [
+        'updateTaskData',
+        'handleParticipantLeft',
+        'markEnded',
+        'clearConsultState',
+        'emitTaskParticipantLeft',
+      ],
+    },
+    {
+      guard: guards.didCurrentAgentLeaveMainInteraction,
+      target: TaskState.TERMINATED,
+      actions: [
+        'updateTaskData',
+        'handleParticipantLeft',
+        'markEnded',
+        'clearConsultState',
+        'emitTaskParticipantLeft',
+        'emitTaskEnd',
+      ],
+    },
+  ];
+
+  const exitConferenceSuccessTransitions = () => [
+    {
+      guard: guards.shouldWrapUp,
+      target: TaskState.WRAPPING_UP,
+      actions: ['updateTaskData', 'markEnded', 'clearConsultState'],
+    },
+    {
+      target: TaskState.TERMINATED,
+      actions: ['updateTaskData', 'markEnded', 'clearConsultState', 'emitTaskEnd'],
+    },
+  ];
+
+  const currentAgentConsultEndTransitions = () => [
+    {
+      guard: (params) =>
+        guards.didCurrentAgentLeaveMainInteraction(params) && guards.shouldWrapUp(params),
+      target: TaskState.WRAPPING_UP,
+      actions: [
+        'updateTaskData',
+        'markEnded',
+        'clearConsultState',
+        'emitTaskConsultEnd',
+        'emitTaskWrapup',
+      ],
+    },
+    {
+      guard: guards.didCurrentAgentLeaveMainInteraction,
+      target: TaskState.TERMINATED,
+      actions: [
+        'updateTaskData',
+        'markEnded',
+        'clearConsultState',
+        'emitTaskConsultEnd',
+        'emitTaskEnd',
+      ],
+    },
+  ];
+
   return {
     id: 'taskStateMachine',
     initial: TaskState.IDLE,
@@ -70,7 +139,7 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
         actions: ['updateTaskData', 'syncTaskDataFromEvent'],
       },
       [TaskEvent.CONTACT_OWNER_CHANGED]: {
-        actions: ['updateTaskData', 'syncTaskDataFromEvent'],
+        actions: ['updateTaskData', 'syncTaskDataFromEvent', 'emitTaskHydrate'],
       },
       // HYDRATE: Update task data from AgentContact event
       // Note: State restoration with transitions is handled in IDLE state.
@@ -190,10 +259,17 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
             target: TaskState.TERMINATED,
             actions: ['updateTaskData', 'markEnded', 'emitTaskReject'],
           },
-          [TaskEvent.TASK_WRAPUP]: {
-            target: TaskState.TERMINATED,
-            actions: ['updateTaskData', 'markEnded', 'emitTaskEnd'],
-          },
+          [TaskEvent.TASK_WRAPUP]: [
+            {
+              guard: guards.shouldWrapUp,
+              target: TaskState.WRAPPING_UP,
+              actions: ['updateTaskData', 'markEnded'],
+            },
+            {
+              target: TaskState.TERMINATED,
+              actions: ['updateTaskData', 'markEnded', 'emitTaskEnd'],
+            },
+          ],
           [TaskEvent.CONTACT_ENDED]: {
             target: TaskState.TERMINATED,
             actions: ['updateTaskData', 'markEnded', 'emitTaskEnd'],
@@ -334,6 +410,7 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
           },
           // AgentConsultEnded from Stable Prod while on connected leg (external end consult).
           [TaskEvent.CONSULT_END]: [
+            ...currentAgentConsultEndTransitions(),
             {
               guard: ({context, event}) => {
                 if (context.consultInitiator !== true) return false;
@@ -378,14 +455,26 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
           ],
           [TaskEvent.TASK_WRAPUP]: {
             target: TaskState.WRAPPING_UP,
-            actions: ['updateTaskData', 'markEnded', 'emitTaskWrapup'],
+            actions: ['updateTaskData', 'markEnded'],
           },
+          [TaskEvent.OUTBOUND_FAILED]: [
+            {
+              guard: guards.shouldWrapUp,
+              target: TaskState.WRAPPING_UP,
+              actions: ['updateTaskData', 'markEnded', 'emitTaskOutdialFailed', 'emitTaskWrapup'],
+            },
+            {
+              target: TaskState.TERMINATED,
+              actions: ['updateTaskData', 'markEnded', 'emitTaskOutdialFailed', 'emitTaskEnd'],
+            },
+          ],
           [TaskEvent.PAUSE_RECORDING]: {
             actions: ['updateTaskData', 'setRecordingState', 'emitTaskRecordingPaused'],
           },
           [TaskEvent.RESUME_RECORDING]: {
             actions: ['updateTaskData', 'setRecordingState', 'emitTaskRecordingResumed'],
           },
+          [TaskEvent.EXIT_CONFERENCE_SUCCESS]: exitConferenceSuccessTransitions(),
         },
       },
 
@@ -401,6 +490,21 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
             target: TaskState.CONNECTED,
             actions: ['updateTaskData'],
           },
+          [TaskEvent.OUTBOUND_FAILED]: [
+            {
+              guard: guards.shouldWrapUp,
+              target: TaskState.WRAPPING_UP,
+              actions: ['updateTaskData', 'markEnded', 'emitTaskOutdialFailed', 'emitTaskWrapup'],
+            },
+            {
+              target: TaskState.TERMINATED,
+              actions: ['updateTaskData', 'markEnded', 'emitTaskOutdialFailed', 'emitTaskEnd'],
+            },
+          ],
+          [TaskEvent.TASK_WRAPUP]: {
+            target: TaskState.WRAPPING_UP,
+            actions: ['updateTaskData', 'markEnded'],
+          },
         },
       },
 
@@ -487,14 +591,31 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
             },
           ],
           // AgentConsultEnded from Stable Prod while main leg is held (external end consult).
-          [TaskEvent.CONSULT_END]: {
-            actions: ['updateTaskData', 'clearConsultState', 'emitTaskConsultEnd'],
-          },
+          [TaskEvent.CONSULT_END]: [
+            ...currentAgentConsultEndTransitions(),
+            {actions: ['updateTaskData', 'clearConsultState', 'emitTaskConsultEnd']},
+          ],
+          [TaskEvent.PARTICIPANT_LEAVE]: [
+            ...currentAgentParticipantLeaveTransitions(),
+            {actions: ['updateTaskData', 'handleParticipantLeft', 'emitTaskParticipantLeft']},
+          ],
           // TODO: This may not be a valid transition, this needs to be checked as well
           [TaskEvent.TASK_WRAPUP]: {
             target: TaskState.WRAPPING_UP,
-            actions: ['updateTaskData', 'markEnded', 'emitTaskWrapup'],
+            actions: ['updateTaskData', 'markEnded'],
           },
+          [TaskEvent.OUTBOUND_FAILED]: [
+            {
+              guard: guards.shouldWrapUp,
+              target: TaskState.WRAPPING_UP,
+              actions: ['updateTaskData', 'markEnded', 'emitTaskOutdialFailed', 'emitTaskWrapup'],
+            },
+            {
+              target: TaskState.TERMINATED,
+              actions: ['updateTaskData', 'markEnded', 'emitTaskOutdialFailed', 'emitTaskEnd'],
+            },
+          ],
+          [TaskEvent.EXIT_CONFERENCE_SUCCESS]: exitConferenceSuccessTransitions(),
         },
       },
 
@@ -507,6 +628,25 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
           [TaskEvent.UNHOLD_FAILED]: {
             target: TaskState.HELD,
           },
+          [TaskEvent.PARTICIPANT_LEAVE]: [
+            ...currentAgentParticipantLeaveTransitions(),
+            {actions: ['updateTaskData', 'handleParticipantLeft', 'emitTaskParticipantLeft']},
+          ],
+          [TaskEvent.OUTBOUND_FAILED]: [
+            {
+              guard: guards.shouldWrapUp,
+              target: TaskState.WRAPPING_UP,
+              actions: ['updateTaskData', 'markEnded', 'emitTaskOutdialFailed', 'emitTaskWrapup'],
+            },
+            {
+              target: TaskState.TERMINATED,
+              actions: ['updateTaskData', 'markEnded', 'emitTaskOutdialFailed', 'emitTaskEnd'],
+            },
+          ],
+          [TaskEvent.TASK_WRAPUP]: {
+            target: TaskState.WRAPPING_UP,
+            actions: ['updateTaskData', 'markEnded'],
+          },
         },
       },
 
@@ -569,6 +709,7 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
           ],
           // AgentConsultEnded from Stable Prod during consult initiation (external end consult).
           [TaskEvent.CONSULT_END]: [
+            ...currentAgentConsultEndTransitions(),
             {
               guard: guards.isPrimaryMediaOnHold,
               target: TaskState.HELD,
@@ -579,6 +720,25 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
               actions: ['updateTaskData', 'clearConsultState', 'emitTaskConsultEnd'],
             },
           ],
+          [TaskEvent.PARTICIPANT_LEAVE]: [
+            ...currentAgentParticipantLeaveTransitions(),
+            {actions: ['updateTaskData', 'handleParticipantLeft', 'emitTaskParticipantLeft']},
+          ],
+          [TaskEvent.OUTBOUND_FAILED]: [
+            {
+              guard: guards.shouldWrapUp,
+              target: TaskState.WRAPPING_UP,
+              actions: ['updateTaskData', 'markEnded', 'emitTaskOutdialFailed', 'emitTaskWrapup'],
+            },
+            {
+              target: TaskState.TERMINATED,
+              actions: ['updateTaskData', 'markEnded', 'emitTaskOutdialFailed', 'emitTaskEnd'],
+            },
+          ],
+          [TaskEvent.TASK_WRAPUP]: {
+            target: TaskState.WRAPPING_UP,
+            actions: ['updateTaskData', 'markEnded'],
+          },
         },
       },
 
@@ -619,6 +779,7 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
 
           // AgentConsultEnded
           [TaskEvent.CONSULT_END]: [
+            ...currentAgentConsultEndTransitions(),
             {
               // Initiator returning to conference only while conference is still active.
               guard: ({context, event}) =>
@@ -686,7 +847,13 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
             {
               // Consulted agent → TERMINATED
               target: TaskState.TERMINATED,
-              actions: ['updateTaskData'],
+              actions: [
+                'updateTaskData',
+                'markEnded',
+                'clearConsultState',
+                'emitTaskConsultEnd',
+                'emitTaskEnd',
+              ],
             },
           ],
 
@@ -705,34 +872,10 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
           },
 
           [TaskEvent.PARTICIPANT_LEAVE]: [
+            ...currentAgentParticipantLeaveTransitions(),
             {
               guard: (params) =>
-                guards.didCurrentAgentLeaveConference(params) && guards.shouldWrapUp(params),
-              target: TaskState.WRAPPING_UP,
-              actions: [
-                'updateTaskData',
-                'handleParticipantLeft',
-                'markEnded',
-                'clearConsultState',
-                'emitTaskParticipantLeft',
-                'emitTaskWrapup',
-              ],
-            },
-            {
-              guard: guards.didCurrentAgentLeaveConference,
-              target: TaskState.TERMINATED,
-              actions: [
-                'updateTaskData',
-                'handleParticipantLeft',
-                'markEnded',
-                'clearConsultState',
-                'emitTaskParticipantLeft',
-                'emitTaskEnd',
-              ],
-            },
-            {
-              guard: (params) =>
-                !guards.didCurrentAgentLeaveConference(params) &&
+                !guards.didCurrentAgentLeaveMainInteraction(params) &&
                 guards.shouldDowngradeConferenceToConnected(params),
               target: TaskState.CONNECTED,
               actions: [
@@ -775,7 +918,6 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
                 'clearConsultState',
                 'handleTransferConferenceSuccess',
                 'clearTransferConferenceRequested',
-                'emitTaskWrapup',
               ],
             },
             {
@@ -823,8 +965,19 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
           },
           [TaskEvent.TASK_WRAPUP]: {
             target: TaskState.WRAPPING_UP,
-            actions: ['updateTaskData', 'markEnded', 'clearConsultState', 'emitTaskWrapup'],
+            actions: ['updateTaskData', 'markEnded', 'clearConsultState'],
           },
+          [TaskEvent.OUTBOUND_FAILED]: [
+            {
+              guard: guards.shouldWrapUp,
+              target: TaskState.WRAPPING_UP,
+              actions: ['updateTaskData', 'markEnded', 'emitTaskOutdialFailed', 'emitTaskWrapup'],
+            },
+            {
+              target: TaskState.TERMINATED,
+              actions: ['updateTaskData', 'markEnded', 'emitTaskOutdialFailed', 'emitTaskEnd'],
+            },
+          ],
           [TaskEvent.MERGE_TO_CONFERENCE]: {
             target: TaskState.CONF_INITIATING,
           },
@@ -860,6 +1013,7 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
           },
           // AgentConsultEnded while conference is initiating (end call before conference completes)
           [TaskEvent.CONSULT_END]: [
+            ...currentAgentConsultEndTransitions(),
             {
               guard: ({event}) => {
                 const taskData = getTaskDataFromEvent(event);
@@ -874,6 +1028,21 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
               actions: ['updateTaskData', 'clearConsultState'],
             },
           ],
+          [TaskEvent.OUTBOUND_FAILED]: [
+            {
+              guard: guards.shouldWrapUp,
+              target: TaskState.WRAPPING_UP,
+              actions: ['updateTaskData', 'markEnded', 'emitTaskOutdialFailed', 'emitTaskWrapup'],
+            },
+            {
+              target: TaskState.TERMINATED,
+              actions: ['updateTaskData', 'markEnded', 'emitTaskOutdialFailed', 'emitTaskEnd'],
+            },
+          ],
+          [TaskEvent.TASK_WRAPUP]: {
+            target: TaskState.WRAPPING_UP,
+            actions: ['updateTaskData', 'markEnded'],
+          },
         },
       },
 
@@ -887,20 +1056,11 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
               'emitTaskConferenceStarted',
             ],
           },
-          [TaskEvent.EXIT_CONFERENCE_SUCCESS]: [
-            {
-              guard: guards.shouldWrapUp,
-              target: TaskState.WRAPPING_UP,
-              actions: ['updateTaskData', 'markEnded', 'clearConsultState', 'emitTaskWrapup'],
-            },
-            {
-              target: TaskState.TERMINATED,
-              actions: ['updateTaskData', 'markEnded', 'clearConsultState', 'emitTaskEnd'],
-            },
-          ],
+          [TaskEvent.EXIT_CONFERENCE_SUCCESS]: exitConferenceSuccessTransitions(),
 
           // Needed as all agents in conference get this event, hence we need to clear the consult state
           [TaskEvent.CONSULT_END]: [
+            ...currentAgentConsultEndTransitions(),
             {
               guard: ({context, event}) => {
                 const taskData = getTaskDataFromEvent(event);
@@ -975,37 +1135,11 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
 
           // Participant leaves - handle conference downgrade scenarios
           [TaskEvent.PARTICIPANT_LEAVE]: [
-            {
-              // Only the leaving agent should wrap up → WRAPPING_UP
-              guard: (params) =>
-                guards.didCurrentAgentLeaveConference(params) && guards.shouldWrapUp(params),
-              target: TaskState.WRAPPING_UP,
-              actions: [
-                'updateTaskData',
-                'handleParticipantLeft',
-                'markEnded',
-                'clearConsultState',
-                'emitTaskParticipantLeft',
-                'emitTaskWrapup',
-              ],
-            },
-            {
-              // Only the leaving agent (no wrapup) → TERMINATED
-              guard: guards.didCurrentAgentLeaveConference,
-              target: TaskState.TERMINATED,
-              actions: [
-                'updateTaskData',
-                'handleParticipantLeft',
-                'markEnded',
-                'clearConsultState',
-                'emitTaskParticipantLeft',
-                'emitTaskEnd',
-              ],
-            },
+            ...currentAgentParticipantLeaveTransitions(),
             {
               // Conference downgraded, customer present → CONNECTED
               guard: (params) =>
-                !guards.didCurrentAgentLeaveConference(params) &&
+                !guards.didCurrentAgentLeaveMainInteraction(params) &&
                 guards.shouldDowngradeConferenceToConnected(params),
               target: TaskState.CONNECTED,
               actions: [
@@ -1040,7 +1174,6 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
                 'clearConsultState',
                 'handleTransferConferenceSuccess',
                 'clearTransferConferenceRequested',
-                'emitTaskWrapup',
               ],
             },
             {
@@ -1075,7 +1208,7 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
               // Agent who should wrap up → WRAPPING_UP
               guard: guards.shouldWrapUp,
               target: TaskState.WRAPPING_UP,
-              actions: ['updateTaskData', 'markEnded', 'clearConsultState', 'emitTaskWrapup'],
+              actions: ['updateTaskData', 'markEnded', 'clearConsultState'],
             },
             {
               // Customer still in call → CONNECTED
@@ -1113,8 +1246,19 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
           [TaskEvent.TASK_WRAPUP]: {
             guard: guards.shouldWrapUp,
             target: TaskState.WRAPPING_UP,
-            actions: ['updateTaskData', 'markEnded', 'clearConsultState', 'emitTaskWrapup'],
+            actions: ['updateTaskData', 'markEnded', 'clearConsultState'],
           },
+          [TaskEvent.OUTBOUND_FAILED]: [
+            {
+              guard: guards.shouldWrapUp,
+              target: TaskState.WRAPPING_UP,
+              actions: ['updateTaskData', 'markEnded', 'emitTaskOutdialFailed', 'emitTaskWrapup'],
+            },
+            {
+              target: TaskState.TERMINATED,
+              actions: ['updateTaskData', 'markEnded', 'emitTaskOutdialFailed', 'emitTaskEnd'],
+            },
+          ],
         },
       },
 
@@ -1122,6 +1266,16 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
         // Only emit wrapup event on entry - task:end should only be emitted when COMPLETED
         entry: ['emitTaskWrapup'],
         on: {
+          // Late AgentWrapup after conference exit already entered WRAPPING_UP
+          [TaskEvent.TASK_WRAPUP]: [
+            {
+              guard: ({context}) => context.taskData?.wrapUpRequired === true,
+              actions: ['updateTaskData'],
+            },
+            {
+              actions: ['updateTaskData', 'emitTaskWrapup'],
+            },
+          ],
           // AgentWrappedup Event
           [TaskEvent.WRAPUP_COMPLETE]: {
             target: TaskState.COMPLETED,

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

@@ -515,12 +515,15 @@ export const actions: TaskActionsMap = {
   }),
   handleConferenceStarted: assign({consultInitiator: false}),
 
-  setConsultDestination: assign(({event}: TaskActionArgs) => {
+  setConsultDestination: assign(({context, event}: TaskActionArgs) => {
     if (!event || event.type !== TaskEvent.CONSULT) {
       return {};
     }
 
-    const taskData = getTaskDataFromEvent(event);
+    // CONSULT is a user action and does not carry taskData. Preserve the current interaction
+    // snapshot while recording the destination; replacing it with only destAgentId would remove
+    // the main-leg membership needed to correlate an immediately following lifecycle event.
+    const taskData = context.taskData;
     const consultDestinationType =
       'destinationType' in event ? event.destinationType ?? null : null;
     const consultDestinationAgentId =

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

@@ -66,7 +66,7 @@ state-machine/
 - **State Graph and Transition Rules**: `TaskStateMachine.ts` defines all states, transition tables, and event handlers that drive the task lifecycle.
 - **Deterministic Context Updates**: `actions.ts` implements XState actions for task context mutation and provides emitter placeholders that `Task` overrides to surface SDK events.
 - **Transition Eligibility**: `guards.ts` contains pure predicates that gate transitions based on current context, task data, and backend state.
-- **UI Controls Computation**: `uiControlsComputer.ts` derives `TaskUIControls` from state and context for voice/digital channels, keeping UI enablement centralized.
+- **UI Controls Computation**: `uiControlsComputer.ts` derives per-leg action controls and ordered Consult/Transfer destination categories from state, Task data, and injected profile policy for voice/digital channels. Consumers read `task.uiControls`; do not add a parallel policy method or UI-side decision tree.
 - **Typed Event Contracts**: `constants.ts` and `types.ts` define `TaskState`, `TaskEvent`, and the `TaskEventPayloadMap` so transitions and payloads stay type-safe.
 - **Public Exports**: `index.ts` exposes the state machine factory, event enums, and types for consumption by the task layer.
 
@@ -266,14 +266,16 @@ shouldWrapUpOrIsInitiator(context, event) {
   return Boolean(event.taskData?.wrapUpRequired || context.consultInitiator);
 }
 
-// Check whether the leaving participant is the current agent
-didCurrentAgentLeaveConference(context, event) {
+// Check whether the current agent left the main interaction
+didCurrentAgentLeaveMainInteraction(context, event) {
   const selfAgentId = getSelfAgentId(context, event.taskData);
   if (!selfAgentId) return false;
 
   const participantIdFromEvent = 'participantId' in event ? event.participantId : undefined;
   const participantId = participantIdFromEvent ?? event.taskData?.participantId;
-  return Boolean(participantId) && participantId === selfAgentId;
+  if (Boolean(participantId) && participantId === selfAgentId) return true;
+  // 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.
 }
 ```