docs(service): add root service docs

[Shreyas281299]

COMPLETES #< INSERT LINK TO ISSUE >

This pull request addresses

< DESCRIBE THE CONTEXT OF THE ISSUE >

by making the following changes

< DESCRIBE YOUR CHANGES >

Change Type

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Tooling change
• Internal code refactor

The following scenarios were tested

< ENUMERATE TESTS PERFORMED, WHETHER MANUAL OR AUTOMATED >

The GAI Coding Policy And Copyright Annotation Best Practices

• GAI was not used (or, no additional notation is required)
• Code was generated entirely by GAI
• GAI was used to create a draft that was subsequently customized or modified
• Coder created a draft manually that was non-substantively modified by GAI (e.g., refactoring was performed by GAI on manually written code)
• Tool used for AI assistance (GitHub Copilot / Other - specify)
  • Github Copilot
  • Other - Please Specify
• This PR is related to
  • Feature
  • Defect fix
  • Tech Debt
  • Automation

I certified that

• I have read and followed contributing guidelines
• I discussed changes with code owners prior to submitting this pull request
• I have not skipped any automated checks
• All existing and new tests passed
• I have updated the documentation accordingly

---

Make sure to have followed the contributing guidelines before submitting.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b30e86b543

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Replace service-doc routes that currently resolve to nothing

This routing table sends readers to agent/task/config/core ai-docs files that are not present under src/services/, while this document also says those docs should always be loaded before making changes. In practice that creates dead-end navigation for the documented workflow and makes the new “authoritative” guide non-actionable unless those targets are added or the links are changed to existing sources.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Use the actual Services.getInstance option key

The example call uses Services.getInstance({webex, config}), but Services is wired around connectionConfig (as seen in src/services/index.ts and the real call site in src/cc.ts). Copying this snippet passes no subscription config into ConnectionService, so the guide currently demonstrates an invocation shape that does not match runtime expectations.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Correct the documented bootstrap sequencing

The “critical” order here says data services are created after register(), TaskManager after stationLogin(), and WebCallingService only for BROWSER login, but ContactCenter instantiates all three in the READY handler before either API call (src/cc.ts constructor). This contradiction makes the architecture guidance unreliable for troubleshooting initialization issues or extending startup logic.

Useful? React with 👍 / 👎.

[Shreyas281299]

Review: docs(service): add root service docs

Overall

The documentation is well-structured and comprehensive -- the file structure tree, key capabilities table, architecture diagrams, bootstrap order, and request/response flow patterns are all clear and useful. This will be a strong reference for AI agents and developers working in the services layer.

Issues to Address

1. PR Template Not Filled Out (Compliance)

The PR description still has the default template placeholders, and none of the checkboxes are ticked. The template itself states:

FAILING TO FILL OUT THIS TEMPLATE WILL RESULT IN REJECTION OF YOUR PULL REQUEST. This is for compliance purposes with FedRAMP program.

Please fill out the PR description -- at minimum the "addresses", "changes", "Change Type" (Documentation update), GAI policy, and "I certified" sections.

2. Verify Relative Links to Package Root

Several links in the "Related" section point three levels up to the package root. Please verify these paths exist on the task-refactor branch:

• ../../../AGENTS.md resolves to packages/@webex/contact-center/AGENTS.md
• ../../../ai-docs/RULES.md resolves to packages/@webex/contact-center/ai-docs/RULES.md
• ../../../ai-docs/patterns/ resolves to packages/@webex/contact-center/ai-docs/patterns/
• ../../../ai-docs/patterns/typescript-patterns.md

If these do not exist yet (or are planned for a future PR), consider noting them as "TODO" or removing the dead links.

3. Sub-Service ai-docs Existence

The Service Routing table links to ai-docs under agent/, task/, config/, core/, and task/state-machine/. Are these already merged or in-flight? If they do not exist yet, readers/agents following these links will hit dead ends. Consider adding a note like: "These docs are being added incrementally -- check the folder for availability."

Suggestions (Non-blocking)

4. Consider Adding an ARCHITECTURE.md Companion

Other service folders (agent, task, config, core) have both AGENTS.md and ARCHITECTURE.md. For consistency, consider whether a companion ARCHITECTURE.md would be useful here -- even if it is lighter-weight, covering just the Services singleton internals and construction details.

5. PageCache Note Placement

