@xema/omni-protocol 0.1.137 → 0.1.138
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/dist/index.d.ts +6 -0
- package/dist/validation.js +7 -0
- package/guide/breaks.md +11 -1
- package/guide/lead.md +1 -1
- package/guide.md +1 -0
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -1404,6 +1404,12 @@ export interface BreakReason {
|
|
|
1404
1404
|
kind?: BreakKind;
|
|
1405
1405
|
/** Survives `canRequestBreak: false`: a mandatory rest is not something a busy hour can cancel. */
|
|
1406
1406
|
alwaysAvailable?: true;
|
|
1407
|
+
/**
|
|
1408
|
+
* The platform's own: a break the provider puts the agent on itself, such as a phone that will
|
|
1409
|
+
* not register. Nobody asks for it or forces it, so neither the agent nor a lead is offered it; it
|
|
1410
|
+
* names a break the provider forced, `forced.by: "provider"`.
|
|
1411
|
+
*/
|
|
1412
|
+
providerOnly?: true;
|
|
1407
1413
|
}
|
|
1408
1414
|
export interface BreakRequest {
|
|
1409
1415
|
/** Optional explanatory text. Omit when no explanation is needed; separate from reasonId. */
|
package/dist/validation.js
CHANGED
|
@@ -1570,6 +1570,7 @@ export function validateTeamCommand(request, context, path = "teamCommand") {
|
|
|
1570
1570
|
if (command.type === "force-break") {
|
|
1571
1571
|
const reasons = Array.isArray(state.reasons) ? state.reasons : [];
|
|
1572
1572
|
into.require(state.reasons === undefined ? command.reasonId === undefined : reasons.some((r) => isPlainObject(r) && r.id === command.reasonId), "team.command.reasonId", path, "force-break uses the target's currently published reason codes");
|
|
1573
|
+
into.require(!reasons.some((r) => isPlainObject(r) && r.id === command.reasonId && r.providerOnly === true), "team.command.reasonId.providerOnly", path, "this reason is the provider's own: the platform puts a member on it, and a lead does not");
|
|
1573
1574
|
}
|
|
1574
1575
|
}
|
|
1575
1576
|
else if (command.type === "join" || command.type === "decline") {
|
|
@@ -1623,6 +1624,7 @@ export function validateBreakCommand(method, request, state, context, path = "br
|
|
|
1623
1624
|
into.require(selected !== undefined, "break.request.reasonId", path, "choose a currently published reasonId; free text is not a substitute");
|
|
1624
1625
|
else
|
|
1625
1626
|
into.require(request.reasonId === undefined, "break.request.reasonId.unexpected", path, "no reason codes were published");
|
|
1627
|
+
into.require(!(isPlainObject(selected) && selected.providerOnly === true), "break.request.reasonId.providerOnly", path, "this reason is the provider's own: it puts the agent on it, and nobody asks for it");
|
|
1626
1628
|
into.require(state.canRequestBreak === true || (isPlainObject(selected) && selected.alwaysAvailable === true), "break.request.canRequestBreak", path, "asking is disabled except for the selected alwaysAvailable reason");
|
|
1627
1629
|
}
|
|
1628
1630
|
else {
|
|
@@ -1734,6 +1736,11 @@ function validateBreakState(value, path, into) {
|
|
|
1734
1736
|
if (reason.alwaysAvailable !== undefined) {
|
|
1735
1737
|
into.require(reason.alwaysAvailable === true, "break.reason.alwaysAvailable", `${at}.alwaysAvailable`, "alwaysAvailable is declared by presence: send true or omit it");
|
|
1736
1738
|
}
|
|
1739
|
+
if (reason.providerOnly !== undefined) {
|
|
1740
|
+
into.require(reason.providerOnly === true, "break.reason.providerOnly", `${at}.providerOnly`, "providerOnly is declared by presence: send true or omit it");
|
|
1741
|
+
// Nobody may ask for the provider's own reason, so nothing can keep it on offer.
|
|
1742
|
+
into.require(reason.alwaysAvailable === undefined, "break.reason.providerOnly.alwaysAvailable", `${at}.alwaysAvailable`, "a providerOnly reason is offered to nobody, so it cannot be alwaysAvailable");
|
|
1743
|
+
}
|
|
1737
1744
|
});
|
|
1738
1745
|
// The active reason is one of the published ones, or it is a reason Omni cannot name.
|
|
1739
1746
|
if (typeof value.activeReasonId === "string" && value.activeReasonId.length > 0) {
|
package/guide/breaks.md
CHANGED
|
@@ -44,6 +44,14 @@ it; it sends the commit again only from a reconnect snapshot that shows the gran
|
|
|
44
44
|
refused. A `BreakReason` marked `alwaysAvailable` survives it: a mandatory rest period is not
|
|
45
45
|
something a busy hour can cancel, and Omni keeps offering those while the rest are withdrawn.
|
|
46
46
|
|
|
47
|
+
**The provider's own reasons are offered to nobody.** A break the platform puts the agent on
|
|
48
|
+
itself -- a phone that will not register, a station still being set up -- still needs a reason,
|
|
49
|
+
since `activeReasonId` names every break where reasons are published. Mark it `providerOnly`. Omni
|
|
50
|
+
leaves it out of the agent's choices and out of a lead's `force-break`, and a request or a
|
|
51
|
+
`force-break` naming it is refused (`break.request.reasonId.providerOnly`,
|
|
52
|
+
`team.command.reasonId.providerOnly`). It is never `alwaysAvailable`
|
|
53
|
+
(`break.reason.providerOnly.alwaysAvailable`).
|
|
54
|
+
|
|
47
55
|
### Forced breaks
|
|
48
56
|
|
|
49
57
|
Migration: the former awaiting-decision value is now `awaiting-approval` in break status
|
|
@@ -134,6 +142,7 @@ a display name.
|
|
|
134
142
|
break in progress or about to be; beside `granted` or `awaiting-approval` the agent application would read a
|
|
135
143
|
request the agent never made and commit it (`break.forced.status`). Where the provider publishes
|
|
136
144
|
`reasons`, the lead's `force-break` named one, and the member's state carries it as `activeReasonId`.
|
|
145
|
+
A break the platform forced itself names one of its `providerOnly` reasons.
|
|
137
146
|
|
|
138
147
|
For example:
|
|
139
148
|
|
|
@@ -314,7 +323,7 @@ request object only to the request method, and undefined to the other three.
|
|
|
314
323
|
|
|
315
324
|
| Method | Required current state |
|
|
316
325
|
| --- | --- |
|
|
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. |
|
|
326
|
+
| `requestBreak` | `not-requested`; selected current reason code when codes exist, never a `providerOnly` one; `canRequestBreak` or the selected reason's `alwaysAvailable` exception. Free text does not replace a code. |
|
|
318
327
|
| `commitBreak` | `granted`, or already committed for an idempotent repeat. A later change to `canRequestBreak` does not revoke the grant. |
|
|
319
328
|
| `cancelBreak` | `awaiting-approval` or `granted`. A concurrent commit winning still answers `omni.break-already-committed` and requires recovery. |
|
|
320
329
|
| `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. |
|
|
@@ -397,6 +406,7 @@ break: {
|
|
|
397
406
|
reasons: [
|
|
398
407
|
{ id: "lunch", label: "Lunch", kind: "meal" },
|
|
399
408
|
{ id: "rest", label: "Mandatory rest period", kind: "rest", alwaysAvailable: true },
|
|
409
|
+
{ id: "no-phone", label: "No phone", kind: "technical", providerOnly: true },
|
|
400
410
|
]
|
|
401
411
|
}
|
|
402
412
|
```
|
package/guide/lead.md
CHANGED
|
@@ -129,7 +129,7 @@ assignment from the member alone.
|
|
|
129
129
|
| `{ type: "lead-features", enabled }` | The team feature on or off. See **The lead switches the feature on and off** above. |
|
|
130
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`. |
|
|
131
131
|
| `{ type: "set-break-policy", policy }` | `approval-required`, `automatically-approved`, or `requests-suspended`. |
|
|
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. |
|
|
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`, never a `providerOnly` one, 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
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
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
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. |
|
package/guide.md
CHANGED