@xema/omni-protocol 0.1.132 → 0.1.133

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/agent.md CHANGED
@@ -122,7 +122,7 @@ A preview's deadline is not on the offer. It travels on the task, as `previewEnd
122
122
  A provider may withdraw a pending task by emitting `task-ended` with a `cancelled` outcome, `by:
123
123
  "provider"`. **`cancelled` says who called the work off**, as `completed` says who completed it:
124
124
  `agent` for a decline, `provider` for a withdrawal or a re-route, `party` for a caller who abandoned
125
- the ring. One word for the three left a supervisor's record unable to tell them apart, so `by` is
125
+ the ring. One word for the three left a lead's record unable to tell them apart, so `by` is
126
126
  required and closed (`event.taskEnded.outcome.cancelled.by`). An offer nobody acted on while
127
127
  `expiresInSeconds` ran is not cancelled by anyone: it lapses, and ends `expired` naming `pending`.
128
128
 
@@ -372,7 +372,7 @@ Migration from the earlier spellings:
372
372
  | schedule on voice alone | `schedule` on every channel, under a manifest that declares `calendar` (`task.capability.calendar.required`), bounded by `settleMs` (`test.schedule.unsettled`) |
373
373
  | a forced break requesting breaks on the other providers | `setCapacity({ count: 0 })` on every other usable provider (`assertForcedBreakStopsTheRest`) |
374
374
  | end-forced-break on a break the platform imposed | refused: `team.command.endForcedBreak.provider`, `omni.break-forced-by-provider` |
375
- | ForcedBreak.expectedDurationMs | `expectedEndsInSeconds`: seconds left, restated (`break.forced.expectedEndsInSeconds`, `.expectedDurationMs.renamed`); the command keeps `expectedDurationMs` |
375
+ | ForcedBreak.expectedDurationMs | `expectedEndsInSeconds`: seconds left, restated (`break.forced.expectedEndsInSeconds`, `.expectedDurationMs.renamed`); the command's is `expectedDurationSeconds`, in the same unit |
376
376
  | MemberShift; the day on the lead's list alone | `Shift`, on `Snapshot.shift` and `shift-updated` for the agent, on `TeamMember.shift` for the lead |
377
377
  | TeamMember.listening as this lead's one entry | `MemberListening[]`, every lead's, each with `leadId` (`team.member.listening.leadId`, `.unique`, `.empty`, `.entry`, `.heard`) |
378
378
  | a member's history trimmed on the lead's list | the record whole, as the member's computer holds it |
@@ -384,7 +384,7 @@ Migration from the earlier spellings:
384
384
  | the phone unspoken | `PhoneState` -- the device, its mute, its channels -- on `Snapshot.phone`, `phone-updated` and `TeamMember.phone`, from a manifest declaring `phoneStatus` (`snapshot.phone.required`, `.unexpected`, `phone.*`, `phone.channel.*`, `event.phone.capability`) |
385
385
  | the agent's readiness for the next call read into setCapacity | the agent's own queue: `capabilities.nextCall`, `requestNextCall`/`cancelNextCall`/`releaseLinedUp`, `Snapshot.nextCall` and `linedUp`, the `next-call` and `lined-up` events (`snapshot.nextCall.idle`, `nextCall.*`, `linedUp.*`) |
386
386
  | a harness that exercised an adapter, drove a call and evaluated rules | the harness reads as a test: `testAdapter`, `withCall`, `timeoutMs`, `notTested`, `rulesTested`, rules `test.*` (`test.timeout`, `test.offer.expired`, `test.preview.deadline`, ...) |
387
- | a `callback-requested` step, and a callback task starting its history afresh | a `callback-requested` step (`by` when an agent arranged it); a callback's task carries the earlier call's steps, oldest first |
387
+ | a `callback-requested` step, and a callback task starting its history afresh | a `callback-requested` step, never with `by` (`task.history.by.unexpected`); a callback's task carries the earlier call's steps, oldest first |
388
388
  | a recording state with an observation id, an observation instant and a validity window, and the helpers that aged it | `recordings` on the task and on `HostRecordingReport`: a list, each recording with `id`, `follows` (`party` or `agent`), `status` (`starting`, `recording`, `paused`, `not-recording`, `unknown`) and a `reason` where paused or unknown; nothing expires; commands name `follows` for a start and `recordingId` otherwise; `validateRecordings` (`recording.task.renamed` refuses the former field) |
389
389
  | a refusal on hold under `omni.command-not-permitted` | `omni.on-hold` |
390
390
  | outbound work's terms reported as `queue` | `dialer`: the dialer that declared the task chose its capabilities |
@@ -432,7 +432,7 @@ something else, which will arrive under its own name and must not be folded in h
432
432
  It rides in the snapshot and is replaced whole like everything else there.
433
433
 
434
434
  Steps are `arrived`, `self-service`, `queued`, `offered`, `answered`, `held`, `muted`, `transferred`, `added`,
435
- `unanswered`, `callback-requested`, and each is defined on `TaskHistoryStep`.
435
+ `unanswered`, `connected-back`, `callback-requested`, and each is defined on `TaskHistoryStep`.
436
436
 
437
437
  **The record starts where the call started.** `arrived` is the instant the call reached the
438
438
  provider, before any menu or queue, and its `seconds`, when the provider measured them, are how
@@ -454,13 +454,20 @@ part, so it has no `by`. `at` is when it began and `seconds`, once it ended, how
454
454
  customer routed again after a transfer has a second entry, one per visit, as a second queue is a
455
455
  second `queued`. A customer that words it *IVR* for its agents does so in `labels.historySteps`.
456
456
 
