@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/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
@@ -80,8 +81,7 @@ mayAsk. Request eligibility remains distinct from approval; existing alwaysAvail
80
81
  exceptions are unchanged. Hosts and providers must update together.
81
82
 
82
83
  Migration: ImposedBreak is now `ForcedBreak`, and the former imposed field is now
83
- `BreakState.forced`. Diagnostic and harness coverage names use `break.forced`. The former agent-end prohibition
84
- has been removed: forced breaks also permit explicit agent resumption. Update hosts and providers together. The old field
84
+ `BreakState.forced`. Diagnostic and harness coverage names use `break.forced`. Update hosts and providers together. The old field
85
85
  is rejected, including when both spellings are sent; no compatibility alias is provided.
86
86
  The break policy value formerly named auto-approve is now `automatically-approved`.
87
87
  Requests are approved automatically; approval does not skip commitment or the prerequisites
@@ -100,16 +100,32 @@ The team break command formerly named place is now `force-break`. Hosts and prov
100
100
  adopt the new command together; place and the interim force spelling are rejected without aliases.
101
101
  The team break command formerly named release is now `end-forced-break`, and its diagnostic is
102
102
  `team.command.endForcedBreak`. The former release command and the interim end spelling are rejected without aliases.
103
- The agent’s `endBreak` now applies to forced breaks as well as requested breaks.
104
-
105
- `ForcedBreak` names who forced the break and may say how long it is expected to run yet, as
106
- `expectedEndsInSeconds`: whole seconds from the publication that carries it, restated on every
107
- publication, so every screen -- the agent's, reloaded or not, and every lead's -- counts down the
108
- same number from receipt (`break.forced.expectedEndsInSeconds`). The duration the lead asked for
109
- travels on the `force-break` command alone; the state says what is left, and drops the field once
110
- it has run out. The agent must explicitly resume when ready. The retired endsAutomatically and
111
- endsAt fields are rejected, including when an expectation is also provided. Who forced it is
112
- `by`, as **A forced break is the provider's act** below sets out.
103
+ Migration: the agent's `endBreak` no longer ends a forced break. It is refused before it is sent
104
+ (`break.command.end.forced`), and a provider that receives one answers `failed` with
105
+ `omni.break-forced`. The agent application no longer offers Resume on a forced break.
106
+ Migration: `ForcedBreak` now says whom it covers, as `scope` (`break.forced.scope`), and its
107
+ `expectedEndsInSeconds` is now `endsInSeconds`, since the break is lifted when it runs out
108
+ (`break.forced.expectedEndsInSeconds.renamed`). The `force-break` command's
109
+ `expectedDurationSeconds` is now `durationSeconds` (`team.command.expectedDurationSeconds.renamed`).
110
+
111
+ `ForcedBreak` names who forced the break, whom it covers, and how long it has left.
112
+
113
+ **There are two kinds, by `scope`.**
114
+
115
+ | `scope` | Covers | Its end | Signed-out time |
116
+ | --- | --- | --- | --- |
117
+ | `team` | The whole team, members who sign in while it runs included. A lead's `force-team-break`, or a break the platform schedules. | One end for everyone, always stated (`break.forced.team.endsInSeconds`). | Counts. A member who signs back in after the end finds no break. |
118
+ | `agent` | One agent. A lead's `force-break`, or a hold the platform puts on one agent. | A length, where one was given; without one it stands until lifted. | Does not count. The clock stops at sign-out and goes on at the next sign-in, so thirty minutes means thirty minutes signed in. |
119
+
120
+ `endsInSeconds` is how long the break has left: whole seconds from the publication that carries
121
+ it, restated on every publication, so every screen -- the agent's, reloaded or not, and every
122
+ lead's -- counts down the same number from receipt (`break.forced.endsInSeconds`). The length the
123
+ lead asked for travels on the command alone, as `durationSeconds`; the state says what is left.
124
+ **When it runs out, the provider lifts the break**, as a lead's `end-forced-break` would: it clears
125
+ `forced` and leaves an ordinary break, and the agent resumes when ready. The agent application
126
+ counts down but never acts on zero; the provider's publication lifts it. The retired
127
+ endsAutomatically and endsAt fields are rejected. Who forced it is `by`, as **A forced break is
128
+ the provider's act** below sets out.
113
129
 
