@xema/omni-protocol 0.1.41 → 0.1.42

package/dist/index.d.ts

@@ -638,7 +638,9 @@ export interface TaskAssisting {
 /**
  * On the lead's own task while they listen to a member's call: whose call, which call, and how the
  * lead is heard, restated on every change of mode. Nothing of it reaches the member's task. There
- * is no take-over here; a lead who wants the call uses lead assist.
+ * is no take-over here; a lead who wants the call uses lead assist. It is the lead's only task:
+ * a lead listens while holding no work of their own, idle or on a break of a kind in
+ * `MONITORING_BREAK_KINDS`.
  */
 export interface TaskMonitoring {
     memberId: UserId;
@@ -927,6 +929,12 @@ export declare const BREAK_KINDS: readonly ["short-break", "meal", "rest", "trai
  * problem one level up. `other` matches nothing, including another provider's `other`.
  */
 export type BreakKind = (typeof BREAK_KINDS)[number];
+/**
+ * The breaks during which a lead may listen to a member's call: work of another sort, not rest.
+ * A monitoring task is the one task a break in effect may hold, and only on one of these.
+ */
+export declare const MONITORING_BREAK_KINDS: readonly ["coaching", "administrative", "training"];
+export declare const breakKindAllowsMonitoring: (kind: BreakKind | undefined) => boolean;
 export interface BreakReason {
     id: string;
     label: string;

package/dist/index.js

@@ -90,6 +90,12 @@ export const BREAK_KINDS = [
     "short-break", "meal", "rest", "training", "coaching",
     "meeting", "administrative", "technical", "personal", "other",
 ];
+/**
+ * The breaks during which a lead may listen to a member's call: work of another sort, not rest.
+ * A monitoring task is the one task a break in effect may hold, and only on one of these.
+ */
+export const MONITORING_BREAK_KINDS = ["coaching", "administrative", "training"];
+export const breakKindAllowsMonitoring = (kind) => kind !== undefined && MONITORING_BREAK_KINDS.includes(kind);
 export const OMNI_FAILURE_CODES = [
     "omni.not-authenticated",
     "omni.capability-not-enabled",

package/dist/validation.js

@@ -9,7 +9,7 @@
 // Each list is pinned to its type both ways -- a member the type lacks, or a member the list
 // lacks, fails to compile -- so what the validators accept cannot drift from what the
 // declarations say.
-import { ALLOWED_BROWSER_URL_SCHEMES, BREAK_KINDS, BROWSER_ISOLATION_SCHEMES, HANDLING_STEPS_THAT_DIAL, IDLE_CAPABILITIES, OMNI_FAILURE_CODES, OMNI_SUPPORTED_PROTOCOL_VERSIONS, negotiateProtocolVersion, DEFAULT_LEVELS, effectiveLevels, } from "./index.js";
+import { ALLOWED_BROWSER_URL_SCHEMES, BREAK_KINDS, MONITORING_BREAK_KINDS, BROWSER_ISOLATION_SCHEMES, HANDLING_STEPS_THAT_DIAL, IDLE_CAPABILITIES, OMNI_FAILURE_CODES, OMNI_SUPPORTED_PROTOCOL_VERSIONS, negotiateProtocolVersion, DEFAULT_LEVELS, effectiveLevels, } from "./index.js";
 export class ProtocolConformanceError extends Error {
     violations;
     constructor(violations, summary = "Adapter violates the Omni protocol") {
@@ -1188,11 +1188,31 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
             }
         });
     }
+    // A lead listens while holding no work of their own: a monitoring task is the only task.
+    if (Array.isArray(snapshot.tasks) && snapshot.tasks.length > 1) {
+        snapshot.tasks.forEach((task, index) => {
+            if (isPlainObject(task) && task.monitoring !== undefined) {
+                into.add("snapshot.monitoring.alone", `${path}.tasks[${index}].monitoring`, "a lead listens only while holding no task of their own");
+            }
+        });
+    }
     // A break in effect begins when the work ends, so it holds no task. A snapshot reporting both
-    // describes a state the agent cannot be in, whichever half is stale.
+    // describes a state the agent cannot be in, whichever half is stale. The one exception is a
+    // lead listening to a call during a break that is work of another sort -- coaching,
+    // administrative, training -- and on no other.
     if (isPlainObject(snapshot.break) && snapshot.break.approval === "in-effect"
         && Array.isArray(snapshot.tasks) && snapshot.tasks.length > 0) {
-        into.add("break.in-effect.tasks", `${path}.tasks`, "a break in effect holds no task: it begins when the work ends, and until then the state is starting-after-task");
+        const listening = snapshot.tasks.every((task) => isPlainObject(task) && task.monitoring !== undefined);
+        if (!listening) {
+            into.add("break.in-effect.tasks", `${path}.tasks`, "a break in effect holds no task: it begins when the work ends, and until then the state is starting-after-task");
+        }
+        else {
+            const state = snapshot.break;
+            const reasons = Array.isArray(state.reasons) ? state.reasons : [];
+            const active = reasons.find((reason) => isPlainObject(reason) && reason.id === state.activeReasonId);
+            const kind = isPlainObject(active) ? active.kind : undefined;
+            into.require(typeof kind === "string" && MONITORING_BREAK_KINDS.includes(kind), "snapshot.monitoring.break", `${path}.tasks`, `a lead listens during a ${MONITORING_BREAK_KINDS.join(", ")} break and no other; the active reason is ${kind === undefined ? "unstated" : String(kind)}`);
+        }
     }
     // Presence is the permission, and it cuts both ways: data a provider never declared a
     // capability for is data Omni would show against a control the agent does not have.

package/guide.md

@@ -2933,7 +2933,7 @@ rendering one as the other tells an agent to wait for somebody who is never comi
 | `awaiting-decision` | A person has to decide. The agent is waiting on somebody. |
 | `granted` | A person decided yes. Omni may now tell this provider to stop the agent; until it does, work continues normally, and this says nothing about why Omni has not. |
 | `starting-after-task` | Omni has told the provider to stop; the break begins when the current task ends. No new work arrives meanwhile, and nobody needs to act. |
-| `in-effect` | The agent is on the break now. It holds no task: a break begins when the work ends, so a snapshot reporting `in-effect` beside a task is refused as `break.in-effect.tasks`. |
+| `in-effect` | The agent is on the break now. It holds no task: a break begins when the work ends, so a snapshot reporting `in-effect` beside a task is refused as `break.in-effect.tasks`. The one exception is a lead's monitoring task during a `coaching`, `administrative` or `training` break -- see **Monitoring a call**. |
 
 A denial is a decision, not a standing approval state. The provider transitions the request directly
 to `not-requested`; Omni returns the agent to idle and never asks again on their behalf. They saw the
@@ -3465,10 +3465,19 @@ executeTeamMonitor({ command: { type: "leave" } })
 provider bridges the lead's leg into the member's call in the mode stated. `monitoring.mode` is
 the state, restated on every change, and a `whisper` or `barge` the login's list does not include
 is answered `failed`. **A lead listens to one call at a time** (`snapshot.monitoring.single`), and
-a task is a joined call or a monitored one, never both (`task.monitoring.assisting`). A lead on a
-break does not listen, for the reason they do not join: a break is a state in which the agent is
-not working. The member's call ending ends the lead's task as it ends the member's, with `left`,
-since the lead was never handling it.
+a task is a joined call or a monitored one, never both (`task.monitoring.assisting`). The member's
+call ending ends the lead's task as it ends the member's, with `left`, since the lead was never
+handling it.
+
+**A lead listens only while holding no work of their own.** A monitoring task is the lead's only
+task, and a snapshot carrying one beside any other is refused (`snapshot.monitoring.alone`); Omni
+offers Monitor to a lead with no task. That includes a lead on a break -- unlike joining, which a
+break forbids -- but only a break that is work of another sort: `coaching`, `administrative` or
+`training`, the kinds in `MONITORING_BREAK_KINDS`, and never a meal or a rest. A break in effect
+otherwise holds no task; the monitoring task is its one exception, and a snapshot carrying one
+during a break whose active reason is of any other kind, or of no stated kind, is refused
+(`snapshot.monitoring.break`). The kind decides, not the reason's name: a centre that wants leads
+listening during a break declares that break `coaching`, `administrative` or `training`.
 
 **Nothing reaches the member.** The member's task carries no trace of a monitoring lead in any
 mode: not on `onCall`, not in the record. Whether a whisper is announced to the agent is the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xema/omni-protocol",
-  "version": "0.1.41",
+  "version": "0.1.42",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",