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

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

@@ -0,0 +1,187 @@
+import {LocalMicrophoneStream, CALL_EVENT_KEYS} from '@webex/calling';
+import {CC_FILE} from '../../../constants';
+import {getErrorDetails} from '../../core/Utils';
+import routingContact from '../contact';
+import {
+  TaskData,
+  TaskResponse,
+  TASK_EVENTS,
+  IWebRTC,
+  VoiceUIControlOptions,
+  VOICE_VARIANT,
+} from '../types';
+import Voice from './Voice';
+import WebCallingService from '../../WebCallingService';
+import {WrapupData} from '../../config/types';
+import MetricsManager from '../../../metrics/MetricsManager';
+import {METRIC_EVENT_NAMES} from '../../../metrics/constants';
+import LoggerProxy from '../../../logger-proxy';
+
+export default class WebRTC extends Voice implements IWebRTC {
+  private localAudioStream: LocalMicrophoneStream;
+  private webCallingService: WebCallingService;
+
+  constructor(
+    contact: ReturnType<typeof routingContact>,
+    webCallingService: WebCallingService,
+    data: TaskData,
+    callOptions?: VoiceUIControlOptions,
+    wrapupData?: WrapupData,
+    agentId?: string
+  ) {
+    const mergedCallOptions: VoiceUIControlOptions = {
+      ...callOptions,
+      voiceVariant: VOICE_VARIANT.WEBRTC,
+    };
+
+    super(contact, data, mergedCallOptions, wrapupData, agentId);
+    this.webCallingService = webCallingService;
+    this.registerWebCallListeners();
+  }
+
+  private registerWebCallListeners() {
+    this.webCallingService.on(CALL_EVENT_KEYS.REMOTE_MEDIA, this.handleRemoteMedia);
+  }
+
+  private handleRemoteMedia = (track: MediaStreamTrack) => {
+    this.emit(TASK_EVENTS.TASK_MEDIA, track);
+  };
+
+  /**
+   * This method is used to unregister the web call listeners.
+   * @returns void
+   * @example
+   * ```typescript
+   * task.unregisterWebCallListeners();
+   * ```
+   */
+  public unregisterWebCallListeners() {
+    this.webCallingService.off(CALL_EVENT_KEYS.REMOTE_MEDIA, this.handleRemoteMedia);
+  }
+
+  /**
+   * This is used for incoming task accept by agent.
+   *
+   * @returns Promise<TaskResponse>
+   * @throws Error
+   * @example
+   * ```typescript
+   * task.accept().then(()=>{}).catch(()=>{})
+   * ```
+   */
+  public async accept(): Promise<TaskResponse> {
+    LoggerProxy.log(`Accepting WebRTC task for taskId:${this.data.interactionId}`, {
+      module: 'WebRTC',
+      method: 'accept',
+    });
+    try {
+      this.metricsManager.timeEvent([
+        METRIC_EVENT_NAMES.TASK_ACCEPT_SUCCESS,
+        METRIC_EVENT_NAMES.TASK_ACCEPT_FAILED,
+      ]);
+
+      const constraints = {audio: true};
+      const localStream = await navigator.mediaDevices.getUserMedia(constraints);
+      const audioTrack = localStream.getAudioTracks()[0];
+      this.localAudioStream = new LocalMicrophoneStream(new MediaStream([audioTrack]));
+      this.webCallingService.answerCall(this.localAudioStream, this.data.interactionId);
+
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.TASK_ACCEPT_SUCCESS,
+        {
+          taskId: this.data.interactionId,
+          ...MetricsManager.getCommonTrackingFieldForAQMResponse(this.data),
+        },
+        ['operational', 'behavioral', 'business']
+      );
+
+      return Promise.resolve();
+    } catch (error) {
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.TASK_ACCEPT_FAILED,
+        {
+          taskId: this.data.interactionId,
+          error: error.toString(),
+          ...MetricsManager.getCommonTrackingFieldForAQMResponseFailed(
+            (error as any).details || {}
+          ),
+        },
+        ['operational', 'behavioral', 'business']
+      );
+      const {error: detailedError} = getErrorDetails(error, 'accept', CC_FILE);
+      throw detailedError;
+    }
+  }
+
+  /**
+   * This is used for the incoming task decline by agent.
+   *
+   * @returns Promise<TaskResponse>
+   * @throws Error
+   * @example
+   * ```typescript
+   * task.decline().then(()=>{}).catch(()=>{})
+   * ```
+   */
+  public async decline(): Promise<TaskResponse> {
+    LoggerProxy.log(`Declining WebRTC task for taskId:${this.data.interactionId}`, {
+      module: 'WebRTC',
+      method: 'decline',
+    });
+    try {
+      this.metricsManager.timeEvent([
+        METRIC_EVENT_NAMES.TASK_DECLINE_SUCCESS,
+        METRIC_EVENT_NAMES.TASK_DECLINE_FAILED,
+      ]);
+
+      this.webCallingService.declineCall(this.data.interactionId);
+      this.unregisterWebCallListeners();
+
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.TASK_DECLINE_SUCCESS,
+        {taskId: this.data.interactionId},
+        ['operational', 'behavioral']
+      );
+
+      return Promise.resolve();
+    } catch (error) {
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.TASK_DECLINE_FAILED,
+        {
+          taskId: this.data.interactionId,
+          error: error.toString(),
+          ...MetricsManager.getCommonTrackingFieldForAQMResponseFailed(
+            (error as any).details || {}
+          ),
+        },
+        ['operational', 'behavioral']
+      );
+      const {error: detailedError} = getErrorDetails(error, 'decline', CC_FILE);
+      throw detailedError;
+    }
+  }
+
+  /**
+   * This is used for the placing the call in mute or unmute by the agent.
+   *
+   * @throws Error
+   * @example
+   * ```typescript
+   * task.toggleMute().then(()=>{}).catch(()=>{})
+   * ```
+   */
+  public async toggleMute() {
+    LoggerProxy.log(`Toggling mute WebRTC task for taskId:${this.data.interactionId}`, {
+      module: 'WebRTC',
+      method: 'toggleMute',
+    });
+    try {
+      this.webCallingService.muteUnmuteCall(this.localAudioStream);
+
+      return Promise.resolve();
+    } catch (error) {
+      const {error: detailedError} = getErrorDetails(error, 'mute', CC_FILE);
+      throw detailedError;
+    }
+  }
+}

