@webex/contact-center 3.13.0-next.1 → 3.13.0-next.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/.repo-context.json +704 -0
  2. package/.sdd/manifest.json +1065 -339
  3. package/AGENTS.md +935 -60
  4. package/dist/webex.js +1 -1
  5. package/docs/adr/0001-spec-source-policy.md +97 -0
  6. package/{ai-docs/features/consult-transfer-list-policy/spec/feature-spec.md → docs/adr/0002-consult-transfer-list-policy.md} +227 -244
  7. package/docs/adr/0003-repo-standards-migration.md +104 -0
  8. package/docs/adr/index.md +35 -0
  9. package/docs/architecture.md +460 -0
  10. package/docs/getting-started.md +142 -0
  11. package/docs/index.md +53 -0
  12. package/docs/specs/README.md +98 -0
  13. package/package.json +10 -9
  14. package/schemas/repo-context.schema.json +796 -0
  15. package/src/docs/README.md +727 -0
  16. package/src/metrics/docs/README.md +710 -0
  17. package/src/services/agent/docs/README.md +673 -0
  18. package/src/services/config/docs/README.md +530 -0
  19. package/src/services/core/docs/README.md +993 -0
  20. package/src/services/docs/README.md +765 -0
  21. package/src/services/task/docs/README.md +1569 -0
  22. package/src/services/task/state-machine/docs/README.md +1388 -0
  23. package/src/utils/AGENTS.md +6 -4
  24. package/src/utils/docs/README.md +413 -0
  25. package/umd/contact-center.min.js +2 -2
  26. package/umd/contact-center.min.js.map +1 -1
  27. package/ai-docs/ARCHITECTURE.md +0 -168
  28. package/ai-docs/CONTRACTS.md +0 -64
  29. package/ai-docs/GETTING_STARTED.md +0 -168
  30. package/ai-docs/GLOSSARY.md +0 -43
  31. package/ai-docs/README.md +0 -138
  32. package/ai-docs/REVIEW_CHECKLIST.md +0 -41
  33. package/ai-docs/RULES.md +0 -444
  34. package/ai-docs/SECURITY.md +0 -52
  35. package/ai-docs/SERVICE_STATE.md +0 -52
  36. package/ai-docs/SPEC_INDEX.md +0 -65
  37. package/ai-docs/adr/0001-spec-source-policy.md +0 -55
  38. package/ai-docs/adr/README.md +0 -8
  39. package/ai-docs/adr/_adr-template.md +0 -31
  40. package/ai-docs/contact-center-spec.md +0 -388
  41. package/ai-docs/features/contact-owner-change-refactor.md +0 -78
  42. package/ai-docs/features/generated-spec-conformance-fidelity-remediation/spec/feature-spec.md +0 -117
  43. package/ai-docs/features/residual-warning-coverage-completion/spec/feature-spec.md +0 -203
  44. package/ai-docs/features/validator-code-fidelity-drift-fix/spec/feature-spec.md +0 -315
  45. package/ai-docs/patterns/event-driven-patterns.md +0 -485
  46. package/ai-docs/patterns/testing-patterns.md +0 -480
  47. package/ai-docs/patterns/typescript-patterns.md +0 -365
  48. package/ai-docs/templates/README.md +0 -102
  49. package/ai-docs/templates/documentation/create-agents-md.md +0 -240
  50. package/ai-docs/templates/documentation/create-architecture-md.md +0 -295
  51. package/ai-docs/templates/existing-service/bug-fix.md +0 -254
  52. package/ai-docs/templates/existing-service/feature-enhancement.md +0 -450
  53. package/ai-docs/templates/new-method/00-master.md +0 -80
  54. package/ai-docs/templates/new-method/01-requirements.md +0 -232
  55. package/ai-docs/templates/new-method/02-implementation.md +0 -295
  56. package/ai-docs/templates/new-method/03-tests.md +0 -201
  57. package/ai-docs/templates/new-method/04-validation.md +0 -141
  58. package/ai-docs/templates/new-service/00-master.md +0 -109
  59. package/ai-docs/templates/new-service/01-pre-questions.md +0 -159
  60. package/ai-docs/templates/new-service/02-code-generation.md +0 -346
  61. package/ai-docs/templates/new-service/03-integration.md +0 -178
  62. package/ai-docs/templates/new-service/04-test-generation.md +0 -205
  63. package/ai-docs/templates/new-service/05-validation.md +0 -145
  64. package/src/metrics/ai-docs/AGENTS.md +0 -350
  65. package/src/metrics/ai-docs/ARCHITECTURE.md +0 -338
  66. package/src/metrics/ai-docs/metrics-spec.md +0 -971
  67. package/src/services/agent/ai-docs/AGENTS.md +0 -240
  68. package/src/services/agent/ai-docs/ARCHITECTURE.md +0 -304
  69. package/src/services/agent/ai-docs/agent-spec.md +0 -505
  70. package/src/services/ai-docs/AGENTS.md +0 -386
  71. package/src/services/ai-docs/services-spec.md +0 -512
  72. package/src/services/config/ai-docs/AGENTS.md +0 -250
  73. package/src/services/config/ai-docs/ARCHITECTURE.md +0 -413
  74. package/src/services/config/ai-docs/config-spec.md +0 -669
  75. package/src/services/core/ai-docs/AGENTS.md +0 -381
  76. package/src/services/core/ai-docs/ARCHITECTURE.md +0 -698
  77. package/src/services/core/ai-docs/core-spec.md +0 -797
  78. package/src/services/task/ai-docs/AGENTS.md +0 -457
  79. package/src/services/task/ai-docs/ARCHITECTURE.md +0 -595
  80. package/src/services/task/ai-docs/task-spec.md +0 -1501
  81. package/src/services/task/state-machine/ai-docs/AGENTS.md +0 -460
  82. package/src/services/task/state-machine/ai-docs/ARCHITECTURE.md +0 -1156
  83. package/src/services/task/state-machine/ai-docs/task-state-machine-spec.md +0 -2247
  84. package/src/utils/ai-docs/utils-spec.md +0 -391
