@webex/contact-center 3.12.0 → 3.13.0-next.10

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.
Files changed (297) hide show
  1. package/.repo-context.json +704 -0
  2. package/.sdd/manifest.json +1613 -0
  3. package/AGENTS.md +969 -0
  4. package/dist/cc.js +1102 -47
  5. package/dist/cc.js.map +1 -1
  6. package/dist/config.js +13 -0
  7. package/dist/config.js.map +1 -1
  8. package/dist/constants.js +46 -3
  9. package/dist/constants.js.map +1 -1
  10. package/dist/index.js +86 -17
  11. package/dist/index.js.map +1 -1
  12. package/dist/metrics/MetricsManager.js +16 -0
  13. package/dist/metrics/MetricsManager.js.map +1 -1
  14. package/dist/metrics/behavioral-events.js +211 -0
  15. package/dist/metrics/behavioral-events.js.map +1 -1
  16. package/dist/metrics/constants.js +58 -4
  17. package/dist/metrics/constants.js.map +1 -1
  18. package/dist/services/AddressBook.js +18 -15
  19. package/dist/services/AddressBook.js.map +1 -1
  20. package/dist/services/AnswerCallOnWebexService.js +202 -0
  21. package/dist/services/AnswerCallOnWebexService.js.map +1 -0
  22. package/dist/services/ApiAiAssistant.js +369 -14
  23. package/dist/services/ApiAiAssistant.js.map +1 -1
  24. package/dist/services/EntryPoint.js +46 -68
  25. package/dist/services/EntryPoint.js.map +1 -1
  26. package/dist/services/Queue.js +27 -22
  27. package/dist/services/Queue.js.map +1 -1
  28. package/dist/services/UserPreference.js +427 -0
  29. package/dist/services/UserPreference.js.map +1 -0
  30. package/dist/services/WebCallingService.js +287 -37
  31. package/dist/services/WebCallingService.js.map +1 -1
  32. package/dist/services/WebexCrossClientService.js +225 -0
  33. package/dist/services/WebexCrossClientService.js.map +1 -0
  34. package/dist/services/WxAppTelephonyMercurySync.js +111 -0
  35. package/dist/services/WxAppTelephonyMercurySync.js.map +1 -0
  36. package/dist/services/config/Util.js +48 -48
  37. package/dist/services/config/Util.js.map +1 -1
  38. package/dist/services/config/constants.js +57 -79
  39. package/dist/services/config/constants.js.map +1 -1
  40. package/dist/services/config/index.js +100 -226
  41. package/dist/services/config/index.js.map +1 -1
  42. package/dist/services/config/types.js +100 -40
  43. package/dist/services/config/types.js.map +1 -1
  44. package/dist/services/constants.js +19 -1
  45. package/dist/services/constants.js.map +1 -1
  46. package/dist/services/core/Err.js.map +1 -1
  47. package/dist/services/core/Utils.js +131 -32
  48. package/dist/services/core/Utils.js.map +1 -1
  49. package/dist/services/core/WebexRequest.js +6 -2
  50. package/dist/services/core/WebexRequest.js.map +1 -1
  51. package/dist/services/core/aqm-reqs.js +17 -11
  52. package/dist/services/core/aqm-reqs.js.map +1 -1
  53. package/dist/services/core/constants.js +9 -1
  54. package/dist/services/core/constants.js.map +1 -1
  55. package/dist/services/core/types.js.map +1 -1
  56. package/dist/services/core/websocket/WebSocketManager.js +26 -6
  57. package/dist/services/core/websocket/WebSocketManager.js.map +1 -1
  58. package/dist/services/core/websocket/connection-service.js +3 -1
  59. package/dist/services/core/websocket/connection-service.js.map +1 -1
  60. package/dist/services/core/websocket/types.js.map +1 -1
  61. package/dist/services/index.js +6 -0
  62. package/dist/services/index.js.map +1 -1
  63. package/dist/services/task/Task.js +955 -0
  64. package/dist/services/task/Task.js.map +1 -0
  65. package/dist/services/task/TaskFactory.js +50 -0
  66. package/dist/services/task/TaskFactory.js.map +1 -0
  67. package/dist/services/task/TaskManager.js +1275 -504
  68. package/dist/services/task/TaskManager.js.map +1 -1
  69. package/dist/services/task/TaskUtils.js +221 -27
  70. package/dist/services/task/TaskUtils.js.map +1 -1
  71. package/dist/services/task/WebexCallingUtils.js +70 -0
  72. package/dist/services/task/WebexCallingUtils.js.map +1 -0
  73. package/dist/services/task/constants.js +22 -2
  74. package/dist/services/task/constants.js.map +1 -1
  75. package/dist/services/task/contact.js +29 -0
  76. package/dist/services/task/contact.js.map +1 -1
  77. package/dist/services/task/dialer.js +78 -0
  78. package/dist/services/task/dialer.js.map +1 -1
  79. package/dist/services/task/digital/Digital.js +78 -0
  80. package/dist/services/task/digital/Digital.js.map +1 -0
  81. package/dist/services/task/state-machine/TaskStateMachine.js +982 -0
  82. package/dist/services/task/state-machine/TaskStateMachine.js.map +1 -0
  83. package/dist/services/task/state-machine/actions.js +572 -0
  84. package/dist/services/task/state-machine/actions.js.map +1 -0
  85. package/dist/services/task/state-machine/constants.js +161 -0
  86. package/dist/services/task/state-machine/constants.js.map +1 -0
  87. package/dist/services/task/state-machine/guards.js +379 -0
  88. package/dist/services/task/state-machine/guards.js.map +1 -0
  89. package/dist/services/task/state-machine/index.js +53 -0
  90. package/dist/services/task/state-machine/index.js.map +1 -0
  91. package/dist/services/task/state-machine/types.js +54 -0
  92. package/dist/services/task/state-machine/types.js.map +1 -0
  93. package/dist/services/task/state-machine/uiControlsComputer.js +703 -0
  94. package/dist/services/task/state-machine/uiControlsComputer.js.map +1 -0
  95. package/dist/services/task/taskDataNormalizer.js +99 -0
  96. package/dist/services/task/taskDataNormalizer.js.map +1 -0
  97. package/dist/services/task/types.js +259 -5
  98. package/dist/services/task/types.js.map +1 -1
  99. package/dist/services/task/voice/Voice.js +1504 -0
  100. package/dist/services/task/voice/Voice.js.map +1 -0
  101. package/dist/services/task/voice/WebRTC.js +152 -0
  102. package/dist/services/task/voice/WebRTC.js.map +1 -0
  103. package/dist/services/task/voice/wxAppOfferObservability.js +145 -0
  104. package/dist/services/task/voice/wxAppOfferObservability.js.map +1 -0
  105. package/dist/services/task/voice/wxAppVoiceMethods.js +395 -0
  106. package/dist/services/task/voice/wxAppVoiceMethods.js.map +1 -0
  107. package/dist/services/wxAppDiagnosticLogging.js +159 -0
  108. package/dist/services/wxAppDiagnosticLogging.js.map +1 -0
  109. package/dist/services/wxAppTelephonyUtils.js +19 -0
  110. package/dist/services/wxAppTelephonyUtils.js.map +1 -0
  111. package/dist/types/cc.d.ts +222 -10
  112. package/dist/types/config.d.ts +13 -0
  113. package/dist/types/constants.d.ts +40 -1
  114. package/dist/types/index.d.ts +58 -22
  115. package/dist/types/metrics/MetricsManager.d.ts +6 -0
  116. package/dist/types/metrics/constants.d.ts +52 -1
  117. package/dist/types/services/AddressBook.d.ts +2 -1
  118. package/dist/types/services/AnswerCallOnWebexService.d.ts +38 -0
  119. package/dist/types/services/ApiAiAssistant.d.ts +67 -5
  120. package/dist/types/services/EntryPoint.d.ts +7 -5
  121. package/dist/types/services/Queue.d.ts +5 -3
  122. package/dist/types/services/UserPreference.d.ts +118 -0
  123. package/dist/types/services/WebexCrossClientService.d.ts +32 -0
  124. package/dist/types/services/WxAppTelephonyMercurySync.d.ts +28 -0
  125. package/dist/types/services/config/Util.d.ts +4 -8
  126. package/dist/types/services/config/constants.d.ts +49 -76
  127. package/dist/types/services/config/index.d.ts +16 -64
  128. package/dist/types/services/config/types.d.ts +252 -114
  129. package/dist/types/services/constants.d.ts +16 -0
  130. package/dist/types/services/core/Err.d.ts +6 -0
  131. package/dist/types/services/core/Utils.d.ts +43 -13
  132. package/dist/types/services/core/WebexRequest.d.ts +1 -0
  133. package/dist/types/services/core/constants.d.ts +7 -0
  134. package/dist/types/services/core/types.d.ts +2 -0
  135. package/dist/types/services/core/websocket/WebSocketManager.d.ts +2 -0
  136. package/dist/types/services/core/websocket/types.d.ts +1 -1
  137. package/dist/types/services/index.d.ts +2 -0
  138. package/dist/types/services/task/Task.d.ts +186 -0
  139. package/dist/types/services/task/TaskFactory.d.ts +14 -0
  140. package/dist/types/services/task/TaskUtils.d.ts +54 -2
  141. package/dist/types/services/task/WebexCallingUtils.d.ts +11 -0
  142. package/dist/types/services/task/constants.d.ts +20 -0
  143. package/dist/types/services/task/contact.d.ts +4 -0
  144. package/dist/types/services/task/dialer.d.ts +30 -0
  145. package/dist/types/services/task/digital/Digital.d.ts +23 -0
  146. package/dist/types/services/task/state-machine/TaskStateMachine.d.ts +1442 -0
  147. package/dist/types/services/task/state-machine/actions.d.ts +10 -0
  148. package/dist/types/services/task/state-machine/constants.d.ts +107 -0
  149. package/dist/types/services/task/state-machine/guards.d.ts +103 -0
  150. package/dist/types/services/task/state-machine/index.d.ts +13 -0
  151. package/dist/types/services/task/state-machine/types.d.ts +277 -0
  152. package/dist/types/services/task/state-machine/uiControlsComputer.d.ts +9 -0
  153. package/dist/types/services/task/taskDataNormalizer.d.ts +10 -0
  154. package/dist/types/services/task/types.d.ts +790 -66
  155. package/dist/types/services/task/voice/Voice.d.ts +241 -0
  156. package/dist/types/services/task/voice/WebRTC.d.ts +54 -0
  157. package/dist/types/services/task/voice/wxAppOfferObservability.d.ts +39 -0
  158. package/dist/types/services/task/voice/wxAppVoiceMethods.d.ts +68 -0
  159. package/dist/types/services/wxAppDiagnosticLogging.d.ts +63 -0
  160. package/dist/types/services/wxAppTelephonyUtils.d.ts +5 -0
  161. package/dist/types/types.d.ts +258 -11
  162. package/dist/types/utils/PageCache.d.ts +20 -3
  163. package/dist/types/webex.d.ts +1 -0
  164. package/dist/types.js +204 -6
  165. package/dist/types.js.map +1 -1
  166. package/dist/utils/PageCache.js +19 -5
  167. package/dist/utils/PageCache.js.map +1 -1
  168. package/dist/webex.js +22 -2
  169. package/dist/webex.js.map +1 -1
  170. package/docs/adr/0001-spec-source-policy.md +97 -0
  171. package/docs/adr/0002-consult-transfer-list-policy.md +345 -0
  172. package/docs/adr/0003-repo-standards-migration.md +104 -0
  173. package/docs/adr/index.md +35 -0
  174. package/docs/architecture.md +460 -0
  175. package/docs/getting-started.md +142 -0
  176. package/docs/index.md +53 -0
  177. package/docs/specs/README.md +98 -0
  178. package/package.json +17 -12
  179. package/schemas/repo-context.schema.json +796 -0
  180. package/src/cc.ts +1439 -105
  181. package/src/config.ts +13 -0
  182. package/src/constants.ts +53 -1
  183. package/src/docs/README.md +727 -0
  184. package/src/index.ts +72 -16
  185. package/src/metrics/MetricsManager.ts +16 -0
  186. package/src/metrics/behavioral-events.ts +218 -0
  187. package/src/metrics/constants.ts +63 -4
  188. package/src/metrics/docs/README.md +710 -0
  189. package/src/services/AddressBook.ts +17 -6
  190. package/src/services/AnswerCallOnWebexService.ts +239 -0
  191. package/src/services/ApiAiAssistant.ts +494 -15
  192. package/src/services/EntryPoint.ts +59 -60
  193. package/src/services/Queue.ts +29 -12
  194. package/src/services/UserPreference.ts +509 -0
  195. package/src/services/WebCallingService.ts +362 -40
  196. package/src/services/WebexCrossClientService.ts +298 -0
  197. package/src/services/WxAppTelephonyMercurySync.ts +142 -0
  198. package/src/services/agent/docs/README.md +673 -0
  199. package/src/services/config/Util.ts +54 -84
  200. package/src/services/config/constants.ts +64 -86
  201. package/src/services/config/docs/README.md +530 -0
  202. package/src/services/config/index.ts +116 -277
  203. package/src/services/config/types.ts +238 -125
  204. package/src/services/constants.ts +18 -0
  205. package/src/services/core/Err.ts +3 -0
  206. package/src/services/core/Utils.ts +151 -37
  207. package/src/services/core/WebexRequest.ts +3 -1
  208. package/src/services/core/aqm-reqs.ts +18 -12
  209. package/src/services/core/constants.ts +8 -0
  210. package/src/services/core/docs/README.md +993 -0
  211. package/src/services/core/types.ts +33 -1
  212. package/src/services/core/websocket/WebSocketManager.ts +37 -8
  213. package/src/services/core/websocket/connection-service.ts +5 -1
  214. package/src/services/core/websocket/types.ts +1 -1
  215. package/src/services/docs/README.md +765 -0
  216. package/src/services/index.ts +4 -0
  217. package/src/services/task/Task.ts +1211 -0
  218. package/src/services/task/TaskFactory.ts +82 -0
  219. package/src/services/task/TaskManager.ts +1551 -584
  220. package/src/services/task/TaskUtils.ts +316 -25
  221. package/src/services/task/WebexCallingUtils.ts +136 -0
  222. package/src/services/task/constants.ts +21 -0
  223. package/src/services/task/contact.ts +30 -0
  224. package/src/services/task/dialer.ts +80 -0
  225. package/src/services/task/digital/Digital.ts +102 -0
  226. package/src/services/task/docs/README.md +1569 -0
  227. package/src/services/task/state-machine/TaskStateMachine.ts +1320 -0
  228. package/src/services/task/state-machine/actions.ts +741 -0
  229. package/src/services/task/state-machine/constants.ts +172 -0
  230. package/src/services/task/state-machine/docs/README.md +1388 -0
  231. package/src/services/task/state-machine/guards.ts +442 -0
  232. package/src/services/task/state-machine/index.ts +28 -0
  233. package/src/services/task/state-machine/types.ts +258 -0
  234. package/src/services/task/state-machine/uiControlsComputer.ts +1135 -0
  235. package/src/services/task/taskDataNormalizer.ts +137 -0
  236. package/src/services/task/types.ts +974 -70
  237. package/src/services/task/voice/Voice.ts +1878 -0
  238. package/src/services/task/voice/WebRTC.ts +194 -0
  239. package/src/services/task/voice/wxAppOfferObservability.ts +204 -0
  240. package/src/services/task/voice/wxAppVoiceMethods.ts +575 -0
  241. package/src/services/wxAppDiagnosticLogging.ts +286 -0
  242. package/src/services/wxAppTelephonyUtils.ts +14 -0
  243. package/src/types.ts +323 -13
  244. package/src/utils/AGENTS.md +291 -0
  245. package/src/utils/PageCache.ts +38 -5
  246. package/src/utils/docs/README.md +413 -0
  247. package/src/webex.js +10 -0
  248. package/test/unit/fixtures/aiSummaryTestUtils.ts +40 -0
  249. package/test/unit/spec/cc.ts +4046 -181
  250. package/test/unit/spec/index.ts +891 -0
  251. package/test/unit/spec/logger-proxy.ts +70 -0
  252. package/test/unit/spec/metrics/MetricsManager.ts +25 -0
  253. package/test/unit/spec/metrics/behavioral-events.ts +60 -0
  254. package/test/unit/spec/services/AddressBook.ts +37 -6
  255. package/test/unit/spec/services/AnswerCallOnWebexService.ts +264 -0
  256. package/test/unit/spec/services/ApiAiAssistant.ts +442 -23
  257. package/test/unit/spec/services/EntryPoint.ts +87 -40
  258. package/test/unit/spec/services/Queue.ts +123 -12
  259. package/test/unit/spec/services/UserPreference.ts +401 -0
  260. package/test/unit/spec/services/WebCallingService.ts +484 -49
  261. package/test/unit/spec/services/WebexCrossClientService.ts +509 -0
  262. package/test/unit/spec/services/WxAppTelephonyMercurySync.ts +136 -0
  263. package/test/unit/spec/services/config/Util.ts +501 -0
  264. package/test/unit/spec/services/config/index.ts +318 -548
  265. package/test/unit/spec/services/core/Utils.ts +447 -8
  266. package/test/unit/spec/services/core/WebexRequest.ts +8 -7
  267. package/test/unit/spec/services/core/aqm-reqs.ts +142 -1
  268. package/test/unit/spec/services/core/websocket/WebSocketManager.ts +132 -56
  269. package/test/unit/spec/services/core/websocket/connection-service.ts +3 -1
  270. package/test/unit/spec/services/task/AutoWrapup.ts +63 -0
  271. package/test/unit/spec/services/task/Task.ts +2723 -0
  272. package/test/unit/spec/services/task/TaskFactory.ts +116 -0
  273. package/test/unit/spec/services/task/TaskManager.ts +4800 -1586
  274. package/test/unit/spec/services/task/TaskUtils.ts +307 -0
  275. package/test/unit/spec/services/task/WebexCallingUtils.ts +153 -0
  276. package/test/unit/spec/services/task/contact.ts +33 -0
  277. package/test/unit/spec/services/task/dialer.ts +190 -0
  278. package/test/unit/spec/services/task/digital/Digital.ts +105 -0
  279. package/test/unit/spec/services/task/state-machine/TaskStateMachine.ts +4060 -0
  280. package/test/unit/spec/services/task/state-machine/guards.ts +839 -0
  281. package/test/unit/spec/services/task/state-machine/types.ts +18 -0
  282. package/test/unit/spec/services/task/state-machine/uiControlsComputer.ts +3101 -0
  283. package/test/unit/spec/services/task/taskTestUtils.ts +87 -0
  284. package/test/unit/spec/services/task/voice/Voice.ts +2355 -0
  285. package/test/unit/spec/services/task/voice/WebRTC.ts +235 -0
  286. package/test/unit/spec/services/task/voice/wxAppOfferObservability.ts +361 -0
  287. package/test/unit/spec/services/task/voice/wxAppVoiceMethods.ts +719 -0
  288. package/test/unit/spec/services/wxAppDiagnosticLogging.ts +179 -0
  289. package/test/unit/spec/wellnessSampleUtils.ts +288 -0
  290. package/typedoc.md +1 -1
  291. package/umd/contact-center.min.js +2 -2
  292. package/umd/contact-center.min.js.map +1 -1
  293. package/dist/services/task/index.js +0 -1525
  294. package/dist/services/task/index.js.map +0 -1
  295. package/dist/types/services/task/index.d.ts +0 -650
  296. package/src/services/task/index.ts +0 -1801
  297. package/test/unit/spec/services/task/index.ts +0 -2184
@@ -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.