114
130
  Omni resolves the name to show with `getUserDetails()`, so a provider sends the identifier and never
115
131
  a display name.
@@ -124,13 +140,40 @@ For example:
124
140
  ```ts
125
141
  forced: {
126
142
  by: "manager-1042",
127
- expectedEndsInSeconds: 600
143
+ scope: "agent",
144
+ endsInSeconds: 600
128
145
  }
129
146
  ```
130
147
 
131
- The agent application keeps **Resume** available for an agent on a forced break. The agent explicitly chooses
132
- Resume; the agent application sends `endBreak()` and follows the provider-confirmed state before resuming
133
- work. The expectation is whole seconds still to run, restated on every publication; omission
148
+ **The agent cannot end a forced break.** Forcing a break is how a lead or the platform takes the
149
+ agent off work, and a break the agent could end at will would take nobody off anything. So the
150
+ agent application offers no Resume while `forced` is present, and `endBreak()` on it is refused
151
+ before it is sent (`break.command.end.forced`). A provider that receives one answers `failed`
152
+ with `omni.break-forced` and leaves the break as it was.
153
+
154
+ **Only lifting ends it.** A lead's `end-forced-break` or `end-team-break`, the platform lifting
155
+ its own, or `endsInSeconds` running out clears `forced` and leaves an ordinary break. The agent
156
+ then resumes when ready, as from any break.
157
+
158
+ **Signing out does not end it.** The agent may sign out on a forced break, as at any time, but
159
+ that ends the session and not the break. The provider keeps the break, and the first snapshot of
160
+ the agent's next session carries it again while it stands, `on-break` with the same `forced`,
161
+ `activeReasonId` and what is left of `endsInSeconds` by its kind's clock. Without that, signing
162
+ out and straight back in would undo any forced break. While the agent is away, the lead's team
163
+ list shows them `signed-out`, not `on-break`: someone who has gone home is not on a break. The
164
+ break is held for their return, not shown.
165
+
166
+ `testAdapter` holds a provider to this when given `signInAgain`, a way to build the adapter again
167
+ that signs the same agent in, as a sign-in screen would. A run that ends with the agent on a
168
+ forced break signs out, signs in again, and reads the new session's snapshot. That snapshot
169
+ carries the same break, from the same person, on the same reason, or the run names it
170
+ (`test.signIn.forcedBreak`). Its time left is held to its kind's clock: a team break's ran on
171
+ while the agent was away, an agent's own stood still, and neither grows
172
+ (`test.signIn.endsInSeconds`). A sign-in that does not come back as the same agent is named too
173
+ (`test.signIn.session`). A run without `signInAgain`, or with no forced break to carry, lists
174
+ `break.forced.signIn` under `notTested`: the rule was not checked, and the result says so.
175
+
176
+ The expectation is whole seconds still to run, restated on every publication; omission
134
177
  means none was stated, or it has run out. Neither its reaching zero nor an overdue indication
135
178
  authorizes the agent application or provider to end the break, restore availability, or route
136
179
  work to the agent.
@@ -151,15 +194,19 @@ to lift: a lead's `end-forced-break` on it is refused before it is sent
151
194
  published state and waits for the agent's explicit Resume, even after reconnect. Historical
152
195
  attribution is not rewritten by clearing the current forced marker.
153
196
 
154
- The agent may explicitly resume either before or after the lead lifts the restriction. A lead
155
- command, timer, late snapshot or reconnect is never a substitute for that choice. Providers
197
+ The agent resumes only after the restriction is lifted, and only by their own choice. A lead
198
+ command, timer, late snapshot or reconnect is never a substitute for that choice. A stream that
199
+ takes a forced break straight back to `not-requested`, without clearing `forced` first, is
200
+ refused (`stream.breakState.forcedEnded`). Providers
156
201
  must correlate resumption to the authenticated agent's action; a state-only ordering validator
157
202
  cannot establish the cause of a transition. The usual multi-provider end/reconciliation flow
158
203
  still applies, and work resumes only on confirmed provider state.
159
204
 
160
- An agent application counts `expectedEndsInSeconds` down from receipt, on every publication that
205
+ An agent application counts `endsInSeconds` down from receipt, on every publication that
161
206
  carries it, and shows nothing of it where the provider sends none. It invents no start and no
