@xema/omni-protocol 0.1.118 → 0.1.120

package/CALL_FLOW.md

@@ -0,0 +1,101 @@
+# Call flow
+
+How one agent's part of a phone call moves, from the offer to the moment it leaves the agent's
+screen. Terms are in `GLOSSARY.md`; the rules are in `guide.md`, `guide/agent.md`,
+`guide/voice.md` and `guide/phone.md`.
+
+## Where a call task stands
+
+```mermaid
+stateDiagram-v2
+  [*] --> pending: task-offered
+  [*] --> in_progress: already underway on connect (snapshot)
+  pending --> confirmed: answered, waiting to connect
+  pending --> in_progress: answered and connected at once
+  pending --> [*]: declined, withdrawn, caller hung up (cancelled) or offer ran out (expired)
+  confirmed --> preview: outbound record shown first
+  confirmed --> in_progress: work begins
+  preview --> in_progress: agent presses Call, customer answers
+  preview --> completing: the call goes out and nobody answers
+  in_progress --> paused: hold
+  paused --> in_progress: resume
+  in_progress --> completing: end call, or the caller hangs up
+  completing --> in_progress: connect back
+  completing --> [*]: complete (task-ended)
+  in_progress --> [*]: completed straight from the call (task-ended)
+
+  state "in-progress" as in_progress
+```
+
+| Phase | What the agent sees | Default label |
+| --- | --- | --- |
+| `pending` | The phone rings, with Answer and maybe Decline. | Offered |
+| `confirmed` | Answered, waiting for the call to connect. Many platforms skip it. | Accepted |
+| `preview` | An outbound customer's record, with a Call button and maybe a countdown. | Preview |
+| `in-progress` | On the call. | On Call |
+| `paused` | The caller is on hold. | On Hold |
+| `completing` | The caller is gone; the agent finishes notes and picks an outcome. | After Call Work |
+
+## An inbound call on the wire
+
+```mermaid
+sequenceDiagram
+  participant P as Provider (adapter)
+  participant A as Agent application
+  actor G as Agent
+  P->>A: task-offered (pending)
+  A->>G: rings, shows Answer
+  G->>A: Answer
+  A->>P: execute answer
+  P->>A: task-updated (in-progress)
+  P->>A: task-audio-started
+  A->>P: openAudio (softphone only)
+  G->>A: Hold
+  A->>P: execute hold
+  P->>A: task-updated (paused)
+  Note over A,G: Mute and End call are unavailable on hold
+  G->>A: Resume
+  A->>P: execute resume
+  P->>A: task-updated (in-progress)
+  G->>A: End call
+  A->>P: execute end-call
+  P->>A: task-audio-ended
+  P->>A: task-updated (completing, wrap time left)
+  G->>A: Complete with outcome
+  A->>P: execute complete
+  P->>A: task-ended (completed)
+```
+
+## An outbound preview call
+
+```mermaid
+sequenceDiagram
+  participant P as Provider (adapter)
+  participant A as Agent application
+  actor G as Agent
+  P->>A: task-offered, then task-updated (preview, maybe a countdown)
+  G->>A: reads the record, presses Call
+  A->>P: execute dial (with a new dialId)
+  P-->>A: dialling
+  P->>A: task-audio-started (ring-back)
+  P->>A: dial-outcome (answered, busy, no-answer, ...)
+  alt answered
+    P->>A: task-updated (in-progress)
+  else nobody answered
+    P->>A: task-audio-ended
+    P->>A: task-updated (completing)
+  end
+```
+
+When the countdown runs out, `atDeadline` says who acts: the provider dials (`provider-dials`),
+the agent application dials (`host-dials`), or nobody does and the record waits (`waits`).
+
+## Rules worth knowing
+
+- **Every offer is owed an ending.** Whatever happens to the call, the provider sends `task-ended`.
+- **Every dial has exactly one outcome.** A dial answered `dialling` always gets its `dial-outcome`.
+- **Audio follows the task, never the other way round.** A dropped stream changes nothing until the provider says so.
+- **No End call from hold.** Resume first; `terminate-call` may end everything, held caller included.
+- **No Mute from hold on a softphone.** A mute already on when the hold began stays on.
+- **No transfer.** Help comes from a lead: listen, coach, join the call, or take it over.
+- **A callback carries the call it comes back to.** Its task's history starts with the earlier call's steps.

