@xema/omni-protocol 0.1.132 → 0.1.134

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/guide/queue.md CHANGED
@@ -26,9 +26,9 @@ await connection.requestNextCall()
26
26
  { type: "lined-up", linedUp: { party: { name: "Priya S", number: { lockedBy: "org" } }, queue: "Billing", queuedSince: "2026-09-12T10:39:20Z", since: "2026-09-12T10:41:30Z", release: true } }
27
27
 
28
28
  // The agent's wrap ends and the call is theirs: the entry goes and the task arrives, as any assignment does.
29
- { type: "task-ended", assignmentId: "alloc-42", outcome: { type: "completed", by: "agent" } }
29
+ { type: "task-ended", assignmentId: "asg-42", outcome: { type: "completed", by: "agent" } }
30
30
  { type: "lined-up" }
31
- { type: "task-offered", task: { assignmentId: "alloc-57", phase: "pending", acceptance: "automatic", party: {...}, history: { steps: [{ step: "queued", at: "2026-09-12T10:39:20Z", seconds: 131 }] }, ... } }
31
+ { type: "task-offered", task: { assignmentId: "asg-57", phase: "pending", acceptance: "automatic", party: {...}, history: { steps: [{ step: "queued", at: "2026-09-12T10:39:20Z", seconds: 131 }] }, ... } }
32
32
 
33
33
  // Or somebody else answered first, or the caller gave up: the entry goes and no task ever was.
34
34
  { type: "lined-up" }
@@ -87,293 +87,3 @@ the release.
87
87
 
88
88
  **The lead sees the member's queue as the member does.** The member on the team member list
89
89
  carries `nextCall` and `linedUp` as the member's own snapshot does, republished with the member.
