@webex/contact-center 3.12.0-next.124 → 3.12.0-next.126

package/.sdd/manifest.json

@@ -51,7 +51,7 @@
       "canonical_spec": "ai-docs/contact-center-spec.md",
       "contracts": {
         "provides": [
-          "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, and mapped EntryPoint records with optional numbers, exported user-preference request/response types, and preview-campaign methods acceptPreviewContact/skipPreviewContact/removePreviewContact",
+          "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, exported action constants/types, internally sourced action context, system-code, and primary notification event APIs",
           "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)",
           "BROWSER stationLogin payload: dialNumber and deviceId are webrtc-{agentId} (contact-center.station-login-browser-dn / AGENT-R-006); public stationLogin({loginOption: 'BROWSER'}) input unchanged"
         ],
@@ -96,7 +96,7 @@
       "canonical_spec": "src/metrics/ai-docs/metrics-spec.md",
       "contracts": {
         "provides": [
-          "MetricsManager timing, behavioral/operational/business event submission, taxonomy, queues, and tracking-field helpers"
+          "MetricsManager timing, behavioral/operational/business event submission, taxonomy, queues, tracking-field helpers, and operational Agent Wellness Break action/notification/system-code event names"
         ],
         "requires": [
           "Webex internal metrics service; Webex ready lifecycle; LoggerProxy; browser document visibility"
@@ -139,7 +139,7 @@
       "canonical_spec": "src/services/ai-docs/services-spec.md",
       "contracts": {
         "provides": [
-          "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"
+          "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"
         ],
         "requires": [
           "Core HTTP/WebSocket/AQM infrastructure; WCC APIs; @webex/calling; MetricsManager; PageCache"
@@ -224,10 +224,10 @@
       "canonical_spec": "src/services/config/ai-docs/config-spec.md",
       "contracts": {
         "provides": [
-          "Agent profile aggregation; config endpoint methods; CC event/type contracts; outdial ANI access"
+          "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"
         ],
         "requires": [
-          "WebexRequest; WCC organization, team, profile, aux-code, dial-plan, site, tenant, and URL-mapping APIs"
+          "WebexRequest; WCC organization, team, profile, AI-feature, aux-code, dial-plan, site, tenant, and URL-mapping APIs"
         ]
       },
       "section_profile": {

package/ai-docs/CONTRACTS.md

@@ -17,6 +17,7 @@
 | `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` |
 | `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` |
 | `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` |
+| `contact-center.agent-wellness-break` | Contact Center / Services / Config | `Profile.isWellnessBreakEnabled`, `requestWellnessBreak`, `respondToWellnessBreak`, `getWellbeingBreakIdleCode`, `WELLNESS_BREAK_NOTIFICATION_ACTIONS`, `WELLNESS_BREAK_USER_ACTIONS`, `WellnessBreakEvent` | Effective gate = backend-delivered `agentWellbeing.enable` + reminders `ENABLED` + `aiAssistantQuantity > 0`; public action unions derive from exported `as const` values. 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. | 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/ApiAiAssistant.ts` |
 
 ### Events
 
@@ -27,6 +28,7 @@
 | `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` |
 | `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` |
 | `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` |
+| `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` |
 
 ## Requires — what this repo depends on
 

package/ai-docs/SERVICE_STATE.md

@@ -10,6 +10,7 @@
 | `task:*` | publish | Task/TaskManager → application | `src/services/task/types.ts` |
 | `CC_EVENTS` | consume | WCC WebSocket → Core/ContactCenter/Task/AqmReqs | `src/services/config/types.ts` |
 | realtime transcript/suggestion | consume/publish | RTD WebSocket → owning Task | `src/services/task/TaskManager.ts` |
+| `Wellness_Break_Handler` | consume/publish | Primary data-notification WebSocket → ContactCenter → `CC_AGENT_EVENTS.WELLNESS_BREAK` | `src/cc.ts`, `src/types.ts` |
 
 ## Data Stores
 
@@ -42,6 +43,9 @@
 | `allowAutomatedRelogin` | silent relogin after recovery | config-defined | ContactCenter | replacement recovery contract exists |
 | `webRtcEnabled` / login option | browser calling path | remote profile | Config/WCC | remote contract removed |
 | task UI/config flags | task controls and operations | profile/config-defined | Task/Config | owning behavior removed |
+| `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 |
+
+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.
 
 ## Maintenance
 

package/ai-docs/contact-center-spec.md

@@ -11,8 +11,8 @@
 | Doc kind | Module spec |
 | Coverage score | Partial (manifest-authoritative); 15/15 required document fields present |
 | Generated from | `module-spec` @ SDLC template library `0.2.1` |
-| generated_by / approved_by / updated_at | Codex generator / developer-approved follow-up review remediation / 2026-08-21 |
-| Validation status | Follow-up validation passed (independent Claude fallback, 2026-07-21); 1 existing test-coverage gap; coverage remains Partial |
+| generated_by / approved_by / updated_at | Codex generator / developer-approved Agent Wellness Break remediation / 2026-09-07 |
+| 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 |
 
 ## Evidence Rules
 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.
@@ -39,6 +39,8 @@ The `@webex/contact-center` package is a Webex SDK plugin that provides a TypeSc
 
 - **Answer on Webex**: Accept, Decline, Mute, and DTMF for voice offers when the agent uses Webex App desktop calling (`enableWxBetterTogether`).
 
+- **Agent Wellness Break**: Effective enablement, agent/org-scoped notifications, active-session action reporting, system idle-code lookup, and legacy state transitions.
+
 ## Purpose / Responsibility
 Own the published Webex Contact Center SDK plugin surface, registration lifecycle, public method delegation, and application-facing event routing.
 
@@ -79,6 +81,7 @@ src/
 | `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` |
 | `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` |
 | `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` |
+| `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` |
 
 Compatibility notes:
 - Do not remove or reinterpret exported symbols/events without a documented consumer migration.
@@ -96,6 +99,9 @@ Compatibility notes:
 | 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 |
 | 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 |
 | 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 |
+| 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 |
+| CONTACT_CENTER-R-007 | When wellness is effectively enabled, route valid `Wellness_Break_Handler` messages from the primary 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 |
+| 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 the legacy pre-break state 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 |
 
 ## Design Overview
 `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.
@@ -104,6 +110,16 @@ Direct data/configuration and user-preference operations return authenticated RE
 
 Durable agent, task, and configuration records remain remote-system owned. The package owns only in-memory profile/task/listener/cache/connection state.
 
+### Agent Wellness Break
+
+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.
+
+After station login or relogin, ContactCenter retains the current agent-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.
+
+Wellness payloads are handled by ContactCenter on the primary 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.
+
+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, creates a session-scoped recovery marker before changing legacy state, 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.
+
 ### wxApp Better Together (WXCC-6026)
 
 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).
@@ -283,6 +299,7 @@ classDiagram
 - **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`.
 - **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`.
 - **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`.
+- **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/`.
 
 ## State Model
 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.
@@ -294,6 +311,9 @@ ContactCenter retains in-memory `agentConfig`, collaborator references, event li
 - ContactCenter owns automated relogin policy; ConnectionService owns transport-state detection/emission. Evidence: `src/cc.ts`, `src/services/core/websocket/connection-service.ts`.
 - Deregistration does not station-logout the agent. Evidence: `src/cc.ts`.
 - Published methods/types/events remain semver-sensitive through `src/index.ts`.
+- 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.
+- Wellness action unions derive from exported `as const` value objects; backend message-type and enablement sentinels use internal constants rather than duplicated literals.
+- 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.
 
 ## Concurrency & Reactive Flow
 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.
@@ -315,7 +335,7 @@ stateDiagram-v2
 ```
 
 ## Protocol / Wire Format
-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`.
+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 WebSocket carries Contact Center and legacy data-notification traffic, including `Wellness_Break_Handler`. 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`.
 
 ## Error Handling & Failure Modes
 | Condition | Signal (error/code/result) | Caller recovery |
@@ -353,6 +373,9 @@ The module registers as `cc` through the Webex SDK plugin system and depends on
 | 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. |
 | CONTACT_CENTER-R-004 | `test/unit/spec/cc.ts` | listener/resource cleanup and error propagation |
 | CONTACT_CENTER-R-005 | `test/unit/spec/cc.ts` | relogin policy ownership |
+| 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. |
+| CONTACT_CENTER-R-007 | `test/unit/spec/cc.ts`, `test/unit/spec/services/ApiAiAssistant.ts` | Wellness normalization on the primary notification socket, notification-session mismatch acceptance, invalid agent/org filtering, and active-session outbound validation. |
+| 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. |
 
 ## Traceability
 - Repo architecture: `ARCHITECTURE.md` · Registry: `SPEC_INDEX.md`

package/dist/cc.js

@@ -240,6 +240,16 @@ class ContactCenter extends _webexCore.WebexPlugin {
    * @private
    */
 
+  /** Current login/relogin session used for agent-scoped wellness validation. */
+
+  /** Registered-session cache for the system WellbeingBreak idle code. */
+
+  /** Registration generation that owns the wellness idle-code cache and in-flight lookups. */
+  wellnessRegistrationGeneration = 0;
+  updateWellnessSession(agentSessionId) {
+    this.currentAgentSessionId = agentSessionId;
+  }
+
   /**
    * API instance for managing Webex Contact Center entry points
    * Provides functionality to fetch entry points with caching support
@@ -375,7 +385,11 @@ class ContactCenter extends _webexCore.WebexPlugin {
       this.answerCallOnWebexService = new _AnswerCallOnWebexService.default(this.$webex);
       this.webexCrossClientService = new _WebexCrossClientService.default(this.$webex);
       this.wxAppTelephonyMercurySync = new _WxAppTelephonyMercurySync.default(this.$webex);
-      this.apiAIAssistant = new _ApiAiAssistant.ApiAIAssistant(this.$webex);
+      this.apiAIAssistant = new _ApiAiAssistant.ApiAIAssistant(this.$webex, () => ({
+        isWellnessBreakEnabled: this.agentConfig?.isWellnessBreakEnabled === true,
+        agentId: this.agentConfig?.agentId,
+        agentSessionId: this.currentAgentSessionId
+      }));
       this.metricsManager = _MetricsManager.default.getInstance({
         webex: this.$webex
       });
@@ -442,6 +456,72 @@ class ContactCenter extends _webexCore.WebexPlugin {
     // @ts-ignore
     this.trigger(_types4.TASK_EVENTS.TASK_CAMPAIGN_PREVIEW_RESERVATION, task);
   };
+  trackInvalidWellnessEvent(reason) {
+    this.metricsManager.trackEvent(_constants4.METRIC_EVENT_NAMES.AI_ASSISTANT_WELLNESS_EVENT_INVALID, {
+      reason
+    }, ['operational']);
+  }
+  normalizeWellnessBreakEvent(payload) {
+    if (this.agentConfig?.isWellnessBreakEnabled !== true) {
+      this.trackInvalidWellnessEvent('wellness_disabled');
+      return null;
+    }
+    const notificationData = (0, _Utils.isRecord)(payload.data) ? payload.data : null;
+    const notificationDetails = notificationData && (0, _Utils.isRecord)(notificationData.notifDetails) ? notificationData.notifDetails : null;
+    const sessionData = notificationData && (0, _Utils.isRecord)(notificationData.data) ? notificationData.data : null;
+    const actionEvent = notificationDetails?.actionEvent;
+    if (payload.type !== _constants.WELLNESS_BREAK_HANDLER || notificationData?.notifType !== _constants.WELLNESS_BREAK_HANDLER || typeof actionEvent !== 'string') {
+      this.trackInvalidWellnessEvent('malformed_wellness_event');
+      return null;
+    }
+    if (!Object.values(_types.WELLNESS_BREAK_NOTIFICATION_ACTIONS).includes(actionEvent)) {
+      this.trackInvalidWellnessEvent('unknown_wellness_action');
+      return null;
+    }
+    const agentId = notificationData.agentId;
+    const eventOrgId = notificationData.orgId;
+    const sessionOrgId = sessionData?.orgId;
+    const envelopeOrgId = payload.orgId;
+    const agentSessionId = sessionData?.agentSessionId;
+    const currentOrgId = this.$webex.credentials.getOrgId();
+    if (typeof agentId !== 'string' || typeof eventOrgId !== 'string' || typeof sessionOrgId !== 'string' || typeof envelopeOrgId !== 'string' || typeof agentSessionId !== 'string' || !agentId || !eventOrgId || !sessionOrgId || !envelopeOrgId || !agentSessionId) {
+      this.trackInvalidWellnessEvent('missing_wellness_identity');
+      return null;
+    }
+    if (agentId !== this.agentConfig?.agentId || eventOrgId !== currentOrgId || sessionOrgId !== currentOrgId || envelopeOrgId !== currentOrgId) {
+      this.trackInvalidWellnessEvent('mismatched_wellness_identity');
+      return null;
+    }
+    const interactionValue = sessionData.interactionId ?? sessionData.InteractionId;
+    const actionText = notificationDetails.actionText;
+    const trackingId = payload.trackingId;
+    return {
+      agentId,
+      orgId: currentOrgId,
+      agentSessionId,
+      actionEvent: actionEvent,
+      ...(typeof actionText === 'string' ? {
+        actionText
+      } : {}),
+      ...(typeof interactionValue === 'string' ? {
+        interactionId: interactionValue
+      } : {}),
+      ...(typeof trackingId === 'string' ? {
+        trackingId
+      } : {})
+    };
+  }
+  handleWellnessBreakWebsocketPayload(payload) {
+    if (payload.type !== _constants.WELLNESS_BREAK_HANDLER) {
+      return false;
+    }
+    const wellnessEvent = this.normalizeWellnessBreakEvent(payload);
+    if (wellnessEvent) {
+      // @ts-ignore - WebexPlugin emit is available at runtime but absent from its declaration.
+      this.emit(_types3.CC_EVENTS.WELLNESS_BREAK, wellnessEvent);
+    }
+    return true;
+  }
   handleRTDWebsocketMessage = event => {
     this.taskManager.handleRealtimeWebsocketEvent(event);
   };
@@ -496,6 +576,8 @@ class ContactCenter extends _webexCore.WebexPlugin {
    * ```
    */
   async register() {
+    this.wellnessRegistrationGeneration += 1;
+    this.wellbeingBreakIdleCode = undefined;
     _loggerProxy.default.log('Starting CC SDK registration', {
       module: _constants.CC_FILE,
       method: _constants.METHODS.REGISTER
@@ -562,6 +644,9 @@ class ContactCenter extends _webexCore.WebexPlugin {
    *
     */
   async deregister() {
+    this.wellnessRegistrationGeneration += 1;
+    this.wellbeingBreakIdleCode = undefined;
+    this.updateWellnessSession();
     try {
       this.metricsManager.timeEvent([_constants4.METRIC_EVENT_NAMES.WEBSOCKET_DEREGISTER_SUCCESS, _constants4.METRIC_EVENT_NAMES.WEBSOCKET_DEREGISTER_FAIL]);
       this.taskManager.off(_types4.TASK_EVENTS.TASK_INCOMING, this.handleIncomingTask);
@@ -601,7 +686,9 @@ class ContactCenter extends _webexCore.WebexPlugin {
       }
 
       // Clear any cached agent configuration
+      this.wellbeingBreakIdleCode = undefined;
       this.agentConfig = null;
+      this.updateWellnessSession();
       if (wxAppPublishError) {
         throw wxAppPublishError;
       }
@@ -748,6 +835,8 @@ class ContactCenter extends _webexCore.WebexPlugin {
       this.taskManager.setAgentId(this.agentConfig.agentId);
       this.taskManager.setWebRtcEnabled(this.agentConfig.webRtcEnabled);
       this.apiAIAssistant.setAIFeatureFlags(this.agentConfig.aiFeature);
+      this.wellbeingBreakIdleCode = undefined;
+      this.updateWellnessSession();
 
       /**
        * RTD websocket currently supports realtime transcripts and suggested responses.
@@ -803,6 +892,7 @@ class ContactCenter extends _webexCore.WebexPlugin {
       }
       return this.agentConfig;
     } catch (error) {
+      this.updateWellnessSession();
       _loggerProxy.default.error(`Error during register: ${error}`, {
         module: _constants.CC_FILE,
         method: _constants.METHODS.CONNECT_WEBSOCKET
@@ -891,6 +981,7 @@ class ContactCenter extends _webexCore.WebexPlugin {
         channelsMap,
         ...loginData
       } = resp.data;
+      this.updateWellnessSession(resp.data.agentSessionId);
       this.agentConfig.currentTeamId = resp.data.teamId;
       const response = {
         ...loginData,
@@ -978,6 +1069,7 @@ class ContactCenter extends _webexCore.WebexPlugin {
         this.webCallingService.deregisterWebCallingLine();
       }
       await this.teardownWxAppLocalState();
+      this.updateWellnessSession();
       _loggerProxy.default.log(`Agent station logout completed successfully`, {
         module: _constants.CC_FILE,
         method: _constants.METHODS.STATION_LOGOUT,
@@ -1098,6 +1190,63 @@ class ContactCenter extends _webexCore.WebexPlugin {
     }
   }
 
+  /**
+   * Returns the system-managed `WellbeingBreak` idle code for the current registration.
+   * The value is fetched outside Desktop Profile filtering and cached until deregistration.
+   * @returns The normalized system idle-code entity
+   * @throws Structured Contact Center error when wellness is disabled or the code is unavailable
+   * @example
+   * const idleCode = await webex.cc.getWellbeingBreakIdleCode();
+   * @public
+   */
+  async getWellbeingBreakIdleCode() {
+    const method = _constants.METHODS.GET_WELLBEING_BREAK_IDLE_CODE;
+    try {
+      if (!this.agentConfig?.isWellnessBreakEnabled) {
+        const validationError = new Error('WELLNESS_BREAK_NOT_ENABLED');
+        validationError.details = {
+          type: 'SDK_VALIDATION_ERROR',
+          orgId: this.$webex.credentials.getOrgId(),
+          trackingId: _constants.EMPTY_STRING,
+          data: {
+            reason: 'WELLNESS_BREAK_NOT_ENABLED'
+          }
+        };
+        throw validationError;
+      }
+      if (this.wellbeingBreakIdleCode) {
+        return this.wellbeingBreakIdleCode;
+      }
+      this.metricsManager.timeEvent([_constants4.METRIC_EVENT_NAMES.WELLBEING_BREAK_IDLE_CODE_FETCH_SUCCESS, _constants4.METRIC_EVENT_NAMES.WELLBEING_BREAK_IDLE_CODE_FETCH_FAILED]);
+      const registrationGeneration = this.wellnessRegistrationGeneration;
+      const orgId = this.$webex.credentials.getOrgId();
+      const idleCode = await this.services.config.getWellbeingBreakIdleCode(orgId);
+      if (registrationGeneration !== this.wellnessRegistrationGeneration || orgId !== this.$webex.credentials.getOrgId() || !this.agentConfig?.isWellnessBreakEnabled) {
+        const staleRegistrationError = new Error('WELLNESS_BREAK_REGISTRATION_CHANGED');
+        staleRegistrationError.details = {
+          type: 'SDK_VALIDATION_ERROR',
+          orgId,
+          trackingId: _constants.EMPTY_STRING,
+          data: {
+            reason: 'WELLNESS_BREAK_REGISTRATION_CHANGED'
+          }
+        };
+        throw staleRegistrationError;
+      }
+      this.wellbeingBreakIdleCode = idleCode;
+      this.metricsManager.trackEvent(_constants4.METRIC_EVENT_NAMES.WELLBEING_BREAK_IDLE_CODE_FETCH_SUCCESS, {}, ['operational']);
+      return idleCode;
+    } catch (error) {
+      this.metricsManager.trackEvent(_constants4.METRIC_EVENT_NAMES.WELLBEING_BREAK_IDLE_CODE_FETCH_FAILED, {
+        reason: error instanceof Error ? error.message : _constants.UNKNOWN_ERROR
+      }, ['operational']);
+      const {
+        error: detailedError
+      } = (0, _Utils.getErrorDetails)(error, method, _constants.CC_FILE);
+      throw detailedError;
+    }
+  }
+
   /**
    * Processes incoming websocket messages and emits corresponding events
    * Handles various event types including agent state changes, login events,
@@ -1131,8 +1280,14 @@ class ContactCenter extends _webexCore.WebexPlugin {
       };
       this.metricsManager.trackEvent(_constants4.METRIC_EVENT_NAMES.WEBSOCKET_EVENT_RECEIVED, metricsPayload, ['operational']);
     }
+    if (this.handleWellnessBreakWebsocketPayload(eventData)) {
+      return;
+    }
     switch (eventData.type) {
       case _types3.CC_EVENTS.AGENT_MULTI_LOGIN:
+        if (eventData.data?.type === 'AgentMultiLoginCloseSession' && (!eventData.data.agentSessionId || eventData.data.agentSessionId === this.currentAgentSessionId)) {
+          this.updateWellnessSession();
+        }
         // @ts-ignore
         this.emit(_types2.AGENT_EVENTS.AGENT_MULTI_LOGIN, eventData.data);
         break;
@@ -1153,6 +1308,7 @@ class ContactCenter extends _webexCore.WebexPlugin {
             channelsMap,
             ...loginData
           } = eventData.data;
+          this.updateWellnessSession(loginData.agentSessionId);
           const stationLoginData = {
             ...loginData,
             mmProfile: {
@@ -1174,6 +1330,7 @@ class ContactCenter extends _webexCore.WebexPlugin {
             channelsMap,
             ...loginData
           } = eventData.data;
+          this.updateWellnessSession(loginData.agentSessionId);
           const stationReLoginData = {
             ...loginData,
             mmProfile: {
@@ -1186,8 +1343,8 @@ class ContactCenter extends _webexCore.WebexPlugin {
           };
           // @ts-ignore
           this.emit(_types2.AGENT_EVENTS.AGENT_RELOGIN_SUCCESS, stationReLoginData);
+          break;
         }
-        break;
       case _types3.CC_EVENTS.AGENT_STATE_CHANGE_SUCCESS:
         // @ts-ignore
         this.emit(_types2.AGENT_EVENTS.AGENT_STATE_CHANGE_SUCCESS, eventData.data);
@@ -1201,6 +1358,9 @@ class ContactCenter extends _webexCore.WebexPlugin {
         this.emit(_types2.AGENT_EVENTS.AGENT_STATION_LOGIN_FAILED, eventData.data);
         break;
       case _types3.CC_EVENTS.AGENT_LOGOUT_SUCCESS:
+        if (!eventData.data.agentSessionId || eventData.data.agentSessionId === this.currentAgentSessionId) {
+          this.updateWellnessSession();
+        }
         // @ts-ignore
         this.emit(_types2.AGENT_EVENTS.AGENT_LOGOUT_SUCCESS, eventData.data);
         break;
@@ -1759,6 +1919,7 @@ class ContactCenter extends _webexCore.WebexPlugin {
     });
     try {
       const reLoginResponse = await this.services.agent.reload();
+      this.updateWellnessSession(reLoginResponse.data.agentSessionId);
       const {
         agentId,
         lastStateChangeReason,