457
- **A callback carries the call it comes back to.** When a caller asks to be called back, or an agent
458
- arranges it, the provider writes a `callback-requested` step: `by` names the agent who arranged it, and
459
- is absent when the caller chose it in the queue. The callback reaches an agent as a new task, and that
460
- task's history carries the earlier call's steps, oldest first, the `callback-requested` step among them,
461
- then the callback's own -- as a hand-over carries the steps before it. The agent opening a callback
462
- sees that the caller waited and asked, or whose promise they are keeping, and a second try reads as
463
- one, the way contact-centre platforms keep a callback with its original contact.
457
+ **A reconnect is a dial on the same call.** When the agent dials a dropped caller back into the same
458
+ interaction -- the `connect-back` command, shown as *Reconnect* -- the provider writes a
459
+ `connected-back` step: `by` is the agent, `dialId` the command's, and `contactId` the contact dialled
460
+ where the provider has one. A reconnect that rings out reads as any dial does: its outcome, and an
461
+ `unanswered` step.
462
+
463
+ **A queue callback carries the call it comes back to.** When a waiting caller asks to be called back
464
+ once an agent is free, the provider writes a `callback-requested` step. It is the caller's own choice,
465
+ so it never names anyone (`task.history.by.unexpected`). The callback reaches an agent as a new task,
466
+ and that task's history carries the earlier call's steps, oldest first, the `callback-requested` step
467
+ among them, then the callback's own -- as a hand-over carries the steps before it. The agent opening a
468
+ callback sees that the caller waited and asked, and a second try reads as one, the way contact-centre
469
+ platforms keep a callback with its original contact. A call booked for later is a scheduled call: the
470
+ `schedule` command, on the calendar, and never a `callback-requested` step.
464
471
 
465
472
  **One call has one history.** Every task the call reaches restates the earlier steps exactly as they
466
473
  stood: the same step, instant, person, dial and destination, and a duration once stated never
@@ -982,8 +989,8 @@ Every task may publish additional provider-specific controls in `capabilities.cu
982
989
  capabilities: {
983
990
  hold: true,
984
991
  custom: [
985
- { id: "request-supervisor", ui: { control: "button", label: "Request supervisor", placement: "secondary" } },
986
- { id: "mark-vip", ui: { control: "toggle", label: "Mark as VIP", placement: "overflow" } },
992
+ { id: "send-survey", ui: { control: "button", label: "Send survey", placement: "secondary", render: "inline" } },
993
+ { id: "mark-vip", ui: { control: "toggle", label: "Mark as VIP", placement: "overflow", render: "inline" } },
987
994
  ],
988
995
  }
989
996
  ```
@@ -1002,7 +1009,7 @@ control and invokes it with the shared custom task command:
1002
1009
  ```ts
1003
1010
  {
1004
1011
  type: "custom",
1005
- name: "request-supervisor",
1012
+ name: "send-survey",
1006
1013
  }
1007
1014
  ```
1008
1015
 
@@ -1048,23 +1055,22 @@ The one thing the agent application performs physically is the microphone, and t
1048
1055
 
1049
1056
  ### Which commands need a capability
1050
1057
 
1051
- **Presence is the permission** gates the controls a provider chooses to offer. Four commands are
1052
- not among them, because every task has them; each is authorized by a different field the provider
1053
- declared:
1058
+ **Presence is the permission** gates the controls a provider chooses to offer. Each command below
1059
+ is authorized by what the provider declared, or by the phase it is issued in:
1054
1060
 
1055
1061
  | Command | What makes it available |
1056
1062
  | --- | --- |
1057
1063
  | `answer`, `accept` | Nothing. A task that was offered can be accepted, or offering it meant nothing. |
1058
1064
  | `end-call` | The `endCall` capability: ends my part, the caller continues. Never from hold: a `paused` task is resumed first (`command.endCall.held`), or the caller is left in the hold. |
1059
1065
  | `terminate-call` | The `terminateCall` capability: ends the whole call, every channel on it. |
1060
- | `addToCall` with `action: "remove"` | The `addToCall` capability, and somebody else on the call: a remove that would leave the agent alone is `end-call`, and a provider answers it `failed`. |
1066
+ | `remove-from-call` | The `addToCall` capability, and somebody else on the call: a remove that would leave the agent alone is `end-call`, and a provider answers it `failed`. |
1061
1067
  | `decline` | The `decline` capability on any channel, **and** Omni local policy permitting it. One word for refusing an offer, whatever the channel. |
1062
1068
  | `dial` | The `preview` phase. A record put in front of an agent is there to be called, so the phase is the gate and there is no capability. It is a dial, with a `dialId` and a `dial-outcome`. |
1063
1069
  | `complete` | A wrap to cut short: any task but a `provider-automatic` one with `wrapAllowance: 0`, under either completion mode (`command.complete.wrapAllowance`). The `outcomes` capability decides whether a code travels with the command, never whether the command exists — a task Omni cannot complete never ends. What travels is what the capability published: a code from its list where it has one (`command.complete.outcome.unknown`), a code at all where it requires one (`.outcome.required`), notes as it said (`.notes.required`, `.notes.unexpected`), and neither where the task declares no outcomes (`.outcome.unexpected`). |
1064
1070
  | `connect-back` | The `connectBack` capability **and** the `completing` phase. It exists to reach the party again after the call, so it has no meaning while the call is up. |
1065
1071
  | `schedule` | The `schedule` capability, on any channel, in `in-progress`, `paused` or `completing`: a follow-up is promised on the call and written up in wrap alike. The manifest declares `calendar` for it to land on. |
1066
1072
  | `lead-assist` with `action: "request"` or `"cancel"` | The `leadAssist` capability. `cancel` needs a request standing -- `Task.leadAssist` with `stage: "requested"`. |
