@webex/contact-center 3.12.0-llmrefactor.2 → 3.12.0-llmrefactor.3

package/src/services/WebexCrossClientService.ts

@@ -0,0 +1,212 @@
+import LoggerProxy from '../logger-proxy';
+import {METHODS} from '../constants';
+import {WebexSDK} from '../types';
+
+const WEBEX_CROSS_CLIENT_FILE = 'WebexCrossClientService';
+const DEFAULT_CROSS_CLIENT_STATE_TTL = 900;
+const EXPIRATION_OFFSET_MS = 60_000;
+/** Must match Agent Desktop usersub publish — Webex App reads `wxcc` cross-client state. */
+const DEFAULT_APP_NAME = 'wxcc';
+const REFRESH_RETRY_DELAY_MS = 30_000;
+const MAX_REFRESH_RETRIES = 3;
+
+type RefreshTimer = ReturnType<typeof setTimeout>;
+
+/**
+ * Publishes usersub cross-client state so Webex App suppresses native calling toasts (WXCC-6026).
+ */
+export default class WebexCrossClientService {
+  private webex: WebexSDK;
+  private refreshTimer?: RefreshTimer;
+  private refreshRetryTimer?: RefreshTimer;
+  private answerCallsState = false;
+  private appName = DEFAULT_APP_NAME;
+  /** Incremented on teardown/disable to ignore stale refresh timer callbacks. */
+  private refreshGeneration = 0;
+
+  constructor(webex: WebexSDK) {
+    this.webex = webex;
+  }
+
+  private extractDeviceIdFromUrl(url: string): string {
+    const match = url.match(/\/devices\/([^/?]+)/);
+
+    return match ? match[1] : '';
+  }
+
+  private getDeviceUrl(): string | undefined {
+    return this.webex.internal.device?.url;
+  }
+
+  private clearRefreshTimer(): void {
+    if (this.refreshTimer) {
+      clearTimeout(this.refreshTimer);
+      this.refreshTimer = undefined;
+    }
+
+    if (this.refreshRetryTimer) {
+      clearTimeout(this.refreshRetryTimer);
+      this.refreshRetryTimer = undefined;
+    }
+  }
+
+  private scheduleRefreshRetry(
+    userId: string,
+    ttl: number,
+    scheduledGeneration: number,
+    retryAttempt: number
+  ): void {
+    if (
+      retryAttempt >= MAX_REFRESH_RETRIES ||
+      scheduledGeneration !== this.refreshGeneration ||
+      !this.answerCallsState
+    ) {
+      return;
+    }
+
+    this.refreshRetryTimer = setTimeout(async () => {
+      if (scheduledGeneration !== this.refreshGeneration || !this.answerCallsState) {
+        return;
+      }
+
+      try {
+        await this.setManageWebexCallingInWxcc(true, {userId, ttl, appName: this.appName});
+      } catch (error) {
+        LoggerProxy.error(`WebexCrossClientService refresh retry failed: ${error}`, {
+          module: WEBEX_CROSS_CLIENT_FILE,
+          method: METHODS.SET_MANAGE_WEBEX_CALLING_IN_WXCC,
+        });
+        this.scheduleRefreshRetry(userId, ttl, scheduledGeneration, retryAttempt + 1);
+      }
+    }, REFRESH_RETRY_DELAY_MS);
+  }
+
+  private startRefreshTimer(userId: string, ttl: number): void {
+    this.clearRefreshTimer();
+
+    if (!this.answerCallsState) {
+      return;
+    }
+
+    const refreshTime = ttl * 1000 - EXPIRATION_OFFSET_MS;
+    const scheduledGeneration = this.refreshGeneration;
+    this.refreshTimer = setTimeout(async () => {
+      if (scheduledGeneration !== this.refreshGeneration || !this.answerCallsState) {
+        return;
+      }
+
+      try {
+        await this.setManageWebexCallingInWxcc(true, {userId, ttl, appName: this.appName});
+      } catch (error) {
+        LoggerProxy.error(`WebexCrossClientService refresh failed: ${error}`, {
+          module: WEBEX_CROSS_CLIENT_FILE,
+          method: METHODS.SET_MANAGE_WEBEX_CALLING_IN_WXCC,
+        });
+        this.scheduleRefreshRetry(userId, ttl, scheduledGeneration, 0);
+      }
+    }, refreshTime);
+  }
+
+  private publishCrossClientState(
+    users: string[],
+    ttl: number,
+    composition: Record<string, unknown>,
+    logContext: string
+  ): Promise<unknown> {
+    const body = {
+      users,
+      compositions: [
+        {
+          type: 'cross-client-state',
+          ttl,
+          composition,
+        },
+      ],
+    };
+
+    return this.webex
+      .request({
+        method: 'POST',
+        service: 'usersub',
+        resource: 'publish',
+        body,
+      })
+      .then((response: {body?: unknown}) => response?.body)
+      .catch((error: unknown) => {
+        LoggerProxy.error(`WebexCrossClientService.${logContext} failed: ${error}`, {
+          module: WEBEX_CROSS_CLIENT_FILE,
+          method: METHODS.SET_MANAGE_WEBEX_CALLING_IN_WXCC,
+        });
+
+        return Promise.reject(error);
+      });
+  }
+
+  public async setManageWebexCallingInWxcc(
+    enable: boolean,
+    options?: {userId?: string; ttl?: number; appName?: string}
+  ): 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;
+    this.appName = appName;
+
+    if (!userId) {
+      throw new Error('User ID is unavailable for cross-client publish');
+    }
+
+    const deviceUrl = this.getDeviceUrl();
+    if (!deviceUrl) {
+      throw new Error('Device URL is unavailable for cross-client publish');
+    }
+
+    const composition = {
+      devices: [
+        {
+          deviceId: this.extractDeviceIdFromUrl(deviceUrl),
+          appName,
+          state: {
+            'answer-calls-on-wxcc': enable,
+          },
+        },
+      ],
+    };
+
+    await this.publishCrossClientState([userId], ttl, composition, 'setManageWebexCallingInWxcc');
+
+    if (operationGeneration !== this.refreshGeneration) {
+      return;
+    }
+
+    this.answerCallsState = enable;
+
+    if (enable) {
+      this.startRefreshTimer(userId, ttl);
+    } else {
+      this.refreshGeneration += 1;
+      this.clearRefreshTimer();
+    }
+
+    LoggerProxy.info(`Cross-client answer-calls-on-wxcc set to ${enable}`, {
+      module: WEBEX_CROSS_CLIENT_FILE,
+      method: METHODS.SET_MANAGE_WEBEX_CALLING_IN_WXCC,
+      data: {
+        appName,
+        deviceId: this.extractDeviceIdFromUrl(deviceUrl),
+        ttl,
+      },
+    });
+  }
+
+  public teardown(): void {
+    this.refreshGeneration += 1;
+    this.clearRefreshTimer();
+    this.answerCallsState = false;
+  }
+
+  /** Whether usersub `answer-calls-on-wxcc: true` was successfully published this session. */
+  public isAnswerCallsStateActive(): boolean {
+    return this.answerCallsState;
+  }
+}

