@webex/contact-center 3.12.0-next.83 → 3.12.0-next.85

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

@@ -1,5 +1,7 @@
 # Task State Machine - AI Agent Guide
 
+> **Legacy/reference-only.** Canonical SDD: [`task-state-machine-spec.md`](task-state-machine-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.
+
 ## Purpose
 
 Guide AI agents working on task lifecycle transitions, guard logic, executable actions and UI control computation in the XState-based task state machine.
@@ -25,6 +27,8 @@ Use this doc when implementing:
 
 ---
 
+
+
 ## File Structure
 
 ```text
@@ -43,6 +47,8 @@ state-machine/
 
 ---
 
+
+
 ## Source of Truth
 
 - Task lifecycle state machine: `TaskStateMachine.ts`
@@ -53,6 +59,8 @@ state-machine/
 
 ---
 
+
+
 ## Key Capabilities
 
 - **State Graph and Transition Rules**: `TaskStateMachine.ts` defines all states, transition tables, and event handlers that drive the task lifecycle.
@@ -64,6 +72,8 @@ state-machine/
 
 ---
 
+
+
 ## State Machine Overview
 
 **Transition Source**: `getTaskStateMachineConfig()` in `TaskStateMachine.ts`
@@ -91,6 +101,8 @@ if (eventPayload) {
 
 ---
 
+
+
 ### Transition Contract
 
 Backend CC events from WebSocket are mapped to `TaskEvent` in `TaskManager.mapEventToTaskStateMachineEvent`.
@@ -103,11 +115,15 @@ All new events must add a typed payload entry in `TaskEventPayloadMap`.
 
 ---
 
+
+
 ## Non-goals
 
 - API contracts for external services.
 - Mercury or CC WebSocket protocols (see `TaskManager.ts` mapping).
 
+
+
 ## Guards
 
 Guards are boolean conditions that determine determine if a state transition is allowed. These functions validate the current context before allowing transitions.
@@ -118,6 +134,8 @@ Guards are boolean conditions that determine determine if a state transition is
 - No mutation or side-effects.
 - Reuse helper accessors (e.g., `getTaskDataFromEvent`).
 
+
+
 ### State-Based Guards
 
 ```typescript
@@ -142,6 +160,8 @@ isInteractionConnected(context, event) {
 }
 ```
 
+
+
 ### Consult Guards
 
 ```typescript
@@ -154,6 +174,8 @@ didInitiateConsult(context, event) {
 }
 ```
 
+
+
 ### Conference Guards
 
 ```typescript
@@ -212,6 +234,8 @@ shouldDowngradeConferenceToConnected(context, event) {
 }
 ```
 
+
+
 ### Wrapup Guards
 
 ```typescript
@@ -253,6 +277,8 @@ didCurrentAgentLeaveConference(context, event) {
 }
 ```
 
+
+
 ### Server State Guards
 
 ```typescript
@@ -267,6 +293,8 @@ isPrimaryMediaOnHold(context, event) {
 
 ---
 
+
+
 ## Actions
 
 Actions are side effects executed during state machine transitions from current state to target state(next state).
@@ -276,12 +304,16 @@ Actions contain:
 - Lifecycle mutations (`clearConsultState`, `markEnded`, consult/conference flags)
 - Integration hooks (`requestAutoAnswer`, `requestCleanup`, emitter placeholders)
 
+
+
 ### Principles
 
 - Context mutations should be centralized in `assign(...)` actions
 - Emitter actions intentionally no-op defaults and overridden by `Task` to bridge machine transitions to SDK events.
 - Deterministic updates from `taskData`.
 
+
+
 ### Context Update Actions
 
 ```typescript
@@ -359,6 +391,8 @@ markEnded() {
 > Note: `forceConsultInitiator`, `handleConferenceFailed`, `handleSwitchToMainCall`, and
 > `handleSwitchToConsult` are not present in current `actions.ts`/`TaskStateMachine.ts`.
 
+
+
 ### Event Emission Actions
 
 ```typescript
@@ -387,6 +421,8 @@ emitTaskWrapup(context, event) {
 // ... more emission actions for each event type
 ```
 
+
+
 ### Cleanup Actions
 
 ```typescript
@@ -403,6 +439,8 @@ cleanupResources(context, event) {
 }
 ```
 
+
+
 ### Auto-Answer Actions
 
 ```typescript
@@ -418,78 +456,3 @@ requestAutoAnswer(context, event) {
 ```
 
 ---
-
-## UI Controls
-
-`uiControlsComputer.ts` computes `TaskUIControls` from:
-
-- current machine state
-- current context
-- channel type (voice vs digital)
-- call/participant metadata from `taskData`
-- config flags (`isEndTaskEnabled`, recording toggles, voice variant)
-
-This keeps all control enablement/visibility logic centralized and testable.
-
-### Source of truth
-
-`computeUIControls()` in `uiControlsComputer.ts`.
-
-### Inputs
-
-- `TaskState`
-- `TaskContext` (including `taskData`)
-- `UIControlConfig` (channel type, agentId, voice variant, recording flags)
-
-### Output
-
-- `TaskUIControls` with per-control visibility and enabled state.
-
----
-
-## Common Workflows
-
-### Add New Event
-
-1. Add event in `TaskEvent` (`constants.ts`)
-2. Add typed payload in `TaskEventPayloadMap` (`types.ts`)
-3. Wire transitions in `TaskStateMachine.ts`
-4. Add/adjust actions in `actions.ts`
-5. Add guard(s) in `guards.ts` if needed
-6. Update `TaskManager` event mapping and unit tests
-
-### Add New Transition Rule
-
-1. Implement pure guard in `guards.ts`
-2. Use guard in `TaskStateMachine.ts` transition array
-3. Keep side-effects in actions only (no side-effects in guards)
-4. Add tests for positive and negative transition paths
-
-### Update UI Controls
-
-1. Update control logic in `computeVoiceUIControls()` or `computeDigitalUIControls()`
-2. Preserve `getDefaultUIControls()` shape compatibility
-3. Verify behavior across `CONNECTED`, `HELD`, `CONSULTING`, `CONFERENCING`, `WRAPPING_UP`
-4. Add or update UI-control unit coverage
-
----
-
-## Testing Checklist
-
-- [ ] Added event is defined in `TaskEvent`
-- [ ] Added payload is typed in `TaskEventPayloadMap`
-- [ ] Add transition(s) in `TaskStateMachine.ts` and validate it for success and failure
-- [ ] Update mapping in `TaskManager.mapEventToTaskStateMachineEvent`
-- [ ] Add/update guards and actions
-- [ ] Update UI controls if state impacts UX and validate them for voice and digital where applicable
-- [ ] Reconnect/hydrate behavior validated
-- [ ] Add/adjust unit tests.
-- [ ] Update diagrams + mapping tables in `ARCHITECTURE.md`.
-
----
-
-## Related Docs
-
-- [ARCHITECTURE.md](ARCHITECTURE.md) - State machine internals and flow diagrams
-- [../../ai-docs/AGENTS.md](../../ai-docs/AGENTS.md) - Task service usage guide
-- [../../ai-docs/ARCHITECTURE.md](../../ai-docs/ARCHITECTURE.md) - Task service architecture

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

@@ -1,5 +1,7 @@
 # Task State Machine - Architecture
 
+> **Legacy/reference-only.** Canonical SDD: [`task-state-machine-spec.md`](task-state-machine-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.
+
 ## Purpose
 
 Technical reference for the complete state machine using XState to drive state transitions and UI control behavior. It orchestrates state transitions, guards, and actions for task lifecycle management.
@@ -1129,7 +1131,7 @@ The HYDRATE event restores state machine state after page refresh or reconnectio
 - `../TaskManager.ts` - maps backend events to state-machine events
 - `../types.ts` - shared task data structures
 - `../../ai-docs/ARCHITECTURE.md` - broader task service architecture
-- [TaskStateMachine.ts](../state-machine/TaskStateMachine.ts) - Implementation
-- [guards.ts](../state-machine/guards.ts) - Guard functions
-- [actions.ts](../state-machine/actions.ts) - Action functions
-- [constants.ts](../state-machine/constants.ts) - State and event enums
+- [TaskStateMachine.ts](../TaskStateMachine.ts) - Implementation
+- [guards.ts](../guards.ts) - Guard functions
+- [actions.ts](../actions.ts) - Action functions
+- [constants.ts](../constants.ts) - State and event enums