90
-
91
- ### Runtime break prerequisite checks
92
-
93
- Use `validateBreakCommand(method, request, state, context)` from the validation entry point
94
- before any agent break dispatch. The context supplies current authentication and transport, and
95
- the manifest's `levels` the session is validated against;
96
- all four methods require the live session's break capability and active transport. Pass the
97
- request object only to the request method, and undefined to the other three.
98
-
99
- | Method | Required current state |
100
- | --- | --- |
101
- | `requestBreak` | `not-requested`; selected current reason code when codes exist; `canRequestBreak` or the selected reason's `alwaysAvailable` exception. Free text does not replace a code. |
102
- | `commitBreak` | `granted`, or already committed for an idempotent repeat. A later change to `canRequestBreak` does not revoke the grant. |
103
- | `cancelBreak` | `awaiting-approval` or `granted`. A concurrent commit winning still answers `omni.break-already-committed` and requires recovery. |
104
- | `endBreak` | `on-break` or `starting-after-task` during reconciliation; the agent may explicitly end a requested or forced break. |
105
-
106
- Use `validateTeamCommand(request, context)` before every lead act, its context carrying the manifest's `levels` as the break check's does: the team feature switch, break
107
- decisions, forcing and ending a forced break, policy, and every act on a member's call. It requires
108
- the live `lead` capability the command needs and active transport, a current team member list for any command naming a
109
- member, and the target's complete break state for forcing/ending a break. Approve/deny requires an
110
- awaiting decision; forcing a break uses the target's reason codes; ending a forced break requires a
111
- forced committed break; join and decline need the member's request on the list; coach, join-call
112
- and leave need the lead already on that member's call; an assignment named must be one the list
113
- shows the member holding. The context's target state must belong to the named member; that
114
- association and backend authorization are provider responsibilities.
115
-
116
- Use `validateBreakStatus(state, tasks)` on the complete retained task view after each transaction,
117
- as well as `validateBreakTransition` for event ordering. Snapshot validation shares the status
118
- checks. Pending and completing tasks still count as work. Only a call a lead took over
119
- (`takenOver`) sits beside a break in effect. Validate full task shapes and the envelope separately.
120
-
121
- These validators report violations without dispatching, rewriting state or proving freshness.
122
- Recheck prerequisites atomically at the provider; client validation cannot prevent a race.
123
- Continue to use `validateResult` for each method's response vocabulary. A request acknowledgment
124
- is not a grant, and no method response overwrites a newer state emission. Rejected promises
125
- remain unknown and recover by snapshot, not automatic retry. The agent application's frozen provider set,
126
- durable mutually exclusive commit/cancel decision and reconciliation obligations under
127
- **Coordinating a multi-provider break** remain
128
- required; per-provider validation does not implement the multi-provider coordinator.
129
-
130
- ### `requestBreak(request)`
131
-
132
- **Explanatory text is optional.** An agent may omit `BreakRequest.reason` for any break type.
133
- A lead may likewise omit reason text from `force-break`. Do not require a text explanation
134
- just because a break is agent-requested or forced. If supplied, text must be nonempty; omit
135
- it rather than sending an empty string. A selected `reasonId` identifies a published break
136
- choice and is separate from this optional text.
137
-
138
- With published choices, `{ reasonId: "lunch" }` is a valid request without explanation;
139
- without published choices, `{}` is valid. A lead can similarly send a `force-break` command
140
- with its member ID and, where required, the selected reason ID, without reason text.
141
-
142
- Requests permission to stop the agent later; it does not itself stop work. The provider continues
143
- offering work and reports `awaiting-approval` or `granted` through `break-state` events. If the request is denied, the
144
- provider reports `not-requested` directly, with `decisionReason` when one was supplied.
145
-
146
- **An agent asks from anywhere — idle or on a task** — and Omni offers the request in the task
147
- workspace as it does on the idle dashboard. Asked on a task, the break is decided and committed like
148
- any other and begins when the work ends: that is `starting-after-task`, and
149
- `assertBreakBeginsAfterTask` is the scenario that holds a provider to it.
150
-
151
- #### Break reasons
152
-
153
- A provider that defines not-ready reason codes publishes them on `Snapshot.break.reasons`,
154
- and Omni returns the agent's choice as `BreakRequest.reasonId`:
155
-
156
- ```ts
157
- break: {
158
- reasons: [
159
- { id: "lunch", label: "Lunch" },
160
- { id: "training", label: "Training", group: "Scheduled" },
161
- ]
162
- }
163
- ```
164
-
165
- Reason ids are non-empty and unique within the provider. They live on the snapshot rather than the
166
- manifest because a provider may change the codes it offers during a shift; a `snapshot` event
167
- replaces the list. `BreakRequest.reason` remains available for free text and is never a substitute
168
- for `reasonId` when the provider publishes codes. A provider that defines no codes omits the
169
- field.
170
-
171
- #### One break across several providers
172
-
173
- An agent connected to several providers takes **one** break, not one per platform. Omni gathers
174
- what every connected provider offers, shows the distinct breaks, and on a choice sends one request
175
- per provider: the same `reason`, and each provider's own `reasonId`.
176
-
177
- To do that, Omni has to know when two providers mean the same break. Say so with `kind`:
178
-
179
- ```ts
180
- break: {
181
- reasons: [
182
- { id: "lunch", label: "Lunch", kind: "meal" },
183
- { id: "rest", label: "Mandatory rest period", kind: "rest", alwaysAvailable: true },
184
- ]
185
- }
186
- ```
187
-
188
- A provider decides which breaks it offers and what it calls them. `BREAK_KINDS` is the list Omni
189
- supports mapping them onto, and every member means something specific:
190
-
191
- | Kind | What it means |
192
- | --- | --- |
193
- | `short-break` | A brief rest between contacts — the comfort break a shift plan allows for. |
194
- | `meal` | A meal: lunch, dinner, whatever the shift calls it. |
195
- | `rest` | A rest period the agent is entitled to and a busy hour cannot cancel. Usually the reason also marked `alwaysAvailable`, though the two are separate: this says what the break *is*, that says whether policy can withdraw it. |
196
- | `training` | Learning something the agent is expected to know afterwards: a course, e-learning, a product walkthrough. However it is delivered, and whoever attends. |
197
- | `coaching` | Reviewing this agent's own work with somebody accountable for it: a call listened back, quality feedback, a one-to-one about their interactions. Even where the outcome is that they learn something. |
198
- | `meeting` | A scheduled gathering that is neither — a team huddle, a project call, a town hall. The agent attends and contributes; nobody is assessing their work and there is nothing they must know by the end. |
199
- | `administrative` | Paperwork and follow-up not attached to a particular contact. |
200
- | `technical` | Equipment or system trouble stopping the agent taking work: a dead headset, a phone that never registered, a tool that will not load. The one member that is not an activity — it says why the agent *cannot* work rather than what they are doing, which makes it the right home for a not-ready state raised about the agent's equipment. |
201
- | `personal` | Personal time the deployment does not classify further. |
202
- | `other` | None of the above. Matches nothing, including another provider's `other`. |
203
-
204
- **The definitions are the point, not decoration.** Ten undefined strings would be the label
205
- problem one level up: two providers could both declare `technical`, one meaning a dead headset
206
- and the other scheduled maintenance, match on it, and nothing could tell the difference.
207
-
208
- `training`, `coaching` and `meeting` can all fit one session, so take them in that order of
209
- specificity: about this agent's own work is `coaching`, else something they must know afterwards is
210
- `training`, else `meeting`.
211
-
212
- **A break somebody forced on the agent is not automatically one of these.** Where the agent was
213
- stopped rather than choosing to stop — see **Forced breaks** — set `BreakState.forced` and prefer
214
- omitting `kind` to reaching for `other`. None of the ten describes "something was done to this
215
- agent", and `other` claims a classification that was never made.
216
-
217
- Omni matches in this order:
218
-
219
- 1. **`kind`**, where both providers declare one. This wins over the label, so `{ id: "MEAL",
220
- label: "Meal", kind: "meal" }` lines up with `{ id: "lunch", label: "Lunch", kind: "meal" }`
221
- and nobody has to word their codes the same way.
222
- 2. **The label**, folded for case and surrounding spacing, where a kind is missing. `"other"`
223
- counts as missing: two providers saying `"other"` have only said their break is not on the
224
- list, which is no evidence they mean the same thing.
225
-
226
- Nothing else is matched. A break Omni cannot pair stays on its own, the agent is told how many
227
- platforms their break will actually reach, and they can pair the odd one by hand — Omni remembers
228
- that for next time.
229
-
230
- Three rules for a provider:
231
-
232
- - **Declare `kind` where you can, and leave it out where you cannot.** Leaving it out costs a
233
- little precision. Getting it wrong sends an agent to lunch on one platform and to training on
234
- another, and nothing can detect that.
235
- - **You may publish several reasons of one kind** — two meal slots, say. Omni will not choose
236
- between them for the agent; saying they are the same kind is not saying they are interchangeable.
237
- - **Do not read `reason` as your own label.** It is the agent's single choice, in whichever
238
- provider's wording they picked it from, sent unchanged to every provider in the break.
239
-
240
- A provider that publishes no reason codes still receives the request, with `reason` set and
241
- `reasonId` omitted.
242
-
243
- #### Coordinating a multi-provider break
244
-
245
- Sending the requests is a two-phase operation, not independent best effort. A provider first grants
246
- permission for the agent to stop, then Omni either commits or cancels that permission.
247
-
248
- `granted` is provider-visible state. It means only that this provider has granted the active
249
- request and is ready to stop the agent when Omni asks. It does not reveal that other providers exist
250
- or why Omni has not committed yet. While reporting `granted`, the provider remains available,
251
- continues to honour Omni's current capacity, and continues offering work normally.
252
-
253
- Omni separately tracks the aggregate agent application states `working`, `requesting-break`, `committing-break`,
254
- `cancelling-break`, and `on-break`. While `requesting-break`, Omni shows which providers remain
255
- outstanding and offers **Cancel break request**, but does not tell the agent that their break has
256
- begun.
257
-
258
- Omni offers the aggregate Break control only when every provider currently holding capacity
259
- declares `capabilities.breaks` at sign-in. If one cannot be stopped, offering a global break would
260
- knowingly permit partial availability.
261
-
262
- Omni coordinates one break attempt as follows:
263
-
264
- 1. Freeze the providers the attempt asks: every connected provider from which the agent can
265
- currently receive work. A provider joining during the attempt is given no capacity until it
266
- finishes. A provider whose authentication is `expired` is not one the agent can receive work
267
- from and is not asked: nothing is asked of it, the break proceeds without it, and when the
268
- session is restored it is reconciled from its snapshot as a set-aside provider is, with no
269
- capacity until then. `refreshing` keeps a provider in — its identity and capabilities remain
270
- available and work continues. `assertBreakAttemptProviders` holds an agent application to this set.
271
- 2. Enter `requesting-break`. Keep the agent's normal capacity in place throughout this phase.
272
- 3. Send one `requestBreak` to every asked provider. A provider reports `awaiting-approval` or
273
- `granted`; neither state stops work. A denial transitions directly to `not-requested` and
274
- causes Omni to take the cancel path.
275
- 4. If every asked provider reports `granted`, durably choose commit, enter `committing-break`,
276
- and send `commitBreak()` to each of them. A provider then stops offering new work
277
- and reports `starting-after-task` or `on-break`. The **commit bound** — ten seconds from the
278
- decision, tunable per deployment — decides who is kept: a provider that has not applied the
279
- commit by then, still `granted` or unreachable, is set aside as unreconciled and the break
280
- begins without it. `on-break` decides `on-break`: Omni enters it once every kept provider
281
- reports `on-break`. A kept provider reporting `starting-after-task` has applied the commit
282
- and is finishing a task; the bound is on delivery, not on that task. Omni shows the break as
283
- settled and beginning when the task ends, and offers no cancel, because the commit is durable.
284
- 5. If any asked provider fails or denies the request, cannot be reconciled within the bounded
285
- decision timeout, or the agent cancels before commit, durably choose cancel and enter
286
- `cancelling-break`. Send `cancelBreak()` to every provider still reporting
287
- `awaiting-approval` or `granted`. Work continues during cancellation because no stop was
288
- committed. Return to `working` only after no provider retains either state.
289
-
290
- Commit and cancel are mutually exclusive decisions for one break attempt. Once Omni chooses commit
291
- it never rolls that attempt back: it is reconciled by snapshot until every asked provider is stopped.
292
- A provider that reports `granted` must therefore preserve the request across reconnects and must
293
- honour a later commit or cancel. This
294
- durable promise prevents a provider from failing the commit after another provider has already
295
- stopped the agent.
296
-
297
- #### Why the commit phase is bounded and the decision is not
298
-
299
- Waiting for unanimity forever is the one way this algorithm can strand an agent. The commit is
300
- durable and cannot be rolled back, so a provider that crashes, has its authentication revoked,
301
- or is uninstalled between granting and committing would hold Omni in `committing-break` with no
302
- exit: the providers that did commit have already stopped the agent, and the agent is neither
303
- working nor on a break.
304
-
305
- Unanimity is required for a reason that survives the bound. It exists so the agent is not stopped
306
- on one platform while another keeps routing work to them — and **a provider Omni cannot reach is
307
- routing nothing.** Setting it aside therefore costs none of the property it was protecting. Waiting
308
- for it costs the agent their break.
309
-
310
- Setting a provider aside is not a rollback and not a cancel. The commit stands and the
311
- obligation stands: until that provider is stopped it has not stopped. When it returns it emits a
312
- snapshot before anything else, and the snapshot decides:
313
-
314
- - `on-break` or `starting-after-task` — the commit arrived after all. Nothing to send.
315
- - still `granted` — the commit was lost. Omni sends `commitBreak()` now. If the original turns up
316
- late behind it, the provider stops an agent who is already stopped; nothing happens, because a
317
- commit is a state to be in, not an act to be done.
318
- - `not-requested` — the grant did not survive. Omni makes a new request for that provider alone,
319
- against an agent who is already on break elsewhere. **A new session is this case too**: the grant
320
- belonged to the old session.
321
-
322
- The provider must not offer work in the meantime, and the commit is what stops it; Omni gives it
323
- no capacity until it is reconciled.
324
-
325
- **If the agent has already ended the break elsewhere, the break attempt is over** and the returning
326
- provider is reconciled to that instead: still `granted` gets `cancelBreak()`, because committing
327
- would stop an agent who is working again; `starting-after-task` or `on-break` gets `endBreak()`.
328
- Never rolling back is about a break that is still on, not one the agent has finished.
329
-
330
- Omni may tell the agent which platforms the break has not yet reached, as it already does when a
331
- break cannot be paired across every provider.
332
-
333
- The decision phase needs no such bound, because nothing has stopped. Work continues throughout
334
- `requesting-break`, so a provider that never answers costs the agent a wait rather than their
335
- availability, and the existing decision timeout resolves it by cancelling — which is safe precisely
336
- because no stop was ever committed.
337
-
338
- If cancel races with a late approval, the provider remains on the cancel path. If commit has already
339
- won, cancel returns `omni.break-already-committed`, and Omni resumes commit recovery rather than
340
- returning the agent to `working`.
341
-
342
- A forced break is not rolled back by this algorithm. If one appears during either the request or
343
- cancellation, the attempt is abandoned: Omni cancels every grant still outstanding and states
344
- `setCapacity({ count: 0 })` on every other usable provider, as **Forced breaks** sets out; no grant
345
- is committed, because the agent has already stopped everywhere.
346
-
347
- This is two-phase coordination across vendor systems: the approval phase keeps the agent working;
348
- the durable commit decision and snapshot reconciliation provide convergence after partial delivery.
349
-
350
- #### Reporting the break the agent is on
351
-
352
- `BreakState.activeReasonId` is the `BreakReason.id` the current break is on. Omni remembers what it
353
- asked for, but only until the session ends — after a reload or reconnect, or where the provider put
354
- the agent on the break itself, the provider is the only one who knows.
355
-
356
- Omit it when you cannot say, and when there is no break: reporting a reason alongside
357
- `status: "not-requested"` describes a break that is not happening, and is rejected.
358
-
359
- ### `cancelBreak()`
360
-
361
- Cancels the active pre-commit request while its status is `awaiting-approval` or `granted`.
362
- Cancellation releases the request but does not restore work because work never stopped. If
363
- commit already won, the provider returns `omni.break-already-committed`. The resulting state is
364
- reported through `break-state`.
365
-
366
- ### `commitBreak()`
367
-
368
- Commits the `granted` request. Once the provider has reported `granted`, it cannot fail for a
369
- business reason. On commit the provider stops offering new work and reports
370
- `starting-after-task` while existing work finishes, or `on-break` when the break is in effect.
371
- Committing a break that is already in effect changes nothing and answers `committed`.
372
-
373
- ### `endBreak()`
374
-
375
- Tells a provider that an agent already on a break wants to become available again. The provider
376
- reports the resulting state through `break-state` and provider status events.
377
-
378
- It ends the break, which is the thing that started. Nothing about the connection was ever paused,
379
- so there is nothing on it to resume.
package/guide/voice.md CHANGED
@@ -125,7 +125,7 @@ phase it is in.
125
125
 