package/src/services/WxAppTelephonyMercurySync.ts

@@ -0,0 +1,115 @@
+import LoggerProxy from '../logger-proxy';
+import {METHODS} from '../constants';
+import {WebexSDK} from '../types';
+
+const WXAPP_TELEPHONY_MERCURY_SYNC_FILE = 'WxAppTelephonyMercurySync';
+
+export const TELEPHONY_CALL_MUTED = 'event:telephony_calls.muted';
+export const TELEPHONY_CALL_UNMUTED = 'event:telephony_calls.unmuted';
+
+export type UpdatedCallMuteStateEvent = {
+  data: {
+    actorId: string;
+    callId: string;
+    muted: boolean;
+  };
+};
+
+type MuteChangeHandler = (callId: string, muted: boolean) => void;
+
+/**
+ * Subscribes to Mercury telephony mute/unmute events for wxApp thick-client sync (AD parity).
+ */
+export default class WxAppTelephonyMercurySync {
+  private webex: WebexSDK;
+  private subscribedAgentId?: string;
+  private muteChangeHandler?: MuteChangeHandler;
+  private boundMuteHandler?: (event: UpdatedCallMuteStateEvent) => void;
+  private boundUnmuteHandler?: (event: UpdatedCallMuteStateEvent) => void;
+
+  constructor(webex: WebexSDK) {
+    this.webex = webex;
+  }
+
+  private decodeBase64(value: string): string {
+    try {
+      return atob(value);
+    } catch {
+      return value;
+    }
+  }
+
+  private handleMuteStateEvent = (agentId: string, event: UpdatedCallMuteStateEvent): void => {
+    const {actorId, callId, muted} = event?.data ?? {};
+    if (!actorId || !callId || muted === undefined) {
+      return;
+    }
+
+    const decodedActorId = this.decodeBase64(actorId);
+    const decodedCallId = this.decodeBase64(callId);
+
+    if (!decodedActorId.endsWith(agentId)) {
+      return;
+    }
+
+    LoggerProxy.info('WxApp telephony mute state sync received', {
+      module: WXAPP_TELEPHONY_MERCURY_SYNC_FILE,
+      method: METHODS.SYNC_WXAPP_MUTE_FROM_MERCURY,
+      data: {muted},
+    });
+
+    this.muteChangeHandler?.(decodedCallId, muted);
+  };
+
+  public subscribe(agentId: string, onMuteChange: MuteChangeHandler): void {
+    this.unsubscribe();
+
+    const mercury = this.webex.internal.mercury;
+    if (!mercury) {
+      LoggerProxy.error('Mercury is unavailable for wxApp mute sync', {
+        module: WXAPP_TELEPHONY_MERCURY_SYNC_FILE,
+        method: METHODS.SYNC_WXAPP_MUTE_FROM_MERCURY,
+      });
+
+      return;
+    }
+
+    this.subscribedAgentId = agentId;
+    this.muteChangeHandler = onMuteChange;
+
+    this.boundMuteHandler = (event: UpdatedCallMuteStateEvent) => {
+      this.handleMuteStateEvent(agentId, event);
+    };
+    this.boundUnmuteHandler = (event: UpdatedCallMuteStateEvent) => {
+      this.handleMuteStateEvent(agentId, event);
+    };
+
+    mercury.on(TELEPHONY_CALL_MUTED, this.boundMuteHandler);
+    mercury.on(TELEPHONY_CALL_UNMUTED, this.boundUnmuteHandler);
+
+    LoggerProxy.info('Subscribed to wxApp telephony Mercury mute sync', {
+      module: WXAPP_TELEPHONY_MERCURY_SYNC_FILE,
+      method: METHODS.SYNC_WXAPP_MUTE_FROM_MERCURY,
+    });
+  }
+
+  public unsubscribe(): void {
+    const mercury = this.webex.internal.mercury;
+
+    if (mercury && this.boundMuteHandler) {
+      mercury.off(TELEPHONY_CALL_MUTED, this.boundMuteHandler);
+    }
+    if (mercury && this.boundUnmuteHandler) {
+      mercury.off(TELEPHONY_CALL_UNMUTED, this.boundUnmuteHandler);
+    }
+
+    this.subscribedAgentId = undefined;
+    this.muteChangeHandler = undefined;
+    this.boundMuteHandler = undefined;
+    this.boundUnmuteHandler = undefined;
+  }
+
+  public isSubscribed(): boolean {
+    return Boolean(this.subscribedAgentId && this.muteChangeHandler);
+  }
+}