package/CHAT_FLOW.md

@@ -0,0 +1,61 @@
+# Chat flow
+
+How one agent's part of a chat moves, from the offer to the moment it leaves the agent's screen. A
+chat has no call: no audio, no phone, no preview. Terms are in `GLOSSARY.md`; the rules are in
+`guide.md`, `guide/agent.md` and `guide/chat.md`.
+
+## Where a chat task stands
+
+```mermaid
+stateDiagram-v2
+  [*] --> pending: task-offered
+  [*] --> in_progress: already underway on connect (snapshot)
+  pending --> confirmed: accepted
+  pending --> [*]: declined, withdrawn, customer left (cancelled) or offer ran out (expired)
+  confirmed --> in_progress: chat begins
+  in_progress --> paused: pause
+  paused --> in_progress: resume
+  in_progress --> completing: the conversation ends and follow-up work remains
+  paused --> completing: the conversation ends while paused
+  in_progress --> [*]: complete (task-ended)
+  completing --> [*]: complete (task-ended)
+
+  state "in-progress" as in_progress
+```
+
+| Phase | What the agent sees | Default label |
+| --- | --- | --- |
+| `pending` | A new chat flashes, with Accept and maybe Decline. | Incoming Chat |
+| `confirmed` | Accepted, waiting for the chat to open. | Accepted |
+| `in-progress` | Chatting with the customer. | In Chat |
+| `paused` | The chat is paused; the customer waits. | Paused |
+| `completing` | The customer is gone; the agent finishes notes. | Wrap-up |
+
+## A chat on the wire
+
+```mermaid
+sequenceDiagram
+  participant P as Provider (adapter)
+  participant A as Agent application
+  actor G as Agent
+  P->>A: task-offered (pending)
+  G->>A: Accept
+  A->>P: execute accept
+  P->>A: task-updated (in-progress)
+  G->>A: Pause
+  A->>P: execute pause
+  P->>A: task-updated (paused)
+  G->>A: Resume
+  A->>P: execute resume
+  P->>A: task-updated (in-progress)
+  G->>A: Complete with outcome
+  A->>P: execute complete
+  P->>A: task-ended (completed)
+```
+
+## Rules worth knowing
+
+- **One agent can hold several chats at once.** How many is the agent's capacity on this provider.
+- **A chat is completed from where it stands.** There is no call to end, so the agent completes from `in-progress`, or from `completing` where the provider moved it there.
+- **Pause is the chat's hold.** The `hold` capability offers it; the command is `pause`, then `resume`.
+- **Every offer is owed an ending.** Whatever happens to the chat, the provider sends `task-ended`.

package/EMAIL_FLOW.md

@@ -0,0 +1,54 @@
+# Email flow
+
+How one agent's part of an email moves, from the assignment to the moment it leaves the agent's
+screen. An email has no call and no pause: it is worked and completed. Terms are in
+`GLOSSARY.md`; the rules are in `guide.md`, `guide/agent.md` and `guide/email.md`.
+
+## Where an email task stands
+
+```mermaid
+stateDiagram-v2
+  [*] --> pending: task-offered
+  [*] --> in_progress: already underway on connect (snapshot)
+  pending --> confirmed: accepted
+  pending --> [*]: declined, withdrawn (cancelled) or offer ran out (expired)
+  confirmed --> in_progress: work begins
+  in_progress --> completing: the reply is sent and follow-up work remains
+  in_progress --> [*]: complete (task-ended)
+  completing --> [*]: complete (task-ended)
+
+  state "in-progress" as in_progress
+```
+
+| Phase | What the agent sees | Default label |
+| --- | --- | --- |
+| `pending` | A new email is assigned, with Accept and maybe Decline. | Assigned |
+| `confirmed` | Accepted, waiting to open. | Accepted |
+| `in-progress` | Reading and replying. | Working |
+| `completing` | The reply is done; the agent finishes notes. | Completing |
+
+## An email on the wire
+
+```mermaid
+sequenceDiagram
+  participant P as Provider (adapter)
+  participant A as Agent application
+  actor G as Agent
+  P->>A: task-offered (pending)
+  G->>A: Accept
+  A->>P: execute accept
+  P->>A: task-updated (in-progress)
+  G->>A: may Schedule a follow-up
+  A->>P: execute schedule
+  P->>A: calendar-updated
+  G->>A: Complete with outcome
+  A->>P: execute complete
+  P->>A: task-ended (completed)
+```
+
+## Rules worth knowing
+
+- **No hold, no pause.** An email waits on its own; there is no `hold` capability on email.
+- **An email is completed from where it stands.** The agent completes from `in-progress`, or from `completing` where the provider moved it there.
+- **A follow-up goes on the calendar.** `schedule` puts it there, from the email or from its wrap, where the provider declares a calendar.
+- **Every offer is owed an ending.** Whatever happens to the email, the provider sends `task-ended`.