1067
- | `addToCall` with `action: "add"` | Its capability, and a `contactId` from the provider's contacts, or a typed `number` where the capability says `any-number` (`command.addToCall.number.contactsOnly`), never both (`command.addToCall.number.both`). |
1073
+ | `add-to-call` | The `addToCall` capability, and a `contactId` from the provider's contacts, or a typed `number` where the capability says `any-number` (`command.addToCall.number.contactsOnly`), never both (`command.addToCall.number.both`). |
1068
1074
  | `custom` | A control the task published under `capabilities.custom`, by its `id` (`command.capability.custom`), carrying a non-empty string for each `required` prompt field and strings for any optional fields supplied (`command.custom.prompt`). A toggle carries its target `on` boolean (`command.custom.on`). |
1069
1075
  | Everything else | Its own named capability. |
1070
1076
 
package/guide/breaks.md CHANGED
@@ -15,7 +15,7 @@ nothing while none are being accepted — so they are not published separately.
15
15
  | `canRequestBreak` | Whether the agent may ask at all. Distinct from `status`. |
16
16
  | `requestUnavailableReason` | Display-ready reason shown when `canRequestBreak` is false — a standing gate that applies to everyone. |
17
17
  | `decisionReason` | The words whoever decided attached, from `decide.reason`. About one request and one decision, not a standing gate. |
18
- | `retryRequestAfterMs` | Milliseconds until the agent may retry a break request, when the provider can say. |
18
+ | `retryRequestInSeconds` | Whole seconds until the agent may ask for a break again, as of this publication and restated on each, when the provider can say. |
19
19
  | `reasons` | Not-ready codes this provider offers. Omitted when it defines none; an empty list is refused, being a second spelling of the same fact. |
20
20
  | `activeReasonId` | The `BreakReason.id` the current break is on. Omitted when there is no break. Required on a break `on-break` or `starting-after-task` where the provider publishes `reasons`, a forced break included (`break.activeReasonId.required`): a break with a kind the provider cannot name is a break whose rules nobody can apply. |
21
21
  | `forced` | Set when the break was forced on the agent rather than requested. |
@@ -58,9 +58,10 @@ lifecycle. The old field is rejected even alongside status; related diagnostics
58
58
  The `BreakStatus` union and its values, `reasons`, `activeReasonId`, and the separate testing
59
59
  helper BreakOnTaskStep.approval are unchanged. Hosts and providers must update together.
60
60
 
61
- Migration: the break-state field formerly named retryAfterMs is now `BreakState.retryRequestAfterMs`,
62
- with diagnostic `break.retryRequestAfterMs`. It remains an optional non-negative finite number
63
- of milliseconds; the former break field is rejected even alongside the new field.
61
+ Migration: the break-state field formerly named retryAfterMs, then retryRequestAfterMs, is now
62
+ `BreakState.retryRequestInSeconds`, with diagnostic `break.retryRequestInSeconds`. It is an optional
63
+ whole number of seconds, as every countdown on this wire; either former field is rejected even
64
+ alongside the new one (`break.retryRequestInSeconds.renamed`).
64
65
  The separate authentication and general failure retryAfterMs fields are unchanged.
65
66
 
66
67
  Migration: the former in-effect break approval value is now `on-break`. It means the
@@ -227,7 +228,7 @@ go, and a provider that waits for it will stall.
227
228
  Your own tasks are the only ones you count. What the agent holds at other providers is not your
228
229
  concern — Omni set `count` knowing it, and this is how: the agent is one person on several
229
230
  providers, and the agent application divides their capacity among them rather than telling each the whole. A
230
- provider that has none of it for now is told **`count: 0`, agent application-stopped**: assign nothing, show
231
+ provider that has none of it for now is told **`count: 0`, stopped by the agent application**: assign nothing, show
231
232
  the member as `elsewhere` on the team member list -- signed in here, capacity held by the agent application for elsewhere,
232
233
  a fact this provider holds, where `on-task` would assert work it cannot see -- and take the next
233
234
  count as any other when the agent application has capacity for this provider again. Zero is the one restatement
@@ -256,3 +257,293 @@ is about to finish a call and wants the next one lined up has a different thing
256
257
  it as **The agent's own queue** in `guide/queue.md` sets out; the ceiling stands unchanged while they do,
257
258
  and the queue lives within it: `count: 0` clears the ask and lets a lined-up call go, and a break
258
259
  in flight or in effect does the same, since the break wins.
