feat(contact-center): add agent wellness breaks (WXCC-12423)

.gitignore

@@ -39,6 +39,8 @@ reports/
 
 #Local stuff
 *.json
+!packages/contact-center/ai-assistant/src/wellness/assets/WellnessBreakAnimationDark.json
+!packages/contact-center/ai-assistant/src/wellness/assets/WellnessBreakAnimationLight.json
 !docs/changelog/logs/*.json
 !.sdd/manifest.json
 .env*

.sdd/manifest.json

@@ -50,7 +50,7 @@
       "package": "@webex/cc-widgets",
       "path": "packages/contact-center/cc-widgets",
       "spec": "packages/contact-center/cc-widgets/ai-docs/cc-widgets-spec.md",
-      "responsibility": "r2wc Web Component wrappers aggregating widget packages for framework-agnostic consumption.",
+      "responsibility": "React widget aggregate and r2wc Web Component wrappers for framework-agnostic consumption.",
       "coverageState": "DRAFT",
       "tier": 1
     },
@@ -96,7 +96,7 @@
       "package": "@webex/cc-ai-assistant",
       "path": "packages/contact-center/ai-assistant",
       "spec": "packages/contact-center/ai-assistant/ai-docs/ai-assistant-spec.md",
-      "responsibility": "AI Assistant widget: panel chrome, Real-time Assist requests, transcript, feedback actions.",
+      "responsibility": "AI Assistant widget: panel chrome, Real-time Assist, and Agent Wellness Break orchestration.",
       "coverageState": "DRAFT",
       "tier": 1
     },

ai-docs/ARCHITECTURE.md

@@ -24,7 +24,8 @@ SDK at runtime — so there is no datastore, schema, or migration discipline to
 |---|---|---|
 | `store/` | MobX singleton: global CC state, SDK event wiring, SDK access surface | `packages/contact-center/store/ai-docs/store-spec.md` |
 | `cc-components/` | Pure presentational React primitives (props-only) | `packages/contact-center/cc-components/ai-docs/cc-components-spec.md` |
-| `cc-widgets/` | r2wc Web Component wrappers; aggregates and exports all widgets | `packages/contact-center/cc-widgets/ai-docs/cc-widgets-spec.md` |
+| `cc-widgets/` | React widget aggregate, including AI Assistant, and r2wc Web Component wrappers | `packages/contact-center/cc-widgets/ai-docs/cc-widgets-spec.md` |
+| `ai-assistant/` | AI Assistant observer/orchestrator for Real-time Assist and Agent Wellness Break | `packages/contact-center/ai-assistant/ai-docs/ai-assistant-spec.md` |
 | `station-login/` | Agent login widget (team + device selection) | `packages/contact-center/station-login/ai-docs/station-login-spec.md` |
 | `user-state/` | Agent state widget (state, idle codes, timer) | `packages/contact-center/user-state/ai-docs/user-state-spec.md` |
 | `task/` | Task widgets: CallControl, CallControlCAD, IncomingTask, OutdialCall, TaskList | `packages/contact-center/task/ai-docs/task-spec.md` |
@@ -36,7 +37,7 @@ SDK at runtime — so there is no datastore, schema, or migration discipline to
 ```mermaid
 graph TD
   Host[Host app / Web Component] --> Widget
-  subgraph WidgetPackages[Widget packages: station-login, user-state, task]
+  subgraph WidgetPackages[Widget packages: station-login, user-state, task, ai-assistant]
     Widget[Widget = observer HOC] --> Hook[Custom hook helper.ts]
   end
   Hook --> Comp[Presentational component cc-components]
@@ -112,7 +113,7 @@ For Consult/Transfer, `Task.uiControls.consultTransferDestinations` is the visib
   `widgets-samples/**/**`.
 - **Inter-package dependency graph** (from each package's `package.json`):
 ```
-cc-widgets ── wraps ──> station-login, user-state, task (+ cc-digital-channels)
+cc-widgets ── wraps ──> station-login, user-state, task, ai-assistant (+ cc-digital-channels)
 station-login ─┐
 user-state    ─┼──> cc-components, cc-store
 task          ─┘

ai-docs/CONTRACTS.md

@@ -9,7 +9,7 @@ This repo is consumed as libraries: its public surface is the package **exports*
 
 ### Exported API & Types
 
-The aggregator package `@webex/cc-widgets` re-exports every widget plus the `store` singleton (`packages/contact-center/cc-widgets/src/index.ts:8-19`). When imported via the bundled `wc.ts` entry, each widget is also registered as a custom element (tag names below).
+The React entry of `@webex/cc-widgets` re-exports the widgets, including `AIAssistant`, and the `store` singleton. React hosts can also import `AIAssistant` directly from `@webex/cc-ai-assistant`. The existing `@webex/cc-widgets/wc` entry registers all widget custom elements, including AI Assistant.
 
 | Contract ID | Owner module/package | Symbol | Signature | Stability / deprecation | Schema / detail link | Defined at |
 |---|---|---|---|---|---|---|
