@webex/contact-center 3.12.0-webex-services-ready.4 → 3.13.0

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 (250) hide show
  1. package/.sdd/manifest.json +24 -13
  2. package/ai-docs/ARCHITECTURE.md +1 -1
  3. package/ai-docs/CONTRACTS.md +19 -3
  4. package/ai-docs/SECURITY.md +1 -1
  5. package/ai-docs/SERVICE_STATE.md +4 -0
  6. package/ai-docs/contact-center-spec.md +50 -6
  7. package/ai-docs/features/consult-transfer-list-policy/spec/feature-spec.md +362 -0
  8. package/ai-docs/features/contact-owner-change-refactor.md +78 -0
  9. package/dist/cc.js +757 -22
  10. package/dist/cc.js.map +1 -1
  11. package/dist/config.js +7 -0
  12. package/dist/config.js.map +1 -1
  13. package/dist/constants.js +23 -2
  14. package/dist/constants.js.map +1 -1
  15. package/dist/index.js +34 -12
  16. package/dist/index.js.map +1 -1
  17. package/dist/metrics/MetricsManager.js +16 -0
  18. package/dist/metrics/MetricsManager.js.map +1 -1
  19. package/dist/metrics/behavioral-events.js +110 -0
  20. package/dist/metrics/behavioral-events.js.map +1 -1
  21. package/dist/metrics/constants.js +33 -0
  22. package/dist/metrics/constants.js.map +1 -1
  23. package/dist/services/AddressBook.js +18 -15
  24. package/dist/services/AddressBook.js.map +1 -1
  25. package/dist/services/AnswerCallOnWebexService.js +202 -0
  26. package/dist/services/AnswerCallOnWebexService.js.map +1 -0
  27. package/dist/services/ApiAiAssistant.js +221 -11
  28. package/dist/services/ApiAiAssistant.js.map +1 -1
  29. package/dist/services/EntryPoint.js +46 -68
  30. package/dist/services/EntryPoint.js.map +1 -1
  31. package/dist/services/Queue.js +27 -22
  32. package/dist/services/Queue.js.map +1 -1
  33. package/dist/services/WebCallingService.js +10 -2
  34. package/dist/services/WebCallingService.js.map +1 -1
  35. package/dist/services/WebexCrossClientService.js +225 -0
  36. package/dist/services/WebexCrossClientService.js.map +1 -0
  37. package/dist/services/WxAppTelephonyMercurySync.js +111 -0
  38. package/dist/services/WxAppTelephonyMercurySync.js.map +1 -0
  39. package/dist/services/config/Util.js +46 -46
  40. package/dist/services/config/Util.js.map +1 -1
  41. package/dist/services/config/constants.js +34 -77
  42. package/dist/services/config/constants.js.map +1 -1
  43. package/dist/services/config/index.js +100 -226
  44. package/dist/services/config/index.js.map +1 -1
  45. package/dist/services/config/types.js +51 -18
  46. package/dist/services/config/types.js.map +1 -1
  47. package/dist/services/constants.js +11 -1
  48. package/dist/services/constants.js.map +1 -1
  49. package/dist/services/core/Err.js.map +1 -1
  50. package/dist/services/core/Utils.js +25 -1
  51. package/dist/services/core/Utils.js.map +1 -1
  52. package/dist/services/core/WebexRequest.js +6 -2
  53. package/dist/services/core/WebexRequest.js.map +1 -1
  54. package/dist/services/core/aqm-reqs.js +17 -11
  55. package/dist/services/core/aqm-reqs.js.map +1 -1
  56. package/dist/services/core/constants.js +9 -1
  57. package/dist/services/core/constants.js.map +1 -1
  58. package/dist/services/core/types.js.map +1 -1
  59. package/dist/services/core/websocket/WebSocketManager.js +17 -1
  60. package/dist/services/core/websocket/WebSocketManager.js.map +1 -1
  61. package/dist/services/task/Task.js +275 -8
  62. package/dist/services/task/Task.js.map +1 -1
  63. package/dist/services/task/TaskFactory.js +11 -6
  64. package/dist/services/task/TaskFactory.js.map +1 -1
  65. package/dist/services/task/TaskManager.js +590 -42
  66. package/dist/services/task/TaskManager.js.map +1 -1
  67. package/dist/services/task/TaskUtils.js +11 -1
  68. package/dist/services/task/TaskUtils.js.map +1 -1
  69. package/dist/services/task/WebexCallingUtils.js +70 -0
  70. package/dist/services/task/WebexCallingUtils.js.map +1 -0
  71. package/dist/services/task/constants.js +14 -2
  72. package/dist/services/task/constants.js.map +1 -1
  73. package/dist/services/task/contact.js +29 -0
  74. package/dist/services/task/contact.js.map +1 -1
  75. package/dist/services/task/digital/Digital.js +4 -3
  76. package/dist/services/task/digital/Digital.js.map +1 -1
  77. package/dist/services/task/state-machine/TaskStateMachine.js +162 -53
  78. package/dist/services/task/state-machine/TaskStateMachine.js.map +1 -1
  79. package/dist/services/task/state-machine/actions.js +6 -1
  80. package/dist/services/task/state-machine/actions.js.map +1 -1
  81. package/dist/services/task/state-machine/guards.js +7 -10
  82. package/dist/services/task/state-machine/guards.js.map +1 -1
  83. package/dist/services/task/state-machine/types.js.map +1 -1
  84. package/dist/services/task/state-machine/uiControlsComputer.js +118 -18
  85. package/dist/services/task/state-machine/uiControlsComputer.js.map +1 -1
  86. package/dist/services/task/types.js +47 -1
  87. package/dist/services/task/types.js.map +1 -1
  88. package/dist/services/task/voice/Voice.js +477 -17
  89. package/dist/services/task/voice/Voice.js.map +1 -1
  90. package/dist/services/task/voice/WebRTC.js +6 -3
  91. package/dist/services/task/voice/WebRTC.js.map +1 -1
  92. package/dist/services/task/voice/wxAppOfferObservability.js +145 -0
  93. package/dist/services/task/voice/wxAppOfferObservability.js.map +1 -0
  94. package/dist/services/task/voice/wxAppVoiceMethods.js +395 -0
  95. package/dist/services/task/voice/wxAppVoiceMethods.js.map +1 -0
  96. package/dist/services/wxAppDiagnosticLogging.js +159 -0
  97. package/dist/services/wxAppDiagnosticLogging.js.map +1 -0
  98. package/dist/services/wxAppTelephonyUtils.js +19 -0
  99. package/dist/services/wxAppTelephonyUtils.js.map +1 -0
  100. package/dist/types/cc.d.ts +102 -8
  101. package/dist/types/config.d.ts +7 -0
  102. package/dist/types/constants.d.ts +21 -0
  103. package/dist/types/index.d.ts +34 -15
  104. package/dist/types/metrics/MetricsManager.d.ts +6 -0
  105. package/dist/types/metrics/constants.d.ts +31 -0
  106. package/dist/types/services/AddressBook.d.ts +2 -1
  107. package/dist/types/services/AnswerCallOnWebexService.d.ts +38 -0
  108. package/dist/types/services/ApiAiAssistant.d.ts +48 -4
  109. package/dist/types/services/EntryPoint.d.ts +7 -5
  110. package/dist/types/services/Queue.d.ts +5 -3
  111. package/dist/types/services/WebexCrossClientService.d.ts +32 -0
  112. package/dist/types/services/WxAppTelephonyMercurySync.d.ts +28 -0
  113. package/dist/types/services/config/Util.d.ts +4 -8
  114. package/dist/types/services/config/constants.d.ts +28 -76
  115. package/dist/types/services/config/index.d.ts +16 -64
  116. package/dist/types/services/config/types.d.ts +146 -173
  117. package/dist/types/services/constants.d.ts +9 -0
  118. package/dist/types/services/core/Err.d.ts +2 -0
  119. package/dist/types/services/core/Utils.d.ts +10 -0
  120. package/dist/types/services/core/WebexRequest.d.ts +1 -0
  121. package/dist/types/services/core/constants.d.ts +7 -0
  122. package/dist/types/services/core/types.d.ts +2 -0
  123. package/dist/types/services/task/Task.d.ts +34 -5
  124. package/dist/types/services/task/TaskFactory.d.ts +4 -2
  125. package/dist/types/services/task/TaskUtils.d.ts +6 -0
  126. package/dist/types/services/task/WebexCallingUtils.d.ts +11 -0
  127. package/dist/types/services/task/constants.d.ts +12 -0
  128. package/dist/types/services/task/contact.d.ts +4 -0
  129. package/dist/types/services/task/digital/Digital.d.ts +4 -3
  130. package/dist/types/services/task/state-machine/TaskStateMachine.d.ts +304 -56
  131. package/dist/types/services/task/state-machine/guards.d.ts +6 -5
  132. package/dist/types/services/task/state-machine/types.d.ts +9 -1
  133. package/dist/types/services/task/types.d.ts +192 -5
  134. package/dist/types/services/task/voice/Voice.d.ts +68 -11
  135. package/dist/types/services/task/voice/WebRTC.d.ts +5 -4
  136. package/dist/types/services/task/voice/wxAppOfferObservability.d.ts +39 -0
  137. package/dist/types/services/task/voice/wxAppVoiceMethods.d.ts +68 -0
  138. package/dist/types/services/wxAppDiagnosticLogging.d.ts +63 -0
  139. package/dist/types/services/wxAppTelephonyUtils.d.ts +5 -0
  140. package/dist/types/types.d.ts +80 -13
  141. package/dist/types/utils/PageCache.d.ts +20 -3
  142. package/dist/types.js +54 -8
  143. package/dist/types.js.map +1 -1
  144. package/dist/utils/PageCache.js +19 -5
  145. package/dist/utils/PageCache.js.map +1 -1
  146. package/dist/webex.js +9 -1
  147. package/dist/webex.js.map +1 -1
  148. package/package.json +10 -9
  149. package/src/cc.ts +969 -38
  150. package/src/config.ts +7 -0
  151. package/src/constants.ts +24 -0
  152. package/src/index.ts +39 -10
  153. package/src/metrics/MetricsManager.ts +16 -0
  154. package/src/metrics/ai-docs/metrics-spec.md +138 -21
  155. package/src/metrics/behavioral-events.ts +112 -0
  156. package/src/metrics/constants.ts +36 -0
  157. package/src/services/AddressBook.ts +17 -6
  158. package/src/services/AnswerCallOnWebexService.ts +239 -0
  159. package/src/services/ApiAiAssistant.ts +297 -13
  160. package/src/services/EntryPoint.ts +59 -60
  161. package/src/services/Queue.ts +29 -12
  162. package/src/services/WebCallingService.ts +16 -2
  163. package/src/services/WebexCrossClientService.ts +298 -0
  164. package/src/services/WxAppTelephonyMercurySync.ts +142 -0
  165. package/src/services/agent/ai-docs/AGENTS.md +1 -1
  166. package/src/services/agent/ai-docs/agent-spec.md +1 -0
  167. package/src/services/ai-docs/AGENTS.md +10 -10
  168. package/src/services/ai-docs/services-spec.md +25 -5
  169. package/src/services/config/Util.ts +52 -82
  170. package/src/services/config/ai-docs/AGENTS.md +35 -40
  171. package/src/services/config/ai-docs/ARCHITECTURE.md +90 -103
  172. package/src/services/config/ai-docs/config-spec.md +132 -132
  173. package/src/services/config/constants.ts +39 -85
  174. package/src/services/config/index.ts +116 -277
  175. package/src/services/config/types.ts +140 -195
  176. package/src/services/constants.ts +10 -0
  177. package/src/services/core/Err.ts +1 -0
  178. package/src/services/core/Utils.ts +28 -0
  179. package/src/services/core/WebexRequest.ts +3 -1
  180. package/src/services/core/ai-docs/core-spec.md +25 -11
  181. package/src/services/core/aqm-reqs.ts +18 -12
  182. package/src/services/core/constants.ts +8 -0
  183. package/src/services/core/types.ts +33 -1
  184. package/src/services/core/websocket/WebSocketManager.ts +26 -2
  185. package/src/services/task/Task.ts +386 -12
  186. package/src/services/task/TaskFactory.ts +33 -6
  187. package/src/services/task/TaskManager.ts +857 -41
  188. package/src/services/task/TaskUtils.ts +13 -0
  189. package/src/services/task/WebexCallingUtils.ts +136 -0
  190. package/src/services/task/ai-docs/ARCHITECTURE.md +1 -0
  191. package/src/services/task/ai-docs/task-spec.md +190 -8
  192. package/src/services/task/constants.ts +13 -0
  193. package/src/services/task/contact.ts +30 -0
  194. package/src/services/task/digital/Digital.ts +11 -4
  195. package/src/services/task/state-machine/TaskStateMachine.ts +235 -81
  196. package/src/services/task/state-machine/actions.ts +5 -2
  197. package/src/services/task/state-machine/ai-docs/AGENTS.md +6 -4
  198. package/src/services/task/state-machine/ai-docs/ARCHITECTURE.md +35 -16
  199. package/src/services/task/state-machine/ai-docs/task-state-machine-spec.md +103 -33
  200. package/src/services/task/state-machine/guards.ts +7 -10
  201. package/src/services/task/state-machine/types.ts +16 -1
  202. package/src/services/task/state-machine/uiControlsComputer.ts +206 -32
  203. package/src/services/task/types.ts +269 -4
  204. package/src/services/task/voice/Voice.ts +625 -17
  205. package/src/services/task/voice/WebRTC.ts +11 -4
  206. package/src/services/task/voice/wxAppOfferObservability.ts +204 -0
  207. package/src/services/task/voice/wxAppVoiceMethods.ts +575 -0
  208. package/src/services/wxAppDiagnosticLogging.ts +286 -0
  209. package/src/services/wxAppTelephonyUtils.ts +14 -0
  210. package/src/types.ts +108 -13
  211. package/src/utils/AGENTS.md +21 -10
  212. package/src/utils/PageCache.ts +38 -5
  213. package/src/utils/ai-docs/utils-spec.md +21 -11
  214. package/src/webex.js +8 -0
  215. package/test/unit/fixtures/aiSummaryTestUtils.ts +40 -0
  216. package/test/unit/spec/cc.ts +3408 -152
  217. package/test/unit/spec/index.ts +885 -0
  218. package/test/unit/spec/metrics/MetricsManager.ts +25 -0
  219. package/test/unit/spec/metrics/behavioral-events.ts +60 -0
  220. package/test/unit/spec/services/AddressBook.ts +37 -6
  221. package/test/unit/spec/services/AnswerCallOnWebexService.ts +264 -0
  222. package/test/unit/spec/services/ApiAiAssistant.ts +269 -8
  223. package/test/unit/spec/services/EntryPoint.ts +87 -40
  224. package/test/unit/spec/services/Queue.ts +123 -12
  225. package/test/unit/spec/services/WebCallingService.ts +38 -0
  226. package/test/unit/spec/services/WebexCrossClientService.ts +509 -0
  227. package/test/unit/spec/services/WxAppTelephonyMercurySync.ts +136 -0
  228. package/test/unit/spec/services/config/Util.ts +501 -0
  229. package/test/unit/spec/services/config/index.ts +313 -543
  230. package/test/unit/spec/services/core/Utils.ts +22 -0
  231. package/test/unit/spec/services/core/WebexRequest.ts +8 -7
  232. package/test/unit/spec/services/core/aqm-reqs.ts +142 -1
  233. package/test/unit/spec/services/core/websocket/WebSocketManager.ts +64 -14
  234. package/test/unit/spec/services/task/Task.ts +2257 -11
  235. package/test/unit/spec/services/task/TaskFactory.ts +56 -2
  236. package/test/unit/spec/services/task/TaskManager.ts +5559 -1493
  237. package/test/unit/spec/services/task/TaskUtils.ts +72 -0
  238. package/test/unit/spec/services/task/WebexCallingUtils.ts +153 -0
  239. package/test/unit/spec/services/task/contact.ts +33 -0
  240. package/test/unit/spec/services/task/state-machine/TaskStateMachine.ts +1501 -92
  241. package/test/unit/spec/services/task/state-machine/guards.ts +210 -8
  242. package/test/unit/spec/services/task/state-machine/uiControlsComputer.ts +445 -7
  243. package/test/unit/spec/services/task/voice/Voice.ts +1710 -4
  244. package/test/unit/spec/services/task/voice/wxAppOfferObservability.ts +361 -0
  245. package/test/unit/spec/services/task/voice/wxAppVoiceMethods.ts +719 -0
  246. package/test/unit/spec/services/wxAppDiagnosticLogging.ts +179 -0
  247. package/test/unit/spec/wellnessSampleUtils.ts +288 -0
  248. package/typedoc.md +1 -1
  249. package/umd/contact-center.min.js +2 -2
  250. package/umd/contact-center.min.js.map +1 -1
