@webex/contact-center 3.12.0-next.15 → 3.12.0-next.151

package/src/metrics/ai-docs/metrics-spec.md

@@ -0,0 +1,971 @@
+# Metrics — SPEC
+
+> Start here → root [`AGENTS.md`](../../../AGENTS.md) · router [`SPEC_INDEX.md`](../../../ai-docs/SPEC_INDEX.md) · system [`ARCHITECTURE.md`](../../../ai-docs/ARCHITECTURE.md). This is the module's canonical specification.
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Module id | `metrics` |
+| Source path(s) | `src/metrics` |
+| 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 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.
+
+## Source Material Register
+| Source material | Scope | Decision | Detail location or disposition |
+|---|---|---|---|
+| Reviewed prior module guides and architecture material | overview / architecture / API / tests | used and code-checked | Content is placed by meaning throughout this specification; exact routing remains in the manifest. |
+
+## Overview
+Metrics is one of nine confirmed Contact Center SDK modules. Own timing, taxonomy, queuing, payload preparation, and submission for Contact Center behavioral, operational, and business telemetry. Existing reviewed documentation is migrated by meaning and code/tests remain the behavioral referee.
+
+- **Singleton Pattern**: Single `MetricsManager` instance shared across the entire SDK
+
+- **Three Metric Types**: Behavioral (user actions), operational (system events), business (business-level analytics)
+
+- **Event Timing**: `timeEvent` + `trackEvent` pattern automatically calculates `duration_ms`
+
+- **Queued Submission**: Events are queued until the Webex SDK is ready, then submitted in order
+
+- **Behavioral Taxonomy**: Structured `product.agent.target.verb` naming convention for behavioral events
+
+- **Webex Together behavioral naming**: Webex Together (wxApp) events use `*_webex_together` compound targets (e.g. `wxcc_sdk.user.task_accept_webex_together.complete`). Operational/business wire names remain `WXCC_SDK_WXAPP_*` unchanged.
+
+- **Payload Preparation**: Automatic cleanup of empty fields, space-to-underscore conversion, and `tabHidden` metadata
+
+- **AQM Response Helpers**: Static methods to extract common tracking fields from AQM responses
+
+## Purpose / Responsibility
+Own timing, taxonomy, queuing, payload preparation, and submission for Contact Center behavioral, operational, and business telemetry.
+
+## Stack
+TypeScript 5.4 singleton service, Webex internal metrics APIs, LoggerProxy, Jest 27.
+
+## Folder / Package Structure
+```text
+src/metrics/
+├── MetricsManager.ts
+├── behavioral-events.ts
+├── constants.ts
+```
+
+```text
+src/metrics/
+├── MetricsManager.ts       # Singleton metrics manager
+├── behavioral-events.ts    # Behavioral event taxonomy mapping
+├── constants.ts            # METRIC_EVENT_NAMES constants
+└── ai-docs/
+    ├── AGENTS.md           # Usage documentation (see PR #4762)
+    └── ARCHITECTURE.md     # Preserved legacy, noncanonical architecture guide
+```
+
+## Key Files (source of truth)
+| File | Holds |
+|---|---|
+| `src/metrics/MetricsManager.ts` | Authoritative Metrics implementation or contract source. |
+| `src/metrics/behavioral-events.ts` | Authoritative Metrics implementation or contract source. |
+| `src/metrics/constants.ts` | Authoritative Metrics implementation or contract source. |
+
+## Public Surface
+| Contract ID | Type | Surface | Purpose | Compatibility / deprecation | Schema / detail link | Root index |
+|---|---|---|---|---|---|---|
+| `metrics.surface` | SDK / event / internal API | Internal `MetricsManager` singleton, metric event constants, taxonomy lookup, timing, and tracking helpers. | Stable module consumption boundary. | Additive changes by default; breaking package exports require a major-version transition. | `src/metrics/MetricsManager.ts` | `../../../ai-docs/CONTRACTS.md` |
+
+Compatibility notes:
+- Do not remove or reinterpret exported symbols/events without a documented consumer migration.
+
+Returns the singleton instance. On first call with `{webex}`, binds to the Webex SDK and begins listening for the `ready` event.
+
+**Parameters**:
+
+- `options` (object, optional): `{webex: WebexSDK}` - The Webex SDK instance
+
+**Returns**: `MetricsManager`
+
+**Example**:
+
+```typescript
+// During initialization (called internally by cc.register())
+const metrics = MetricsManager.getInstance({webex});
+
+// Subsequent calls (no webex needed)
+const metrics = MetricsManager.getInstance();
+```
+
+Starts a timer for one or more event keys. When a matching `trackEvent` / `trackBehavioralEvent` / `trackOperationalEvent` / `trackBusinessEvent` is called, `duration_ms` is automatically added to the payload.
+
+**Parameters**:
+
+- `keys` (string | string[]): One or more `METRIC_EVENT_NAMES` values. The first key is the tracking key; all keys in the array will resolve the same timer.
+
+**Returns**: `void`
+
+**Example**:
+
+```typescript
+// Single key
+metrics.timeEvent(METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS);
+
+// Multiple keys (success/failure share one timer)
+metrics.timeEvent([
+  METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS,
+  METRIC_EVENT_NAMES.STATION_LOGIN_FAILED,
+]);
+```
+
+Tracks an event across one or more metric services.
+
+**Parameters**:
+
+- `name` (METRIC_EVENT_NAMES): The event name constant
+
+- `payload` (EventPayload, optional): Key-value pairs of event data
+
+- `metricServices` (MetricsType[], optional): Array of `'behavioral'` | `'operational'` | `'business'` (default: `['behavioral']`)
+
+**Returns**: `void`
+
+**Example**:
+
+```typescript
+// Behavioral only (default)
+metrics.trackEvent(METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS, {agentId: '123'});
+
+// Multiple services
+metrics.trackEvent(
+  METRIC_EVENT_NAMES.TASK_ACCEPT_SUCCESS,
+  {interactionId: 'abc'},
+  ['behavioral', 'operational']
+);
+```
+
+Tracks a single behavioral event. Looks up the event taxonomy from `behavioral-events.ts` and submits via `webex.internal.newMetrics.submitBehavioralEvent`.
+
+**Parameters**:
+
+- `name` (METRIC_EVENT_NAMES): The event name
+
+- `options` (EventPayload, optional): Additional payload data
+
+**Returns**: `void`
+
+Tracks a single operational event. Prefixes the event name with `WXCC_SDK_` and submits via `webex.internal.newMetrics.submitOperationalEvent`.
+
+**Parameters**:
+
+- `name` (METRIC_EVENT_NAMES): The event name
+
+- `options` (EventPayload, optional): Additional payload data
+
+**Returns**: `void`
+
+Tracks a single business event. Prefixes the event name with `WXCC_SDK_` and submits via `webex.internal.newMetrics.submitBusinessEvent` with `appType: 'wxcc_sdk'`.
+
+**Parameters**:
+
+- `name` (METRIC_EVENT_NAMES): The event name
+
+- `options` (EventPayload, optional): Additional payload data
+
+**Returns**: `void`
+
+Enables or disables metrics collection. When disabled, all pending events are cleared and new events are dropped.
+
+**Parameters**:
+
+- `disabled` (boolean): `true` to disable, `false` to enable
+
+**Returns**: `void`
+
+Static helper that extracts common tracking fields from an AQM success response.
+
+**Parameters**:
+
+- `response` (any): The AQM response object
+
+**Returns**: `Record<string, any>` with fields: `agentId`, `agentSessionId`, `teamId`, `siteId`, `orgId`, `eventType`, `trackingId`, `notifTrackingId`
+
+**Example**:
+
+```typescript
+const fields = MetricsManager.getCommonTrackingFieldForAQMResponse(aqmResponse);
+metrics.trackEvent(METRIC_EVENT_NAMES.TASK_ACCEPT_SUCCESS, {
+  ...fields,
+  interactionId: task.interactionId,
+});
+```
+
+Resets the singleton instance. Used for testing only.
+
+**Returns**: `void`
+
+All event names are defined in `METRIC_EVENT_NAMES` (`constants.ts`). Events follow a `<Category> <Action> <Result>` pattern.
+
+| Constant | Value | Description |
+|---|---|---|
+| `STATION_LOGIN_SUCCESS` | `'Station Login Success'` | Agent station login succeeded |
+| `STATION_LOGIN_FAILED` | `'Station Login Failed'` | Agent station login failed |
+| `STATION_LOGOUT_SUCCESS` | `'Station Logout Success'` | Agent station logout succeeded |
+| `STATION_LOGOUT_FAILED` | `'Station Logout Failed'` | Agent station logout failed |
+| `STATION_RELOGIN_SUCCESS` | `'Station Relogin Success'` | Silent relogin succeeded |
+| `STATION_RELOGIN_FAILED` | `'Station Relogin Failed'` | Silent relogin failed |
+| `AGENT_STATE_CHANGE_SUCCESS` | `'Agent State Change Success'` | State change succeeded |
+| `AGENT_STATE_CHANGE_FAILED` | `'Agent State Change Failed'` | State change failed |
+| `FETCH_BUDDY_AGENTS_SUCCESS` | `'Fetch Buddy Agents Success'` | Buddy agents fetch succeeded |
+| `FETCH_BUDDY_AGENTS_FAILED` | `'Fetch Buddy Agents Failed'` | Buddy agents fetch failed |
+| `AGENT_RONA` | `'Agent RONA'` | Agent Ring-On-No-Answer triggered |
+| `AGENT_CONTACT_ASSIGN_FAILED` | `'Agent Contact Assign Failed'` | Contact assignment failed |
+| `AGENT_INVITE_FAILED` | `'Agent Invite Failed'` | Agent invite failed |
+| `AGENT_DEVICE_TYPE_UPDATE_SUCCESS` | `'Agent Device Type Update Success'` | Device type update succeeded |
+| `AGENT_DEVICE_TYPE_UPDATE_FAILED` | `'Agent Device Type Update Failed'` | Device type update failed |
+| `TASK_ACCEPT_SUCCESS` / `FAILED` | `'Task Accept ...'` | Task accept result |
+| `TASK_DECLINE_SUCCESS` / `FAILED` | `'Task Decline ...'` | Task decline result |
+| `TASK_END_SUCCESS` / `FAILED` | `'Task End ...'` | Task end result |
+| `TASK_WRAPUP_SUCCESS` / `FAILED` | `'Task Wrapup ...'` | Task wrapup result |
+| `TASK_HOLD_SUCCESS` / `FAILED` | `'Task Hold ...'` | Task hold result |
+| `TASK_RESUME_SUCCESS` / `FAILED` | `'Task Resume ...'` | Task resume result |
+| `TASK_CONSULT_START_SUCCESS` / `FAILED` | `'Task Consult Start ...'` | Consult start result |
+| `TASK_CONSULT_END_SUCCESS` / `FAILED` | `'Task Consult End ...'` | Consult end result |
+| `TASK_TRANSFER_SUCCESS` / `FAILED` | `'Task Transfer ...'` | Transfer result |
+| `TASK_PAUSE_RECORDING_SUCCESS` / `FAILED` | `'Task Pause Recording ...'` | Pause recording result |
+| `TASK_RESUME_RECORDING_SUCCESS` / `FAILED` | `'Task Resume Recording ...'` | Resume recording result |
+| `TASK_ACCEPT_CONSULT_SUCCESS` / `FAILED` | `'Task Accept Consult ...'` | Accept consult result |
+| `TASK_AUTO_ANSWER_SUCCESS` / `FAILED` | `'Task Auto Answer ...'` | Auto-answer result |
+| `TASK_OUTDIAL_SUCCESS` / `FAILED` | `'Task Outdial ...'` | Outdial result |
+| `WXAPP_TASK_MUTE_SUCCESS` / `FAILED` | `'WxApp Task Mute ...'` | Webex Together task mute/unmute toggle (`wxcc_sdk.user.task_mute_webex_together.complete\|fail`). Mute telephony is queued per task via tail promise chain (`Voice.wxAppMuteToggleTail`) so concurrent toggles do not overwrite the shared `timeEvent` timer or reorder requests. |
+| `WXAPP_TASK_DTMF_SUCCESS` / `FAILED` | `'WxApp Task Dtmf ...'` | Webex Together DTMF/keypad (`wxcc_sdk.user.task_dtmf_webex_together.complete\|fail`). DTMF telephony is queued per task via tail promise chain (`Voice.wxAppDtmfTail`) so concurrent keypad input does not overwrite the shared `timeEvent` timer or reorder digits. |
+| `WXAPP_TASK_ACCEPT_SUCCESS` / `FAILED` | `'WxApp Task Accept ...'` | Webex Together accept/answer (`wxcc_sdk.user.task_accept_webex_together.complete\|fail`) |
+| `WXAPP_TASK_DECLINE_SUCCESS` / `FAILED` | `'WxApp Task Decline ...'` | Webex Together reject/decline (`wxcc_sdk.user.task_reject_webex_together.complete\|fail`). Inbound offers: telephony `rejectCall` via `runWxAppReject`. wxApp outdial cancellations: CC `cancelTask` via `runWxAppOutdialDecline` (additive with `TASK_DECLINE_*`). Outdial failure payloads merge AQM `error.details` via `getCommonTrackingFieldForAQMResponseFailed` so wxApp metrics and diagnostic logs preserve `trackingId` / structured failure reason. |
+| `WXAPP_SESSION_INIT_SUCCESS` / `FAILED` | `'WxApp Session Init ...'` | Webex Together session orchestration (`wxcc_sdk.user.webex_together_session_init.complete\|fail`) |
+| `WXAPP_SESSION_SKIPPED` | `'WxApp Session Skipped'` | Webex Together session skipped (`wxcc_sdk.user.webex_together_session_init.ignore`) |
+| `WXAPP_USERSUB_PUBLISH_SUCCESS` / `FAILED` | `'WxApp Usersub Publish ...'` | Cross-client usersub publish (`wxcc_sdk.user.webex_together_usersub_publish.complete\|fail`). Preflight failures (missing `userId` or device URL before HTTP publish) emit `WXAPP_USERSUB_PUBLISH_FAILED` with `skipReason` (`user_id_unavailable` / `device_url_unavailable`) and no `timeEvent` timer. Stale-generation discards (teardown or concurrent disable while HTTP publish is in flight) call `cancelTimedEvent` without emitting success/fail only when the completing publish still owns the active timer (`usersubPublishMetricsId` guard — a newer overlapping publish must not have its timer cleared). |
+| `WXAPP_MERCURY_SUBSCRIBE_SUCCESS` / `FAILED` | `'WxApp Mercury Subscribe ...'` | Telephony Mercury mute-sync subscribe (`wxcc_sdk.user.webex_together_mercury_subscribe.complete\|fail`) |
+| `WXAPP_OFFER_PARTICIPANT_FIELDS_MISSING` | `'WxApp Offer Participant Fields Missing'` | Read-only observability when usersub is active but inbound OFFERED participant **still** lacks valid wxApp fields after a **500 ms grace period** (orchestrated in `voice/wxAppOfferObservability.ts`; avoids false alarms from transient WS ordering). After usersub publish, `TaskManager.refreshWxAppOfferObservabilityForAllTasks()` re-runs the observer so a pre-publish OFFERED task can still schedule grace. Task removal calls `disposeWxAppOfferObservability()` so a pending timer cannot emit after `CONTACT_MERGED` / collection drop. Emitted with matching `[CC wxApp] participant fields mismatch` WARN (`wxcc_sdk.user.webex_together_offer_participant_fields.fail`) |
+| `TASK_CONFERENCE_START_SUCCESS` / `FAILED` | `'Task Conference Start ...'` | Conference start result |
+| `TASK_CONFERENCE_END_SUCCESS` / `FAILED` | `'Task Conference End ...'` | Conference end result |
+| `TASK_CONFERENCE_TRANSFER_SUCCESS` / `FAILED` | `'Task Conference Transfer ...'` | Conference transfer result |
+| `TASK_CONFERENCE_EXIT_SUCCESS` / `FAILED` | `'Task Conference Exit ...'` | Conference exit result |
+| `TASK_CONFERENCE_PARTICIPANT_DROP_SUCCESS` / `FAILED` | `'Task Conference Participant Drop ...'` | Participant Drop result |
+| `TASK_SWITCH_CALL_SUCCESS` / `FAILED` | `'Task Switch Call ...'` | Switch call result |
+| `WEBSOCKET_REGISTER_SUCCESS` / `FAILED` | `'Websocket Register ...'` | WebSocket registration result |
+| `WEBSOCKET_DEREGISTER_SUCCESS` / `FAIL` | `'Websocket Deregister ...'` | WebSocket deregistration result |
+| `WEBSOCKET_EVENT_RECEIVED` | `'Websocket Event Received'` | WebSocket event received |
+| `UPLOAD_LOGS_SUCCESS` / `FAILED` | `'Upload Logs ...'` | Log upload result |
+| `ENTRYPOINT_FETCH_SUCCESS` / `FAILED` | `'Entrypoint Fetch ...'` | Entry point fetch result |
+| `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:
+
+| Category               | Success Event                          | Failure Event                          |
+|---|---|---|
+| Station Login          | `STATION_LOGIN_SUCCESS`                | `STATION_LOGIN_FAILED`                 |
+| Station Logout         | `STATION_LOGOUT_SUCCESS`               | `STATION_LOGOUT_FAILED`                |
+| Station Relogin        | `STATION_RELOGIN_SUCCESS`              | `STATION_RELOGIN_FAILED`               |
+| State Change           | `AGENT_STATE_CHANGE_SUCCESS`           | `AGENT_STATE_CHANGE_FAILED`            |
+| Buddy Agents           | `FETCH_BUDDY_AGENTS_SUCCESS`           | `FETCH_BUDDY_AGENTS_FAILED`            |
+| WebSocket Register     | `WEBSOCKET_REGISTER_SUCCESS`           | `WEBSOCKET_REGISTER_FAILED`            |
+| Task Accept            | `TASK_ACCEPT_SUCCESS`                  | `TASK_ACCEPT_FAILED`                   |
+| Task Decline           | `TASK_DECLINE_SUCCESS`                 | `TASK_DECLINE_FAILED`                  |
+| Task End               | `TASK_END_SUCCESS`                     | `TASK_END_FAILED`                      |
+| Task Wrapup            | `TASK_WRAPUP_SUCCESS`                  | `TASK_WRAPUP_FAILED`                   |
+| Task Hold              | `TASK_HOLD_SUCCESS`                    | `TASK_HOLD_FAILED`                     |
+| Task Resume            | `TASK_RESUME_SUCCESS`                  | `TASK_RESUME_FAILED`                   |
+| Task Consult Start     | `TASK_CONSULT_START_SUCCESS`           | `TASK_CONSULT_START_FAILED`            |
+| Task Consult End       | `TASK_CONSULT_END_SUCCESS`             | `TASK_CONSULT_END_FAILED`              |
+| Task Transfer          | `TASK_TRANSFER_SUCCESS`                | `TASK_TRANSFER_FAILED`                 |
+| Task Resume Recording  | `TASK_RESUME_RECORDING_SUCCESS`        | `TASK_RESUME_RECORDING_FAILED`         |
+| Task Pause Recording   | `TASK_PAUSE_RECORDING_SUCCESS`         | `TASK_PAUSE_RECORDING_FAILED`          |
+| Task Accept Consult    | `TASK_ACCEPT_CONSULT_SUCCESS`          | `TASK_ACCEPT_CONSULT_FAILED`           |
+| Task Auto Answer       | `TASK_AUTO_ANSWER_SUCCESS`             | `TASK_AUTO_ANSWER_FAILED`              |
+| Conference Start       | `TASK_CONFERENCE_START_SUCCESS`        | `TASK_CONFERENCE_START_FAILED`         |
+| Conference End         | `TASK_CONFERENCE_END_SUCCESS`          | `TASK_CONFERENCE_END_FAILED`           |
+| Conference Transfer    | `TASK_CONFERENCE_TRANSFER_SUCCESS`     | `TASK_CONFERENCE_TRANSFER_FAILED`      |
+| Conference Exit        | `TASK_CONFERENCE_EXIT_SUCCESS`         | `TASK_CONFERENCE_EXIT_FAILED`          |
+| Conference Participant Drop | `TASK_CONFERENCE_PARTICIPANT_DROP_SUCCESS` | `TASK_CONFERENCE_PARTICIPANT_DROP_FAILED` |
+| Switch Call            | `TASK_SWITCH_CALL_SUCCESS`             | `TASK_SWITCH_CALL_FAILED`              |
+| Outdial                | `TASK_OUTDIAL_SUCCESS`                 | `TASK_OUTDIAL_FAILED`                  |
+| WxApp Task Mute        | `WXAPP_TASK_MUTE_SUCCESS`              | `WXAPP_TASK_MUTE_FAILED`               |
+| WxApp Task DTMF        | `WXAPP_TASK_DTMF_SUCCESS`              | `WXAPP_TASK_DTMF_FAILED`               |
+| WxApp Task Accept      | `WXAPP_TASK_ACCEPT_SUCCESS`            | `WXAPP_TASK_ACCEPT_FAILED`             |
+| WxApp Task Decline     | `WXAPP_TASK_DECLINE_SUCCESS`           | `WXAPP_TASK_DECLINE_FAILED`            |
+| WxApp Session Init     | `WXAPP_SESSION_INIT_SUCCESS`           | `WXAPP_SESSION_INIT_FAILED`            |
+| WxApp Usersub Publish  | `WXAPP_USERSUB_PUBLISH_SUCCESS`        | `WXAPP_USERSUB_PUBLISH_FAILED`         |
+| WxApp Mercury Subscribe | `WXAPP_MERCURY_SUBSCRIBE_SUCCESS`     | `WXAPP_MERCURY_SUBSCRIBE_FAILED`       |
+| WxApp Offer Participant Fields | —                              | `WXAPP_OFFER_PARTICIPANT_FIELDS_MISSING` |
+| Upload Logs            | `UPLOAD_LOGS_SUCCESS`                  | `UPLOAD_LOGS_FAILED`                   |
+| WebSocket Deregister   | `WEBSOCKET_DEREGISTER_SUCCESS`         | `WEBSOCKET_DEREGISTER_FAIL`            |
+| Device Type Update     | `AGENT_DEVICE_TYPE_UPDATE_SUCCESS`     | `AGENT_DEVICE_TYPE_UPDATE_FAILED`      |
+| EntryPoint             | `ENTRYPOINT_FETCH_SUCCESS`             | `ENTRYPOINT_FETCH_FAILED`              |
+| AddressBook            | `ADDRESSBOOK_FETCH_SUCCESS`            | `ADDRESSBOOK_FETCH_FAILED`             |
+| Queue                  | `QUEUE_FETCH_SUCCESS`                  | `QUEUE_FETCH_FAILED`                   |
+| Outdial ANI Entries    | `OUTDIAL_ANI_EP_FETCH_SUCCESS`         | `OUTDIAL_ANI_EP_FETCH_FAILED`          |
+
+### Webex Together behavioral taxonomy
+
+Webex Together events (`WXAPP_*` constants) use `*_webex_together` compound targets. Assembled Amplitude names follow `wxcc_sdk.user.{target}.{verb}`:
+
+| Feature | Behavioral target | Success name | Failure name | Skip name |
+|---|---|---|---|---|
+| Task accept / answer | `task_accept_webex_together` | `wxcc_sdk.user.task_accept_webex_together.complete` | `wxcc_sdk.user.task_accept_webex_together.fail` | — |
+| Task reject / decline | `task_reject_webex_together` | `wxcc_sdk.user.task_reject_webex_together.complete` | `wxcc_sdk.user.task_reject_webex_together.fail` | — |
+| Task mute / unmute toggle | `task_mute_webex_together` | `wxcc_sdk.user.task_mute_webex_together.complete` | `wxcc_sdk.user.task_mute_webex_together.fail` | — |
+| Task DTMF / keypad | `task_dtmf_webex_together` | `wxcc_sdk.user.task_dtmf_webex_together.complete` | `wxcc_sdk.user.task_dtmf_webex_together.fail` | — |
+| Usersub publish | `webex_together_usersub_publish` | `wxcc_sdk.user.webex_together_usersub_publish.complete` | `wxcc_sdk.user.webex_together_usersub_publish.fail` | — |
+| Mercury subscribe | `webex_together_mercury_subscribe` | `wxcc_sdk.user.webex_together_mercury_subscribe.complete` | `wxcc_sdk.user.webex_together_mercury_subscribe.fail` | — |
+| Session init | `webex_together_session_init` | `wxcc_sdk.user.webex_together_session_init.complete` | `wxcc_sdk.user.webex_together_session_init.fail` | `wxcc_sdk.user.webex_together_session_init.ignore` |
+| Offer participant fields | `webex_together_offer_participant_fields` | — | `wxcc_sdk.user.webex_together_offer_participant_fields.fail` | — |
+
+Operational and business wire names are unchanged (`WXCC_SDK_WXAPP_*`).
+
+### WxApp metric payload fields (operational / behavioral tags)
+
+| Event | Payload fields (booleans/enums; no raw IDs) |
+|---|---|
+| `WXAPP_SESSION_INIT_SUCCESS` | `loginOption`, `enableWxBetterTogether`, `usersubPublished`, `mercurySubscribed`, `telephonyTaskType` |
+| `WXAPP_SESSION_INIT_FAILED` | above + `skipReason` (`usersub_not_published`, `mercury_not_subscribed`, `mercury_subscribe_failed`, `publish_failed`) + optional `error`. `usersubPublished` reflects **retained session state** (`isAnswerCallsStateActive()` / `answerCallsState`), including on catch-path failures — not gated on the current init attempt's `publishedEnable`. |
+| `WXAPP_USERSUB_PUBLISH_SUCCESS` | `enableWxBetterTogether`, `usersubPublished` |
+| `WXAPP_USERSUB_PUBLISH_FAILED` | `enableWxBetterTogether`, `usersubPublished`, optional `skipReason`, `error`. `usersubPublished` reflects **retained session state** (`answerCallsState`), not the requested enable value — a failed disable/refresh while usersub remains active reports `true`. |
+| `WXAPP_MERCURY_SUBSCRIBE_SUCCESS` | `mercurySubscribed: true` |
+| `WXAPP_MERCURY_SUBSCRIBE_FAILED` | `mercurySubscribed: false`, `error` |
+| `WXAPP_TASK_ACCEPT_*` / `DECLINE_*` | `taskId`, `hasDeviceCallId`, `hasDeviceId`, optional `acceptReason`; failures add `trackingId` when available. `acceptReason` is captured **before** the telephony REST call (not hard-coded `wxApp_offer_ready`) so success and failure both retain `wxApp_answer_pending` / `wxApp_accept_in_flight` when those flags were already set. Outdial-cancel AQM failures (`error.details`) include the same participant context fields via `getWxAppTelephonyMetricContext` merged with AQM correlation fields. Outdial cancel during post-accept pending phase may report `acceptReason: wxApp_answer_pending`. |
+| `WXAPP_TASK_MUTE_*` / `DTMF_*` | `taskId`, `hasDeviceCallId`, `hasDeviceId`; failures add `trackingId` when available |
+| `WXAPP_OFFER_PARTICIPANT_FIELDS_MISSING` | `taskId`, `usersubPublished`, `hasDeviceCallId`, `hasDeviceId`, `acceptReason` |
+
+### Customer console log triage (MMT / support)
+
+Customers often embed with `logger.level: 'log'`. wxApp diagnostics use **`LoggerProxy.log`** / **`warn`** / **`error`** with prefix **`[CC wxApp]`** and grep-friendly `key=value` suffixes on the message string (fields also appear in structured `data`).
+
+| Search in browser console | Meaning |
+|---|---|
+| `[CC wxApp]` | All wxApp diagnostic lines (primary search) |
+| `WXCC_SDK_WXAPP` | Operational metric wire names (name only in console; payloads go to backend) |
+| `session readiness` | usersub + Mercury state after station login |
+| `offer decision` | Why Accept is visible/enabled; includes `acceptReason`, `hasDeviceCallId`, `usersubPublished` |
+| `participant fields mismatch` | usersub active but WS participant **still** missing wxApp triple after ~500 ms (transient gaps on first OFFERED tick are normal — look for `wxApp_offer_ready` within 1 s) |
+| `telephony accept failed` | REST answer failure; includes `trackingId` when available |
+
+Do **not** search `WXAPP` alone — it matches metric wire names but misses `[CC wxApp]` diagnostic lines.
+
+Example lines at `logger.level: 'log'`:
+
+```text
+PLUGIN_CC - [LOG]: ... [CC wxApp] session readiness usersubPublished=true mercurySubscribed=true loginOption=EXTENSION ...
+PLUGIN_CC - [LOG]: ... [CC wxApp] offer decision acceptReason=wxApp_offer_ready hasDeviceCallId=true usersubPublished=true interactionId=...
+PLUGIN_CC - [WARN]: ... [CC wxApp] participant fields mismatch usersubPublished=true hasDeviceCallId=false acceptReason=extension_non_wxApp_offer interactionId=...
+PLUGIN_CC - [LOG]: ... operational-events -> @submitEvent. Submit event: WXCC_SDK_WXAPP_TASK_ACCEPT_SUCCESS
+```
+
+Special events (no success/failure pair):
+
+- `AGENT_RONA` — has behavioral taxonomy (`service.agent_rona.set`)
+
+- `AGENT_CONTACT_ASSIGN_FAILED` — has behavioral taxonomy (`service.agent_contact_assign.fail`)
+
+- `AGENT_INVITE_FAILED` — has behavioral taxonomy (`service.agent_invite.fail`)
+
+- `WEBSOCKET_EVENT_RECEIVED` — **no** behavioral taxonomy (not in `eventTaxonomyMap`)
+
+- `WXAPP_SESSION_SKIPPED` — has behavioral taxonomy (`wxcc_sdk.user.webex_together_session_init.ignore`)
+
+Of the 121 defined metric names, 97 have behavioral taxonomy and 24 do not. The unmapped names are the eight original `AI_ASSISTANT_*` names, three Agent Wellness Break `AI_ASSISTANT_WELLNESS_*` names, two `WELLBEING_BREAK_IDLE_CODE_FETCH_*` names, eight `AI_SUMMARY_*` names, and three WebSocket names (`WEBSOCKET_DEREGISTER_SUCCESS`, `WEBSOCKET_DEREGISTER_FAIL`, and `WEBSOCKET_EVENT_RECEIVED`). Agent Wellness Break and AI summary metrics are intentionally operational-only.
+
+### Complete METRIC_EVENT_NAMES catalog
+
+This table contains all 121 names from `src/metrics/constants.ts`; taxonomy presence is checked against `src/metrics/behavioral-events.ts`: 97 mapped and 24 unmapped.
+
+| Constant | Emitted name | Behavioral taxonomy? |
+|---|---|---|
+| `STATION_LOGIN_SUCCESS` | `Station Login Success` | yes |
+| `STATION_LOGIN_FAILED` | `Station Login Failed` | yes |
+| `STATION_LOGOUT_SUCCESS` | `Station Logout Success` | yes |
+| `STATION_LOGOUT_FAILED` | `Station Logout Failed` | yes |
+| `STATION_RELOGIN_SUCCESS` | `Station Relogin Success` | yes |
+| `STATION_RELOGIN_FAILED` | `Station Relogin Failed` | yes |
+| `AGENT_STATE_CHANGE_SUCCESS` | `Agent State Change Success` | yes |
+| `AGENT_STATE_CHANGE_FAILED` | `Agent State Change Failed` | yes |
+| `FETCH_BUDDY_AGENTS_SUCCESS` | `Fetch Buddy Agents Success` | yes |
+| `FETCH_BUDDY_AGENTS_FAILED` | `Fetch Buddy Agents Failed` | yes |
+| `WEBSOCKET_REGISTER_SUCCESS` | `Websocket Register Success` | yes |
+| `WEBSOCKET_REGISTER_FAILED` | `Websocket Register Failed` | yes |
+| `AGENT_RONA` | `Agent RONA` | yes |
+| `AGENT_CONTACT_ASSIGN_FAILED` | `Agent Contact Assign Failed` | yes |
+| `AGENT_INVITE_FAILED` | `Agent Invite Failed` | yes |
+| `TASK_ACCEPT_SUCCESS` | `Task Accept Success` | yes |
+| `TASK_ACCEPT_FAILED` | `Task Accept Failed` | yes |
+| `TASK_DECLINE_SUCCESS` | `Task Decline Success` | yes |
+| `TASK_DECLINE_FAILED` | `Task Decline Failed` | yes |
+| `TASK_END_SUCCESS` | `Task End Success` | yes |
+| `TASK_END_FAILED` | `Task End Failed` | yes |
+| `TASK_WRAPUP_SUCCESS` | `Task Wrapup Success` | yes |
+| `TASK_WRAPUP_FAILED` | `Task Wrapup Failed` | yes |
+| `TASK_HOLD_SUCCESS` | `Task Hold Success` | yes |
+| `TASK_HOLD_FAILED` | `Task Hold Failed` | yes |
+| `TASK_RESUME_SUCCESS` | `Task Resume Success` | yes |
+| `TASK_RESUME_FAILED` | `Task Resume Failed` | yes |
+| `TASK_CONSULT_START_SUCCESS` | `Task Consult Start Success` | yes |
+| `TASK_CONSULT_START_FAILED` | `Task Consult Start Failed` | yes |
+| `TASK_CONSULT_END_SUCCESS` | `Task Consult End Success` | yes |
+| `TASK_CONSULT_END_FAILED` | `Task Consult End Failed` | yes |
+| `TASK_TRANSFER_SUCCESS` | `Task Transfer Success` | yes |
+| `TASK_TRANSFER_FAILED` | `Task Transfer Failed` | yes |
+| `TASK_RESUME_RECORDING_SUCCESS` | `Task Resume Recording Success` | yes |
+| `TASK_RESUME_RECORDING_FAILED` | `Task Resume Recording Failed` | yes |
+| `TASK_PAUSE_RECORDING_SUCCESS` | `Task Pause Recording Success` | yes |
+| `TASK_PAUSE_RECORDING_FAILED` | `Task Pause Recording Failed` | yes |
+| `TASK_ACCEPT_CONSULT_SUCCESS` | `Task Accept Consult Success` | yes |
+| `TASK_ACCEPT_CONSULT_FAILED` | `Task Accept Consult Failed` | yes |
+| `TASK_AUTO_ANSWER_SUCCESS` | `Task Auto Answer Success` | yes |
+| `TASK_AUTO_ANSWER_FAILED` | `Task Auto Answer Failed` | yes |
+| `TASK_CONFERENCE_START_SUCCESS` | `Task Conference Start Success` | yes |
+| `TASK_CONFERENCE_START_FAILED` | `Task Conference Start Failed` | yes |
+| `TASK_CONFERENCE_END_SUCCESS` | `Task Conference End Success` | yes |
+| `TASK_CONFERENCE_END_FAILED` | `Task Conference End Failed` | yes |
+| `TASK_CONFERENCE_TRANSFER_SUCCESS` | `Task Conference Transfer Success` | yes |
+| `TASK_CONFERENCE_TRANSFER_FAILED` | `Task Conference Transfer Failed` | yes |
+| `TASK_CONFERENCE_EXIT_SUCCESS` | `Task Conference Exit Success` | yes |
+| `TASK_CONFERENCE_EXIT_FAILED` | `Task Conference Exit Failed` | yes |
+| `TASK_CONFERENCE_PARTICIPANT_DROP_SUCCESS` | `Task Conference Participant Drop Success` | yes |
+| `TASK_CONFERENCE_PARTICIPANT_DROP_FAILED` | `Task Conference Participant Drop Failed` | yes |
+| `TASK_SWITCH_CALL_SUCCESS` | `Task Switch Call Success` | yes |
+| `TASK_SWITCH_CALL_FAILED` | `Task Switch Call Failed` | yes |
+| `TASK_OUTDIAL_SUCCESS` | `Task Outdial Success` | yes |
+| `TASK_OUTDIAL_FAILED` | `Task Outdial Failed` | yes |
+| `WXAPP_TASK_MUTE_SUCCESS` | `WxApp Task Mute Success` | yes |
+| `WXAPP_TASK_MUTE_FAILED` | `WxApp Task Mute Failed` | yes |
+| `WXAPP_TASK_DTMF_SUCCESS` | `WxApp Task Dtmf Success` | yes |
+| `WXAPP_TASK_DTMF_FAILED` | `WxApp Task Dtmf Failed` | yes |
+| `WXAPP_TASK_ACCEPT_SUCCESS` | `WxApp Task Accept Success` | yes |
+| `WXAPP_TASK_ACCEPT_FAILED` | `WxApp Task Accept Failed` | yes |
+| `WXAPP_TASK_DECLINE_SUCCESS` | `WxApp Task Decline Success` | yes |
+| `WXAPP_TASK_DECLINE_FAILED` | `WxApp Task Decline Failed` | yes |
+| `WXAPP_SESSION_INIT_SUCCESS` | `WxApp Session Init Success` | yes |
+| `WXAPP_SESSION_INIT_FAILED` | `WxApp Session Init Failed` | yes |
+| `WXAPP_SESSION_SKIPPED` | `WxApp Session Skipped` | yes |
+| `WXAPP_USERSUB_PUBLISH_SUCCESS` | `WxApp Usersub Publish Success` | yes |
+| `WXAPP_USERSUB_PUBLISH_FAILED` | `WxApp Usersub Publish Failed` | yes |
+| `WXAPP_MERCURY_SUBSCRIBE_SUCCESS` | `WxApp Mercury Subscribe Success` | yes |
+| `WXAPP_MERCURY_SUBSCRIBE_FAILED` | `WxApp Mercury Subscribe Failed` | yes |
+| `WXAPP_OFFER_PARTICIPANT_FIELDS_MISSING` | `WxApp Offer Participant Fields Missing` | yes |
+| `UPLOAD_LOGS_SUCCESS` | `Upload Logs Success` | yes |
+| `UPLOAD_LOGS_FAILED` | `Upload Logs Failed` | yes |
+| `WEBSOCKET_DEREGISTER_SUCCESS` | `Websocket Deregister Success` | no |
+| `WEBSOCKET_DEREGISTER_FAIL` | `Websocket Deregister Failed` | no |
+| `AGENT_DEVICE_TYPE_UPDATE_SUCCESS` | `Agent Device Type Update Success` | yes |
+| `AGENT_DEVICE_TYPE_UPDATE_FAILED` | `Agent Device Type Update Failed` | yes |
+| `WEBSOCKET_EVENT_RECEIVED` | `Websocket Event Received` | no |
+| `ENTRYPOINT_FETCH_SUCCESS` | `Entrypoint Fetch Success` | yes |
+| `ENTRYPOINT_FETCH_FAILED` | `Entrypoint Fetch Failed` | yes |
+| `ADDRESSBOOK_FETCH_SUCCESS` | `AddressBook Fetch Success` | yes |
+| `ADDRESSBOOK_FETCH_FAILED` | `AddressBook Fetch Failed` | yes |
+| `QUEUE_FETCH_SUCCESS` | `Queue Fetch Success` | yes |
+| `QUEUE_FETCH_FAILED` | `Queue Fetch Failed` | yes |
+| `OUTDIAL_ANI_EP_FETCH_SUCCESS` | `Outdial ANI Entries Fetch Success` | yes |
+| `OUTDIAL_ANI_EP_FETCH_FAILED` | `Outdial ANI Entries Fetch Failed` | yes |
+| `CAMPAIGN_PREVIEW_ACCEPT_SUCCESS` | `Campaign Preview Accept Success` | yes |
+| `CAMPAIGN_PREVIEW_ACCEPT_FAILED` | `Campaign Preview Accept Failed` | yes |
+| `CAMPAIGN_PREVIEW_SKIP_SUCCESS` | `Campaign Preview Skip Success` | yes |
+| `CAMPAIGN_PREVIEW_SKIP_FAILED` | `Campaign Preview Skip Failed` | yes |
+| `CAMPAIGN_PREVIEW_REMOVE_SUCCESS` | `Campaign Preview Remove Success` | yes |
+| `CAMPAIGN_PREVIEW_REMOVE_FAILED` | `Campaign Preview Remove Failed` | yes |
+| `AI_ASSISTANT_SEND_EVENT_SUCCESS` | `AI Assistant Send Event Success` | no |
+| `AI_ASSISTANT_SEND_EVENT_FAILED` | `AI Assistant Send Event Failed` | no |
+| `AI_ASSISTANT_GET_REAL_TIME_ASSISTANCE_SUCCESS` | `AI Assistant Get Real Time Assistance Success` | no |
+| `AI_ASSISTANT_GET_REAL_TIME_ASSISTANCE_FAILED` | `AI Assistant Get Real Time Assistance Failed` | no |
+| `AI_ASSISTANT_SEND_REAL_TIME_ASSISTANCE_USER_ACTION_SUCCESS` | `AI Assistant Send Real Time Assistance User Action Success` | no |
+| `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 |
+| `AI_SUMMARY_GET_POST_CALL_SUCCESS` | `Post Call Summary Get Success` | no |
+| `AI_SUMMARY_GET_POST_CALL_FAILED` | `Post Call Summary Get Failed` | no |
+| `AI_SUMMARY_GET_MID_CALL_SUCCESS` | `Mid Call Summary Get Success` | no |
+| `AI_SUMMARY_GET_MID_CALL_FAILED` | `Mid Call Summary Get Failed` | no |
+| `AI_SUMMARY_POST_CALL_RESPONSE_SUCCESS` | `Post Call Summary Response Success` | no |
+| `AI_SUMMARY_POST_CALL_RESPONSE_FAILED` | `Post Call Summary Response Failed` | no |
+| `AI_SUMMARY_MID_CALL_RESPONSE_SUCCESS` | `Mid Call Summary Response Success` | no |
+| `AI_SUMMARY_MID_CALL_RESPONSE_FAILED` | `Mid Call Summary Response 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 |
+| `USER_PREFERENCE_CREATE_FAILED` | `User Preference Create Failed` | yes |
+| `USER_PREFERENCE_UPDATE_SUCCESS` | `User Preference Update Success` | yes |
+| `USER_PREFERENCE_UPDATE_FAILED` | `User Preference Update Failed` | yes |
+| `USER_PREFERENCE_DELETE_SUCCESS` | `User Preference Delete Success` | yes |
+| `USER_PREFERENCE_DELETE_FAILED` | `User Preference Delete Failed` | yes |
+
+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
+- Webex ready lifecycle
+- LoggerProxy and browser visibility metadata
+
+- **`@webex/internal-plugin-metrics`**: Provides `webex.internal.newMetrics` for actual metric submission (`submitBehavioralEvent`, `submitOperationalEvent`, `submitBusinessEvent`)
+
+- **`LoggerProxy`**: Used for error logging within the metrics module
+
+- **`Failure` type** (from `services/core/GlobalTypes`): Used in `getCommonTrackingFieldForAQMResponseFailed`
+
+- **`PRODUCT_NAME`** (from `constants.ts`): Set to `'wxcc_sdk'`, used as the product identifier in behavioral taxonomy and as prefix for operational/business event names
+
+## Requirements
+| ID | WHAT | WHY | Source Evidence | Test / Example Evidence | Assumptions / Gaps | Confidence |
+|---|---|---|---|---|---|---|
+| METRICS-R-001 | Track only names defined by METRIC_EVENT_NAMES and keep the canonical catalog synchronized with the const object. | Telemetry queries and dashboards depend on exact stable event names. | `src/metrics/constants.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-002 | Map behavioral events through eventTaxonomyMap and explicitly identify defined names without taxonomy. | Undefined taxonomy must not be mistaken for an emitted or classified behavioral event. | `src/metrics/behavioral-events.ts` | `test/unit/spec/metrics/behavioral-events.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
+| 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.
+
+> **Purpose**: Track behavioral, operational, and business metrics for Contact Center SDK operations using a singleton `MetricsManager`. Provides event timing, payload preparation, batching, and submission to the Webex metrics backend.
+
+Each behavioral event maps to a structured taxonomy in `behavioral-events.ts`:
+
+```text
+{product}.{agent}.{target}.{verb}
+```
+
+- **product**: Always `'wxcc_sdk'` (from `PRODUCT_NAME`)
+
+- **agent**: `'user'` for user-initiated actions, `'service'` for system-generated events
+
+- **target**: Snake_case description of the action (e.g., `'station_login'`, `'task_accept'`)
+
+- **verb**: `'complete'` for success, `'fail'` for failure, `'set'` for RONA events
+
+**Example**: `STATION_LOGIN_SUCCESS` maps to `wxcc_sdk.user.station_login.complete`
+
+> **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.
+
+> **Purpose**: Technical documentation for the metrics collection, batching, and submission system within the Contact Center SDK.
+
+Each metric event name maps to a `BehavioralEventTaxonomy` with four fields:
+
+```typescript
+type BehavioralEventTaxonomy = {
+  product: MetricEventProduct;  // Always PRODUCT_NAME ('wxcc_sdk')
+  agent: MetricEventAgent;      // 'user' or 'service'
+  target: string;               // e.g., 'station_login', 'task_accept'
+  verb: MetricEventVerb;        // 'complete' for success, 'fail' for failure
+};
+```
+
+The final behavioral event name is constructed as: `{product}.{agent}.{target}.{verb}`
+
+Example: `wxcc_sdk.user.station_login.complete`
+
+The mapping is defined in `behavioral-events.ts` via `eventTaxonomyMap` and accessed through `getEventTaxonomy(name)`.
+
+Participant Drop uses target `task_conference_participant_drop` with `complete` for success and `fail` for failure. Its metric payload is limited to task/request correlation and standard AQM tracking fields; participant IDs, numbers, names, URLs, headers, and raw routing payloads are excluded.
+
+```mermaid
+flowchart LR
+    A[timeEvent keys] --> B[runningEvents stores startTime + key Set]
+    B --> C[trackEvent called with one of the keys]
+    C --> D[addDurationIfTimed matches key]
+    D --> E[Calculates duration_ms = now - startTime]
+    E --> F[Removes all keys for that operation]
+    F --> G[Attaches duration_ms to payload]
+```
+
+Usage pattern from `cc.ts`:
+
+```typescript
+// Before operation
+this.metricsManager.timeEvent([
+  METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS,
+  METRIC_EVENT_NAMES.STATION_LOGIN_FAILED,
+]);
+
+// On success
+this.metricsManager.trackEvent(
+  METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS,
+  { ...MetricsManager.getCommonTrackingFieldForAQMResponse(resp) },
+  ['behavioral', 'operational', 'business']
+);
+
+// On failure
+this.metricsManager.trackEvent(
+  METRIC_EVENT_NAMES.STATION_LOGIN_FAILED,
+  { ...MetricsManager.getCommonTrackingFieldForAQMResponseFailed(failure) },
+  ['behavioral', 'operational', 'business']
+);
+```
+
+Two static helpers extract standardized fields from AQM responses for metric payloads:
+
+Extracts: `agentId`, `agentSessionId`, `teamId`, `siteId`, `orgId`, `eventType`, `trackingId`, `notifTrackingId`
+
+## Data Flow
+```mermaid
+flowchart TD
+    A[cc.ts calls metricsManager.timeEvent] --> B[Store startTime + keys in runningEvents]
+    B --> C[Operation executes]
+    C --> D{Success or Failure?}
+    D -->|Success| E[cc.ts calls metricsManager.trackEvent with success name]
+    D -->|Failure| F[cc.ts calls metricsManager.trackEvent with failure name]
+    E --> G[addDurationIfTimed attaches duration_ms]
+    F --> G
+    G --> H[preparePayload cleans and enriches]
+    H --> I{Metric type?}
+    I -->|behavioral| J[Push to pendingBehavioralEvents]
+    I -->|operational| K[Push to pendingOperationalEvents]
+    I -->|business| L[Push to pendingBusinessEvents]
+    J --> M[submitPendingBehavioralEvents]
+    K --> N[submitPendingOperationalEvents]
+    L --> O[submitPendingBusinessEvents]
+    M --> P[webex.internal.newMetrics.submitBehavioralEvent]
+    N --> Q[webex.internal.newMetrics.submitOperationalEvent]
+    O --> R[webex.internal.newMetrics.submitBusinessEvent]
+```
+
+## Sequence Diagram(s)
+Sequence coverage:
+
+| Operation group | Diagram | Failure / recovery coverage |
+|---|---|---|
+| Time and track an event | Timing and tracking | Success/failure keys share one timer; missing timing data leaves the payload untimed. |
+| Queue until SDK readiness | SDK readiness | A not-ready SDK retains events; READY drains them through the configured metrics service. |
+| Submit behavioral/operational/business events | Category submission | The module does not retry or requeue after handing an event to `newMetrics`. |
+| Disable metrics | Disablement | Pending queues are cleared and future timing/tracking calls return immediately. |
+
+### Timing and tracking
+
+```mermaid
+sequenceDiagram
+    participant CC as ContactCenter (cc.ts)
+    participant MM as MetricsManager
+    participant NM as webex.internal.newMetrics
+
+    CC->>MM: timeEvent([SUCCESS_KEY, FAILURE_KEY])
+    Note over MM: Store startTime + key set in runningEvents
+    CC->>CC: Execute operation (e.g., stationLogin)
+    Note over MM: trackEvent defaults to ['behavioral'] only if no metricServices specified
+    alt Success
+        CC->>MM: trackEvent(SUCCESS_KEY, payload, ['behavioral', 'operational', 'business'])
+    else Failure
+        CC->>MM: trackEvent(FAILURE_KEY, payload, ['behavioral', 'operational', 'business'])
+    end
+    MM->>MM: addDurationIfTimed → attach duration_ms
+    MM->>MM: preparePayload → clean empty fields, add tabHidden
+    loop For each metric type
+        MM->>MM: Push to pending queue
+        alt readyToSubmitEvents
+            MM->>NM: submit[Behavioral|Operational|Business]Event
+        else not ready
+            Note over MM: Events stay queued until SDK ready
+        end
+    end
+```
+
+### SDK readiness
+
+```mermaid
+sequenceDiagram
+    participant CC as ContactCenter
+    participant MM as MetricsManager
+    participant Webex as WebexSDK
+
+    CC->>MM: getInstance({webex})
+    MM->>MM: Create singleton (if needed)
+    MM->>MM: setWebex(webex)
+    opt webex.ready === true
+        MM->>MM: setReadyToSubmitEvents()
+        MM->>MM: submitPendingEvents()
+    end
+    MM->>Webex: webex.once('ready', callback)
+    Note over MM: 'ready' listener is always registered
+    Webex-->>MM: 'ready' event fires
+    MM->>MM: setReadyToSubmitEvents()
+    MM->>MM: submitPendingEvents()
+```
+
+### Category submission
+
+```mermaid
+sequenceDiagram
+  participant Caller
+  participant MM as MetricsManager
+  participant NM as webex.internal.newMetrics
+  Caller->>MM: trackEvent(name, payload, metricServices)
+  loop each requested metric service
+    alt behavioral
+      MM->>NM: submitBehavioralEvent(taxonomy + payload)
+    else operational
+      MM->>NM: submitOperationalEvent(WXCC_SDK_* + payload)
+    else business
+      MM->>NM: submitBusinessEvent(WXCC_SDK_* + appType)
+    else invalid metric service
+      MM->>MM: LoggerProxy.error(invalid type)
+    end
+  end
+  Note over MM,NM: No module-level retry or requeue after submission handoff
+```
+
+### Disablement
+
+```mermaid
+sequenceDiagram
+  participant Caller
+  participant MM as MetricsManager
+  Caller->>MM: setMetricsDisabled(true)
+  MM->>MM: clear pending behavioral/operational/business queues
+  Caller->>MM: timeEvent(...) / trackEvent(...)
+  alt metricsDisabled
+    MM-->>Caller: return without timing, queueing, or submission
+  else re-enabled
+    MM->>MM: use normal timing/queue flow
+  end
+```
+
+## Class / Component Relationships
+```mermaid
+classDiagram
+  class ContactCenter
+  class MetricsManager
+  class METRIC_EVENT_NAMES
+  class eventTaxonomyMap
+  class NewMetrics
+  ContactCenter --> MetricsManager : timeEvent / trackEvent
+  MetricsManager --> METRIC_EVENT_NAMES : canonical names
+  MetricsManager --> eventTaxonomyMap : behavioral taxonomy lookup
+  MetricsManager --> NewMetrics : submit queued event types
+```
+
+| Component                | File                    | Responsibility                                                                 |
+|---|---|---|
+| `MetricsManager`         | `MetricsManager.ts`     | Singleton that manages event queuing, timing, payload preparation, and submission |
+| `BehavioralEventTaxonomy`| `behavioral-events.ts`  | Maps metric event names to structured taxonomy for behavioral analytics         |
+| `METRIC_EVENT_NAMES`     | `constants.ts`          | Canonical constant object of all tracked metric event names                     |
+
+`MetricsManager` uses a private constructor with a static `getInstance` factory:
+
+```typescript
+// MetricsManager.ts
+export default class MetricsManager {
+  private static instance: MetricsManager;
+  private constructor() {}
+
+  public static getInstance(options?: {webex: WebexSDK}): MetricsManager {
+    if (!MetricsManager.instance) {
+      MetricsManager.instance = new MetricsManager();
+    }
+    if (!MetricsManager.instance.webex && options?.webex) {
+      MetricsManager.instance.setWebex(options.webex);
+    }
+    return MetricsManager.instance;
+  }
+
+  public static resetInstance() {
+    MetricsManager.instance = undefined;
+  }
+}
+```
+
+- The Webex SDK instance is set once via `setWebex()`, which listens for the `ready` event before flushing pending queues.
+
+- `resetInstance()` sets the singleton to `undefined`, allowing a fresh instance to be created. Primarily used in tests.
+
+## Use Cases
+- **UC-1 Time and track an event:** `timeEvent` records the start against success/failure keys and `trackEvent` attaches `duration_ms` before preparing and queuing the payload. Evidence: `src/metrics/MetricsManager.ts`, `test/unit/spec/metrics/MetricsManager.ts`.
+- **UC-2 Queue until SDK readiness:** events remain in the behavioral/operational/business pending queues until the host is ready, then the ready callback drains them. Evidence: `src/metrics/MetricsManager.ts`, `test/unit/spec/metrics/MetricsManager.ts`.
+- **UC-3 Submit event categories:** each requested metric service uses its matching `webex.internal.newMetrics` submission method; taxonomy is applied only where `eventTaxonomyMap` contains the name. Evidence: `src/metrics/MetricsManager.ts`, `src/metrics/behavioral-events.ts`, `test/unit/spec/metrics/MetricsManager.ts`.
+
+```typescript
+import MetricsManager from '../metrics/MetricsManager';
+import {METRIC_EVENT_NAMES} from '../metrics/constants';
+
+// Get the singleton instance (webex is set during the ContactCenter READY callback)
+const metrics = MetricsManager.getInstance();
+
+// Time an operation, then track its result
+metrics.timeEvent(METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS);
+// ... perform the operation ...
+metrics.trackEvent(METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS, {agentId: '123'});
+```
+
+The standard pattern used throughout the Contact Center SDK:
+
+```typescript
+const metrics = MetricsManager.getInstance();
+
+// 1. Start timing before the operation
+metrics.timeEvent([
+  METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS,
+  METRIC_EVENT_NAMES.STATION_LOGIN_FAILED,
+]);
+
+try {
+  const response = await performLogin(params);
+
+  // 2a. Track success (duration_ms auto-added)
+  metrics.trackEvent(METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS, {
+    ...MetricsManager.getCommonTrackingFieldForAQMResponse(response),
+  });
+} catch (error) {
+  // 2b. Track failure (duration_ms auto-added)
+  metrics.trackEvent(METRIC_EVENT_NAMES.STATION_LOGIN_FAILED, {
+    ...MetricsManager.getCommonTrackingFieldForAQMResponseFailed(error),
+  });
+}
+```
+
+## State Model
+MetricsManager holds three pending queues, running timing entries, a readiness flag, a submission lock, and an independent disabled flag. Host READY enables draining; disabling metrics prevents both timing and tracking and clears pending events through the configured disable path.
+
+`preparePayload()` processes every event payload before submission:
+
+1. **Removes empty/null/undefined fields** — strips keys with `undefined`, `null`, `''`, any arrays, or empty objects
+
+2. **Converts spaces to underscores** — `spacesToUnderscore()` applied to all key names
+
+3. **Adds common metadata** — appends `tabHidden: document.hidden` in browser environments
+
+## Business Rules & Invariants
+- `timeEvent` and every tracking method return immediately while metrics are disabled.
+- 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.
+
+## Concurrency & Reactive Flow
+- Queue insertion is synchronous. Submission is gated by host readiness and the submission lock; each metric type drains through its own host method without propagating telemetry failures to product callers.
+
+MetricsManager maintains three independent pending event queues:
+
+| Queue                       | Type         | Submitted Via                                      | Name Transform                                  | Extra Metadata                   |
+|---|---|---|---|---|
+| `pendingBehavioralEvents`   | behavioral   | `webex.internal.newMetrics.submitBehavioralEvent`   | Taxonomy-based (`{product}.{agent}.{target}.{verb}`) | None                             |
+| `pendingOperationalEvents`  | operational  | `webex.internal.newMetrics.submitOperationalEvent`  | `WXCC_SDK_` prefix + uppercase (e.g. `WXCC_SDK_STATION_LOGIN_SUCCESS`) | None                             |
+| `pendingBusinessEvents`     | business     | `webex.internal.newMetrics.submitBusinessEvent`     | `WXCC_SDK_` prefix + uppercase (same as operational) | `metadata: {appType: 'wxcc_sdk'}` |
+
+## State Machine
+```mermaid
+stateDiagram-v2
+  [*] --> Buffering
+  Buffering --> ReadyToSubmit: host already ready / ready event
+  ReadyToSubmit --> Submitting: pending events and lock acquired
+  Submitting --> ReadyToSubmit: queues drained and lock released
+  Buffering --> Disabled: setMetricsDisabled(true)
+  ReadyToSubmit --> Disabled: setMetricsDisabled(true)
+  Disabled --> Buffering: enabled before host ready
+  Disabled --> ReadyToSubmit: enabled after host ready
+```
+
+- **readyToSubmitEvents**: Set to `true` only after `webex.once('ready')` fires. Events queue until then.
+
+- **submittingEvents**: Lock flag to prevent concurrent `submitPendingEvents()` calls.
+
+- **metricsDisabled**: When `true`, `timeEvent` and all `track*` methods return early, and `clearPendingEvents()` empties all queues.
+
+## Pitfalls
+- `METRIC_EVENT_NAMES` and `eventTaxonomyMap` are different inventories: 24 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.
+
+Static helper that extracts common tracking fields from an AQM failure response.
+
+**Parameters**:
+
+- `failureResponse` (Failure): The AQM failure response object
+
+**Returns**: `Record<string, any>` with fields: `agentId`, `trackingId`, `notifTrackingId`, `orgId`, `failureType`, `failureReason`, `reasonCode`
+
+MetricsManager is designed to be non-blocking. Metric failures do not propagate to callers:
+
+- If `webex` is not yet ready, events are queued in `pendingBehavioralEvents`, `pendingOperationalEvents`, or `pendingBusinessEvents`
+
+- Once `webex.ready` fires, all pending events are flushed
+
+- If metrics are disabled via `setMetricsDisabled(true)`, all track methods silently return
+
+- Invalid metric types log an error via `LoggerProxy` but do not throw
+
+MetricsManager does not throw errors to callers. Instead:
+
+- Invalid metric types are logged via `LoggerProxy.error`
+
+- Empty `timeEvent` key arrays are logged and ignored
+
+- Disabled state (`metricsDisabled`) prevents both timing and tracking and silently drops new events
+
+- The `submittingEvents` lock prevents race conditions during concurrent submissions
+
+Extracts: `agentId`, `trackingId`, `notifTrackingId`, `orgId`, `failureType`, `failureReason`, `reasonCode`
+
+**Cause**: Webex SDK not yet ready when `trackEvent` is called
+
+**Solution**: Events are automatically queued in `pending*Events` arrays and flushed once `webex.once('ready')` fires. Verify the SDK is initializing correctly.
+
+**Cause**: `timeEvent` was not called before `trackEvent`, or the event name does not match any key in `runningEvents`
+
+**Solution**: Ensure `timeEvent([SUCCESS_KEY, FAILURE_KEY])` is called before the operation, and that the exact `METRIC_EVENT_NAMES` constant is used in both calls.
+
+**Cause**: `metricsDisabled` is set to `true`
+
+**Solution**: Check if `setMetricsDisabled(true)` was called. This clears all pending queues and causes all `track*` methods to return early.
+
+## Module Do's / Don'ts
+- DO use `METRIC_EVENT_NAMES` and the matching category submitter instead of constructing event names manually.
+- DO keep timing success/failure keys together so either outcome clears the same running timer.
+- DON'T add a behavioral taxonomy entry unless the backend taxonomy contract exists.
+- DON'T make product behavior depend on metrics delivery.
+
+## Key Design Trade-off
+- Telemetry is deliberately non-blocking and queue-backed so product behavior never waits for metrics; failures are logged rather than propagated.
+
+## Test-Case Strategy (module)
+Use `test/unit/spec/metrics/MetricsManager.ts` for readiness queues, timing/tracking, disabled behavior, submission categories, and failures. Use `test/unit/spec/metrics/behavioral-events.ts` to reconcile every taxonomy-backed name. Mechanically compare the complete constant catalog with taxonomy keys so newly defined events cannot disappear from the spec.
+
+| 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 24 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`
+- Coverage state and contracts baseline: `../../../.sdd/manifest.json`
+
+- [`MetricsManager.ts`](../MetricsManager.ts) - Singleton metrics manager implementation
+
+- [`behavioral-events.ts`](../behavioral-events.ts) - Event taxonomy mapping
+
+- [`constants.ts`](../constants.ts) - `METRIC_EVENT_NAMES` definitions
+
+- [`../../constants.ts`](../../constants.ts) - `PRODUCT_NAME` constant
+
+- [`services/core/GlobalTypes.ts`](../../services/core/GlobalTypes.ts) - `Failure` type definition
+
+- [MetricsManager.ts](../MetricsManager.ts) — Singleton metrics manager
+
+- [behavioral-events.ts](../behavioral-events.ts) — Event taxonomy mapping
+
+- [constants.ts](../constants.ts) — METRIC_EVENT_NAMES definitions
+
+- [cc.ts](../../cc.ts) — Main plugin class (primary consumer)
+
+- [constants.ts](../../constants.ts) — PRODUCT_NAME used in event prefixing