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

package/src/metrics/behavioral-events.ts

@@ -313,6 +313,98 @@ const eventTaxonomyMap: Record<string, BehavioralEventTaxonomy> = {
     target: 'task_outdial',
     verb: 'fail',
   },
+  [METRIC_EVENT_NAMES.WXAPP_TASK_MUTE_SUCCESS]: {
+    product,
+    agent: 'user',
+    target: 'task_mute_webex_together',
+    verb: 'complete',
+  },
+  [METRIC_EVENT_NAMES.WXAPP_TASK_MUTE_FAILED]: {
+    product,
+    agent: 'user',
+    target: 'task_mute_webex_together',
+    verb: 'fail',
+  },
+  [METRIC_EVENT_NAMES.WXAPP_TASK_DTMF_SUCCESS]: {
+    product,
+    agent: 'user',
+    target: 'task_dtmf_webex_together',
+    verb: 'complete',
+  },
+  [METRIC_EVENT_NAMES.WXAPP_TASK_DTMF_FAILED]: {
+    product,
+    agent: 'user',
+    target: 'task_dtmf_webex_together',
+    verb: 'fail',
+  },
+
+  // Webex Together (wxApp)
+  [METRIC_EVENT_NAMES.WXAPP_TASK_ACCEPT_SUCCESS]: {
+    product,
+    agent: 'user',
+    target: 'task_accept_webex_together',
+    verb: 'complete',
+  },
+  [METRIC_EVENT_NAMES.WXAPP_TASK_ACCEPT_FAILED]: {
+    product,
+    agent: 'user',
+    target: 'task_accept_webex_together',
+    verb: 'fail',
+  },
+  [METRIC_EVENT_NAMES.WXAPP_TASK_DECLINE_SUCCESS]: {
+    product,
+    agent: 'user',
+    target: 'task_reject_webex_together',
+    verb: 'complete',
+  },
+  [METRIC_EVENT_NAMES.WXAPP_TASK_DECLINE_FAILED]: {
+    product,
+    agent: 'user',
+    target: 'task_reject_webex_together',
+    verb: 'fail',
+  },
+  [METRIC_EVENT_NAMES.WXAPP_SESSION_INIT_SUCCESS]: {
+    product,
+    agent: 'user',
+    target: 'webex_together_session_init',
+    verb: 'complete',
+  },
+  [METRIC_EVENT_NAMES.WXAPP_SESSION_INIT_FAILED]: {
+    product,
+    agent: 'user',
+    target: 'webex_together_session_init',
+    verb: 'fail',
+  },
+  [METRIC_EVENT_NAMES.WXAPP_SESSION_SKIPPED]: {
+    product,
+    agent: 'user',
+    target: 'webex_together_session_init',
+    verb: 'ignore',
+  },
+  [METRIC_EVENT_NAMES.WXAPP_USERSUB_PUBLISH_SUCCESS]: {
+    product,
+    agent: 'user',
+    target: 'webex_together_usersub_publish',
+    verb: 'complete',
+  },
+  [METRIC_EVENT_NAMES.WXAPP_USERSUB_PUBLISH_FAILED]: {
+    product,
+    agent: 'user',
+    target: 'webex_together_usersub_publish',
+    verb: 'fail',
+  },
+  [METRIC_EVENT_NAMES.WXAPP_MERCURY_SUBSCRIBE_SUCCESS]: {
+    product,
+    agent: 'user',
+    target: 'webex_together_mercury_subscribe',
+    verb: 'complete',
+  },
+  [METRIC_EVENT_NAMES.WXAPP_MERCURY_SUBSCRIBE_FAILED]: {
+    product,
+    agent: 'user',
+    target: 'webex_together_mercury_subscribe',
+    verb: 'fail',
+  },
 
   // Conference Tasks
   [METRIC_EVENT_NAMES.TASK_CONFERENCE_START_SUCCESS]: {

package/src/metrics/constants.ts

@@ -139,6 +139,24 @@ export const METRIC_EVENT_NAMES = {
   TASK_OUTDIAL_SUCCESS: 'Task Outdial Success',
   TASK_OUTDIAL_FAILED: 'Task Outdial Failed',
 
+  WXAPP_TASK_MUTE_SUCCESS: 'WxApp Task Mute Success',
+  WXAPP_TASK_MUTE_FAILED: 'WxApp Task Mute Failed',
+  WXAPP_TASK_DTMF_SUCCESS: 'WxApp Task Dtmf Success',
+  WXAPP_TASK_DTMF_FAILED: 'WxApp Task Dtmf Failed',
+
+  // WxApp Better Together
+  WXAPP_TASK_ACCEPT_SUCCESS: 'WxApp Task Accept Success',
+  WXAPP_TASK_ACCEPT_FAILED: 'WxApp Task Accept Failed',
+  WXAPP_TASK_DECLINE_SUCCESS: 'WxApp Task Decline Success',
+  WXAPP_TASK_DECLINE_FAILED: 'WxApp Task Decline Failed',
+  WXAPP_SESSION_INIT_SUCCESS: 'WxApp Session Init Success',
+  WXAPP_SESSION_INIT_FAILED: 'WxApp Session Init Failed',
+  WXAPP_SESSION_SKIPPED: 'WxApp Session Skipped',
+  WXAPP_USERSUB_PUBLISH_SUCCESS: 'WxApp Usersub Publish Success',
+  WXAPP_USERSUB_PUBLISH_FAILED: 'WxApp Usersub Publish Failed',
+  WXAPP_MERCURY_SUBSCRIBE_SUCCESS: 'WxApp Mercury Subscribe Success',
+  WXAPP_MERCURY_SUBSCRIBE_FAILED: 'WxApp Mercury Subscribe Failed',
+
   UPLOAD_LOGS_SUCCESS: 'Upload Logs Success',
   UPLOAD_LOGS_FAILED: 'Upload Logs Failed',
   WEBSOCKET_DEREGISTER_SUCCESS: 'Websocket Deregister Success',

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:
@@ -902,22 +904,21 @@ event so consumers can rebind to the surviving task object.
 
 Dropping an Agent while that Agent is consulting continues through the existing
 `PARTICIPANT_LEAVE` transition, which clears consult state and emits the normal
-participant-left and task-end lifecycle. This self-departure check applies in
-every active call-control state and uses an explicit self participant ID,
-`hasLeft`, or removal of a previously active Agent from the participant map. A
-participant-left event naming somebody else never infers self-departure from a
-partial media roster. A consulted Agent receiving
-`AgentConsultEnded` continues through `CONSULT_END`; current-agent departure is
-evaluated before consult-initiator recovery. For the from-conference nested-consult
-ordering race only, the guard also compares `mainCall` membership (located by
-`mType`) when the Agent remains active in the participant map and is still present
-on the consult leg. Missing, contradictory, or ordinary CONNECTED/HELD media snapshots
-are non-terminal. Accepted consultees emit
-`task:consultEnd` and `task:end`, while an unaccepted OFFERED consultee retains
-the existing consult-end-only signal. A surviving consult initiator still
-returns to the main-call state selected by the existing guards. Starting a
-consult preserves the prior task snapshot so this membership comparison remains
-available while the consult is initiating.
+participant-left and task-end lifecycle. `PARTICIPANT_LEAVE` is handled in
+`HELD`, `RESUME_INITIATING`, `CONSULTING`, `CONSULT_INITIATING`, and
+`CONFERENCING`; `CONNECTED`, `HOLD_INITIATING`, and `CONF_INITIATING` ignore the
+event. The current Agent is treated as departed only when the event names that
+Agent or the updated participants map omits that Agent (EP-DN removal). Remaining
+in the map with `hasLeft`, or disappearing only from `mainCall` media, is
+non-terminal. A consulted Agent receiving `AgentConsultEnded` continues through
+`CONSULT_END`; current-agent departure is evaluated before consult-initiator
+recovery and does not use mainCall membership as self-departure evidence.
+Accepted consultees emit `task:consultEnd` and `task:end`, while an unaccepted
+OFFERED consultee retains the existing consult-end-only signal. A surviving
+consult initiator still returns to the main-call state selected by the existing
+guards. The state-machine transition table lives in
+`src/services/task/state-machine/ai-docs/task-state-machine-spec.md`
+`TASK_STATE_MACHINE-R-008`.
 
 Primary-Agent promotion remains backend-authoritative and follows the two-event
 desktop contract. `ContactOwnerChanged` updates the promoted Agent; TaskManager

package/src/services/task/state-machine/TaskStateMachine.ts

@@ -416,14 +416,6 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
               actions: ['updateTaskData', 'clearConsultState', 'emitTaskConsultEnd'],
             },
           ],