260
+
261
+ ### Runtime break prerequisite checks
262
+
263
+ Use `validateBreakCommand(method, request, state, context)` from the validation entry point
264
+ before any agent break dispatch. The context supplies current authentication and transport, and
265
+ the manifest's `levels` the session is validated against;
266
+ all four methods require the live session's break capability and active transport. Pass the
267
+ request object only to the request method, and undefined to the other three.
268
+
269
+ | Method | Required current state |
270
+ | --- | --- |
271
+ | `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. |
272
+ | `commitBreak` | `granted`, or already committed for an idempotent repeat. A later change to `canRequestBreak` does not revoke the grant. |
273
+ | `cancelBreak` | `awaiting-approval` or `granted`. A concurrent commit winning still answers `omni.break-already-committed` and requires recovery. |
274
+ | `endBreak` | `on-break` or `starting-after-task` during reconciliation; the agent may explicitly end a requested or forced break. |
275
+
276
+ 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
277
+ decisions, forcing and ending a forced break, policy, and every act on a member's call. It requires
278
+ the live `lead` capability the command needs and active transport, a current team member list for any command naming a
279
+ member, and the target's complete break state for forcing/ending a break. Approve/deny requires an
280
+ awaiting decision; forcing a break uses the target's reason codes; ending a forced break requires a
281
+ forced committed break; join and decline need the member's request on the list; coach, join-call
282
+ and leave need the lead already on that member's call; an assignment named must be one the list
283
+ shows the member holding. The context's target state must belong to the named member; that
284
+ association and backend authorization are provider responsibilities.
285
+
286
+ Use `validateBreakStatus(state, tasks)` on the complete retained task view after each transaction,
287
+ as well as `validateBreakTransition` for event ordering. Snapshot validation shares the status
288
+ checks. Pending and completing tasks still count as work. Only a call a lead took over
289
+ (`takenOver`) sits beside a break in effect. Validate full task shapes and the envelope separately.
290
+
291
+ These validators report violations without dispatching, rewriting state or proving freshness.
292
+ Recheck prerequisites atomically at the provider; client validation cannot prevent a race.
293
+ Continue to use `validateResult` for each method's response vocabulary. A request acknowledgment
294
+ is not a grant, and no method response overwrites a newer state emission. Rejected promises
295
+ remain unknown and recover by snapshot, not automatic retry. The agent application's frozen provider set,
296
+ durable mutually exclusive commit/cancel decision and reconciliation obligations under
297
+ **Coordinating a multi-provider break** remain
298
+ required; per-provider validation does not implement the multi-provider coordinator.
299
+
300
+ ### `requestBreak(request)`
301
+
302
+ **Explanatory text is optional.** An agent may omit `BreakRequest.reason` for any break type.
303
+ A lead may likewise omit reason text from `force-break`. Do not require a text explanation
304
+ just because a break is agent-requested or forced. If supplied, text must be nonempty; omit
305
+ it rather than sending an empty string. A selected `reasonId` identifies a published break
306
+ choice and is separate from this optional text.
307
+
308
+ With published choices, `{ reasonId: "lunch" }` is a valid request without explanation;
309
+ without published choices, `{}` is valid. A lead can similarly send a `force-break` command
310
+ with its member ID and, where required, the selected reason ID, without reason text.
311
+
312
+ Requests permission to stop the agent later; it does not itself stop work. The provider continues
313
+ offering work and reports `awaiting-approval` or `granted` through `break-state` events. If the request is denied, the
314
+ provider reports `not-requested` directly, with `decisionReason` when one was supplied.
315
+
316
+ **An agent asks from anywhere — idle or on a task** — and Omni offers the request in the task
317
+ workspace as it does on the idle dashboard. Asked on a task, the break is decided and committed like
318
+ any other and begins when the work ends: that is `starting-after-task`, and
319
+ `assertBreakBeginsAfterTask` is the scenario that holds a provider to it.
320
+
321
+ #### Break reasons
322
+
323
+ A provider that defines not-ready reason codes publishes them on `Snapshot.break.reasons`,
324
+ and Omni returns the agent's choice as `BreakRequest.reasonId`:
325
+
326
+ ```ts
327
+ break: {
328
+ reasons: [
329
+ { id: "lunch", label: "Lunch" },
330
+ { id: "training", label: "Training", group: "Scheduled" },
331
+ ]
332
+ }
333
+ ```
334
+
335
+ Reason ids are non-empty and unique within the provider. They live on the snapshot rather than the
336
+ manifest because a provider may change the codes it offers during a shift; a `snapshot` event
337
+ replaces the list. `BreakRequest.reason` remains available for free text and is never a substitute
338
+ for `reasonId` when the provider publishes codes. A provider that defines no codes omits the
339
+ field.
340
+
341
+ #### One break across several providers
342
+
343
+ An agent connected to several providers takes **one** break, not one per platform. Omni gathers
344
+ what every connected provider offers, shows the distinct breaks, and on a choice sends one request
345
+ per provider: the same `reason`, and each provider's own `reasonId`.
346
+
347
+ To do that, Omni has to know when two providers mean the same break. Say so with `kind`:
348
+
349
+ ```ts
350
+ break: {
351
+ reasons: [
352
+ { id: "lunch", label: "Lunch", kind: "meal" },
353
+ { id: "rest", label: "Mandatory rest period", kind: "rest", alwaysAvailable: true },
354
+ ]
355
+ }
356
+ ```
357
+
358
+ A provider decides which breaks it offers and what it calls them. `BREAK_KINDS` is the list Omni
359
+ supports mapping them onto, and every member means something specific:
360
+
361
+ | Kind | What it means |
362
+ | --- | --- |
363
+ | `short-break` | A brief rest between contacts — the comfort break a shift plan allows for. |
364
+ | `meal` | A meal: lunch, dinner, whatever the shift calls it. |
365
+ | `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. |
366
+ | `training` | Learning something the agent is expected to know afterwards: a course, e-learning, a product walkthrough. However it is delivered, and whoever attends. |
367
+ | `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. |
368
+ | `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. |
369
+ | `administrative` | Paperwork and follow-up not attached to a particular contact. |
370
+ | `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. |
371
+ | `personal` | Personal time the deployment does not classify further. |
372
+ | `other` | None of the above. Matches nothing, including another provider's `other`. |
373
+
374
+ **The definitions are the point, not decoration.** Ten undefined strings would be the label
375
+ problem one level up: two providers could both declare `technical`, one meaning a dead headset
376
+ and the other scheduled maintenance, match on it, and nothing could tell the difference.
377
+
378
+ `training`, `coaching` and `meeting` can all fit one session, so take them in that order of
379
+ specificity: about this agent's own work is `coaching`, else something they must know afterwards is
380
+ `training`, else `meeting`.
381
+
382
+ **A break somebody forced on the agent is not automatically one of these.** Where the agent was
383
+ stopped rather than choosing to stop — see **Forced breaks** — set `BreakState.forced` and prefer
384
+ omitting `kind` to reaching for `other`. None of the ten describes "something was done to this
385
+ agent", and `other` claims a classification that was never made.
386
+
387
+ Omni matches in this order:
388
+
389
+ 1. **`kind`**, where both providers declare one. This wins over the label, so `{ id: "MEAL",
390
+ label: "Meal", kind: "meal" }` lines up with `{ id: "lunch", label: "Lunch", kind: "meal" }`
391
+ and nobody has to word their codes the same way.
392
+ 2. **The label**, folded for case and surrounding spacing, where a kind is missing. `"other"`
393
+ counts as missing: two providers saying `"other"` have only said their break is not on the
394
+ list, which is no evidence they mean the same thing.
395
+
396
+ Nothing else is matched. A break Omni cannot pair stays on its own, the agent is told how many
397
+ platforms their break will actually reach, and they can pair the odd one by hand — Omni remembers
398
+ that for next time.
399
+
400
+ Three rules for a provider:
401
+
402
+ - **Declare `kind` where you can, and leave it out where you cannot.** Leaving it out costs a
403
+ little precision. Getting it wrong sends an agent to lunch on one platform and to training on
404
+ another, and nothing can detect that.
405
+ - **You may publish several reasons of one kind** — two meal slots, say. Omni will not choose
406
+ between them for the agent; saying they are the same kind is not saying they are interchangeable.
407
+ - **Do not read `reason` as your own label.** It is the agent's single choice, in whichever
408
+ provider's wording they picked it from, sent unchanged to every provider in the break.
409
+
410
+ A provider that publishes no reason codes still receives the request, with `reason` set and
411
+ `reasonId` omitted.
412
+
413
+ #### Coordinating a multi-provider break
414
+
415
+ Sending the requests is a two-phase operation, not independent best effort. A provider first grants
416
+ permission for the agent to stop, then Omni either commits or cancels that permission.
417
+
418
+ `granted` is provider-visible state. It means only that this provider has granted the active
419
+ request and is ready to stop the agent when Omni asks. It does not reveal that other providers exist
420
+ or why Omni has not committed yet. While reporting `granted`, the provider remains available,
421
+ continues to honour Omni's current capacity, and continues offering work normally.
422
+
423
+ Omni separately tracks the aggregate agent application states `working`, `requesting-break`, `committing-break`,
424
+ `cancelling-break`, and `on-break`. While `requesting-break`, Omni shows which providers remain
425
+ outstanding and offers **Cancel break request**, but does not tell the agent that their break has
426
+ begun.
427
+
428
+ Omni offers the aggregate Break control only when every provider currently holding capacity
429
+ declares `capabilities.breaks` at sign-in. If one cannot be stopped, offering a global break would
430
+ knowingly permit partial availability.
431
+
432
+ Omni coordinates one break attempt as follows:
433
+
434
+ 1. Freeze the providers the attempt asks: every connected provider from which the agent can
435
+ currently receive work. A provider joining during the attempt is given no capacity until it
436
+ finishes. A provider whose authentication is `expired` is not one the agent can receive work
437
+ from and is not asked: nothing is asked of it, the break proceeds without it, and when the
438
+ session is restored it is reconciled from its snapshot as a set-aside provider is, with no
439
+ capacity until then. `refreshing` keeps a provider in — its identity and capabilities remain
440
+ available and work continues. `assertBreakAttemptProviders` holds an agent application to this set.
441
+ 2. Enter `requesting-break`. Keep the agent's normal capacity in place throughout this phase.
442
+ 3. Send one `requestBreak` to every asked provider. A provider reports `awaiting-approval` or
443
+ `granted`; neither state stops work. A denial transitions directly to `not-requested` and
444
+ causes Omni to take the cancel path.
445
+ 4. If every asked provider reports `granted`, durably choose commit, enter `committing-break`,
446
+ and send `commitBreak()` to each of them. A provider then stops offering new work
447
+ and reports `starting-after-task` or `on-break`. The **commit bound** — ten seconds from the
448
+ decision, tunable per deployment — decides who is kept: a provider that has not applied the
449
+ commit by then, still `granted` or unreachable, is set aside as unreconciled and the break
450
+ begins without it. `on-break` decides `on-break`: Omni enters it once every kept provider
451
+ reports `on-break`. A kept provider reporting `starting-after-task` has applied the commit
452
+ and is finishing a task; the bound is on delivery, not on that task. Omni shows the break as
453
+ settled and beginning when the task ends, and offers no cancel, because the commit is durable.
454
+ 5. If any asked provider fails or denies the request, cannot be reconciled within the bounded
455
+ decision timeout, or the agent cancels before commit, durably choose cancel and enter
456
+ `cancelling-break`. Send `cancelBreak()` to every provider still reporting
457
+ `awaiting-approval` or `granted`. Work continues during cancellation because no stop was
458
+ committed. Return to `working` only after no provider retains either state.
459
+
460
+ Commit and cancel are mutually exclusive decisions for one break attempt. Once Omni chooses commit
461
+ it never rolls that attempt back: it is reconciled by snapshot until every asked provider is stopped.
462
+ A provider that reports `granted` must therefore preserve the request across reconnects and must
463
+ honour a later commit or cancel. This
464
+ durable promise prevents a provider from failing the commit after another provider has already
465
+ stopped the agent.
466
+
467
+ #### Why the commit phase is bounded and the decision is not
468
+
469
+ Waiting for unanimity forever is the one way this algorithm can strand an agent. The commit is
470
+ durable and cannot be rolled back, so a provider that crashes, has its authentication revoked,
471
+ or is uninstalled between granting and committing would hold Omni in `committing-break` with no
472
+ exit: the providers that did commit have already stopped the agent, and the agent is neither
473
+ working nor on a break.
474
+
475
+ Unanimity is required for a reason that survives the bound. It exists so the agent is not stopped
476
+ on one platform while another keeps routing work to them — and **a provider Omni cannot reach is
477
+ routing nothing.** Setting it aside therefore costs none of the property it was protecting. Waiting
478
+ for it costs the agent their break.
479
+
480
+ Setting a provider aside is not a rollback and not a cancel. The commit stands and the
481
+ obligation stands: until that provider is stopped it has not stopped. When it returns it emits a
482
+ snapshot before anything else, and the snapshot decides:
483
+
484
+ - `on-break` or `starting-after-task` — the commit arrived after all. Nothing to send.
485
+ - still `granted` — the commit was lost. Omni sends `commitBreak()` now. If the original turns up
486
+ late behind it, the provider stops an agent who is already stopped; nothing happens, because a
487
+ commit is a state to be in, not an act to be done.
488
+ - `not-requested` — the grant did not survive. Omni makes a new request for that provider alone,
489
+ against an agent who is already on break elsewhere. **A new session is this case too**: the grant
490
+ belonged to the old session.
491
+
492
+ The provider must not offer work in the meantime, and the commit is what stops it; Omni gives it
493
+ no capacity until it is reconciled.
494
+
495
+ **If the agent has already ended the break elsewhere, the break attempt is over** and the returning
496
+ provider is reconciled to that instead: still `granted` gets `cancelBreak()`, because committing
497
+ would stop an agent who is working again; `starting-after-task` or `on-break` gets `endBreak()`.
498
+ Never rolling back is about a break that is still on, not one the agent has finished.
499
+
500
+ Omni may tell the agent which platforms the break has not yet reached, as it already does when a
501
+ break cannot be paired across every provider.
502
+
503
+ The decision phase needs no such bound, because nothing has stopped. Work continues throughout
504
+ `requesting-break`, so a provider that never answers costs the agent a wait rather than their
505
+ availability, and the existing decision timeout resolves it by cancelling — which is safe precisely
506
+ because no stop was ever committed.
507
+
508
+ If cancel races with a late approval, the provider remains on the cancel path. If commit has already
509
+ won, cancel returns `omni.break-already-committed`, and Omni resumes commit recovery rather than
510
+ returning the agent to `working`.
511
+
512
+ A forced break is not rolled back by this algorithm. If one appears during either the request or
513
+ cancellation, the attempt is abandoned: Omni cancels every grant still outstanding and states
514
+ `setCapacity({ count: 0 })` on every other usable provider, as **Forced breaks** sets out; no grant
515
+ is committed, because the agent has already stopped everywhere.
516
+
517
+ This is two-phase coordination across vendor systems: the approval phase keeps the agent working;
518
+ the durable commit decision and snapshot reconciliation provide convergence after partial delivery.
519
+
520
+ #### Reporting the break the agent is on
521
+
522
+ `BreakState.activeReasonId` is the `BreakReason.id` the current break is on. Omni remembers what it
523
+ asked for, but only until the session ends — after a reload or reconnect, or where the provider put
524
+ the agent on the break itself, the provider is the only one who knows.
525
+
526
+ Omit it when you cannot say, and when there is no break: reporting a reason alongside
527
+ `status: "not-requested"` describes a break that is not happening, and is rejected.
528
+
529
+ ### `cancelBreak()`
530
+
531
+ Cancels the active pre-commit request while its status is `awaiting-approval` or `granted`.
532
+ Cancellation releases the request but does not restore work because work never stopped. If
533
+ commit already won, the provider returns `omni.break-already-committed`. The resulting state is
534
+ reported through `break-state`.
535
+
536
+ ### `commitBreak()`
537
+
538
+ Commits the `granted` request. Once the provider has reported `granted`, it cannot fail for a
539
+ business reason. On commit the provider stops offering new work and reports
540
+ `starting-after-task` while existing work finishes, or `on-break` when the break is in effect.
541
+ Committing a break that is already in effect changes nothing and answers `committed`.
542
+
543
+ ### `endBreak()`
544
+
545
+ Tells a provider that an agent already on a break wants to become available again. The provider
546
+ reports the resulting state through `break-state` and provider status events.
547
+
548
+ It ends the break, which is the thing that started. Nothing about the connection was ever paused,
549
+ so there is nothing on it to resume.
package/guide/chat.md CHANGED
@@ -7,6 +7,6 @@ What is true of a chat and of nothing else. Part of the contract in `guide.md`,
7
7
  | Capability | Omni UI | Contract |
8
8
  | --- | --- | --- |
9
9
  | `decline` | Pending-task button: Decline | The provider can decline a pending chat offer. Omni shows it only when local policy also permits declining. |
10
- | `hold` | Primary toggle: Hold | Omni may pause and resume the agent’s interaction in the chat. |
10
+ | `hold` | Primary toggle: Pause | Omni may pause and resume the agent’s interaction in the chat. |
11
11
  | `schedule` | Secondary menu item: Schedule | Omni may put a follow-up for this party on the calendar, from the conversation or from its wrap. See **Scheduling a follow-up** in `guide/agent.md`. |
12
12
  | `outcomes` | Primary button: Complete | Omni may request task completion with a provider outcome and notes. |
package/guide/lead.md CHANGED
@@ -20,7 +20,7 @@ computes nothing. See **`team-updated`** in `guide.md` and its companions.
20
20
 
21
21
  | Field | Contract |
22
22
  | --- | --- |
23
- | `members` | Every member of this lead's team, whatever their state, each with their open tasks. `[]` says the lead has a team with nobody in it; omitting the team member list says something else entirely — see **The session is the permission** below. |
23
+ | `members` | Every member of this lead's team, whatever their state, each with their open tasks. `[]` says the lead has a team with nobody in it; omitting the team member list says something else entirely — see **The user's capabilities are the permission** below. |
24
24
  | `policies` | The team's policy per capability as it stands — the setting, who set it, and `lockedBy` where a level above the team made it theirs to keep. Present where the provider offers policy control; absent where it does not. See **Who decides what an agent may do** in `guide.md`. |
25
25
 
26
26
  | `TeamMember` field | Contract |
@@ -34,7 +34,7 @@ computes nothing. See **`team-updated`** in `guide.md` and its companions.
34
34
  | `request` | Present while the member is asking a lead to join one of their calls: which assignment, the note they wrote, since when. The call named is one their `tasks` carry (`team.member.request.assignment`). Absent when they are not asking. See **Lead assist**. |
35
35
  | `nextCall`, `linedUp` | The member's own queue as their own snapshot carries it: their standing ask for the next call, and the call lined up for them. See **The agent's own queue** in `guide/queue.md`. |
36
36
  | `phone` | The member's phone as the platform sees it: the same `PhoneState` the member's own snapshot carries, so a lead sees a hardphone that is down, or a call on it that is no task, as the member does. Present where the provider declares `phoneStatus`. See **The phone's own view** in `guide/phone.md`. |
37
- | `shift` | The member's own history for the day, about the person rather than any one call: `signedInAt`, `signedOutAt` once it has happened, today's totals as the provider counts them — `talkSeconds`, `holdSeconds`, `breakSeconds`, `tasksHandled`, each present only when the provider knows it — and the day's sign-in, sign-out and break `events`, oldest first. The same `Shift` the member's own snapshot carries, the same numbers from the same count. Omitted where the provider cannot say. |
37
+ | `shift` | The member's own history for the day, about the person rather than any one call: `signedInAt`, the day's first sign-in; `signedOutAt`, present only while the member is signed out; today's totals as the provider counts them — `talkSeconds`, `holdSeconds`, `breakSeconds`, `tasksHandled`, each present only when the provider knows it; `running`, the stretches still under way, which the totals leave out; and the day's sign-in, sign-out and break `events`, oldest first. The same instants and count the member's own snapshot carries, cut by the lead's day. Omitted where the provider cannot say. |
38
38
 
39
39
  Each availability value means one thing:
40
40
 
@@ -43,7 +43,7 @@ Each availability value means one thing:
43
43
  | `ready` | Signed in, able to take work, none assigned. |
44
44
  | `on-task` | Working on at least one task. It says nothing about how many, and nothing about whether more will fit. |
45
45
  | `on-break` | Stopped and not taking work, whether they asked or somebody stopped them. The reason lives on their own `BreakState`, not here. |
46
- | `elsewhere` | Signed in here, and the agent application holds this agent's capacity for another provider (`count: 0`, agent application-stopped): not receiving this provider's work, and not on a break. See **Capacity**. |
46
+ | `elsewhere` | Signed in here, and the agent application holds this agent's capacity for another provider (`count: 0`, stopped by the agent application): not receiving this provider's work, and not on a break. See **Capacity and break actions** in `guide/breaks.md`. |
47
47
  | `signed-out` | Known to this team but not signed in to this provider. |
48
48
 
49
49
  **Publish the whole team once, then each member whole.** Team presence typically reaches an
@@ -68,10 +68,12 @@ part for longer than the delay between them.
68
68
 
69
69
  **The agent's day is on the wire.** The lead sees `shift` totals as the provider counts them, and
70
70
  the agent sees the same: `Snapshot.shift` and `shift-updated` carry the agent's own day in the same
71
- shape, from the same count, so "calls today: 12" is one number on both screens. The agent computer computes
72
- nothing of the day; `tasksHandled` moves when a task ends and `talkSeconds` when a leg closes, and
73
- the active call's running time is the screen's own until then, as **Every screen counts from the
74
- provider's clock** sets out.
71
+ shape, from the same count, so "calls today: 12" is one number on both screens -- each cut by its
72
+ viewer's day, as **The agent's day** in `guide.md` sets out. The agent computer computes nothing of
73
+ the day. A total stands as of the last `shift-updated`; a stretch still under way is in `running`,
74
+ left out of its total, and the agent computer counts it on from its `since`, on the provider's
75
+ clock, as **Every screen counts from the provider's clock** in `guide.md` sets out. A provider sends
76
+ no timer: the totals move on the events that move them.
75
77
 
76
78
  **Omit `since` rather than inventing one.** Omni renders it as a duration, so a timestamp
77
79
  synthesised from the adapter's own clock at seed time reads as "on task for 0 seconds" for
@@ -127,7 +129,7 @@ assignment from the member alone.
127
129
  | `{ type: "lead-features", enabled }` | The team feature on or off. See **The lead switches the feature on and off** above. |
128
130
  | `{ type: "decide-break-request", memberId, decision, reason? }` | Settles one pending request. `decision` is `granted` or `denied`. A grant moves the member to `granted`; a denial ends the request and moves it directly to `not-requested`. |
129
131
  | `{ type: "set-break-policy", policy }` | `approval-required`, `automatically-approved`, or `requests-suspended`. |
130
- | `{ type: "force-break", memberId, reasonId?, reason?, expectedDurationMs? }` | Puts a member on a break they did not ask for. `reasonId` names a published `BreakReason.id` and is required whenever the provider publishes `reasons`; the member's forced break carries it as `activeReasonId`, so its kind is known. Optional `expectedDurationMs` is advisory; the resulting forced break publishes what is left of it as `expectedEndsInSeconds`, restated on every publication. |
132
+ | `{ type: "force-break", memberId, reasonId?, reason?, expectedDurationSeconds? }` | Puts a member on a break they did not ask for. `reasonId` names a published `BreakReason.id` and is required whenever the provider publishes `reasons`; the member's forced break carries it as `activeReasonId`, so its kind is known. Optional `expectedDurationSeconds` is advisory; the resulting forced break publishes what is left of it as `expectedEndsInSeconds`, restated on every publication. |
131
133
  | `{ type: "end-forced-break", memberId }` | Asks the provider to lift a forced-break restriction a lead asked for, by clearing `BreakState.forced`; one the platform imposed is its own to lift (`team.command.endForcedBreak.provider`, `omni.break-forced-by-provider`). The committed break continues; only the agent resumes work. |
132
134
  | `{ type: "join", memberId, assignmentId? }` | Answers the member's request: the provider bridges the lead's channel into the call. See **Lead assist**. |
133
135
  | `{ type: "decline", memberId, assignmentId?, reason? }` | Refuses the member's request. |
@@ -161,14 +163,14 @@ flow, in order:
161
163
 
162
164
  ```ts