@@ -11,18 +11,24 @@
11
11
  },
12
12
  "topology": "Orchestrator-plus-components",
13
13
  "commands": {
14
+ "compile": {
15
+ "command": "yarn workspace @webex/contact-center compile",
16
+ "source_file": "packages/@webex/contact-center/package.json",
17
+ "verified_at": "2026-08-05T10:53:14Z"
18
+ },
14
19
  "build": {
15
20
  "command": "yarn workspace @webex/contact-center build:src",
16
21
  "source_file": "package.json"
17
22
  },
23
+ "unit-test": {
24
+ "command": "yarn workspace @webex/contact-center test:unit",
25
+ "source_file": "packages/@webex/contact-center/package.json",
26
+ "verified_at": "2026-08-05T10:53:14Z"
27
+ },
18
28
  "test": {
19
29
  "command": "yarn workspace @webex/contact-center test",
20
30
  "source_file": "package.json"
21
31
  },
22
- "test:unit": {
23
- "command": "yarn workspace @webex/contact-center test:unit",
24
- "source_file": "package.json"
25
- },
26
32
  "lint": {
27
33
  "command": "yarn workspace @webex/contact-center test:style",
28
34
  "source_file": "package.json"
@@ -45,7 +51,9 @@
45
51
  "canonical_spec": "ai-docs/contact-center-spec.md",
46
52
  "contracts": {
47
53
  "provides": [
48
- "Published @webex/contact-center package; ContactCenter WebexPlugin; public SDK methods, events, types, Task, AddressBook, ApiAIAssistant, UserPreference, cc.userPreference, exported user-preference request/response types, and preview-campaign methods acceptPreviewContact/skipPreviewContact/removePreviewContact"
54
+ "Published @webex/contact-center package; ContactCenter WebexPlugin; public SDK methods, events, types, Task with ordered action-specific consult/transfer destination controls, AddressBook, ApiAIAssistant, UserPreference, cc.userPreference, existing getQueues/getEntryPoints methods with consult/transfer defaults, full Queue records, mapped EntryPoint records with optional numbers, exported user-preference request/response types, preview-campaign methods acceptPreviewContact/skipPreviewContact/removePreviewContact, and Agent Wellness Break effective-profile, registered-session Profile projection, exported action constants/types, internally sourced action context, system-code, and primary/RTD notification event APIs",
55
+ "WXCC-6026 wxApp Better Together: enableWxBetterTogether init config, isWxBetterTogetherEnabled read API, unified task telephony (task.accept/decline/toggleMute/transmitDtmf), TASK_WXAPP_MUTE_STATE_UPDATED event, optional main.keypad uiControl, multi-login supported; runtime toggle deferred to Phase 2 (private)",
56
+ "BROWSER stationLogin payload: dialNumber and deviceId are webrtc-{agentId} (contact-center.station-login-browser-dn / AGENT-R-006); public stationLogin({loginOption: 'BROWSER'}) input unchanged"
49
57
  ],
50
58
  "requires": [
51
59
  "Webex SDK host/plugin runtime; Contact Center REST and WebSocket services; internal Webex calling, metrics, support, authorization, logger, and mercury packages"
@@ -88,7 +96,8 @@
88
96
  "canonical_spec": "src/metrics/ai-docs/metrics-spec.md",
89
97
  "contracts": {
90
98
  "provides": [
91
- "MetricsManager timing, behavioral/operational/business event submission, taxonomy, queues, and tracking-field helpers"
99
+ "MetricsManager timing, behavioral/operational/business event submission, taxonomy, queues, tracking-field helpers, and operational Agent Wellness Break action/notification/system-code event names",
100
+ "WXAPP_OFFER_PARTICIPANT_FIELDS_MISSING operational/behavioral telemetry event (contract metrics.wxapp-offer-participant-fields-missing; emit site voice/wxAppOfferObservability.ts)"
92
101
  ],
93
102
  "requires": [
94
103
  "Webex internal metrics service; Webex ready lifecycle; LoggerProxy; browser document visibility"
@@ -131,7 +140,7 @@
131
140
  "canonical_spec": "src/services/ai-docs/services-spec.md",
132
141
  "contracts": {
133
142
  "provides": [
134
- "Services composition root; agent/config/contact/dialer factories; AddressBook, EntryPoint, Queue, UserPreference, ApiAiAssistant, and WebCalling integration; cc.userPreference exposes user-preference CRUD"
143
+ "Services composition root; agent/config/contact/dialer factories; AddressBook, EntryPoint, Queue, UserPreference, ApiAiAssistant, and WebCalling integration; existing Queue/EntryPoint list methods with SDK-owned defaults and compatible existing-parameter overrides; Queue returns full records and EntryPoint maps profile-scoped dial-number rows to typed records with optional numbers; cc.userPreference exposes user-preference CRUD; ApiAiAssistant exposes session-validated direct wellness actions through a read-only context provider supplied at construction"
135
144
  ],
136
145
  "requires": [
137
146
  "Core HTTP/WebSocket/AQM infrastructure; WCC APIs; @webex/calling; MetricsManager; PageCache"
@@ -173,7 +182,7 @@
173
182
  "canonical_spec": "src/services/agent/ai-docs/agent-spec.md",
174
183
  "contracts": {
175
184
  "provides": [
176
- "Agent request factory; station login/logout, state changes, buddy-agent and relogin operations; AGENT_EVENTS and agent types"
185
+ "Agent request factory; station login/logout, state changes, buddy-agent and relogin operations; AGENT_EVENTS and agent types; BROWSER station login sends dialNumber and deviceId as webrtc-{agentId} (contact-center.station-login-browser-dn / AGENT-R-006)"
177
186
  ],
178
187
  "requires": [
179
188
  "AqmReqs; WCC API gateway; correlated WebSocket notifications; ContactCenter registration/profile state"
@@ -216,10 +225,10 @@
216
225
  "canonical_spec": "src/services/config/ai-docs/config-spec.md",
217
226
  "contracts": {
218
227
  "provides": [
219
- "Agent profile aggregation; config endpoint methods; CC event/type contracts; outdial ANI access"
228
+ "Agent profile aggregation including fail-closed Agent Wellness Break enablement; config endpoint methods including exact, registration-owned system wellness idle-code lookup; CC event/type contracts; outdial ANI access"
220
229
  ],
221
230
  "requires": [
222
- "WebexRequest; WCC organization, team, profile, aux-code, dial-plan, site, tenant, and URL-mapping APIs"
231
+ "WebexRequest; WCC organization and user desktop-login aggregate APIs; WCC team, aux-code, dial-plan, and site APIs"
223
232
  ]
224
233
  },
225
234
  "section_profile": {
@@ -298,11 +307,13 @@
298
307
  {
299
308
  "path": "src/services/task",
300
309
  "coverage_status": "Partial",
301
- "coverage_evidence": "Canonical spec is structurally complete with 15/15 required documentation fields and source/test evidence mapped by requirement. Independent PR #5088 remediation validation completed on claude-code (2026-07-15); coverage remains Partial until post-baseline promotion criteria are satisfied.",
310
+ "coverage_evidence": "Canonical spec is structurally complete with 15/15 required documentation fields and source/test evidence mapped by requirement. Independent PR #5088 remediation validation completed on claude-code (2026-07-15); AI summary method, delivery, enablement, and cleanup updates are pending independent review (2026-10-06); coverage remains Partial until post-baseline promotion criteria are satisfied.",
302
311
  "canonical_spec": "src/services/task/ai-docs/task-spec.md",
303
312
  "contracts": {
304
313
  "provides": [
305
- "Task/Voice/WebRTC/Digital lifecycle APIs; TaskManager; task events/types; call-control and dialer operations including acceptPreviewContact, skipPreviewContact, and removePreviewContact"
314
+ "Task/Voice/WebRTC/Digital lifecycle APIs; TaskManager lifecycle correlation, narrowly scoped backend-authoritative ContactOwnerChanged recovery, and task-event publication, including routing owner-changing ContactUpdated through the existing task:hydrate event; TaskManager/Voice stamp wrapUpRequired on wrap-up ingress so task:wrapup and profile-gated auto wrap-up can start; task events/types; ordered action-specific consult/transfer destination controls; call-control and dialer operations including acceptPreviewContact, skipPreviewContact, and removePreviewContact",
315
+ "task.ai-summary: receiving-agent summary events delivered directly to taskCollection[conversationId]; latest payload for an unavailable task retained without expiry until its collection key is registered or session cleanup; creation/merge replay follows public task publication; cleanup cancels requests and clears task flags and pending maps; ContactCenter deregistration removes the RTD listener",
316
+ "contact-center.task-ai-summary: four dedicated request/response methods; request methods directly check current agent configuration generated-summary flags on the shared ApiAIAssistant.aiFeature field; responses use the current task interaction ID and main interaction ID with an interaction ID fallback for conversation ID; per-task enablement survives data updates, consults, re-keying, and wrapup, then clears on task removal or session cleanup"
306
317
  ],
307
318
  "requires": [
308
319
  "Contact/dialer AqmReqs; WebSocket managers; @webex/calling; MetricsManager; XState task-state module"
@@ -345,7 +356,7 @@
345
356
  "canonical_spec": "src/services/task/state-machine/ai-docs/task-state-machine-spec.md",
346
357
  "contracts": {
347
358
  "provides": [
348
- "Task state-machine factory; TaskState/TaskEvent contracts; guards/actions; state-derived UI-control computation"
359
+ "Task state-machine factory; TaskState/TaskEvent contracts; guards/actions; state/profile/interaction-derived UI-control and ordered consult/transfer destination computation"
349
360
  ],
350
361
  "requires": [
351
362
  "XState; TaskData/task event contracts; Task and TaskManager integration"
@@ -97,7 +97,7 @@ flowchart TD
97
97
  | Agent/Profile | Remote WCC services; Config aggregates a local view | ContactCenter, Agent, Task |
98
98
  | Task/Interaction | Remote WCC services; Task owns client representation | ContactCenter consumers |
99
99
  | Metric event | Metrics module until submission; remote metrics backend after submit | Observability systems |
100
- | Cached page | Utils PageCache (ephemeral only) | AddressBook, EntryPoint, Queue |
100
+ | Cached page | Utils PageCache (ephemeral only) | AddressBook, Queue |
101
101
 
102
102
  ## Caching Catalog
103
103
 
@@ -6,22 +6,38 @@
6
6
  | Contract ID | Owner module/package | Symbol | Signature / shape | Stability / deprecation | Schema / detail link | Defined at |
7
7
  |---|---|---|---|---|---|---|
8
8
  | `contact-center.plugin` | Contact Center | `ContactCenter` / default plugin | WebexPlugin implementing `IContactCenter` | semver public | `ai-docs/contact-center-spec.md` | `src/index.ts` |
9
- | `contact-center.routing-agent` | Agent/Core | `routingAgent` | `(routing: AqmReqs) => {stationLogin, logout, stateChange, buddyAgents, reload}` | semver public export; returned methods follow backend contracts | `src/services/agent/ai-docs/agent-spec.md` | `src/index.ts`, `src/services/agent/index.ts` |
9
+ | `contact-center.routing-agent` | Agent/Core | `routingAgent` | `(routing: AqmReqs) => {stationLogin, logout, stateChange, buddyAgents, reload}`; BROWSER login payload follows `contact-center.station-login-browser-dn` | semver public export; returned methods follow backend contracts | `src/services/agent/ai-docs/agent-spec.md` | `src/index.ts`, `src/services/agent/index.ts` |
10
+ | `contact-center.station-login-browser-dn` | Contact Center / Agent | `cc.stationLogin` BROWSER payload on `POST /v1/agents/login` | BROWSER sends `dialNumber` and `deviceId` as `webrtc-{agentId}`; EXTENSION and AGENT_DN continue to send the caller-supplied dial number for both fields | backend contract alignment; public `stationLogin({loginOption: 'BROWSER'})` input unchanged | `src/services/agent/ai-docs/agent-spec.md` AGENT-R-006 | `src/cc.ts` |
10
11
  | `contact-center.task` | Task | `Task`, `ITask`, task payload/control types | task instance and compatibility interface | semver public | `src/services/task/ai-docs/task-spec.md` | `src/index.ts` |
12
+ | `contact-center.task-ai-summary` | Task | `requestPostCallSummary`, `sendPostCallSummaryResponse`, `requestMidCallSummary`, `sendMidCallSummaryResponse` | Dedicated request and response methods; mid-call methods take `AISummaryAction`; requests directly check current agent configuration flags on the shared `ApiAIAssistant.aiFeature` field and per-task enablement. Responses use the current task's interaction ID and main interaction ID, with the interaction ID as the conversation ID fallback. Task flags survive data updates and wrapup, then clear on task removal or session cleanup. | public signatures unchanged by cleanup | `src/services/task/ai-docs/task-spec.md` AI summary APIs | `src/services/task/Task.ts`, `src/services/task/types.ts`, `src/services/ApiAiAssistant.ts`, `src/services/task/TaskManager.ts` |
11
13
  | `contact-center.events` | Agent/Task/Config | `AGENT_EVENTS`, `TASK_EVENTS`, `CC_AGENT_EVENTS`, `CC_TASK_EVENTS`, `CC_EVENTS` | typed string event contracts | additive; removals or semantic changes are breaking | owning module specs | `src/index.ts` |
12
14
  | `contact-center.data` | Services/Utils | `AddressBook`, `ApiAIAssistant`, SDK data response/search types | SDK data and AI-assistant access | semver public | Services/Utils specs | `src/index.ts` |
15
+ | `contact-center.consult-transfer-lists` | Contact Center/Services | Existing `getQueues`, `getEntryPoints`, `ContactServiceQueueSearchParams`, `EntryPointSearchParams`, `ContactServiceQueuesResponse`, `EntryPointListResponse`, `ContactServiceQueue`, and `EntryPointRecord` with optional mapped `number` | Queue telephony eligibility/profile views/`name,ASC` and entry-point desktop-profile dial-number mapping/`entryPointName,ASC` are defaults on the existing methods; compatible search/filter/sort parameters remain available and backend row order is preserved | behavioral default correction on existing public methods; no specialized methods or projected response wrappers; `EntryPointRecord.number` is additive and raw configuration-only fields are optional | `ai-docs/features/consult-transfer-list-policy/spec/feature-spec.md` | `src/cc.ts`, `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/types.ts` |
13
16
  | `contact-center.user-preference` | Services/Config | `UserPreference`, `cc.userPreference`, `UserPreferenceData`, request/response types | `getUserPreference(params?)`, `createUserPreference(data)`, `updateUserPreference(userId, data)`, `deleteUserPreference(userId)` | semver public | `src/services/ai-docs/services-spec.md` | `src/index.ts`, `src/cc.ts`, `src/services/UserPreference.ts`, `src/services/config/types.ts` |
14
17
  | `contact-center.preview-campaign` | Contact Center/Task | `acceptPreviewContact`, `skipPreviewContact`, `removePreviewContact` | `(payload: PreviewContactPayload) => Promise<TaskResponse>` | semver public | `ai-docs/contact-center-spec.md`, `src/services/task/ai-docs/task-spec.md` | `src/cc.ts`, `src/services/task/dialer.ts`, `src/services/task/types.ts` |
15
- | `contact-center.state-controls` | Task state machine | `getDefaultUIControls`, task state/control types | function is exported directly from `uiControlsComputer.ts` by package root | semver public | `src/services/task/state-machine/ai-docs/task-state-machine-spec.md` | `src/index.ts`, `src/services/task/state-machine/uiControlsComputer.ts` |
18
+ | `contact-center.state-controls` | Task state machine | `getDefaultUIControls`, `TaskUIControls` with ordered `consultTransferDestinations` arrays | Task controls include per-leg action state plus ordered `consult`/`transfer` destination categories derived from profile and interaction policy | additive semver public field; destination arrays are SDK-owned and first item is the consumer default | `src/services/task/state-machine/ai-docs/task-state-machine-spec.md` | `src/index.ts`, `src/services/task/types.ts`, `src/services/task/state-machine/uiControlsComputer.ts` |
19
+ | `contact-center.conference-participant-drop` | Task | `DropConferenceParticipantPayload`, `ITask.dropConferenceParticipant` | `(payload: {participantId: string}) => Promise<TaskResponse>`; Voice resolves from correlated `ParticipantLeftConference`, while non-voice base Task rejects as unsupported. Existing participant/consult lifecycle events may resolve one unique child-keyed task by `mainInteractionId`; no new public event is introduced. | semver public | `src/services/task/ai-docs/task-spec.md`, `src/services/task/state-machine/ai-docs/task-state-machine-spec.md` | `src/index.ts`, `src/services/task/types.ts`, `src/services/task/voice/Voice.ts`, `src/services/task/contact.ts`, `src/services/task/TaskManager.ts` |
20
+ | `contact-center.wxapp-answer` | Contact Center / Task | `enableWxBetterTogether`, `isWxBetterTogetherEnabled()`, `getWxAppMuted`, `syncWxAppMuteFromCallDetails`, unified task telephony (`ITask.accept`, `decline`, `toggleMute({ muted?, lineOwnerId? })`, `transmitDtmf({ dtmf, lineOwnerId? })`) | init flag ON → usersub `true` + Mercury on supported station login **and silent relogin**; init flag OFF → force usersub `false` on supported station login **and silent relogin** (clears stale suppression after refresh); **Phase 1 init-only** — change flag via re-init; multi-login supported; mute backfill via GET call details + `getWxAppMuted()` on hydrate/refresh; shared-line `lineOwnerId` defaults from participant; SDK `Voice` routes wxApp telephony when flag active | semver public | `src/services/task/ai-docs/task-spec.md`, `ai-docs/contact-center-spec.md`, `src/services/ai-docs/services-spec.md` | `src/cc.ts`, `src/services/task/voice/Voice.ts`, `src/services/task/voice/wxAppVoiceMethods.ts` |
21
+ | `contact-center.desktop-login-aggregate` | Services / Config | `getOrgDesktopLoginConfig`, `getUserDesktopLoginConfig`, `OrgDesktopLoginResponse`, `UserDesktopLoginResponse`, `AgentProfile`, `OrgUrlMappings`, `MicrosoftConfig`, `WebexConfig`; retyped `Profile.teams`; changed `getListOfTeams` / `getAllTeams`; removed `DesktopProfileResponse`, `URLMapping`, `AIFeatureFlagsResponse`, `Profile.environment` | `getAgentConfig` builds `Profile` from 6 calls (5 when `agentProfile.dialPlanEnabled` is false) instead of 11: `organization/{orgId}/desktop-login` and `organization/{orgId}/v2/user/by-ci-user-id/{ciUserId}/desktop-login` replace the org-info, org-setting, tenant-configuration, org-url-mapping, ai-feature, user-by-ci-user-id and agent-profile calls. `getListOfTeams(orgId, page, pageSize, userId)` filters on `userId=={user.dbId}` (unquoted) rather than a team-id list. `multimediaProfileId` resolves team → site. Auxiliary codes return the full organization pool with no per-agent restriction, while `Profile.idleCodesAccess` / `wrapupCodesAccess` still report `ALL` / `SPECIFIC`. Dial plans are filtered on `active`. Microsoft/Webex presence config is read from org level. | **not additive — breaking.** Removal: `DesktopProfileResponse` (renamed to `AgentProfile`), `URLMapping`, `AIFeatureFlagsResponse`, `Profile.environment`, and seven service methods. Payload reinterpretation: `Profile.callVariablesSuppressed` `string` → `boolean`. Semantic break: `getListOfTeams` filter meaning; unrestricted auxiliary-code pool; `webexConfig.stateSynchronizationWebex` may flip `false` → `true`. Type correction: `Profile.teams` `Team[]` → `TeamList[]`, matching what the team API has always returned. Ships as a **major version** — the release commit carries a `BREAKING CHANGE:` body and consumer notes live in `ai-docs/features/desktop-login-aggregate-migration/migration-notes.md`. | `ai-docs/features/desktop-login-aggregate-migration/migration-notes.md`, `src/services/config/ai-docs/config-spec.md` | `src/index.ts`, `src/services/config/index.ts`, `src/services/config/types.ts`, `src/services/config/constants.ts`, `src/services/config/Util.ts` |
22
+ | `contact-center.agent-wellness-break` | Contact Center / Services / Config | `Profile.isWellnessBreakEnabled`, optional `Profile.agentSessionId` after logged-in registration, `requestWellnessBreak`, `respondToWellnessBreak`, `getWellbeingBreakIdleCode`, `WELLNESS_BREAK_NOTIFICATION_ACTIONS`, `WELLNESS_BREAK_USER_ACTIONS`, `WellnessBreakEvent` | Effective gate = backend-delivered `agentWellbeing.enable` + reminders `ENABLED` + `aiAssistantQuantity > 0`; registration projects the SDK-owned active station session after silent relogin so hosts can validate refresh recovery. Action calls accept no identity or context-mutating fields, read the current organization/agent/session from a read-only provider supplied to ApiAIAssistant at construction, and POST a direct `WellnessBreakAction` custom event; current-session logout, multi-login close, relogin, and deregistration entry update or invalidate the provider's source state; system idle code lookup is exact, registration-generation cached, and rejects stale results; valid wellness notifications from either primary or RTD sockets emit the same public event. | additive semver public; no client-side Split dependency or invented rollout field—the delivered AI feature configuration is the server rollout boundary | `ai-docs/contact-center-spec.md`, `src/services/ai-docs/services-spec.md`, `src/services/config/ai-docs/config-spec.md` | `src/index.ts`, `src/types.ts`, `src/cc.ts`, `src/services/config/types.ts`, `src/services/ApiAiAssistant.ts` |
16
23
 
17
24
  ### Events
18
25
 
19
26
  | Contract ID | Owner module | Event / topic | Direction | Payload schema link | Delivery guarantees | Compatibility / deprecation | Defined at |
20
27
  |---|---|---|---|---|---|---|---|
21
28
  | `agent.events` | Agent | `agent:*` | publish to application | agent spec/types | realtime; backend ordering/correlation | additive constants | `src/services/agent/types.ts` |
22
- | `task.events` | Task | `task:*` | publish to application/task | task spec/types | event-driven; state guarded | additive constants | `src/services/task/types.ts` |
29
+ | `task.events` | Task | `task:*`, including existing `task:hydrate` and `task:wrapup` | consume/map backend task lifecycle events, then publish to application/task | task spec `TASK-R-010` / `TASK-R-011` / types | `ContactOwnerChanged` and owner-changing `ContactUpdated` route through `CONTACT_OWNER_CHANGED`; a complete promoted-current-Agent owner change may narrowly recover a missing task; consumers receive one `task:hydrate` and no synthetic `task:incoming`. TaskManager stamps `wrapUpRequired` once at ingress (`AGENT_WRAPUP`, conference-end/leave/transfer when this agent should wrap; HTTP `exitConference` on Voice uses the same empty-pending self-exit fallback as leave — true unless this agent is a consulted non-owner — and pending-list precedence uses the correlated response only) so consumers may receive `task:wrapup` and `task.autoWrapup` on those events. `PARTICIPANT_LEAVE` into `WRAPPING_UP` does not transition-emit; the `WRAPPING_UP` entry still emits `task:wrapup`. A nonempty `agentsPendingWrapUp` wins over transfer initiator signals (`consultingAgentId` / `transferConferenceRequested`); a named other `participantId` is never self-leave; leave wrap-up is not stamped when the actor ignores `PARTICIPANT_LEAVE` (`CONNECTED`, `HOLD_INITIATING`, `CONF_INITIATING`); leave-self with empty/absent pending stamps true unless this agent is a consulted non-owner; remaining conference agents stay unstamped. Profile-gated auto wrap-up still requires `autoWrapup !== false`, interval, and a default reason | compatible semantic extension of existing events; no new event constant; backend `interaction.owner` remains authoritative | `src/services/task/TaskManager.ts`, `src/services/task/Task.ts`, `src/services/task/voice/Voice.ts`, `src/services/task/types.ts` |
30
+ | `task.wxapp-mute.events` | Task | `task:wxapp-mute-state-updated` | publish to application/task | task spec/types | event-driven | additive | `src/services/task/types.ts`, `src/services/task/voice/Voice.ts` |
23
31
  | `cc.events` | Config/Core | backend CC_EVENTS | consume/map | config/core specs | remote WebSocket delivery; AQM correlation where configured | backend contract | `src/services/config/types.ts` |
24
32
  | `rtd.events` | Task | realtime transcription/suggestion | consume then publish per task | task spec | websocket best-effort according to remote service | additive payloads | `src/services/task/TaskManager.ts` |
33
+ | `task.ai-summary` | Task | `task:midCallSummaryReceived` | consume RTD summaries, then publish on `taskCollection[conversationId]` | task spec AI summary APIs / types | RTD conversation ID is the task collection key; latest payload for an unavailable task is retained in memory without expiry until registration or session cleanup; creation/merge replay follows public task publication; cleanup cancels requests and clears task flags and pending maps, while ContactCenter deregistration removes the RTD listener | existing event and payload; direct task lookup and no cache expiry timer | `src/services/task/TaskManager.ts`, `src/services/task/types.ts`, `src/cc.ts` |
34
+ | `wellness.notification.events` | Contact Center | `CC_AGENT_EVENTS.WELLNESS_BREAK` | consume validated wellness payloads from the primary data-notification socket, then publish normalized application events | Contact Center spec/types | exact current agent/org; notification session is diagnostic and is not compared with the active session; canonical optional `actionText` is normalized to public `actionText`; malformed/stale payloads are ignored | additive | `src/cc.ts`, `src/types.ts`, `src/services/config/types.ts` |
35
+
36
+ ### Telemetry / Metrics Events
37
+
38
+ | Contract ID | Owner module | Event constant | Wire name | Payload schema link | Tags | Defined at |
39
+ |---|---|---|---|---|---|---|
40
+ | `metrics.wxapp-offer-participant-fields-missing` | Task / Metrics | `WXAPP_OFFER_PARTICIPANT_FIELDS_MISSING` | `WxApp Offer Participant Fields Missing` | `src/metrics/ai-docs/metrics-spec.md` | operational, behavioral | `src/metrics/constants.ts`, `src/services/task/voice/wxAppOfferObservability.ts` |
25
41
 
26
42
  ## Requires — what this repo depends on
27
43
 
@@ -45,7 +45,7 @@
45
45
  |---|---|---|---|
46
46
  | Log upload | Runtime context could contain sensitive values | Shared error helpers upload only approved diagnostic context; never add credentials/payload dumps | Contact Center maintainers |
47
47
  | WebSocket event parsing | Malformed/unexpected remote data | Parse defensively, map known event constants, ignore/reject invalid transitions | Core/Task maintainers |
48
- | Public dial/contact inputs | PII and external numbers | Validate and avoid logging raw values | Contact Center maintainers |
48
+ | Public dial/contact/participant-drop inputs | PII, external numbers, and participant identifiers | Validate and avoid logging raw values; sensitive AQM operations redact dynamic URLs and raw routing failures | Contact Center maintainers |
49
49
 
50
50
  ## Reporting & Review
51
51
 
@@ -10,6 +10,7 @@
10
10
  | `task:*` | publish | Task/TaskManager → application | `src/services/task/types.ts` |
11
11
  | `CC_EVENTS` | consume | WCC WebSocket → Core/ContactCenter/Task/AqmReqs | `src/services/config/types.ts` |
12
12
  | realtime transcript/suggestion | consume/publish | RTD WebSocket → owning Task | `src/services/task/TaskManager.ts` |
13
+ | `Wellness_Break_Handler` | consume/publish | Primary data-notification WebSocket → ContactCenter → `CC_AGENT_EVENTS.WELLNESS_BREAK` | `src/cc.ts`, `src/types.ts` |
13
14
 
14
15
  ## Data Stores
15
16
 
@@ -42,6 +43,9 @@
42
43
  | `allowAutomatedRelogin` | silent relogin after recovery | config-defined | ContactCenter | replacement recovery contract exists |
43
44
  | `webRtcEnabled` / login option | browser calling path | remote profile | Config/WCC | remote contract removed |
44
45
  | task UI/config flags | task controls and operations | profile/config-defined | Task/Config | owning behavior removed |
46
+ | `Profile.isWellnessBreakEnabled` | wellness event/action APIs and system-code access | false unless backend AI enablement, reminders, and positive license quantity are all present | Config/ContactCenter | wellness contract removed |
47
+
48
+ The backend-delivered `agentWellbeing.enable` value is the supported server rollout decision. The SDK combines it with `wellnessBreakReminders === 'ENABLED'` and `aiAssistantQuantity > 0`; it does not evaluate the Desktop Split flag or define a new rollout response field.
45
49
 
46
50
  ## Maintenance
47
51
 
@@ -11,8 +11,8 @@
11
11
  | Doc kind | Module spec |
12
12
  | Coverage score | Partial (manifest-authoritative); 15/15 required document fields present |
13
13
  | Generated from | `module-spec` @ SDLC template library `0.2.1` |
14
- | generated_by / approved_by / updated_at | Codex generator / developer-approved follow-up review remediation / 2026-07-21 |
15
- | Validation status | Follow-up validation passed (independent Claude fallback, 2026-07-21); 1 existing test-coverage gap; coverage remains Partial |
14
+ | generated_by / approved_by / updated_at | Codex generator / developer-approved Agent Wellness Break remediation / 2026-09-07 |
15
+ | Validation status | Agent Wellness Break v0.4 remediation independently validated by claude-code on 2026-09-07; coverage remains Partial until the remaining baseline promotion criteria are satisfied |
16
16
 
17
17
  ## Evidence Rules
18
18
  Every requirement cites stable source and test file paths. Code/tests are the behavioral referee; routed source text supplies explicit intent and rationale. Missing or contradictory evidence blocks promotion.
@@ -37,6 +37,10 @@ The `@webex/contact-center` package is a Webex SDK plugin that provides a TypeSc
37
37
 
38
38
  - **Metrics & Diagnostics**: Built-in telemetry and log upload
39
39
 
40
+ - **Answer on Webex**: Accept, Decline, Mute, and DTMF for voice offers when the agent uses Webex App desktop calling (`enableWxBetterTogether`).
41
+
42
+ - **Agent Wellness Break**: Effective enablement, agent/org-scoped notifications, active-session action reporting, system idle-code lookup, and legacy state transitions.
43
+
40
44
  ## Purpose / Responsibility
41
45
  Own the published Webex Contact Center SDK plugin surface, registration lifecycle, public method delegation, and application-facing event routing.
42
46
 
@@ -66,14 +70,18 @@ src/
66
70
  | `src/config.ts` | Authoritative Contact Center implementation or contract source. |
67
71
  | `src/services/UserPreference.ts` | User-preference CRUD implementation exposed through `cc.userPreference`. |
68
72
  | `src/services/task/dialer.ts` | Preview-campaign AQM request implementations. |
69
- | `src/services/task/types.ts` | `PreviewContactPayload`, `TaskResponse`, and task contract types. |
73
+ | `src/services/task/types.ts` | `PreviewContactPayload`, `DropConferenceParticipantPayload`, `TaskResponse`, and task contract types. |
70
74
 
71
75
  ## Public Surface
72
76
  | Contract ID | Type | Surface | Purpose | Compatibility / deprecation | Schema / detail link | Root index |
73
77
  |---|---|---|---|---|---|---|
74
78
  | `contact-center.surface` | SDK / event / internal API | Published `@webex/contact-center` exports and the `ContactCenter` (`cc`) WebexPlugin API. | Stable module consumption boundary. | Additive changes by default; breaking package exports require a major-version transition. | `src/index.ts` | `CONTRACTS.md` |
79
+ | `contact-center.consult-transfer-lists` | SDK data API | Existing `getQueues` and `getEntryPoints` methods, their existing search/response types, and full `ContactServiceQueue` / `EntryPointRecord` rows. | Provide consult/transfer telephony defaults without adding a parallel list API or projected destination model. | Behavioral default correction; explicit existing filter/sort/profile inputs remain overrides and full record types remain the response contract. | `src/cc.ts`, `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/types.ts` | `CONTRACTS.md` |
80
+ | `contact-center.consult-transfer-controls` | SDK task control API | Ordered `TaskUIControls.consultTransferDestinations` arrays using the existing destination values. | Give all Task consumers the same ordered, action-specific destination visibility without a second policy call. | Additive public field; consumers may hide SDK-allowed categories but must not enable omitted categories. | `src/cc.ts`, `src/services/task/types.ts`, `src/services/task/state-machine/uiControlsComputer.ts`, `src/index.ts` | `CONTRACTS.md` |
75
81
  | `contact-center.user-preference` | SDK data API | Exported `UserPreference`, `cc.userPreference`, and user-preference request/response types. | Read and mutate user preferences through authenticated REST operations. | Additive public API; removals or signature changes are breaking. | `src/services/UserPreference.ts`, `src/services/config/types.ts` | `CONTRACTS.md` |
76
82
  | `contact-center.preview-campaign` | SDK task API | `acceptPreviewContact`, `skipPreviewContact`, `removePreviewContact`. | Resolve campaign preview reservations through typed AQM operations. | Additive public API; removals or signature changes are breaking. | `src/cc.ts`, `src/services/task/dialer.ts`, `src/services/task/types.ts` | `CONTRACTS.md` |
83
+ | `contact-center.conference-participant-drop` | SDK task API | Exported `DropConferenceParticipantPayload` and `ITask.dropConferenceParticipant`. | Remove a conference participant through the media-specific task implementation and correlated AQM completion. | Additive public API; removals or signature changes are breaking. | `src/index.ts`, `src/services/task/types.ts`, `src/services/task/voice/Voice.ts` | `CONTRACTS.md` |
84
+ | `contact-center.agent-wellness-break` | SDK API / events | `Profile.isWellnessBreakEnabled`, `requestWellnessBreak`, `respondToWellnessBreak`, `getWellbeingBreakIdleCode`, and the wellness notification event contract. | Let hosts implement the public wellness-break lifecycle without reproducing backend payloads, routing rules, or session validation. | Additive public API; the effective gate is false unless all supported configuration inputs are affirmative. | `src/cc.ts`, `src/types.ts`, `src/services/config/types.ts` | `CONTRACTS.md` |
77
85
 
78
86
  Compatibility notes:
79
87
  - Do not remove or reinterpret exported symbols/events without a documented consumer migration.
@@ -88,17 +96,45 @@ Compatibility notes:
88
96
  |---|---|---|---|---|---|---|
89
97
  | CONTACT_CENTER-R-001 | Construct the service graph once after the host Webex SDK emits READY, before `register()` is invoked. | Collaborators require initialized host request, logger, and plugin configuration state. | `src/cc.ts` | `test/unit/spec/cc.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
90
98
  | CONTACT_CENTER-R-002 | `register()` must attach connection/message listeners, connect the primary WebSocket, and return the fetched Profile or rethrow a logged failure. | Applications need an explicit readiness boundary and must never observe a synthetic successful registration. | `src/cc.ts` | `test/unit/spec/cc.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
91
- | CONTACT_CENTER-R-003 | Delegate agent, task, data, user-preference, preview-campaign, AI-assistant, calling, and telemetry behavior to their owning collaborators while preserving typed package methods and events. Before preview delegation, reject disabled skip/remove actions from task campaign flags. | A stable façade keeps consumer compatibility while specialized modules retain transport and lifecycle ownership; campaign controls must prevent prohibited backend operations. | `src/cc.ts`, `src/services/UserPreference.ts`, `src/services/task/dialer.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/services/UserPreference.ts`, `test/unit/spec/services/task/dialer.ts` | Public preview delegation is covered; the `campaignPreviewSkipDisabled` and `campaignPreviewRemoveDisabled` early-exit guards lack direct unit coverage. Independent review identified this gap on 2026-07-15. | PRESENT |
99
+ | CONTACT_CENTER-R-003 | Delegate agent, task, data, user-preference, preview-campaign, AI-assistant, calling, and telemetry behavior to their owning collaborators while preserving typed package methods and events. Existing `getQueues` and `getEntryPoints` delegate to their services with unchanged signatures and full-record responses; the services own consult/transfer telephony filter, profile-view, ordering, and cache defaults while honoring explicit existing-parameter overrides. Before preview delegation, reject disabled skip/remove actions from task campaign flags. | A thin stable façade avoids parallel consumer APIs while service-owned defaults keep ordinary widget calls consistent and preserve an override path for other consumers. | `src/cc.ts`, `src/types.ts`, `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/services/UserPreference.ts`, `src/services/task/dialer.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts`, `test/unit/spec/services/UserPreference.ts`, `test/unit/spec/services/task/dialer.ts` | Public preview delegation is covered; the `campaignPreviewSkipDisabled` and `campaignPreviewRemoveDisabled` early-exit guards lack direct unit coverage. Independent review identified this gap on 2026-07-15. | PRESENT |
92
100
  | CONTACT_CENTER-R-004 | `deregister()` must remove registered listeners, stop applicable host/calling resources, close primary and RTD WebSockets, clear agent configuration, and surface cleanup failures. | Listener or connection leaks create duplicate events and stale authenticated sessions in long-lived hosts. | `src/cc.ts` | `test/unit/spec/cc.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
93
101
  | CONTACT_CENTER-R-005 | On `connectionLost`, ContactCenter must own recovery policy and invoke private `silentRelogin()` only when automated relogin is allowed. | ConnectionService reports transport state; only ContactCenter has agent profile and policy context for authentication recovery. | `src/cc.ts` | `test/unit/spec/cc.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
102
+ | CONTACT_CENTER-R-006 | Expose Agent Wellness Break methods, action-value objects, and types only through the package façade. Derive the public action unions from those `as const` value objects. Action calls accept no identity or context-mutating API; ApiAIAssistant reads effective enablement and organization/agent/session identity from a read-only provider supplied by ContactCenter at construction and rejects when that context is incomplete. Logout, deregistration entry, a current-session multi-login close, and relogin update the provider's source state. The exact system idle-code cache and its in-flight lookup are owned by one registration generation; a newer registration or deregistration rejects a late result instead of caching it. | Wellness actions and cached configuration are registration-scoped and must not leak across agents, relogins, multi-login closures, organizations, or registrations; one public value/type source prevents wire-value drift. | `src/cc.ts`, `src/types.ts`, `src/services/ApiAiAssistant.ts`, `src/index.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/services/ApiAiAssistant.ts`, `docs/samples/contact-center/` | The backend-delivered `agentWellbeing.enable` value is treated as the server rollout decision because no distinct rollout field exists in the supported SDK response contracts. | PRESENT |
103
+ | CONTACT_CENTER-R-007 | When wellness is effectively enabled, connect the RTD WebSocket even if transcripts and suggested responses are disabled. Route valid `Wellness_Break_Handler` messages from the primary or RTD data-notification socket to `CC_AGENT_EVENTS.WELLNESS_BREAK`. Notification eligibility is scoped to the current agent and organization and deliberately does not compare the notification-provided `agentSessionId` with the active session; outbound wellness APIs remain active-session validated. Ignore malformed or foreign-identity messages without logging the full payload. | A long-lived host needs parity with Desktop notification routing without dropping legitimate nudges whose backend session metadata differs, while actions must still be sent only for the active local session. | `src/cc.ts`, `src/constants.ts`, `src/services/config/types.ts`, `src/services/ApiAiAssistant.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/services/ApiAiAssistant.ts`, `docs/samples/contact-center/` | Notification delivery remains best-effort; the backend owns offer generation and ordering. | PRESENT |
104
+ | CONTACT_CENTER-R-008 | The standalone SDK sample must keep `WellbeingBreak` out of the ordinary idle-code selector, wait for legacy state confirmation and all tasks to become safe, restore `Available` after a completed break with bounded recovery, synchronize authoritative external state changes, use a session-scoped refresh marker without replaying an offer, action, or break, and revoke manual-request eligibility on `WELLNESS_BREAK_NOT_ALLOWED`. A rejected `REJECTED` or `NO_RESPONSE` delivery must retain and re-arm the offer for retry. Logout cleanup must ignore a different agent session, and deregistration cleanup must run when the SDK has completed its local teardown even if a deferred cleanup error is reported. Pure transition helpers own these decisions and are covered behaviorally; browser/source checks are limited to bundle and copy surfaces. | The sample is the executable public-contract reference and must track backend eligibility, avoid duplicated wire literals, and avoid state stranding or cross-session cleanup. | `docs/samples/contact-center/app.js`, `docs/samples/contact-center/wellness-utils.js`, `docs/samples/contact-center/index.html`, `src/webex.js` | `test/unit/spec/wellnessSampleUtils.ts`, sample build | Live QA still supplies authoritative backend/session integration evidence. | PRESENT |
94
105
 
95
106
  ## Design Overview
96
107
  `ContactCenter` is the package façade and lifecycle owner. Its constructor waits for the host Webex SDK `READY` event, validates plugin configuration, initializes `WebexRequest`, obtains the singleton `Services` graph, and constructs calling, AI-assistant, metrics, task-management, `UserPreference`, and data-service collaborators. `register()` is deliberately narrower: it attaches runtime listeners and establishes the primary Contact Center WebSocket subscription.
97
108
 
98
109
  Direct data/configuration and user-preference operations return authenticated REST responses. Enabled agent/task AQM operations, including preview-campaign accept/skip/remove, send authenticated HTTP requests but resolve or reject only after a matching WebSocket notification. Before delegating preview skip/remove, ContactCenter checks the task's campaign-disable flags and throws locally when the corresponding flag is `'true'`. TaskManager converts backend task events into Task instances and typed state-machine events. ContactCenter maps package-facing events through WebexPlugin `trigger` or its internal EventEmitter according to the published contract.
99
110
 
111
+ Inbound primary-WebSocket messages are mapped through `handleWebsocketMessage`, which emits only event names on the typed `CC_EVENTS`/`AGENT_EVENTS` allow-list. A server-controlled `eventData.data.type` that is not a known allow-listed constant is ignored and never emitted as an application event name.
112
+
100
113
  Durable agent, task, and configuration records remain remote-system owned. The package owns only in-memory profile/task/listener/cache/connection state.
101
114
 
115
+ ### Agent Wellness Break
116
+
117
+ The public enablement signal is `Profile.isWellnessBreakEnabled`. It is true only when the backend-delivered AI feature row has `agentWellbeing.enable === true`, `wellnessBreakReminders === 'ENABLED'`, and the organization reports `aiAssistantQuantity > 0`. The SDK does not create a Desktop Split client or invent a rollout response field: the backend controls rollout by deciding whether the delivered AI feature configuration enables wellness for the organization.
118
+
119
+ After station login or relogin, ContactCenter retains the current agent-session id. When registration silently restores an already logged-in station, the returned `Profile.agentSessionId` projects that active session. It is absent when registration has no active session. This lets hosts recover session-scoped state after refresh without reading SDK internals or trusting a notification's session id. ApiAIAssistant reads the current effective gate and organization/agent/session identity through a read-only provider supplied by ContactCenter at construction; it exposes no context-mutating method or separate factory. Logout, deregistration entry, and a current-session multi-login close invalidate the provider's source state. `requestWellnessBreak()` and `respondToWellnessBreak()` do not accept identity fields; they POST a direct custom event with a fresh numeric timestamp and reject disabled or incomplete context before transport. Public action types are derived from exported `as const` action-value objects so applications and samples can use the same wire values without an enum. `getWellbeingBreakIdleCode()` resolves the exact active system code named `WellbeingBreak` and caches it for the registration lifetime. The lookup captures its registration generation and organization before transport; if either ownership value changes before the response arrives, the stale result is rejected and never repopulates the cache.
120
+
121
+ Wellness payloads are handled by ContactCenter on the primary or RTD data-notification socket before ordinary routing. Only known actions with matching agent and organization are emitted; the notification session is retained as diagnostic metadata and is not treated as action authority. The canonical optional `actionText` field is normalized to public `actionText`. Deregistration clears the wellness session and system-code cache.
122
+
123
+ The standalone SDK browser sample keeps `WellbeingBreak` out of the ordinary status selector. It reads the exported wellness wire constants from the standalone `Webex` constructor, seeds its current session and legacy state from a logged-in registration profile after silent relogin, and shows only the action name in its latest-event display. It creates a session-scoped recovery marker before changing legacy state, clears manual-request eligibility when a break starts so the request control remains disabled after restoration until another `SUGGEST_WELLNESS_BREAK`, confirms the transition, sends `ACCEPTED` only after state success, and waits for every task to leave incoming, active, consult, conference, campaign, and wrap-up work before starting its 60-second demonstration timer. Restoration targets `Available / 0`, retries bounded failures, and retains reconnect recovery ownership after exhaustion. Authoritative external Available changes end the local lifecycle, while refresh recovery restores a matching current session without replaying the offer, response action, or break. Pure helpers own notification, response, logout, and deregistration transition decisions; a failed rejection/no-response delivery retains and re-arms its offer. If SDK deregistration completes its local teardown but reports a deferred error, the sample still detaches listeners and resets its local controls.
124
+
125
+ ### wxApp Better Together (WXCC-6026)
126
+
127
+ Contract id: `contact-center.wxapp-answer` ([CONTRACTS.md](./CONTRACTS.md)). Task telephony routing, UI controls, and mute events are specified in [task-spec.md](../src/services/task/ai-docs/task-spec.md). Service collaborators: [services-spec.md](../src/services/ai-docs/services-spec.md).
128
+
129
+ - **Init flag:** `webex.init({ cc: { enableWxBetterTogether: boolean } })` — default `false`. When `true`, ContactCenter enables wxApp telephony routing on tasks after supported station login. **Compatible with `allowMultiLogin: true`** (multiple SDK sessions may receive offers; wxApp telephony is routed per active task instance). **Phase 1 is init-only** — to change the flag after SDK init, re-init with updated config.
130
+ - **Read API:** `cc.isWxBetterTogetherEnabled()` returns the current init flag value.
131
+ - **Phase 2 (internal/private):** `setManageWebexCallingInWxcc(enabled)` remains as a private implementation for future runtime toggle; hosts must not call it in Phase 1.
132
+ - **Post-login hooks:** `ensureWxAppPostStationLogin()` runs after successful `stationLogin()` and after `silentRelogin()` on socket reconnect. When the init flag is ON, it publishes usersub `true`, connects Mercury/device for mute sync, and backfills mute state on active tasks. Failures roll back wxApp config and release partial Mercury/device resources without failing station login. When OFF, it force-publishes usersub `false` (clears stale suppression after page refresh) and tears down wxApp Mercury resources.
133
+ - **Teardown:** `deregister()`, station logout, and wxApp teardown paths call `teardownWxAppLocalState()` — publish usersub `false`, unsubscribe Mercury, release CC-owned device/Mercury connections, and reset **session runtime** state (usersub active flag, Mercury subscriptions, task-manager wxApp routing) so stale session flags do not apply on relogin. The host init flag (`enableWxBetterTogether`) is **not** cleared on station logout — it persists until `deregister()` or re-init per Phase 1 contract. Local cleanup runs even when usersub publish fails.
134
+ - **Host telephony surface:** Hosts call unified `task.accept()`, `task.decline()`, `task.toggleMute({ muted? })`, and `task.transmitDtmf({ dtmf })`; SDK `Voice` routes wxApp legs internally when the flag is active. Shared-line `lineOwnerId` defaults from the wxApp agent participant when omitted.
135
+
136
+ Evidence: `src/cc.ts`, `src/config.ts`, `src/services/WebexCrossClientService.ts`, `src/services/WxAppTelephonyMercurySync.ts`, `test/unit/spec/cc.ts`.
137
+
102
138
  ## Data Flow
103
139
  ```mermaid
104
140
  flowchart TD
@@ -265,6 +301,7 @@ classDiagram
265
301
  - **UC-3 Delegate SDK operations:** validate/map public inputs, call the owning collaborator, track metrics, and return or emit typed results. Evidence: `src/cc.ts`, `src/index.ts`, `test/unit/spec/cc.ts`.
266
302
  - **UC-4 Recover connection:** consume ConnectionService state and conditionally reload the agent session through ContactCenter policy. Evidence: `src/cc.ts`, `test/unit/spec/cc.ts`.
267
303
  - **UC-5 Deregister:** remove the same listener identities, shut down applicable host/WebSocket resources, and clear in-memory profile state. Evidence: `src/cc.ts`, `test/unit/spec/cc.ts`.
304
+ - **UC-6 Wellness lifecycle:** consume an agent/org-scoped offer regardless of its notification session metadata, report a user action using the active local session, resolve the system idle code, and demonstrate legacy Idle/Available transitions. Evidence: `src/cc.ts`, `src/services/ApiAiAssistant.ts`, `src/services/config/index.ts`, `test/unit/spec/cc.ts`, `docs/samples/contact-center/`.
268
305
 
269
306
  ## State Model
270
307
  ContactCenter retains in-memory `agentConfig`, collaborator references, event listeners, task collections through TaskManager, and connection/recovery state. Remote Webex services remain authoritative for agent, task, and organization data. Registration establishes runtime connectivity but does not imply station login; deregistration tears down SDK resources but does not itself perform station logout.
@@ -273,9 +310,13 @@ ContactCenter retains in-memory `agentConfig`, collaborator references, event li
273
310
  - Collaborators are initialized after host READY and before their use; `register()` must not be documented as their constructor boundary. Evidence: `src/cc.ts`.
274
311
  - AQM promises complete only from correlated WebSocket success/failure or timeout, not from HTTP acknowledgement. Evidence: `src/services/core/aqm-reqs.ts`.
275
312
  - `skipPreviewContact` checks `campaignPreviewSkipDisabled` and `removePreviewContact` checks `campaignPreviewRemoveDisabled` on the matching task. When the applicable value is `'true'`, ContactCenter throws before initiating an HTTP or WebSocket-correlated AQM operation; `acceptPreviewContact` has no equivalent pre-guard. Evidence: `src/cc.ts`.
313
+ - `handleWebsocketMessage` only re-emits event names that belong to the typed `CC_EVENTS`/`AGENT_EVENTS` allow-list; an untrusted `eventData.data.type` outside that allow-list is not emitted as an event name. Evidence: `src/cc.ts`.
276
314
  - ContactCenter owns automated relogin policy; ConnectionService owns transport-state detection/emission. Evidence: `src/cc.ts`, `src/services/core/websocket/connection-service.ts`.
277
315
  - Deregistration does not station-logout the agent. Evidence: `src/cc.ts`.
278
316
  - Published methods/types/events remain semver-sensitive through `src/index.ts`.
317
+ - Wellness actions take no public identity or context-mutating input and require the effective profile flag plus non-empty SDK-owned organization, registered-agent, and current-session context read from the internal live provider; all checks fail closed after current-session logout, multi-login close, or deregistration.
318
+ - Wellness action unions derive from exported `as const` value objects; backend message-type and enablement sentinels use internal constants rather than duplicated literals.
319
+ - Malformed, unknown-action, stale-agent, and stale-org wellness notifications are ignored and measured without logging the full payload. A different notification `agentSessionId` is retained as diagnostic metadata and does not make an otherwise valid current-agent/current-org wellness event stale.
279
320
 
280
321
  ## Concurrency & Reactive Flow
281
322
  READY initialization, REST promises, AQM WebSocket correlation, TaskManager events, calling events, and connection timers execute asynchronously. Listener cleanup must use the registered function identity. Message listeners are independent: AqmReqs correlates pending requests, ContactCenter maps package events, TaskManager owns task lifecycle, and ConnectionService tracks liveness/reconnect state.
@@ -297,7 +338,7 @@ stateDiagram-v2
297
338
  ```
298
339
 
299
340
  ## Protocol / Wire Format
300
- Authenticated REST initiates direct data/config operations and AQM agent/task operations. For AQM, the HTTP response is acknowledgement only; `notifSuccess.bind`/`notifFail.bind` match WebSocket payloads that settle the promise. The primary WebSocket carries Contact Center notifications; the RTD WebSocket carries transcript/suggestion traffic. Payload and event names are owned by `src/types.ts`, `src/services/config/types.ts`, `src/services/agent/types.ts`, and `src/services/task/types.ts`.
341
+ Authenticated REST initiates direct data/config operations and AQM agent/task operations. For AQM, the HTTP response is acknowledgement only; `notifSuccess.bind`/`notifFail.bind` match WebSocket payloads that settle the promise. Wellness actions are the exception: ApiAIAssistant posts a direct `CUSTOM_EVENT` to `/event` and requires HTTP 202. The primary and RTD WebSockets can carry `Wellness_Break_Handler`; ContactCenter routes it before task-specific traffic. Payload and event names are owned by `src/types.ts`, `src/services/config/types.ts`, `src/services/agent/types.ts`, and `src/services/task/types.ts`.
301
342
 
302
343
  ## Error Handling & Failure Modes
303
344
  | Condition | Signal (error/code/result) | Caller recovery |
@@ -326,7 +367,7 @@ The module registers as `cc` through the Webex SDK plugin system and depends on
326
367
  - A single plugin surface centralizes compatibility and event routing, while specialized modules retain implementation ownership; this costs careful bootstrap and cleanup ordering.
327
368
 
328
369
  ## Test-Case Strategy (module)
329
- `test/unit/spec/cc.ts` is the characterization baseline. Cover READY-time construction, registration success/failure, listener identity, public method delegation, WebSocket event mapping, preview-campaign operations (including disabled skip/remove pre-guards), automated-relogin enabled/disabled branches, browser-calling conditions, and deregistration cleanup/error paths. Use `test/unit/spec/services/UserPreference.ts` for user-preference CRUD and `test/unit/spec/services/task/dialer.ts` for preview AQM request contracts. Preserve the package-wide 85% branch/function/line/statement threshold.
370
+ `test/unit/spec/cc.ts` is the characterization baseline. Cover READY-time construction, registration success/failure, listener identity, existing queue/entry-point method delegation, WebSocket event mapping, preview-campaign operations (including disabled skip/remove pre-guards), automated-relogin enabled/disabled branches, browser-calling conditions, and deregistration cleanup/error paths. Use Queue and EntryPoint service tests for default policy and explicit existing-parameter overrides, `test/unit/spec/services/UserPreference.ts` for user-preference CRUD, and `test/unit/spec/services/task/dialer.ts` for preview AQM request contracts. Preserve the package-wide 85% branch/function/line/statement threshold.
330
371
 
331
372
  | Requirement | Existing evidence | Required revalidation |
332
373
  |---|---|---|
@@ -335,6 +376,9 @@ The module registers as `cc` through the Webex SDK plugin system and depends on
335
376
  | CONTACT_CENTER-R-003 | `test/unit/spec/cc.ts`, `test/unit/spec/services/UserPreference.ts`, `test/unit/spec/services/task/dialer.ts` | Add direct tests proving disabled skip/remove flags throw before dialer invocation; revalidate typed delegation, user-preference CRUD, preview-campaign AQM operations, and event routing. |
336
377
  | CONTACT_CENTER-R-004 | `test/unit/spec/cc.ts` | listener/resource cleanup and error propagation |
337
378
  | CONTACT_CENTER-R-005 | `test/unit/spec/cc.ts` | relogin policy ownership |
379
+ | CONTACT_CENTER-R-006 | `test/unit/spec/cc.ts`, `test/unit/spec/services/ApiAiAssistant.ts` | Effective-gate and internal organization/agent/session validation, current-session multi-login invalidation, registration-generation idle-code cache ownership, identity-free public input, exact request body, action validation, and direct-HTTP failure paths. |
380
+ | CONTACT_CENTER-R-007 | `test/unit/spec/cc.ts`, `test/unit/spec/services/ApiAiAssistant.ts` | Wellness normalization on primary and RTD notification sockets, notification-session mismatch acceptance, invalid agent/org filtering, and active-session outbound validation. |
381
+ | CONTACT_CENTER-R-008 | `test/unit/spec/wellnessSampleUtils.ts`, sample build | Safe-work classification, legacy external/RONA decisions, minimal refresh marker, recovery decisions, retryable offer-response transitions, session-scoped logout cleanup, deferred-error deregistration cleanup, and standalone browser constant exposure. |
338
382
 
339
383
  ## Traceability
340
384
  - Repo architecture: `ARCHITECTURE.md` · Registry: `SPEC_INDEX.md`