-          // Routing lifecycle events can arrive out of order in child-task/EP-DN flows. The
-          // local actor may still be CONNECTED when ParticipantLeftConference reports that this
-          // agent left the main interaction. Handle that self-departure race; for another
-          // participant, the action-only fallback updates data while preserving CONNECTED.
-          [TaskEvent.PARTICIPANT_LEAVE]: [
-            ...currentAgentParticipantLeaveTransitions(),
-            {actions: ['updateTaskData', 'handleParticipantLeft', 'emitTaskParticipantLeft']},
-          ],
           // AgentContactEnded Event
           [TaskEvent.CONTACT_ENDED]: [
             {
@@ -486,13 +478,6 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
             target: TaskState.CONNECTED,
             actions: ['updateTaskData'],
           },
-          // Another agent can remove this agent while the local hold request is awaiting its
-          // routing acknowledgement. Process that backend lifecycle event independently of
-          // whether Drop was initiated from this task; another-participant event preserves state.
-          [TaskEvent.PARTICIPANT_LEAVE]: [
-            ...currentAgentParticipantLeaveTransitions(),
-            {actions: ['updateTaskData', 'handleParticipantLeft', 'emitTaskParticipantLeft']},
-          ],
           [TaskEvent.OUTBOUND_FAILED]: [
             {
               guard: guards.shouldWrapUp,
@@ -626,7 +611,6 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
           [TaskEvent.UNHOLD_FAILED]: {
             target: TaskState.HELD,
           },
-          // The same remote-removal race can occur while an unhold request is in flight.
           [TaskEvent.PARTICIPANT_LEAVE]: [
             ...currentAgentParticipantLeaveTransitions(),
             {actions: ['updateTaskData', 'handleParticipantLeft', 'emitTaskParticipantLeft']},
@@ -1020,10 +1004,6 @@ export function getTaskStateMachineConfig(uiControlConfig: UIControlConfig) {
               actions: ['updateTaskData', 'clearConsultState'],
             },
           ],
-          [TaskEvent.PARTICIPANT_LEAVE]: [
-            ...currentAgentParticipantLeaveTransitions(),
-            {actions: ['updateTaskData', 'handleParticipantLeft', 'emitTaskParticipantLeft']},
-          ],
           [TaskEvent.OUTBOUND_FAILED]: [
             {
               guard: guards.shouldWrapUp,

package/src/services/task/state-machine/ai-docs/AGENTS.md

@@ -274,10 +274,8 @@ didCurrentAgentLeaveMainInteraction(context, event) {
   const participantIdFromEvent = 'participantId' in event ? event.participantId : undefined;
   const participantId = participantIdFromEvent ?? event.taskData?.participantId;
   if (Boolean(participantId) && participantId === selfAgentId) return true;
-  // Explicit hasLeft or removal of a previously active self from the participant map is terminal.
-  // PARTICIPANT_LEAVE naming another participant does not infer self departure from media.
-  // Only a from-conference CONSULT_END may compare mainCall membership, and only when self
-  // remains active in the participant map and on the consult leg. Partial ordinary calls are false.
+  // Self missing from the updated participants map is terminal (EP-DN removal).
+  // Remaining in the map with hasLeft, or disappearing only from mainCall media, is not.
 }
 ```
 

package/src/services/task/state-machine/ai-docs/ARCHITECTURE.md

@@ -476,13 +476,12 @@ It is instantiated by `Task` and receives mapped backend/user events through `se
   - Guard: default
   - Actions: `updateTaskData`, `handleParticipantLeft`, `emitTaskParticipantLeft`
 
-`didCurrentAgentLeaveMainInteraction` treats an explicit self participant ID,
-self `hasLeft`, or removal from a previously active participant map as terminal.
-A `PARTICIPANT_LEAVE` event naming another participant does not infer departure
-from media membership. The previous-versus-updated `mainCall` comparison is
-restricted to from-conference `CONSULT_END` nested-consult cleanup when self
-remains active in the participant map and on the consult leg; partial ordinary CONNECTED/HELD
-snapshots remain non-terminal.
+`didCurrentAgentLeaveMainInteraction` treats an explicit self participant ID
+or absence from the updated participants map as terminal (EP-DN removal).
+Remaining in the map with `hasLeft`, or disappearing only from `mainCall` media,
+is not treated as departure. `PARTICIPANT_LEAVE` is handled in `HELD`,
+`RESUME_INITIATING`, `CONSULTING`, `CONSULT_INITIATING`, and `CONFERENCING`;
+`CONNECTED`, `HOLD_INITIATING`, and `CONF_INITIATING` ignore the event.
 
 - `CONFERENCE_END` -> `WRAPPING_UP`
   - Guard: `guards.shouldWrapUp`
@@ -758,7 +757,7 @@ Complete mapping from backend CC_EVENTS to internal TaskEvent types.
 | `PARTICIPANT_JOINED_CONFERENCE`    | `CONFERENCE_START`            | `CONSULTING` / `CONF_INITIATING` / `CONFERENCING`    | `CONFERENCING` / same                                                         | Conference participant joined     |
 | `AGENT_CONSULT_CONFERENCE_FAILED`  | `CONFERENCE_FAILED`           | `CONF_INITIATING`                                    | `CONSULTING`                                                                  | Merge fail fallback               |
 | `AGENT_CONSULT_CONFERENCE_ENDED`   | `CONFERENCE_END`              | `CONFERENCING`                                       | `WRAPPING_UP` / `CONNECTED` / `TERMINATED`                                    | Guard-driven                      |
-| `PARTICIPANT_LEFT_CONFERENCE`      | `PARTICIPANT_LEAVE`           | `CONFERENCING`                                       | `WRAPPING_UP` / `TERMINATED` / `CONNECTED` / same                             | Ownership + downgrade guards      |
+| `PARTICIPANT_LEFT_CONFERENCE`      | `PARTICIPANT_LEAVE`           | `HELD` / `RESUME_INITIATING` / `CONSULTING` / `CONSULT_INITIATING` / `CONFERENCING` | `WRAPPING_UP` / `TERMINATED` / `CONNECTED` / same | Named self or omitted from participant map; `CONNECTED` / `HOLD_INITIATING` / `CONF_INITIATING` ignore |
 | `AGENT_CONFERENCE_TRANSFERRED`     | `TRANSFER_CONFERENCE_SUCCESS` | `CONSULTING` / `CONFERENCING`                        | `WRAPPING_UP` / `CONFERENCING` / `TERMINATED` / same                          | Initiator/receiver dependent      |
 
 ### Explicitly not mapped to state machine
@@ -818,7 +817,7 @@ Complete mapping from backend CC_EVENTS to internal TaskEvent types.
 | API `task.consultConference()`   | `MERGE_TO_CONFERENCE`         | CONSULTING → CONF_INITIATING                               | Starts merge flow                                                                             |
 | `AgentConsultConferenced`        | `CONFERENCE_START`            | CONSULTING/CONF_INITIATING → CONFERENCING                  | `handleConferenceStarted` path                                                                |
 | `ParticipantJoinedConference`    | `CONFERENCE_START`            | CONFERENCING → CONFERENCING                                | Refresh + emit conference started                                                             |
-| `ParticipantLeftConference`      | `PARTICIPANT_LEAVE`           | Any active call-control state → WRAPPING_UP / TERMINATED / CONNECTED / stay | Uses `didCurrentAgentLeaveMainInteraction`, `shouldWrapUp`, `shouldDowngradeConferenceToConnected` |
+| `ParticipantLeftConference`      | `PARTICIPANT_LEAVE`           | HELD / RESUME_INITIATING / CONSULTING / CONSULT_INITIATING / CONFERENCING → WRAPPING_UP / TERMINATED / CONNECTED / stay; CONNECTED / HOLD_INITIATING / CONF_INITIATING ignore | Uses `didCurrentAgentLeaveMainInteraction` (named self or omitted from participant map), `shouldWrapUp`, `shouldDowngradeConferenceToConnected` |
 | `AgentConsultConferenceEnded`    | `CONFERENCE_END`              | CONFERENCING → WRAPPING_UP / CONNECTED / TERMINATED        | Guard-based branch                                                                            |
 | `AgentConsultConferenceFailed`   | `CONFERENCE_FAILED`           | CONF_INITIATING → CONSULTING                               | Merge failed fallback                                                                         |
 | `AgentConferenceTransferred`     | `TRANSFER_CONFERENCE_SUCCESS` | CONSULTING/CONFERENCING branch logic                       | Initiator/receiver dependent                                                                  |