package/src/types.ts

@@ -6,7 +6,12 @@ import {
 } from '@webex/internal-plugin-metrics/src/metrics.types';
 import * as Agent from './services/agent/types';
 import * as Contact from './services/task/types';
-import {Profile} from './services/config/types';
+import {
+  AIFeatureFlags,
+  Profile,
+  CreateUserPreferenceRequest,
+  UpdateUserPreferenceRequest,
+} from './services/config/types';
 import {PaginatedResponse, BaseSearchParams} from './utils/PageCache';
 
 /**
@@ -156,6 +161,8 @@ export interface CCPluginConfig {
   };
   /** Configuration for the calling client */
   callingClientConfig: CallingClientConfig;
+  /** Whether to skip Mobius/WebRTC registration for browser login flows */
+  disableWebRTCRegistration?: boolean;
 }
 
 /**
@@ -295,6 +302,8 @@ interface IWebexInternal {
     get: (service: string) => string;
     /** Wait for service catalog to be loaded */
     waitForCatalog: (service: string) => Promise<void>;
+    /** Check if current environment is INT (integration) */
+    isIntegrationEnvironment: () => boolean;
     /** Host catalog for service discovery */
     _hostCatalog: Record<string, ServiceHost[]>;
     /** Service URLs cache */
@@ -539,7 +548,10 @@ export type RequestBody =
   | Contact.ConsultTransferPayLoad
   | Contact.cancelCtq
   | Contact.WrapupPayLoad
-  | Contact.DialerPayload;
+  | Contact.DialerPayload
+  | Contact.PreviewContactPayload
+  | CreateUserPreferenceRequest
+  | UpdateUserPreferenceRequest;
 
 /**
  * Represents the options to fetch buddy agents for the logged in agent.
@@ -565,6 +577,25 @@ export type BuddyAgents = {
 };
 
 /**
+ * Holds the configuration flags for the Agent.
+ * These flags determine the availability of certain features in the Agent UI.
+ * @internal
+ */
+export type ConfigFlags = {
+  isEndTaskEnabled: boolean;
+  isEndConsultEnabled: boolean;
+  webRtcEnabled: boolean;
+  autoWrapup: boolean;
+  aiFeature?: AIFeatureFlags;
+  /**
+   * Optional toggle to globally enable/disable recording controls.
+   * Falls back to backend hints when omitted.
+   */
+  isRecordingEnabled?: boolean;
+};
+
+/**
+
  * Generic error structure for Contact Center SDK errors.
  * Contains detailed information about the error context.
  * @public
@@ -817,3 +848,175 @@ export type BuddyAgentsResponse = Agent.BuddyAgentsSuccess | Error;
  * function handleUpdateDeviceType(resp: UpdateDeviceTypeResponse) { ... }
  */
 export type UpdateDeviceTypeResponse = Agent.DeviceTypeUpdateSuccess | Error;