@@ -22,6 +22,9 @@ The aggregator package `@webex/cc-widgets` re-exports every widget plus the `sto
 | cc-widgets.OutdialCall | `@webex/cc-task` | `OutdialCall` | React component; custom element `widget-cc-outdial-call`; no declared props | stable semver | `packages/contact-center/task/ai-docs/task-spec.md` | `packages/contact-center/task/src/index.ts` |
 | cc-widgets.RealTimeTranscript | `@webex/cc-task` | `RealTimeTranscript` | React component; custom element `widget-cc-realtime-transcript`; props `liveTranscriptEntries` (json), `className` (string) | stable semver | `packages/contact-center/task/ai-docs/task-spec.md` | `packages/contact-center/task/src/index.ts` |
 | cc-widgets.DigitalChannels | `@webex/cc-digital-channels` | `DigitalChannels` | React component; custom element `widget-cc-digital-channels`; no declared props | stable semver | `packages/contact-center/cc-digital-channels/ai-docs/cc-digital-channels-spec.md` | `packages/contact-center/cc-digital-channels/src/index.ts` |
+| ai-assistant.AIAssistant | `@webex/cc-widgets` and `@webex/cc-ai-assistant` (React); `@webex/cc-widgets/wc` (custom element) | `AIAssistant`; `widget-cc-ai-assistant` | React component and existing custom element; wellness callbacks `onWellnessBreakOffered`, `onWellnessBreakAccepted`, `onWellnessBreakStarted`, `onWellnessBreakEnded`, `onWellnessBreakError`; optional `wellnessAudioUrl` and `wellnessBreakOverlayTarget` | Both React import paths remain available; WC entry retains the tag | `packages/contact-center/ai-assistant/ai-docs/ai-assistant-spec.md` | `packages/contact-center/ai-assistant/src/ai-assistant.types.ts`, `packages/contact-center/cc-widgets/src/index.ts`, `packages/contact-center/cc-widgets/src/wc.ts` |
+| ai-assistant.wellness-types | `@webex/cc-ai-assistant` | `WellnessBreakPhase`, `WellnessBreakErrorCode`, `WellnessBreakError`, `WellnessBreakOverlayTarget` | Exported TypeScript lifecycle, error, and layout contracts | additive minor surface; literals are stable | `packages/contact-center/ai-assistant/ai-docs/ai-assistant-spec.md` | `packages/contact-center/ai-assistant/src/ai-assistant.types.ts` |
+| cc-components.WellnessBreak | `@webex/cc-components` | `WellnessBreakRequestCard`, `WellnessBreakOfferCard`, `WellnessBreakModal`, `WellnessBreakError` | Props-only Agent Wellness Break presentation; modal accepts an optional animation loader supplied by AI Assistant and owns no wellness media | monorepo component surface; no SDK/store or Lottie dependency | `packages/contact-center/cc-components/ai-docs/cc-components-spec.md` | `packages/contact-center/cc-components/src/components/AIAssistant/WellnessBreak/` |
 | cc-widgets.store | `@webex/cc-store` | `store` | MobX singleton (`Store.getInstance()`); `init(options: InitParams, setupEventListeners): Promise<void>`; sole SDK access point via `store.cc.*` | stable semver | `packages/contact-center/store/ai-docs/store-spec.md` | `packages/contact-center/store/src/index.ts:1,4` |
 | store.host-init.enableWxBetterTogether | `@webex/cc-store` | `webexConfig.cc.enableWxBetterTogether` → `store.enableWxBetterTogether` | Host init boolean (default `false`), set **before** `store.init()`: read from `webexConfig.cc` on `{ webexConfig, access_token }` init or `webex.config.cc` on `{ webex }` init; read-only observable after init (Phase 1: re-init to change). Gates wxApp Mute/Keypad visibility and wxApp mute seed; SDK owns mute/DTMF API routing. | stable semver; renaming or removing the init key or store getter is breaking | `packages/contact-center/store/ai-docs/store-spec.md` (`STORE-R-030`); `packages/contact-center/task/ai-docs/task-spec.md` (WXCC-6026) | `packages/contact-center/store/src/store.ts`, `packages/contact-center/store/src/store.types.ts` (`WebexCcInitConfig`) |
 | store.types | `@webex/cc-store` | Existing queue/entry-point request, response, and entity type re-exports plus `TaskUIControls` | TypeScript exports describing the SDK-backed domain surface; established entity rows and Task destination controls pass through without a widget destination abstraction | stable semver; SDK-shaped types track SDK | `@webex/contact-center` types (`node_modules/@webex/contact-center/dist/types/index.d.ts`) (SDK source); `packages/contact-center/store/ai-docs/store-spec.md` | `packages/contact-center/store/src/store.types.ts` |
@@ -38,7 +41,8 @@ The aggregator package `@webex/cc-widgets` re-exports every widget plus the `sto
 | Dependency (service / package / datastore) | What is consumed | Schema / detail link | Availability assumption | Fallback on failure | Version floor |
 |---|---|---|---|---|---|
 | `@webex/contact-center` SDK | The entire CC runtime: `Webex.init()`, `webex.cc.*` methods, `ITask.dropConferenceParticipant({participantId})`, CC/task event stream, agent `Profile`, `webex.credentials.getUserToken()` | `@webex/contact-center` types (`node_modules/@webex/contact-center/dist/types/index.d.ts`); consumed only via the store/task object | Host establishes the authenticated Webex session; SDK and routing backend are assumed reachable and authoritative | `Store.init()` rejects after a 6s init timeout; participant Drop rejects and `CallControlCAD` shows generic feedback | Pinned by the SDK dependency in each package's `package.json`; Participant Drop requires the published SDK version recorded in the feature intake |