package/GLOSSARY.md

@@ -0,0 +1,116 @@
+# Glossary
+
+The words this protocol uses, in everyday language, with what the larger contact-centre platforms
+call the same thing. The protocol picks one word per idea and keeps it. Where the industry uses
+several names for one idea, this list shows them so a reader from any platform can find their way.
+The exact rules live in `guide.md` and the files under `guide/`.
+
+The platform names in the last column are given as each platform commonly presents them. They are
+for orientation only: each platform's own documentation is the authority on its terms.
+
+## The pieces
+
+| Term | In plain words | What others call it |
+| --- | --- | --- |
+| **Agent** | The person handling the work: answering calls, chats and emails. | Agent everywhere; *user* in Genesys Cloud's admin screens; *representative* or *advisor* in some service desks. |
+| **Lead** | An agent who also looks after a team: sees their members, listens in, coaches, helps and takes calls over. | *Supervisor* in Amazon Connect, Genesys Cloud, NICE CXone and Twilio Flex; *team lead* on most floors. |
+| **Provider** | One outside system that brings work to the agent: a phone platform, a chat platform, a mail platform. | *Channel provider*, *ACD*, *CCaaS platform*; Salesforce calls a connected phone system a *telephony provider*. |
+| **Adapter** | The software that connects one provider to this protocol. | *Connector*, *integration*, *CTI adapter* (Salesforce Open CTI, Zendesk Talk Partner Edition). |
+| **Agent application** | The software the agent works in, here called Omni. | *Agent desktop* (Amazon Connect CCP, Genesys Cloud agent UI, NICE CXone MAX), *agent workspace* (Salesforce, Zendesk). |
+| **Agent computer** | The agent's screen and machine, where the agent application runs. | *Desktop*, *workstation*, *station*. |
+| **Manifest** | What a provider declares about itself up front: its name, channel, phones and features. | *Integration definition*, *app manifest* (Twilio Flex plugins, Salesforce call center definition file). |
+| **Channel** | The kind of work: voice, chat or email. | *Media type* (Genesys Cloud), *channel* (Amazon Connect, Salesforce Omni-Channel), *media* (NICE). |
+| **Login** | One signed-in session of one agent on one provider. | *Session*, *agent session*. |
+
+## The work
+
+| Term | In plain words | What others call it |
+| --- | --- | --- |
+| **Call** | The customer's whole phone call, which may pass through menus, queues and several agents. | *Contact* (Amazon Connect), *conversation* (Genesys Cloud), *interaction* (NICE, Five9). |
+| **Task** | One agent's piece of one contact, on any channel: offered to them, worked, wrapped up. A call that reaches three agents is three tasks. | *Task* (Twilio TaskRouter), *work item* or *AgentWork* (Salesforce Omni-Channel), *contact* as the agent sees it (Amazon Connect), *participant* in a conversation (Genesys Cloud). |
+| **Assignment** | The routing of a call to this agent, from the offer until the task ends. Its id names the task. | *Reservation* (Twilio TaskRouter), *offer* or *routed work* (Salesforce), *alerting* (Genesys Cloud). |
+| **Interaction** | The agent's time actually on the call: from answering until their audio ends, holds included. | *Talk time* plus *hold time*, together *handle time* without the wrap; Genesys Cloud reports it as *interact*. |
+| **Party** | The customer on the other end. | *Customer*, *caller*, *external participant*; the number is the *ANI* or *caller ID*. |
+| **Task type** | The provider's name for a kind of work, such as a queue or a mailbox. | *Queue*, *skill*, *routing profile*, *campaign*. |
+| **Queue** | Where calls wait for an agent. | *Queue* everywhere; *hunt group* or *split* on older systems. |
+
+## Where a task stands
+
+| Term | In plain words | What others call it |
+| --- | --- | --- |
+| **Pending** | Offered and not yet accepted: the phone is ringing or the chat is flashing. | *Ringing*, *alerting* (Genesys Cloud), *incoming* (Amazon Connect), *reserved* (Twilio). |
+| **Confirmed** | Accepted, waiting for the work to start. | *Accepted*, *connecting*. |
+| **Preview** | An outbound record shown to the agent before the call goes out. | *Preview dialing* (Five9, Genesys Cloud, Amazon Connect outbound campaigns). |
+| **In progress** | The agent is working it: on the call, in the chat, writing the email. | *Connected*, *on call*, *active*, *talking*. |
+| **Paused** | The work is on hold: the caller hears hold music, or the chat waits. | *Hold* on a call; *paused* or *parked* on a chat. |
+| **Completing** | The customer has gone and the agent is finishing their notes. | *After-call work* or *ACW* (Amazon Connect, Genesys Cloud, NICE), *wrap-up* (Twilio, Five9), *after conversation work* (Salesforce). |
+| **Wrap allowance** | How long the agent has for that finishing work. | *ACW timeout*, *wrap-up time limit*. |
+| **Outcome** | What the agent records about how the task went. | *Wrap-up code* (Genesys Cloud), *disposition* (Five9, NICE, Twilio), *contact disposition*. |
+| **Task ended** | The task is gone from the agent's screen. | *Contact ended*, *disconnected*, *completed*. |
+
+## Controls on a call
+
+| Term | In plain words | What others call it |
+| --- | --- | --- |
+| **Answer** / **Accept** | Take an offered task: a call is answered, a chat or an email accepted. | *Accept*, *answer*, *pick up*. |
+| **Decline** | Turn an offered task down. | *Reject*, *decline*. |
+| **Hold** / **Resume** | Put the caller on hold, and take them off it. | The same everywhere. |
+| **Mute** | Silence the agent's microphone. The caller hears nothing from the agent. | The same everywhere. |
+| **End call** | End the agent's part. The caller carries on to wherever the provider sends them, such as a survey. | *Leave*, *drop*, *hang up* (agent leg only). |
+| **Terminate call** | End the whole call for everyone. | *Disconnect all*, *end conversation*. |
+| **Conference** | Bring a colleague into the call. | *Conference*, *add participant*, *three-way call*. |
+| **Connect back** | Call the customer again after the call has ended, during the wrap. | *Callback from wrap*, *re-dial*. |
+| **Schedule** | Put a follow-up with this customer on the calendar. | *Scheduled callback* (Amazon Connect, Genesys Cloud), *personal callback* (Five9). |
+| **Callback requested** | The customer asked to be called back, or an agent arranged it. | *Queued callback* (Amazon Connect), *callback* (Genesys Cloud), *virtual hold*. |
+
+There is deliberately no **transfer**. An agent who needs help asks a lead, and a call changes
+hands only through routing or a lead's take-over.
+
+## Leads and teams
+
+| Term | In plain words | What others call it |
+| --- | --- | --- |
+| **Lead assist** | The agent asks a lead for help on the call. | *Request supervisor*, *raise hand*, *help request*. |
+| **Listen** | The lead hears the call silently. | *Monitor* or *silent monitor* (Amazon Connect, Genesys Cloud, NICE). |
+| **Coach** | The lead talks to the agent only; the customer cannot hear. | *Whisper* or *coach* (Genesys Cloud, Twilio Flex). |
+| **Join call** | The lead speaks to both the agent and the customer. | *Barge* or *barge-in* (Amazon Connect, Genesys Cloud). |
+| **Take over** | The lead takes the call from the agent. | *Take over*, *intercept*. |
+| **Team** | The agents a lead looks after, each with their status and tasks. | *Team*, *group*, *agent list* in a supervisor view. |
+
+## Availability
+
+| Term | In plain words | What others call it |
+| --- | --- | --- |
+| **Capacity** | How many tasks the agent can take at once on this provider. Zero means none. | *Concurrency* (Amazon Connect routing profiles), *capacity* (Twilio, Salesforce), *utilization* (Genesys Cloud). |
+| **Break** | Time away: lunch, training, a personal break. The agent asks, the provider decides. | *Aux* or *auxiliary code* (Avaya and many floors), *presence* such as Break or Meal (Genesys Cloud), *agent status* (Amazon Connect), *unavailable code* (NICE). |
+| **Forced break** | A break a lead or the provider puts the agent on. | *Forced aux*, *supervisor-set status*. |
+| **Next call** | The agent says they are ready for another call before this one ends. | *Request next*, *ready for next*. |
+| **Lined up** | A call waiting in this agent's own queue, held for them. | *Agent queue* or *personal queue* (Amazon Connect), *direct routing*. |
+| **Shift** | The agent's day: when they signed in, their breaks, their totals. | *Schedule adherence* data, *agent state history*. |
+
+## The phone
+
+| Term | In plain words | What others call it |
+| --- | --- | --- |
+| **Softphone** | A phone inside the agent application, using the computer's headset. | *Softphone* (Amazon Connect), *WebRTC phone* (Genesys Cloud). |
+| **Hardphone** | A separate physical phone that the provider rings. | *Desk phone* (Amazon Connect), *SIP phone* or *physical phone* (Genesys Cloud). |
+| **Station** | The agent's audio equipment: headset, speaker, microphone. | *Station*, *endpoint*. |
+
+## Records and recording
+
+| Term | In plain words | What others call it |
+| --- | --- | --- |
+| **History** | The steps a call went through before and with this agent: queued, answered, held, handed over. | *Contact trace record* (Amazon Connect), *conversation details* or *segments* (Genesys Cloud), *call detail record*. |
+| **Recording** | A recording of one side of the call, the customer's or the agent's. | *Call recording*, *screen and voice recording*. |
+| **Paused for sensitive details** | Recording stops while card or account details are given. | *Secure pause* (Genesys Cloud), *PCI pause*. |
+
+## How the parts talk
+
+| Term | In plain words | What others call it |
+| --- | --- | --- |
+| **Snapshot** | Everything the provider knows right now, sent whole when the agent application connects or reconnects. | *State sync*, *initial state*. |
+| **Event** | One change the provider reports as it happens: a call offered, a task ended. | *Event*, *notification*, *webhook*. |
+| **Command** | Something the agent asks the provider to do: hold, end call, complete. | *Action*, *API call*. |
+| **Capability** | A control the provider offers on a task. If it is offered, the agent can use it. | *Permission*, *feature flag*, *agent capability*. |
+| **Lock** | A setting fixed by a level above the agent, such as the team or the site. | *Policy*, *enforced setting*. |
+| **Guarantee** | A promise the agent application makes at sign-in, such as not offering Mute while a call is on hold. | *Client capability*, *declared support*. |