126
126
  The line runs between the provider's word and Omni's own senses. `task-audio-ended` is the
127
127
  provider's report that primary interaction ended — a fact about the work, which is why the completion
128
- allowance starts on it and the Connect back control appears on it — and Omni follows that report as it
128
+ allowance starts on it and the Reconnect control appears on it — and Omni follows that report as it
129
129
  follows any other. What Omni never does is derive a task's state from its own audio session: a
130
130
  stream that drops, a track that ends, a transport that disconnects, a microphone that fails, an
131
131
  endpoint re-registering change nothing about the task until the provider says so. Structurally:
@@ -167,7 +167,7 @@ tell a task coming back from one going backwards (`stream.taskUpdated.phase`).
167
167
  **The control exists only while there is a window to use it in.** Under `agent-command` the task
168
168
  stays `completing` until the agent completes it, so the window is open for as long as they need.
169
169
  Under `provider-automatic` the window is the allowance -- and with `wrapAllowance: 0` there
170
- is none: the provider completes the task at provider end, and Omni does not offer Connect back,
170
+ is none: the provider completes the task at provider end, and Omni does not offer Reconnect,
171
171
  whatever the task declares. A capability names a control that can be used; on a task with no `completing`
172
172
  window it cannot, and declaring it there changes nothing.