package/src/services/ai-docs/AGENTS.md

@@ -109,12 +109,12 @@ src/services/
 │       └── ARCHITECTURE.md
 │
 ├── AddressBook.ts              # Address book entries — getEntries() with pagination/cache
-├── EntryPoint.ts               # Entry points — getEntryPoints() with pagination/cache
+├── EntryPoint.ts               # Profile-scoped entry-point dial-number mappings (uncached)
 ├── Queue.ts                    # Queues — getQueues() with pagination/cache
 └── WebCallingService.ts        # WebRTC calling — register/deregister line, answer/mute/decline
 ```
 
-Note: The `src/utils/` folder (sibling to `src/services/`) contains shared utilities like [`PageCache.ts`](../../utils/PageCache.ts) which provides generic pagination caching with `BaseSearchParams`, `PaginatedResponse`, and `PaginationMeta` types used by all data services.
+Note: The `src/utils/` folder (sibling to `src/services/`) contains [`PageCache.ts`](../../utils/PageCache.ts), which provides pagination contracts/defaults shared by data-service types and optional page caching used by AddressBook and Queue. EntryPoint deliberately bypasses PageCache because every request is profile-scoped.
 
 ### Shared Constants (`src/services/constants.ts`)
 
@@ -137,8 +137,8 @@ Use [`constants.ts`](../constants.ts) as the canonical source for service-level
 | **Task Management** | [`task/`](../task/TaskManager.ts) | Task lifecycle (accept, hold, transfer, conference, wrapup), Task state machine, contact operations, outbound dialing |
 | **Configuration** | [`config/`](../config/index.ts) | Agent profile aggregation from 8+ API endpoints, org settings, teams, aux codes, dial plans |
 | **Core Infrastructure** | [`core/`](../core/WebexRequest.ts) | HTTP requests (`WebexRequest`), WebSocket management (`WebSocketManager`), connection lifecycle (`ConnectionService`), AQM request/response correlation (`AqmReqs`), error handling (`Utils`, `Err`) |
-| **Data Services** | [`AddressBook.ts`](../AddressBook.ts), [`Queue.ts`](../Queue.ts), [`EntryPoint.ts`](../EntryPoint.ts) | Standalone REST-based data services with pagination and caching for address books, queues, and entry points |
-| **Utilities** | [`src/utils/PageCache.ts`](../../utils/PageCache.ts) | Shared `PageCache<T>` generic class for pagination caching, plus `BaseSearchParams`, `PaginatedResponse`, and `PaginationMeta` types used by all data services |
+| **Data Services** | [`AddressBook.ts`](../AddressBook.ts), [`Queue.ts`](../Queue.ts), [`EntryPoint.ts`](../EntryPoint.ts) | Standalone REST-based paginated services; AddressBook and Queue optionally cache eligible pages, while profile-scoped EntryPoint requests are always fetched |
+| **Utilities** | [`src/utils/PageCache.ts`](../../utils/PageCache.ts) | Shared pagination contracts/defaults plus optional `PageCache<T>` reuse for AddressBook and Queue |
 | **WebRTC Calling** | [`WebCallingService.ts`](../WebCallingService.ts) | Browser-based voice calling via `@webex/calling`, line registration, call answer/mute/decline |
 
 ---
@@ -156,7 +156,7 @@ Each service folder contains its own `ai-docs/` with detailed documentation. **A
 
 > **Note**: The task state machine (`task/state-machine/`) is part of the Task service, not a separate service. Its dedicated docs live at [`task/state-machine/ai-docs/AGENTS.md`](../task/state-machine/ai-docs/AGENTS.md) and [`ARCHITECTURE.md`](../task/state-machine/ai-docs/ARCHITECTURE.md). Load these when working on state transitions, guards, or actions.
 
-**Data services** (AddressBook, Queue, EntryPoint) do not have dedicated ai-docs. Read their source files directly — they follow shared REST/pagination/caching patterns documented in [`ai-docs/patterns/typescript-patterns.md`](../../../ai-docs/patterns/typescript-patterns.md).
+**Data services** (AddressBook, Queue, EntryPoint) do not have dedicated ai-docs. Read their source files directly. They share direct REST, pagination, logging, metrics, and error propagation, but cache policy is service-owned: AddressBook/Queue use PageCache when eligible and EntryPoint always fetches its profile-scoped mapping.
 
 **WebCallingService** also has no dedicated ai-docs, but it follows a different pattern: EventEmitter-based call lifecycle orchestration around `@webex/calling` (`createClient`, line registration/deregistration, `ICall` events), `callTaskMap` tracking, and async registration flows with timeout handling. Read [`WebCallingService.ts`](../WebCallingService.ts) directly when changing browser calling behavior.
 
@@ -271,16 +271,16 @@ const services = Services.getInstance({
 
 ## Data Services Pattern (AddressBook, Queue, EntryPoint)
 
-These three services share an identical pattern. Use any one as a reference when creating similar services:
+These services share the direct REST and pagination pattern, with service-specific request mapping and cache policy:
 
 | Aspect | Pattern |
 |---|---|
-| **Class structure** | Standalone class with `WebexRequest`, `WebexSDK`, `MetricsManager`, `PageCache` |
+| **Class structure** | Standalone class with `WebexRequest`, `WebexSDK`, and `MetricsManager`; cache-enabled services additionally own `PageCache` |
 | **Constructor** | `constructor(webex: WebexSDK)` — gets singletons via `.getInstance()` |
 | **HTTP calls** | `this.webexRequest.request({service: WCC_API_GATEWAY, resource, method: HTTP_METHODS.GET})` |
 | **Endpoints** | Uses `endPointMap` functions from `config/constants.ts` to build URL paths |
-| **Pagination** | Query params with `page`, `pageSize`; uses `PageCache` for caching |
-| **Caching** | `PageCache<T>` — caches pages for simple pagination, bypasses cache for search/filter |
+| **Pagination** | Query params with `page` and `pageSize` |
+| **Caching** | AddressBook/Queue may use `PageCache<T>` for eligible pages; EntryPoint always fetches because its request is desktop-profile scoped |
 | **Metrics** | `timeEvent` on API call start, `trackEvent` on success/failure |
 | **Logging** | `LoggerProxy` with `{module: 'ClassName', method: 'methodName'}` context |
 | **Error handling** | try/catch with `LoggerProxy.error` + `metricsManager.trackEvent` for failures, then re-throw so callers receive the error |
@@ -288,7 +288,7 @@ These three services share an identical pattern. Use any one as a reference when
 Reference files:
 - [`AddressBook.ts`](../AddressBook.ts) — includes `addressBookId` parameter
 - [`Queue.ts`](../Queue.ts) — includes additional query params (sortBy, sortOrder, etc.)
-- [`EntryPoint.ts`](../EntryPoint.ts) — simplest example
+- [`EntryPoint.ts`](../EntryPoint.ts) — profile-scoped dial-number mapping without PageCache
 
 ---
 

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

@@ -54,6 +54,7 @@ The `src/services/` directory is the service layer of the `@webex/contact-center
 | **User Preferences** | [`UserPreference.ts`](../UserPreference.ts) | Direct REST CRUD service exposed as `cc.userPreference`; it resolves the default user from agent configuration and does not use PageCache |
 | **Utilities** | [`src/utils/PageCache.ts`](../../utils/PageCache.ts) | Shared `PageCache<T>` generic class for pagination caching, plus `BaseSearchParams`, `PaginatedResponse`, and `PaginationMeta` types used by all data services |
 | **WebRTC Calling** | [`WebCallingService.ts`](../WebCallingService.ts) | Browser-based voice calling via `@webex/calling`, line registration, call answer/mute/decline |