-| `@webex/contact-center` SDK | The CC runtime, including existing `getBuddyAgents`/`getQueues`/`getEntryPoints` methods, established queue records and entry-point response wrapper with mapped `number`, ordered Task destination controls, CC/task events, agent `Profile`, and host credentials | `@webex/contact-center` types (`node_modules/@webex/contact-center/dist/types/index.d.ts`); operations are consumed via the store and Task controls arrive on SDK task objects | Host establishes the authenticated Webex session; SDK assumed reachable | Store methods log and rethrow SDK failures; widget hooks apply their existing empty/error UI fallbacks | `3.12.0-next.109`, pinned by the store package dependency |
+| `@webex/contact-center` SDK | The CC runtime, including existing `getBuddyAgents`/`getQueues`/`getEntryPoints` methods, established queue records and entry-point response wrapper with mapped `number`, ordered Task destination controls, CC/task events, agent `Profile`, and host credentials | `@webex/contact-center` types (`node_modules/@webex/contact-center/dist/types/index.d.ts`); operations are consumed via the store and Task controls arrive on SDK task objects | Host establishes the authenticated Webex session; SDK assumed reachable | Store methods log and rethrow SDK failures; widget hooks apply their existing empty/error UI fallbacks | `3.12.0-next.131`, pinned by the store package dependency |
+| `@webex/contact-center` SDK — Agent Wellness Break | Effective `Profile.isWellnessBreakEnabled`, public `WellnessBreak` event and action constants/types, `getWellbeingBreakIdleCode()`, `setAgentState()`, identity-free `apiAIAssistant.requestWellnessBreak()` / `respondToWellnessBreak({action})`, and optional active `Profile.agentSessionId` on logged-in registration | Release contract in `ai-docs/features/agent-wellness-break-intake.md`; package-root declarations are authoritative | Registered-session projection requires the companion SDK release before refresh behavior can be verified | UI stays gated when session/system code is unavailable; no local SDK path or unpublished version is committed | Existing APIs: `3.12.0-next.131`; session projection: pending release |
 | `react` / `react-dom` (18) | Component runtime; consumer peer dependency | React docs | Provided by host or bundled | N/A (build-time/runtime peer) | React 18 |
 | `mobx` / `mobx-react-lite` | Store reactivity (`runInAction`, `observer`) | MobX docs | Bundled with store package | N/A | per `package.json` |
 | `@r2wc/react-to-web-component` | Wraps React widgets as custom elements (`packages/contact-center/cc-widgets/src/wc.ts:1`) | r2wc docs | Bundled with `cc-widgets` | N/A | per `package.json` |

ai-docs/SPEC_INDEX.md

@@ -16,7 +16,7 @@
 | `station-login/` | Agent login: team + device selection | DRAFT | `packages/contact-center/station-login/ai-docs/station-login-spec.md` |
 | `user-state/` | Agent state: state, idle codes, timer | DRAFT | `packages/contact-center/user-state/ai-docs/user-state-spec.md` |
 | `task/` | Task widget bundle: CallControl, IncomingTask, OutdialCall, TaskList, CallControlCAD | DRAFT | `packages/contact-center/task/ai-docs/task-spec.md` |
-| `ai-assistant/` | AI Assistant widget: chrome + Real-time Assist requests, transcript, feedback | DRAFT | `packages/contact-center/ai-assistant/ai-docs/ai-assistant-spec.md` |
+| `ai-assistant/` | AI Assistant widget: chrome, Real-time Assist, and Agent Wellness Break orchestration | DRAFT | `packages/contact-center/ai-assistant/ai-docs/ai-assistant-spec.md` |
 | `ui-logging/` | Metrics/telemetry: `withMetrics`, `metricsLogger` | DRAFT | `packages/contact-center/ui-logging/ai-docs/ui-logging-spec.md` |
 | `test-fixtures/` | Shared test mocks/helpers | DRAFT | `packages/contact-center/test-fixtures/ai-docs/test-fixtures-spec.md` |
 | `@webex/widgets/` | Legacy meetings widgets (separate family) | DRAFT | `packages/@webex/widgets/ai-docs/widgets-spec.md` |