173
173
 
@@ -181,7 +181,7 @@ const connectBackCapable = {
181
181
  } satisfies Pick<Task<"voice">, "channel" | "capabilities" | "phase" | "completionMode" | "wrapAllowance">;
182
182
  ```
183
183
 
184
- With ten seconds of the thirty left, the agent presses Connect back: `execute({ command: { type:
184
+ With ten seconds of the thirty left, the agent presses Reconnect: `execute({ command: { type:
185
185
  "connect-back", dialId } })` returns `dialling`, the task is `in-progress`, and the thirty seconds
186
186
  are gone.
187
187
  The second call ends: `task-audio-ended`, the task is `completing`, and a new thirty seconds runs
@@ -202,7 +202,7 @@ const immediateProviderCompletion = {
202
202
  | `hold` | Primary toggle: Hold | Omni may issue voice-task `hold` and `resume` commands. Hold holds the caller: while the task is `paused` the party waits on hold and the agent keeps talking with everyone else on the call -- an added colleague, a lead who joined -- and `onCall` marks the party `held: true`. |
203
203
  | `endCall` | Primary button: End call | The provider ends the agent's channel and every channel the agent added; the caller continues on the provider's path. The task goes to its wrap. See **Ending a call, and removing one person from it**. |
204
204
  | `terminateCall` | Primary button: Terminate call | The provider ends the whole call: every channel on it, the agent's, the caller's, any colleague's and anyone else's. The task goes to its wrap. See **Ending a call, and removing one person from it**. |
205
- | `connectBack` | Completing-task button: Connect back | Omni may have the provider connect the agent back to the task's party while the task is `completing`, returning it to `in-progress` on the same task. Not offered where there is no `completing` window: `provider-automatic` with a zero allowance completes the task at provider end. See **Connecting back during completion**. |
205
+ | `connectBack` | Completing-task button: Reconnect | Omni may have the provider connect the agent back to the task's party while the task is `completing`, returning it to `in-progress` on the same task. Not offered where there is no `completing` window: `provider-automatic` with a zero allowance completes the task at provider end. See **Connecting back during completion**. |
206
206
  | `schedule` | Secondary menu item: Schedule | Omni may put a follow-up for this party on the calendar, from the call or from its wrap: a time, and a note. See **Scheduling a follow-up** in `guide/agent.md`. |
207
207
  | `leadAssist` | Secondary menu item: Lead assist | Omni may ask a lead to join this call, with a note. The lead's decision reaches the agent on `Task.leadAssist`. See **Lead assist** in `guide/lead.md`. |
208
208
  | `addToCall` | Secondary button: Add to call | Omni may dial a contact or a typed number into the active call (`add-to-call`), and remove one person from it (`remove-from-call`) -- an added entry, one still ringing included, which calls the dial off, or the party, leaving the agent with the colleague. See **Ending a call, and removing one person from it**. |
@@ -392,7 +392,7 @@ claims, and both are true at once when a leg answers and never joins. An agent c
392
392
  dial's conclusion and says "on the call" only when the person appears on `Task.onCall`; the obvious
393
393
  reading of `answered` -- that they are on the line -- is the one it does not make.
394
394
 
395
- **A provider says which outcomes it can tell apart.** No switch distinguishes all five, and a
395
+ **A provider says which outcomes it can tell apart.** No switch distinguishes them all, and a
396
396
  provider that cannot tell busy from unreachable must not pick one. The manifest declares
397
397
  `dialOutcomes`, and a `dial-outcome` carries only a declared member
398
398
  (`event.dialOutcome.undeclared`). The list includes `answered`, or the provider could never state a
@@ -460,7 +460,7 @@ outcome for its dial is refused (`stream.taskUpdated.stage`), as an update that
460
460
  The rule keys on the entry's `dialId`, so an entry the platform added itself, with none, is one
461
461
  whose move the stream cannot hold to an outcome: a clean stream proves nothing about ordering there. It is stated rather
462
462
  than left to whoever placed the dial because that knowledge lives in one process: after a reload,
463
- on a second session, or on a supervisor's screen the snapshot is the only source, and a room that
463
+ on a second session, or on a lead's screen the snapshot is the only source, and a room that
464
464
  cannot tell ringing from joined says it contains someone who may never arrive. Nobody ringing is
465
465
  held (`task.onCall.held.ringing`). A colleague who never answers is a dial that ended: the
466
466
  provider restates the room without the entry, and the agent is back with the customer.