@webex/contact-center 3.13.0-next.1 → 3.13.0-next.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.repo-context.json +704 -0
- package/.sdd/manifest.json +1065 -339
- package/AGENTS.md +935 -60
- package/dist/webex.js +1 -1
- package/docs/adr/0001-spec-source-policy.md +97 -0
- package/{ai-docs/features/consult-transfer-list-policy/spec/feature-spec.md → docs/adr/0002-consult-transfer-list-policy.md} +227 -244
- package/docs/adr/0003-repo-standards-migration.md +104 -0
- package/docs/adr/index.md +35 -0
- package/docs/architecture.md +460 -0
- package/docs/getting-started.md +142 -0
- package/docs/index.md +53 -0
- package/docs/specs/README.md +98 -0
- package/package.json +10 -9
- package/schemas/repo-context.schema.json +796 -0
- package/src/docs/README.md +727 -0
- package/src/metrics/docs/README.md +710 -0
- package/src/services/agent/docs/README.md +673 -0
- package/src/services/config/docs/README.md +530 -0
- package/src/services/core/docs/README.md +993 -0
- package/src/services/docs/README.md +765 -0
- package/src/services/task/docs/README.md +1569 -0
- package/src/services/task/state-machine/docs/README.md +1388 -0
- package/src/utils/AGENTS.md +6 -4
- package/src/utils/docs/README.md +413 -0
- package/umd/contact-center.min.js +2 -2
- package/umd/contact-center.min.js.map +1 -1
- package/ai-docs/ARCHITECTURE.md +0 -168
- package/ai-docs/CONTRACTS.md +0 -64
- package/ai-docs/GETTING_STARTED.md +0 -168
- package/ai-docs/GLOSSARY.md +0 -43
- package/ai-docs/README.md +0 -138
- package/ai-docs/REVIEW_CHECKLIST.md +0 -41
- package/ai-docs/RULES.md +0 -444
- package/ai-docs/SECURITY.md +0 -52
- package/ai-docs/SERVICE_STATE.md +0 -52
- package/ai-docs/SPEC_INDEX.md +0 -65
- package/ai-docs/adr/0001-spec-source-policy.md +0 -55
- package/ai-docs/adr/README.md +0 -8
- package/ai-docs/adr/_adr-template.md +0 -31
- package/ai-docs/contact-center-spec.md +0 -388
- package/ai-docs/features/contact-owner-change-refactor.md +0 -78
- package/ai-docs/features/generated-spec-conformance-fidelity-remediation/spec/feature-spec.md +0 -117
- package/ai-docs/features/residual-warning-coverage-completion/spec/feature-spec.md +0 -203
- package/ai-docs/features/validator-code-fidelity-drift-fix/spec/feature-spec.md +0 -315
- package/ai-docs/patterns/event-driven-patterns.md +0 -485
- package/ai-docs/patterns/testing-patterns.md +0 -480
- package/ai-docs/patterns/typescript-patterns.md +0 -365
- package/ai-docs/templates/README.md +0 -102
- package/ai-docs/templates/documentation/create-agents-md.md +0 -240
- package/ai-docs/templates/documentation/create-architecture-md.md +0 -295
- package/ai-docs/templates/existing-service/bug-fix.md +0 -254
- package/ai-docs/templates/existing-service/feature-enhancement.md +0 -450
- package/ai-docs/templates/new-method/00-master.md +0 -80
- package/ai-docs/templates/new-method/01-requirements.md +0 -232
- package/ai-docs/templates/new-method/02-implementation.md +0 -295
- package/ai-docs/templates/new-method/03-tests.md +0 -201
- package/ai-docs/templates/new-method/04-validation.md +0 -141
- package/ai-docs/templates/new-service/00-master.md +0 -109
- package/ai-docs/templates/new-service/01-pre-questions.md +0 -159
- package/ai-docs/templates/new-service/02-code-generation.md +0 -346
- package/ai-docs/templates/new-service/03-integration.md +0 -178
- package/ai-docs/templates/new-service/04-test-generation.md +0 -205
- package/ai-docs/templates/new-service/05-validation.md +0 -145
- package/src/metrics/ai-docs/AGENTS.md +0 -350
- package/src/metrics/ai-docs/ARCHITECTURE.md +0 -338
- package/src/metrics/ai-docs/metrics-spec.md +0 -971
- package/src/services/agent/ai-docs/AGENTS.md +0 -240
- package/src/services/agent/ai-docs/ARCHITECTURE.md +0 -304
- package/src/services/agent/ai-docs/agent-spec.md +0 -505
- package/src/services/ai-docs/AGENTS.md +0 -386
- package/src/services/ai-docs/services-spec.md +0 -512
- package/src/services/config/ai-docs/AGENTS.md +0 -250
- package/src/services/config/ai-docs/ARCHITECTURE.md +0 -413
- package/src/services/config/ai-docs/config-spec.md +0 -669
- package/src/services/core/ai-docs/AGENTS.md +0 -381
- package/src/services/core/ai-docs/ARCHITECTURE.md +0 -698
- package/src/services/core/ai-docs/core-spec.md +0 -797
- package/src/services/task/ai-docs/AGENTS.md +0 -457
- package/src/services/task/ai-docs/ARCHITECTURE.md +0 -595
- package/src/services/task/ai-docs/task-spec.md +0 -1501
- package/src/services/task/state-machine/ai-docs/AGENTS.md +0 -460
- package/src/services/task/state-machine/ai-docs/ARCHITECTURE.md +0 -1156
- package/src/services/task/state-machine/ai-docs/task-state-machine-spec.md +0 -2247
- package/src/utils/ai-docs/utils-spec.md +0 -391
|
@@ -0,0 +1,1388 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: Module Spec
|
|
3
|
+
title: 'Task state machine specification'
|
|
4
|
+
description: Responsibilities, boundaries, states, transitions, guards, actions, UI-control computation, and verification for the XState task state machine of @webex/contact-center.
|
|
5
|
+
tags: [module, specification]
|
|
6
|
+
---
|
|
7
|
+
<!-- sdd-generated-metadata
|
|
8
|
+
doc_kind: module-spec
|
|
9
|
+
generated_from: module-spec@0.3.0
|
|
10
|
+
generated_by: claude-code
|
|
11
|
+
approved_by: rarajes2@cisco.com
|
|
12
|
+
updated_at: 2026-11-17T03:03:58Z
|
|
13
|
+
validation_status: pass-with-warnings
|
|
14
|
+
-->
|
|
15
|
+
|
|
16
|
+
# Task state machine
|
|
17
|
+
|
|
18
|
+
This source-local document at `src/services/task/state-machine/docs/README.md` owns the stable
|
|
19
|
+
specification for **the task state machine**: the XState graph, typed `TaskEvent` contracts, pure
|
|
20
|
+
guards, context actions, and the UI-control computer that every contact-center `Task` runs. Ground
|
|
21
|
+
every claim in package evidence and link to the
|
|
22
|
+
[package architecture](../../../../../docs/architecture.md) and the parent
|
|
23
|
+
[task module specification](../../docs/README.md) instead of repeating broader facts. No service
|
|
24
|
+
specification exists because this package is a library.
|
|
25
|
+
|
|
26
|
+
Related context: [documentation index](../../../../../docs/index.md) ·
|
|
27
|
+
[package agent instructions](../../../../../AGENTS.md)
|
|
28
|
+
|
|
29
|
+
## Metadata
|
|
30
|
+
|
|
31
|
+
| Field | Value |
|
|
32
|
+
| ----- | ----- |
|
|
33
|
+
| Owner | `@webex/web-sdk` |
|
|
34
|
+
| Source path | `src/services/task/state-machine` |
|
|
35
|
+
| Resource kind | module |
|
|
36
|
+
| Status | Active |
|
|
37
|
+
| Last verified | 2026-11-16 at `0b8c34db7f` |
|
|
38
|
+
| Module id | `task-state-machine` |
|
|
39
|
+
| Parent spec | [`src/services/task/docs/README.md`](../../docs/README.md) |
|
|
40
|
+
| Doc kind | Module spec |
|
|
41
|
+
| Coverage score | Pending coverage assessment |
|
|
42
|
+
| Validation status | pass-with-warnings — assessed 2026-11-17; validator runtime 01a1e76f-2293-79a0-9f8f-f060038448dd; 0 Blocking, 0 Important, 4 Minor findings. |
|
|
43
|
+
|
|
44
|
+
## Applicability
|
|
45
|
+
|
|
46
|
+
| Condition ID | Status | Evidence or reason | Owned section |
|
|
47
|
+
| ------------------------------------ | ---------- | ------------------ | ------------- |
|
|
48
|
+
| `module.has_tiers` | N/A | No tier policy exists in `package.json` or in the module | Tier |
|
|
49
|
+
| `module.has_ui` | N/A | `src/services/task/state-machine/uiControlsComputer.ts` returns visibility and enablement data; the module renders nothing | UI use-case flow |
|
|
50
|
+
| `module.crosses_service_boundaries` | N/A | No transport imports in `src/services/task/state-machine/TaskStateMachine.ts` or `src/services/task/state-machine/actions.ts`; Task and TaskManager own every network call | Cross-boundary use-case flow |
|
|
51
|
+
| `module.holds_client_state` | Applicable | `src/services/task/state-machine/types.ts` declares TaskContext, held by each task actor | Client state model |
|
|
52
|
+
| `module.enforces_domain_rules` | Applicable | `src/services/task/state-machine/guards.ts` gates every lifecycle transition | Business rules and invariants |
|
|
53
|
+
| `module.is_concurrent_async` | Applicable | `src/services/task/state-machine/TaskStateMachine.ts` is an event-driven actor fed by asynchronous backend notifications | Concurrency and reactive flow |
|
|
54
|
+
| `module.owns_persistence` | N/A | `src/services/task/state-machine/actions.ts` writes only actor context; nothing is stored | Data, schema, and migration discipline |
|
|
55
|
+
| `module.stateful_transitions` | Applicable | `src/services/task/state-machine/TaskStateMachine.ts` defines 13 implemented states and guarded transitions | State machine |
|
|
56
|
+
| `module.exposes_wire_protocol` | N/A | `src/services/task/TaskManager.ts` maps wire messages before they reach the machine | Protocol and wire format |
|
|
57
|
+
| `module.ui_multi_screen` | N/A | No UI | UI flow |
|
|
58
|
+
| `module.large_data_model` | N/A | `src/services/task/state-machine/types.ts` holds one context type and one event payload map; task data types belong to the task module | Data model |
|
|
59
|
+
| `module.returns_caller_errors` | N/A | `src/services/task/state-machine/TaskStateMachine.ts` never throws; unhandled events are ignored | Caller-visible failure modes |
|
|
60
|
+
| `module.module_specific_conventions` | Applicable | Pure guards, assign actions, and emitter placeholders in `src/services/task/state-machine/actions.ts` | Module-specific rules |
|
|
61
|
+
| `module.published_package` | N/A | Internal module; only getDefaultUIControls reaches the package root through `src/index.ts`, owned by the package spec | Export stability |
|
|
62
|
+
| `module.embedded_in_host` | N/A | No host mount or theme contract | Host integration and theming |
|
|
63
|
+
| `module.has_design_tradeoff` | Applicable | Typed TaskEvent vocabulary in `src/services/task/state-machine/constants.ts` isolates the graph from transport events | Key design trade-off |
|
|
64
|
+
| `module.has_submodules` | N/A | No child module under `src/services/task/state-machine/index.ts` (module_tree.py) | Sub-modules |
|
|
65
|
+
|
|
66
|
+
## Evidence register
|
|
67
|
+
|
|
68
|
+
| Evidence | What it establishes |
|
|
69
|
+
| -------- | ------------------- |
|
|
70
|
+
| `src/services/task/state-machine/TaskStateMachine.ts` | `getTaskStateMachineConfig(uiControlConfig)`: root-level handlers, the 13 implemented states, guarded transition arrays, shared transition helpers, entry actions, and the two final states; `createTaskStateMachine(uiControlConfig, options)` merges default actions with caller overrides through `.provide` |
|
|
71
|
+
| `src/services/task/state-machine/constants.ts` | `TaskState` (including five declared but unimplemented states), `TaskEvent`, `INTERACTION_STATE`, `CONSULT_STATE`, `PARTICIPANT_TYPE`, `MEDIA_TYPE_CONSULT`, `MAX_PARTICIPANTS_IN_MULTIPARTY_CONFERENCE` |
|
|
72
|
+
| `src/services/task/state-machine/types.ts` | `UIControlConfig`, `TaskContext`, the private `TaskEventPayloadMap`, `TaskEventPayload`, `isEventOfType`, `TaskActionsMap`, `TaskActionArgs` |
|
|
73
|
+
| `src/services/task/state-machine/guards.ts` | The `guards` object, the helpers `getTaskDataFromEvent`, `getSelfAgentId`, `isSelfConsultingAgent`, `hasActiveConsultInPostCall`, `shouldWrapUpForThisAgent`, and the JSDoc rationale for each guard |
|
|
74
|
+
| `src/services/task/state-machine/actions.ts` | The default `actions` map (`assign` mutators and no-op emitter placeholders), `createInitialContext`, `deriveTaskDataUpdates`, `getTaskStateForUiControls`, `updateUIControls`. Wiring: `handleConferenceFailed`, `handleSwitchToMainCall`, and `handleSwitchToConsult` are defined in `actions.ts` and wired by `TaskStateMachine.ts`. `forceConsultInitiator` is defined in `actions.ts` but is not wired in the current graph; neither are `setConsultCallHeld`, `clearConsultCallHeld`, `setExitingConference`, `emitTaskConsultCreated`, or `emitTaskExitConference` |
|
|
75
|
+
| `src/services/task/state-machine/uiControlsComputer.ts` | `getDefaultUIControls`, `computeUIControls`, `haveUIControlsChanged`, and the private voice, digital, destination, and leg helpers |
|
|
76
|
+
| `src/services/task/state-machine/index.ts` | The module's export list consumed by the task layer |
|
|
77
|
+
| `src/index.ts` | Re-exports `getDefaultUIControls` directly from `uiControlsComputer.ts` |
|
|
78
|
+
| `src/services/task/Task.ts` | Actor bootstrap (`initializeStateMachine`), `sendStateMachineEvent`, `updateUiControls`, and the action overrides including `syncTaskDataFromEvent`, emitters, `requestAutoAnswer`, `requestCleanup`, `cleanupResources` |
|
|
79
|
+
| `src/services/task/voice/Voice.ts` | API-driven events (`HOLD_INITIATED`, `HOLD_SUCCESS`, `HOLD_FAILED`, `CONSULT`, `CONSULT_SUCCESS`, `MERGE_TO_CONFERENCE`, `CONFERENCE_FAILED`, `EXIT_CONFERENCE_SUCCESS`, `TRANSFER_CONFERENCE`, `TRANSFER_CONFERENCE_FAILED`, `SWITCH_TO_MAIN_CALL`, `SWITCH_TO_CONSULT`) and voice emitter overrides |
|
|
80
|
+
| `src/services/task/TaskManager.ts` | `mapEventToTaskStateMachineEvent` (CC event to `TaskEvent`), owner-change recovery that sends an internal `HYDRATE` before listeners are installed, and `preserveConfirmedOwner` |
|
|
81
|
+
| `test/unit/spec/services/task/state-machine/TaskStateMachine.ts` | 98 jest cases over transitions, wrap-up, consult, conference, hydrate, and outbound-failure paths |
|
|
82
|
+
| `test/unit/spec/services/task/state-machine/guards.ts` | 35 jest cases over hydrate, conference, consult, wrap-up, departure, conference-transfer, and server-state guards |
|
|
83
|
+
| `test/unit/spec/services/task/state-machine/uiControlsComputer.ts` | 80 jest cases over per-leg controls, destinations, conference, post-call, outdial, WebRTC, and wxApp controls |
|
|
84
|
+
| `test/unit/spec/services/task/state-machine/types.ts` | 2 jest cases over `isEventOfType` |
|
|
85
|
+
| `test/unit/spec/services/task/Task.ts`, `test/unit/spec/services/task/TaskManager.ts` | Task-side `syncTaskDataFromEvent`, owner-change hydrate, and roster synchronization behavior |
|
|
86
|
+
| `src/services/task/state-machine/TaskStateMachine.ts` (extension subsections) | Justifies the `###` subsections under Design overview, Data flow and sequence coverage, and State machine: one per runtime concern, operation group, shared transition group, state, and event group in the graph |
|
|
87
|
+
|
|
88
|
+
## Purpose and boundary
|
|
89
|
+
|
|
90
|
+
- Responsibility: Own deterministic task lifecycle states, transition guards/actions, typed internal events, and state-derived UI-control availability.
|
|
91
|
+
- In scope: internal state management for the task lifecycle: states and transitions, context mutation, guard logic, UI-control computation, and the typed event and payload contracts (one file each, listed in Structure and key files).
|
|
92
|
+
- Out of scope (non-goals): API contracts for external services, and Mercury or CC WebSocket protocols (see `TaskManager.ts` mapping). Logging, metrics, authentication, AQM requests, and SDK event emission belong to Task, Voice, and TaskManager.
|
|
93
|
+
- Consumers: `Task` (`src/services/task/Task.ts`) builds one actor per task; `Voice`, `TaskManager`, and the wxApp voice helpers import `TaskState`, `TaskEvent`, and the payload types; applications read the computed controls through `task.uiControls` and the package-root `getDefaultUIControls`.
|
|
94
|
+
|
|
95
|
+
Use this doc when implementing:
|
|
96
|
+
|
|
97
|
+
- new state transitions
|
|
98
|
+
- event mapping and payload extensions
|
|
99
|
+
- guard/action fixes
|
|
100
|
+
- UI control behavior changes tied to task state
|
|
101
|
+
|
|
102
|
+
## Structure and key files
|
|
103
|
+
|
|
104
|
+
```text
|
|
105
|
+
src/services/task/state-machine/
|
|
106
|
+
├── TaskStateMachine.ts
|
|
107
|
+
├── actions.ts
|
|
108
|
+
├── guards.ts
|
|
109
|
+
├── uiControlsComputer.ts
|
|
110
|
+
├── constants.ts
|
|
111
|
+
├── types.ts
|
|
112
|
+
├── index.ts
|
|
113
|
+
└── docs/
|
|
114
|
+
└── README.md
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
| Path | Responsibility |
|
|
118
|
+
| ---- | -------------- |
|
|
119
|
+
| `src/services/task/state-machine/TaskStateMachine.ts` | **State Graph and Transition Rules**: `TaskStateMachine.ts` defines all states, transition tables, and event handlers that drive the task lifecycle. |
|
|
120
|
+
| `src/services/task/state-machine/actions.ts` | **Deterministic Context Updates**: `actions.ts` implements XState actions for task context mutation and provides emitter placeholders that `Task` overrides to surface SDK events. |
|
|
121
|
+
| `src/services/task/state-machine/guards.ts` | **Transition Eligibility**: `guards.ts` contains pure predicates that gate transitions based on current context, task data, and backend state. |
|
|
122
|
+
| `src/services/task/state-machine/uiControlsComputer.ts` | **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. |
|
|
123
|
+
| `src/services/task/state-machine/constants.ts`, `src/services/task/state-machine/types.ts` | **Typed Event Contracts**: `constants.ts` and `types.ts` define `TaskState`, `TaskEvent`, and the `TaskEventPayloadMap` so transitions and payloads stay type-safe. |
|
|
124
|
+
| `src/services/task/state-machine/index.ts` | **Public Exports**: `index.ts` exposes the state machine factory, event enums, and types for consumption by the task layer. |
|
|
125
|
+
| `src/services/task/Task.ts` | Actor lifecycle, action overrides, event emission (parent module) |
|
|
126
|
+
| `src/services/task/TaskManager.ts` | Maps backend events to state-machine events (parent module) |
|
|
127
|
+
| `src/services/task/types.ts` | Shared task data structures: `TaskData`, `TaskUIControls`, `InteractionUIControls`, destination types (parent module) |
|
|
128
|
+
| `src/services/task/state-machine/docs/README.md` | This module specification |
|
|
129
|
+
| `test/unit/spec/services/task/state-machine/TaskStateMachine.ts` | Transition and action tests |
|
|
130
|
+
| `test/unit/spec/services/task/state-machine/guards.ts` | Guard tests |
|
|
131
|
+
| `test/unit/spec/services/task/state-machine/uiControlsComputer.ts` | UI-control tests |
|
|
132
|
+
| `test/unit/spec/services/task/state-machine/types.ts` | Event type-guard tests |
|
|
133
|
+
|
|
134
|
+
## Public surface
|
|
135
|
+
|
|
136
|
+
The module is internal to the package (contract `contact-center-task-state-machine`). Only
|
|
137
|
+
`getDefaultUIControls` reaches applications, through the package root (contract `contact-center-sdk`).
|
|
138
|
+
|
|
139
|
+
| Surface | Consumer | Compatibility commitment | Source |
|
|
140
|
+
| -------- | ---------- | ------------------------ | -------- |
|
|
141
|
+
| `createTaskStateMachine`, type `TaskStateMachine` (`contact-center-task-state-machine`) | `Task` (module-internal Task integration) | Internal; takes `uiControlConfig` and optional `options.actions` (a partial `TaskActionsMap`); may change with its callers in the same change | `src/services/task/state-machine/index.ts` |
|
|
142
|
+
| `TaskState`, `TaskEvent`, `isEventOfType`, types `TaskContext`, `TaskEventPayload`, `TaskStateMachineConfig`, `UIControlConfig`, `TaskActionsMap`, `TaskActionArgs` (`contact-center-task-state-machine`) | Task, Voice, TaskManager, wxApp voice helpers | Internal; every event keeps a typed payload entry | `src/services/task/state-machine/types.ts` |
|
|
143
|
+
| `guards`, types `GuardParams`, `GuardFunction`; `actions`, `createInitialContext` (`contact-center-task-state-machine`) | Internal state-graph implementations and unit tests | Internal | `src/services/task/state-machine/guards.ts` |
|
|
144
|
+
| `getDefaultUIControls` (`contact-center-sdk`) | Applications | Published: returns `{main, consult, activeLeg: 'main', consultTransferDestinations: {consult: [], transfer: []}}` with every control hidden and disabled; exported from `uiControlsComputer.ts` and re-exported directly by package root; not exported by `state-machine/index.ts` | `src/index.ts` |
|
|
145
|
+
| `computeUIControls`, `haveUIControlsChanged` (`contact-center-task-state-machine`) | Task, actions | Internal | `src/services/task/state-machine/uiControlsComputer.ts` |
|
|
146
|
+
| `computeVoiceInteractionUIControls` / `computeDigitalInteractionUIControls` | none outside the file | private helpers; not public APIs | `src/services/task/state-machine/uiControlsComputer.ts` |
|
|
147
|
+
|
|
148
|
+
## Dependencies
|
|
149
|
+
|
|
150
|
+
| Dependency | Why it is required | Failure behavior |
|
|
151
|
+
| --------------------- | ------------------ | ----------------------------------- |
|
|
152
|
+
| XState (`xstate` 5.24.0, contract `xstate-runtime`) | `setup`, `createMachine`, `.provide`, and `assign` build the actor graph | Build-time dependency; no runtime fallback |
|
|
153
|
+
| TaskData and task-event contracts (`src/services/task/types.ts`) | `TaskData`, `TaskUIControls`, `InteractionUIControls`, `DestinationType`, channel and voice-variant enums shape context and controls | Type-level; payload fields read defensively with optional chaining |
|
|
154
|
+
| Task and TaskManager event/action integration (`src/services/task/Task.ts`, `src/services/task/TaskManager.ts`) | Task owns the actor and supplies action overrides; TaskManager and Voice send mapped `TaskEvent` values | Without overrides, emitters, `requestAutoAnswer`, `requestCleanup`, and `cleanupResources` are no-ops and `syncTaskDataFromEvent` is unimplemented |
|
|
155
|
+
| Task utilities (`src/services/task/TaskUtils.ts`, `src/services/task/WebexCallingUtils.ts`) | Customer-in-call, conference participant counts, conference-in-progress, EP-DN pending-merge, campaign-preview, server hold, and wxApp device checks | Pure helpers; return false on missing data |
|
|
156
|
+
| Config constants (`src/services/config/constants.ts`, `src/services/config/types.ts`, `src/constants.ts`) | `COLLABORATION_ACCESS.NONE`, `CC_EVENTS` consult terminal events, inbound and outdial direction constants | Static constants |
|
|
157
|
+
|
|
158
|
+
## Requirements
|
|
159
|
+
|
|
160
|
+
| ID | WHAT | WHY | Source Evidence | Test / Example Evidence | Assumptions / Gaps | Confidence |
|
|
161
|
+
|---|---|---|---|---|---|---|
|
|
162
|
+
| TASK_STATE_MACHINE-R-001 | Map typed Task events through the XState graph and preserve guards/actions for offer, assignment, consult, conference, transfer, wrapup, termination, and hydration. | A deterministic event vocabulary isolates lifecycle policy from transport payloads. | `src/services/task/state-machine/TaskStateMachine.ts` | `test/unit/spec/services/task/state-machine/TaskStateMachine.ts` | None. | PRESENT |
|
|
163
|
+
| TASK_STATE_MACHINE-R-003 | Treat `syncTaskDataFromEvent` as a Task-supplied machine implementation, not a default action in `actions.ts`. | The reusable graph declares the action name while Task owns integration-specific data synchronization. | `src/services/task/Task.ts` | `test/unit/spec/services/task/Task.ts` | None. | PRESENT |
|
|
164
|
+
| TASK_STATE_MACHINE-R-004 | Compute per-leg action controls and ordered `consultTransferDestinations.consult`/`.transfer` arrays through `uiControlsComputer`, preserving the public `getDefaultUIControls` shape with empty destination arrays. Voice queue rules use Consult profile enablement or Transfer direction plus `callProcessingDetails.outdialTransferToQueueEnabled`; digital supports agent/queue only; profile `NONE` removes the matching category. | Applications depend on one deterministic Task control surface, the default order (`agent`, `queue`, `dialNumber`, `entryPoint`), and correct action/media/profile gating. | `src/services/task/state-machine/uiControlsComputer.ts` | `test/unit/spec/services/task/state-machine/uiControlsComputer.ts` | Consumers may further hide allowed categories but must not infer or enable omitted categories. | PRESENT |
|
|
165
|
+
| 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 |
|
|
166
|
+
| 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 |
|
|
167
|
+
| 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 |
|
|
168
|
+
| TASK_STATE_MACHINE-R-008 | `CONTACT_OWNER_CHANGED` must synchronize task/context data and emit `task:hydrate` without transitioning state. Participant Drop must rely on the existing `ParticipantLeftConference` mapping rather than adding an initiating state event. `PARTICIPANT_LEAVE` and `CONSULT_END` end the task for the current Agent only when `guards.didCurrentAgentLeaveMainInteraction` passes; `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. TaskManager's owner-change mapping and recovery are TASK-R-010 in the [task module specification](../../docs/README.md). | Owner-sensitive consumers must rerender promptly while participant removal and consult removal 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` | `test/unit/spec/services/task/state-machine/TaskStateMachine.ts`, `test/unit/spec/services/task/state-machine/guards.ts`, `test/unit/spec/services/task/Task.ts` | Backend delivery of complete departure payloads is outside this module. | PRESENT |
|
|
169
|
+
| TASK_STATE_MACHINE-R-009 | Every implemented state except the final ones handles `OUTBOUND_FAILED`: `IDLE` terminates (race before `TASK_INCOMING`), and every other active state enters `WRAPPING_UP` when `guards.shouldWrapUp` passes, otherwise `TERMINATED`, always emitting `emitTaskOutdialFailed`. | An outdial failure can arrive in any phase of the call, including before the task is offered, and must never leave a task stuck in an active state. | `src/services/task/state-machine/TaskStateMachine.ts` | `test/unit/spec/services/task/state-machine/TaskStateMachine.ts` | None. | PRESENT |
|
|
170
|
+
| TASK_STATE_MACHINE-R-010 | `COMPLETED` and `TERMINATED` are final states; `COMPLETED` entry runs `emitTaskWrappedup` before `cleanupResources`, `TERMINATED` entry runs `cleanupResources`, and `computeUIControls` returns `getDefaultUIControls()` for both. | Subscribers must receive intact task data before cleanup removes the task from the collection, and no control may stay enabled on a finished task. | `src/services/task/state-machine/TaskStateMachine.ts`, `src/services/task/state-machine/uiControlsComputer.ts` | `test/unit/spec/services/task/state-machine/TaskStateMachine.ts` | None. | PRESENT |
|
|
171
|
+
|
|
172
|
+
## Design overview
|
|
173
|
+
|
|
174
|
+
Stack: TypeScript 5.4, XState 5 actors, pure guards, assign actions, Jest 27. The state pattern (via XState) is used to manage complex task lifecycle with clear states, transitions, guards, and actions.
|
|
175
|
+
|
|
176
|
+
It is instantiated by `Task` and receives mapped backend/user events through `sendStateMachineEvent(...)`.
|
|
177
|
+
|
|
178
|
+
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.
|
|
179
|
+
|
|
180
|
+
### Runtime integration
|
|
181
|
+
|
|
182
|
+
`Task` owns one actor per task; `Task.initializeStateMachine`, the snapshot subscription, and UI-control emission are specified in the [task module specification](../../docs/README.md).
|
|
183
|
+
|
|
184
|
+
`createTaskStateMachine(uiControlConfig, options?)` builds the graph from `getTaskStateMachineConfig(uiControlConfig)` with `setup` and calls `.provide({actions: {...actions, ...options?.actions}})`, so a caller override replaces the default action of the same name. The config has `id: 'taskStateMachine'`, `initial: TaskState.IDLE`, and `context: createInitialContext(uiControlConfig, TaskState.IDLE)`. `setup` from `xstate` types the context as `TaskContext` and events as `TaskEventPayload`, and the default `actions` and `guards` come from `./actions` and `./guards`. `getTaskStateMachineConfig(uiControlConfig)` returns root-level `on` handlers and a `states` map in which each `[TaskState.X]` node maps `[TaskEvent.Y]` to one transition object or a guarded array of `{guard, target, actions}` entries; the transitions are listed per state in State machine.
|
|
185
|
+
|
|
186
|
+
API-driven transition from `voice/Voice.ts`:
|
|
187
|
+
|
|
188
|
+
```typescript
|
|
189
|
+
// task.hold() / task.resume() -> holdResume()
|
|
190
|
+
stateMachineService.send({type: TaskEvent.HOLD_INITIATED, mediaResourceId});
|
|
191
|
+
// ... backend call succeeds
|
|
192
|
+
stateMachineService.send({type: TaskEvent.HOLD_SUCCESS, mediaResourceId});
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Backend-driven transition from `TaskManager.ts`:
|
|
196
|
+
|
|
197
|
+
```typescript
|
|
198
|
+
const eventPayload = TaskManager.mapEventToTaskStateMachineEvent(
|
|
199
|
+
CC_EVENTS.AGENT_CONTACT_RESERVED,
|
|
200
|
+
taskData
|
|
201
|
+
);
|
|
202
|
+
if (eventPayload) {
|
|
203
|
+
task.sendStateMachineEvent(eventPayload);
|
|
204
|
+
}
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
### Guards
|
|
208
|
+
|
|
209
|
+
Guards are boolean conditions that determine if a state transition is allowed. These functions validate the current context before allowing transitions. Each guard in the `guards` object of `src/services/task/state-machine/guards.ts` takes `{context, event}` (`GuardParams`) and reads task data through `getTaskDataFromEvent(event)`; the self agent comes from `getSelfAgentId(context, taskData)`, which prefers `context.uiControlConfig.agentId`, then `context.taskData.agentId`, then the event's `taskData.agentId`.
|
|
210
|
+
|
|
211
|
+
Principles:
|
|
212
|
+
|
|
213
|
+
- Guards must be pure and must return boolean only
|
|
214
|
+
- No mutation or side-effects.
|
|
215
|
+
- Reuse helper accessors (e.g., `getTaskDataFromEvent`).
|
|
216
|
+
|
|
217
|
+
Hydrate (state-based) guards:
|
|
218
|
+
|
|
219
|
+
- `isInteractionTerminated` checks if the interaction is in terminated state: true when `event.taskData.interaction.isTerminated === true`, or when the self participant has `isWrapUp === true`.
|
|
220
|
+
- `isEpDnPendingConferenceMergeHydrate` is true when `isEpDnConsultPendingConferenceMerge(taskData, selfAgentId)` reports an EP-DN consult merged to conference before the destination joined the main call.
|
|
221
|
+
- `isInteractionConsulting` checks if the interaction is consulting: true when `event.taskData.interaction.state === 'consulting'`; when the self participant's `consultState` is `consulting` (or `consultInitiated` with `isConsulted === false`) and a consult media leg exists; when `callProcessingDetails.relationshipType === 'consult'` while the interaction state is `connected` (EP-DN consulted agent); or when the interaction is `post_call` but the self agent is still consulting on consult media (`hasActiveConsultInPostCall`).
|
|
222
|
+
- `isInteractionHeld` checks if the interaction is held: true when `event.taskData.interaction.state === 'hold'` or the main media leg (`mainInteractionId` or `interactionId`) has `isHold === true`.
|
|
223
|
+
- `isInteractionConnected` checks if the interaction is connected: true when `event.taskData.interaction.state === 'connected'`.
|
|
224
|
+
- `isConferencingByParticipants` checks if conference is in progress by participants: it counts participants of the main call media whose `pType` is not `Customer` or `Supervisor` and who have not left, and returns true when `agentCount >= 2`.
|
|
225
|
+
|
|
226
|
+
Conference guards:
|
|
227
|
+
|
|
228
|
+
- `conferenceInProgressFromEvent` checks if conference is in progress from event taskData: false without `taskData.interaction`, otherwise `getIsConferenceInProgress(taskData)`.
|
|
229
|
+
- `isConferenceHoldParticipantFromEvent` reads `callProcessingDetails.conferenceHoldParticipant` from event or context task data and accepts boolean `true` or string `'true'`.
|
|
230
|
+
- `shouldDowngradeConferenceToConnected` checks if conference should downgrade to connected: using event or context task data, it returns false without a self agent or main call id, and does not downgrade while backend still reports active conference state (`interaction.state === 'conference'`); it then requires `getConferenceParticipantsCount` below 2, `getIsCustomerInCall` true, and the self agent in the main call media participants.
|
|
231
|
+
|
|
232
|
+
Consult guards:
|
|
233
|
+
|
|
234
|
+
- `didInitiateConsult` checks if current agent initiated consult: false when `event.taskData.isConsulted === true`; with `consultingAgentId` it returns `isSelfConsultingAgent(context, event.taskData)`, otherwise `context.consultInitiator === true`. It is defined but not referenced by the graph.
|
|
235
|
+
- `isConsultingAssignment` is true when an `ASSIGN` payload has `isConsulted === true`, `callProcessingDetails.relationshipType === 'consult'`, or interaction state `consulting`; EP-DN and consulted legs can arrive as `AGENT_CONTACT_ASSIGNED` without a preceding AgentConsulting event.
|
|
236
|
+
- `isCampaignReservationAccept` is true for a `TASK_INCOMING` event with `isCampaignReservationAccept === true`.
|
|
237
|
+
|
|
238
|
+
Wrapup guards:
|
|
239
|
+
|
|
240
|
+
- `shouldWrapUp` checks if this agent should move to wrapup: false without task data; for `CONFERENCE_END` it requires a self agent, then returns `agentsPendingWrapUp.includes(selfAgentId)` when that array is non-empty, otherwise `wrapUpRequired === true` or the self participant's `isWrapUp === true`; for every other event it returns `shouldWrapUpForThisAgent(context, taskData)`.
|
|
241
|
+
- `shouldWrapUpForThisAgent` (helper) applies the priority `agentsPendingWrapUp` > `wrapUpRequired` / participant `isWrapUp` > interaction `owner === selfAgentId` > `isConsulted === false`.
|
|
242
|
+
- `shouldWrapUpOrIsInitiator` checks if wrapup is required OR current agent is consult initiator: `Boolean(event.taskData?.wrapUpRequired || context.consultInitiator)`.
|
|
243
|
+
- `isCampaignPreviewContactEnded` is true for a `CONTACT_ENDED` on a campaign preview task when no explicit wrap-up signal exists (`wrapUpRequired`, self `isWrapUp`, self in `agentsPendingWrapUp`, or interaction state `wrapUp`).
|
|
244
|
+
- `didCurrentAgentLeaveMainInteraction` checks whether the current agent left the main interaction: it returns true when the event's `participantId` (or `taskData.participantId`) equals the self agent, or when the updated participants map omits the self agent. 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.
|
|
245
|
+
- `isSelfConferenceTransferInitiator`: True when this agent initiated the conference transfer (widgets or desktop). Mirrors determineConsultInitiator — consultingAgentId === self only (not consultState). It returns true when `context.transferConferenceRequested === true`, otherwise `taskData.consultingAgentId === selfAgentId`.
|
|
246
|
+
- `isPassiveConferenceTransferObserver`: Passive observer: another agent transferred; refresh data only. It is false when `isSelfConferenceTransferInitiator` passes, or when the participants map omits the self agent or marks it `hasLeft`; otherwise true.
|
|
247
|
+
|
|
248
|
+
Server state guards:
|
|
249
|
+
|
|
250
|
+
- `isPrimaryMediaOnHold` checks if primary media leg is on hold: false without task data or `taskData.mediaResourceId`, otherwise `taskData.interaction.media[taskData.mediaResourceId].isHold === true`.
|
|
251
|
+
|
|
252
|
+
### Actions
|
|
253
|
+
|
|
254
|
+
Actions are side effects executed during state machine transitions from current state to target state(next state).
|
|
255
|
+
Actions contain:
|
|
256
|
+
|
|
257
|
+
- Context synchronization (`initializeTask`, `updateTaskData`, `syncTaskDataFromEvent`)
|
|
258
|
+
- Lifecycle mutations (`clearConsultState`, `markEnded`, consult/conference flags)
|
|
259
|
+
- Integration hooks (`requestAutoAnswer`, `requestCleanup`, emitter placeholders)
|
|
260
|
+
|
|
261
|
+
Principles:
|
|
262
|
+
|
|
263
|
+
- Context mutations should be centralized in `assign(...)` actions
|
|
264
|
+
- Emitter actions intentionally no-op defaults and overridden by `Task` to bridge machine transitions to SDK events.
|
|
265
|
+
- Deterministic updates from `taskData`.
|
|
266
|
+
|
|
267
|
+
Context update actions in `src/services/task/state-machine/actions.ts`:
|
|
268
|
+
|
|
269
|
+
- `initializeTask` initializes context for an incoming task: it resets `consultInitiator: false`, `exitingConference: false`, `consultDestinationType: null`, `consultDestinationAgentJoined: false`, then spreads `deriveTaskDataUpdates(context, event.taskData)`.
|
|
270
|
+
- `updateTaskData` updates taskData plus derived recording/consult fields through `deriveTaskDataUpdates(context, event.taskData)`, which stores the task data (copying `agentId` to `consultingAgentId` for `AgentConsultCreated`), derives recording flags from `callProcessingDetails`, derives `consultInitiator`, `consultFromConference`, `consultDestinationAgentJoined`, `consultDestinationType`, `consultDestinationAgentId`, `consultCallHeld`, and `hideBlindTransferForEpDnPendingMerge`, clears consult context on `AgentConsultEnded` and `AgentConsultFailed` payloads, and recomputes `uiControls` for the state inferred by `getTaskStateForUiControls`. An event without task data leaves context unchanged.
|
|
271
|
+
- `syncTaskDataFromEvent` keeps Task instance data in sync: it is not in the default map; the Task override in `src/services/task/Task.ts` calls `this.updateTaskFromEvent(event)`.
|
|
272
|
+
- `setHoldState` updates the hold flag on a specific media leg in `context.taskData.interaction.media`: it handles `HOLD_SUCCESS` and `UNHOLD_SUCCESS` for `event.mediaResourceId`, ignores events without a known media entry, and sets `consultCallHeld` when the leg is the consult media and this agent is the consult initiator.
|
|
273
|
+
- `setConsultInitiator` returns `consultInitiator: true` for `CONSULT`; for backend events it uses `consultingAgentId` versus the payload `agentId`, or `isConsulted === true` (not initiator), and otherwise leaves the flag.
|
|
274
|
+
- `setConsultDestination` runs only for `CONSULT`: it sets `consultDestinationType`, `consultDestinationAgentId` (from `destAgentId` or `destination`), resets `consultDestinationAgentJoined` and `consultFromConference`, and preserves the current interaction snapshot while recording `destAgentId`.
|
|
275
|
+
- `setConsultAgentJoined` sets `consultDestinationAgentJoined` on `CONSULTING_ACTIVE` when the event carries `consultDestinationAgentJoined: true` and the flag is not already set.
|
|
276
|
+
- Conference/consult lifecycle mutators: `handleConferenceStarted` returns `{consultInitiator: false}`; `handleConsultFailed` clears the same consult fields as `clearConsultState` and recomputes controls from event or context task data; `handleParticipantLeft`, `handleTransferConferenceSuccess`, and `handleConferenceFailed` store `event.taskData` when present, otherwise change nothing.
|
|
277
|
+
- Consult destination and mode flags: `setConsultFromConference` returns `{consultFromConference: true}`; `setExitingConference` returns `{exitingConference: true}`.
|
|
278
|
+
- Conference transfer flags: `setTransferConferenceRequested` returns `{transferConferenceRequested: true}`; `clearTransferConferenceRequested` returns `{transferConferenceRequested: false}`.
|
|
279
|
+
- Consult call hold flags: `setConsultCallHeld` / `handleSwitchToMainCall` set `consultCallHeld: true`; `clearConsultCallHeld` / `handleSwitchToConsult` set `consultCallHeld: false`.
|
|
280
|
+
- `setRecordingState` is the recording state mutator for pause/resume events: `PAUSE_RECORDING` sets `recordingControlsAvailable: true` and `recordingInProgress: false`; `RESUME_RECORDING` sets both true.
|
|
281
|
+
- `clearConsultState` resets consult/conference-related context: `consultDestinationType: null`, `consultDestinationAgentId: null`, `consultDestinationAgentJoined: false`, `consultInitiator: false`, `exitingConference: false`, `consultCallHeld: false`, `consultFromConference: false`, `transferConferenceRequested: false`, recomputes `hideBlindTransferForEpDnPendingMerge`, and recomputes `uiControls`.
|
|
282
|
+
- `markEnded` is the end-of-task cleanup for recording flags: `{recordingControlsAvailable: false, recordingInProgress: false}`.
|
|
283
|
+
|
|
284
|
+
Event emission actions: every `emitTask*` entry in the default map (incoming, campaign preview reservation and failures, hydrate, offer contact, assigned, hold, resume, end, offer consult, consult created, consulting, consult accepted, consult end, reject, wrapup, recording started/paused/resumed, wrapped up, participant left, conference started/ended/failed, exit conference, transfer conference and its failure, switch call, outdial failed) is a no-op placeholder. `Task.getStateMachineActionOverrides()` and the Voice overrides replace them: for example `emitTaskIncoming` emits `TASK_EVENTS.TASK_INCOMING`, `emitTaskAssigned` emits `TASK_EVENTS.TASK_ASSIGNED` plus `TASK_EVENTS.TASK_MULTI_LOGIN_HYDRATE`, `emitTaskHold` (Voice) emits `TASK_EVENTS.TASK_HOLD`, and `emitTaskWrapup` updates task data and emits `TASK_EVENTS.TASK_WRAPUP` only when `this.data.wrapUpRequired` is true.
|
|
285
|
+
|
|
286
|
+
Cleanup actions: `requestCleanup` and `cleanupResources` are no-op placeholders in `actions.ts` and are overridden in `Task.ts`. The `requestCleanup` override emits `TASK_EVENTS.TASK_CLEANUP` with `{removeFromCollection: false}` (keep the task object); `cleanupResources` emits it with `{removeFromCollection: true}`.
|
|
287
|
+
|
|
288
|
+
Auto-answer actions: `requestAutoAnswer` is a placeholder in `actions.ts` and is overridden in `Task.ts`, where it calls `autoAnswerIfNeeded()`. That method auto-accepts only for digital or WebRTC voice tasks whose `data.isAutoAnswering` is true.
|
|
289
|
+
|
|
290
|
+
### UI control computation
|
|
291
|
+
|
|
292
|
+
`uiControlsComputer.ts` computes `TaskUIControls` from:
|
|
293
|
+
|
|
294
|
+
- current machine state
|
|
295
|
+
- current context
|
|
296
|
+
- channel type (voice vs digital)
|
|
297
|
+
- call/participant metadata from `taskData`
|
|
298
|
+
- config flags (`isEndTaskEnabled`, recording toggles, voice variant)
|
|
299
|
+
|
|
300
|
+
This keeps all control enablement/visibility logic centralized and testable.
|
|
301
|
+
|
|
302
|
+
Transition source for controls: `computeUIControls()` in `uiControlsComputer.ts`. Inputs and output of `computeUIControls(currentState, context, fallbackTaskData?)`:
|
|
303
|
+
|
|
304
|
+
- `TaskState`
|
|
305
|
+
- `TaskContext` (including `taskData`)
|
|
306
|
+
- `UIControlConfig` (channel type, agentId, voice variant, recording flags)
|
|
307
|
+
- `TaskUIControls` with per-control visibility and enabled state.
|
|
308
|
+
|
|
309
|
+
The result has `main` and `consult` `InteractionUIControls` (`accept`, `decline`, `hold`, `mute`, `end`, `transfer`, `consult`, `consultTransfer`, `endConsult`, `recording`, `conference`, `wrapup`, `exitConference`, `transferConference`, `mergeToConference`, `switch`, `keypad`, each `{isVisible, isEnabled}`), an `activeLeg` of `main` or `consult`, and `consultTransferDestinations` with ordered `consult` and `transfer` arrays. Rules:
|
|
310
|
+
|
|
311
|
+
- `TERMINATED` and `COMPLETED` return `getDefaultUIControls()`; `IDLE` returns default per-leg controls; an unknown channel type returns `getDefaultUIControls()`.
|
|
312
|
+
- Voice: `getVoiceLegState` decides whether a consult leg exists, which leg is active (`main` when `consultCallHeld`, else `consult`), and the state each leg is computed for; the consult leg gets real controls only when it exists. Live task data passed as the fallback is preferred over the actor snapshot during multi-login sync. `end` is hidden when `isEndTaskEnabled` is false on non-WebRTC voice; `recording` needs `recordingControlsAvailable` and `isRecordingEnabled`; `consultTransfer` is always disabled; wxApp-engaged tasks get `mute` and `keypad` on the main leg only.
|
|
313
|
+
- Digital: `accept` in `OFFERED`; `end` and `transfer` in `CONNECTED`; `wrapup` when wrapping up or the interaction is terminated; every other control disabled, and the consult leg always default.
|
|
314
|
+
- Destinations: without `consultTransferConfig` both arrays are empty. Otherwise the order is `agent` (unless `accessBuddyTeam` is `NONE`), `queue` (unless `accessQueue` is `NONE`; on voice, consult needs `allowConsultToQueue` and transfer needs an inbound direction or an outdial with `callProcessingDetails.outdialTransferToQueueEnabled === true`), then on voice only `dialNumber` and `entryPoint` (unless `accessEntryPoint` is `NONE`).
|
|
315
|
+
|
|
316
|
+
### Change recipes
|
|
317
|
+
|
|
318
|
+
Adding a new event:
|
|
319
|
+
|
|
320
|
+
1. Add event in `TaskEvent` (`constants.ts`)
|
|
321
|
+
2. Add typed payload in `TaskEventPayloadMap` (`types.ts`)
|
|
322
|
+
3. Wire transitions in `TaskStateMachine.ts`
|
|
323
|
+
4. Add/adjust actions in `actions.ts`
|
|
324
|
+
5. Add guard(s) in `guards.ts` if needed
|
|
325
|
+
6. Update `TaskManager` event mapping and unit tests
|
|
326
|
+
|
|
327
|
+
Adding a new guard:
|
|
328
|
+
|
|
329
|
+
1. Implement pure guard in `guards.ts`
|
|
330
|
+
2. Use guard in `TaskStateMachine.ts` transition array
|
|
331
|
+
3. Keep side-effects in actions only (no side-effects in guards)
|
|
332
|
+
4. Add tests for positive and negative transition paths
|
|
333
|
+
|
|
334
|
+
Changing UI controls:
|
|
335
|
+
|
|
336
|
+
1. Update control logic in `computeVoiceInteractionUIControls()` or `computeDigitalInteractionUIControls()`
|
|
337
|
+
2. Preserve `getDefaultUIControls()` shape compatibility
|
|
338
|
+
3. Verify behavior across `CONNECTED`, `HELD`, `CONSULTING`, `CONFERENCING`, `WRAPPING_UP`
|
|
339
|
+
4. Add or update UI-control unit coverage
|
|
340
|
+
|
|
341
|
+
## Data flow and sequence coverage
|
|
342
|
+
|
|
343
|
+
Call style: in-process, synchronous XState `send` calls on one actor per task. Backend CC events from WebSocket are mapped to `TaskEvent` in `TaskManager.mapEventToTaskStateMachineEvent`. The state machine consumes only `TaskEvent` and never raw CC events. Task APIs in `Voice` send the initiating, success, and failure events of their own HTTP requests.
|
|
344
|
+
|
|
345
|
+
```mermaid
|
|
346
|
+
flowchart LR
|
|
347
|
+
WS[Contact Center notification] --> TM[TaskManager maps to TaskEvent]
|
|
348
|
+
TM --> Task[Owning Task instance]
|
|
349
|
+
Task --> Actor[XState task actor]
|
|
350
|
+
Actor --> Guards[guards.ts evaluates transition]
|
|
351
|
+
Guards --> Actions[actions.ts mutates TaskContext and emits]
|
|
352
|
+
Task --> Sync[Task-provided syncTaskDataFromEvent]
|
|
353
|
+
Actions --> UI[computeUIControls]
|
|
354
|
+
UI --> Events[Task UI controls and TASK_EVENTS]
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
Sequence coverage:
|
|
358
|
+
|
|
359
|
+
| Operation group | Entry and outcome | Diagram or evidence | Failure and recovery coverage |
|
|
360
|
+
| --------------- | ----------------- | ------------------- | ----------------------------- |
|
|
361
|
+
| Offer and assignment | `TASK_INCOMING` enters OFFERED; `TASK_OFFERED` updates that state and `ASSIGN` selects CONNECTED or CONSULTING. | Offer and assignment | RONA/invite/assign failures terminate the offered task; outbound failure may wrap up instead. |
|
|
362
|
+
| Hold/resume | `HOLD_INITIATED`/`UNHOLD_INITIATED` enter intermediate states; success/failure selects HELD or CONNECTED. | Hold and resume | Failure transitions update task data and restore the stable state; Voice owns the thrown error and failure metric. |
|
|
363
|
+
| Consult | `CONSULT` enters `CONSULT_INITIATING`; local and backend success/failure/end events select CONSULTING, HELD, CONNECTED, CONFERENCING, WRAPPING_UP, or TERMINATED. | Consult | Consult failure/end actions update and clear consult context according to guards. |
|
|
364
|
+
| Conference/transfer | `MERGE_TO_CONFERENCE` and `CONFERENCE_START` use `CONF_INITIATING`/`CONFERENCING`; conference transfer uses the `TRANSFER_CONFERENCE*` events and blind or consult transfer uses `TRANSFER_SUCCESS`/`TRANSFER_FAILED`. | Conference and transfer | `handleConferenceFailed` returns to CONSULTING; transfer and conference-transfer failures keep the current state and clear the request flag. |
|
|
365
|
+
| Wrapup/termination | End/wrapup events select `WRAPPING_UP` or `TERMINATED`; `WRAPUP_COMPLETE` moves `WRAPPING_UP` to `COMPLETED`. | Wrapup and termination | Terminal states are final and cannot accept normal interaction transitions. |
|
|
366
|
+
| Hydrate/recovery | IDLE `HYDRATE` guards restore WRAPPING_UP, CONFERENCING, CONSULTING, HELD, or CONNECTED; otherwise remain IDLE. | Hydrate and recovery | Root-level HYDRATE on an active task updates data without incorrectly re-entering a child state. |
|
|
367
|
+
| Backend event mapping | TaskManager converts each CC event to one `TaskEvent` payload (or `null`) before it reaches the actor. | Backend CC event mapping (table) | Unmapped CC events return `null` and never reach the actor; `CONTACT_ENDED` remaps to `OUTBOUND_FAILED` for agent-terminated wxApp outdials. |
|
|
368
|
+
|
|
369
|
+
### Offer and assignment
|
|
370
|
+
|
|
371
|
+
```mermaid
|
|
372
|
+
sequenceDiagram
|
|
373
|
+
participant TM as TaskManager
|
|
374
|
+
participant Task
|
|
375
|
+
participant Actor as XState actor
|
|
376
|
+
participant Guard as guards.ts
|
|
377
|
+
participant Action as actions.ts / Task override
|
|
378
|
+
TM->>Task: AgentContactReserved mapping
|
|
379
|
+
Task->>Actor: send(TASK_INCOMING)
|
|
380
|
+
Actor->>Action: initializeTask + emit incoming/reservation
|
|
381
|
+
Actor-->>Task: OFFERED
|
|
382
|
+
alt offer update then assignment
|
|
383
|
+
Task->>Actor: TASK_OFFERED then ASSIGN
|
|
384
|
+
Actor->>Action: update data + emit offer/assignment
|
|
385
|
+
Actor-->>Task: CONNECTED or guarded CONSULTING
|
|
386
|
+
else RONA/invite/assign failure
|
|
387
|
+
Actor->>Action: failure cleanup/event
|
|
388
|
+
Actor-->>Task: TERMINATED
|
|
389
|
+
end
|
|
390
|
+
```
|
|
391
|
+
|
|
392
|
+
### Hold and resume
|
|
393
|
+
|
|
394
|
+
```mermaid
|
|
395
|
+
sequenceDiagram
|
|
396
|
+
participant Task
|
|
397
|
+
participant Actor as XState actor
|
|
398
|
+
participant Action as actions.ts
|
|
399
|
+
participant UI as uiControlsComputer
|
|
400
|
+
Task->>Actor: HOLD_INITIATED or UNHOLD_INITIATED
|
|
401
|
+
Actor-->>Task: HOLD_INITIATING or RESUME_INITIATING
|
|
402
|
+
alt success event
|
|
403
|
+
Task->>Actor: HOLD_SUCCESS or UNHOLD_SUCCESS
|
|
404
|
+
Actor->>Action: update media hold state; emit task event
|
|
405
|
+
Actor->>UI: compute controls for HELD/CONNECTED
|
|
406
|
+
Actor-->>Task: HELD or CONNECTED
|
|
407
|
+
else failure event
|
|
408
|
+
Task->>Actor: HOLD_FAILED or UNHOLD_FAILED
|
|
409
|
+
Actor->>Action: update task data
|
|
410
|
+
Actor-->>Task: CONNECTED or HELD
|
|
411
|
+
end
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
### Consult
|
|
415
|
+
|
|
416
|
+
```mermaid
|
|
417
|
+
sequenceDiagram
|
|
418
|
+
participant Task
|
|
419
|
+
participant Actor as XState actor
|
|
420
|
+
participant Guard as guards.ts
|
|
421
|
+
participant Action as actions.ts / Task override
|
|
422
|
+
Task->>Actor: CONSULT
|
|
423
|
+
Actor->>Action: setConsultInitiator + setConsultDestination
|
|
424
|
+
Actor-->>Task: CONSULT_INITIATING
|
|
425
|
+
alt local request or backend consult succeeds
|
|
426
|
+
Task->>Actor: CONSULT_SUCCESS / CONSULTING_ACTIVE
|
|
427
|
+
Actor->>Action: updateTaskData + consult context actions
|
|
428
|
+
Actor-->>Task: CONSULTING
|
|
429
|
+
else consult failed/ended/cancelled
|
|
430
|
+
Task->>Actor: CONSULT_FAILED / CTQ_CANCEL / CONSULT_END
|
|
431
|
+
Actor->>Guard: consultFromConference, isPrimaryMediaOnHold, departure guards
|
|
432
|
+
Actor->>Action: clear/update consult context
|
|
433
|
+
Actor-->>Task: CONFERENCING, HELD, CONNECTED, or termination path
|
|
434
|
+
end
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
### Conference and transfer
|
|
438
|
+
|
|
439
|
+
```mermaid
|
|
440
|
+
sequenceDiagram
|
|
441
|
+
participant Task
|
|
442
|
+
participant Actor as XState actor
|
|
443
|
+
participant Action as actions.ts
|
|
444
|
+
Task->>Actor: MERGE_TO_CONFERENCE
|
|
445
|
+
Actor-->>Task: CONF_INITIATING
|
|
446
|
+
alt conference succeeds
|
|
447
|
+
Task->>Actor: CONFERENCE_START
|
|
448
|
+
Actor->>Action: updateTaskData + syncTaskDataFromEvent + handleConferenceStarted + clearConsultState
|
|
449
|
+
Actor-->>Task: CONFERENCING
|
|
450
|
+
else conference fails
|
|
451
|
+
Task->>Actor: CONFERENCE_FAILED
|
|
452
|
+
Actor->>Action: handleConferenceFailed + emitTaskConferenceFailed
|
|
453
|
+
Actor-->>Task: CONSULTING
|
|
454
|
+
end
|
|
455
|
+
Task->>Actor: TRANSFER_CONFERENCE (CONSULTING or CONFERENCING)
|
|
456
|
+
Actor->>Action: setTransferConferenceRequested + emitTaskTransferConference
|
|
457
|
+
alt conference transfer succeeds
|
|
458
|
+
Task->>Actor: TRANSFER_CONFERENCE_SUCCESS
|
|
459
|
+
Actor->>Action: handleTransferConferenceSuccess + clearTransferConferenceRequested
|
|
460
|
+
Actor-->>Task: CONFERENCING, WRAPPING_UP, or TERMINATED
|
|
461
|
+
else conference transfer fails
|
|
462
|
+
Task->>Actor: TRANSFER_CONFERENCE_FAILED
|
|
463
|
+
Actor->>Action: clearTransferConferenceRequested + emitTaskTransferConferenceFailed
|
|
464
|
+
Actor-->>Task: stay in current state
|
|
465
|
+
end
|
|
466
|
+
```
|
|
467
|
+
|
|
468
|
+
### Wrapup and termination
|
|
469
|
+
|
|
470
|
+
```mermaid
|
|
471
|
+
sequenceDiagram
|
|
472
|
+
participant TM as TaskManager
|
|
473
|
+
participant Task
|
|
474
|
+
participant Actor as XState actor
|
|
475
|
+
TM->>Task: end/wrapup/backend terminal event
|
|
476
|
+
Task->>Actor: mapped TaskEvent
|
|
477
|
+
alt wrapup required
|
|
478
|
+
Actor-->>Task: WRAPPING_UP
|
|
479
|
+
Task->>Actor: WRAPUP_COMPLETE
|
|
480
|
+
Actor-->>Task: COMPLETED
|
|
481
|
+
else contact terminated/no wrapup
|
|
482
|
+
Actor-->>Task: TERMINATED
|
|
483
|
+
end
|
|
484
|
+
Note over Actor: terminal states do not accept normal interaction transitions
|
|
485
|
+
```
|
|
486
|
+
|
|
487
|
+
### Hydrate and recovery
|
|
488
|
+
|
|
489
|
+
The HYDRATE event restores state machine state after page refresh or reconnection. In `IDLE` the guarded `HYDRATE` entries choose the restored state (order and guards in State machine > IDLE); in any other state the root handler only refreshes data. TaskManager's owner-change recovery that sends this internal `HYDRATE` is specified in the [task module specification](../../docs/README.md) (TASK-R-010).
|
|
490
|
+
|
|
491
|
+
```mermaid
|
|
492
|
+
sequenceDiagram
|
|
493
|
+
participant TM as TaskManager
|
|
494
|
+
participant Task
|
|
495
|
+
participant Actor as XState actor
|
|
496
|
+
participant Guard as guards.ts
|
|
497
|
+
participant Action as actions.ts
|
|
498
|
+
TM->>Task: HYDRATE(taskData)
|
|
499
|
+
Task->>Actor: send(HYDRATE)
|
|
500
|
+
alt actor is IDLE
|
|
501
|
+
Actor->>Guard: choose backend-represented state
|
|
502
|
+
Guard-->>Actor: first passing IDLE HYDRATE guard, or default IDLE
|
|
503
|
+
Actor->>Action: updateTaskData + emitTaskHydrate
|
|
504
|
+
else actor already active
|
|
505
|
+
Actor->>Action: root-level updateTaskData + emitTaskHydrate
|
|
506
|
+
Actor-->>Task: retain current child state with updated context
|
|
507
|
+
end
|
|
508
|
+
```
|
|
509
|
+
|
|
510
|
+
### Backend CC event mapping
|
|
511
|
+
|
|
512
|
+
Complete mapping from backend CC_EVENTS to internal TaskEvent types, as implemented by `TaskManager.mapEventToTaskStateMachineEvent` in `src/services/task/TaskManager.ts`.
|
|
513
|
+
|
|
514
|
+
| Backend CC Event | TaskEvent | Typical From State(s) | Target State | Notes / Guards |
|
|
515
|
+
|---|---|---|---|---|
|
|
516
|
+
| `AGENT_CONTACT_RESERVED` | `TASK_INCOMING` | `IDLE` | `OFFERED` | Incoming task entry |
|
|
517
|
+
| `AGENT_OFFER_CAMPAIGN_RESERVATION` | `TASK_INCOMING` | `IDLE` | `OFFERED` | Sets `isCampaignReservationAccept`; `guards.isCampaignReservationAccept` emits the campaign preview reservation event instead of incoming. A campaign-preview `AGENT_CONTACT_RESERVED` sets the same flag. |
|
|
518
|
+
| `AGENT_OFFER_CONTACT` | `TASK_OFFERED` | `OFFERED` | `OFFERED` | Offer payload refresh |
|
|
519
|
+
| `AGENT_CONTACT` | `HYDRATE` | `IDLE` | `WRAPPING_UP` / `CONSULTING` / `HELD` / `CONNECTED` / `CONFERENCING` / `IDLE` | Guard-based restore |
|
|
520
|
+
| `CONTACT_UPDATED` | `CONTACT_UPDATED` or `CONTACT_OWNER_CHANGED` | any | same | Owner delta uses existing hydrate path; same/missing owner is context sync only |
|
|
521
|
+
| `CONTACT_OWNER_CHANGED` | `CONTACT_OWNER_CHANGED` | any | same | Context/data sync + `task:hydrate` |
|
|
522
|
+
| `AGENT_OFFER_CONSULT` | `OFFER_CONSULT` | `OFFERED` | `OFFERED` | Receiver-side consult offer |
|
|
523
|
+
| `AGENT_CONTACT_ASSIGNED` | `ASSIGN` | `OFFERED` / `CONNECTED` / `CONSULTING` | `CONNECTED` / `CONSULTING` | Assign/reassign; from `OFFERED`, `guards.isConsultingAssignment` selects `CONSULTING` |
|
|
524
|
+
| `AGENT_CONTACT_HELD` | `HOLD_SUCCESS` | `HOLD_INITIATING` | `HELD` | Includes `mediaResourceId` |
|
|
525
|
+
| `AGENT_CONTACT_UNHELD` | `UNHOLD_SUCCESS` | `RESUME_INITIATING` | `CONNECTED` | Includes `mediaResourceId` |
|
|
526
|
+
| `AGENT_CONSULT_CREATED` | `CONSULT_CREATED` | varies | same | Root-level context action (`updateTaskData` + `setConsultInitiator`); no emitter action; payload stamped `isConsulted: false` |
|
|
527
|
+
| `AGENT_CONSULTING` | `CONSULTING_ACTIVE` | `IDLE` / `OFFERED` / `CONNECTED` / `HELD` / `CONSULT_INITIATING` / `CONSULTING` / `CONFERENCING` | `CONSULTING` | Sets consult joined flag |
|
|
528
|
+
| `AGENT_CONSULT_ENDED` | `CONSULT_END` | `OFFERED` / `CONNECTED` / `HELD` / `CONSULT_INITIATING` / `CONSULTING` / `CONF_INITIATING` / `CONFERENCING` | `CONFERENCING` / `HELD` / `CONNECTED` / `WRAPPING_UP` / `TERMINATED` / same | Depends on departure, initiator, conference, and hold guards |
|
|
529
|
+
| `AGENT_CONSULT_FAILED` | `CONSULT_FAILED` | `OFFERED` / `CONSULT_INITIATING` / `CONSULTING` / `CONFERENCING` / any | `TERMINATED` / `CONFERENCING` / `HELD` / `CONNECTED` / same | Guard-based fallback; root-level handler covers held or connected tasks |
|
|
530
|
+
| `AGENT_CTQ_FAILED` | `CONSULT_FAILED` | `CONSULT_INITIATING` | `CONFERENCING` / `HELD` / `CONNECTED` | Same as consult failed |
|
|
531
|
+
| `AGENT_CTQ_CANCELLED` | `CTQ_CANCEL` | `CONSULT_INITIATING` | `HELD` / `CONNECTED` | Guarded by hold state |
|
|
532
|
+
| `AGENT_CTQ_CANCEL_FAILED` | `CTQ_CANCEL_FAILED` | varies | same | No transition mapping |
|
|
533
|
+
| `AGENT_BLIND_TRANSFERRED` | `TRANSFER_SUCCESS` | `CONNECTED` / `HELD` / `CONSULTING` | `WRAPPING_UP` / `CONNECTED` | `shouldWrapUpOrIsInitiator` |
|
|
534
|
+
| `AGENT_CONSULT_TRANSFERRED` | `TRANSFER_SUCCESS` | `CONNECTED` / `HELD` / `CONSULTING` | `WRAPPING_UP` / `CONNECTED` | Same path |
|
|
535
|
+
| `AGENT_VTEAM_TRANSFERRED` | `TRANSFER_SUCCESS` | `CONNECTED` / `HELD` / `CONSULTING` | `WRAPPING_UP` / `CONNECTED` | Same path |
|
|
536
|
+
| `AGENT_WRAPUP` | `TASK_WRAPUP` | `OFFERED` / `CONNECTED` / `HELD` / `CONSULTING` | `WRAPPING_UP` / `TERMINATED` | `shouldWrapUp` selects wrap-up; default terminates (wxApp outdial pre-accept agent end may wrap while still `OFFERED`) |
|
|
537
|
+
| `AGENT_BLIND_TRANSFER_FAILED` | `TRANSFER_FAILED` | `CONNECTED` / `HELD` / `CONSULTING` | same | Context update |
|
|
538
|
+
| `AGENT_VTEAM_TRANSFER_FAILED` | `TRANSFER_FAILED` | `CONNECTED` / `HELD` / `CONSULTING` | same | Context update |
|
|
539
|
+
| `AGENT_CONSULT_TRANSFER_FAILED` | `TRANSFER_FAILED` | `CONNECTED` / `HELD` / `CONSULTING` | same | Context update |
|
|
540
|
+
| `AGENT_CONFERENCE_TRANSFER_FAILED` | `TRANSFER_FAILED` | `CONNECTED` / `HELD` / `CONSULTING` | same | Context update |
|
|
541
|
+
| `CONTACT_ENDED` | `CONTACT_ENDED` or `OUTBOUND_FAILED` | `OFFERED` / `CONNECTED` / `HELD` / `CONSULTING` / `CONFERENCING` | `WRAPPING_UP` / `TERMINATED` / etc. | wxApp outdial pre-accept decline → `CONTACT_ENDED` → `TERMINATED` (no wrapup) when `wxAppAnswerPending` is false and `agentsPendingWrapUp` is empty (backend may still send `interaction.state: wrapUp`). Post-accept agent end remaps to `OUTBOUND_FAILED` (`AGENT_ENDS`) when `wxAppAnswerPending` or wrapup pending — including while SM is still `OFFERED` before `ASSIGN`. |
|
|
542
|
+
| `AGENT_INVITE_FAILED` | `INVITE_FAILED` | `OFFERED` | `TERMINATED` | Reject path |
|
|
543
|
+
| `AGENT_CONTACT_ASSIGN_FAILED` | `ASSIGN_FAILED` | `OFFERED` | `TERMINATED` | Reject path |
|
|
544
|
+
| `AGENT_CONTACT_OFFER_RONA` | `RONA` | `OFFERED` | `TERMINATED` | Timeout path |
|
|
545
|
+
| `AGENT_OUTBOUND_FAILED` | `OUTBOUND_FAILED` | `IDLE` / `OFFERED` / `CONNECTED` / `HOLD_INITIATING` / `HELD` / `RESUME_INITIATING` / `CONSULT_INITIATING` / `CONSULTING` / `CONF_INITIATING` / `CONFERENCING` | `WRAPPING_UP` or `TERMINATED` | Outbound failure; wrapup when `shouldWrapUp`. Non-wxApp agent-terminated `AGENT_ENDS` sets `suppressOutdialFailedPopup` (wrapup without outdial-failed modal). `IDLE` handles race before `TASK_INCOMING`. |
|
|
546
|
+
| `CAMPAIGN_PREVIEW_ACCEPT_FAILED` / `CAMPAIGN_PREVIEW_SKIP_FAILED` / `CAMPAIGN_PREVIEW_REMOVE_FAILED` | same-named `TaskEvent` | `OFFERED` | same | `updateTaskData` + the matching campaign preview failure emitter |
|
|
547
|
+
| `CONTACT_RECORDING_STARTED` | `RECORDING_STARTED` | any | same | Recording state update |
|
|
548
|
+
| `CONTACT_RECORDING_PAUSED` | `PAUSE_RECORDING` | `CONNECTED` / `HELD` | same | Recording state update |
|
|
549
|
+
| `CONTACT_RECORDING_RESUMED` | `RESUME_RECORDING` | `CONNECTED` / `HELD` | same | Recording state update |
|
|
550
|
+
| `AGENT_WRAPPEDUP` | `WRAPUP_COMPLETE` | `WRAPPING_UP` | `COMPLETED` | Final completion |
|
|
551
|
+
| `AGENT_CONSULT_CONFERENCED` | `CONFERENCE_START` | `CONSULTING` / `CONF_INITIATING` / `CONFERENCING` | `CONFERENCING` / same | Conference established |
|
|
552
|
+
| `AGENT_CONSULT_CONFERENCING` | `CONFERENCE_START` | `CONNECTED` / `HELD` / `CONSULTING` / `CONF_INITIATING` / `CONFERENCING` | `CONFERENCING` / same | Conference in progress |
|
|
553
|
+
| `PARTICIPANT_JOINED_CONFERENCE` | `CONFERENCE_START` | `CONSULTING` / `CONF_INITIATING` / `CONFERENCING` | `CONFERENCING` / same | Conference participant joined |
|
|
554
|
+
| `AGENT_CONSULT_CONFERENCE_FAILED` | `CONFERENCE_FAILED` | `CONF_INITIATING` | `CONSULTING` | Merge fail fallback |
|
|
555
|
+
| `AGENT_CONSULT_CONFERENCE_ENDED` | `CONFERENCE_END` | `CONFERENCING` | `WRAPPING_UP` / `CONNECTED` / `TERMINATED` | Guard-driven |
|
|
556
|
+
| `PARTICIPANT_LEFT_CONFERENCE` | `PARTICIPANT_LEAVE` | `HELD` / `RESUME_INITIATING` / `CONSULTING` / `CONSULT_INITIATING` / `CONFERENCING` | `WRAPPING_UP` / `TERMINATED` / `CONNECTED` / same | Departure guard first; handled and ignoring states are listed in State machine > Shared transition groups |
|
|
557
|
+
| `AGENT_CONFERENCE_TRANSFERRED` | `TRANSFER_CONFERENCE_SUCCESS` | `CONSULTING` / `CONFERENCING` | `WRAPPING_UP` / `CONFERENCING` / `TERMINATED` / same | Initiator/receiver dependent |
|
|
558
|
+
|
|
559
|
+
- `AGENT_CONTACT_UNASSIGNED` -> returns `null` in mapper (`TaskManager.mapEventToTaskStateMachineEvent`); so does every CC event without a case.
|
|
560
|
+
- Events sent by task APIs rather than the mapper: `HOLD_INITIATED`, `UNHOLD_INITIATED`, and `HOLD_SUCCESS` / `UNHOLD_SUCCESS` after the HTTP response, plus `HOLD_FAILED` / `UNHOLD_FAILED` when the AQM hold request rejects on `AgentContactHoldFailed` or `AgentContactUnHoldFailed` (`Voice` hold and resume); `CONSULT` and `CONSULT_SUCCESS` (`task.consult()`); `MERGE_TO_CONFERENCE` and `CONFERENCE_FAILED` (`task.consultConference()`); `EXIT_CONFERENCE_SUCCESS` and `EXIT_CONFERENCE_FAILED` (`task.exitConference()`); `TRANSFER_CONFERENCE` and `TRANSFER_CONFERENCE_FAILED` (`task.transferConference()`); `SWITCH_TO_MAIN_CALL` / `SWITCH_TO_CONSULT` (`task.switchCall()`).
|
|
561
|
+
- API `task.dropConferenceParticipant()` sends no state event: AQM waits for backend `ParticipantLeftConference`; that event follows the existing `PARTICIPANT_LEAVE` path.
|
|
562
|
+
|
|
563
|
+
## Class and component relationships
|
|
564
|
+
|
|
565
|
+
`Task` owns one actor; `TaskStateMachine.ts` composes the default `actions` and `guards`; `actions.ts`
|
|
566
|
+
calls `computeUIControls` from `uiControlsComputer.ts`; `Task` and `Voice` inject action overrides.
|
|
567
|
+
|
|
568
|
+
```mermaid
|
|
569
|
+
classDiagram
|
|
570
|
+
class TaskManager
|
|
571
|
+
class Task
|
|
572
|
+
class TaskStateMachine
|
|
573
|
+
class Guards
|
|
574
|
+
class Actions
|
|
575
|
+
class UIControlsComputer
|
|
576
|
+
TaskManager --> Task : sends mapped events
|
|
577
|
+
Task --> TaskStateMachine : owns configured actor
|
|
578
|
+
TaskStateMachine --> Guards : evaluates
|
|
579
|
+
TaskStateMachine --> Actions : executes
|
|
580
|
+
Task --> Actions : provides syncTaskDataFromEvent
|
|
581
|
+
TaskStateMachine --> UIControlsComputer : recomputes controls
|
|
582
|
+
```
|
|
583
|
+
|
|
584
|
+
## Use cases and flows
|
|
585
|
+
|
|
586
|
+
| Use case | Actor or caller | Primary steps and outcome | Failure or boundary behavior | Evidence |
|
|
587
|
+
| -------- | --------------- | ----------------------------- | ---------------------------- | ------------------------- |
|
|
588
|
+
| `UC-1` Offer and assignment | TaskManager | map reserved/offer/assigned notifications to typed events and enter OFFERED, then CONNECTED or (for consult assignments) CONSULTING with updated task data | RONA, invite, assign, consult-failed, and contact-ended offers terminate; outbound failure and required wrap-up enter `WRAPPING_UP` | `src/services/task/state-machine/TaskStateMachine.ts`, `test/unit/spec/services/task/state-machine/TaskStateMachine.ts` |
|
|
589
|
+
| `UC-2` Hold/resume | Voice API, TaskManager | represent the initiating operation separately, then settle into HELD or CONNECTED from success/failure events | Remote hold or resume from another login session moves `CONNECTED` and `HELD` directly | `src/services/task/state-machine/TaskStateMachine.ts`, `test/unit/spec/services/task/state-machine/TaskStateMachine.ts` |
|
|
590
|
+
| `UC-3` Consult | Voice API, TaskManager | retain main/consult context while moving through CONSULT_INITIATING and CONSULTING; use the Task-supplied synchronization action for ownership changes | Consult failure, queue cancel, and consult end return the initiator to the held or connected main leg, or to the conference | `src/services/task/Task.ts`, `test/unit/spec/services/task/Task.ts` |
|
|
591
|
+
| `UC-4` Conference/transfer | Voice API, TaskManager | execute conference and switch actions only where the graph wires them | Conference failure returns to `CONSULTING`; transfer and conference-transfer failures stay in the current state | `src/services/task/state-machine/actions.ts`, `src/services/task/state-machine/TaskStateMachine.ts` |
|
|
592
|
+
| `UC-5` Wrapup/termination | TaskManager | select WRAPPING_UP, COMPLETED, or TERMINATED from backend state and wrapup requirements | Final states accept no events | `src/services/task/state-machine/TaskStateMachine.ts`, `test/unit/spec/services/task/state-machine/TaskStateMachine.ts` |
|
|
593
|
+
| `UC-6` Hydrate/recovery | TaskManager | use IDLE HYDRATE guards to restore backend state while active-task hydration updates context without a child-state transition | Unmatched hydrate data leaves the actor in `IDLE` | `src/services/task/state-machine/TaskStateMachine.ts`, `test/unit/spec/services/task/state-machine/TaskStateMachine.ts` |
|
|
594
|
+
|
|
595
|
+
## Client state model
|
|
596
|
+
|
|
597
|
+
`TaskContext` only stores data that cannot be derived from state machine state.
|
|
598
|
+
|
|
599
|
+
| State or slice | Owner | Initial state | Transition triggers | Reset or persistence boundary |
|
|
600
|
+
| -------------- | ---------- | ------------- | ------------------- | ----------------------------- |
|
|
601
|
+
| `taskData` | `initializeTask`, `updateTaskData`, `setHoldState`, `setConsultDestination`, `handleParticipantLeft`, `handleTransferConferenceSuccess`, `handleConferenceFailed` | `null` | Any event carrying `taskData` | Lives with the actor; discarded when the task is cleaned up |
|
|
602
|
+
| `consultInitiator`, `consultFromConference`, `consultDestinationType`, `consultDestinationAgentId`, `consultDestinationAgentJoined`, `consultCallHeld` | Consult actions and `deriveTaskDataUpdates` | `false` / `null` | `CONSULT`, `CONSULT_CREATED`, `CONSULTING_ACTIVE`, hold events on the consult leg, switch events | Cleared by `clearConsultState`, `handleConsultFailed`, and consult-terminal payloads (`AgentConsultEnded`, `AgentConsultFailed`) |
|
|
603
|
+
| `exitingConference` | `setExitingConference` (unwired) | `false` | None in the current graph | Reset by `initializeTask` and `clearConsultState` |
|
|
604
|
+
| `transferConferenceRequested` | `setTransferConferenceRequested` | `false` | `TRANSFER_CONFERENCE` | Cleared on conference-transfer success or failure and by `clearConsultState` |
|
|
605
|
+
| `hideBlindTransferForEpDnPendingMerge` | `deriveTaskDataUpdates`, `clearConsultState`, `handleConsultFailed` | `false` | Payloads showing an EP-DN consult merged before Agent 2 joins | Recomputed on every task-data update |
|
|
606
|
+
| `recordingControlsAvailable`, `recordingInProgress` | `deriveTaskDataUpdates`, `setRecordingState` | `false` | `callProcessingDetails` recording fields, `PAUSE_RECORDING`, `RESUME_RECORDING` | `markEnded` sets both false |
|
|
607
|
+
| `uiControlConfig` | `Task` at construction | Task-supplied | None inside the machine | Immutable for the actor's life |
|
|
608
|
+
| `uiControls` | `createInitialContext`, `deriveTaskDataUpdates`, `clearConsultState`, `handleConsultFailed` | `computeUIControls(IDLE, context)` | Every task-data update | Task recomputes its public `uiControls` after each snapshot |
|
|
609
|
+
|
|
610
|
+
## Business rules and invariants
|
|
611
|
+
|
|
612
|
+
| ID | Invariant | WHY | Enforcement source | Test evidence |
|
|
613
|
+
| --------- | ------------------------------------ | ----------- | ------------------ | ------------- |
|
|
614
|
+
| `INV-001` | Every transition event is a declared `TaskEvent`; raw Contact Center messages are mapped by TaskManager before actor delivery. All new events must add a typed payload entry in `TaskEventPayloadMap`. | Source of truth: `TaskEventPayloadMap` in `types.ts`; typed payloads keep transitions and payloads type-safe | `src/services/task/state-machine/types.ts` | `test/unit/spec/services/task/state-machine/types.ts` |
|
|
615
|
+
| `INV-002` | In every `CONSULT_END` and `PARTICIPANT_LEAVE` guarded array, the current-agent departure entries come first, and in `CONFERENCING` the passive-observer entry comes first for `TRANSFER_CONFERENCE_SUCCESS`. | XState evaluates guarded arrays in order; reordering changes which agent terminates or wraps up | `src/services/task/state-machine/TaskStateMachine.ts` | `test/unit/spec/services/task/state-machine/TaskStateMachine.ts` |
|
|
616
|
+
|
|
617
|
+
## Concurrency and reactive flow
|
|
618
|
+
|
|
619
|
+
- Execution model: one XState actor per task on the JavaScript event loop; `send` runs guards and actions synchronously.
|
|
620
|
+
- Ordering guarantees: TaskManager serially maps each backend notification to a Task event; the actor applies guards/actions synchronously for that event, while remote operation completion arrives as later mapped events. XState evaluates guarded transition arrays in order, and the first passing entry wins.
|
|
621
|
+
- Idempotency and retry: no retries inside the module; repeated success events are tolerated because intermediate states consume the first one (for example `HOLD_SUCCESS` from both Voice and `AgentContactHeld`) and later states either ignore it or self-transition.
|
|
622
|
+
- Shared-state protection: context changes only through `assign` actions; guards never mutate. UI controls are recomputed from the resulting context/state and emitted only through the owning Task integration.
|
|
623
|
+
- Blocking restrictions: guards and actions must not await or call transport; the `requestAutoAnswer` override starts an async accept without blocking the transition.
|
|
624
|
+
|
|
625
|
+
## State machine
|
|
626
|
+
|
|
627
|
+
**Transition Source**: `getTaskStateMachineConfig()` in `TaskStateMachine.ts`
|
|
628
|
+
|
|
629
|
+
The actor starts at `IDLE`. Normal interaction paths cover `OFFERED`, `CONNECTED`, `HELD`, `CONSULTING`, and `CONFERENCING`, with explicit initiating states for hold, resume, consult, and conference. `WRAPPING_UP` precedes final `COMPLETED` or `TERMINATED` outcomes. Backend task data remains authoritative for HYDRATE recovery. `TaskState` also declares `CONSULT_INITIATED`, `CONSULT_COMPLETED`, `POST_CALL`, `PARKED`, and `MONITORING`, marked NOT IMPLEMENTED; the graph has no node for them. An event that the current state (and the root) does not handle is ignored, and a guarded array whose guards all fail leaves the state unchanged.
|
|
630
|
+
|
|
631
|
+
This diagram represents state-to-state lifecycle transitions for the task state machine. Labels are `TaskEvent` names with the selecting guard in brackets; the backend source of each event is in the mapping table under Data flow and sequence coverage.
|
|
632
|
+
|
|
633
|
+
```mermaid
|
|
634
|
+
stateDiagram-v2
|
|
635
|
+
[*] --> IDLE
|
|
636
|
+
|
|
637
|
+
%% IDLE
|
|
638
|
+
IDLE --> OFFERED: TASK_INCOMING [isCampaignReservationAccept or default]
|
|
639
|
+
IDLE --> WRAPPING_UP: HYDRATE [isInteractionTerminated]
|
|
640
|
+
IDLE --> CONFERENCING: HYDRATE [isEpDnPendingConferenceMergeHydrate or isConferencingByParticipants]
|
|
641
|
+
IDLE --> CONSULTING: HYDRATE [isInteractionConsulting] / CONSULTING_ACTIVE
|
|
642
|
+
IDLE --> HELD: HYDRATE [isInteractionHeld]
|
|
643
|
+
IDLE --> CONNECTED: HYDRATE [isInteractionConnected]
|
|
644
|
+
IDLE --> TERMINATED: OUTBOUND_FAILED
|
|
645
|
+
|
|
646
|
+
%% OFFERED
|
|
647
|
+
OFFERED --> OFFERED: TASK_OFFERED / OFFER_CONSULT / CAMPAIGN_PREVIEW_*_FAILED
|
|
648
|
+
OFFERED --> CONSULTING: ASSIGN [isConsultingAssignment] / CONSULTING_ACTIVE
|
|
649
|
+
OFFERED --> CONNECTED: ASSIGN [default]
|
|
650
|
+
OFFERED --> WRAPPING_UP: TASK_WRAPUP / OUTBOUND_FAILED [shouldWrapUp]
|
|
651
|
+
OFFERED --> TERMINATED: TASK_WRAPUP / OUTBOUND_FAILED [default]
|
|
652
|
+
OFFERED --> TERMINATED: RONA / ASSIGN_FAILED / INVITE_FAILED / CONTACT_ENDED / CONSULT_FAILED / CONSULT_END
|
|
653
|
+
|
|
654
|
+
%% CONNECTED
|
|
655
|
+
CONNECTED --> CONNECTED: ASSIGN / UNHOLD_SUCCESS / TRANSFER_SUCCESS [default] / TRANSFER_FAILED / CONSULT_END [consultInitiator] / PAUSE_RECORDING / RESUME_RECORDING
|
|
656
|
+
CONNECTED --> HOLD_INITIATING: HOLD_INITIATED
|
|
657
|
+
CONNECTED --> RESUME_INITIATING: UNHOLD_INITIATED
|
|
658
|
+
CONNECTED --> HELD: HOLD_SUCCESS / CONSULT_END [consultInitiator and main media held]
|
|
659
|
+
CONNECTED --> CONSULT_INITIATING: CONSULT
|
|
660
|
+
CONNECTED --> CONSULTING: CONSULTING_ACTIVE
|
|
661
|
+
CONNECTED --> CONFERENCING: CONFERENCE_START / CONTACT_ENDED [conferenceInProgressFromEvent]
|
|
662
|
+
CONNECTED --> WRAPPING_UP: TRANSFER_SUCCESS [shouldWrapUpOrIsInitiator] / CONTACT_ENDED, OUTBOUND_FAILED, EXIT_CONFERENCE_SUCCESS [shouldWrapUp] / TASK_WRAPUP / CONSULT_END [self left and shouldWrapUp]
|
|
663
|
+
CONNECTED --> TERMINATED: CONTACT_ENDED [isCampaignPreviewContactEnded or default] / OUTBOUND_FAILED, EXIT_CONFERENCE_SUCCESS [default] / CONSULT_END [self left]
|
|
664
|
+
|
|
665
|
+
%% HOLD_INITIATING
|
|
666
|
+
HOLD_INITIATING --> HELD: HOLD_SUCCESS
|
|
667
|
+
HOLD_INITIATING --> CONNECTED: HOLD_FAILED
|
|
668
|
+
HOLD_INITIATING --> WRAPPING_UP: TASK_WRAPUP / OUTBOUND_FAILED [shouldWrapUp]
|
|
669
|
+
HOLD_INITIATING --> TERMINATED: OUTBOUND_FAILED [default]
|
|
670
|
+
|
|
671
|
+
%% HELD
|
|
672
|
+
HELD --> HELD: PAUSE_RECORDING / RESUME_RECORDING / TRANSFER_FAILED / CONSULT_END [default] / PARTICIPANT_LEAVE [default]
|
|
673
|
+
HELD --> RESUME_INITIATING: UNHOLD_INITIATED
|
|
674
|
+
HELD --> CONNECTED: UNHOLD_SUCCESS / TRANSFER_SUCCESS [default]
|
|
675
|
+
HELD --> CONSULT_INITIATING: CONSULT
|
|
676
|
+
HELD --> CONSULTING: CONSULTING_ACTIVE
|
|
677
|
+
HELD --> CONFERENCING: CONFERENCE_START / CONTACT_ENDED [conferenceInProgressFromEvent]
|
|
678
|
+
HELD --> WRAPPING_UP: TRANSFER_SUCCESS [shouldWrapUpOrIsInitiator] / CONTACT_ENDED, OUTBOUND_FAILED, EXIT_CONFERENCE_SUCCESS [shouldWrapUp] / TASK_WRAPUP / CONSULT_END or PARTICIPANT_LEAVE [self left and shouldWrapUp]
|
|
679
|
+
HELD --> TERMINATED: CONTACT_ENDED [isCampaignPreviewContactEnded or default] / OUTBOUND_FAILED, EXIT_CONFERENCE_SUCCESS [default] / CONSULT_END or PARTICIPANT_LEAVE [self left]
|
|
680
|
+
|
|
681
|
+
%% RESUME_INITIATING
|
|
682
|
+
RESUME_INITIATING --> CONNECTED: UNHOLD_SUCCESS
|
|
683
|
+
RESUME_INITIATING --> HELD: UNHOLD_FAILED
|
|
684
|
+
RESUME_INITIATING --> RESUME_INITIATING: PARTICIPANT_LEAVE [default]
|
|
685
|
+
RESUME_INITIATING --> WRAPPING_UP: TASK_WRAPUP / OUTBOUND_FAILED [shouldWrapUp] / PARTICIPANT_LEAVE [self left and shouldWrapUp]
|
|
686
|
+
RESUME_INITIATING --> TERMINATED: OUTBOUND_FAILED [default] / PARTICIPANT_LEAVE [self left]
|
|
687
|
+
|
|
688
|
+
%% CONSULT_INITIATING
|
|
689
|
+
CONSULT_INITIATING --> CONSULT_INITIATING: HOLD_SUCCESS / PARTICIPANT_LEAVE [default]
|
|
690
|
+
CONSULT_INITIATING --> CONSULTING: CONSULT_SUCCESS / CONSULTING_ACTIVE
|
|
691
|
+
CONSULT_INITIATING --> CONFERENCING: CONSULT_FAILED [consultFromConference]
|
|
692
|
+
CONSULT_INITIATING --> HELD: CONSULT_FAILED / CTQ_CANCEL / CONSULT_END [isPrimaryMediaOnHold]
|
|
693
|
+
CONSULT_INITIATING --> CONNECTED: HOLD_FAILED / CONSULT_FAILED / CTQ_CANCEL / CONSULT_END [default]
|
|
694
|
+
CONSULT_INITIATING --> WRAPPING_UP: TASK_WRAPUP / OUTBOUND_FAILED [shouldWrapUp] / CONSULT_END or PARTICIPANT_LEAVE [self left and shouldWrapUp]
|
|
695
|
+
CONSULT_INITIATING --> TERMINATED: OUTBOUND_FAILED [default] / CONSULT_END or PARTICIPANT_LEAVE [self left]
|
|
696
|
+
|
|
697
|
+
%% CONSULTING
|
|
698
|
+
CONSULTING --> CONSULTING: CONSULTING_ACTIVE / SWITCH_TO_MAIN_CALL / SWITCH_TO_CONSULT / HOLD_SUCCESS / UNHOLD_SUCCESS / TRANSFER_FAILED / TRANSFER_CONFERENCE / TRANSFER_CONFERENCE_FAILED / PARTICIPANT_LEAVE [default]
|
|
699
|
+
CONSULTING --> CONFERENCING: CONSULT_FAILED [consultFromConference] / CONSULT_END [consultInitiator and conference in progress] / TRANSFER_CONFERENCE_SUCCESS [not self initiator] / CONFERENCE_START
|
|
700
|
+
CONSULTING --> HELD: CONSULT_FAILED [isPrimaryMediaOnHold] / CONSULT_END [conference downgraded on hold, or consultInitiator]
|
|
701
|
+
CONSULTING --> CONNECTED: CONSULT_FAILED [default] / CONSULT_END [conference downgraded, or consultCallHeld] / PARTICIPANT_LEAVE [shouldDowngradeConferenceToConnected] / TRANSFER_SUCCESS [default] / ASSIGN
|
|
702
|
+
CONSULTING --> CONF_INITIATING: MERGE_TO_CONFERENCE
|
|
703
|
+
CONSULTING --> WRAPPING_UP: CONSULT_END [customer left and wrap-up] / TRANSFER_SUCCESS [shouldWrapUpOrIsInitiator] / TRANSFER_CONFERENCE_SUCCESS, OUTBOUND_FAILED [shouldWrapUp] / CONTACT_ENDED / TASK_WRAPUP / CONSULT_END or PARTICIPANT_LEAVE [self left and shouldWrapUp]
|
|
704
|
+
CONSULTING --> TERMINATED: CONSULT_END [consulted agent] / TRANSFER_CONFERENCE_SUCCESS, OUTBOUND_FAILED [default] / CONSULT_END or PARTICIPANT_LEAVE [self left]
|
|
705
|
+
|
|
706
|
+
%% CONF_INITIATING
|
|
707
|
+
CONF_INITIATING --> CONFERENCING: CONFERENCE_START
|
|
708
|
+
CONF_INITIATING --> CONSULTING: CONFERENCE_FAILED
|
|
709
|
+
CONF_INITIATING --> CONNECTED: CONSULT_END [default]
|
|
710
|
+
CONF_INITIATING --> WRAPPING_UP: CONSULT_END [isTerminated, or self left and shouldWrapUp] / TASK_WRAPUP / OUTBOUND_FAILED [shouldWrapUp]
|
|
711
|
+
CONF_INITIATING --> TERMINATED: OUTBOUND_FAILED [default] / CONSULT_END [self left]
|
|
712
|
+
|
|
713
|
+
%% CONFERENCING
|
|
714
|
+
CONFERENCING --> CONFERENCING: CONFERENCE_START / CONSULT_END [default] / HOLD_SUCCESS, UNHOLD_SUCCESS, PARTICIPANT_LEAVE [default] / TRANSFER_CONFERENCE / TRANSFER_CONFERENCE_SUCCESS [passive observer or not self initiator] / TRANSFER_CONFERENCE_FAILED / CONTACT_ENDED / CONSULT_FAILED
|
|
715
|
+
CONFERENCING --> CONSULT_INITIATING: CONSULT
|
|
716
|
+
CONFERENCING --> CONSULTING: CONSULTING_ACTIVE
|
|
717
|
+
CONFERENCING --> HELD: HOLD_SUCCESS [shouldDowngradeConferenceToConnected]
|
|
718
|
+
CONFERENCING --> CONNECTED: UNHOLD_SUCCESS, PARTICIPANT_LEAVE [shouldDowngradeConferenceToConnected] / CONFERENCE_END [customerInCall]
|
|
719
|
+
CONFERENCING --> WRAPPING_UP: EXIT_CONFERENCE_SUCCESS, TRANSFER_CONFERENCE_SUCCESS, CONFERENCE_END, TASK_WRAPUP, OUTBOUND_FAILED [shouldWrapUp] / CONSULT_END [isTerminated and wrap-up, or self left and shouldWrapUp] / PARTICIPANT_LEAVE [self left and shouldWrapUp]
|
|
720
|
+
CONFERENCING --> TERMINATED: EXIT_CONFERENCE_SUCCESS, TRANSFER_CONFERENCE_SUCCESS, CONFERENCE_END, OUTBOUND_FAILED [default] / CONSULT_END or PARTICIPANT_LEAVE [self left]
|
|
721
|
+
|
|
722
|
+
%% WRAPPING_UP / FINAL
|
|
723
|
+
WRAPPING_UP --> WRAPPING_UP: TASK_WRAPUP
|
|
724
|
+
WRAPPING_UP --> COMPLETED: WRAPUP_COMPLETE
|
|
725
|
+
COMPLETED --> [*]
|
|
726
|
+
TERMINATED --> [*]
|
|
727
|
+
```
|
|
728
|
+
|
|
729
|
+
The full diagram above is the source of truth.
|
|
730
|
+
|
|
731
|
+
### Root-level handlers
|
|
732
|
+
|
|
733
|
+
These handlers sit on the machine root, so they run in any non-final state whose own `on` map does not handle the event, and never change the active state:
|
|
734
|
+
|
|
735
|
+
- `RECORDING_STARTED`: `updateTaskData`, `emitTaskRecordingStarted`
|
|
736
|
+
- `CONTACT_UPDATED`: `updateTaskData`, `syncTaskDataFromEvent`
|
|
737
|
+
- `CONTACT_OWNER_CHANGED`: `updateTaskData`, `syncTaskDataFromEvent`, `emitTaskHydrate`
|
|
738
|
+
- `HYDRATE`: `updateTaskData`, `emitTaskHydrate` (state restoration with transitions is handled in `IDLE`, because root-level events cannot transition to child states)
|
|
739
|
+
- `CONSULT_CREATED`: `updateTaskData`, `setConsultInitiator` (AgentConsultCreated while already HELD/CONNECTED, an external consult)
|
|
740
|
+
- `CONSULT_FAILED`: `updateTaskData`, `handleConsultFailed` (AgentConsultFailed while HELD/CONNECTED without passing through `CONSULT_INITIATING`)
|
|
741
|
+
|
|
742
|
+
### Shared transition groups
|
|
743
|
+
|
|
744
|
+
`TaskStateMachine.ts` builds three helper arrays (`currentAgentParticipantLeaveTransitions`, `currentAgentConsultEndTransitions`, `exitConferenceSuccessTransitions`) and reuses them so lifecycle handling stays consistent across active states; the outbound-failure pair is repeated inline in each state:
|
|
745
|
+
|
|
746
|
+
- Outbound failure (`OUTBOUND_FAILED`, inline in `OFFERED`, `CONNECTED`, `HOLD_INITIATING`, `HELD`, `RESUME_INITIATING`, `CONSULT_INITIATING`, `CONSULTING`, `CONF_INITIATING`, `CONFERENCING`): Guard `guards.shouldWrapUp` -> `WRAPPING_UP` with `updateTaskData`, `markEnded`, `emitTaskOutdialFailed`, `emitTaskWrapup`; default -> `TERMINATED` with `updateTaskData`, `markEnded`, `emitTaskOutdialFailed`, `emitTaskEnd`.
|
|
747
|
+
- Current-agent participant leave (`currentAgentParticipantLeaveTransitions`, first entries of every `PARTICIPANT_LEAVE` array): Guard `guards.didCurrentAgentLeaveMainInteraction && guards.shouldWrapUp` -> `WRAPPING_UP` with `updateTaskData`, `handleParticipantLeft`, `markEnded`, `clearConsultState`, `emitTaskParticipantLeft`; Guard `guards.didCurrentAgentLeaveMainInteraction` -> `TERMINATED` with the same actions plus `emitTaskEnd`.
|
|
748
|
+
- Current-agent consult end (`currentAgentConsultEndTransitions`, first entries of every `CONSULT_END` array except `OFFERED`): Guard `guards.didCurrentAgentLeaveMainInteraction && guards.shouldWrapUp` -> `WRAPPING_UP` with `updateTaskData`, `markEnded`, `clearConsultState`, `emitTaskConsultEnd`, `emitTaskWrapup`; Guard `guards.didCurrentAgentLeaveMainInteraction` -> `TERMINATED` with `updateTaskData`, `markEnded`, `clearConsultState`, `emitTaskConsultEnd`, `emitTaskEnd`.
|
|
749
|
+
- Exit conference success (`exitConferenceSuccessTransitions`, in `CONNECTED`, `HELD`, `CONFERENCING`): Guard `guards.shouldWrapUp` -> `WRAPPING_UP` with `updateTaskData`, `markEnded`, `clearConsultState`; default -> `TERMINATED` with `updateTaskData`, `markEnded`, `clearConsultState`, `emitTaskEnd`.
|
|
750
|
+
|
|
751
|
+
`PARTICIPANT_LEAVE` is handled in `HELD`, `RESUME_INITIATING`, `CONSULTING`, `CONSULT_INITIATING`, and `CONFERENCING`; `CONNECTED`, `HOLD_INITIATING`, and `CONF_INITIATING` ignore the event.
|
|
752
|
+
|
|
753
|
+
### IDLE
|
|
754
|
+
|
|
755
|
+
**Description**: Initial state before a task is offered or restored.
|
|
756
|
+
|
|
757
|
+
**How this state is reached (incoming transitions)**:
|
|
758
|
+
|
|
759
|
+
- Machine start -> `IDLE` (no event, no actions)
|
|
760
|
+
|
|
761
|
+
**Valid transitions from `IDLE` state**:
|
|
762
|
+
|
|
763
|
+
- `TASK_INCOMING` -> `OFFERED` (campaign preview reservation)
|
|
764
|
+
- Guard: `guards.isCampaignReservationAccept`
|
|
765
|
+
- Actions: `initializeTask`, `emitTaskCampaignPreviewReservation`
|
|
766
|
+
- `TASK_INCOMING` -> `OFFERED`
|
|
767
|
+
- Guard: default
|
|
768
|
+
- Actions: `initializeTask`, `emitTaskIncoming`
|
|
769
|
+
`HYDRATE` entries are evaluated in the order listed below; the first passing guard wins, and each entry updates context with hydrated data and emits TASK_HYDRATE (`emitTaskHydrate`).
|
|
770
|
+
|
|
771
|
+
- `HYDRATE` -> `WRAPPING_UP`
|
|
772
|
+
- Guard: `guards.isInteractionTerminated`
|
|
773
|
+
- Actions: `updateTaskData`, `markEnded`, `emitTaskHydrate`
|
|
774
|
+
- `HYDRATE` -> `CONFERENCING` (EP-DN consult merged before Agent 2 joins)
|
|
775
|
+
- Guard: `guards.isEpDnPendingConferenceMergeHydrate`
|
|
776
|
+
- Actions: `updateTaskData`, `emitTaskHydrate`
|
|
777
|
+
- `HYDRATE` -> `CONSULTING`
|
|
778
|
+
- Guard: `guards.isInteractionConsulting`
|
|
779
|
+
- Actions: `updateTaskData`, `emitTaskHydrate`
|
|
780
|
+
- `HYDRATE` -> `HELD`
|
|
781
|
+
- Guard: `guards.isInteractionHeld`
|
|
782
|
+
- Actions: `updateTaskData`, `emitTaskHydrate`
|
|
783
|
+
- `HYDRATE` -> `CONNECTED`
|
|
784
|
+
- Guard: `guards.isInteractionConnected`
|
|
785
|
+
- Actions: `updateTaskData`, `emitTaskHydrate`
|
|
786
|
+
- `HYDRATE` -> `CONFERENCING`
|
|
787
|
+
- Guard: `guards.isConferencingByParticipants`
|
|
788
|
+
- Actions: `updateTaskData`, `emitTaskHydrate`
|
|
789
|
+
- `HYDRATE` -> stay `IDLE` (default hydrate branch)
|
|
790
|
+
- Guard: default
|
|
791
|
+
- Actions: `updateTaskData`, `emitTaskHydrate`
|
|
792
|
+
- `OUTBOUND_FAILED` -> `TERMINATED` (AgentOutboundFailed can arrive before `TASK_INCOMING` due to race conditions)
|
|
793
|
+
- Guard: none
|
|
794
|
+
- Actions: `updateTaskData`, `markEnded`, `emitTaskOutdialFailed`, `emitTaskEnd`
|
|
795
|
+
- `CONSULTING_ACTIVE` -> `CONSULTING` (EP-DN split-leg ordering can deliver AgentConsulting before HYDRATE/TASK_INCOMING)
|
|
796
|
+
- Guard: none
|
|
797
|
+
- Actions: `setConsultInitiator`, `setConsultDestination`, `setConsultFromConference`, `setConsultAgentJoined`, `updateTaskData`, `emitTaskConsultAccepted`, `emitTaskConsulting`
|
|
798
|
+
|
|
799
|
+
### OFFERED
|
|
800
|
+
|
|
801
|
+
**Description**: Task has been offered/reserved and is waiting for assignment or termination paths. Reached from `IDLE` by `TASK_INCOMING`.
|
|
802
|
+
|
|
803
|
+
**Valid transitions from `OFFERED`**:
|
|
804
|
+
|
|
805
|
+
- `TASK_OFFERED` -> Stay `OFFERED`
|
|
806
|
+
- Guard: none
|
|
807
|
+
- Actions: `updateTaskData`, `emitTaskOfferContact`, `requestAutoAnswer`
|
|
808
|
+
- `OFFER_CONSULT` -> Stay `OFFERED`
|
|
809
|
+
- Guard: none
|
|
810
|
+
- Actions: `updateTaskData`, `emitTaskOfferConsult`, `requestAutoAnswer`
|
|
811
|
+
- `ASSIGN` -> `CONSULTING`
|
|
812
|
+
- Guard: `guards.isConsultingAssignment`
|
|
813
|
+
- Actions: `updateTaskData`, `emitTaskConsultAccepted`, `emitTaskConsulting`
|
|
814
|
+
- `ASSIGN` -> `CONNECTED`
|
|
815
|
+
- Guard: default
|
|
816
|
+
- Actions: `updateTaskData`, `emitTaskAssigned`
|
|
817
|
+
- `CONSULTING_ACTIVE` -> `CONSULTING`
|
|
818
|
+
- Guard: none
|
|
819
|
+
- Actions: `setConsultAgentJoined`, `setConsultDestination`, `updateTaskData`, `emitTaskConsultAccepted`, `emitTaskConsulting`
|
|
820
|
+
- `TASK_WRAPUP` -> `WRAPPING_UP`
|
|
821
|
+
- Guard: `guards.shouldWrapUp`
|
|
822
|
+
- Actions: `updateTaskData`, `markEnded`; `WRAPPING_UP` entry emits `task:wrapup`
|
|
823
|
+
- `TASK_WRAPUP` -> `TERMINATED` (default branch)
|
|
824
|
+
- Guard: default (when wrap-up is not required)
|
|
825
|
+
- Actions: `updateTaskData`, `markEnded`, `emitTaskEnd`
|
|
826
|
+
- `CONTACT_ENDED` -> `TERMINATED` (customer disconnects before the agent answers)
|
|
827
|
+
- Guard: none
|
|
828
|
+
- Actions: `updateTaskData`, `markEnded`, `emitTaskEnd`
|
|
829
|
+
- `RONA` / `ASSIGN_FAILED` / `INVITE_FAILED` -> `TERMINATED`
|
|
830
|
+
- Guard: none
|
|
831
|
+
- Actions: `updateTaskData`, `markEnded`, `emitTaskReject`
|
|
832
|
+
- `OUTBOUND_FAILED` -> `WRAPPING_UP` or `TERMINATED` (outbound failure group)
|
|
833
|
+
- `CAMPAIGN_PREVIEW_ACCEPT_FAILED` / `CAMPAIGN_PREVIEW_SKIP_FAILED` / `CAMPAIGN_PREVIEW_REMOVE_FAILED` -> Stay `OFFERED`
|
|
834
|
+
- Guard: none
|
|
835
|
+
- Actions: `updateTaskData`, and `emitTaskCampaignPreviewAcceptFailed` / `emitTaskCampaignPreviewSkipFailed` / `emitTaskCampaignPreviewRemoveFailed`
|
|
836
|
+
- `CONSULT_FAILED` -> `TERMINATED` (consulted agent does not answer or declines)
|
|
837
|
+
- Guard: none
|
|
838
|
+
- Actions: `updateTaskData`, `clearConsultState`, `emitTaskReject`
|
|
839
|
+
- `CONSULT_END` -> `TERMINATED` (initiator ends the consult before the consulted agent accepts)
|
|
840
|
+
- Guard: none
|
|
841
|
+
- Actions: `updateTaskData`, `clearConsultState`, `emitTaskConsultEnd`
|
|
842
|
+
|
|
843
|
+
### CONNECTED
|
|
844
|
+
|
|
845
|
+
**Description**: Agent is connected on the main customer interaction leg. Reached from `OFFERED` (`ASSIGN`), `IDLE` (`HYDRATE`), `HOLD_INITIATING` (`HOLD_FAILED`), `HELD` (`UNHOLD_SUCCESS`, `TRANSFER_SUCCESS`), `RESUME_INITIATING` (`UNHOLD_SUCCESS`), `CONSULT_INITIATING`, `CONSULTING`, `CONF_INITIATING`, and `CONFERENCING` branches.
|
|
846
|
+
|
|
847
|
+
**Valid transitions from `CONNECTED`**:
|
|
848
|
+
|
|
849
|
+
- `ASSIGN` -> `CONNECTED` (self-transition)
|
|
850
|
+
- Guard: none
|
|
851
|
+
- Actions: `updateTaskData`, `emitTaskAssigned`
|
|
852
|
+
- `HOLD_INITIATED` -> `HOLD_INITIATING`
|
|
853
|
+
- Guard: none
|
|
854
|
+
- Actions: none
|
|
855
|
+
- `HOLD_SUCCESS` -> `HELD` (remote hold from another login session)
|
|
856
|
+
- Guard: none
|
|
857
|
+
- Actions: `updateTaskData`, `setHoldState`, `emitTaskHold`
|
|
858
|
+
- `UNHOLD_INITIATED` -> `RESUME_INITIATING`
|
|
859
|
+
- Guard: none
|
|
860
|
+
- Actions: none
|
|
861
|
+
- `UNHOLD_SUCCESS` -> Stay `CONNECTED` (main media still on hold after a consult RONA or decline)
|
|
862
|
+
- Guard: none
|
|
863
|
+
- Actions: `updateTaskData`, `setHoldState`, `emitTaskResume`
|
|
864
|
+
- `CONSULT` -> `CONSULT_INITIATING`
|
|
865
|
+
- Guard: none
|
|
866
|
+
- Actions: `setConsultInitiator`, `setConsultDestination`
|
|
867
|
+
- `CONSULTING_ACTIVE` -> `CONSULTING`
|
|
868
|
+
- Guard: none
|
|
869
|
+
- Actions: `setConsultInitiator`, `setConsultDestination`, `setConsultAgentJoined`, `updateTaskData`, `emitTaskConsultAccepted`, `emitTaskConsulting`
|
|
870
|
+
- `CONFERENCE_START` -> `CONFERENCING`
|
|
871
|
+
- Guard: none
|
|
872
|
+
- Actions: `updateTaskData`, `syncTaskDataFromEvent`, `clearConsultState`, `emitTaskConferenceStarted`
|
|
873
|
+
- `TRANSFER_SUCCESS` -> `WRAPPING_UP`
|
|
874
|
+
- Guard: `guards.shouldWrapUpOrIsInitiator`
|
|
875
|
+
- Actions: `updateTaskData`, `markEnded`, `clearConsultState`, `emitTaskWrapup`
|
|
876
|
+
- `TRANSFER_SUCCESS` -> Stay `CONNECTED` (receiver/default branch)
|
|
877
|
+
- Guard: default
|
|
878
|
+
- Actions: `updateTaskData`, `clearConsultState`
|
|
879
|
+
- `TRANSFER_FAILED` -> Stay `CONNECTED`
|
|
880
|
+
- Guard: none
|
|
881
|
+
- Actions: `updateTaskData`
|
|
882
|
+
- `CONSULT_END` -> `WRAPPING_UP` or `TERMINATED` (current-agent consult end group)
|
|
883
|
+
- `CONSULT_END` -> `HELD`
|
|
884
|
+
- Guard: inline `context.consultInitiator === true` and the main media leg `isHold === true`
|
|
885
|
+
- Actions: `updateTaskData`, `clearConsultState`, `emitTaskConsultEnd`
|
|
886
|
+
- `CONSULT_END` -> Stay `CONNECTED`
|
|
887
|
+
- Guard: inline `context.consultInitiator === true`
|
|
888
|
+
- Actions: `updateTaskData`, `clearConsultState`, `emitTaskConsultEnd`
|
|
889
|
+
- `CONTACT_ENDED` -> `TERMINATED` (campaign preview)
|
|
890
|
+
- Guard: `guards.isCampaignPreviewContactEnded`
|
|
891
|
+
- Actions: `updateTaskData`, `markEnded`, `emitTaskEnd`
|
|
892
|
+
- `CONTACT_ENDED` -> `CONFERENCING`
|
|
893
|
+
- Guard: `guards.conferenceInProgressFromEvent`
|
|
894
|
+
- Actions: `updateTaskData`, `emitTaskConferenceStarted`, `requestCleanup`
|
|
895
|
+
- `CONTACT_ENDED` -> `WRAPPING_UP`
|
|
896
|
+
- Guard: `guards.shouldWrapUp`
|
|
897
|
+
- Actions: `updateTaskData`, `markEnded`, `emitTaskWrapup`, `requestCleanup`
|
|
898
|
+
- `CONTACT_ENDED` -> `TERMINATED` (default branch)
|
|
899
|
+
- Guard: default
|
|
900
|
+
- Actions: `updateTaskData`, `markEnded`, `emitTaskEnd`
|
|
901
|
+
- `TASK_WRAPUP` -> `WRAPPING_UP`
|
|
902
|
+
- Guard: none
|
|
903
|
+
- Actions: `updateTaskData`, `markEnded`; `WRAPPING_UP` entry emits `task:wrapup`
|
|
904
|
+
- `OUTBOUND_FAILED` -> `WRAPPING_UP` or `TERMINATED` (outbound failure group)
|
|
905
|
+
- `PAUSE_RECORDING` / `RESUME_RECORDING` -> Stay `CONNECTED`
|
|
906
|
+
- Guard: none
|
|
907
|
+
- Actions: `updateTaskData`, `setRecordingState`, `emitTaskRecordingPaused` / `emitTaskRecordingResumed`
|
|
908
|
+
- `EXIT_CONFERENCE_SUCCESS` -> `WRAPPING_UP` or `TERMINATED`
|
|
909
|
+
- Guard: `guards.shouldWrapUp` (wrap-up branch) or default (terminate)
|
|
910
|
+
- Actions: `updateTaskData`, `markEnded`, `clearConsultState`, or `emitTaskEnd`; `WRAPPING_UP` entry emits `task:wrapup` (same as `CONFERENCING`; Voice `exitConference()` while actor stays `CONNECTED` with conference in task data)
|
|
911
|
+
|
|
912
|
+
### HOLD_INITIATING
|
|
913
|
+
|
|
914
|
+
**Description**: Hold request has been sent and is awaiting backend confirmation. Reached from `CONNECTED` by `HOLD_INITIATED`.
|
|
915
|
+
|
|
916
|
+
**Valid transitions from `HOLD_INITIATING`**:
|
|
917
|
+
|
|
918
|
+
- `HOLD_SUCCESS` -> `HELD`
|
|
919
|
+
- Guard: none
|
|
920
|
+
- Actions: `updateTaskData`, `setHoldState`, `emitTaskHold`
|
|
921
|
+
- `HOLD_FAILED` -> `CONNECTED`
|
|
922
|
+
- Guard: none
|
|
923
|
+
- Actions: `updateTaskData`
|
|
924
|
+
- `TASK_WRAPUP` -> `WRAPPING_UP`
|
|
925
|
+
- Guard: none
|
|
926
|
+
- Actions: `updateTaskData`, `markEnded` (`WRAPPING_UP` entry emits `task:wrapup`)
|
|
927
|
+
- `OUTBOUND_FAILED` -> `WRAPPING_UP` or `TERMINATED` (outbound failure group)
|
|
928
|
+
|
|
929
|
+
### HELD
|
|
930
|
+
|
|
931
|
+
**Description**: Main call is on hold. Reached from `IDLE` (`HYDRATE`), `CONNECTED` (`HOLD_SUCCESS`, `CONSULT_END`), `HOLD_INITIATING` (`HOLD_SUCCESS`), `RESUME_INITIATING` (`UNHOLD_FAILED`), `CONSULT_INITIATING` and `CONSULTING` (consult failure, cancel, or end while the primary media is held), and `CONFERENCING` (`HOLD_SUCCESS` after a downgrade).
|
|
932
|
+
|
|
933
|
+
**Valid transitions from `HELD`**:
|
|
934
|
+
|
|
935
|
+
- `UNHOLD_INITIATED` -> `RESUME_INITIATING`
|
|
936
|
+
- Guard: none
|
|
937
|
+
- Actions: none
|
|
938
|
+
- `UNHOLD_SUCCESS` -> `CONNECTED` (remote resume from another login session)
|
|
939
|
+
- Guard: none
|
|
940
|
+
- Actions: `updateTaskData`, `setHoldState`, `emitTaskResume`
|
|
941
|
+
- `CONSULT` -> `CONSULT_INITIATING`
|
|
942
|
+
- Guard: none
|
|
943
|
+
- Actions: `setConsultInitiator`, `setConsultDestination`
|
|
944
|
+
- `CONSULTING_ACTIVE` -> `CONSULTING`
|
|
945
|
+
- Guard: none
|
|
946
|
+
- Actions: `setConsultInitiator`, `setConsultDestination`, `setConsultAgentJoined`, `updateTaskData`, `emitTaskConsultAccepted`, `emitTaskConsulting`
|
|
947
|
+
- `CONFERENCE_START` -> `CONFERENCING` (conference merged while this agent is held after refresh or recovery)
|
|
948
|
+
- Guard: none
|
|
949
|
+
- Actions: `updateTaskData`, `syncTaskDataFromEvent`, `clearConsultState`, `emitTaskConferenceStarted`
|
|
950
|
+
- `PAUSE_RECORDING` / `RESUME_RECORDING` -> Stay `HELD`
|
|
951
|
+
- Guard: none
|
|
952
|
+
- Actions: `updateTaskData`, `setRecordingState`, `emitTaskRecordingPaused` / `emitTaskRecordingResumed`
|
|
953
|
+
- `TRANSFER_SUCCESS` -> `WRAPPING_UP`
|
|
954
|
+
- Guard: `guards.shouldWrapUpOrIsInitiator`
|
|
955
|
+
- Actions: `updateTaskData`, `markEnded`, `emitTaskWrapup`
|
|
956
|
+
- `TRANSFER_SUCCESS` -> `CONNECTED` (receiver/default branch)
|
|
957
|
+
- Guard: default
|
|
958
|
+
- Actions: `updateTaskData`, `clearConsultState`
|
|
959
|
+
- `TRANSFER_FAILED` -> stay `HELD`
|
|
960
|
+
- Guard: none
|
|
961
|
+
- Actions: `updateTaskData`
|
|
962
|
+
- `CONTACT_ENDED` -> `TERMINATED` (campaign preview)
|
|
963
|
+
- Guard: `guards.isCampaignPreviewContactEnded`
|
|
964
|
+
- Actions: `updateTaskData`, `markEnded`, `emitTaskEnd`
|
|
965
|
+
- `CONTACT_ENDED` -> `CONFERENCING`
|
|
966
|
+
- Guard: `guards.conferenceInProgressFromEvent`
|
|
967
|
+
- Actions: `updateTaskData`, `emitTaskConferenceStarted`, `requestCleanup`
|
|
968
|
+
- `CONTACT_ENDED` -> `WRAPPING_UP`
|
|
969
|
+
- Guard: `guards.shouldWrapUp`
|
|
970
|
+
- Actions: `updateTaskData`, `markEnded`, `emitTaskWrapup`, `requestCleanup`
|
|
971
|
+
- `CONTACT_ENDED` -> `TERMINATED` (default branch)
|
|
972
|
+
- Guard: default
|
|
973
|
+
- Actions: `updateTaskData`, `markEnded`, `emitTaskEnd`
|
|
974
|
+
- `CONSULT_END` -> `WRAPPING_UP` or `TERMINATED` (current-agent consult end group), otherwise stay `HELD`
|
|
975
|
+
- Guard: default
|
|
976
|
+
- Actions: `updateTaskData`, `clearConsultState`, `emitTaskConsultEnd`
|
|
977
|
+
- `PARTICIPANT_LEAVE` -> `WRAPPING_UP` or `TERMINATED` (current-agent participant leave group), otherwise stay `HELD`
|
|
978
|
+
- Guard: default
|
|
979
|
+
- Actions: `updateTaskData`, `handleParticipantLeft`, `emitTaskParticipantLeft`
|
|
980
|
+
- `TASK_WRAPUP` -> `WRAPPING_UP`
|
|
981
|
+
- Guard: none
|
|
982
|
+
- Actions: `updateTaskData`, `markEnded`; `WRAPPING_UP` entry emits `task:wrapup`
|
|
983
|
+
- `OUTBOUND_FAILED` -> `WRAPPING_UP` or `TERMINATED` (outbound failure group)
|
|
984
|
+
- `EXIT_CONFERENCE_SUCCESS` -> `WRAPPING_UP` or `TERMINATED`
|
|
985
|
+
- Guard: `guards.shouldWrapUp` or default
|
|
986
|
+
- Actions: `updateTaskData`, `markEnded`, `clearConsultState`, or `emitTaskEnd`; `WRAPPING_UP` entry emits `task:wrapup` (shared with `CONNECTED` / `CONFERENCING`)
|
|
987
|
+
|
|
988
|
+
### RESUME_INITIATING
|
|
989
|
+
|
|
990
|
+
**Description**: Resume/unhold request has been sent and is awaiting backend confirmation. Reached from `HELD` by `UNHOLD_INITIATED`, and from `CONNECTED` by `UNHOLD_INITIATED`.
|
|
991
|
+
|
|
992
|
+
**Valid transitions from `RESUME_INITIATING`**:
|
|
993
|
+
|
|
994
|
+
- `UNHOLD_SUCCESS` -> `CONNECTED`
|
|
995
|
+
- Guard: none
|
|
996
|
+
- Actions: `updateTaskData`, `setHoldState`, `emitTaskResume`
|
|
997
|
+
- `UNHOLD_FAILED` -> `HELD`
|
|
998
|
+
- Guard: none
|
|
999
|
+
- Actions: none
|
|
1000
|
+
- `PARTICIPANT_LEAVE` -> `WRAPPING_UP` or `TERMINATED` (current-agent participant leave group), otherwise stay `RESUME_INITIATING`
|
|
1001
|
+
- Guard: default
|
|
1002
|
+
- Actions: `updateTaskData`, `handleParticipantLeft`, `emitTaskParticipantLeft`
|
|
1003
|
+
- `TASK_WRAPUP` -> `WRAPPING_UP`
|
|
1004
|
+
- Guard: none
|
|
1005
|
+
- Actions: `updateTaskData`, `markEnded` (`WRAPPING_UP` entry emits `task:wrapup`)
|
|
1006
|
+
- `OUTBOUND_FAILED` -> `WRAPPING_UP` or `TERMINATED` (outbound failure group)
|
|
1007
|
+
|
|
1008
|
+
### CONSULT_INITIATING
|
|
1009
|
+
|
|
1010
|
+
**Description**: Consult request is in-flight. Reached from `CONNECTED`, `HELD`, and `CONFERENCING` by `CONSULT`; from `CONFERENCING` the actions add `setConsultFromConference`.
|
|
1011
|
+
|
|
1012
|
+
**Valid transitions from `CONSULT_INITIATING`**:
|
|
1013
|
+
|
|
1014
|
+
- `CONSULT_SUCCESS` -> `CONSULTING`
|
|
1015
|
+
- Guard: none
|
|
1016
|
+
- Actions: `updateTaskData`, `setConsultInitiator` (`consultDestinationAgentJoined` waits for `CONSULTING_ACTIVE`)
|
|
1017
|
+
- `CONSULTING_ACTIVE` -> `CONSULTING`
|
|
1018
|
+
- Guard: none
|
|
1019
|
+
- Actions: `setConsultInitiator`, `setConsultDestination`, `setConsultAgentJoined`, `updateTaskData`, `emitTaskConsultAccepted`, `emitTaskConsulting`
|
|
1020
|
+
- `CONSULT_FAILED` -> `CONFERENCING`
|
|
1021
|
+
- Guard: inline `context.consultFromConference === true`
|
|
1022
|
+
- Actions: `updateTaskData`, `handleConsultFailed`
|
|
1023
|
+
- `CONSULT_FAILED` -> `HELD`
|
|
1024
|
+
- Guard: `guards.isPrimaryMediaOnHold`
|
|
1025
|
+
- Actions: `updateTaskData`, `handleConsultFailed`
|
|
1026
|
+
- `CONSULT_FAILED` -> `CONNECTED` (default branch)
|
|
1027
|
+
- Guard: default
|
|
1028
|
+
- Actions: `updateTaskData`, `handleConsultFailed`
|
|
1029
|
+
- `CTQ_CANCEL` -> `HELD`
|
|
1030
|
+
- Guard: `guards.isPrimaryMediaOnHold`
|
|
1031
|
+
- Actions: `updateTaskData`, `clearConsultState`
|
|
1032
|
+
- `CTQ_CANCEL` -> `CONNECTED` (default branch)
|
|
1033
|
+
- Guard: default
|
|
1034
|
+
- Actions: `updateTaskData`, `clearConsultState`
|
|
1035
|
+
- `CONSULT_END` -> `WRAPPING_UP` or `TERMINATED` (current-agent consult end group), then `HELD` when `guards.isPrimaryMediaOnHold` passes, otherwise `CONNECTED`
|
|
1036
|
+
- Guard: `guards.isPrimaryMediaOnHold` or default
|
|
1037
|
+
- Actions: `updateTaskData`, `clearConsultState`, `emitTaskConsultEnd`
|
|
1038
|
+
- `HOLD_SUCCESS` -> stay `CONSULT_INITIATING`
|
|
1039
|
+
- Guard: none
|
|
1040
|
+
- Actions: `updateTaskData`
|
|
1041
|
+
- `HOLD_FAILED` -> `CONNECTED`
|
|
1042
|
+
- Guard: none
|
|
1043
|
+
- Actions: `updateTaskData`, `handleConsultFailed`
|
|
1044
|
+
- `PARTICIPANT_LEAVE` -> `WRAPPING_UP` or `TERMINATED` (current-agent participant leave group), otherwise stay `CONSULT_INITIATING`
|
|
1045
|
+
- Guard: default
|
|
1046
|
+
- Actions: `updateTaskData`, `handleParticipantLeft`, `emitTaskParticipantLeft`
|
|
1047
|
+
- `TASK_WRAPUP` -> `WRAPPING_UP`
|
|
1048
|
+
- Guard: none
|
|
1049
|
+
- Actions: `updateTaskData`, `markEnded`
|
|
1050
|
+
- `OUTBOUND_FAILED` -> `WRAPPING_UP` or `TERMINATED` (outbound failure group)
|
|
1051
|
+
|
|
1052
|
+
### CONSULTING
|
|
1053
|
+
|
|
1054
|
+
**Description**: Agent is in active consult leg. Reached from `IDLE` (`HYDRATE`, `CONSULTING_ACTIVE`), `OFFERED` (`ASSIGN` for a consult assignment, `CONSULTING_ACTIVE`), `CONNECTED`, `HELD`, and `CONFERENCING` (`CONSULTING_ACTIVE`), `CONSULT_INITIATING` (`CONSULT_SUCCESS`, `CONSULTING_ACTIVE`), and `CONF_INITIATING` (`CONFERENCE_FAILED`).
|
|
1055
|
+
|
|
1056
|
+
**Valid transitions from `CONSULTING`**:
|
|
1057
|
+
|
|
1058
|
+
- `CONSULTING_ACTIVE` -> stay `CONSULTING`
|
|
1059
|
+
- Guard: none
|
|
1060
|
+
- Actions: `setConsultAgentJoined`, `setConsultDestination`, `updateTaskData`, `emitTaskConsulting`
|
|
1061
|
+
- `CONSULT_FAILED` -> `CONFERENCING`, `HELD`, or `CONNECTED` (RONA or consultee decline while the initiator is already consulting)
|
|
1062
|
+
- Guard: inline `context.consultFromConference === true`, then `guards.isPrimaryMediaOnHold`, then default
|
|
1063
|
+
- Actions: `updateTaskData`, `handleConsultFailed`
|
|
1064
|
+
- `CONSULT_END` -> `WRAPPING_UP` or `TERMINATED` (current-agent consult end group), then in order:
|
|
1065
|
+
- `CONSULT_END` -> `CONFERENCING`
|
|
1066
|
+
- Guard: inline `context.consultInitiator === true && guards.conferenceInProgressFromEvent`
|
|
1067
|
+
- Actions: `updateTaskData`, `clearConsultState`, `emitTaskConsultEnd`
|
|
1068
|
+
- `CONSULT_END` -> `HELD` (conference consult ended after a downgrade while the main leg is held)
|
|
1069
|
+
- Guard: inline `context.consultInitiator === true && context.consultFromConference === true`, no conference in progress, and `guards.isConferenceHoldParticipantFromEvent`
|
|
1070
|
+
- Actions: `updateTaskData`, `clearConsultState`, `emitTaskConsultEnd`
|
|
1071
|
+
- `CONSULT_END` -> `CONNECTED` (conference consult ended after a downgrade while the main leg is connected)
|
|
1072
|
+
- Guard: the same, with `!guards.isConferenceHoldParticipantFromEvent`
|
|
1073
|
+
- Actions: `updateTaskData`, `clearConsultState`, `emitTaskConsultEnd`
|
|
1074
|
+
- `CONSULT_END` -> `CONNECTED` (initiator already switched back to the main leg)
|
|
1075
|
+
- Guard: inline `context.consultInitiator === true && context.consultCallHeld === true`
|
|
1076
|
+
- Actions: `updateTaskData`, `clearConsultState`, `emitTaskConsultEnd`
|
|
1077
|
+
- `CONSULT_END` -> `WRAPPING_UP` (interaction terminated during consult because the customer left)
|
|
1078
|
+
- Guard: inline `callProcessingDetails.hasCustomerLeft === 'true'`, `interaction.isTerminated === true`, and `shouldWrapUpForThisAgent`
|
|
1079
|
+
- Actions: `updateTaskData`, `markEnded`, `clearConsultState`, `emitTaskWrapup`, `requestCleanup`
|
|
1080
|
+
- `CONSULT_END` -> `HELD`
|
|
1081
|
+
- Guard: inline `context.consultInitiator === true`
|
|
1082
|
+
- Actions: `updateTaskData`, `clearConsultState`, `emitTaskConsultEnd`
|
|
1083
|
+
- `CONSULT_END` -> `TERMINATED` (default branch, consulted agent)
|
|
1084
|
+
- Guard: default
|
|
1085
|
+
- Actions: `updateTaskData`, `markEnded`, `clearConsultState`, `emitTaskConsultEnd`, `emitTaskEnd`
|
|
1086
|
+
- `SWITCH_TO_MAIN_CALL` -> stay `CONSULTING`
|
|
1087
|
+
- Guard: none
|
|
1088
|
+
- Actions: `handleSwitchToMainCall`, `emitTaskSwitchCall`
|
|
1089
|
+
- `SWITCH_TO_CONSULT` -> stay `CONSULTING`
|
|
1090
|
+
- Guard: none
|
|
1091
|
+
- Actions: `handleSwitchToConsult`, `emitTaskSwitchCall`
|
|
1092
|
+
- `HOLD_SUCCESS` -> stay `CONSULTING`
|
|
1093
|
+
- Guard: none
|
|
1094
|
+
- Actions: `updateTaskData`, `setHoldState`, `emitTaskHold`
|
|
1095
|
+
- `UNHOLD_SUCCESS` -> stay `CONSULTING`
|
|
1096
|
+
- Guard: none
|
|
1097
|
+
- Actions: `updateTaskData`, `setHoldState`, `emitTaskResume`
|
|
1098
|
+
- `TRANSFER_SUCCESS` -> `WRAPPING_UP`
|
|
1099
|
+
- Guard: `guards.shouldWrapUpOrIsInitiator`
|
|
1100
|
+
- Actions: `updateTaskData`, `markEnded`, `clearConsultState`, `emitTaskWrapup`
|
|
1101
|
+
- `TRANSFER_SUCCESS` -> `CONNECTED` (receiver/default branch)
|
|
1102
|
+
- Guard: default
|
|
1103
|
+
- Actions: `updateTaskData`, `clearConsultState`
|
|
1104
|
+
- `TRANSFER_FAILED` -> stay `CONSULTING`
|
|
1105
|
+
- Guard: none
|
|
1106
|
+
- Actions: `updateTaskData`
|
|
1107
|
+
- `TRANSFER_CONFERENCE` -> stay `CONSULTING`
|
|
1108
|
+
- Guard: none
|
|
1109
|
+
- Actions: `setTransferConferenceRequested`, `emitTaskTransferConference`
|
|
1110
|
+
- `TRANSFER_CONFERENCE_SUCCESS` -> `WRAPPING_UP`
|
|
1111
|
+
- Guard: `guards.shouldWrapUp`
|
|
1112
|
+
- Actions: `updateTaskData`, `markEnded`, `clearConsultState`, `handleTransferConferenceSuccess`, `clearTransferConferenceRequested`; `WRAPPING_UP` entry emits `task:wrapup`
|
|
1113
|
+
- `TRANSFER_CONFERENCE_SUCCESS` -> `CONFERENCING`
|
|
1114
|
+
- Guard: `!guards.isSelfConferenceTransferInitiator`
|
|
1115
|
+
- Actions: `updateTaskData`, `clearConsultState`, `handleTransferConferenceSuccess`, `clearTransferConferenceRequested`
|
|
1116
|
+
- `TRANSFER_CONFERENCE_SUCCESS` -> `TERMINATED` (default branch)
|
|
1117
|
+
- Guard: default
|
|
1118
|
+
- Actions: `updateTaskData`, `markEnded`, `clearConsultState`, `handleTransferConferenceSuccess`, `clearTransferConferenceRequested`, `emitTaskEnd`
|
|
1119
|
+
- `TRANSFER_CONFERENCE_FAILED` -> stay `CONSULTING`
|
|
1120
|
+
- Guard: none
|
|
1121
|
+
- Actions: `clearTransferConferenceRequested`, `emitTaskTransferConferenceFailed`
|
|
1122
|
+
- `PARTICIPANT_LEAVE` -> `WRAPPING_UP`
|
|
1123
|
+
- Guard: `guards.didCurrentAgentLeaveMainInteraction && guards.shouldWrapUp`
|
|
1124
|
+
- Actions: `updateTaskData`, `handleParticipantLeft`, `markEnded`, `clearConsultState`, `emitTaskParticipantLeft` (entry emits `task:wrapup`)
|
|
1125
|
+
- `PARTICIPANT_LEAVE` -> `TERMINATED`
|
|
1126
|
+
- Guard: `guards.didCurrentAgentLeaveMainInteraction`
|
|
1127
|
+
- Actions: `updateTaskData`, `handleParticipantLeft`, `markEnded`, `clearConsultState`, `emitTaskParticipantLeft`, `emitTaskEnd`
|
|
1128
|
+
- `PARTICIPANT_LEAVE` -> `CONNECTED`
|
|
1129
|
+
- Guard: `guards.shouldDowngradeConferenceToConnected` (after current-agent departure guards)
|
|
1130
|
+
- Actions: `updateTaskData`, `handleParticipantLeft`, `clearConsultState`, `emitTaskParticipantLeft`, `emitTaskConferenceEnded`
|
|
1131
|
+
- `PARTICIPANT_LEAVE` -> stay `CONSULTING` (default)
|
|
1132
|
+
- Guard: default
|
|
1133
|
+
- Actions: `updateTaskData`, `handleParticipantLeft`, `emitTaskParticipantLeft`
|
|
1134
|
+
- `ASSIGN` -> `CONNECTED`
|
|
1135
|
+
- Guard: none
|
|
1136
|
+
- Actions: `updateTaskData`, `emitTaskAssigned`
|
|
1137
|
+
- `CONTACT_ENDED` -> `WRAPPING_UP`
|
|
1138
|
+
- Guard: none
|
|
1139
|
+
- Actions: `updateTaskData`, `markEnded`, `clearConsultState`, `emitTaskWrapup`, `requestCleanup`
|
|
1140
|
+
- `TASK_WRAPUP` -> `WRAPPING_UP`
|
|
1141
|
+
- Guard: none
|
|
1142
|
+
- Actions: `updateTaskData`, `markEnded`, `clearConsultState`; `WRAPPING_UP` entry emits `task:wrapup`
|
|
1143
|
+
- `OUTBOUND_FAILED` -> `WRAPPING_UP` or `TERMINATED` (outbound failure group)
|
|
1144
|
+
- `MERGE_TO_CONFERENCE` -> `CONF_INITIATING`
|
|
1145
|
+
- Guard: none
|
|
1146
|
+
- Actions: none
|
|
1147
|
+
- `CONFERENCE_START` -> `CONFERENCING`
|
|
1148
|
+
- Guard: none
|
|
1149
|
+
- Actions: `updateTaskData`, `syncTaskDataFromEvent`, `handleConferenceStarted`, `clearConsultState`
|
|
1150
|
+
|
|
1151
|
+
### CONF_INITIATING
|
|
1152
|
+
|
|
1153
|
+
**Description**: Conference merge is being established. Reached from `CONSULTING` by `MERGE_TO_CONFERENCE` (no guard, no actions).
|
|
1154
|
+
|
|
1155
|
+
**Valid transitions from `CONF_INITIATING`**:
|
|
1156
|
+
|
|
1157
|
+
- `CONFERENCE_START` -> `CONFERENCING`
|
|
1158
|
+
- Guard: none
|
|
1159
|
+
- Actions: `updateTaskData`, `syncTaskDataFromEvent`, `handleConferenceStarted`, `clearConsultState`
|
|
1160
|
+
- `CONFERENCE_FAILED` -> `CONSULTING`
|
|
1161
|
+
- Guard: none
|
|
1162
|
+
- Actions: `handleConferenceFailed`, `emitTaskConferenceFailed`
|
|
1163
|
+
- `CONSULT_END` -> `WRAPPING_UP` or `TERMINATED` (current-agent consult end group; call ended before the conference completes)
|
|
1164
|
+
- `CONSULT_END` -> `WRAPPING_UP`
|
|
1165
|
+
- Guard: inline `interaction.isTerminated === true`
|
|
1166
|
+
- Actions: `updateTaskData`, `markEnded`, `clearConsultState`, `emitTaskWrapup`
|
|
1167
|
+
- `CONSULT_END` -> `CONNECTED` (default branch)
|
|
1168
|
+
- Guard: default
|
|
1169
|
+
- Actions: `updateTaskData`, `clearConsultState`
|
|
1170
|
+
- `TASK_WRAPUP` -> `WRAPPING_UP`
|
|
1171
|
+
- Guard: none
|
|
1172
|
+
- Actions: `updateTaskData`, `markEnded`
|
|
1173
|
+
- `OUTBOUND_FAILED` -> `WRAPPING_UP` or `TERMINATED` (outbound failure group)
|
|
1174
|
+
|
|
1175
|
+
### CONFERENCING
|
|
1176
|
+
|
|
1177
|
+
**Description**: Active conference call state. Reached from `IDLE` (`HYDRATE`), `CONNECTED` and `HELD` (`CONFERENCE_START`, or `CONTACT_ENDED` with `guards.conferenceInProgressFromEvent`), `CONSULTING` (`CONFERENCE_START`, `CONSULT_FAILED`, `CONSULT_END`, `TRANSFER_CONFERENCE_SUCCESS` with `!guards.isSelfConferenceTransferInitiator`), `CONSULT_INITIATING` (`CONSULT_FAILED` from a conference), and `CONF_INITIATING` (`CONFERENCE_START`).
|
|
1178
|
+
|
|
1179
|
+
**Valid transitions from `CONFERENCING`**:
|
|
1180
|
+
|
|
1181
|
+
- `CONSULT` -> `CONSULT_INITIATING`
|
|
1182
|
+
- Guard: none
|
|
1183
|
+
- Actions: `setConsultInitiator`, `setConsultDestination`, `setConsultFromConference`
|
|
1184
|
+
- `CONSULTING_ACTIVE` -> `CONSULTING`
|
|
1185
|
+
- Guard: none
|
|
1186
|
+
- Actions: `setConsultInitiator`, `setConsultDestination`, `setConsultFromConference`, `setConsultAgentJoined`, `updateTaskData`, `emitTaskConsultAccepted`, `emitTaskConsulting`
|
|
1187
|
+
- `CONFERENCE_START` -> stay `CONFERENCING`
|
|
1188
|
+
- Guard: none
|
|
1189
|
+
- Actions: `updateTaskData`, `syncTaskDataFromEvent`, `clearConsultState`, `emitTaskConferenceStarted`
|
|
1190
|
+
- `EXIT_CONFERENCE_SUCCESS` -> `WRAPPING_UP` or `TERMINATED`
|
|
1191
|
+
- Guard: `guards.shouldWrapUp` or default
|
|
1192
|
+
- Actions: `updateTaskData`, `markEnded`, `clearConsultState`, or `emitTaskEnd` on terminate; `WRAPPING_UP` entry emits `task:wrapup` (shared helper on `CONNECTED`, `HELD`, and `CONFERENCING` for Voice HTTP exit)
|
|
1193
|
+
- `CONSULT_END` -> `WRAPPING_UP` or `TERMINATED` (current-agent consult end group; every agent in a conference receives this event)
|
|
1194
|
+
- `CONSULT_END` -> `WRAPPING_UP`
|
|
1195
|
+
- Guard: inline `interaction.isTerminated === true` and `shouldWrapUpForThisAgent`
|
|
1196
|
+
- Actions: `updateTaskData`, `markEnded`, `clearConsultState`, `emitTaskWrapup`
|
|
1197
|
+
- `CONSULT_END` -> stay `CONFERENCING`
|
|
1198
|
+
- Guard: none
|
|
1199
|
+
- Actions: `updateTaskData`, `clearConsultState`
|
|
1200
|
+
- `HOLD_SUCCESS` -> `HELD` (conference already downgraded, so the UI renders resume)
|
|
1201
|
+
- Guard: `guards.shouldDowngradeConferenceToConnected`
|
|
1202
|
+
- Actions: `updateTaskData`, `setHoldState`, `emitTaskHold`
|
|
1203
|
+
- `HOLD_SUCCESS` -> stay `CONFERENCING`
|
|
1204
|
+
- Guard: default
|
|
1205
|
+
- Actions: `updateTaskData`, `setHoldState`, `emitTaskHold`
|
|
1206
|
+
- `UNHOLD_SUCCESS` -> `CONNECTED` (conference already downgraded, so hold is available again)
|
|
1207
|
+
- Guard: `guards.shouldDowngradeConferenceToConnected`
|
|
1208
|
+
- Actions: `updateTaskData`, `syncTaskDataFromEvent`, `setHoldState`, `emitTaskResume`
|
|
1209
|
+
- `UNHOLD_SUCCESS` -> stay `CONFERENCING`
|
|
1210
|
+
- Guard: default
|
|
1211
|
+
- Actions: `updateTaskData`, `syncTaskDataFromEvent`, `setHoldState`, `emitTaskResume`
|
|
1212
|
+
- `TRANSFER_CONFERENCE` -> stay `CONFERENCING`
|
|
1213
|
+
- Guard: none
|
|
1214
|
+
- Actions: `setTransferConferenceRequested`, `emitTaskTransferConference`
|
|
1215
|
+
- `TRANSFER_CONFERENCE_SUCCESS` -> stay `CONFERENCING`
|
|
1216
|
+
- Guard: `guards.isPassiveConferenceTransferObserver`
|
|
1217
|
+
- Actions: `updateTaskData`, `handleTransferConferenceSuccess`, `clearTransferConferenceRequested`
|
|
1218
|
+
- `TRANSFER_CONFERENCE_SUCCESS` -> `WRAPPING_UP`
|
|
1219
|
+
- Guard: `guards.shouldWrapUp`
|
|
1220
|
+
- Actions: `updateTaskData`, `markEnded`, `clearConsultState`, `handleTransferConferenceSuccess`, `clearTransferConferenceRequested`; `WRAPPING_UP` entry emits `task:wrapup`
|
|
1221
|
+
- `TRANSFER_CONFERENCE_SUCCESS` -> `CONFERENCING`
|
|
1222
|
+
- Guard: `!guards.isSelfConferenceTransferInitiator`
|
|
1223
|
+
- Actions: `updateTaskData`, `clearConsultState`, `handleTransferConferenceSuccess`, `clearTransferConferenceRequested`
|
|
1224
|
+
- `TRANSFER_CONFERENCE_SUCCESS` -> `TERMINATED` (default branch)
|
|
1225
|
+
- Guard: default
|
|
1226
|
+
- Actions: `updateTaskData`, `markEnded`, `clearConsultState`, `handleTransferConferenceSuccess`, `clearTransferConferenceRequested`, `emitTaskEnd`
|
|
1227
|
+
- `TRANSFER_CONFERENCE_FAILED` -> stay `CONFERENCING`
|
|
1228
|
+
- Guard: none
|
|
1229
|
+
- Actions: `clearTransferConferenceRequested`, `emitTaskTransferConferenceFailed`
|
|
1230
|
+
- `PARTICIPANT_LEAVE` -> `WRAPPING_UP`
|
|
1231
|
+
- Guard: `guards.didCurrentAgentLeaveMainInteraction && guards.shouldWrapUp`
|
|
1232
|
+
- Actions: `updateTaskData`, `handleParticipantLeft`, `markEnded`, `clearConsultState`, `emitTaskParticipantLeft` (entry emits `task:wrapup`)
|
|
1233
|
+
- `PARTICIPANT_LEAVE` -> `TERMINATED`
|
|
1234
|
+
- Guard: `guards.didCurrentAgentLeaveMainInteraction`
|
|
1235
|
+
- Actions: `updateTaskData`, `handleParticipantLeft`, `markEnded`, `clearConsultState`, `emitTaskParticipantLeft`, `emitTaskEnd`
|
|
1236
|
+
- `PARTICIPANT_LEAVE` -> `CONNECTED`
|
|
1237
|
+
- Guard: `guards.shouldDowngradeConferenceToConnected`
|
|
1238
|
+
- Actions: `updateTaskData`, `handleParticipantLeft`, `clearConsultState`, `emitTaskParticipantLeft`, `emitTaskConferenceEnded`
|
|
1239
|
+
- `PARTICIPANT_LEAVE` -> stay `CONFERENCING` (default)
|
|
1240
|
+
- Guard: default
|
|
1241
|
+
- Actions: `updateTaskData`, `handleParticipantLeft`, `emitTaskParticipantLeft`
|
|
1242
|
+
|
|
1243
|
+
Customer hangup and agent-initiated customer Drop share this backend event.
|
|
1244
|
+
When two or more active conference participants survive on the main leg, the
|
|
1245
|
+
customer is removed from the authoritative snapshot while the task remains
|
|
1246
|
+
`CONFERENCING`; no `task:conferenceEnded` event is emitted. When another
|
|
1247
|
+
agent/endpoint leaves, the same rule preserves the remaining conference, and
|
|
1248
|
+
the guarded `CONNECTED` branch is used only after the conference participant
|
|
1249
|
+
count falls below two while the customer remains.
|
|
1250
|
+
|
|
1251
|
+
- `CONFERENCE_END` -> `WRAPPING_UP`
|
|
1252
|
+
- Guard: `guards.shouldWrapUp`
|
|
1253
|
+
- Actions: `updateTaskData`, `markEnded`, `clearConsultState`; `WRAPPING_UP` entry emits `task:wrapup`
|
|
1254
|
+
- `CONFERENCE_END` -> `CONNECTED`
|
|
1255
|
+
- Guard: inline `!context.exitingConference && customerInCall`
|
|
1256
|
+
- Actions: `updateTaskData`, `clearConsultState`, `emitTaskConferenceEnded`
|
|
1257
|
+
- `CONFERENCE_END` -> `TERMINATED` (default branch)
|
|
1258
|
+
- Guard: default
|
|
1259
|
+
- Actions: `updateTaskData`, `markEnded`, `clearConsultState`, `emitTaskEnd`
|
|
1260
|
+
- `CONTACT_ENDED` -> stay `CONFERENCING`
|
|
1261
|
+
- Guard: none
|
|
1262
|
+
- Actions: `updateTaskData`, `requestCleanup`
|
|
1263
|
+
- `CONSULT_FAILED` -> stay `CONFERENCING`
|
|
1264
|
+
- Guard: none
|
|
1265
|
+
- Actions: `updateTaskData`, `handleConsultFailed`
|
|
1266
|
+
- `TASK_WRAPUP` -> `WRAPPING_UP`
|
|
1267
|
+
- Guard: `guards.shouldWrapUp`
|
|
1268
|
+
- Actions: `updateTaskData`, `markEnded`, `clearConsultState`; `WRAPPING_UP` entry emits `task:wrapup`
|
|
1269
|
+
- `OUTBOUND_FAILED` -> `WRAPPING_UP` or `TERMINATED` (outbound failure group)
|
|
1270
|
+
|
|
1271
|
+
### WRAPPING_UP
|
|
1272
|
+
|
|
1273
|
+
**Description**: Post-interaction work (ACW) is in progress.
|
|
1274
|
+
|
|
1275
|
+
**How this state is reached (incoming transitions)**:
|
|
1276
|
+
|
|
1277
|
+
- Reached from `IDLE` (`HYDRATE`) and from every active state via `CONTACT_ENDED`, `TASK_WRAPUP`, `TRANSFER_SUCCESS`, `TRANSFER_CONFERENCE_SUCCESS`, `PARTICIPANT_LEAVE`, `CONSULT_END`, `CONFERENCE_END`, `EXIT_CONFERENCE_SUCCESS`, or `OUTBOUND_FAILED` branches
|
|
1278
|
+
- Entry always emits wrapup event after transition; the Task override publishes `task:wrapup` only when `wrapUpRequired` is true
|
|
1279
|
+
|
|
1280
|
+
**Entry Actions**:
|
|
1281
|
+
|
|
1282
|
+
- `emitTaskWrapup`
|
|
1283
|
+
|
|
1284
|
+
**Valid transitions from `WRAPPING_UP`**:
|
|
1285
|
+
|
|
1286
|
+
- `TASK_WRAPUP` -> stay `WRAPPING_UP`
|
|
1287
|
+
- Guard: if `context.taskData.wrapUpRequired === true` before the event, actions are `updateTaskData` only; otherwise `updateTaskData`, `emitTaskWrapup` (late AgentWrapup after wrap-up was already published)
|
|
1288
|
+
- `WRAPUP_COMPLETE` -> `COMPLETED`
|
|
1289
|
+
- Guard: none
|
|
1290
|
+
- Actions: `updateTaskData`
|
|
1291
|
+
|
|
1292
|
+
### COMPLETED
|
|
1293
|
+
|
|
1294
|
+
**Description**: Final wrapped-up terminal state. Reached from `WRAPPING_UP` by `WRAPUP_COMPLETE` (actions `updateTaskData`).
|
|
1295
|
+
|
|
1296
|
+
**Entry Actions** (order matters — `emitTaskWrappedup` before `cleanupResources` so subscribers receive intact task data):
|
|
1297
|
+
|
|
1298
|
+
- `emitTaskWrappedup`
|
|
1299
|
+
- `cleanupResources`
|
|
1300
|
+
|
|
1301
|
+
**Valid transitions from `COMPLETED`**: None (final state)
|
|
1302
|
+
|
|
1303
|
+
**Guards**: None
|
|
1304
|
+
|
|
1305
|
+
### TERMINATED
|
|
1306
|
+
|
|
1307
|
+
**Description**: Final terminated terminal state.
|
|
1308
|
+
|
|
1309
|
+
**Entry Actions**:
|
|
1310
|
+
|
|
1311
|
+
- `cleanupResources`
|
|
1312
|
+
|
|
1313
|
+
**How this state is reached (incoming transitions)**:
|
|
1314
|
+
|
|
1315
|
+
- Reached from `IDLE` (`OUTBOUND_FAILED`), `OFFERED`, `CONNECTED`, `HOLD_INITIATING`, `HELD`, `RESUME_INITIATING`, `CONSULT_INITIATING`, `CONSULTING`, `CONF_INITIATING`, and `CONFERENCING` via terminating branches (`TASK_WRAPUP` default in `OFFERED`, failure paths, current-agent departure, and default end-of-contact/conference branches)
|
|
1316
|
+
|
|
1317
|
+
**Valid transitions from `TERMINATED`**: None (final state)
|
|
1318
|
+
|
|
1319
|
+
**Guards**: None
|
|
1320
|
+
|
|
1321
|
+
### Events
|
|
1322
|
+
|
|
1323
|
+
Event names below are from `TaskEvent` in `constants.ts`.
|
|
1324
|
+
|
|
1325
|
+
- `TASK_INCOMING`, `TASK_OFFERED`, `HYDRATE`
|
|
1326
|
+
- `CONTACT_UPDATED`, `CONTACT_OWNER_CHANGED`
|
|
1327
|
+
- `ASSIGN`, `CONTACT_ENDED`, `TASK_WRAPUP`, `WRAPUP_COMPLETE`
|
|
1328
|
+
- `HOLD_INITIATED`, `HOLD_SUCCESS`, `HOLD_FAILED`
|
|
1329
|
+
- `UNHOLD_INITIATED`, `UNHOLD_SUCCESS`, `UNHOLD_FAILED`
|
|
1330
|
+
- `OFFER_CONSULT`, `CONSULT`, `CONSULT_SUCCESS`, `CONSULT_CREATED`
|
|
1331
|
+
- `CONSULTING_ACTIVE`, `CONSULT_END`, `CONSULT_FAILED`
|
|
1332
|
+
- `CTQ_CANCEL`, `CTQ_CANCEL_FAILED`
|
|
1333
|
+
- `MERGE_TO_CONFERENCE`, `CONFERENCE_START`, `CONFERENCE_FAILED`, `CONFERENCE_END`
|
|
1334
|
+
- `PARTICIPANT_LEAVE`
|
|
1335
|
+
- `TRANSFER_CONFERENCE`, `TRANSFER_CONFERENCE_SUCCESS`, `TRANSFER_CONFERENCE_FAILED`
|
|
1336
|
+
- `EXIT_CONFERENCE`, `EXIT_CONFERENCE_SUCCESS`, `EXIT_CONFERENCE_FAILED`
|
|
1337
|
+
- `TRANSFER_SUCCESS`, `TRANSFER_FAILED`
|
|
1338
|
+
- `RECORDING_STARTED`, `PAUSE_RECORDING`, `RESUME_RECORDING`
|
|
1339
|
+
- `RONA`, `INVITE_FAILED`, `ASSIGN_FAILED`, `OUTBOUND_FAILED`
|
|
1340
|
+
- `CAMPAIGN_PREVIEW_ACCEPT_FAILED`, `CAMPAIGN_PREVIEW_SKIP_FAILED`, `CAMPAIGN_PREVIEW_REMOVE_FAILED`
|
|
1341
|
+
- `SWITCH_TO_MAIN_CALL`, `SWITCH_TO_CONSULT`
|
|
1342
|
+
- `ACCEPT`, `DECLINE`, `END`
|
|
1343
|
+
|
|
1344
|
+
Declared but not handled by any state or the root: `EXIT_CONFERENCE`, `EXIT_CONFERENCE_FAILED`, `CTQ_CANCEL_FAILED`, `ACCEPT`, `DECLINE`, and `END`. Sending one is a no-op.
|
|
1345
|
+
|
|
1346
|
+
## Pitfalls and constraints
|
|
1347
|
+
|
|
1348
|
+
- Root-level handlers run only when the active state has no handler for that event. Adding a child handler for `HYDRATE`, `CONSULT_FAILED`, or `CONTACT_UPDATED` silently replaces the root behavior for that state (`src/services/task/state-machine/TaskStateMachine.ts`).
|
|
1349
|
+
- A root-level event cannot move the actor into a child state, which is why state-restoring `HYDRATE` lives in `IDLE`; a `HYDRATE` on an active task only refreshes data and emits `task:hydrate`.
|
|
1350
|
+
- Guarded handlers without a default branch drop the event when no guard passes: `CONSULT_END` in `CONNECTED` for a non-initiator, and `TASK_WRAPUP` in `CONFERENCING` when `guards.shouldWrapUp` fails.
|
|
1351
|
+
- `setExitingConference` is not wired, so `context.exitingConference` stays false and the `CONFERENCE_END` -> `CONNECTED` guard depends only on the customer being in the main call.
|
|
1352
|
+
- `AGENT_CONFERENCE_TRANSFER_FAILED` maps to `TRANSFER_FAILED`, not `TRANSFER_CONFERENCE_FAILED`; `CONFERENCING` has no `TRANSFER_FAILED` handler, so the backend failure is ignored there (`src/services/task/TaskManager.ts`).
|
|
1353
|
+
- `TaskState` lists five NOT IMPLEMENTED states; do not route events to them without adding graph nodes and UI-control rules.
|
|
1354
|
+
- `PAUSE_RECORDING` and `RESUME_RECORDING` are handled only in `CONNECTED` and `HELD`; recording changes in other states arrive only through `deriveTaskDataUpdates` on the next payload.
|
|
1355
|
+
|
|
1356
|
+
## Module-specific rules
|
|
1357
|
+
|
|
1358
|
+
- Do: map backend notifications to typed `TaskEvent` values before sending them to the actor.
|
|
1359
|
+
- Do: preserve initiating states separately from success/failure stable states.
|
|
1360
|
+
- Do: keep side effects in Task or Voice overrides of the emitter and integration placeholders, and keep the defaults in `actions.ts` as no-ops.
|
|
1361
|
+
- Do not: export or document the private UI-control helpers (`computeVoiceInteractionUIControls`, `computeDigitalInteractionUIControls`) as public APIs; consumers read `task.uiControls`.
|
|
1362
|
+
|
|
1363
|
+
## Key design trade-off
|
|
1364
|
+
|
|
1365
|
+
| Chosen trade-off | Preserved invariant or benefit | Cost or limitation | Decision evidence |
|
|
1366
|
+
| ---------------- | ------------------------------ | ------------------ | ----------------- |
|
|
1367
|
+
| Backend events are mapped into a typed internal event vocabulary before transition evaluation, isolating the state graph from transport details. | The graph is testable with synthetic events and survives backend renames in one mapper | Every new CC event needs a mapper case and a typed payload entry, and several CC events collapse into one `TaskEvent` | `src/services/task/state-machine/constants.ts`, `src/services/task/TaskManager.ts` |
|
|
1368
|
+
| Emitters and integration hooks are no-op placeholders that Task and Voice override through `createTaskStateMachine(config, {actions})` | The graph stays free of SDK event, logging, and request dependencies | Behavior visible to applications lives in two places: the graph decides when, the overrides decide what | `src/services/task/state-machine/actions.ts`, `src/services/task/Task.ts` |
|
|
1369
|
+
|
|
1370
|
+
## Verification
|
|
1371
|
+
|
|
1372
|
+
Use `test/unit/spec/services/task/state-machine/TaskStateMachine.ts`, `guards.ts`, and `uiControlsComputer.ts` to cover every documented transition/action/guard/control claim. Use `test/unit/spec/services/task/Task.ts` for injected `syncTaskDataFromEvent` behavior. Run `yarn workspace @webex/contact-center test:unit` from the workspace root; run `yarn workspace @webex/contact-center build:src` first because the legacy tests may import built output.
|
|
1373
|
+
|
|
1374
|
+
| Requirement or invariant | Test level | Positive evidence | Negative or boundary evidence | Gap |
|
|
1375
|
+
| ------------------------ | ----------------------------- | ----------------- | ----------------------------- | ---------------------- |
|
|
1376
|
+
| `TASK_STATE_MACHINE-R-001` | Unit | `test/unit/spec/services/task/state-machine/TaskStateMachine.ts` | `test/unit/spec/services/task/state-machine/TaskStateMachine.ts` (ignored PARTICIPANT_LEAVE in CONNECTED and HOLD_INITIATING) | Keep transition coverage synchronized with all mapped TaskEvent groups. |
|
|
1377
|
+
| `TASK_STATE_MACHINE-R-003` | Unit | `test/unit/spec/services/task/Task.ts` | none found | None. |
|
|
1378
|
+
| `TASK_STATE_MACHINE-R-004` | Unit | `test/unit/spec/services/task/state-machine/uiControlsComputer.ts` | `test/unit/spec/services/task/state-machine/uiControlsComputer.ts` (profile NONE, digital) | None. |
|
|
1379
|
+
| `TASK_STATE_MACHINE-R-005`, `TASK_STATE_MACHINE-R-007` | Static (imports) | None (static) | none found | No test; transport, auth, and observability absence is verified only by reading the module's imports. |
|
|
1380
|
+
| `TASK_STATE_MACHINE-R-006` | Unit | `test/unit/spec/services/task/Task.ts` | none found | None. |
|
|
1381
|
+
| `TASK_STATE_MACHINE-R-008` | Unit | `test/unit/spec/services/task/state-machine/TaskStateMachine.ts`, `test/unit/spec/services/task/Task.ts` | `test/unit/spec/services/task/state-machine/guards.ts` (partial payloads, hasLeft) | None. |
|
|
1382
|
+
| `TASK_STATE_MACHINE-R-009` | Unit | `test/unit/spec/services/task/state-machine/TaskStateMachine.ts` | `test/unit/spec/services/task/state-machine/TaskStateMachine.ts` (no-wrap-up branches) | None. |
|
|
1383
|
+
| `TASK_STATE_MACHINE-R-010` | Unit | `test/unit/spec/services/task/state-machine/TaskStateMachine.ts` | none found | Default controls in final states are covered only indirectly. |
|
|
1384
|
+
| `INV-001` | Unit | `test/unit/spec/services/task/state-machine/types.ts` | none found | Payload completeness is enforced by the TypeScript compiler, not tests. |
|
|
1385
|
+
| `INV-002` | Unit | `test/unit/spec/services/task/state-machine/TaskStateMachine.ts` | `test/unit/spec/services/task/state-machine/TaskStateMachine.ts` (passive observer stays in CONFERENCING) | No test pins the array order itself. |
|
|
1386
|
+
|
|
1387
|
+
A module specification is complete only when its public surface, invariants, failure modes, and test
|
|
1388
|
+
evidence agree with the implementation.
|