+| **WxApp Better Together** | [`WebexCrossClientService.ts`](../WebexCrossClientService.ts), [`AnswerCallOnWebexService.ts`](../AnswerCallOnWebexService.ts), [`WxAppTelephonyMercurySync.ts`](../WxAppTelephonyMercurySync.ts) | usersub cross-client publish (`answer-calls-on-wxcc`), Hydra telephony REST (answer/reject/mute/DTMF/GET call), Mercury mute sync — orchestrated from `cc.ts` when `enableWxBetterTogether` is active |
 
 Each service folder contains its own `ai-docs/` with detailed documentation. **Always load the relevant service docs before making changes.**
 
@@ -227,6 +228,7 @@ Use [`constants.ts`](../constants.ts) as the canonical source for service-level
 | Contract ID | Type | Surface | Purpose | Compatibility / deprecation | Schema / detail link | Root index |
 |---|---|---|---|---|---|---|
 | `services.surface` | SDK / event / internal API | Internal `Services.getInstance()` composition root plus data-service and calling collaborators consumed by `ContactCenter`. | Stable module consumption boundary. | Additive changes by default; breaking package exports require a major-version transition. | `src/services/index.ts` | `../../../ai-docs/CONTRACTS.md` |
+| `services.destination-lists` | SDK data API | Existing `Queue.getQueues(ContactServiceQueueSearchParams)` and `EntryPoint.getEntryPoints(EntryPointSearchParams)` methods with full-record paginated responses. | Apply consult/transfer telephony eligibility, profile views, and backend name ordering as overridable defaults. | Behavioral default correction on existing methods; no specialized method, projected response, or replacement signature. | `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/types.ts` | `../../../ai-docs/CONTRACTS.md` |
 | `services.user-preference` | SDK data API | `UserPreference` and `cc.userPreference`. | Direct REST CRUD for user preferences; separate from PageCache-based pagination services. | Additive semver-public API; removals or signature changes are breaking. | `src/services/UserPreference.ts`, `src/services/config/types.ts` | `../../../ai-docs/CONTRACTS.md` |
 
 Compatibility notes:
@@ -261,6 +263,7 @@ ContactCenter READY callback
 | SERVICES-R-004 | Pass ApiAIAssistant, contact routing, WebCallingService, primary WebSocket, and RTD WebSocket into TaskManager. | Voice, task, transcript, and suggestion behavior depend on the complete collaborator set. | `src/cc.ts` | `test/unit/spec/services/task/TaskManager.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
 | SERVICES-R-005 | Inherit authenticated request identity from the host Webex SDK through Core/WebexRequest; Services must not store, parse, or refresh credentials. | One host-owned authentication boundary avoids duplicate token handling and credential leakage across composed services. | `src/services/index.ts`, `src/services/core/WebexRequest.ts` | `test/unit/spec/services/core/WebexRequest.ts` | None; authentication ownership is explicit. | PRESENT |
 | SERVICES-R-006 | Treat Services composition as unconditionally created by the ContactCenter READY callback; Services owns no rollout or feature-flag decision. | Capability flags belong to the consuming config/task/calling collaborators, so the composition root must not silently gate construction. | `src/services/index.ts`, `src/cc.ts` | `test/unit/spec/cc.ts` | None; rollout applicability is explicitly N/A for Services. | PRESENT |
+| SERVICES-R-007 | Existing Queue and EntryPoint list methods must apply inbound, active, telephony, profile/agent-view, and `name,ASC` defaults while retaining their established parameter and full-record response types. Caller-supplied existing filter, sort, or profile inputs override defaults. Queue must also treat `sortOrder` without `sortBy` as a name sort and bypass the simple-page cache. | Defaults on the established methods let thin consumers request lists without a parallel API, while existing parameters preserve specialized behavior for other consumers and full-record types remain truthful because no field projection is requested. | `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/types.ts` | `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts`, `test/unit/spec/cc.ts` | The backend honors the view flags and combined CMS sort value. | PRESENT |
 
 ## Design Overview
 `Services` is a singleton composition root for transport-facing capabilities only. It constructs two `WebSocketManager` instances (primary Contact Center and RTD), creates `AqmReqs` on the primary manager, then creates config, agent, contact, dialer, and ConnectionService collaborators.
@@ -419,7 +422,8 @@ These three services share an identical pattern. Use any one as a reference when
 | **HTTP calls** | `this.webexRequest.request({service: WCC_API_GATEWAY, resource, method: HTTP_METHODS.GET})` |
 | **Endpoints** | Uses `endPointMap` functions from `config/constants.ts` to build URL paths |
 | **Pagination** | Query params with `page`, `pageSize`; uses `PageCache` for caching |
-| **Caching** | `PageCache<T>` — caches pages for simple pagination, bypasses cache for search/filter |
+| **Caching** | `PageCache<T>` — caches pages for simple pagination and bypasses cache for result/shape variants, including an effective Queue sort |
+| **Consult/transfer policy** | Existing Queue and EntryPoint methods apply telephony eligibility, profile views, and backend name ordering by default, accept overrides through their existing query parameters, and return full-record responses unchanged |
 | **Metrics** | `timeEvent` on API call start, `trackEvent` on success/failure |
 | **Logging** | `LoggerProxy` with `{module: 'ClassName', method: 'methodName'}` context |
 | **Error handling** | try/catch with `LoggerProxy.error` + `metricsManager.trackEvent` for failures, then re-throw so callers receive the error |
@@ -476,6 +480,7 @@ Unit tests mirror module paths under `test/unit/spec/services`. Preserve positiv
 | `SERVICES-R-004` | `test/unit/spec/services/task/TaskManager.ts`, `test/unit/spec/cc.ts` | None. |
 | `SERVICES-R-005` | `test/unit/spec/services/core/WebexRequest.ts` | None. |
 | `SERVICES-R-006` | `test/unit/spec/cc.ts` | None. |
+| `SERVICES-R-007` | `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts`, `test/unit/spec/cc.ts` | None. |
 
 ## Traceability
 - Repo architecture: `../../../ai-docs/ARCHITECTURE.md` · Registry: `../../../ai-docs/SPEC_INDEX.md`

package/src/services/config/Util.ts

@@ -238,6 +238,9 @@ function parseAgentConfigs(profileData: {
     callVariablesSuppressed: tenantData.callVariablesSuppressed,
     agentDbId: userData.dbId,
     allowConsultToQueue: agentProfileData.consultToQueue,
+    accessQueue: agentProfileData.accessQueue,
+    accessEntryPoint: agentProfileData.accessEntryPoint,
+    accessBuddyTeam: agentProfileData.accessBuddyTeam,
     agentPersonalStatsEnabled: agentProfileData.viewableStatistics
       ? agentProfileData.viewableStatistics.agentStats
       : false,

package/src/services/config/ai-docs/AGENTS.md

@@ -156,7 +156,7 @@ Additionally, the following endpoints are defined in `constants.ts` `endPointMap
 | Endpoint | Used By | Description |
 |----------|---------|-------------|
 | `queueList` | [`Queue.ts`](../../Queue.ts) | Fetch contact service queues |