@@ -1,31 +0,0 @@
1
- # ADR-NNNN — Short decision title
2
-
3
- | Field | Value |
4
- |---|---|
5
- | Status | Proposed |
6
- | Date | YYYY-MM-DD |
7
- | Deciders | roles |
8
- | Supersedes / Superseded by | none |
9
-
10
- ## Context
11
-
12
- State the code-grounded forces and evidence paths.
13
-
14
- ## Decision
15
-
16
- State the directive.
17
-
18
- ## Alternatives Considered
19
-
20
- | Alternative | Pros | Cons | Why rejected |
21
- |---|---|---|---|
22
-
23
- ## Consequences
24
-
25
- - **Positive:**
26
- - **Negative / cost:**
27
- - **Agents must:**
28
-
29
- ## Revisit When
30
-
31
- - Define a measurable reconsideration trigger.
@@ -1,388 +0,0 @@
1
- # Contact Center — SPEC
2
-
3
- > Start here → root [`AGENTS.md`](../AGENTS.md) · router [`SPEC_INDEX.md`](SPEC_INDEX.md) · system [`ARCHITECTURE.md`](ARCHITECTURE.md). This is the module's canonical specification.
4
-
5
- ## Metadata
6
-
7
- | Field | Value |
8
- |---|---|
9
- | Module id | `contact-center` |
10
- | Source path(s) | `src` |
11
- | Doc kind | Module spec |
12
- | Coverage score | Partial (manifest-authoritative); 15/15 required document fields present |
13
- | Generated from | `module-spec` @ SDLC template library `0.2.1` |
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
-
17
- ## Evidence Rules
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.
19
-
20
- ## Source Material Register
21
- | Source material | Scope | Decision | Detail location or disposition |
22
- |---|---|---|---|
23
- | Reviewed prior module guides and architecture material | overview / architecture / API / tests | used and code-checked | Content is placed by meaning throughout this specification; exact routing remains in the manifest. |
24
-
25
- ## Overview
26
- Contact Center is one of nine confirmed Contact Center SDK modules. Own the published Webex Contact Center SDK plugin surface, registration lifecycle, public method delegation, and application-facing event routing. Existing reviewed documentation is migrated by meaning and code/tests remain the behavioral referee.
27
-
28
- The `@webex/contact-center` package is a Webex SDK plugin that provides a TypeScript/JavaScript API for building Contact Center agent applications. It enables:
29
-
30
- - **Agent Session Management**: Register, login, logout, state changes
31
-
32
- - **Task Handling**: Inbound/outbound calls, chat, transfers, conferences
33
-
34
- - **Real-time Events**: WebSocket-based notifications for agent and task events
35
-
36
- - **Browser-based Calling**: WebRTC integration for browser softphone
37
-
38
- - **Metrics & Diagnostics**: Built-in telemetry and log upload
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
- - **Browser voice readiness**: A public snapshot and change event for local browser line and Mobius socket state, with an `Available` transition guard when browser voice is required.
44
-
45
- ## Purpose / Responsibility
46
- Own the published Webex Contact Center SDK plugin surface, registration lifecycle, public method delegation, and application-facing event routing.
47
-
48
- ## Stack
49
- TypeScript 5.4, WebexPlugin, Node EventEmitter, WebSocket/WebRTC integrations, Jest 27, Yarn 3.4.1.
50
-
51
- ## Folder / Package Structure
52
- ```text
53
- src/
54
- ├── index.ts package exports and plugin registration
55
- ├── cc.ts ContactCenter façade and lifecycle orchestration
56
- ├── types.ts package-level public contracts
57
- ├── metrics/ telemetry manager and taxonomy
58
- ├── services/ transport, agent, config, data, and calling collaborators
59
- │ ├── UserPreference.ts user-preference CRUD REST client
60
- │ └── task/ task objects, manager, media implementations, state machine
61
- └── utils/PageCache.ts shared pagination cache
62
- ```
63
-
64
- ## Key Files (source of truth)
65
- | File | Holds |
66
- |---|---|
67
- | `src/index.ts` | Authoritative Contact Center implementation or contract source. |
68
- | `src/cc.ts` | Authoritative Contact Center implementation or contract source. |
69
- | `src/types.ts` | Authoritative Contact Center implementation or contract source. |
70
- | `src/constants.ts` | Authoritative Contact Center implementation or contract source. |
71
- | `src/config.ts` | Authoritative Contact Center implementation or contract source. |
72
- | `src/services/UserPreference.ts` | User-preference CRUD implementation exposed through `cc.userPreference`. |
73
- | `src/services/task/dialer.ts` | Preview-campaign AQM request implementations. |
74
- | `src/services/task/types.ts` | `PreviewContactPayload`, `DropConferenceParticipantPayload`, `TaskResponse`, and task contract types. |
75
-
76
- ## Public Surface
77
- | Contract ID | Type | Surface | Purpose | Compatibility / deprecation | Schema / detail link | Root index |
78
- |---|---|---|---|---|---|---|
79
- | `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` |
80
- | `contact-center.browser-voice-state` | SDK API / event | `getVoiceConnectionState()`, `voice:connectionStateChange`, and exported voice status/error symbols. | Let hosts observe local browser voice readiness and allow the SDK to reject only transitions into `Available` while required voice is unavailable. | Additive API/event; local login controls requirement and deregistration resets the snapshot. | `src/cc.ts`, `src/services/WebCallingService.ts`, `src/types.ts`, `src/services/config/types.ts` | `CONTRACTS.md` |
81
- | `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` |
82
- | `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` |
83
- | `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` |
84
- | `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` |
85
- | `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` |
86
- | `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` |
87
-
88
- Compatibility notes:
89
- - Do not remove or reinterpret exported symbols/events without a documented consumer migration.
90
-
91
- ## Requires (dependencies)
92
- - Webex SDK host/plugin lifecycle
93
- - Contact Center REST and WebSocket backends
94
- - Services, TaskManager, MetricsManager, WebCallingService, UserPreference, and data-service modules
95
-
96
- ## Requirements
97
- | ID | WHAT | WHY | Source Evidence | Test / Example Evidence | Assumptions / Gaps | Confidence |
98
- |---|---|---|---|---|---|---|
99
- | 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 |
100
- | 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 |
101
- | 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 |
102
- | 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 |
103
- | 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 |
104
- | 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 |
105
- | 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 |
106
- | 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 |
107
- | CONTACT_CENTER-R-009 | Expose `getVoiceConnectionState()` and `voice:connectionStateChange` through the Contact Center package façade. Track local browser line registration separately from Mobius socket status; mark voice required only when the local BROWSER login enables WebRTC registration; preserve the socket failure reason across line keepalive events; detach all line listeners and reset the snapshot on logout. Keep the `REGISTERED` listener active for later registration recovery. Preserve browser line registration during silent relogin unless `disableWebRTCRegistration` is enabled, even when voice is not required by the profile. Clear a stale local voice requirement when a station login notification reports `EXTENSION` or `AGENT_DN`. Reject only transitions into `Available` while required browser voice is unavailable, and send the `BROWSER_VOICE_NOT_READY` validation error through the existing failure metric/log path. | Contact Center hosts need reliable local readiness signals and agents must be able to leave `Available` during outages; multi-login notifications from another SDK instance must not create or retain a false local requirement. | `src/cc.ts`, `src/services/WebCallingService.ts`, `src/types.ts`, `src/services/config/types.ts`, `src/index.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/services/WebCallingService.ts`, `docs/samples/contact-center/` | The sample displays the current state; registration retries and socket recovery are reflected independently. | PRESENT |
108
-
109
- ## Design Overview
110
- `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.
111
-
112
- 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.
113
-
114
- 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.
115
-
116
- Durable agent, task, and configuration records remain remote-system owned. The package owns only in-memory profile/task/listener/cache/connection state.
117
-
118
- ### Agent Wellness Break
119
-
120
- 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.
121
-
122
- 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.
123
-
124
- 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.
125
-
126
- 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.
127
-
128
- ### wxApp Better Together (WXCC-6026)
129
-
130
- 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).
131
-
132
- - **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.
133
- - **Read API:** `cc.isWxBetterTogetherEnabled()` returns the current init flag value.
134
- - **Phase 2 (internal/private):** `setManageWebexCallingInWxcc(enabled)` remains as a private implementation for future runtime toggle; hosts must not call it in Phase 1.
135
- - **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.
136
- - **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.
137
- - **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.
138
-
139
- Evidence: `src/cc.ts`, `src/config.ts`, `src/services/WebexCrossClientService.ts`, `src/services/WxAppTelephonyMercurySync.ts`, `test/unit/spec/cc.ts`.
140
-
141
- ## Data Flow
142
- ```mermaid
143
- flowchart TD
144
- Host[Host Webex SDK READY] --> Validate[Validate plugin config]
145
- Validate --> WR[Initialize WebexRequest]
146
- WR --> Services[Services singleton: agent/config/contact/dialer + primary/RTD WebSockets]
147
- Services --> Collaborators[Create WebCalling, ApiAIAssistant, Metrics, TaskManager, UserPreference, data services]
148
- Collaborators --> Register[Application calls register]
149
- Register --> Listeners[Attach connection and message listeners]
150
- Listeners --> Connect[Subscribe/connect primary WebSocket]
151
- Connect --> Profile[Fetch/return Profile]
152
- Profile --> App[Application invokes typed cc methods]
153
- App --> Direct[Direct REST data/config]
154
- App --> AQM[AQM HTTP initiation]
155
- AQM --> WS[Correlated WebSocket completion]
156
- Direct --> App
157
- WS --> App
158
- ```
159
-
160
- ## Sequence Diagram(s)
161
- Sequence coverage:
162
-
163
- | Operation group | Diagram | Failure / recovery coverage |
164
- |---|---|---|
165
- | READY-time bootstrap | Bootstrap | Invalid configuration or collaborator initialization rejects readiness-dependent use. |
166
- | Registration | Register | Connection/subscription failure is logged, metrics record failure, logs upload, and the error is rethrown. |
167
- | Deregistration | Deregister | Cleanup failure is measured, logged, and rethrown; no synthetic success. |
168
- | Connection recovery | Recovery | ConnectionService emits state; ContactCenter chooses silent relogin or preserves failure state. |
169
-
170
- ### Bootstrap
171
-
172
- ```mermaid
173
- sequenceDiagram
174
- participant Host as Host Webex SDK
175
- participant CC as ContactCenter
176
- participant S as Services
177
- participant TM as TaskManager
178
- Host-->>CC: READY
179
- CC->>CC: validatePluginConfig()
180
- alt configuration valid
181
- CC->>CC: WebexRequest.getInstance(webex)
182
- CC->>S: Services.getInstance(webex, connectionConfig)
183
- CC->>CC: create WebCallingService + ApiAIAssistant + MetricsManager
184
- CC->>TM: getTaskManager(aiAssistant, contact, calling, primaryWS, rtdWS)
185
- CC->>CC: create EntryPoint + AddressBook + Queue; initialize LoggerProxy
186
- else invalid configuration or initialization failure
187
- CC-->>Host: readiness-dependent use rejects
188
- end
189
- ```
190
-
191
- ### Register
192
-
193
- ```mermaid
194
- sequenceDiagram
195
- participant App
196
- participant CC as ContactCenter
197
- participant WS as Primary WebSocketManager
198
- participant Cfg as AgentConfigService
199
- participant Agent as Services.agent
200
- participant Metrics
201
- App->>CC: register()
202
- CC->>CC: setupEventListeners(); listen for WS messages
203
- CC->>Metrics: time register success/failure
204
- CC->>WS: initWebSocket({body, resource: SUBSCRIBE_API})
205
- WS-->>CC: Welcome data containing agentId
206
- CC->>Cfg: getAgentConfig(orgId, agentId)
207
- alt profile fetched
208
- Cfg-->>CC: Profile
209
- CC->>CC: set TaskManager/config/AI flags
210
- opt applicable AI feature enabled
211
- CC->>CC: start RTD WebSocket; log but contain RTD failure
212
- end
213
- opt browser calling applicable
214
- CC->>CC: mercury.connect(); log but contain failure
215
- end
216
- opt allowAutomatedRelogin
217
- CC->>Agent: reload()
218
- Agent-->>CC: relogin result, AGENT_NOT_FOUND, or error
219
- end
220
- CC->>Metrics: track registration success
221
- CC-->>App: Profile
222
- else primary subscription/profile/relogin failure
223
- CC->>Metrics: track registration failure
224
- CC->>CC: uploadLogs(correlationId)
225
- CC-->>App: throw error
226
- end
227
- ```
228
-
229
- ### Deregister
230
-
231
- ```mermaid
232
- sequenceDiagram
233
- participant App
234
- participant CC as ContactCenter
235
- participant Host as Mercury/device
236
- participant WS as Primary + RTD WebSockets
237
- App->>CC: deregister()
238
- CC->>CC: remove TaskManager/message/connection listeners
239
- opt browser calling resources active
240
- CC->>Host: disconnect Mercury; unregister device
241
- end
242
- CC->>WS: close(false, reason)
243
- CC->>CC: agentConfig = null
244
- alt cleanup succeeds
245
- CC-->>App: void
246
- else cleanup fails
247
- CC-->>App: throw error
248
- end
249
- ```
250
-
251
- ### Recovery
252
-
253
- ```mermaid
254
- sequenceDiagram
255
- participant CS as ConnectionService
256
- participant CC as ContactCenter
257
- participant Agent as Services.agent
258
- CS-->>CC: connectionLost(details)
259
- CC->>CC: handleConnectionLost(details)
260
- alt allowAutomatedRelogin
261
- CC->>CC: silentRelogin()
262
- CC->>Agent: reload()
263
- alt relogin succeeds
264
- Agent-->>CC: relogin result; update agent config/device state
265
- else AGENT_NOT_FOUND
266
- Agent-->>CC: handled silently
267
- else other failure
268
- Agent--xCC: throw detailed error
269
- end
270
- else disabled
271
- CC->>CC: make no relogin call; retain reported transport state
272
- end
273
- ```
274
-
275
- ## Class / Component Relationships
276
- ```mermaid
277
- classDiagram
278
- class ContactCenter
279
- class Services
280
- class WebexRequest
281
- class MetricsManager
282
- class TaskManager
283
- class WebCallingService
284
- class ApiAIAssistant
285
- class EntryPoint
286
- class AddressBook
287
- class Queue
288
- ContactCenter --> WebexRequest : initializes/uses for log upload
289
- ContactCenter --> Services : agent/config/contact/dialer + WebSockets
290
- ContactCenter --> MetricsManager : timings and tracking
291
- ContactCenter --> TaskManager : task lifecycle/events
292
- ContactCenter --> WebCallingService : browser calling
293
- ContactCenter --> ApiAIAssistant : transcript/suggestion API
294
- ContactCenter --> EntryPoint
295
- ContactCenter --> AddressBook
296
- ContactCenter --> Queue
297
- TaskManager --> ApiAIAssistant
298
- TaskManager --> WebCallingService
299
- ```
300
-
301
- ## Use Cases
302
- - **UC-1 Host bootstrap:** after host READY, initialize the complete collaborator graph exactly once. Evidence: `src/cc.ts`, `test/unit/spec/cc.ts`.
303
- - **UC-2 Register:** attach listeners and establish the primary WebSocket subscription before returning Profile. Evidence: `src/cc.ts`, `test/unit/spec/cc.ts`.
304
- - **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`.
305
- - **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`.
306
- - **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`.
307
- - **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/`.
308
-
309
- ## State Model
310
- 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.
311
-
312
- ## Business Rules & Invariants
313
- - Collaborators are initialized after host READY and before their use; `register()` must not be documented as their constructor boundary. Evidence: `src/cc.ts`.
314
- - AQM promises complete only from correlated WebSocket success/failure or timeout, not from HTTP acknowledgement. Evidence: `src/services/core/aqm-reqs.ts`.
315
- - `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`.
316
- - `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`.
317
- - ContactCenter owns automated relogin policy; ConnectionService owns transport-state detection/emission. Evidence: `src/cc.ts`, `src/services/core/websocket/connection-service.ts`.
318
- - Deregistration does not station-logout the agent. Evidence: `src/cc.ts`.
319
- - Published methods/types/events remain semver-sensitive through `src/index.ts`.
320
- - 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.
321
- - Wellness action unions derive from exported `as const` value objects; backend message-type and enablement sentinels use internal constants rather than duplicated literals.
322
- - 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.
323
-
324
- ## Concurrency & Reactive Flow
325
- 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.
326
-
327
- ## State Machine
328
- ```mermaid
329
- stateDiagram-v2
330
- [*] --> AwaitingHostReady
331
- AwaitingHostReady --> Initialized: host READY + collaborators created
332
- Initialized --> Registering: register()
333
- Registering --> Registered: WebSocket/profile success
334
- Registering --> Initialized: registration failure
335
- Registered --> Recovering: connectionLost
336
- Recovering --> Registered: reconnect/relogin succeeds
337
- Recovering --> Registered: relogin disabled; transport state reported
338
- Registered --> Deregistering: deregister()
339
- Deregistering --> Initialized: listeners/resources cleared
340
- Deregistering --> Registered: cleanup throws before completion
341
- ```
342
-
343
- ## Protocol / Wire Format
344
- 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`.
345
-
346
- ## Error Handling & Failure Modes
347
- | Condition | Signal (error/code/result) | Caller recovery |
348
- |---|---|---|
349
- | Dependency rejection | Typed/rethrown error or failure event | Inspect structured details, preserve tracking id, and retry only when the operation is safe. |
350
- | Timeout or missing async completion | Timeout/recovery state | Follow the module-specific recovery path; never synthesize success. |
351
-
352
- ## Pitfalls
353
- - READY-time construction and `register()` are different lifecycle boundaries; moving collaborator creation into `register()` can duplicate listeners and use uninitialized host services.
354
- - AQM HTTP responses are acknowledgements, not operation completion; only a correlated WebSocket notification or timeout settles the operation.
355
- - Listener cleanup must use the same bound function identities registered during setup or repeated register/deregister cycles will leak handlers.
356
-
357
- ## Module Do's / Don'ts
358
- - DO construct the collaborator graph only after host READY and keep registration focused on listeners, subscription, and profile retrieval.
359
- - DO route agent recovery decisions through ContactCenter because it owns profile/config policy.
360
- - DON'T synthesize successful register/deregister results after a dependency or cleanup failure.
361
- - DON'T let transport services call `silentRelogin()` directly.
362
-
363
- ## Export Stability
364
- The npm export/type-declaration surface is semver-sensitive. Additive optional types are compatible; removals, renames, or semantic changes require a major-version migration and changelog entry.
365
-
366
- ## Host Integration & Theming
367
- The module registers as `cc` through the Webex SDK plugin system and depends on host-provided Webex credentials, configuration, request routing, and lifecycle events. It renders no UI and defines no theme contract.
368
-
369
- ## Key Design Trade-off
370
- - A single plugin surface centralizes compatibility and event routing, while specialized modules retain implementation ownership; this costs careful bootstrap and cleanup ordering.
371
-
372
- ## Test-Case Strategy (module)
373
- `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.
374
-
375
- | Requirement | Existing evidence | Required revalidation |
376
- |---|---|---|
377
- | CONTACT_CENTER-R-001 | `test/unit/spec/cc.ts` | READY-time ownership and initialization order |
378
- | CONTACT_CENTER-R-002 | `test/unit/spec/cc.ts` | register success/failure and log-upload path |
379
- | 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. |
380
- | CONTACT_CENTER-R-004 | `test/unit/spec/cc.ts` | listener/resource cleanup and error propagation |
381
- | CONTACT_CENTER-R-005 | `test/unit/spec/cc.ts` | relogin policy ownership |
382
- | 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. |
383
- | 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. |
384
- | 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. |
385
-
386
- ## Traceability
387
- - Repo architecture: `ARCHITECTURE.md` · Registry: `SPEC_INDEX.md`
388
- - Coverage state and contracts baseline: `../.sdd/manifest.json`
@@ -1,78 +0,0 @@
1
- # Contact Owner Change Refactor
2
-
3
- ## Scope
4
-
5
- This change refactors only the owner-change propagation introduced by
6
- webex-js-sdk PR #5187. It preserves the behavior required by Participant Drop:
7
- when the backend promotes a new primary Agent, existing SDK tasks publish the
8
- updated owner through the existing `task:hydrate` event so widgets immediately
9
- recompute the Primary label, icon, and Drop permission.
10
-
11
- There is no public API, routing-event, state-machine transition, Participant
12
- Drop request, or widget contract change.
13
-
14
- ## Retained behavior
15
-
16
- | Behavior | Why it remains | Existing-flow impact |
17
- |---|---|---|
18
- | Map an owner-changing `ContactUpdated` to `CONTACT_OWNER_CHANGED` | Remaining conference Agents receive `ContactUpdated`, not necessarily `ContactOwnerChanged`. The existing state-machine action synchronizes task data and emits `task:hydrate`. | Preserves immediate owner/Primary UI updates without adding a new public event or state transition. Same-owner and owner-less updates remain data-only. |
19
- | Resolve `ContactOwnerChanged` by exact ID before related IDs | Exact identity remains the safest and existing lookup contract. | Existing exact task routing is unchanged. |
20
- | Resolve one unique related task using nested interaction IDs, the collection key, or the `mainCall` media-map key | Some supported owner-change payloads identify the surviving call through a child top-level ID and omit `mainInteractionId`. | Preserves cross-channel promotion across the documented payload variants. Task aliases are deduplicated and ambiguous matches remain ignored. |
21
- | Accept current-Agent main-leg evidence from the existing task or authoritative incoming promotion | A local child task can be briefly stale when the owner-change payload first proves promotion. | Preserves the stale-snapshot fix while continuing to reject ordinary consult-only tasks. |
22
- | Recover a missing promoted-Agent task from a complete `ContactOwnerChanged` payload | Reloaded or desynchronized clients may receive the authoritative promotion before normal task creation catches up. Agent Desktop supports the same recovery path. | A complete telephony main-leg payload restores the task under the stable main interaction ID, emits one `task:hydrate`, and emits no synthetic `task:incoming`. |
23
- | Preserve a confirmed owner across a late `ParticipantLeftConference` snapshot that still names the departed owner | Participant Drop can deliver owner change and participant-left notifications in either order. | Prevents the Primary UI from reverting after it has already received the authoritative new owner. |
24
-
25
- ## Refactoring and safety constraints
26
-
27
- Owner-change correlation and recovery retain the following protections:
28
-
29
- - generic lifecycle-event correlation is unchanged; collection-key and media-key
30
- matching are enabled only for `ContactOwnerChanged`;
31
- - only a task selected by the related-interaction fallback may be re-keyed;
32
- - conflicting task/payload main IDs are ignored;
33
- - a stable main key already owned by a different Task causes the event to be
34
- ignored; and
35
- - an exact child task is never normalized over a distinct main task;
36
- - aliases of the same Task object are deduplicated before uniqueness is tested;
37
- - consult-only and ambiguous matches are rejected; and
38
- - missing-task recovery is rejected whenever any related task or canonical-key
39
- occupant already exists.
40
-
41
- This closes the PR review scenario where an exact child task could previously
42
- be normalized to a main key and silently replace the actual main Task, orphaning
43
- its listeners and resources.
44
-
45
- Recovery is intentionally narrow. It requires a non-terminal telephony payload,
46
- `interaction.owner` equal to the current Agent, an active participant entry for
47
- that Agent on an `mType: mainCall` leg, and a stable main interaction ID. It does
48
- not use `toOwner`, elect an owner locally, or create a task for a missing
49
- owner-changing `ContactUpdated` event.
50
-
51
- ## Resulting event flow
52
-
53
- 1. The backend chooses the new `interaction.owner`.
54
- 2. The promoted Agent receives `ContactOwnerChanged`; other surviving Agents may
55
- receive an owner-changing `ContactUpdated`.
56
- 3. TaskManager first uses an exact task match and otherwise accepts one unique,
57
- eligible related task.
58
- 4. If the promoted Agent has no related task, a complete authoritative payload
59
- may recover the task under its stable main interaction ID. An internal
60
- pre-listener `HYDRATE` restores the actor state without publishing an event.
61
- 5. Both notification forms use the existing `CONTACT_OWNER_CHANGED` state-machine
62
- event.
63
- 6. The state machine updates task/context data, keeps the current task state, and
64
- emits exactly one public `task:hydrate`.
65
- 7. Widget consumers receive the hydrated Task and render the backend-provided
66
- owner immediately.
67
-
68
- `ParticipantLeftConference` continues through its existing event/state-machine
69
- path. No client elects a successor and no Drop completion fabricates an owner.
70
-
71
- ## Verification coverage
72
-
73
- The focused TaskManager tests cover owner-changing versus data-only
74
- `ContactUpdated`, exact and child-keyed correlation, collection-key and
75
- `mainCall` media-key payloads, stale incoming promotion evidence, consult-only
76
- and ambiguous rejection, narrow missing-task recovery, listener/alias safety,
77
- later `AgentContact` and `ContactMerged` reuse, exact-child/main-task collision
78
- protection, and both owner-change/participant-left orders.