@webex/contact-center 3.12.0-llmrefactor.8 → 3.12.0-llmrefactor.9

package/src/services/AnswerCallOnWebexService.ts

@@ -12,19 +12,30 @@ export type WxAppTelephonyError = Error & {
   status?: number | string;
 };
 
-const markWxAppTelephonyError = (error: Error, source: unknown): WxAppTelephonyError => {
-  const marked = error as WxAppTelephonyError;
-  marked.isWxAppTelephonyError = true;
-  const sourceObj = source as {
-    details?: {trackingId?: string; status?: number | string};
+const extractWxAppTrackingId = (source: unknown): string | undefined => {
+  const sourceObj = source as {details?: {trackingId?: string}; trackingId?: string};
+
+  return sourceObj?.details?.trackingId || sourceObj?.trackingId;
+};
+
+const extractWxAppHttpStatus = (source: unknown): number | string | undefined => {
+  const obj = source as {
     statusCode?: number;
     status?: number | string;
+    details?: {status?: number | string};
   };
-  const trackingId = sourceObj?.details?.trackingId;
+
+  return obj?.statusCode ?? obj?.status ?? obj?.details?.status;
+};
+
+const markWxAppTelephonyError = (error: Error, source: unknown): WxAppTelephonyError => {
+  const marked = error as WxAppTelephonyError;
+  marked.isWxAppTelephonyError = true;
+  const trackingId = extractWxAppTrackingId(source);
   if (trackingId) {
     marked.trackingId = trackingId;
   }
-  const status = sourceObj?.statusCode ?? sourceObj?.details?.status ?? sourceObj?.status;
+  const status = extractWxAppHttpStatus(source);
   if (status !== undefined) {
     marked.status = status;
   }
@@ -73,6 +84,10 @@ export default class AnswerCallOnWebexService {
     return `${hydraUrl.replace(/\/$/, '')}/telephony/calls`;
   }
 
+  private extractTrackingId(source: unknown): string | undefined {
+    return extractWxAppTrackingId(source);
+  }
+
   private async telephonyRequest(
     resource: string,
     method: HTTP_METHODS,
@@ -88,16 +103,29 @@ export default class AnswerCallOnWebexService {
         data: {uri, bodyKeys: Object.keys(body)},
       });
 
-      return (await this.webex.request({
+      const response = (await this.webex.request({
         uri,
         method,
         body,
         addAuthHeader: true,
       })) as IHttpResponse;
+
+      LoggerProxy.info(`AnswerCallOnWebexService.${logMethod} success`, {
+        module: ANSWER_CALL_ON_WEBEX_FILE,
+        method: logMethod,
+        data: {statusCode: response.statusCode},
+      });
+
+      return response;
     } catch (error) {
+      const trackingId = this.extractTrackingId(error);
       LoggerProxy.error(`AnswerCallOnWebexService.${logMethod} failed: ${error}`, {
         module: ANSWER_CALL_ON_WEBEX_FILE,
         method: logMethod,
+        data: {
+          trackingId,
+          status: extractWxAppHttpStatus(error),
+        },
       });
       const {error: detailedError} = getErrorDetails(error, logMethod, CC_FILE);
       throw markWxAppTelephonyError(detailedError, error);
@@ -191,9 +219,14 @@ export default class AnswerCallOnWebexService {
         throw markWxAppTelephonyError(err, error);
       }
 
+      const trackingId = this.extractTrackingId(error);
       LoggerProxy.error(`AnswerCallOnWebexService.getCallDetails failed: ${error}`, {
         module: ANSWER_CALL_ON_WEBEX_FILE,
         method: METHODS.GET_CALL_DETAILS_ON_WEBEX,
+        data: {
+          trackingId,
+          status: extractWxAppHttpStatus(error),
+        },
       });
       const {error: detailedError} = getErrorDetails(
         error,

package/src/services/WebexCrossClientService.ts

@@ -1,6 +1,8 @@
 import LoggerProxy from '../logger-proxy';
 import {METHODS} from '../constants';
 import {WebexSDK} from '../types';
+import MetricsManager from '../metrics/MetricsManager';
+import {METRIC_EVENT_NAMES} from '../metrics/constants';
 
 const WEBEX_CROSS_CLIENT_FILE = 'WebexCrossClientService';
 const DEFAULT_CROSS_CLIENT_STATE_TTL = 900;
@@ -23,6 +25,8 @@ export default class WebexCrossClientService {
   private appName = DEFAULT_APP_NAME;
   /** Incremented on teardown/disable to ignore stale refresh timer callbacks. */
   private refreshGeneration = 0;
+  /** Monotonic id for usersub publish metrics timers; stale publishes cancel only their own timer. */
+  private usersubPublishMetricsId = 0;
 
   constructor(webex: WebexSDK) {
     this.webex = webex;
@@ -144,21 +148,31 @@ export default class WebexCrossClientService {
 
   public async setManageWebexCallingInWxcc(
     enable: boolean,
-    options?: {userId?: string; ttl?: number; appName?: string}
+    options?: {userId?: string; ttl?: number; appName?: string; trackPublishMetrics?: boolean}
   ): Promise<void> {
     const operationGeneration = this.refreshGeneration;
     const userId = options?.userId ?? this.webex.internal.device?.userId;
     const ttl = options?.ttl ?? DEFAULT_CROSS_CLIENT_STATE_TTL;
     const appName = options?.appName ?? DEFAULT_APP_NAME;
+    const trackPublishMetrics = options?.trackPublishMetrics ?? false;
     this.appName = appName;
 
     if (!userId) {
-      throw new Error('User ID is unavailable for cross-client publish');
+      const error = 'User ID is unavailable for cross-client publish';
+      this.trackUsersubPreflightFailure(enable, 'user_id_unavailable', error, trackPublishMetrics);
+      throw new Error(error);
     }
 
     const deviceUrl = this.getDeviceUrl();
     if (!deviceUrl) {
-      throw new Error('Device URL is unavailable for cross-client publish');
+      const error = 'Device URL is unavailable for cross-client publish';
+      this.trackUsersubPreflightFailure(
+        enable,
+        'device_url_unavailable',
+        error,
+        trackPublishMetrics
+      );
+      throw new Error(error);
     }
 
     const composition = {
@@ -173,9 +187,47 @@ export default class WebexCrossClientService {
       ],
     };
 
-    await this.publishCrossClientState([userId], ttl, composition, 'setManageWebexCallingInWxcc');
+    const metricsManager = MetricsManager.getInstance();
+    const usersubPublishEventKeys = [
+      METRIC_EVENT_NAMES.WXAPP_USERSUB_PUBLISH_SUCCESS,
+      METRIC_EVENT_NAMES.WXAPP_USERSUB_PUBLISH_FAILED,
+    ];
+
+    let publishMetricsId = 0;
+    if (trackPublishMetrics) {
+      this.usersubPublishMetricsId += 1;
+      publishMetricsId = this.usersubPublishMetricsId;
+      metricsManager.timeEvent(usersubPublishEventKeys);
+    }
+
+    try {
+      await this.publishCrossClientState([userId], ttl, composition, 'setManageWebexCallingInWxcc');
+    } catch (error) {
+      if (trackPublishMetrics) {
+        if (operationGeneration !== this.refreshGeneration) {
+          if (publishMetricsId === this.usersubPublishMetricsId) {
+            metricsManager.cancelTimedEvent(usersubPublishEventKeys);
+          }
+        } else {
+          metricsManager.trackEvent(
+            METRIC_EVENT_NAMES.WXAPP_USERSUB_PUBLISH_FAILED,
+            {
+              enableWxBetterTogether: enable,
+              error: error instanceof Error ? error.toString() : String(error),
+            },
+            ['operational', 'behavioral']
+          );
+        }
+      }
+
+      throw error;
+    }
 
     if (operationGeneration !== this.refreshGeneration) {
+      if (trackPublishMetrics && publishMetricsId === this.usersubPublishMetricsId) {
+        metricsManager.cancelTimedEvent(usersubPublishEventKeys);
+      }
+
       return;
     }
 
@@ -188,6 +240,14 @@ export default class WebexCrossClientService {
       this.clearRefreshTimer();
     }
 
+    if (trackPublishMetrics) {
+      metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.WXAPP_USERSUB_PUBLISH_SUCCESS,
+        {enableWxBetterTogether: enable},
+        ['operational', 'behavioral']
+      );
+    }
+
     LoggerProxy.info(`Cross-client answer-calls-on-wxcc set to ${enable}`, {
       module: WEBEX_CROSS_CLIENT_FILE,
       method: METHODS.SET_MANAGE_WEBEX_CALLING_IN_WXCC,
@@ -199,6 +259,27 @@ export default class WebexCrossClientService {
     });
   }
 
+  private trackUsersubPreflightFailure(
+    enable: boolean,
+    skipReason: 'user_id_unavailable' | 'device_url_unavailable',
+    error: string,
+    trackPublishMetrics: boolean
+  ): void {
+    if (!trackPublishMetrics) {
+      return;
+    }
+
+    MetricsManager.getInstance().trackEvent(
+      METRIC_EVENT_NAMES.WXAPP_USERSUB_PUBLISH_FAILED,
+      {
+        enableWxBetterTogether: enable,
+        skipReason,
+        error,
+      },
+      ['operational', 'behavioral']
+    );
+  }
+
   public teardown(): void {
     this.refreshGeneration += 1;
     this.clearRefreshTimer();

package/src/services/WxAppTelephonyMercurySync.ts

@@ -1,6 +1,9 @@
 import LoggerProxy from '../logger-proxy';
 import {METHODS} from '../constants';
 import {WebexSDK} from '../types';
+import MetricsManager from '../metrics/MetricsManager';
+import {METRIC_EVENT_NAMES} from '../metrics/constants';
+import {callIdSuffix, logWxAppMercuryMuteSync} from './wxAppDiagnosticLogging';
 
 const WXAPP_TELEPHONY_MERCURY_SYNC_FILE = 'WxAppTelephonyMercurySync';
 
@@ -42,6 +45,11 @@ export default class WxAppTelephonyMercurySync {
   private handleMuteStateEvent = (agentId: string, event: UpdatedCallMuteStateEvent): void => {
     const {actorId, callId, muted} = event?.data ?? {};
     if (!actorId || !callId || muted === undefined) {
+      logWxAppMercuryMuteSync({
+        phase: 'dropped',
+        dropReason: 'missing_mercury_event_fields',
+      });
+
       return;
     }
 
@@ -49,13 +57,20 @@ export default class WxAppTelephonyMercurySync {
     const decodedCallId = this.decodeBase64(callId);
 
     if (!decodedActorId.endsWith(agentId)) {
+      logWxAppMercuryMuteSync({
+        phase: 'dropped',
+        muted,
+        callIdSuffix: callIdSuffix(decodedCallId),
+        dropReason: 'actor_id_mismatch',
+      });
+
       return;
     }
 
-    LoggerProxy.info('WxApp telephony mute state sync received', {
-      module: WXAPP_TELEPHONY_MERCURY_SYNC_FILE,
-      method: METHODS.SYNC_WXAPP_MUTE_FROM_MERCURY,
-      data: {muted},
+    logWxAppMercuryMuteSync({
+      phase: 'received',
+      muted,
+      callIdSuffix: callIdSuffix(decodedCallId),
     });
 
     this.muteChangeHandler?.(decodedCallId, muted);
@@ -71,6 +86,12 @@ export default class WxAppTelephonyMercurySync {
         method: METHODS.SYNC_WXAPP_MUTE_FROM_MERCURY,
       });
 
+      MetricsManager.getInstance().trackEvent(
+        METRIC_EVENT_NAMES.WXAPP_MERCURY_SUBSCRIBE_FAILED,
+        {error: 'Mercury is unavailable for wxApp mute sync'},
+        ['operational', 'behavioral']
+      );
+
       return;
     }
 
@@ -87,6 +108,12 @@ export default class WxAppTelephonyMercurySync {
     mercury.on(TELEPHONY_CALL_MUTED, this.boundMuteHandler);
     mercury.on(TELEPHONY_CALL_UNMUTED, this.boundUnmuteHandler);
 
+    MetricsManager.getInstance().trackEvent(
+      METRIC_EVENT_NAMES.WXAPP_MERCURY_SUBSCRIBE_SUCCESS,
+      {},
+      ['operational', 'behavioral']
+    );
+
     LoggerProxy.info('Subscribed to wxApp telephony Mercury mute sync', {
       module: WXAPP_TELEPHONY_MERCURY_SYNC_FILE,
       method: METHODS.SYNC_WXAPP_MUTE_FROM_MERCURY,

package/src/services/agent/ai-docs/agent-spec.md

@@ -87,6 +87,7 @@ Key nested WebSocket binds use the actual outer/data constants, for example `CC_
 | AGENT-R-003 | Buddy-agent lookup must preserve its typed request and correlated response contract. | Consult/transfer selection depends on backend-filtered availability. | `src/services/agent/index.ts` | `test/unit/spec/services/agent/index.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
 | AGENT-R-004 | The agent factory exposes `reload`, while ContactCenter alone decides when automated relogin is permitted. | Transport recovery lacks the profile/policy context required to mutate an agent session safely. | `src/cc.ts` | `test/unit/spec/cc.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
 | AGENT-R-005 | Device/profile update must be documented as `ContactCenter.updateAgentProfile`, not as an agent-factory method. | Calling a non-existent `routingAgent.deviceUpdate` would fail at runtime. | `src/cc.ts` | `test/unit/spec/cc.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
+| AGENT-R-006 | BROWSER station login must send `dialNumber` and `deviceId` as `webrtc-{agentId}` on `POST /v1/agents/login`. EXTENSION and AGENT_DN continue to send the caller-supplied dial number for both fields. | QRM stores `agent.dn` from `dialNumber`. Legacy VPOP RTMS only treats a DN as WebRTC when it starts with `webrtc-`; a bare UUID gets a steering prefix and the agent invite fails with SIP 484. | `src/cc.ts` | `test/unit/spec/cc.ts` | Public `stationLogin({loginOption: 'BROWSER'})` input is unchanged; only the backend login payload is prefixed. | PRESENT |
 
 ## Design Overview
 `routingAgent` is a pure AQM factory. It receives an initialized AqmReqs instance and returns five request functions: `reload`, `logout`, `stationLogin`, `stateChange`, and `buddyAgents`. Each request config declares the endpoint/payload plus exact `CC_EVENTS` notification binds.

package/src/services/task/ai-docs/task-spec.md

@@ -619,6 +619,8 @@ This keeps transcript and suggestion delivery aligned on the same per-task event
 
 **wxApp offer UI (`uiControlsComputer`):** `wxAppAcceptInFlight` disables accept/decline during the accept REST call. `wxAppAnswerPending` additionally disables accept and decline for **inbound** offers until ASSIGN; wxApp **outdial** keeps decline enabled during the post-accept "Calling…" phase so `cancelTask` remains available.
 
+**wxApp decline observability:** Inbound wxApp offers decline via telephony `rejectCall` (`runWxAppReject` → `WXAPP_TASK_DECLINE_*`). wxApp outdial cancellations use CC routing `cancelTask` (`runWxAppOutdialDecline` → additive `WXAPP_TASK_DECLINE_*` plus existing `TASK_DECLINE_*`).
+
 **wxApp mute backfill guard (`Voice.syncWxAppMuteFromCallDetails`):** Skips telephony `GET /calls/{callId}` when the interaction is terminated or the task is a pre-accept wxApp OFFERED offer (`wxAppAnswerPending` false). Post-accept OFFERED and engaged CONNECTED sync still run. `isWxAppEngagedForControls` and `getWebexCallingCallId` exclude `TERMINATED` and `COMPLETED`. Expected 400 / "Call not found" / `101002` responses are not logged as errors.
 
 For BROWSER login, TaskManager integrates with WebCalling:

package/src/services/task/voice/Voice.ts

@@ -41,12 +41,20 @@ import {
   isWebexAppInboundCallingOffer as wxIsWebexAppInboundCallingOffer,
   mapWxAppVoiceError,
   runWxAppAccept,
+  runWxAppOutdialDecline,
   runWxAppReject,
   runWxAppToggleMute,
   runWxAppTransmitDtmf,
   WxAppVoiceDependencies,
   WxAppVoiceLifecycle,
 } from './wxAppVoiceMethods';
+import {
+  deriveWxAppAcceptReason,
+  logWxAppMercuryMuteSync,
+  logWxAppOfferDecision,
+  callIdSuffix,
+  WxAppAcceptReason,
+} from '../../wxAppDiagnosticLogging';
 
 export default class Voice extends Task implements IVoice {
   private static readonly WXAPP_MUTE_SYNC_RETRY_DELAY_MS = 50;
@@ -58,7 +66,9 @@ export default class Voice extends Task implements IVoice {
   private wxAppAnswerPending = false;
   private wxAppAcceptInFlight = false;
   private wxAppMuteSyncInFlight?: Promise<boolean | undefined>;
-  private wxAppMuteToggleInFlight?: Promise<void>;
+  private wxAppMuteToggleTail: Promise<void> = Promise.resolve();
+  private wxAppDtmfTail: Promise<void> = Promise.resolve();
+  private lastLoggedWxAppAcceptReason?: WxAppAcceptReason;
 
   constructor(
     contact: ReturnType<typeof routingContact>,
@@ -95,6 +105,7 @@ export default class Voice extends Task implements IVoice {
       enableWxBetterTogether: this.enableWxBetterTogether,
       answerCallOnWebexService: this.answerCallOnWebexService,
       agentId: this.agentId,
+      metricsManager: this.metricsManager,
       getTaskData: () => this.data,
       getTaskState: () => this.stateMachineService?.getSnapshot?.()?.value as TaskState | undefined,
       getWxAppMuted: () => this.wxAppMuted,
@@ -135,17 +146,98 @@ export default class Voice extends Task implements IVoice {
     this.updateUiControls(true);
   }
 
+  protected updateUiControls(forceEmit = false): void {
+    super.updateUiControls(forceEmit);
+    this.logWxAppOfferDecisionIfNeeded();
+  }
+
+  private logWxAppOfferDecisionIfNeeded(): void {
+    if (!this.enableWxBetterTogether) {
+      return;
+    }
+
+    const state = this.stateMachineService?.getSnapshot?.()?.value as TaskState | undefined;
+    if (state !== TaskState.OFFERED) {
+      return;
+    }
+
+    const accept = this.currentUiControls?.main?.accept;
+    if (!accept?.isVisible) {
+      return;
+    }
+
+    const deps = this.getWxAppVoiceDependencies();
+    const isOutdial = this.data?.interaction?.outboundType === 'OUTDIAL';
+    const isWxAppInboundOffer = this.isWebexAppInboundCallingOffer();
+    const isWxAppOutdialOffer = this.isWebexAppCallingOffer() && isOutdial;
+    const deviceDetails = getCallingDeviceDetails(deps);
+    const acceptReason = deriveWxAppAcceptReason({
+      isWxAppInboundOffer,
+      isWxAppOutdialOffer,
+      isWebrtc: this.uiControlConfig.voiceVariant === VOICE_VARIANT.WEBRTC,
+      isOutdial,
+      wxAppAcceptInFlight: this.wxAppAcceptInFlight,
+      wxAppAnswerPending: this.wxAppAnswerPending,
+      enableWxBetterTogether: this.enableWxBetterTogether,
+      hasDeviceCallId: Boolean(deviceDetails?.deviceCallId),
+    });
+
+    if (acceptReason === this.lastLoggedWxAppAcceptReason) {
+      return;
+    }
+
+    this.lastLoggedWxAppAcceptReason = acceptReason;
+
+    logWxAppOfferDecision({
+      interactionId: this.data.interactionId,
+      acceptVisible: accept.isVisible,
+      acceptEnabled: accept.isEnabled,
+      acceptReason,
+      wxAppParticipantDeviceType: deviceDetails?.deviceType,
+      hasDeviceCallId: Boolean(deviceDetails?.deviceCallId),
+    });
+  }
+
   public applyWxAppMuteStateFromSync(incomingCallId: string, muted: boolean): void {
     if (!this.enableWxBetterTogether) {
       return;
     }
 
     const activeCallId = this.getWebexCallingCallId();
-    if (!activeCallId || !incomingCallId.endsWith(activeCallId) || this.wxAppMuted === muted) {
+    const incomingSuffix = callIdSuffix(incomingCallId);
+    const activeSuffix = callIdSuffix(activeCallId);
+
+    if (!activeCallId || !incomingCallId.endsWith(activeCallId)) {
+      logWxAppMercuryMuteSync({
+        phase: 'dropped',
+        muted,
+        callIdSuffix: incomingSuffix,
+        interactionId: this.data.interactionId,
+        dropReason: !activeCallId ? 'no_active_wxApp_call' : 'call_id_mismatch',
+      });
+
+      return;
+    }
+
+    if (this.wxAppMuted === muted) {
+      logWxAppMercuryMuteSync({
+        phase: 'dropped',
+        muted,
+        callIdSuffix: incomingSuffix,
+        interactionId: this.data.interactionId,
+        dropReason: 'mute_state_unchanged',
+      });
+
       return;
     }
 
     this.wxAppMuted = muted;
+    logWxAppMercuryMuteSync({
+      phase: 'applied',
+      muted,
+      callIdSuffix: activeSuffix,
+      interactionId: this.data.interactionId,
+    });
     this.emit(TASK_EVENTS.TASK_WXAPP_MUTE_STATE_UPDATED, {muted});
   }
 
@@ -354,7 +446,9 @@ export default class Voice extends Task implements IVoice {
       ]);
 
       this.setWxAppAnswerPending(false);
-      const response = await this.contact.cancelTask({interactionId});
+      const response = await runWxAppOutdialDecline(this.getWxAppVoiceDependencies(), () =>
+        this.contact.cancelTask({interactionId})
+      );
 
       this.metricsManager.trackEvent(
         METRIC_EVENT_NAMES.TASK_DECLINE_SUCCESS,
@@ -388,25 +482,13 @@ export default class Voice extends Task implements IVoice {
    */
   public async toggleMute(options?: TaskToggleMuteOptions): Promise<void> {
     if (this.enableWxBetterTogether && this.getWebexCallingCallId()) {
-      if (this.wxAppMuteToggleInFlight) {
-        await this.wxAppMuteToggleInFlight.catch(() => undefined);
-      }
-
-      const togglePromise = runWxAppToggleMute(
-        this.getWxAppVoiceDependencies(),
-        this.createWxAppLifecycle(),
-        options
-      );
-
-      this.wxAppMuteToggleInFlight = togglePromise;
-      togglePromise
-        .finally(() => {
-          if (this.wxAppMuteToggleInFlight === togglePromise) {
-            this.wxAppMuteToggleInFlight = undefined;
-          }
-        })
-        .catch(() => undefined);
+      const togglePromise = this.wxAppMuteToggleTail
+        .catch(() => undefined)
+        .then(() =>
+          runWxAppToggleMute(this.getWxAppVoiceDependencies(), this.createWxAppLifecycle(), options)
+        );
 
+      this.wxAppMuteToggleTail = togglePromise.catch(() => undefined);
       await togglePromise;
 
       return;
@@ -420,11 +502,18 @@ export default class Voice extends Task implements IVoice {
    */
   public async transmitDtmf(options: TaskTransmitDtmfOptions): Promise<void> {
     if (this.enableWxBetterTogether && this.getWebexCallingCallId()) {
-      await runWxAppTransmitDtmf(
-        this.getWxAppVoiceDependencies(),
-        this.createWxAppLifecycle(),
-        options
-      );
+      const dtmfPromise = this.wxAppDtmfTail
+        .catch(() => undefined)
+        .then(() =>
+          runWxAppTransmitDtmf(
+            this.getWxAppVoiceDependencies(),
+            this.createWxAppLifecycle(),
+            options
+          )
+        );
+
+      this.wxAppDtmfTail = dtmfPromise.catch(() => undefined);
+      await dtmfPromise;
 
       return;
     }