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

package/src/cc.ts

@@ -26,6 +26,9 @@ import {
   UpdateDeviceTypeResponse,
   GenericError,
   ConfigFlags,
+  WellnessBreakEvent,
+  WellnessBreakNotificationAction,
+  WELLNESS_BREAK_NOTIFICATION_ACTIONS,
 } from './types';
 import {
   READY,
@@ -38,6 +41,7 @@ import {
   UNKNOWN_ERROR,
   MERCURY_DISCONNECTED_SUCCESS,
   METHODS,
+  WELLNESS_BREAK_HANDLER,
 } from './constants';
 import {AGENT_STATE_AVAILABLE, AGENT_STATE_AVAILABLE_ID} from './services/config/constants';
 import {AGENT, RTD_SUBSCRIBE_API, SUBSCRIBE_API, WEB_RTC_PREFIX} from './services/constants';
@@ -45,13 +49,14 @@ import Services from './services';
 import WebexRequest from './services/core/WebexRequest';
 import LoggerProxy from './logger-proxy';
 import {StateChange, Logout, StateChangeSuccess, AGENT_EVENTS} from './services/agent/types';
-import {getErrorDetails, isValidDialNumber} from './services/core/Utils';
+import {getErrorDetails, isRecord, isValidDialNumber} from './services/core/Utils';
 import {
   Profile,
   WelcomeEvent,
   CC_EVENTS,
   OutdialAniEntriesResponse,
   OutdialAniParams,
+  Entity,
 } from './services/config/types';
 import {ConnectionLostDetails} from './services/core/websocket/types';
 import TaskManager from './services/task/TaskManager';
@@ -296,6 +301,19 @@ export default class ContactCenter extends WebexPlugin implements IContactCenter
    */
   private metricsManager: MetricsManager;
 
+  /** Current login/relogin session used for agent-scoped wellness validation. */
+  private currentAgentSessionId?: string;
+
+  /** Registered-session cache for the system WellbeingBreak idle code. */
+  private wellbeingBreakIdleCode?: Entity;
+
+  /** Registration generation that owns the wellness idle-code cache and in-flight lookups. */
+  private wellnessRegistrationGeneration = 0;
+
+  private updateWellnessSession(agentSessionId?: string): void {
+    this.currentAgentSessionId = agentSessionId;
+  }
+
   /**
    * API instance for managing Webex Contact Center entry points
    * Provides functionality to fetch entry points with caching support
@@ -440,7 +458,11 @@ export default class ContactCenter extends WebexPlugin implements IContactCenter
       this.answerCallOnWebexService = new AnswerCallOnWebexService(this.$webex);
       this.webexCrossClientService = new WebexCrossClientService(this.$webex);
       this.wxAppTelephonyMercurySync = new WxAppTelephonyMercurySync(this.$webex);
-      this.apiAIAssistant = new ApiAIAssistant(this.$webex);
+      this.apiAIAssistant = new ApiAIAssistant(this.$webex, () => ({
+        isWellnessBreakEnabled: this.agentConfig?.isWellnessBreakEnabled === true,
+        agentId: this.agentConfig?.agentId,
+        agentSessionId: this.currentAgentSessionId,
+      }));
       this.metricsManager = MetricsManager.getInstance({webex: this.$webex});
       this.taskManager = TaskManager.getTaskManager(
         this.apiAIAssistant,
@@ -512,6 +534,114 @@ export default class ContactCenter extends WebexPlugin implements IContactCenter
     this.trigger(TASK_EVENTS.TASK_CAMPAIGN_PREVIEW_RESERVATION, task);
   };
 
+  private trackInvalidWellnessEvent(reason: string): void {
+    this.metricsManager.trackEvent(
+      METRIC_EVENT_NAMES.AI_ASSISTANT_WELLNESS_EVENT_INVALID,
+      {reason},
+      ['operational']
+    );
+  }
+
+  private normalizeWellnessBreakEvent(payload: Record<string, unknown>): WellnessBreakEvent | null {
+    if (this.agentConfig?.isWellnessBreakEnabled !== true) {
+      this.trackInvalidWellnessEvent('wellness_disabled');
+
+      return null;
+    }
+
+    const notificationData = isRecord(payload.data) ? payload.data : null;
+    const notificationDetails =
+      notificationData && isRecord(notificationData.notifDetails)
+        ? notificationData.notifDetails
+        : null;
+    const sessionData =
+      notificationData && isRecord(notificationData.data) ? notificationData.data : null;
+    const actionEvent = notificationDetails?.actionEvent;
+
+    if (
+      payload.type !== WELLNESS_BREAK_HANDLER ||
+      notificationData?.notifType !== WELLNESS_BREAK_HANDLER ||
+      typeof actionEvent !== 'string'
+    ) {
+      this.trackInvalidWellnessEvent('malformed_wellness_event');
+
+      return null;
+    }
+
+    if (
+      !Object.values(WELLNESS_BREAK_NOTIFICATION_ACTIONS).includes(
+        actionEvent as WellnessBreakNotificationAction
+      )
+    ) {
+      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 as WellnessBreakNotificationAction,
+      ...(typeof actionText === 'string' ? {actionText} : {}),
+      ...(typeof interactionValue === 'string' ? {interactionId: interactionValue} : {}),
+      ...(typeof trackingId === 'string' ? {trackingId} : {}),
+    };
+  }
+
+  private handleWellnessBreakWebsocketPayload(payload: Record<string, unknown>): boolean {
+    if (payload.type !== 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(CC_EVENTS.WELLNESS_BREAK, wellnessEvent);
+    }
+
+    return true;
+  }
+
   private handleRTDWebsocketMessage = (event: string) => {
     this.taskManager.handleRealtimeWebsocketEvent(event);
   };
@@ -569,6 +699,8 @@ export default class ContactCenter extends WebexPlugin implements IContactCenter
    * ```
    */
   public async register(): Promise<Profile> {
+    this.wellnessRegistrationGeneration += 1;
+    this.wellbeingBreakIdleCode = undefined;
     LoggerProxy.log('Starting CC SDK registration', {
       module: CC_FILE,
       method: METHODS.REGISTER,
@@ -651,6 +783,9 @@ export default class ContactCenter extends WebexPlugin implements IContactCenter
 
    */
   public async deregister(): Promise<void> {
+    this.wellnessRegistrationGeneration += 1;
+    this.wellbeingBreakIdleCode = undefined;
+    this.updateWellnessSession();
     try {
       this.metricsManager.timeEvent([
         METRIC_EVENT_NAMES.WEBSOCKET_DEREGISTER_SUCCESS,
@@ -703,7 +838,9 @@ export default class ContactCenter extends WebexPlugin implements IContactCenter
       }
 
       // Clear any cached agent configuration
+      this.wellbeingBreakIdleCode = undefined;
       this.agentConfig = null;
+      this.updateWellnessSession();
 
       if (wxAppPublishError) {
         throw wxAppPublishError;
@@ -873,6 +1010,8 @@ export default class ContactCenter extends WebexPlugin implements IContactCenter
       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.
@@ -945,6 +1084,7 @@ export default class ContactCenter extends WebexPlugin implements IContactCenter
 
       return this.agentConfig;
     } catch (error) {
+      this.updateWellnessSession();
       LoggerProxy.error(`Error during register: ${error}`, {
         module: CC_FILE,
         method: METHODS.CONNECT_WEBSOCKET,
@@ -1055,6 +1195,7 @@ export default class ContactCenter extends WebexPlugin implements IContactCenter
 
       const resp = await loginResponse;
       const {channelsMap, ...loginData} = resp.data;
+      this.updateWellnessSession(resp.data.agentSessionId);
       this.agentConfig.currentTeamId = resp.data.teamId;
       const response = {
         ...loginData,
@@ -1170,6 +1311,7 @@ export default class ContactCenter extends WebexPlugin implements IContactCenter
       }
 
       await this.teardownWxAppLocalState();
+      this.updateWellnessSession();
 
       LoggerProxy.log(`Agent station logout completed successfully`, {
         module: CC_FILE,
@@ -1307,6 +1449,77 @@ export default class ContactCenter extends WebexPlugin implements IContactCenter
     }
   }
 
+  /**
+   * 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
+   */
+  public async getWellbeingBreakIdleCode(): Promise<Entity> {
+    const method = METHODS.GET_WELLBEING_BREAK_IDLE_CODE;
+    try {
+      if (!this.agentConfig?.isWellnessBreakEnabled) {
+        const validationError = new Error('WELLNESS_BREAK_NOT_ENABLED') as GenericError;
+        validationError.details = {
+          type: 'SDK_VALIDATION_ERROR',
+          orgId: this.$webex.credentials.getOrgId(),
+          trackingId: EMPTY_STRING,
+          data: {reason: 'WELLNESS_BREAK_NOT_ENABLED'},
+        };
+        throw validationError;
+      }
+
+      if (this.wellbeingBreakIdleCode) {
+        return this.wellbeingBreakIdleCode;
+      }
+
+      this.metricsManager.timeEvent([
+        METRIC_EVENT_NAMES.WELLBEING_BREAK_IDLE_CODE_FETCH_SUCCESS,
+        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'
+        ) as GenericError;
+        staleRegistrationError.details = {
+          type: 'SDK_VALIDATION_ERROR',
+          orgId,
+          trackingId: EMPTY_STRING,
+          data: {reason: 'WELLNESS_BREAK_REGISTRATION_CHANGED'},
+        };
+        throw staleRegistrationError;
+      }
+
+      this.wellbeingBreakIdleCode = idleCode;
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.WELLBEING_BREAK_IDLE_CODE_FETCH_SUCCESS,
+        {},
+        ['operational']
+      );
+
+      return idleCode;
+    } catch (error) {
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.WELLBEING_BREAK_IDLE_CODE_FETCH_FAILED,
+        {reason: error instanceof Error ? error.message : UNKNOWN_ERROR},
+        ['operational']
+      );
+      const {error: detailedError} = getErrorDetails(error, method, CC_FILE);
+      throw detailedError;
+    }
+  }
+
   /**
    * Processes incoming websocket messages and emits corresponding events
    * Handles various event types including agent state changes, login events,
@@ -1345,8 +1558,19 @@ export default class ContactCenter extends WebexPlugin implements IContactCenter
       ]);
     }
 
+    if (this.handleWellnessBreakWebsocketPayload(eventData)) {
+      return;
+    }
+
     switch (eventData.type) {
       case CC_EVENTS.AGENT_MULTI_LOGIN:
+        if (
+          eventData.data?.type === 'AgentMultiLoginCloseSession' &&
+          (!eventData.data.agentSessionId ||
+            eventData.data.agentSessionId === this.currentAgentSessionId)
+        ) {
+          this.updateWellnessSession();
+        }
         // @ts-ignore
         this.emit(AGENT_EVENTS.AGENT_MULTI_LOGIN, eventData.data);
         break;
@@ -1365,6 +1589,7 @@ export default class ContactCenter extends WebexPlugin implements IContactCenter
     switch (eventData.data.type) {
       case CC_EVENTS.AGENT_STATION_LOGIN_SUCCESS: {
         const {channelsMap, ...loginData} = eventData.data;
+        this.updateWellnessSession(loginData.agentSessionId);
         const stationLoginData = {
           ...loginData,
           mmProfile: {
@@ -1380,23 +1605,23 @@ export default class ContactCenter extends WebexPlugin implements IContactCenter
         this.emit(AGENT_EVENTS.AGENT_STATION_LOGIN_SUCCESS, stationLoginData);
         break;
       }
-      case CC_EVENTS.AGENT_RELOGIN_SUCCESS:
-        {
-          const {channelsMap, ...loginData} = eventData.data;
-          const stationReLoginData = {
-            ...loginData,
-            mmProfile: {
-              chat: channelsMap.chat?.length,
-              email: channelsMap.email?.length,
-              social: channelsMap.social?.length,
-              telephony: channelsMap.telephony?.length,
-            },
-            notifsTrackingId: eventData.trackingId,
-          };
-          // @ts-ignore
-          this.emit(AGENT_EVENTS.AGENT_RELOGIN_SUCCESS, stationReLoginData);
-        }
+      case CC_EVENTS.AGENT_RELOGIN_SUCCESS: {
+        const {channelsMap, ...loginData} = eventData.data;
+        this.updateWellnessSession(loginData.agentSessionId);
+        const stationReLoginData = {
+          ...loginData,
+          mmProfile: {
+            chat: channelsMap.chat?.length,
+            email: channelsMap.email?.length,
+            social: channelsMap.social?.length,
+            telephony: channelsMap.telephony?.length,
+          },
+          notifsTrackingId: eventData.trackingId,
+        };
+        // @ts-ignore
+        this.emit(AGENT_EVENTS.AGENT_RELOGIN_SUCCESS, stationReLoginData);
         break;
+      }
       case CC_EVENTS.AGENT_STATE_CHANGE_SUCCESS:
         // @ts-ignore
         this.emit(AGENT_EVENTS.AGENT_STATE_CHANGE_SUCCESS, eventData.data);
@@ -1410,6 +1635,12 @@ export default class ContactCenter extends WebexPlugin implements IContactCenter
         this.emit(AGENT_EVENTS.AGENT_STATION_LOGIN_FAILED, eventData.data);
         break;
       case CC_EVENTS.AGENT_LOGOUT_SUCCESS:
+        if (
+          !eventData.data.agentSessionId ||
+          eventData.data.agentSessionId === this.currentAgentSessionId
+        ) {
+          this.updateWellnessSession();
+        }
         // @ts-ignore
         this.emit(AGENT_EVENTS.AGENT_LOGOUT_SUCCESS, eventData.data);
         break;
@@ -2079,6 +2310,8 @@ export default class ContactCenter extends WebexPlugin implements IContactCenter
 
     try {
       const reLoginResponse = await this.services.agent.reload();
+      this.updateWellnessSession(reLoginResponse.data.agentSessionId);
+
       const {
         agentId,
         lastStateChangeReason,

package/src/constants.ts

@@ -8,6 +8,7 @@ export const LOG_PREFIX = 'PLUGIN_CC';
 export const WEB_CALLING_SERVICE_FILE = 'WebCallingService';
 export const CONFIG_FILE_NAME = 'config-index';
 export const CC_FILE = 'cc';
+export const WELLNESS_BREAK_HANDLER = 'Wellness_Break_Handler';
 export const CONNECTION_SERVICE_FILE = 'connection-service';
 export const WEB_SOCKET_MANAGER_FILE = 'WebSocketManager';
 export const AQM_REQS_FILE = 'aqm-reqs';
@@ -72,6 +73,9 @@ export const METHODS = {
   GET_REAL_TIME_ASSISTANCE: 'getRealTimeAssistance',
   SEND_REAL_TIME_ASSISTANCE_USER_ACTION: 'sendRealTimeAssistanceUserAction',
   FETCH_HISTORIC_TRANSCRIPTS: 'fetchHistoricTranscripts',
+  REQUEST_WELLNESS_BREAK: 'requestWellnessBreak',
+  RESPOND_TO_WELLNESS_BREAK: 'respondToWellnessBreak',
+  GET_WELLBEING_BREAK_IDLE_CODE: 'getWellbeingBreakIdleCode',
   SET_MANAGE_WEBEX_CALLING_IN_WXCC: 'setManageWebexCallingInWxcc',
   IS_WX_BETTER_TOGETHER_ENABLED: 'isWxBetterTogetherEnabled',
   SYNC_WXAPP_MUTE_FROM_MERCURY: 'syncWxAppMuteFromMercury',

package/src/index.ts

@@ -30,6 +30,9 @@ export {default as AddressBook} from './services/AddressBook';
 export {default as ApiAIAssistant} from './services/ApiAiAssistant';
 export {default as UserPreference} from './services/UserPreference';
 
+/** Agent Wellness Break notification and action wire values. */
+export {WELLNESS_BREAK_NOTIFICATION_ACTIONS, WELLNESS_BREAK_USER_ACTIONS} from './types';
+
 /** EntryPoint API types */
 export type {
   EntryPointRecord,
@@ -120,6 +123,14 @@ export type {
   GenericError,
   /** Set state response */
   SetStateResponse,
+  /** Wellness notification action */
+  WellnessBreakNotificationAction,
+  /** Wellness action API value */
+  WellnessBreakUserAction,
+  /** Validated agent-scoped wellness notification */
+  WellnessBreakEvent,
+  /** Wellness offer-response parameters */
+  RespondToWellnessBreakParams,
 } from './types';
 
 /** Task related types */

package/src/metrics/ai-docs/metrics-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.
@@ -260,6 +260,9 @@ All event names are defined in `METRIC_EVENT_NAMES` (`constants.ts`). Events fol
 | `ADDRESSBOOK_FETCH_SUCCESS` / `FAILED` | `'AddressBook Fetch ...'` | Address book fetch result |
 | `QUEUE_FETCH_SUCCESS` / `FAILED` | `'Queue Fetch ...'` | Queue fetch result |
 | `OUTDIAL_ANI_EP_FETCH_SUCCESS` / `FAILED` | `'Outdial ANI Entries Fetch ...'` | Outdial ANI entries fetch result |
+| `AI_ASSISTANT_WELLNESS_ACTION_ACCEPTED` / `FAILED` | `'AI Assistant Wellness Action ...'` | Direct wellness custom-event result |
+| `AI_ASSISTANT_WELLNESS_EVENT_INVALID` | `'AI Assistant Wellness Event Invalid'` | Malformed or mismatched wellness notification ignored |
+| `WELLBEING_BREAK_IDLE_CODE_FETCH_SUCCESS` / `FAILED` | `'Wellbeing Break Idle Code Fetch ...'` | System wellness idle-code lookup result |
 
 All event names are defined in `constants.ts` as `METRIC_EVENT_NAMES`. Events follow a `{Domain} {Action} {Success|Failed}` naming convention:
 
@@ -334,11 +337,11 @@ Special events (no success/failure pair):
 
 - `WXAPP_SESSION_SKIPPED` — has behavioral taxonomy (`wxcc_sdk.user.webex_together_session_init.ignore`)
 
-Of the 107 defined metric names, 96 have behavioral taxonomy and 11 do not. Events **without** an `eventTaxonomyMap` entry are the eight `AI_ASSISTANT_*` names plus `WEBSOCKET_DEREGISTER_SUCCESS`, `WEBSOCKET_DEREGISTER_FAIL`, and `WEBSOCKET_EVENT_RECEIVED`.
+Of the 116 defined metric names, 96 have behavioral taxonomy and 20 do not. The Agent Wellness Break names are intentionally operational-only and therefore have no `eventTaxonomyMap` entries.
 
 ### Complete METRIC_EVENT_NAMES catalog
 
-This table contains all 107 names from `src/metrics/constants.ts`; taxonomy presence is checked against `src/metrics/behavioral-events.ts`: 96 mapped and 11 unmapped.
+This table contains all 116 names from `src/metrics/constants.ts`; taxonomy presence is checked against `src/metrics/behavioral-events.ts`: 96 mapped and 20 unmapped.
 
 | Constant | Emitted name | Behavioral taxonomy? |
 |---|---|---|
@@ -441,6 +444,11 @@ This table contains all 107 names from `src/metrics/constants.ts`; taxonomy pres
 | `AI_ASSISTANT_SEND_REAL_TIME_ASSISTANCE_USER_ACTION_FAILED` | `AI Assistant Send Real Time Assistance User Action Failed` | no |
 | `AI_ASSISTANT_FETCH_HISTORIC_TRANSCRIPTS_SUCCESS` | `AI Assistant Fetch Historic Transcripts Success` | no |
 | `AI_ASSISTANT_FETCH_HISTORIC_TRANSCRIPTS_FAILED` | `AI Assistant Fetch Historic Transcripts Failed` | no |
+| `AI_ASSISTANT_WELLNESS_ACTION_ACCEPTED` | `AI Assistant Wellness Action Accepted` | no |
+| `AI_ASSISTANT_WELLNESS_ACTION_FAILED` | `AI Assistant Wellness Action Failed` | no |
+| `AI_ASSISTANT_WELLNESS_EVENT_INVALID` | `AI Assistant Wellness Event Invalid` | no |
+| `WELLBEING_BREAK_IDLE_CODE_FETCH_SUCCESS` | `Wellbeing Break Idle Code Fetch Success` | no |
+| `WELLBEING_BREAK_IDLE_CODE_FETCH_FAILED` | `Wellbeing Break Idle Code Fetch Failed` | no |
 | `USER_PREFERENCE_GET_SUCCESS` | `User Preference Get Success` | yes |
 | `USER_PREFERENCE_GET_FAILED` | `User Preference Get Failed` | yes |
 | `USER_PREFERENCE_CREATE_SUCCESS` | `User Preference Create Success` | yes |
@@ -450,7 +458,7 @@ This table contains all 107 names from `src/metrics/constants.ts`; taxonomy pres
 | `USER_PREFERENCE_DELETE_SUCCESS` | `User Preference Delete Success` | yes |
 | `USER_PREFERENCE_DELETE_FAILED` | `User Preference Delete Failed` | yes |
 
-Defined names without an `eventTaxonomyMap` entry: `AI_ASSISTANT_FETCH_HISTORIC_TRANSCRIPTS_FAILED`, `AI_ASSISTANT_FETCH_HISTORIC_TRANSCRIPTS_SUCCESS`, `AI_ASSISTANT_GET_REAL_TIME_ASSISTANCE_FAILED`, `AI_ASSISTANT_GET_REAL_TIME_ASSISTANCE_SUCCESS`, `AI_ASSISTANT_SEND_EVENT_FAILED`, `AI_ASSISTANT_SEND_EVENT_SUCCESS`, `AI_ASSISTANT_SEND_REAL_TIME_ASSISTANCE_USER_ACTION_FAILED`, `AI_ASSISTANT_SEND_REAL_TIME_ASSISTANCE_USER_ACTION_SUCCESS`, `WEBSOCKET_DEREGISTER_FAIL`, `WEBSOCKET_DEREGISTER_SUCCESS`, `WEBSOCKET_EVENT_RECEIVED`.
+Defined names without an `eventTaxonomyMap` entry: `WEBSOCKET_DEREGISTER_SUCCESS`, `WEBSOCKET_DEREGISTER_FAIL`, `WEBSOCKET_EVENT_RECEIVED`, all eight AI Assistant request names, and the seven Agent Wellness Break notification/action/system-code/ASC names listed above.
 
 ## Requires (dependencies)
 - `webex.internal.newMetrics` submission APIs
@@ -473,6 +481,7 @@ Defined names without an `eventTaxonomyMap` entry: `AI_ASSISTANT_FETCH_HISTORIC_
 | METRICS-R-003 | When metrics are disabled, clear pending events and make `timeEvent` plus all tracking methods return without recording/submitting. | Telemetry must never block or alter product behavior and disablement must be comprehensive. | `src/metrics/MetricsManager.ts` | `test/unit/spec/metrics/MetricsManager.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
 | METRICS-R-004 | Queue submissions until the host SDK is ready and flush through the correct behavioral/operational/business service. | Early lifecycle telemetry must not be lost solely because the host is not ready. | `src/metrics/MetricsManager.ts` | `test/unit/spec/metrics/MetricsManager.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
 | METRICS-R-005 | Submit through the host SDK's `webex.internal.newMetrics` client without storing credentials or implementing authorization policy in MetricsManager. | Host-owned authentication keeps telemetry credential handling outside the Contact Center metrics module. | `src/metrics/MetricsManager.ts` | `test/unit/spec/metrics/MetricsManager.ts` | None; authentication is inherited and credential ownership is explicitly N/A. | PRESENT |
+| METRICS-R-006 | Track wellness action, invalid notification, system-code lookup, and ASC state-change outcomes as operational metrics using fixed names and reason-only/context-minimized payloads. | The feature needs diagnosable lifecycle signals without logging wellness payloads or agent PII. | `src/metrics/constants.ts`, `src/cc.ts`, `src/services/ApiAiAssistant.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/services/ApiAiAssistant.ts` | These names intentionally have no behavioral taxonomy. | PRESENT |
 
 ## Design Overview
 Metrics separates its stable consumption boundary from collaborators so ownership and failure behavior stay explicit. Telemetry is deliberately non-blocking and queue-backed so product behavior never waits for metrics; failures are logged rather than propagated.
@@ -495,18 +504,7 @@ Each behavioral event maps to a structured taxonomy in `behavioral-events.ts`:
 
 **Example**: `STATION_LOGIN_SUCCESS` maps to `wxcc_sdk.user.station_login.complete`
 
-> **Note**: The following events do **not** have behavioral taxonomy mappings in `behavioral-events.ts`:
-> - `AI_ASSISTANT_SEND_EVENT_SUCCESS`
-> - `AI_ASSISTANT_SEND_EVENT_FAILED`
-> - `AI_ASSISTANT_GET_REAL_TIME_ASSISTANCE_SUCCESS`
-> - `AI_ASSISTANT_GET_REAL_TIME_ASSISTANCE_FAILED`
-> - `AI_ASSISTANT_SEND_REAL_TIME_ASSISTANCE_USER_ACTION_SUCCESS`
-> - `AI_ASSISTANT_SEND_REAL_TIME_ASSISTANCE_USER_ACTION_FAILED`
-> - `AI_ASSISTANT_FETCH_HISTORIC_TRANSCRIPTS_SUCCESS`
-> - `AI_ASSISTANT_FETCH_HISTORIC_TRANSCRIPTS_FAILED`
-> - `WEBSOCKET_DEREGISTER_SUCCESS`
-> - `WEBSOCKET_DEREGISTER_FAIL`
-> - `WEBSOCKET_EVENT_RECEIVED`
+> **Note**: The 20 names catalogued above as lacking `eventTaxonomyMap` entries, including all nine new wellness-related names, are operational-only.
 >
 > Calling `trackBehavioralEvent` with these event names will push an event with an `undefined` taxonomy.
 
@@ -796,7 +794,7 @@ MetricsManager holds three pending queues, running timing entries, a readiness f
 
 ## Business Rules & Invariants
 - `timeEvent` and every tracking method return immediately while metrics are disabled.
-- Only names present in `eventTaxonomyMap` receive behavioral taxonomy; 73 of 82 names are mapped and the six AI Assistant plus three WebSocket names are intentionally catalogued as unmapped.
+- Only names present in `eventTaxonomyMap` receive behavioral taxonomy; 81 of 101 names are mapped and all 20 exceptions are explicitly catalogued as unmapped.
 - `submittingEvents` prevents overlapping queue-drain executions.
 - Authentication is inherited from the host Webex SDK's metrics client; MetricsManager owns no credentials, tokens, or authorization policy.
 
@@ -831,7 +829,7 @@ stateDiagram-v2
 - **metricsDisabled**: When `true`, `timeEvent` and all `track*` methods return early, and `clearPendingEvents()` empties all queues.
 
 ## Pitfalls
-- `METRIC_EVENT_NAMES` and `eventTaxonomyMap` are different inventories: eleven defined names intentionally have no behavioral taxonomy.
+- `METRIC_EVENT_NAMES` and `eventTaxonomyMap` are different inventories: 20 defined names intentionally have no behavioral taxonomy.
 - `setMetricsDisabled(true)` clears pending queues but does not create a delivery receipt; callers must not infer that previously submitted events were accepted.
 - Submission helpers hand events to `webex.internal.newMetrics` without a module-level retry/requeue policy, so telemetry must remain non-blocking and non-authoritative.
 
@@ -892,10 +890,11 @@ Use `test/unit/spec/metrics/MetricsManager.ts` for readiness queues, timing/trac
 | Behavior / Requirement | Existing test evidence | Gap |
 |---|---|---|
 | `METRICS-R-001` | `test/unit/spec/metrics/MetricsManager.ts` | Add a catalog parity assertion if constants change. |
-| `METRICS-R-002` | `test/unit/spec/metrics/behavioral-events.ts` | Keep explicit coverage for all eleven unmapped names. |
+| `METRICS-R-002` | `test/unit/spec/metrics/behavioral-events.ts` | Keep explicit coverage for all 20 unmapped names. |
 | `METRICS-R-003` | `test/unit/spec/metrics/MetricsManager.ts` | None. |
 | `METRICS-R-004` | `test/unit/spec/metrics/MetricsManager.ts` | None. |
 | `METRICS-R-005` | `test/unit/spec/metrics/MetricsManager.ts` | Authentication ownership is verified indirectly through the host metrics client. |
+| `METRICS-R-006` | `test/unit/spec/cc.ts`, `test/unit/spec/services/ApiAiAssistant.ts` | Add direct catalog-parity coverage if metrics constants receive a dedicated test. |
 
 ## Traceability
 - Repo architecture: `../../../ai-docs/ARCHITECTURE.md` · Registry: `../../../ai-docs/SPEC_INDEX.md`

package/src/metrics/constants.ts

@@ -203,6 +203,11 @@ export const METRIC_EVENT_NAMES = {
   AI_ASSISTANT_FETCH_HISTORIC_TRANSCRIPTS_SUCCESS:
     'AI Assistant Fetch Historic Transcripts Success',
   AI_ASSISTANT_FETCH_HISTORIC_TRANSCRIPTS_FAILED: 'AI Assistant Fetch Historic Transcripts Failed',
+  AI_ASSISTANT_WELLNESS_ACTION_ACCEPTED: 'AI Assistant Wellness Action Accepted',
+  AI_ASSISTANT_WELLNESS_ACTION_FAILED: 'AI Assistant Wellness Action Failed',
+  AI_ASSISTANT_WELLNESS_EVENT_INVALID: 'AI Assistant Wellness Event Invalid',
+  WELLBEING_BREAK_IDLE_CODE_FETCH_SUCCESS: 'Wellbeing Break Idle Code Fetch Success',
+  WELLBEING_BREAK_IDLE_CODE_FETCH_FAILED: 'Wellbeing Break Idle Code Fetch Failed',
 
   // User Preference API Events
   USER_PREFERENCE_GET_SUCCESS: 'User Preference Get Success',