Task with state machine #4562

arun3528 · 2025-11-04T02:38:18Z

COMPLETES #< INSERT LINK TO ISSUE >

This pull request addresses

< DESCRIBE THE CONTEXT OF THE ISSUE >

by making the following changes

< DESCRIBE YOUR CHANGES >

Change Type

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update
Tooling change
Internal code refactor

The following scenarios were tested

< ENUMERATE TESTS PERFORMED, WHETHER MANUAL OR AUTOMATED >

The GAI Coding Policy And Copyright Annotation Best Practices

I certified that

I have read and followed contributing guidelines
I discussed changes with code owners prior to submitting this pull request
I have not skipped any automated checks
All existing and new tests passed
I have updated the documentation accordingly

Make sure to have followed the contributing guidelines before submitting.

adhmenon · 2025-11-17T08:49:46Z

packages/@webex/contact-center/src/services/task/state-machine/TaskStateMachine.ts

+      on: {
+        [TaskEvent.UNHOLD]: {
+          target: TaskState.CONNECTED,
+          cond: 'canResume',


Not sure if we really need canResume guard check here... i feel it should be allowed irrsepctive right?

we only allow resume when its on hold , we need some check on the SDK not on the widgets ,

this normally could be enhanced adding intermediate state as well

adhmenon · 2025-11-17T09:08:51Z

packages/@webex/contact-center/src/services/task/Task.ts

  public data: TaskData;
  public webCallMap: Record<TaskId, CallId>;
-  public taskUiControls: TaskUIControls;
+  public state: any;


One small doubt, which I think we can discuss.
I like that the state is public... so for some cases, say HELD state, is it ok if the user directly accesses the state from this object rather than storing it themsleves? That ways this state can be the source of truth.
Wanted to know if that was also the thinking here?

ya @adhmenon that was the idea we just expose current state , state machine and intermediate state only gets used internally

Kesari3008 · 2025-11-12T17:13:00Z

packages/@webex/contact-center/src/services/task/state-machine/guards.ts

+  /**
+   * Can accept if in OFFERED or OFFERED_CONSULT state
+   */
+  canAccept: (context: TaskContext, event: any, meta: {state: {value: StateValue}}): boolean => {


We do not recommend using any in the code, so please assign a type to the event

Kesari3008 · 2025-11-17T13:33:57Z

packages/@webex/contact-center/src/services/task/state-machine/guards.ts

+ * Validate state transition
+ * Returns true if transition from current state to target state is valid
+ */
+export function isValidTransition(currentState: TaskState, targetState: TaskState): boolean {


Why do we need separate function to validate the state transitions? State Machine takes care of validating them on its own and blocks the transitions from happening if not valid

it was just a helper method, not getting used will remove it

Kesari3008 · 2025-11-17T13:37:57Z

packages/@webex/contact-center/src/services/task/voice/Voice.ts

+    // Determine UI control states based on current state and context
+    const isOffered = state.matches(TaskState.OFFERED) || state.matches(TaskState.OFFERED_CONSULT);
+    const isConnected = state.matches(TaskState.CONNECTED);
+    const isHeld = state.matches(TaskState.HELD);


How is context being used here to determine the UI control state? From what I understand we are only verifying if the current state matches the passed state

no context is not getting used here. just the state , context only comes into picture for complex flows , there is only 3 or 4 or them , will be used more in conference

Kesari3008 · 2025-11-17T13:42:30Z

packages/@webex/contact-center/src/services/task/voice/Voice.ts

+   * task.hold().then(()=>{}).catch(()=>{})
+   * ```
+   * */
+  public async hold(): Promise<TaskResponse> {


Why have we changed this ?

There was a issue we expose hold in webrtc and task but voice only has holdResume and not hold, resume , not sure how we missed it , whats your thoughts on it ?

Kesari3008 · 2025-11-17T13:45:30Z

packages/@webex/contact-center/src/services/task/voice/Voice.ts

    const shouldHold = !this.data.interaction.media[this.data.mediaResourceId].isHold;

+    // Validate operation is allowed in current state
+    const state = this.stateMachineService?.state;


I don't understand the significance of this code, if we have state machine in place that should block the API invocation too instead of we need to add if else condition to throw error. This should be controlled via state machine itself

Kesari3008 · 2025-11-17T13:47:22Z

packages/@webex/contact-center/src/services/task/voice/Voice.ts

   */
  public async pauseRecording(): Promise<TaskResponse> {
+    // Validate recording is active
+    const context = this.stateMachineService?.state?.context;


Same comment here

Kesari3008 · 2025-11-17T13:48:55Z

packages/@webex/contact-center/src/services/task/voice/Voice.ts

+  public async consult(consultPayload?: ConsultPayload): Promise<TaskResponse> {
+    // Validate consult is allowed
+    const state = this.stateMachineService?.state;
+    const canConsult =


We have a canConsult guard as well as we are calculating the same thing here again using state machine. Feels redundant

Kesari3008 · 2025-11-17T14:31:32Z

packages/@webex/contact-center/src/services/task/state-machine/guards.ts

+  /**
+   * Can only start conference if consult destination agent has joined
+   */
+  canStartConference: (


Conditions that we have in these guards can be just be directly put in the actions itself that are being invoked from each of the state transitions and update context based on conditions

arun3528 · 2025-11-20T14:15:48Z

packages/@webex/contact-center/src/services/task/TaskManager.ts

+      });
+
+      // Send event to task's state machine
+      taskWithStateMachine.stateMachineService.send(stateMachineEvent);


change the second argument to payload

arun3528 · 2025-11-20T14:20:34Z

packages/@webex/contact-center/src/services/task/Task.ts

+  public async pauseRecording(): Promise<TaskResponse> {
+    this.unsupportedMethodError('pauseRecording');
+
+    return Promise.reject(new Error('pauseRecording not supported for this channel type'));


use throw error rather then returning
Promise.reject

arun3528 · 2025-11-20T14:26:21Z

packages/@webex/contact-center/src/services/task/Task.ts

+   * ```
+   */
+  public get taskUiControls(): TaskUIActions {
+    // Convert computed UI controls to TaskActionControl objects for backward compatibility


remove this , make sure we publish event on each UI control change , its will have UI control object

arun3528 · 2025-11-20T14:29:23Z

packages/@webex/contact-center/src/services/task/Task.ts

+   *
+   * @returns UI control states for all task actions
+   */
+  protected computeUIControls(): TaskUIControls {


returned object can be a loop one liner

arun3528 · 2025-11-20T14:32:16Z

packages/@webex/contact-center/src/services/task/voice/Voice.ts

+   * This replaces the old updateUIControlsFromState() method.
+   * Returns plain objects instead of mutating taskUiControls.
+   */
+  protected computeUIControls(): import('../Task').TaskUIControls {


arun3528 · 2025-11-20T14:41:41Z

packages/@webex/contact-center/src/services/task/voice/Voice.ts

+      // Consult transfer: visible during consulting
+      consultTransfer: {
+        visible: isConsulting,
+        enabled: true,


enabled/show/visable /display :
supported

check on the naming

arun3528 · 2025-11-20T14:54:08Z

packages/@webex/contact-center/src/services/task/voice/Voice.ts

+    // Validate operation is allowed in current state
+    const state = this.stateMachineService?.state;
+    if (state) {
+      const currentState = state.value as TaskState;


move this logic inside the hold function and resume function

arun3528 · 2025-11-20T15:19:49Z

packages/@webex/contact-center/src/services/task/state-machine/actions.ts

+ * Create initial context for a new task
+ */
+export function createInitialContext(): TaskContext {
+  return {


doc on how the context can be used for a specific feature , comment out all the unused values

Kesari3008 · 2025-11-24T06:56:46Z

packages/@webex/contact-center/src/services/task/state-machine/actions.ts

+   * Initialize task with offer data
+   */
+  initializeTask: assign((context: TaskContext, event: TaskEventPayload) => {
+    if (isEventOfType(event, TaskEvent.OFFER) || isEventOfType(event, TaskEvent.OFFER_CONSULT)) {


We don't seem to be invoking this action apart from these 2 events only so why do we have the need to add this condition here ?

Kesari3008 · 2025-11-24T06:59:06Z

packages/@webex/contact-center/src/services/task/state-machine/TaskStateMachine.ts

+
+      [TaskState.OFFERED]: {
+        on: {
+          [TaskEvent.ACCEPT]: {


What's the difference between ACCEPT and ASSIGN ? Why do we need 2 events here ?

Kesari3008 · 2025-11-24T07:02:51Z

packages/@webex/contact-center/src/services/task/state-machine/TaskStateMachine.ts

+            target: TaskState.CONNECTED,
+            actions: ['updateTaskData'],
+          },
+          [TaskEvent.RONA]: {


These 2 events also can be one single event

Kesari3008 · 2025-11-24T07:04:00Z

packages/@webex/contact-center/src/services/task/state-machine/TaskStateMachine.ts

+          [TaskEvent.ACCEPT]: {
+            target: TaskState.CONSULTING,
+          },
+          [TaskEvent.RONA]: {


Same comment here

Kesari3008 · 2025-11-24T12:59:49Z

packages/@webex/contact-center/src/services/task/state-machine/TaskStateMachine.ts

+          [TaskEvent.CONSULTING_ACTIVE]: {
+            actions: ['setConsultAgentJoined'],
+          },
+          [TaskEvent.START_CONFERENCE]: {


start_conference and merge conference are not very different from each other so do we need separate states for it

Kesari3008 · 2025-11-24T13:42:02Z

packages/@webex/contact-center/src/services/task/TaskManager.ts

  private registerTaskListeners() {
    this.webSocketManager.on('message', (event) => {
      const payload = JSON.parse(event);
+      if (payload?.keepalive === 'true' || payload?.keepalive === true) {


Why did we need this additional condition ?

Kesari3008 · 2025-11-24T13:42:41Z

packages/@webex/contact-center/src/services/task/TaskManager.ts

+        return;
+      }
+      if (payload?.data?.interaction) {
+        payload.data = normalizeTaskData(payload.data);


Why was this normalizing required ?

Kesari3008 · 2025-11-24T13:44:03Z

packages/@webex/contact-center/src/services/task/TaskManager.ts

            this.updateTaskData(task, payload.data);
            task.emit(TASK_EVENTS.TASK_RECORDING_RESUME_FAILED, task);
            break;
-          case CC_EVENTS.AGENT_CONSULT_CONFERENCING:


Did we remove this because we are going to add conference separately ? Maybe commenting would be better than removing

Kesari3008 · 2025-11-24T13:44:45Z

packages/@webex/contact-center/src/services/task/TaskManager.ts

              this.emit(TASK_EVENTS.TASK_INCOMING, task);
            }
            break;
          case CC_EVENTS.AGENT_OFFER_CONTACT:


Do we even need other event handling here now that we have state machine taking care of it

Kesari3008 · 2025-11-24T13:45:19Z

packages/@webex/contact-center/src/services/task/voice/Voice.ts

      return result;
    } catch (error) {
+      // Send failure event to transition back to previous state
+      if (this.stateMachineService) {


Why is this if condition required everywhere ?

Kesari3008 · 2025-11-24T13:47:52Z

Please make the PR ready for review so can run the pipeline too on the changes

arun3528 · 2025-11-24T13:58:05Z

add check for normalizer to pass through if its a boolean @rajeshtezu

arun3528 · 2025-11-24T14:15:40Z

remove the callbacks from the actions and add enum , rather then callbackl , add one callback

arun3528 added 5 commits October 30, 2025 21:20

feat(contact-center): multiparty conference skeleton

91a01ca

feat(contact-center): with state management

ec119ce

fix(contact-center): update the state machine

d2e8d03

fix(contact-center): update the guard to use the state object

e4af4c7

fix(contact-center): finalize the state machine

95afdde

arun3528 force-pushed the task-with-state branch from 4cbbe04 to a92618d Compare November 5, 2025 17:33

fix(contact-center): revert the conference and derived state changes

5b416f6

arun3528 force-pushed the task-with-state branch from a92618d to 5b416f6 Compare November 5, 2025 17:40

adhmenon reviewed Nov 17, 2025

View reviewed changes

Kesari3008 requested changes Nov 17, 2025

View reviewed changes

fix(contact center): remove guard and un used action

d322be9

arun3528 commented Nov 20, 2025

View reviewed changes

arun3528 added 2 commits November 20, 2025 23:30

fix(contact-center): use the context and move the uicontrol logic

870ba6b

fix(contract center): recording flag enabled

9cb7cd3

Kesari3008 requested changes Nov 24, 2025

View reviewed changes

Task with state machine #4562

Are you sure you want to change the base?

Task with state machine #4562

Uh oh!

Conversation

arun3528 commented Nov 4, 2025

COMPLETES #< INSERT LINK TO ISSUE >

This pull request addresses

by making the following changes

Change Type

The following scenarios were tested

The GAI Coding Policy And Copyright Annotation Best Practices

I certified that

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!