+
+/**
+ * Supported transcript control actions for AI Assistant events.
+ * @public
+ * @example
+ * const action: TranscriptAction = 'START';
+ * @ignore
+ */
+export type TranscriptAction = 'START' | 'STOP';
+
+/**
+ * Parameters used to request AI Assistant real-time assistance.
+ * @public
+ * @example
+ * const params: RealTimeAssistanceParams = {
+ *   interactionId: 'interaction-123',
+ *   context: 'Need help with credit card payment due date',
+ * };
+ */
+export type RealTimeAssistanceParams = {
+  /** Agent identifier */
+  agentId: string;
+  /** Interaction identifier for which assistance should be generated */
+  interactionId: string;
+  /** Optional additional context that should refine the assistance */
+  context?: string;
+  /** Optional language code for assistance (for example, 'en'). Defaults to 'en'. */
+  languageCode?: string;
+};
+
+/**
+ * Supported user actions on an AI Assistant real-time assistance adaptive card.
+ * @public
+ */
+export const RealTimeAssistanceUserActionId = {
+  /** User liked the real-time assistance response */
+  LIKE: 'likeButton',
+  /** User disliked the real-time assistance response */
+  DISLIKE: 'dislikeButton',
+  /** User copied the real-time assistance response */
+  COPY: 'copyButton',
+} as const;
+
+/**
+ * Union type of supported real-time assistance user actions.
+ * @public
+ */
+export type RealTimeAssistanceUserActionId = Enum<typeof RealTimeAssistanceUserActionId>;
+
+/**
+ * Parameters used to send user action feedback for a real-time assistance adaptive card.
+ * @public
+ * @example
+ * const params: RealTimeAssistanceUserActionParams = {
+ *   agentId: 'agent-123',
+ *   interactionId: 'interaction-123',
+ *   adaptiveCardId: 'adaptive-card-123',
+ *   actionId: RealTimeAssistanceUserActionId.LIKE,
+ * };
+ */
+export type RealTimeAssistanceUserActionParams = {
+  /** Agent identifier */
+  agentId: string;
+  /** Interaction identifier associated with the real-time assistance response */
+  interactionId: string;
+  /** Adaptive card identifier from the real-time assistance payload */
+  adaptiveCardId: string;
+  /** User action performed on the adaptive card */
+  actionId: RealTimeAssistanceUserActionId;
+  /** Optional language code. Defaults to 'en'. */
+  languageCode?: string;
+};
+
+/**
+ * Supported AI Assistant event categories.
+ * @public
+ * @example
+ * const eventType: AIAssistantEventType = AIAssistantEventType.CUSTOM_EVENT;
+ * @ignore
+ */
+export const AIAssistantEventType = {
+  /** Custom AI Assistant event */
+  CUSTOM_EVENT: 'CUSTOM_EVENT',
+  /** CTI-backed AI Assistant event */
+  CTI_EVENT: 'CTI_EVENT',
+} as const;
+
+/**
+ * Union type of AI Assistant event categories.
+ * @public
+ * @example
+ * function send(type: AIAssistantEventType) { ... }
+ * @ignore
+ */
+export type AIAssistantEventType = Enum<typeof AIAssistantEventType>;
+
+/**
+ * Supported AI Assistant event names.
+ * @public
+ * @example
+ * const name: AIAssistantEventName = AIAssistantEventName.GET_TRANSCRIPTS;
+ * @ignore
+ */
+export const AIAssistantEventName = {
+  /** Request transcript streaming for an interaction */
+  GET_TRANSCRIPTS: 'GET_TRANSCRIPTS',
+  /** Request a suggested response for an interaction */
+  GET_SUGGESTIONS: 'GET_SUGGESTIONS',
+  /** Add extra context to refine a suggested response */
+  ADD_SUGGESTIONS_EXTRA_CONTEXT: 'ADD_SUGGESTIONS_EXTRA_CONTEXT',
+  /** Request mid-call summary generation */
+  GET_MID_CALL_SUMMARY: 'GET_MID_CALL_SUMMARY',
+  /** Request post-call summary generation */
+  GET_POST_CALL_SUMMARY: 'GET_POST_CALL_SUMMARY',
+  /** Mid-call summary response event */
+  MID_CALL_SUMMARY_RESPONSE: 'MID_CALL_SUMMARY_RESPONSE',
+  /** Post-call summary response event */
+  POST_CALL_SUMMARY_RESPONSE: 'POST_CALL_SUMMARY_RESPONSE',
+  /** Suggested digital response event */
+  SUGGESTED_RESPONSES_DIGITAL: 'SUGGESTED_RESPONSES_DIGITAL',
+  /** User action on a suggested response adaptive card */
+  SUGGESTED_RESPONSES_USER_ACTION: 'SUGGESTED_RESPONSES_USER_ACTION',
+} as const;
+
+/**
+ * Union type of AI Assistant event names.
+ * @public
+ * @example
+ * function handle(name: AIAssistantEventName) { ... }
+ * @ignore
+ */
+export type AIAssistantEventName = Enum<typeof AIAssistantEventName>;
+
+/**
+ * A single transcript message entry returned by AI Assistant APIs.
+ * @public
+ * @example
+ * const message: TranscriptMessage = { role: 'AGENT', content: 'Hello', messageId: '1', publishTimestamp: Date.now() };
+ *
+ */
+export type TranscriptMessage = {
+  /** Speaker role for this message */
+  role: string;
+  /** Transcript chunk content */
+  content: string;
+  /** Unique message identifier */
+  messageId: string;
+  /** Message publish timestamp (epoch milliseconds) */
+  publishTimestamp: number;
+};
+
+/**
+ * Response payload for historic transcripts API.
+ * @public
+ * @example
+ * const resp: HistoricTranscriptsResponse = { orgId: 'org', agentId: 'agent', conversationId: null, interactionId: 'int', source: 'AI', data: [] };
+ *
+ */
+export type HistoricTranscriptsResponse = {
+  /** Organization identifier */
+  orgId: string;
+  /** Agent identifier */
+  agentId: string;
+  /** Conversation identifier when available */
+  conversationId: string | null;
+  /** Interaction identifier */
+  interactionId: string;
+  /** Data source identifier */
+  source: string;
+  /** Transcript messages */
+  data: TranscriptMessage[];
+};