package/README.md

@@ -15,8 +15,10 @@ system.
 | `guide/` | One file per role and channel: `agent.md`, `lead.md`, `queue.md`, `breaks.md`, `phone.md`, `voice.md`, `chat.md`, `email.md`. Each points back into `guide.md` for what it relies on. |
 | `src/index.ts` | The TypeScript declarations. |
 | `src/validation.ts` | Runtime validators Omni applies to adapter output. |
-| `src/testing.ts` | Testing an adapter an adapter runs against its own test state. |
+| `src/testing.ts` | The test an adapter runs against its own test state. |
 | `tests/` | One test file per source module, plus the guards over the guide and the repository's own text. |
+| `GLOSSARY.md` | **The words.** Every term in plain language, with what the larger contact-centre platforms call it. |
+| `CALL_FLOW.md`, `CHAT_FLOW.md`, `EMAIL_FLOW.md` | **The flows.** How a task moves on each channel, from the offer to its end, as diagrams. |
 
 ## Entry points
 

package/dist/testing.d.ts

@@ -215,8 +215,6 @@ export declare class TeamStream {
     private static ids;
     /** A snapshot carrying a team is the team whole; one carrying none leaves the lead with none. */
     seed(snapshot: unknown): void;
-    /** Whether the team currently carries this member, as the events left it. */
-    has(id: string): boolean;
     apply(envelope: unknown, path?: string): ProtocolViolation[];
 }
 export declare class BreakStream {

package/dist/testing.js

@@ -2235,8 +2235,6 @@ export class TeamStream {
     seed(snapshot) {
         this.members = TeamStream.ids(isRecord(snapshot) ? snapshot.team : undefined);
     }
-    /** Whether the team currently carries this member, as the events left it. */
-    has(id) { return this.members?.has(id) === true; }
     apply(envelope, path = "event") {
         const event = isRecord(envelope) ? envelope.event : undefined;
         if (!isRecord(event))

package/guide.md

@@ -2548,7 +2548,9 @@ a backend that does not know the session yet — yields no snapshot, and the ada
 
 A snapshot must account for **everything the adapter has emitted before it resolves**, not merely
 everything emitted when it was requested. Omni drops the state-replacing events held during the
-read on that promise, and applies the rest after it (see **`Connection.snapshot()`**); an adapter
+read on that promise, and applies the rest after it (see **`Connection.snapshot()`**). Which kinds a
+snapshot restates, and so supersedes, is exported from the testing module as
+`SUPERSEDED_BY_A_SNAPSHOT`, so an agent application and the harness drop the same ones; an adapter
 that serves a stale snapshot and then lets an earlier event through will have Omni apply state the
 snapshot already superseded. The harness reads its connect snapshot the same way, and holds the
 snapshot to accounting for every task event it superseded: a task published during the read and
@@ -2935,6 +2937,9 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | `validateProviderTimeEstimate(estimate, scope)` | Optional agent application estimate shape and provider/login scope; no accuracy guarantee. |
 | `validateHistoryReport(report, path?, manifest?, task?)` | What the agent application reports of a leg it performed, for an adapter to check before forwarding: a task, a step, when it began, a positive `seconds` where stated, and an explicit `ended` that carries the final duration. Given the manifest, a running report is refused unless it declares `runningStepReports`. Given the task, the agent application's own mute beginning on a `paused` task is refused (`historyReport.muted.held`): the Mute waits for resume. |
 | `validateHostReport(report)` | The agent application's own report as published to an adapter: `online`, and where there is audio, an input that is `available` with the microphone and `flowing`, or `unavailable` with a reason and the failure that says why, and an output that is `available` or `unavailable` with its failure. The harness validates whatever agent application a test hands the adapter; `stillHost(report)` builds one that never changes. |
+| `validateNextCall(value)` | The agent's standing ask for the next call, on its own as `next-call` and `Snapshot.nextCall` carry it: since when, and nothing else (`nextCall.since`, `nextCall.field`). |
+| `validateLinedUp(value, path?, levels?)` | A call lined up in the agent's own queue, on its own as `lined-up` and `Snapshot.linedUp` carry it: the caller under the same contact rules as a task's party, the queue's label, the waits, and `release` by presence (`linedUp.*`). |
+| `validatePhoneState(value, path?, context?)` | The phone as the platform sees it, on its own as `phone-updated` and `Snapshot.phone` carry it: its status, its one active channel, its mute where a hardphone's is observed (`phone.*`). |
 | `validateHostMute(mute, softphone)` | What the agent application's Mute does, stated on a softphone login and nowhere else: `stream` or `station` (`host.mute`), required where the agent application holds a microphone (`host.mute.required`) and refused where it does not (`host.mute.unexpected`). The harness holds `ConnectContext.host.mute` to it. |
 | `validateLoginStore(store)` | The login's store the agent application hands every connection: an object with `get`, `set` and `delete` (`store.shape`, `store.get`, `.set`, `.delete`). The harness holds `ConnectContext.store` to it. |
 | `validateCapacity(capacity)` | What the agent application states as capacity: a whole number of zero or more (`capacity.count`), zero being agent application-stopped. The harness states one on connect and two, one and zero after the test, each answered `applied`, and holds any offer to the count in force (`stream.taskOffered.overCapacity`). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xema/omni-protocol",
-  "version": "0.1.118",
+  "version": "0.1.120",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",
@@ -8,6 +8,10 @@
   "files": [
     "dist",
     "README.md",
+    "GLOSSARY.md",
+    "CALL_FLOW.md",
+    "CHAT_FLOW.md",
+    "EMAIL_FLOW.md",
     "guide.md",
     "guide",
     "LICENSE"