162
- return time, and nothing acts on the number reaching zero.
207
+ return time, and the agent application does not act on the number reaching zero: the provider's
208
+ publication lifting the break does. It shows a `team` break as the team's and an `agent` break as
209
+ the agent's own.
163
210
 
164
211
  A break applies to the **agent**, not to one provider. When a provider forces one, Omni stops the
165
212
  agent everywhere else at once, and not by asking: it states `setCapacity({ count: 0 })` on every
@@ -227,7 +274,7 @@ go, and a provider that waits for it will stall.
227
274
  Your own tasks are the only ones you count. What the agent holds at other providers is not your
228
275
  concern — Omni set `count` knowing it, and this is how: the agent is one person on several
229
276
  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
277
+ provider that has none of it for now is told **`count: 0`, stopped by the agent application**: assign nothing, show
231
278
  the member as `elsewhere` on the team member list -- signed in here, capacity held by the agent application for elsewhere,
232
279
  a fact this provider holds, where `on-task` would assert work it cannot see -- and take the next
233
280
  count as any other when the agent application has capacity for this provider again. Zero is the one restatement
@@ -256,3 +303,293 @@ is about to finish a call and wants the next one lined up has a different thing
256
303
  it as **The agent's own queue** in `guide/queue.md` sets out; the ceiling stands unchanged while they do,
257
304
  and the queue lives within it: `count: 0` clears the ask and lets a lined-up call go, and a break
258
305
  in flight or in effect does the same, since the break wins.