-| `entryPointList` | [`EntryPoint.ts`](../../EntryPoint.ts) | Fetch entry points |
+| `entryPointDialNumberList` | [`EntryPoint.ts`](../../EntryPoint.ts) | Fetch profile-scoped entry-point dial-number mappings |
 | `addressBookEntries` | [`AddressBook.ts`](../../AddressBook.ts) | Fetch address book entries |
 
 ---

package/src/services/config/ai-docs/ARCHITECTURE.md

@@ -132,8 +132,8 @@ export const endPointMap = {
   queueList: (orgId: string, queryParams: string) =>
     `/organization/${orgId}/v2/contact-service-queue?${queryParams}`,
 
-  entryPointList: (orgId: string, queryParams: string) =>
-    `/organization/${orgId}/v2/entry-point?${queryParams}`,
+  entryPointDialNumberList: (orgId: string, queryParams: string) =>
+    `/organization/${orgId}/v3/dial-number?${queryParams}`,
 
   addressBookEntries: (orgId: string, addressBookId: string, queryParams: string) =>
     `/organization/${orgId}/v2/address-book/${addressBookId}/entry?${queryParams}`,

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

@@ -158,6 +158,12 @@ The AgentProfile is defined as the [`Profile`](../types.ts) type. This is not an
 | `dialPlan` | [`DialPlan`](../types.ts) | Number transformation rules |
 | `isOutboundEnabledForAgent` | boolean | Outbound calling allowed |
 | `outDialEp` | string | Outbound entry point ID |
+| `allowConsultToQueue` | boolean | Whether consult-to-queue is enabled on the Desktop Profile |
+| `accessQueue` | `'ALL' \| 'SPECIFIC' \| 'NONE'` | Collaboration tab queue access scope from Desktop Profile |
+| `accessEntryPoint` | `'ALL' \| 'SPECIFIC' \| 'NONE'` | Collaboration tab entry-point access scope from Desktop Profile |
+| `accessBuddyTeam` | `'ALL' \| 'SPECIFIC' \| 'NONE'` | Collaboration tab buddy-team access scope from Desktop Profile |
+
+`parseAgentConfigs()` maps the three `access*` fields from `DesktopProfileResponse` onto the public `Profile` returned by `cc.register()`.
 
 The following diagram shows how `getAgentConfig` orchestrates multiple API calls and combines their results into the AgentProfile via `parseAgentConfigs()`:
 

package/src/services/config/constants.ts

@@ -1,6 +1,13 @@
 // making query params configurable for List Teams and List Aux Codes API
 export const DEFAULT_PAGE = 0;
 
+/** Desktop Profile access levels for collaboration destination categories. */
+export const COLLABORATION_ACCESS = {
+  ALL: 'ALL',
+  SPECIFIC: 'SPECIFIC',
+  NONE: 'NONE',
+} as const;
+
 /**
  * Default page size for paginated API requests.
  * @type {number}
@@ -258,17 +265,14 @@ export const endPointMap = {
   queueList: (orgId: string, queryParams: string) =>
     `/organization/${orgId}/v2/contact-service-queue?${queryParams}`,
   /**
-   * Gets the endpoint for entry points list with custom query parameters.
+   * Gets the desktop-profile-filtered dial-number mappings used by entry-point destination lists.
    * @param orgId - Organization ID.
    * @param queryParams - Query parameters string.
    * @returns The endpoint URL string.
-   * @public
-   * @example
-   * const url = endPointMap.entryPointList('org123', 'page=0&pageSize=10');
    * @ignore
    */
-  entryPointList: (orgId: string, queryParams: string) =>
-    `/organization/${orgId}/v2/entry-point?${queryParams}`,
+  entryPointDialNumberList: (orgId: string, queryParams: string) =>
+    `/organization/${orgId}/v3/dial-number?${queryParams}`,
   /**
    * Gets the endpoint for address book entries with custom query parameters.
    * @param orgId - Organization ID.

package/src/services/config/types.ts

@@ -1,4 +1,5 @@
 import * as Agent from '../agent/types';
+import {COLLABORATION_ACCESS} from './constants';
 
 /**
  * Generic type for converting a const enum object into a union type of its values
@@ -6,6 +7,9 @@ import * as Agent from '../agent/types';
  */
 type Enum<T extends Record<string, unknown>> = T[keyof T];
 
+/** Desktop Profile access level for a collaboration destination category. */
+export type CollaborationAccess = Enum<typeof COLLABORATION_ACCESS>;
+
 /**
  * Events emitted on task objects
  * @enum {string}
@@ -57,6 +61,8 @@ export const CC_TASK_EVENTS = {
   PARTICIPANT_LEFT_CONFERENCE: 'ParticipantLeftConference',
   /** Event emitted when participant leaving conference fails */
   PARTICIPANT_LEFT_CONFERENCE_FAILED: 'ParticipantLeftConferenceFailed',
+  /** Event emitted when dropping another conference participant fails */
+  PARTICIPANT_DROP_CONFERENCE_FAILED: 'ParticipantDropConferenceFailed',
   /** Event emitted when consultation conference end fails */
   AGENT_CONSULT_CONFERENCE_END_FAILED: 'AgentConsultConferenceEndFailed',
   /** Event emitted when conference is successfully transferred */
@@ -404,9 +410,9 @@ export type DesktopProfileResponse = {
   allowAutoWrapUpExtension: boolean;
 
   /**
-   * Access control for queues assigned to the agent (ALL or SPECIFIC).
+   * Access control for queues assigned to the agent (ALL, SPECIFIC, or NONE).
    */
-  accessQueue: string;
+  accessQueue: CollaborationAccess;
 
   /**
    * Queue identifiers available to the agent when access is SPECIFIC.
@@ -416,7 +422,7 @@ export type DesktopProfileResponse = {
   /**
    * Access control for entry points assigned to the agent.
    */
-  accessEntryPoint: string;
+  accessEntryPoint: CollaborationAccess;
 
   /**
    * Entry point identifiers available to the agent when access is SPECIFIC.
@@ -426,7 +432,7 @@ export type DesktopProfileResponse = {
   /**
    * Access control for buddy teams assigned to the agent.
    */
-  accessBuddyTeam: string;
+  accessBuddyTeam: CollaborationAccess;
 
   /**
    * Buddy team identifiers available to the agent when access is SPECIFIC.
@@ -1169,6 +1175,12 @@ export type Profile = {
   agentAnalyzerId?: string;
   /** Whether consult to queue is allowed */
   allowConsultToQueue: boolean;
+  /** Access control for queues on Desktop Profile Collaboration tab */
+  accessQueue?: CollaborationAccess;
+  /** Access control for entry points on Desktop Profile Collaboration tab */
+  accessEntryPoint?: CollaborationAccess;
+  /** Access control for buddy teams on Desktop Profile Collaboration tab */
+  accessBuddyTeam?: CollaborationAccess;
   /** Additional campaign manager information */
   campaignManagerAdditionalInfo?: string;
   /** Whether personal statistics are enabled */

package/src/services/core/Err.ts

@@ -30,6 +30,7 @@ export type TaskErrorIds =
   | {'Service.aqm.err.trackingId': {trackingId: string}}
   | {'Service.aqm.task.consultAccept': Failure}
   | {'Service.aqm.task.consultConference': Failure}
+  | {'Service.aqm.task.dropConferenceParticipant': Failure}
   | {'Service.aqm.task.consultEnd': Failure}
   | {'Service.aqm.task.cancelCtq': Failure}
   | {'Service.aqm.task.hold': Failure}

package/src/services/core/WebexRequest.ts

@@ -34,14 +34,16 @@ class WebexRequest {
     resource: string;
     method: HTTP_METHODS;
     body?: RequestBody;
+    headers?: Record<string, string | null>;
   }): Promise<IHttpResponse> {
-    const {service, resource, method, body} = options;
+    const {service, resource, method, body, headers} = options;
 
     return this.webex.request({
       service,
       resource,
       method,
       body,
+      ...(headers ? {headers} : {}),
     });
   }