# AI Agent Instructions Package-scoped SDD entry for `@webex/calling`. This file orients agents; the monorepo root `AGENTS.md` governs workspace-wide setup (Node version, install, workspace scripts). `@webex/calling` is the TypeScript SDK package for Webex Calling clients, line registration, call control/media, settings, contacts, history, recordings, voicemail, metrics, and Mobius transport. **What it is:** - A published library package inside the `webex-js-sdk` workspace. - A typed adapter over Webex Calling backends, Webex SDK services, events, media, and WebSocket transport. **What it is NOT:** - It is not a UI application or a datastore owner. - It does not own the remote Webex services or their persisted records. ## Working Method - Read the relevant package files before editing. Do not edit blind. - Understand the task and affected surfaces before writing code. - Prefer focused edits over rewriting whole files. - Do not invent commands, paths, exports, event keys, metric names, or endpoints. Verify them from this package's source and tests. When in doubt, follow existing code patterns. - Code and tests are the behavioral source of truth. Module specs are `Partial` (cross-check them against code) and `src/SDKConnector/` is `Untracked` (code and tests are authoritative until its spec is validated); `.sdd/manifest.json` records each module's coverage state. - Load the affected module spec plus this file; do not load every module document. - Test or validate before declaring done. - Keep output concise. If something is uncertain, say so instead of guessing. Task routing for code changes: - Feature placement triage first: can this requirement be implemented cleanly inside an existing module without breaking module boundaries? Yes: enhance the existing module. No: create a new module. Do not start implementation until this triage is complete. - If it extends existing API methods, modifies existing behavior, or adds capabilities to an existing class, it is an enhancement. If it introduces a new domain concept, new backend endpoints unrelated to existing modules, or a new public interface, it is a new module. - Inside an existing module, decide whether this is a new method addition or an existing method modification. A new method must update interface type(s), implementation, tests, and API docs comments. For a modification, explicitly assess backward compatibility and impacted call sites. - A new top-level client module is comparable to `CallHistory`, `CallSettings`, `Contacts`, or `Voicemail`; a module tightly coupled to the CallingClient lifecycle is a sub-module under `src/CallingClient/`. A new top-level module must define its factory export, `types.ts`, `constants.ts` (if needed), implementation, and tests. - Confirm if feature is backend-specific (`WXC`/`UCM`/`Broadworks`). - For a bug, reproduce from tests or execution path first. Identify root cause before patching. Identify the entry point (e.g., `call.dial()`, `line.register()`), trace the code path through any delegation (e.g., `CallingClient` → `Line` → `Registration`), state machine transitions (`calling/call.ts`), and WebSocket event handling (`calling/callManager.ts`); check whether the error is caught, swallowed, or of the wrong type, and whether the right event is emitted with the right payload. Document the root cause and confirm it with the developer before fixing; the fix addresses the root cause (not just symptoms) and ships with a regression test for the specific bug scenario. - Bug severity: **Critical**: calls drop, registration fails, no audio. **Major**: feature doesn't work (hold, transfer, mute). **Minor**: cosmetic issue, wrong event data, missing log. - A read-only analysis or explanation task needs no pre-questions: read the module spec, source, and tests and explain. - If a developer request includes multiple task types, split into ordered subtasks and run each through the same confirm-then-implement sequence. Before coding a new module, new method, method change, or bug fix, ask and confirm: 1. Exact target module/file(s)? 2. Backend scope: `WXC`, `UCM`, `Broadworks`, or all? 3. Public API change? (yes/no; expected signature) 4. Events affected? (event keys and payload contracts) 5. Error behavior expected? (emit event, return value, throw) 6. Metrics expectations? (success/failure tracking) 7. Test scope expected? (unit only vs additional) 8. Backward compatibility constraints? For a method that calls Mobius, also confirm whether the state change comes back via the HTTP response or via a Mercury WebSocket event. For a bug, also collect expected and actual behavior, reproduction steps, environment (browser, calling backend, network), and logs (look for the `webex-calling:` prefix). Do not proceed until mandatory fields are explicit, and present a short summary of the planned change (files, API, events, errors, metrics, breaking change, test plan) for approval before writing code unless the developer explicitly skips it. During automated lifecycle runs, stop on the first unresolved critical fact, source conflict, failed conformance check, or same-runtime validation attempt. Retry transient infrastructure failures once only. ## Canonical Repository Documentation Before changing code or documentation, start with: - [`docs/index.md`](docs/index.md) for package documentation navigation; - [`docs/getting-started.md`](docs/getting-started.md) for setup and first run; - [`docs/architecture.md`](docs/architecture.md) for package boundaries, shared code (`src/common`, `src/Errors`, `src/Events`, `src/Logger`, `src/index.ts`, `src/api.ts`), security, and the contract index; - [`docs/specs/README.md`](docs/specs/README.md) for the manifest-backed module and contract registry; - the affected module's spec, routed by the table below; and - [`docs/adr/index.md`](docs/adr/index.md) plus applicable concrete ADRs for durable decisions. | Module | Scope Keywords | Source of Truth | | --------------- | ------------------------------------------------------------------------- | --------------- | | `CallingClient` | register, line, call lifecycle, hold/resume, transfer, media, keepalive | [CallingClient spec](src/CallingClient/docs/README.md) with sub-module specs [calling](src/CallingClient/calling/docs/README.md), [CallerId](src/CallingClient/calling/CallerId/docs/README.md), [line](src/CallingClient/line/docs/README.md), [registration](src/CallingClient/registration/docs/README.md) | | `CallHistory` | sessions, viewed/deleted records, Janus history events | [CallHistory spec](src/CallHistory/docs/README.md) + tests | | `CallRecording` | recordings list, metadata, delete, recording events | [CallRecording spec](src/CallRecording/docs/README.md) + tests | | `CallSettings` | forwarding, DND, voicemail settings, backend connectors | [CallSettings spec](src/CallSettings/docs/README.md) + connector tests | | `Contacts` | people lookup, SCIM, groups | [Contacts spec](src/Contacts/docs/README.md) + `src/Contacts/ContactsClient.test.ts` | | `Voicemail` | voicemail list/content/update/delete/summary/transcript | [Voicemail spec](src/Voicemail/docs/README.md) + backend connector tests | | `Errors` | `ExtendedError`, `CallError`, `LineError`, `CallingClientError` | `src/Errors/types.ts`, `src/Errors/index.ts` | | `Events` | event enums + typed callback maps | `src/Events/types.ts` | | `common` | shared helpers (`handle*Errors`, `serviceErrorCodeHandler`, `uploadLogs`) | `src/common/Utils.ts`, `src/common/types.ts`, `src/common/constants.ts` | | `Metrics` | metric manager + event taxonomy | [Metrics spec](src/Metrics/docs/README.md) | | `SDKConnector` | singleton webex bridge and listeners | [SDKConnector spec](src/SDKConnector/docs/README.md) | | `mobius-socket` | Mobius WebSocket transport (singleton client), reconnect, shutdown switchover, token refresh, message dispatch | [mobius-socket spec](src/mobius-socket/docs/README.md) | Follow `.sdd/manifest.json` for each contract's publication state and canonical source. This package publishes an SDK surface: its contract artifact is `package.json` (`main`, `module`, and `types` point at the build of `src/index.ts`). It serves no HTTP API; the Mobius, Janus, Hydra, User Hub, BroadWorks, UCM, and contacts endpoints it calls are external contracts listed in `docs/architecture.md`. There is no `docs/service.md`, because this is a library, not a deployable service. ## 1. Commands (Run First) Use only documented commands. Do not invent alternatives when a command is missing. Run every command from the workspace root; the package scripts run through `yarn workspace @webex/calling