package/src/utils/AGENTS.md

@@ -0,0 +1,278 @@
+# Utils
+
+> **Legacy/reference-only.** Canonical SDD: [`ai-docs/utils-spec.md`](ai-docs/utils-spec.md). Use the package [manifest](../../.sdd/manifest.json) and [`SPEC_INDEX.md`](../../ai-docs/SPEC_INDEX.md) for routing; code and tests remain the behavioral referee.
+>
+> **Legacy scope:** This guide covers shared pagination/cache contracts used by data services. For repository rules and cross-service conventions, see the [root orchestrator AGENTS.md](../../AGENTS.md).
+
+---
+
+## Key Capabilities
+
+The utils scope currently provides shared pagination and cache behavior for contact-center data services:
+
+- **Typed Pagination Contracts**: Reusable interfaces for response metadata and query params
+- **Generic In-Memory Page Caching**: `PageCache<T>` utility for simple pagination reuse
+- **Cache Safety Rules**: Explicit bypass behavior for search/filter/sort scenarios
+- **Spec-Driven Utility Workflow**: Utility-specific implementation and validation flow documented inline in this file
+
+| Component             | File                             | Description                                                                                                                                     |
+| --------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PageCache`           | [`PageCache.ts`](./PageCache.ts) | Generic in-memory cache utility for paginated API responses with TTL expiry and helper methods for key generation and cache eligibility checks. |
+| `Pagination Types`    | [`PageCache.ts`](./PageCache.ts) | `PaginationMeta`, `PaginatedResponse<T>`, `BaseSearchParams`, and `PageCacheEntry<T>` shared across data services.                              |
+| `Pagination Defaults` | [`PageCache.ts`](./PageCache.ts) | `PAGINATION_DEFAULTS` (`PAGE`, `PAGE_SIZE`) used by services for consistent request defaults.                                                   |
+| `Specs Workflow`      | `AGENTS.md` (inline)             | Mermaid flow for specs-driven utility changes, acceptance criteria, and drift checks.                                                           |
+
+---
+
+## File Structure
+
+```
+src/utils/
+├── AGENTS.md          # This file: utils scope guide
+└── PageCache.ts       # Generic cache + pagination contracts/defaults
+```
+
+---
+
+## PageCache Utility
+
+`PageCache<T>` provides a consistent caching model for paginated list APIs. It is optimized for simple page browsing and intentionally bypasses cache for parameterized query cases (`search`, `filter`, `attributes`, `sortBy`).
+
+### Reference Usage
+
+```typescript
+import PageCache, {PAGINATION_DEFAULTS} from '../utils/PageCache';
+
+const cache = new PageCache<MyItem>('MyService');
+
+const page = PAGINATION_DEFAULTS.PAGE;
+const pageSize = PAGINATION_DEFAULTS.PAGE_SIZE;
+const cacheKey = cache.buildCacheKey(scopeId, page, pageSize);
+
+// Include sortBy only for services that support sorting.
+const canUseCache = cache.canUseCache({search, filter, attributes, sortBy});
+
+if (canUseCache) {
+  const cachedEntry = cache.getCachedPage(cacheKey);
+  if (cachedEntry) {
+    return {
+      data: cachedEntry.data,
+      meta: {
+        page,
+        pageSize,
+        ...cachedEntry.totalMeta,
+      },
+    };
+  }
+}
+
+const response = await fetchPageFromApi();
+
+if (canUseCache && response.data) {
+  cache.cachePage(cacheKey, response.data, response.meta);
+}
+
+return response;
+```
+
+### Cache Lifecycle
+
+```mermaid
+graph TD
+  A[Request arrives with scopeId/page/pageSize] --> B{canUseCache?}
+  B -->|No: search/filter/attributes/sortBy provided| C[Bypass cache and call API]
+  B -->|Yes| D[buildCacheKey scopeId:page:pageSize]
+  D --> E["getCachedPage(cacheKey)"]
+  E -->|Miss| C
+  E -->|Hit and not expired| F[Return cached data and totalMeta]
+  E -->|Hit but expired >= 5 minutes| G[Delete entry and treat as miss]
+  G --> C
+  C --> H[Receive API response]
+  H --> I["cachePage(cacheKey, data, meta)"]
+  I --> J[Return fresh response]
+```
+
+---
+
+## Public Contracts
+
+All public contracts for utils are defined in [`PageCache.ts`](./PageCache.ts).
+
+### `PaginationMeta`
+
+Common pagination metadata used across list APIs.
+
+| Field                         | Type                     | Notes                   |
+| ----------------------------- | ------------------------ | ----------------------- |
+| `orgid`                       | `string`                 | Organization identifier |
+| `page` / `currentPage`        | `number`                 | Current page aliases    |
+| `pageSize`                    | `number`                 | Items per page          |
+| `totalPages`                  | `number`                 | Total page count        |
+| `totalRecords` / `totalItems` | `number`                 | Total item aliases      |
+| `links`                       | `Record<string, string>` | Pagination link map     |
+
+### `PaginatedResponse<T>`
+
+Canonical paginated response type:
+
+```typescript
+interface PaginatedResponse<T> {
+  data: T[];
+  meta: PaginationMeta;
+}
+```
+
+### `PageCacheEntry<T>`
+
+Shape of a cached page entry returned by `getCachedPage()`:
+
+- `data: T[]`
+- `timestamp: number` (epoch milliseconds)
+- `totalMeta?: { totalPages?: number; totalRecords?: number }`
+
+### `CacheValidationParams`
+
+Contract passed to `canUseCache()`:
+
+- `search?: string`
+- `filter?: string`
+- `attributes?: string`
+- `sortBy?: string`
+
+Behavior note:
+
+- Cache bypass is triggered by `sortBy`, not by `sortOrder` alone.
+- If a new service treats `sortOrder` as meaningful without `sortBy`, extend `CacheValidationParams` and `canUseCache()` together.
+
+### `BaseSearchParams`
+
+Common query parameter contract with pagination and sorting:
+
+- `search`, `filter`, `attributes`
+- `page`, `pageSize`
+- `sortBy`, `sortOrder`
+
+### `PAGINATION_DEFAULTS`
+
+Standard defaults exported for callers:
+
+- `PAGE: 0`
+- `PAGE_SIZE: 100`
+
+---
+
+## PageCache API
+
+### `constructor(apiName: string)`
+
+Creates a typed cache instance and stores `apiName` for `LoggerProxy` context.
+
+### `canUseCache(params: CacheValidationParams): boolean`
+
+Returns `true` only when all of these are absent:
+
+- `search`
+- `filter`
+- `attributes`
+- `sortBy`
+
+`sortOrder` alone does not trigger cache bypass because `CacheValidationParams` currently keys bypass on fields that materially change the query result set in existing consumers.
+
+### `buildCacheKey(scopeId: string, page: number, pageSize: number): string`
+
+Builds deterministic cache key format:
+
+```text
+${scopeId}:${page}:${pageSize}
+```
+
+### `getCachedPage(cacheKey: string): PageCacheEntry<T> | null`
+
+Behavior:
+
+1. Returns `null` if key not found
+2. Computes cache age in minutes
+3. If age is `>= 5`, logs expiry, deletes entry, returns `null`
+4. Otherwise returns cached entry
+
+### `cachePage(cacheKey: string, data: T[], meta?: any): void`
+
+Stores entry with:
+
+- `data`
+- `timestamp`
+- `totalMeta.totalPages`
+- `totalMeta.totalRecords` mapped from `meta.totalRecords || meta.totalItems`
+
+### `clearCache(): void`
+
+Clears all entries and logs cleared entry count.
+
+### `getCacheSize(): number`
+
+Returns current in-memory entry count.
+
+Note: `clearCache()` and `getCacheSize()` are available for future use and are not currently called by existing consumers.
+
+---
+
+## Consumer Map
+
+Current consumers of `PageCache` and defaults:
+
+| Consumer                | File                                                       | Usage                                                        |
+| ----------------------- | ---------------------------------------------------------- | ------------------------------------------------------------ |
+| `AddressBook`           | [`../services/AddressBook.ts`](../services/AddressBook.ts) | Caches paged address-book responses                          |
+| `EntryPoint`            | [`../services/EntryPoint.ts`](../services/EntryPoint.ts)   | Caches paged entry-point responses                           |
+| `Queue`                 | [`../services/Queue.ts`](../services/Queue.ts)             | Caches paged queue responses                                 |
+| `Public type contracts` | [`../types.ts`](../types.ts)                               | Re-exports pagination/search contracts into SDK-facing types |
+
+Cross-scope mention:
+
+- Services-layer docs reference utils caching contracts at [`../services/ai-docs/AGENTS.md`](../services/ai-docs/AGENTS.md).
+
+---
+
+## Spec-Driven Utility Changes
+
+When changing `src/utils` behavior or contracts:
+
+1. Follow the workflow diagram below
+2. Define acceptance criteria for contract and runtime behavior
+3. Verify cache TTL, bypass rules, and key schema
+4. Validate no spec drift before shipping
+
+```mermaid
+flowchart TD
+  A[Change proposed in src/utils] --> B{Classify change scope}
+  B -->|Contract change| C[Document expected API/type behavior]
+  B -->|Runtime behavior change| D[Document cache behavior and TTL impact]
+  B -->|Both| C
+  C --> E[Update utils AGENTS.md contracts and consumer map]
+  D --> F[Validate cache key schema and bypass conditions]
+  E --> G[Run drift check against PageCache.ts and consumer services]
+  F --> G
+  G --> H{Behavior and docs aligned?}
+  H -->|No| I[Revise implementation/docs and re-validate]
+  I --> G
+  H -->|Yes| J[Prepare PR with acceptance criteria and evidence]
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Public types remain backward-compatible or migration is documented
+- [ ] `PAGINATION_DEFAULTS` changes are intentional and propagated to consumers
+- [ ] Cache TTL behavior remains explicit and covered by tests
+- [ ] `canUseCache()` bypass conditions are unchanged or intentionally updated
+- [ ] `totalRecords`/`totalItems` mapping behavior is preserved
+- [ ] Logging still uses `LoggerProxy` with `module` and `method`
+- [ ] AddressBook/EntryPoint/Queue integration behavior remains correct
+
+---
+
+## Related
+
+- [Root orchestrator AGENTS.md](../../AGENTS.md) - Task routing and critical package rules
+- [PageCache implementation](./PageCache.ts)