The note about src/utils/PageCache.ts at the bottom of the File Structure section feels slightly out of place. Consider moving it to the Data Services Pattern section where PageCache is directly referenced and more contextually relevant.

Summary

Good documentation overall. Main action items: (1) fill out the PR template for compliance, (2) verify the relative links, (3) clarify sub-service docs availability.

[ciscoRankush]

Review: Service Root-level AGENTS.md

Good overall structure — the service routing table, architecture diagram, and AqmReqs factory pattern documentation are valuable for AI agent navigation. A few accuracy issues need fixing before merge, mostly around bootstrap order and event flow.

3 Important | 2 Medium | 2 Minor

[ciscoRankush]

[Important] Services.getInstance({webex, config}) — the second parameter is connectionConfig, not config.

Actual signature in services/index.ts:39:

constructor(options: {webex: WebexSDK; connectionConfig: SubscribeRequest})

Suggest:

├── Services.getInstance({webex, connectionConfig}) ← initialized SECOND (singleton)

[ciscoRankush]

[Important] Bootstrap order is inaccurate. In cc.ts:register() (lines 350-376), all of these are created during register():

1. WebexRequest
2. Services
3. WebCallingService (always instantiated; only registerWebCallingLine() is conditional on BROWSER)
4. MetricsManager
5. TaskManager
6. Data services (AddressBook, EntryPoint, Queue)

• Line 170: TaskManager is not created "after login" — it's created in register().
• Line 171: WebCallingService is not "created on BROWSER login" — it's always created; only line registration is conditional.
• Lines 185-187: Same errors in the numbered list.

Same errors repeat in "What Services does NOT create" section (lines 250-251): "TaskManager — created after successful station login" and "WebCallingService — created only for BROWSER login" are both inaccurate.

[ciscoRankush]

[Important] This event flow implies cc.ts is a central router that forwards events to TaskManager and ConnectionService. In reality, there are 4 independent listeners on webSocketManager.on('message'):

1. AqmReqs — aqm-reqs.ts:20 (registered in AqmReqs constructor)
2. cc.ts — cc.ts:358 (registered in register())
3. TaskManager — TaskManager.ts:314 (registered in registerTaskListeners())
4. ConnectionService — connection-service.ts:44-45 (registered in constructor)

cc.ts does not route or forward events to TaskManager or ConnectionService — each listener independently processes the same WebSocket messages.

---

[Medium] Also, line 359 says "Agent events → emitted on cc EventEmitter" but cc.ts uses two different emission mechanisms: this.emit() (EventEmitter) for agent events and this.trigger() (WebexPlugin) for task events (cc.ts:1075-1177). This distinction matters for consumers subscribing to events.

[ciscoRankush]

[Medium] constants.ts only gets a one-liner here. This file contains important shared constants that AI agents need when adding new endpoints or services:

• WCC_API_GATEWAY — service identifier used in all HTTP requests
• SUBSCRIBE_API, LOGIN_API, STATE_CHANGE_API — API path constants
• WEB_RTC_PREFIX — prefix for WebRTC endpoints
• WEBSOCKET_EVENT_TIMEOUT — 20000ms timeout
• DEFAULT_RTMS_DOMAIN, WCC_CALLING_RTMS_DOMAIN — WebRTC domain constants
• METHODS object — WebCallingService method name constants

Consider adding a brief "Shared Constants" section or expanding this annotation so AI agents discover these naming conventions.

[ciscoRankush]

[Medium] WebCallingService does not follow "the same patterns documented in typescript-patterns.md" as data services. Data services use REST + pagination + PageCache caching. WebCallingService extends EventEmitter, wraps @webex/calling (createClient/ICallingClient/ILine/ICall), manages call lifecycle with a callTaskMap, and has an async registration flow with timeout — a completely different pattern. Consider noting this distinction rather than grouping it with data services.

[ciscoRankush]

[Minor] File tree omits state-machine/index.ts — this file exists and serves as the barrel export for all state machine public API (createTaskStateMachine, TaskState, TaskEvent, guards, actions, createInitialContext, types). Should be listed here alongside the other state machine files.

[ciscoRankush]

[Minor] Error handling pattern says "try/catch with LoggerProxy.error + metricsManager.trackEvent" but omits that data services re-throw the error after logging (e.g., AddressBook.ts catch block logs then throws). The re-throw is important — it means errors propagate to callers rather than being silently swallowed.