163
165
  // 1. The agent asks, with a small note. Their task carries `leadAssist` from here on.
164
- execute({ assignmentId: "alloc-42", command: { type: "lead-assist", action: "request", note: "Refund dispute, needs approval" } })
166
+ execute({ assignmentId: "asg-42", command: { type: "lead-assist", action: "request", note: "Refund dispute, needs approval" } })
165
167
  // task.leadAssist = { stage: "requested", note: "Refund dispute, needs approval", since }
166
168
 
167
169
  // 2. Every lead with the team feature on sees the request on the member.
168
- // team-member-updated: member: { id: "A-1", ..., request: { assignmentId: "alloc-42", note, since } }
170
+ // team-member-updated: member: { id: "A-1", ..., request: { assignmentId: "asg-42", note, since } }
169
171
 
170
172
  // 3. A lead joins, or declines.
171
- executeTeam({ command: { type: "join", memberId: "A-1", assignmentId: "alloc-42" } })
173
+ executeTeam({ command: { type: "join", memberId: "A-1", assignmentId: "asg-42" } })
172
174
  executeTeam({ command: { type: "decline", memberId: "A-1", reason: "In a call" } })
173
175
  ```
174
176
 
@@ -259,10 +261,10 @@ The flow, end to end:
259
261
  // 1. The lead, with the feature on, sees a member on-task with their tasks, and picks a call.
260
262
  // 2. The lead's channel joins it in silence. Conditions: the lead's voice channel is free --
261
263
  // not on a call, not listening elsewhere. Capacity is not involved: nothing is assigned.
262
- executeTeam({ command: { type: "listen", memberId: "A-1", assignmentId: "alloc-42" } })
264
+ executeTeam({ command: { type: "listen", memberId: "A-1", assignmentId: "asg-42" } })
263
265
  // 3. The provider publishes the member whole on team-member-updated, to every lead; the member carries
264
- // listening: [{ leadId: "L-9", assignmentId: "alloc-42", mode: "listen", since }]
265
- // -- L-9's application opens openAudio({ assignmentId: "alloc-42" }) on its own connection; every
266
+ // listening: [{ leadId: "L-9", assignmentId: "asg-42", mode: "listen", since }]
267
+ // -- L-9's application opens openAudio({ assignmentId: "asg-42" }) on its own connection; every
266
268
  // other lead's shows L-9 on the call and opens nothing.
267
269
  // 4. The lead changes how they are heard; the member is published again with the entry's new mode. The audio stays open.
268
270
  // join-call is heard by everyone, so the member's task is also republished with L-9 on onCall as an agent.
package/guide/phone.md CHANGED
@@ -17,7 +17,7 @@ mode stays with the session rather than being inferred from a snapshot or a devi
17
17
  Nor does the audio ever stand in for the task: a task's presence and
18
18
  phase follow the provider's reports about the work, and the audio — attaching, moving through a
19
19
  hold, someone added to the call, a lead joining or a take-over, and ending — is transient beside it. See **A task is
20
- never its audio** under **Task assignment lifecycle**.
20
+ never its audio** in `guide/voice.md`.
21
21
 
22
22
  ### The agent application reports, the adapter decides
23
23
 
@@ -83,8 +83,9 @@ stated a violation. Capacity does not wait on the microphone: whether an agent w
83
83
  can take calls is the platform's question, answered by the adapter from the agent application's report, not by
84
84
  Omni withholding capacity for every platform alike.
85
85
 
86
- Capacity follows **automatically** once the connection is established; the agent does not press
87
- anything to become available.
86
+ Capacity follows once the connection is established, when the agent application's local policy
87
+ says -- at once, or when the agent presses Ready -- as **The agent becomes ready** in
88
+ `guide/agent.md` sets out; the connection itself makes nobody available.
88
89
 
89
90
  | Situation | What Omni sends |
90
91
  | --- | --- |
@@ -248,7 +249,7 @@ through `recordStep` -- its own Mute, and a station mute it observed during a ca
248
249
  the provider knows who that is: it attributes the leg to the session's agent in `by`, a fact it
249
250
  holds and not an inference, for a station mute as much as for the agent application's own. An unattributed
250
251
  `muted` entry is refused (`task.history.muted.by`); a shared handset's unattributed hold
251
- is a different claim, and stands. A supervisor reading the record then sees "the agent muted for
252
+ is a different claim, and stands. A lead reading the record then sees "the agent muted for
252
253
  forty seconds" and "the agent's headset was muted for forty seconds" as the different things they
253
254
  are. See **The agent application records what it performs** in `guide/agent.md`.
254
255
 
@@ -295,10 +296,10 @@ and `phone-updated`, from a manifest that declares `phoneStatus` (`snapshot.phon
295
296
  `snapshot.phone.unexpected`, `event.phone.capability`).
296
297
 
297
298
  ```ts
298
- // people added to the call on alloc-42 -- one channel, since the bridge mixes -- with alloc-43 parked
299
+ // people added to the call on asg-42 -- one channel, since the bridge mixes -- with asg-43 parked
299
300
  const busy: PhoneState = { phone: "hardphone", status: "ready", muted: true, channels: [
300
- { state: "active", since: "2026-09-12T10:30:04Z", assignmentId: "alloc-42" },
301
- { state: "held", since: "2026-09-12T10:35:20Z", assignmentId: "alloc-43" },
301
+ { state: "active", since: "2026-09-12T10:30:04Z", assignmentId: "asg-42" },
302
+ { state: "held", since: "2026-09-12T10:35:20Z", assignmentId: "asg-43" },
302
303
  ] };
303
304
  // an internal call on the extension the agent computer never saw as a task
304
305
  const internal: PhoneState = { phone: "hardphone", status: "ready", channels: [{ state: "active", since: "2026-09-12T11:02:00Z" }] };