@webex/contact-center 3.12.0-llmrefactor.11 → 3.12.0-llmrefactor.13

package/src/services/ApiAiAssistant.ts

@@ -12,6 +12,10 @@ import {
   HistoricTranscriptsResponse,
   RealTimeAssistanceParams,
   RealTimeAssistanceUserActionParams,
+  RespondToWellnessBreakParams,
+  WellnessBreakUserAction,
+  WELLNESS_BREAK_USER_ACTIONS,
+  GenericError,
 } from '../types';
 import {getErrorDetails} from './core/Utils';
 import {
@@ -22,6 +26,12 @@ import {
 } from './constants';
 import {AIFeatureFlags} from './config/types';
 
+type WellnessBreakContextProvider = () => {
+  isWellnessBreakEnabled: boolean;
+  agentId?: string;
+  agentSessionId?: string;
+};
+
 /**
  * ApiAIAssistant provides AI Assistant APIs for transcript controls.
  * @public
@@ -30,9 +40,23 @@ export class ApiAIAssistant {
   private webex: WebexSDK;
   private metricsManager: MetricsManager;
   private aiFeature: AIFeatureFlags;
+  private readonly wellnessContextProvider?: WellnessBreakContextProvider;
+
+  private createWellnessError(reason: string): GenericError {
+    const error = new Error(reason) as GenericError;
+    error.details = {
+      type: 'SDK_VALIDATION_ERROR',
+      orgId: this.webex.credentials.getOrgId(),
+      trackingId: '',
+      data: {reason},
+    };
+
+    return error;
+  }
 
-  constructor(webex: WebexSDK) {
+  constructor(webex: WebexSDK, wellnessContextProvider?: WellnessBreakContextProvider) {
     this.webex = webex;
+    this.wellnessContextProvider = wellnessContextProvider;
     this.metricsManager = MetricsManager.getInstance({webex});
   }
 
@@ -40,6 +64,134 @@ export class ApiAIAssistant {
     this.aiFeature = aiFeature;
   }
 
+  private async sendWellnessBreakAction(
+    action: WellnessBreakUserAction,
+    method: string
+  ): Promise<void> {
+    this.metricsManager.timeEvent([
+      METRIC_EVENT_NAMES.AI_ASSISTANT_WELLNESS_ACTION_ACCEPTED,
+      METRIC_EVENT_NAMES.AI_ASSISTANT_WELLNESS_ACTION_FAILED,
+    ]);
+
+    try {
+      const context = this.wellnessContextProvider?.();
+      const agentId = context?.agentId?.trim();
+      const agentSessionId = context?.agentSessionId?.trim();
+      const orgId = this.webex.credentials.getOrgId()?.trim();
+
+      if (context?.isWellnessBreakEnabled !== true) {
+        throw this.createWellnessError('WELLNESS_BREAK_NOT_ENABLED');
+      }
+      if (!orgId) {
+        throw this.createWellnessError('WELLNESS_BREAK_ORG_ID_REQUIRED');
+      }
+      if (!agentId) {
+        throw this.createWellnessError('WELLNESS_BREAK_AGENT_ID_REQUIRED');
+      }
+      if (!agentSessionId) {
+        throw this.createWellnessError('WELLNESS_BREAK_AGENT_SESSION_REQUIRED');
+      }
+
+      const baseUrl = this.getBaseUrl();
+      const response = (await this.webex.request({
+        uri: `${baseUrl}${AI_ASSISTANT_API_URLS.EVENT}`,
+        method: HTTP_METHODS.POST,
+        addAuthHeader: true,
+        body: {
+          agentId,
+          orgId,
+          eventType: AIAssistantEventType.CUSTOM_EVENT,
+          eventName: AIAssistantEventName.WELLNESS_BREAK_ACTION,
+          eventDetails: {
+            data: {
+              action,
+              agentSessionId,
+              actionTimeStamp: Date.now(),
+            },
+          },
+        },
+      })) as IHttpResponse;
+
+      if (response.statusCode !== 202) {
+        throw this.createWellnessError(
+          `WELLNESS_BREAK_ACTION_UNEXPECTED_STATUS_${response.statusCode}`
+        );
+      }
+
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.AI_ASSISTANT_WELLNESS_ACTION_ACCEPTED,
+        {action},
+        ['operational']
+      );
+      LoggerProxy.log('Wellness action accepted by AI Assistant', {
+        module: CC_FILE,
+        method,
+        data: {action},
+      });
+    } catch (error) {
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.AI_ASSISTANT_WELLNESS_ACTION_FAILED,
+        {
+          action,
+          error: error instanceof Error ? error.message : String(error),
+        },
+        ['operational']
+      );
+      const {error: detailedError} = getErrorDetails(error, method, CC_FILE);
+      throw detailedError;
+    }
+  }
+
+  /**
+   * Requests an Agent Wellness Break.
+   * The promise resolves when the HTTP request is accepted with status 202; the later
+   * approval or denial is delivered independently through a wellness notification.
+   * @returns A promise that resolves with no value after HTTP acceptance
+   * @throws Structured Contact Center error when disabled, stale, invalid, or delivery fails
+   * @example
+   * await webex.cc.apiAIAssistant.requestWellnessBreak();
+   * @public
+   */
+  public async requestWellnessBreak(): Promise<void> {
+    return this.sendWellnessBreakAction(
+      WELLNESS_BREAK_USER_ACTIONS.REQUESTED,
+      METHODS.REQUEST_WELLNESS_BREAK
+    );
+  }
+
+  /**
+   * Responds to a backend-provided Agent Wellness Break offer.
+   * The promise resolves when the HTTP request is accepted with status 202 and does not
+   * wait for a WebSocket completion event.
+   * @param params - ACCEPTED, REJECTED, or NO_RESPONSE
+   * @returns A promise that resolves with no value after HTTP acceptance
+   * @throws Structured Contact Center error when disabled, stale, invalid, or delivery fails
+   * @example
+   * await webex.cc.apiAIAssistant.respondToWellnessBreak({
+   *   action: WELLNESS_BREAK_USER_ACTIONS.ACCEPTED,
+   * });
+   * @public
+   */
+  public async respondToWellnessBreak(params: RespondToWellnessBreakParams): Promise<void> {
+    const {action} = params;
+    if (
+      ![
+        WELLNESS_BREAK_USER_ACTIONS.ACCEPTED,
+        WELLNESS_BREAK_USER_ACTIONS.REJECTED,
+        WELLNESS_BREAK_USER_ACTIONS.NO_RESPONSE,
+      ].includes(action)
+    ) {
+      const {error} = getErrorDetails(
+        this.createWellnessError('WELLNESS_BREAK_ACTION_INVALID'),
+        METHODS.RESPOND_TO_WELLNESS_BREAK,
+        CC_FILE
+      );
+      throw error;
+    }
+
+    return this.sendWellnessBreakAction(action, METHODS.RESPOND_TO_WELLNESS_BREAK);
+  }
+
   private getBaseUrl(): string {
     const wccApiGatewayUrl = this.webex.internal.services.get(WCC_API_GATEWAY) || '';
 

package/src/services/ai-docs/services-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-07-21 |
-| Validation status | Follow-up validation passed (independent Claude fallback, 2026-07-21); coverage remains Partial |
+| generated_by / approved_by / updated_at | Codex generator / Agent Wellness Break v0.4 intake audit / 2026-09-07 |
+| Validation status | Agent Wellness Break v0.4 delta 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.
@@ -55,6 +55,7 @@ The `src/services/` directory is the service layer of the `@webex/contact-center
 | **Utilities** | [`src/utils/PageCache.ts`](../../utils/PageCache.ts) | Shared `PageCache<T>` generic class for pagination caching, plus `BaseSearchParams`, `PaginatedResponse`, and `PaginationMeta` types used by all data services |
 | **WebRTC Calling** | [`WebCallingService.ts`](../WebCallingService.ts) | Browser-based voice calling via `@webex/calling`, line registration, call answer/mute/decline |
 | **WxApp Better Together** | [`WebexCrossClientService.ts`](../WebexCrossClientService.ts), [`AnswerCallOnWebexService.ts`](../AnswerCallOnWebexService.ts), [`WxAppTelephonyMercurySync.ts`](../WxAppTelephonyMercurySync.ts) | usersub cross-client publish (`answer-calls-on-wxcc`), Hydra telephony REST (answer/reject/mute/DTMF/GET call), Mercury mute sync — orchestrated from `cc.ts` when `enableWxBetterTogether` is active |
+| **AI Assistant / Wellness** | [`ApiAiAssistant.ts`](../ApiAiAssistant.ts) | Existing transcript/suggestion requests plus direct, session-validated wellness custom-event reporting. |
 
 Each service folder contains its own `ai-docs/` with detailed documentation. **Always load the relevant service docs before making changes.**
 
@@ -230,6 +231,7 @@ Use [`constants.ts`](../constants.ts) as the canonical source for service-level
 | `services.surface` | SDK / event / internal API | Internal `Services.getInstance()` composition root plus data-service and calling collaborators consumed by `ContactCenter`. | Stable module consumption boundary. | Additive changes by default; breaking package exports require a major-version transition. | `src/services/index.ts` | `../../../ai-docs/CONTRACTS.md` |
 | `services.destination-lists` | SDK data API | Existing `Queue.getQueues(ContactServiceQueueSearchParams)` and `EntryPoint.getEntryPoints(EntryPointSearchParams)` methods with full-record paginated responses. | Apply consult/transfer telephony eligibility, profile views, and backend name ordering as overridable defaults. | Behavioral default correction on existing methods; no specialized method, projected response, or replacement signature. | `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/types.ts` | `../../../ai-docs/CONTRACTS.md` |
 | `services.user-preference` | SDK data API | `UserPreference` and `cc.userPreference`. | Direct REST CRUD for user preferences; separate from PageCache-based pagination services. | Additive semver-public API; removals or signature changes are breaking. | `src/services/UserPreference.ts`, `src/services/config/types.ts` | `../../../ai-docs/CONTRACTS.md` |
+| `services.agent-wellness-break` | SDK data / action API | `ApiAIAssistant.requestWellnessBreak` and `respondToWellnessBreak`, invoked through `ContactCenter`. | Submit validated `WellnessBreakAction` custom events through direct HTTP. | Additive semver-public behavior; exact action/event payload is backend-owned. | `src/services/ApiAiAssistant.ts`, `src/types.ts` | `../../../ai-docs/CONTRACTS.md` |
 
 Compatibility notes:
 - Do not remove or reinterpret exported symbols/events without a documented consumer migration.
@@ -264,6 +266,7 @@ ContactCenter READY callback
 | SERVICES-R-005 | Inherit authenticated request identity from the host Webex SDK through Core/WebexRequest; Services must not store, parse, or refresh credentials. | One host-owned authentication boundary avoids duplicate token handling and credential leakage across composed services. | `src/services/index.ts`, `src/services/core/WebexRequest.ts` | `test/unit/spec/services/core/WebexRequest.ts` | None; authentication ownership is explicit. | PRESENT |
 | SERVICES-R-006 | Treat Services composition as unconditionally created by the ContactCenter READY callback; Services owns no rollout or feature-flag decision. | Capability flags belong to the consuming config/task/calling collaborators, so the composition root must not silently gate construction. | `src/services/index.ts`, `src/cc.ts` | `test/unit/spec/cc.ts` | None; rollout applicability is explicitly N/A for Services. | PRESENT |
 | SERVICES-R-007 | Existing Queue and EntryPoint list methods must apply inbound, active, telephony, profile/agent-view, and `name,ASC` defaults while retaining their established parameter and full-record response types. Caller-supplied existing filter, sort, or profile inputs override defaults. Queue must also treat `sortOrder` without `sortBy` as a name sort and bypass the simple-page cache. | Defaults on the established methods let thin consumers request lists without a parallel API, while existing parameters preserve specialized behavior for other consumers and full-record types remain truthful because no field projection is requested. | `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/types.ts` | `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts`, `test/unit/spec/cc.ts` | The backend honors the view flags and combined CMS sort value. | PRESENT |
+| SERVICES-R-008 | ApiAIAssistant wellness requests must accept no public identity or context-mutating input, read effective enablement and non-empty SDK-owned organization/agent/session context from a read-only provider supplied at construction, then POST the exact `WellnessBreakAction` custom-event body directly to `/event`; only HTTP 202 resolves successfully. Public action unions derive from exported `as const` action-value objects. | SDK-owned live context prevents callers from supplying stale/different login identities to action calls, one value/type source prevents wire drift, and direct HTTP matches the AI event endpoint rather than AQM completion semantics. | `src/services/ApiAiAssistant.ts`, `src/types.ts`, `src/index.ts`, `src/cc.ts` | `test/unit/spec/services/ApiAiAssistant.ts`, `test/unit/spec/cc.ts` | None. | PRESENT |
 
 ## Design Overview
 `Services` is a singleton composition root for transport-facing capabilities only. It constructs two `WebSocketManager` instances (primary Contact Center and RTD), creates `AqmReqs` on the primary manager, then creates config, agent, contact, dialer, and ConnectionService collaborators.
@@ -272,6 +275,8 @@ ContactCenter owns the broader READY-time graph: WebCallingService, ApiAIAssista
 
 AQM factories return functions whose HTTP request is initiation and whose promise settles on correlated primary-WebSocket notifications. Direct config/data services return authenticated REST responses.
 
+ApiAIAssistant wellness reporting is also direct REST, but it reads live context through a read-only provider supplied by ContactCenter at construction rather than a separate factory or context setter. It fails closed unless wellness is effectively enabled and the SDK owns a current organization, agent, and session; public action calls do not accept identity fields.
+
 ## Data Flow
 ```mermaid
 flowchart TD
@@ -399,6 +404,7 @@ classDiagram
 - **UC-2 Direct REST:** configuration, data, and user-preference services return authenticated HTTP results directly. Evidence: `src/services/config/index.ts`, `src/services/UserPreference.ts`, `test/unit/spec/services/config/index.ts`, `test/unit/spec/services/UserPreference.ts`.
 - **UC-3 AQM operation:** initiate HTTP and settle only on matching WebSocket notification or timeout. Evidence: `src/services/core/aqm-reqs.ts`, `test/unit/spec/services/core/aqm-reqs.ts`.
 - **UC-4 Task/AI realtime:** TaskManager consumes primary and RTD streams with ApiAIAssistant/calling collaborators. Evidence: `src/services/task/TaskManager.ts`, `test/unit/spec/services/task/TaskManager.ts`.
+- **UC-5 Wellness action reporting:** validate the current profile/session context and submit a direct AI custom event that completes only on HTTP 202. Evidence: `src/services/ApiAiAssistant.ts`, `test/unit/spec/services/ApiAiAssistant.ts`.
 
 ## State Model
 `Services` is a process-local singleton. Its first `getInstance({webex, connectionConfig})` call synchronously constructs the two WebSocket managers, AqmReqs-backed factories, config service, and ConnectionService; later calls return that same composed graph. Socket lifecycle and domain records are owned by the corresponding collaborators, not by a Services state machine.
@@ -409,6 +415,7 @@ classDiagram
 - ApiAIAssistant, TaskManager, and UserPreference are READY-time ContactCenter collaborators, not fields constructed by Services.
 - Authentication is inherited from the host SDK through Core/WebexRequest; Services owns no credential lifecycle.
 - Rollout applicability is N/A for the Services composition root: it is created at READY and does not evaluate a feature flag.
+- ApiAIAssistant evaluates the current effective wellness flag and identities through its constructor-supplied read-only provider; the public object exposes no context mutator, and the Services singleton itself remains unconditionally composed.
 
 ## Concurrency & Reactive Flow
 - `getInstance` composition is synchronous in the JavaScript execution turn. Direct REST promises can proceed independently, while each AQM promise remains pending until its matching primary-WebSocket notification, HTTP failure, or timeout.
@@ -447,7 +454,7 @@ stateDiagram-v2
 ```
 
 ## Protocol / Wire Format
-- Request, response, and event payload ownership is anchored in `src/services/index.ts`. HTTP initiates backend work where applicable; WebSocket messages provide realtime events and, for AQM flows, correlated completion.
+- Request, response, and event payload ownership is anchored in `src/services/index.ts`. HTTP initiates backend work where applicable; WebSocket messages provide realtime events and, for AQM flows, correlated completion. Wellness actions POST `CUSTOM_EVENT` / `WellnessBreakAction` bodies directly to `/event` and accept only status 202; wellness offers arrive as primary `Wellness_Break_Handler` notifications.
 
 ## Error Handling & Failure Modes
 | Condition | Signal (error/code/result) | Caller recovery |
@@ -481,6 +488,7 @@ Unit tests mirror module paths under `test/unit/spec/services`. Preserve positiv
 | `SERVICES-R-005` | `test/unit/spec/services/core/WebexRequest.ts` | None. |
 | `SERVICES-R-006` | `test/unit/spec/cc.ts` | None. |
 | `SERVICES-R-007` | `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts`, `test/unit/spec/cc.ts` | None. |
+| `SERVICES-R-008` | `test/unit/spec/services/ApiAiAssistant.ts` | None. |
 
 ## Traceability
 - Repo architecture: `../../../ai-docs/ARCHITECTURE.md` · Registry: `../../../ai-docs/SPEC_INDEX.md`

package/src/services/config/Util.ts

@@ -1,4 +1,5 @@
 import {LOST_CONNECTION_RECOVERY_TIMEOUT} from '../core/constants';
+import {WELLNESS_BREAK_REMINDERS_ENABLED} from './constants';
 import {
   AgentResponse,
   AuxCode,
@@ -186,6 +187,10 @@ function parseAgentConfigs(profileData: {
   const defaultWrapUpData = getDefaultWrapUpCode(wrapupCodes);
   const aiFeature: AIFeatureFlags | undefined =
     aiFeatureFlags?.data?.length > 0 ? aiFeatureFlags.data[0] : undefined;
+  const isWellnessConfigured =
+    aiFeature?.agentWellbeing?.enable === true &&
+    aiFeature.agentWellbeing.wellnessBreakReminders === WELLNESS_BREAK_REMINDERS_ENABLED;
+  const hasAIAssistantLicense = (orgSettingsData.aiAssistantQuantity ?? 0) > 0;
 
   const finalData = {
     teams: teamData,
@@ -264,6 +269,7 @@ function parseAgentConfigs(profileData: {
     lostConnectionRecoveryTimeout:
       tenantData.lostConnectionRecoveryTimeout || LOST_CONNECTION_RECOVERY_TIMEOUT,
     aiFeature,
+    isWellnessBreakEnabled: isWellnessConfigured && hasAIAssistantLicense,
   };
 
   return finalData;

package/src/services/config/ai-docs/config-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-07-21 |
-| Validation status | Follow-up validation passed (independent Claude fallback, 2026-07-21); coverage remains Partial |
+| generated_by / approved_by / updated_at | Codex generator / developer-approved Agent Wellness Break delta / 2026-09-02 |
+| Validation status | Agent Wellness Break v0.4 delta 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.
@@ -100,6 +100,8 @@ services/config/
 | Organization masking | `OrgSettings.maskSensitiveData` | `src/services/config/types.ts`, `src/services/config/Util.ts` |
 | Auxiliary-code list URL | includes `desktopProfileFilter=true` | `src/services/config/constants.ts` |
 | Outdial ANI entries | public wrapper through ContactCenter | `src/services/config/index.ts`, `src/cc.ts` |
+| `Profile.isWellnessBreakEnabled` | required effective flag derived from backend AI feature configuration and organization license quantity | `src/services/config/Util.ts`, `src/services/config/types.ts` |
+| `getWellbeingBreakIdleCode(orgId)` | paginated exact lookup for the active system idle code named `WellbeingBreak`, exposed and registration-cached by ContactCenter | `src/services/config/index.ts`, `src/services/config/constants.ts`, `src/cc.ts` |
 
 The service has no `TeamList.channelMap` contract. Exact package exports are indexed in root `CONTRACTS.md`.
 
@@ -116,6 +118,8 @@ The service has no `TeamList.channelMap` contract. Exact package exports are ind
 | CONFIG-R-003 | Paginate teams and auxiliary codes until completion and include `desktopProfileFilter=true` for auxiliary-code requests. | A partial or unfiltered set yields invalid profile/team/auxiliary choices. | `src/services/config/constants.ts` | `test/unit/spec/services/config/index.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
 | CONFIG-R-004 | Expose current response/field names: `MultimediaProfileResponse`, `OrgSettings.maskSensitiveData`, and real TeamList fields only. | Type-name drift causes invalid consumer code and incorrect privacy behavior. | `src/services/config/types.ts` | `test/unit/spec/services/config/index.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
 | CONFIG-R-005 | Reject the entire profile aggregation when any required dependent request fails. | Consumers must never receive an internally inconsistent partial Profile. | `src/services/config/index.ts` | `test/unit/spec/services/config/index.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
+| CONFIG-R-006 | Always populate `Profile.isWellnessBreakEnabled`; set it true only when `agentWellbeing.enable` is true, `wellnessBreakReminders` is `ENABLED`, and `OrgSettings.aiAssistantQuantity` is greater than zero. Missing or null inputs fail closed. | Hosts need one license-and-server-rollout-aware signal rather than reconstructing partial configuration. | `src/services/config/Util.ts`, `src/services/config/types.ts` | `test/unit/spec/services/config/Util.ts` | The supported SDK contracts expose no separate rollout response field; backend delivery of enabled `agentWellbeing` configuration is the rollout decision. | PRESENT |
+| CONFIG-R-007 | Retrieve the wellness idle code from `/v2/auxiliary-code` using `workType=IDLE_CODE`, `customFilter=isSystemCode==true`, and `desktopProfileFilter=false`; follow pagination and accept only the exact active system code name `WellbeingBreak`. | The dedicated state must be independent of desktop-profile filtering and must never fall back to a similarly named or non-system code. | `src/services/config/index.ts`, `src/services/config/constants.ts` | `test/unit/spec/services/config/index.ts` | None. | PRESENT |
 
 ## Design Overview
 Config separates its stable consumption boundary from collaborators so ownership and failure behavior stay explicit. Profile creation is all-or-nothing across dependent API calls so consumers never receive internally inconsistent partial configuration.
@@ -162,6 +166,7 @@ The AgentProfile is defined as the [`Profile`](../types.ts) type. This is not an
 | `accessQueue` | `'ALL' \| 'SPECIFIC' \| 'NONE'` | Collaboration tab queue access scope from Desktop Profile |
 | `accessEntryPoint` | `'ALL' \| 'SPECIFIC' \| 'NONE'` | Collaboration tab entry-point access scope from Desktop Profile |
 | `accessBuddyTeam` | `'ALL' \| 'SPECIFIC' \| 'NONE'` | Collaboration tab buddy-team access scope from Desktop Profile |
+| `isWellnessBreakEnabled` | boolean | Effective wellness gate derived from backend enablement/reminder configuration and positive AI Assistant license quantity |
 
 `parseAgentConfigs()` maps the three `access*` fields from `DesktopProfileResponse` onto the public `Profile` returned by `cc.register()`.
 
@@ -264,7 +269,7 @@ The service fetches data from multiple APIs with these response structures:
 | `getTenantData` | `TenantData` | `outdialEnabled`, `forceDefaultDn`, `privacyShieldVisible`, `timeoutDesktopInactivityEnabled` | Tenant-level feature flags |
 | `getOrgInfo` | `OrgInfo` | `tenantId`, `timezone` | Organization metadata |
 | `getAllAuxCodes` | `AuxCode[]` | `id`, `name`, `workTypeCode`, `active`, `isSystemCode`, `defaultCode` | Auxiliary codes for idle/wrap-up states |
-| `getOrganizationSetting` | `OrgSettings` | `webRtcEnabled`, `maskSensitiveData`, `campaignManagerEnabled` | Organization-level feature flags |
+| `getOrganizationSetting` | `OrgSettings` | `webRtcEnabled`, `maskSensitiveData`, `campaignManagerEnabled`, `aiAssistantQuantity` | Organization-level feature flags and AI Assistant license quantity |
 | `getDialPlanData` | `DialPlanEntity[]` | `id`, `name`, `regularExpression`, `prefix`, `strippedChars` | Dial plan rules for outbound calling |
 | `getURLMapping` | `URLMapping[]` | `name`, `url` | External service URL mappings |
 | `getSiteInfo` | `SiteInfo` | Site-specific configuration | Site details |
@@ -449,11 +454,14 @@ classDiagram
 - **UC-2 Paginated teams/aux codes:** follow backend page metadata to completion; auxiliary-code requests include `desktopProfileFilter=true`. Evidence: `src/services/config/index.ts`, `test/unit/spec/services/config/index.ts`.
 - **UC-3 Dial plan and URL mapping:** request dial-plan data only when the desktop profile enables it while always including URL mapping in profile aggregation. Evidence: `src/services/config/index.ts`, `test/unit/spec/services/config/index.ts`.
 - **UC-4 Outdial ANI retrieval:** return the organization-scoped ANI list through authenticated WebexRequest and propagate failures without a partial substitute. Evidence: `src/services/config/index.ts`, `test/unit/spec/services/config/index.ts`.
+- **UC-5 Wellness configuration:** produce one fail-closed effective profile flag and retrieve the exact system wellness idle code across pages. Evidence: `src/services/config/Util.ts`, `src/services/config/index.ts`, `test/unit/spec/services/config/Util.ts`, `test/unit/spec/services/config/index.ts`.
 
 ## Business Rules & Invariants
 - `getAgentConfig` rejects when any required dependent request rejects; it never returns a partial Profile.
 - `Profile.aiFeature` is derived from the AI-feature response, and sensitive-data masking uses the real `maskSensitiveData` field.
 - Team data has no `channelMap` contract; multimedia profile responses use `MultimediaProfileResponse`.
+- `isWellnessBreakEnabled` is always boolean and defaults false when any gate is absent, disabled, or unlicensed.
+- The system wellness code lookup is separate from profile auxiliary-code aggregation and uses `desktopProfileFilter=false`.
 
 ## Concurrency & Reactive Flow
 - The initial user lookup supplies identifiers for a ten-promise `Promise.all`; pagination loops await pages in order and stop from returned metadata.
@@ -465,6 +473,7 @@ All Config operations are authenticated REST calls through WebexRequest. Importa
 |---|---|
 | AI feature flags | `organization/{orgId}/v2/ai-feature?page=0&pageSize=100` |
 | Auxiliary codes | pagination/filter/attributes plus `desktopProfileFilter=true` |
+| Wellness system idle code | `organization/{orgId}/v2/auxiliary-code?page={page}&pageSize={pageSize}&workType=IDLE_CODE&customFilter=isSystemCode==true&desktopProfileFilter=false` |
 | Multimedia profile | organization-scoped multimedia-profile resource |
 | Dial plan | organization-scoped dial-plan resource when desktop profile enables it |
 
@@ -653,6 +662,8 @@ public async getUserUsingCI(orgId: string, agentId: string): Promise<AgentRespon
 | `CONFIG-R-003` | `test/unit/spec/services/config/index.ts` | None. |
 | `CONFIG-R-004` | `test/unit/spec/services/config/index.ts` | None. |
 | `CONFIG-R-005` | `test/unit/spec/services/config/index.ts` | Keep an explicit rejection assertion for each required dependency category. |
+| `CONFIG-R-006` | `test/unit/spec/services/config/Util.ts` | None. |
+| `CONFIG-R-007` | `test/unit/spec/services/config/index.ts` | None. |
 
 ## Traceability
 - Repo architecture: `../../../../ai-docs/ARCHITECTURE.md` · Registry: `../../../../ai-docs/SPEC_INDEX.md`

package/src/services/config/constants.ts

@@ -34,6 +34,12 @@ export const AGENT_STATE_AVAILABLE_ID = '0';
  */
 export const AGENT_STATE_AVAILABLE = 'Available';
 
+/** System idle-code name reserved for Agent Wellness Break. */
+export const WELLBEING_BREAK_IDLE_CODE = 'WellbeingBreak';
+
+/** Backend sentinel indicating wellness-break reminders are enabled. @internal */
+export const WELLNESS_BREAK_REMINDERS_ENABLED = 'ENABLED';
+
 /**
  * Description for the 'Available' agent state.
  * @type {string}
@@ -75,6 +81,7 @@ export const METHODS = {
   GET_URL_MAPPING: 'getURLMapping',
   GET_DIAL_PLAN_DATA: 'getDialPlanData',
   GET_AI_FEATURE_FLAGS: 'getAIFeatureFlags',
+  GET_WELLBEING_BREAK_IDLE_CODE: 'getWellbeingBreakIdleCode',
   GET_QUEUES: 'getQueues',
 
   // Util methods
@@ -175,6 +182,11 @@ export const endPointMap = {
       filter && filter.length > 0 ? `&filter=id=in=(${filter})` : ''
     }&attributes=${attributes}&desktopProfileFilter=true`,
 
+  /** Lists system idle codes without applying the agent Desktop Profile filter. */
+  systemIdleCodes: (orgId: string, page: number, pageSize: number) =>
+    `organization/${orgId}/v2/auxiliary-code?page=${page}&pageSize=${pageSize}` +
+    '&workType=IDLE_CODE&customFilter=isSystemCode==true&desktopProfileFilter=false',
+
   /**
    * Gets the endpoint for organization info.
    * @param orgId - Organization ID.

package/src/services/config/index.ts

@@ -23,6 +23,7 @@ import {
   OutdialAniEntriesResponse,
   OutdialAniParams,
   AIFeatureFlagsResponse,
+  Entity,
 } from './types';
 import WebexRequest from '../core/WebexRequest';
 import {WCC_API_GATEWAY} from '../constants';
@@ -34,6 +35,7 @@ import {
   DEFAULT_PAGE_SIZE,
   endPointMap,
   METHODS,
+  WELLBEING_BREAK_IDLE_CODE,
 } from './constants';
 
 /**
@@ -470,6 +472,69 @@ export default class AgentConfigService {
     }
   }
 
+  /**
+   * Retrieves the exact system-managed WellbeingBreak idle code.
+   * This query intentionally bypasses Desktop Profile filtering so the system code does not
+   * need to appear in the normal agent-selectable idle-code list.
+   * @param orgId - Organization identifier
+   * @returns The normalized WellbeingBreak entity
+   * @throws When the request fails or the exact system code is unavailable
+   * @internal
+   */
+  public async getWellbeingBreakIdleCode(orgId: string): Promise<Entity> {
+    LoggerProxy.info('Fetching WellbeingBreak system idle code', {
+      module: CONFIG_FILE_NAME,
+      method: METHODS.GET_WELLBEING_BREAK_IDLE_CODE,
+    });
+
+    try {
+      let page = DEFAULT_PAGE;
+      let totalPages = 1;
+
+      do {
+        // Pagination is intentionally sequential so the lookup can stop as soon as the code is found.
+        // eslint-disable-next-line no-await-in-loop
+        const response = await this.webexReq.request({
+          service: WCC_API_GATEWAY,
+          resource: endPointMap.systemIdleCodes(orgId, page, DEFAULT_PAGE_SIZE),
+          method: HTTP_METHODS.GET,
+        });
+
+        if (response.statusCode !== 200) {
+          throw new Error(`API call failed with ${response.statusCode}`);
+        }
+
+        const result = response.body as ListAuxCodesResponse;
+        const wellbeingCode = result.data?.find(
+          (code) =>
+            code.active === true &&
+            code.isSystemCode === true &&
+            code.name === WELLBEING_BREAK_IDLE_CODE
+        );
+
+        if (wellbeingCode) {
+          return {
+            id: wellbeingCode.id,
+            name: wellbeingCode.name,
+            isSystem: true,
+            isDefault: wellbeingCode.defaultCode,
+          };
+        }
+
+        totalPages = result.meta?.totalPages ?? 1;
+        page += 1;
+      } while (page < totalPages);
+
+      throw new Error('WELLBEING_BREAK_IDLE_CODE_NOT_FOUND');
+    } catch (error) {
+      LoggerProxy.error(`getWellbeingBreakIdleCode API call failed with ${error}`, {
+        module: CONFIG_FILE_NAME,
+        method: METHODS.GET_WELLBEING_BREAK_IDLE_CODE,
+      });
+      throw error;
+    }
+  }
+
   /**
    * Fetches the site data for the given orgId and siteId.
    * @ignore

package/src/services/config/types.ts

@@ -150,8 +150,7 @@ export const CC_TASK_EVENTS = {
 /**
  * Events emitted on Contact Center agent operations
  * @enum {string}
- * @private
- * @ignore
+ * @public
  */
 export const CC_AGENT_EVENTS = {
   /** Welcome event when agent connects to websocket/backend */
@@ -190,6 +189,8 @@ export const CC_AGENT_EVENTS = {
   AGENT_BUDDY_AGENTS_RETRIEVE_FAILED: 'BuddyAgentsRetrieveFailed',
   /** Event emitted when contact is reserved for agent */
   AGENT_CONTACT_RESERVED: 'AgentContactReserved',
+  /** Agent-level Agent Wellness Break notification */
+  WELLNESS_BREAK: 'WellnessBreak',
 } as const;
 
 /**
@@ -729,6 +730,8 @@ export type OrgSettings = {
   maskSensitiveData: boolean;
   /** Whether campaign manager features are enabled */
   campaignManagerEnabled: boolean;
+  /** Number of AI Assistant licenses assigned to the organization */
+  aiAssistantQuantity?: number | null;
 };
 
 /**
@@ -1245,6 +1248,12 @@ export type Profile = {
   lastIdleCodeChangeTimestamp?: number;
   /** AI feature flags resolved from organization config */
   aiFeature?: AIFeatureFlags;
+  /**
+   * Whether Agent Wellness Break is effectively enabled for this profile.
+   * This combines the organization wellbeing configuration with AI Assistant licensing;
+   * Server-side rollout remains enforced by the backend configuration and notification delivery.
+   */
+  isWellnessBreakEnabled?: boolean;
 };
 
 /**

package/src/services/core/Utils.ts

@@ -16,6 +16,10 @@ import {
 import {PARTICIPANT_TYPES, STATE_CONSULT} from './constants';
 import {DialPlan} from '../config/types';
 
+/** Returns whether a value is a non-null object with string keys. */
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
 /**
  * Extracts common error details from a Webex request payload.
  *

package/src/types.ts

@@ -8,6 +8,7 @@ import * as Agent from './services/agent/types';
 import * as Contact from './services/task/types';
 import {
   AIFeatureFlags,
+  Entity,
   Profile,
   CreateUserPreferenceRequest,
   UpdateUserPreferenceRequest,
@@ -419,6 +420,9 @@ export interface IContactCenter {
    * cc.register().then(profile => { ... });
    */
   register(): Promise<Profile>;
+
+  /** Returns the system-managed WellbeingBreak idle code for the registered session. */
+  getWellbeingBreakIdleCode(): Promise<Entity>;
 }
 
 /**
@@ -945,6 +949,63 @@ export type RealTimeAssistanceUserActionParams = {
   languageCode?: string;
 };
 
+/**
+ * Wellness notification actions delivered by the Contact Center notification service.
+ * @public
+ */
+export const WELLNESS_BREAK_NOTIFICATION_ACTIONS = {
+  PROVIDE_WELLNESS_BREAK: 'PROVIDE_WELLNESS_BREAK',
+  SUGGEST_WELLNESS_BREAK: 'SUGGEST_WELLNESS_BREAK',
+  WELLNESS_BREAK_NOT_ALLOWED: 'WELLNESS_BREAK_NOT_ALLOWED',
+} as const;
+
+/** Union of supported wellness notification actions. @public */
+export type WellnessBreakNotificationAction = Enum<typeof WELLNESS_BREAK_NOTIFICATION_ACTIONS>;
+
+/**
+ * Agent actions accepted by the wellness action API.
+ * @public
+ */
+export const WELLNESS_BREAK_USER_ACTIONS = {
+  REQUESTED: 'REQUESTED',
+  ACCEPTED: 'ACCEPTED',
+  REJECTED: 'REJECTED',
+  NO_RESPONSE: 'NO_RESPONSE',
+} as const;
+
+/** Union of supported wellness action API values. @public */
+export type WellnessBreakUserAction = Enum<typeof WELLNESS_BREAK_USER_ACTIONS>;
+
+/**
+ * Validated, agent-scoped wellness notification emitted by Contact Center.
+ * @public
+ */
+export interface WellnessBreakEvent {
+  /** Agent identifier */
+  agentId: string;
+  /** Organization identifier */
+  orgId: string;
+  /** Session identifier supplied by the notification; it may differ from the consumer's active session */
+  agentSessionId: string;
+  /** Backend wellness action */
+  actionEvent: WellnessBreakNotificationAction;
+  /** Optional untrusted plain-text message supplied by the backend */
+  actionText?: string;
+  /** Optional normalized interaction diagnostic */
+  interactionId?: string;
+  /** Notification diagnostic only; never an action-request correlation identifier */
+  trackingId?: string;
+}
+
+/**
+ * Parameters for responding to a backend-provided wellness offer.
+ * @public
+ */
+export interface RespondToWellnessBreakParams {
+  /** Agent response; REQUESTED is available only through requestWellnessBreak */
+  action: Exclude<WellnessBreakUserAction, typeof WELLNESS_BREAK_USER_ACTIONS.REQUESTED>;
+}
+
 /**
  * Supported AI Assistant event categories.
  * @public
@@ -994,6 +1055,8 @@ export const AIAssistantEventName = {
   SUGGESTED_RESPONSES_DIGITAL: 'SUGGESTED_RESPONSES_DIGITAL',
   /** User action on a suggested response adaptive card */
   SUGGESTED_RESPONSES_USER_ACTION: 'SUGGESTED_RESPONSES_USER_ACTION',
+  /** Agent Wellness Break request/response action */
+  WELLNESS_BREAK_ACTION: 'WellnessBreakAction',
 } as const;
 
 /**

package/src/webex.js

@@ -9,6 +9,8 @@ import '@webex/internal-plugin-support';
 import './index';
 
 import config from './webex-config';
+import {CC_AGENT_EVENTS} from './services/config/types';
+import {WELLNESS_BREAK_NOTIFICATION_ACTIONS, WELLNESS_BREAK_USER_ACTIONS} from './types';
 
 export * from './index';
 
@@ -30,6 +32,12 @@ const Webex = WebexCore.extend({
   version: PACKAGE_VERSION,
 });
 
+// The standalone UMD bundle exports the Webex constructor as its default value. Attach the
+// public agent-event contract so browser samples can use the same constants as module consumers.
+Webex.CC_AGENT_EVENTS = CC_AGENT_EVENTS;
+Webex.WELLNESS_BREAK_NOTIFICATION_ACTIONS = WELLNESS_BREAK_NOTIFICATION_ACTIONS;
+Webex.WELLNESS_BREAK_USER_ACTIONS = WELLNESS_BREAK_USER_ACTIONS;
+
 /**
  * Initializes a new Webex instance with merged configuration.
  *