@xema/omni-protocol 0.1.136 → 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 CHANGED
@@ -812,6 +812,10 @@ export interface OutcomeCode {
812
812
  group?: string;
813
813
  }
814
814
  export interface OutcomeRules {
815
+ /**
816
+ * The agent's `complete` carries a code. A person's close chooses an outcome; only the provider's
817
+ * own close, when a `provider-automatic` wrap runs out, may carry none.
818
+ */
815
819
  required?: boolean;
816
820
  notes?: "required" | "optional" | "none";
817
821
  codes?: OutcomeCode[];
@@ -1400,6 +1404,12 @@ export interface BreakReason {
1400
1404
  kind?: BreakKind;
1401
1405
  /** Survives `canRequestBreak: false`: a mandatory rest is not something a busy hour can cancel. */
1402
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;
1403
1413
  }
1404
1414
  export interface BreakRequest {
1405
1415
  /** Optional explanatory text. Omit when no explanation is needed; separate from reasonId. */
@@ -1374,11 +1374,6 @@ function validateTaskInto(task, context, path, into) {
1374
1374
  if (capabilities.browsers === true && Array.isArray(task.browsers) && task.browsers.length === 0) {
1375
1375
  into.add("task.browsers.required", `${path}.browsers`, "a task that declares capabilities.browsers supplies at least one; with none, omit the capability");
1376
1376
  }
1377
- // An outcome is given in wrap, by the agent: a provider that completes the task itself cannot
1378
- // wait for one, and a task with no wrap has nowhere to take one.
1379
- if (isPlainObject(capabilities.outcomes) && capabilities.outcomes.required === true) {
1380
- into.require(task.completionMode !== "provider-automatic", "task.outcomes.required.mode", `${path}.capabilities.outcomes.required`, "a required outcome is the agent's to give, so the task completes on the agent's command; provider-automatic completion cannot wait for it");
1381
- }
1382
1377
  // Under agent-command the allowance is the expected wrap, shown and never acted on: the agent
1383
1378
  // completes whenever they are done, so there is always a wrap to collect the code in.
1384
1379
  if (capabilities.outcomes !== undefined) {
@@ -1575,6 +1570,7 @@ export function validateTeamCommand(request, context, path = "teamCommand") {
1575
1570
  if (command.type === "force-break") {
1576
1571
  const reasons = Array.isArray(state.reasons) ? state.reasons : [];
1577
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");
1578
1574
  }
1579
1575
  }
1580
1576
  else if (command.type === "join" || command.type === "decline") {
@@ -1628,6 +1624,7 @@ export function validateBreakCommand(method, request, state, context, path = "br
1628
1624
  into.require(selected !== undefined, "break.request.reasonId", path, "choose a currently published reasonId; free text is not a substitute");
1629
1625
  else
1630
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");
1631
1628
  into.require(state.canRequestBreak === true || (isPlainObject(selected) && selected.alwaysAvailable === true), "break.request.canRequestBreak", path, "asking is disabled except for the selected alwaysAvailable reason");
1632
1629
  }
1633
1630
  else {
@@ -1739,6 +1736,11 @@ function validateBreakState(value, path, into) {
1739
1736
  if (reason.alwaysAvailable !== undefined) {
1740
1737
  into.require(reason.alwaysAvailable === true, "break.reason.alwaysAvailable", `${at}.alwaysAvailable`, "alwaysAvailable is declared by presence: send true or omit it");
1741
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
+ }
1742
1744
  });
1743
1745
  // The active reason is one of the published ones, or it is a reason Omni cannot name.
1744
1746
  if (typeof value.activeReasonId === "string" && value.activeReasonId.length > 0) {
package/guide/agent.md CHANGED
@@ -164,7 +164,7 @@ time. Runtime conformance checks also require the task channel to match its prov
164
164
  | `previewEndsInSeconds` | Voice only, in `preview`: how long the preparation has left, in whole seconds from this publication, restated on every publication that carries it. Absent, the agent has as long as they need without a preparation countdown. Always with `atDeadline`. See **Preview: the agent presses Call** in `guide/voice.md`. |
165
165
  | `atDeadline` | Voice only, in `preview`, with `previewEndsInSeconds`: what the system does when it runs out -- `provider-dials` makes the provider initiate dialing, `host-dials` makes the agent application issue Call, `waits` keeps the task in preview awaiting the agent. |
166
166
  | `reference` | Optional agent-facing reference such as a case, call, conversation, ticket, or message number. It is distinct from the protocol `id`. |
167
- | `completionMode` | `agent-command` waits for the channel's `complete` command; `provider-automatic` completes without one, and takes the agent's `complete` as finishing early. A required outcome is the agent's to give, so it needs `agent-command` (`task.outcomes.required.mode`). |
167
+ | `completionMode` | `agent-command` waits for the channel's `complete` command; `provider-automatic` completes without one, and takes the agent's `complete` as finishing early. A required outcome binds the agent's `complete` under either mode. |
168
168
  | `wrapAllowance` | Fixed time allowed to complete the task after primary interaction ends. For real-time audio, it begins after `task-audio-ended`. Required under `provider-automatic`, where the provider acts on it. Optional under `agent-command`: omitted says the provider imposes no deadline, and Omni counts nothing down; stated, it is the expected wrap, shown and never acted on. `0` under `provider-automatic` is no wrap at all, so such a task publishes no `outcomes` (`task.outcomes.wrapAllowance`). |
169
169
  | `wrapEndsInSeconds` | In `completing`, wherever `wrapAllowance` is stated: how much of the wrap is left, in whole seconds from this publication, restated on every publication that carries it (`task.completing.wrapEndsInSeconds`, `.required`, `.unexpected`). A reloaded agent computer and a lead's screen count down the same number. See **Completion timing**. |
170
170
  | `attributes` | Optional ordered, typed `TaskAttribute` entries with keys unique within the task. Each contact or timestamp is a separate array item; new attribute shapes require new union members. |
@@ -254,10 +254,17 @@ with no wrap at all -- `provider-automatic` with `wrapAllowance: 0` -- has nothi
254
254
  the command is refused there (`command.complete.wrapAllowance`). An ending the agent asked for says
255
255
  so, `completed` with `by: "agent"`, whichever mode the task was under.
256
256
 
257
- **A required outcome is the agent's to give.** A task whose `outcomes` says `required: true` waits
258
- for a code the agent chooses, so it completes on the agent's command: `provider-automatic` cannot
259
- wait for it, and the pair is refused (`task.outcomes.required.mode`). Optional outcomes may ride on
260
- a task the provider completes itself; the agent gives one if in time. And a code is given in wrap,
257
+ Migration: a required outcome under `provider-automatic` is no longer refused; the former
258
+ `task.outcomes.required.mode` rule is gone.
259
+
260
+ **A required outcome binds the agent's close.** `required: true` says the agent's `complete`
261
+ carries a code from the list (`command.complete.outcome.required`): a person who closes the task
262
+ chooses how it went. It says nothing about the provider's own close. Under `agent-command` the
263
+ task waits for the agent, so every close carries a code. Under `provider-automatic` the agent may
264
+ still close early, with a code, and when the wrap runs out the provider closes it with none, since
265
+ nobody chose one. The agent computer reads `required` and asks for a code before it sends
266
+ `complete`, so the agent is never told one is needed only after pressing it. Optional outcomes
267
+ ride on either mode; the agent gives one if they want to. And a code is given in wrap,
261
268
  so a `provider-automatic` task with `wrapAllowance: 0` publishes no `outcomes` at all
262
269
  (`task.outcomes.wrapAllowance`).
263
270
 
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
@@ -1019,6 +1019,7 @@ type BreakReason = {
1019
1019
  group?: string;
1020
1020
  kind?: BreakKind;
1021
1021
  alwaysAvailable?: true;
1022
+ providerOnly?: true;
1022
1023
  };
1023
1024
 
1024
1025
  type BreakRequest = {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xema/omni-protocol",
3
- "version": "0.1.136",
3
+ "version": "0.1.138",
4
4
  "description": "The Omni protocol: the contract every provider adapter implements",
5
5
  "type": "module",
6
6
  "license": "MIT",