306
+
307
+ ### Runtime break prerequisite checks
308
+
309
+ Use `validateBreakCommand(method, request, state, context)` from the validation entry point
310
+ before any agent break dispatch. The context supplies current authentication and transport, and
311
+ the manifest's `levels` the session is validated against;
312
+ all four methods require the live session's break capability and active transport. Pass the
313
+ request object only to the request method, and undefined to the other three.
314
+
315
+ | Method | Required current state |
316
+ | --- | --- |
317
+ | `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. |
318
+ | `commitBreak` | `granted`, or already committed for an idempotent repeat. A later change to `canRequestBreak` does not revoke the grant. |
319
+ | `cancelBreak` | `awaiting-approval` or `granted`. A concurrent commit winning still answers `omni.break-already-committed` and requires recovery. |
320
+ | `endBreak` | `on-break` or `starting-after-task` during reconciliation, and not `forced` (`break.command.end.forced`): the agent ends a break they asked for, or one whose restriction was lifted. |
321
+
322
+ 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
323
+ decisions, forcing and ending a forced break, for a member or the team, policy, and every act on a member's call. It requires
324
+ the live `lead` capability the command needs and active transport, a current team member list for any command naming a
325
+ member, and the target's complete break state for forcing/ending a break. Approve/deny requires an
326
+ awaiting decision; forcing a break uses the target's reason codes; ending a forced break requires a
327
+ forced committed break; join and decline need the member's request on the list; coach, join-call
328
+ and leave need the lead already on that member's call; an assignment named must be one the list
329
+ shows the member holding. The context's target state must belong to the named member; that
330
+ association and backend authorization are provider responsibilities.
331
+
332
+ Use `validateBreakStatus(state, tasks)` on the complete retained task view after each transaction,
333
+ as well as `validateBreakTransition` for event ordering. Snapshot validation shares the status
334
+ checks. Pending and completing tasks still count as work. Only a call a lead took over
335
+ (`takenOver`) sits beside a break in effect. Validate full task shapes and the envelope separately.
336
+
337
+ These validators report violations without dispatching, rewriting state or proving freshness.
338
+ Recheck prerequisites atomically at the provider; client validation cannot prevent a race.
339
+ Continue to use `validateResult` for each method's response vocabulary. A request acknowledgment
340
+ is not a grant, and no method response overwrites a newer state emission. Rejected promises
341
+ remain unknown and recover by snapshot, not automatic retry. The agent application's frozen provider set,
342
+ durable mutually exclusive commit/cancel decision and reconciliation obligations under
343
+ **Coordinating a multi-provider break** remain
344
+ required; per-provider validation does not implement the multi-provider coordinator.
345
+
346
+ ### `requestBreak(request)`
347
+
348
+ **Explanatory text is optional.** An agent may omit `BreakRequest.reason` for any break type.
349
+ A lead may likewise omit reason text from `force-break`. Do not require a text explanation
350
+ just because a break is agent-requested or forced. If supplied, text must be nonempty; omit
351
+ it rather than sending an empty string. A selected `reasonId` identifies a published break
352
+ choice and is separate from this optional text.
353
+
354
+ With published choices, `{ reasonId: "lunch" }` is a valid request without explanation;
355
+ without published choices, `{}` is valid. A lead can similarly send a `force-break` command
356
+ with its member ID and, where required, the selected reason ID, without reason text.
357
+
358
+ Requests permission to stop the agent later; it does not itself stop work. The provider continues
359
+ offering work and reports `awaiting-approval` or `granted` through `break-state` events. If the request is denied, the
360
+ provider reports `not-requested` directly, with `decisionReason` when one was supplied.
361
+
362
+ **An agent asks from anywhere — idle or on a task** — and Omni offers the request in the task
363
+ workspace as it does on the idle dashboard. Asked on a task, the break is decided and committed like
364
+ any other and begins when the work ends: that is `starting-after-task`, and
365
+ `assertBreakBeginsAfterTask` is the scenario that holds a provider to it.
366
+
367
+ #### Break reasons
368
+
369
+ A provider that defines not-ready reason codes publishes them on `Snapshot.break.reasons`,
370
+ and Omni returns the agent's choice as `BreakRequest.reasonId`:
371
+
372
+ ```ts
373
+ break: {
374
+ reasons: [
375
+ { id: "lunch", label: "Lunch" },
376
+ { id: "training", label: "Training", group: "Scheduled" },
377
+ ]
378
+ }
379
+ ```
380
+
381
+ Reason ids are non-empty and unique within the provider. They live on the snapshot rather than the
382
+ manifest because a provider may change the codes it offers during a shift; a `snapshot` event
383
+ replaces the list. `BreakRequest.reason` remains available for free text and is never a substitute
384
+ for `reasonId` when the provider publishes codes. A provider that defines no codes omits the
385
+ field.
386
+
387
+ #### One break across several providers
388
+
389
+ An agent connected to several providers takes **one** break, not one per platform. Omni gathers
390
+ what every connected provider offers, shows the distinct breaks, and on a choice sends one request
391
+ per provider: the same `reason`, and each provider's own `reasonId`.
392
+
393
+ To do that, Omni has to know when two providers mean the same break. Say so with `kind`:
394
+
395
+ ```ts
396
+ break: {
397
+ reasons: [
398
+ { id: "lunch", label: "Lunch", kind: "meal" },
399
+ { id: "rest", label: "Mandatory rest period", kind: "rest", alwaysAvailable: true },
400
+ ]
401
+ }
402
+ ```
403
+
404
+ A provider decides which breaks it offers and what it calls them. `BREAK_KINDS` is the list Omni
405
+ supports mapping them onto, and every member means something specific:
406
+
407
+ | Kind | What it means |
408
+ | --- | --- |
409
+ | `short-break` | A brief rest between contacts — the comfort break a shift plan allows for. |
410
+ | `meal` | A meal: lunch, dinner, whatever the shift calls it. |
411
+ | `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. |
412
+ | `training` | Learning something the agent is expected to know afterwards: a course, e-learning, a product walkthrough. However it is delivered, and whoever attends. |
413
+ | `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. |
414
+ | `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. |
415
+ | `administrative` | Paperwork and follow-up not attached to a particular contact. |
416
+ | `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. |
417
+ | `personal` | Personal time the deployment does not classify further. |
418
+ | `other` | None of the above. Matches nothing, including another provider's `other`. |
419
+
420
+ **The definitions are the point, not decoration.** Ten undefined strings would be the label
421
+ problem one level up: two providers could both declare `technical`, one meaning a dead headset
422
+ and the other scheduled maintenance, match on it, and nothing could tell the difference.
423
+
424
+ `training`, `coaching` and `meeting` can all fit one session, so take them in that order of
425
+ specificity: about this agent's own work is `coaching`, else something they must know afterwards is
426
+ `training`, else `meeting`.
427
+
428
+ **A break somebody forced on the agent is not automatically one of these.** Where the agent was
429
+ stopped rather than choosing to stop — see **Forced breaks** — set `BreakState.forced` and prefer
430
+ omitting `kind` to reaching for `other`. None of the ten describes "something was done to this
431
+ agent", and `other` claims a classification that was never made.
432
+
433
+ Omni matches in this order:
434
+
435
+ 1. **`kind`**, where both providers declare one. This wins over the label, so `{ id: "MEAL",
436
+ label: "Meal", kind: "meal" }` lines up with `{ id: "lunch", label: "Lunch", kind: "meal" }`
437
+ and nobody has to word their codes the same way.
438
+ 2. **The label**, folded for case and surrounding spacing, where a kind is missing. `"other"`
439
+ counts as missing: two providers saying `"other"` have only said their break is not on the
440
+ list, which is no evidence they mean the same thing.
441
+
442
+ Nothing else is matched. A break Omni cannot pair stays on its own, the agent is told how many
443
+ platforms their break will actually reach, and they can pair the odd one by hand — Omni remembers
444
+ that for next time.
445
+
446
+ Three rules for a provider:
447
+
448
+ - **Declare `kind` where you can, and leave it out where you cannot.** Leaving it out costs a
449
+ little precision. Getting it wrong sends an agent to lunch on one platform and to training on
450
+ another, and nothing can detect that.
451
+ - **You may publish several reasons of one kind** — two meal slots, say. Omni will not choose
452
+ between them for the agent; saying they are the same kind is not saying they are interchangeable.
453
+ - **Do not read `reason` as your own label.** It is the agent's single choice, in whichever
454
+ provider's wording they picked it from, sent unchanged to every provider in the break.
455
+
456
+ A provider that publishes no reason codes still receives the request, with `reason` set and
457
+ `reasonId` omitted.
458
+
459
+ #### Coordinating a multi-provider break
460
+
461
+ Sending the requests is a two-phase operation, not independent best effort. A provider first grants
462
+ permission for the agent to stop, then Omni either commits or cancels that permission.
463
+
464
+ `granted` is provider-visible state. It means only that this provider has granted the active
465
+ request and is ready to stop the agent when Omni asks. It does not reveal that other providers exist
466
+ or why Omni has not committed yet. While reporting `granted`, the provider remains available,
467
+ continues to honour Omni's current capacity, and continues offering work normally.
468
+
469
+ Omni separately tracks the aggregate agent application states `working`, `requesting-break`, `committing-break`,
470
+ `cancelling-break`, and `on-break`. While `requesting-break`, Omni shows which providers remain
471
+ outstanding and offers **Cancel break request**, but does not tell the agent that their break has
472
+ begun.
473
+
474
+ Omni offers the aggregate Break control only when every provider currently holding capacity
475
+ declares `capabilities.breaks` at sign-in. If one cannot be stopped, offering a global break would
476
+ knowingly permit partial availability.
477
+
478
+ Omni coordinates one break attempt as follows:
479
+
480
+ 1. Freeze the providers the attempt asks: every connected provider from which the agent can
481
+ currently receive work. A provider joining during the attempt is given no capacity until it
482
+ finishes. A provider whose authentication is `expired` is not one the agent can receive work
483
+ from and is not asked: nothing is asked of it, the break proceeds without it, and when the
484
+ session is restored it is reconciled from its snapshot as a set-aside provider is, with no
485
+ capacity until then. `refreshing` keeps a provider in — its identity and capabilities remain
486
+ available and work continues. `assertBreakAttemptProviders` holds an agent application to this set.
487
+ 2. Enter `requesting-break`. Keep the agent's normal capacity in place throughout this phase.
488
+ 3. Send one `requestBreak` to every asked provider. A provider reports `awaiting-approval` or
489
+ `granted`; neither state stops work. A denial transitions directly to `not-requested` and
490
+ causes Omni to take the cancel path.
491
+ 4. If every asked provider reports `granted`, durably choose commit, enter `committing-break`,
492
+ and send `commitBreak()` to each of them. A provider then stops offering new work
493
+ and reports `starting-after-task` or `on-break`. The **commit bound** — ten seconds from the
494
+ decision, tunable per deployment — decides who is kept: a provider that has not applied the
495
+ commit by then, still `granted` or unreachable, is set aside as unreconciled and the break
496
+ begins without it. `on-break` decides `on-break`: Omni enters it once every kept provider
497
+ reports `on-break`. A kept provider reporting `starting-after-task` has applied the commit
498
+ and is finishing a task; the bound is on delivery, not on that task. Omni shows the break as
499
+ settled and beginning when the task ends, and offers no cancel, because the commit is durable.
500
+ 5. If any asked provider fails or denies the request, cannot be reconciled within the bounded
501
+ decision timeout, or the agent cancels before commit, durably choose cancel and enter
502
+ `cancelling-break`. Send `cancelBreak()` to every provider still reporting
503
+ `awaiting-approval` or `granted`. Work continues during cancellation because no stop was
504
+ committed. Return to `working` only after no provider retains either state.
505
+
506
+ Commit and cancel are mutually exclusive decisions for one break attempt. Once Omni chooses commit
507
+ it never rolls that attempt back: it is reconciled by snapshot until every asked provider is stopped.
508
+ A provider that reports `granted` must therefore preserve the request across reconnects and must
509
+ honour a later commit or cancel. This
510
+ durable promise prevents a provider from failing the commit after another provider has already
511
+ stopped the agent.
512
+
513
+ #### Why the commit phase is bounded and the decision is not
514
+
515
+ Waiting for unanimity forever is the one way this algorithm can strand an agent. The commit is
516
+ durable and cannot be rolled back, so a provider that crashes, has its authentication revoked,
517
+ or is uninstalled between granting and committing would hold Omni in `committing-break` with no
518
+ exit: the providers that did commit have already stopped the agent, and the agent is neither
519
+ working nor on a break.
520
+
521
+ Unanimity is required for a reason that survives the bound. It exists so the agent is not stopped
522
+ on one platform while another keeps routing work to them — and **a provider Omni cannot reach is
523
+ routing nothing.** Setting it aside therefore costs none of the property it was protecting. Waiting
524
+ for it costs the agent their break.
525
+
526
+ Setting a provider aside is not a rollback and not a cancel. The commit stands and the
527
+ obligation stands: until that provider is stopped it has not stopped. When it returns it emits a
528
+ snapshot before anything else, and the snapshot decides:
529
+
530
+ - `on-break` or `starting-after-task` — the commit arrived after all. Nothing to send.
531
+ - still `granted` — the commit was lost. Omni sends `commitBreak()` now. If the original turns up
532
+ late behind it, the provider stops an agent who is already stopped; nothing happens, because a
533
+ commit is a state to be in, not an act to be done.
534
+ - `not-requested` — the grant did not survive. Omni makes a new request for that provider alone,
535
+ against an agent who is already on break elsewhere. **A new session is this case too**: the grant
536
+ belonged to the old session.
537
+
538
+ The provider must not offer work in the meantime, and the commit is what stops it; Omni gives it
539
+ no capacity until it is reconciled.
540
+
541
+ **If the agent has already ended the break elsewhere, the break attempt is over** and the returning
542
+ provider is reconciled to that instead: still `granted` gets `cancelBreak()`, because committing
543
+ would stop an agent who is working again; `starting-after-task` or `on-break` gets `endBreak()`.
544
+ Never rolling back is about a break that is still on, not one the agent has finished.
545
+
546
+ Omni may tell the agent which platforms the break has not yet reached, as it already does when a
547
+ break cannot be paired across every provider.
548
+
549
+ The decision phase needs no such bound, because nothing has stopped. Work continues throughout
550
+ `requesting-break`, so a provider that never answers costs the agent a wait rather than their
551
+ availability, and the existing decision timeout resolves it by cancelling — which is safe precisely
552
+ because no stop was ever committed.
553
+
554
+ If cancel races with a late approval, the provider remains on the cancel path. If commit has already
555
+ won, cancel returns `omni.break-already-committed`, and Omni resumes commit recovery rather than
556
+ returning the agent to `working`.
557
+
558
+ A forced break is not rolled back by this algorithm. If one appears during either the request or
559
+ cancellation, the attempt is abandoned: Omni cancels every grant still outstanding and states
560
+ `setCapacity({ count: 0 })` on every other usable provider, as **Forced breaks** sets out; no grant
561
+ is committed, because the agent has already stopped everywhere.
562
+
563
+ This is two-phase coordination across vendor systems: the approval phase keeps the agent working;
564
+ the durable commit decision and snapshot reconciliation provide convergence after partial delivery.
565
+
566
+ #### Reporting the break the agent is on
567
+
568
+ `BreakState.activeReasonId` is the `BreakReason.id` the current break is on. Omni remembers what it
569
+ asked for, but only until the session ends — after a reload or reconnect, or where the provider put
570
+ the agent on the break itself, the provider is the only one who knows.
571
+
572
+ Omit it when you cannot say, and when there is no break: reporting a reason alongside
573
+ `status: "not-requested"` describes a break that is not happening, and is rejected.
574
+
575
+ ### `cancelBreak()`
576
+
577
+ Cancels the active pre-commit request while its status is `awaiting-approval` or `granted`.
578
+ Cancellation releases the request but does not restore work because work never stopped. If
579
+ commit already won, the provider returns `omni.break-already-committed`. The resulting state is
580
+ reported through `break-state`.
581
+
582
+ ### `commitBreak()`
583
+
584
+ Commits the `granted` request. Once the provider has reported `granted`, it cannot fail for a
585
+ business reason. On commit the provider stops offering new work and reports
586
+ `starting-after-task` while existing work finishes, or `on-break` when the break is in effect.
587
+ Committing a break that is already in effect changes nothing and answers `committed`.
588
+
589
+ ### `endBreak()`
590
+
591
+ Tells a provider that an agent already on a break wants to become available again. The provider
592
+ reports the resulting state through `break-state` and provider status events.
593
+
594
+ It ends the break, which is the thing that started. Nothing about the connection was ever paused,
595
+ 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,8 +129,10 @@ 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. |
131
- | `{ 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
+ | `{ type: "force-break", memberId, reasonId?, reason?, durationSeconds? }` | Puts one member on a break they did not ask for, `scope: "agent"`. `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. With `durationSeconds`, the break publishes what is left as `endsInSeconds`, counted only while the member is signed in, and is lifted when it runs out; without it, it stands until a lead lifts it. |
133
+ | `{ type: "force-team-break", reasonId?, reason?, durationSeconds }` | Puts the whole team on a break, `scope: "team"`, members who sign in while it runs included. `durationSeconds` is required (`team.command.durationSeconds`): one end for everyone, which runs on while a member is signed out. The provider lifts it for all when it runs out. |
134
+ | `{ 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. It lifts a team break for this member alone. |
135
+ | `{ type: "end-team-break" }` | Lifts the team break for every member, as `end-forced-break` does for one. With no team break running it changes nothing. |
132
136
  | `{ type: "join", memberId, assignmentId? }` | Answers the member's request: the provider bridges the lead's channel into the call. See **Lead assist**. |
133
137
  | `{ type: "decline", memberId, assignmentId?, reason? }` | Refuses the member's request. |
134
138
  | `{ type: "listen", memberId, assignmentId? }` | The lead's channel joins the member's call unasked, in silence. See **Listening to a call**. |
@@ -161,14 +165,14 @@ flow, in order:
161
165
 
162
166
  ```ts
163
167
  // 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" } })
168
+ execute({ assignmentId: "asg-42", command: { type: "lead-assist", action: "request", note: "Refund dispute, needs approval" } })
165
169
  // task.leadAssist = { stage: "requested", note: "Refund dispute, needs approval", since }
166
170
 
167
171
  // 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 } }
172
+ // team-member-updated: member: { id: "A-1", ..., request: { assignmentId: "asg-42", note, since } }
169
173
 
170
174
  // 3. A lead joins, or declines.
171
- executeTeam({ command: { type: "join", memberId: "A-1", assignmentId: "alloc-42" } })
175
+ executeTeam({ command: { type: "join", memberId: "A-1", assignmentId: "asg-42" } })
172
176
  executeTeam({ command: { type: "decline", memberId: "A-1", reason: "In a call" } })
173
177
  ```
174
178
 
@@ -259,10 +263,10 @@ The flow, end to end:
259
263
  // 1. The lead, with the feature on, sees a member on-task with their tasks, and picks a call.
260
264
  // 2. The lead's channel joins it in silence. Conditions: the lead's voice channel is free --
261
265
  // 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" } })
266
+ executeTeam({ command: { type: "listen", memberId: "A-1", assignmentId: "asg-42" } })
263
267
  // 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
268
+ // listening: [{ leadId: "L-9", assignmentId: "asg-42", mode: "listen", since }]
269
+ // -- L-9's application opens openAudio({ assignmentId: "asg-42" }) on its own connection; every
266
270
  // other lead's shows L-9 on the call and opens nothing.
267
271
  // 4. The lead changes how they are heard; the member is published again with the entry's new mode. The audio stays open.
268
272
  // 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" }] };