@xema/omni-protocol 0.1.40 → 0.1.42

package/dist/index.d.ts

@@ -175,9 +175,21 @@ export interface TeamCapabilities {
     breakControl?: true;
     /** This lead may join a member's call on request. Requires `executeTeamLeadAssist`. */
     leadAssistControl?: true;
+    /**
+     * This lead may listen to a member's call unasked, in these modes and no others. Whisper and
+     * barge begin from a monitor, so the list always includes `monitor`. Nothing of it reaches the
+     * member's task. Requires `executeTeamMonitor`.
+     */
+    monitorControl?: MonitorMode[];
     /** This lead sets the team's policy per capability -- on, off, or the agent's -- within what the queue allows. Requires `executeTeamPolicy`. */
     policyControl?: true;
 }
+/**
+ * How a lead listening to a member's call is heard: `monitor` hears both sides in silence,
+ * `whisper` is heard by the agent alone, `barge` by everyone on the call.
+ */
+export type MonitorMode = "monitor" | "whisper" | "barge";
+export declare const MONITOR_MODES: readonly ["monitor", "whisper", "barge"];
 /**
  * What this login may do, beyond any one task. It travels with the identity because it is part
  * of who the agent is on this provider: the provider knows the roles and says so at sign-in.
@@ -623,6 +635,19 @@ export interface TaskAssisting {
     note?: string;
     since: IsoTimestamp;
 }
+/**
+ * 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. 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;
+    taskId: TaskId;
+    mode: MonitorMode;
+    since: IsoTimestamp;
+}
 /**
  * A level of the organisation's structure, by the id its manifest declares -- or one of the four
  * a typical organisation has, `DEFAULT_LEVELS`, when the manifest declares no ladder. The protocol
@@ -693,11 +718,13 @@ export type Task<C extends Channel = Channel> = {
     onCall?: OnCall[];
     leadAssist?: TaskLeadAssist;
     assisting?: TaskAssisting;
+    monitoring?: TaskMonitoring;
     media?: TaskMediaState;
 } : {
     onCall?: never;
     leadAssist?: never;
     assisting?: never;
+    monitoring?: never;
     media?: never;
 });
 /**
@@ -902,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;
@@ -1032,6 +1065,24 @@ export type TeamLeadAssistCommand = {
 export interface TeamLeadAssistCommandRequest {
     command: TeamLeadAssistCommand;
 }
+/**
+ * A lead listening to a member's call. `monitor` starts one, silent, on a member from the roster;
+ * `whisper` and `barge` change how the standing one is heard; `leave` ends it. One member at a
+ * time, and only the modes the login's `monitorControl` lists.
+ */
+export type TeamMonitorCommand = {
+    type: "monitor";
+    memberId: UserId;
+} | {
+    type: "whisper";
+} | {
+    type: "barge";
+} | {
+    type: "leave";
+};
+export interface TeamMonitorCommandRequest {
+    command: TeamMonitorCommand;
+}
 export type TeamBreakCommand = {
     type: "decide";
     memberId: UserId;
@@ -1296,6 +1347,8 @@ export interface Connection<C extends Channel = Channel> {
     executeTeamBreak?(request: TeamBreakCommandRequest): Promise<TeamCommandResult>;
     /** Required when the login declares `capabilities.team.leadAssistControl`. */
     executeTeamLeadAssist?(request: TeamLeadAssistCommandRequest): Promise<TeamCommandResult>;
+    /** Required when the login declares `capabilities.team.monitorControl`. */
+    executeTeamMonitor?(request: TeamMonitorCommandRequest): Promise<TeamCommandResult>;
     /** Required when the login declares `capabilities.team.policyControl`. */
     executeTeamPolicy?(request: TeamPolicyCommandRequest): Promise<TeamCommandResult>;
     /** Required of every voice adapter: all voice audio lands in Omni. */

package/dist/index.js

@@ -25,6 +25,7 @@ export const IDLE_CAPABILITY_UI = {
     calendar: "Calendar",
     contacts: "Contacts",
 };
+export const MONITOR_MODES = ["monitor", "whisper", "barge"];
 // ---------------------------------------------------------------------------
 // Task workspace.
 // ---------------------------------------------------------------------------
@@ -89,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",
@@ -167,10 +174,12 @@ export function handlingStepExpectsAPerson(step) {
  * not the thing being compared. Key order does not matter, and `team: {}` is not `team` absent.
  */
 export function sameCapabilities(a, b) {
+    const modes = (team) => team?.monitorControl === undefined ? undefined : [...team.monitorControl].sort().join(",");
     return a.breaks === b.breaks &&
         (a.team === undefined) === (b.team === undefined) &&
         a.team?.breakControl === b.team?.breakControl &&
-        a.team?.leadAssistControl === b.team?.leadAssistControl;
+        a.team?.leadAssistControl === b.team?.leadAssistControl &&
+        modes(a.team) === modes(b.team);
 }
 /**
  * The storage-profile key a reusing browser shares, or `undefined` where it shares nothing.

package/dist/testing.d.ts

@@ -7,7 +7,7 @@ export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation }
  * rules -- each optional part of a task, each optional part of the break state and roster, each
  * declared contribution, and each event type.
  */
-declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.handlingHistory", "task.onCall", "task.leadAssist", "task.assisting", "task.media", "task.acceptance", "task.dispositions", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.imposed", "team.members", "team.requests", "contacts", "scheduledActivities", "team.policies"];
+declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.handlingHistory", "task.onCall", "task.leadAssist", "task.assisting", "task.monitoring", "task.media", "task.acceptance", "task.dispositions", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.imposed", "team.members", "team.requests", "contacts", "scheduledActivities", "team.policies"];
 export type ContractSubject = (typeof STATE_SUBJECTS)[number] | `event.${ProviderEvent["type"]}`;
 export interface AdapterContractResult {
     events: ProviderEventEnvelope[];

package/dist/testing.js

@@ -15,6 +15,7 @@ const STATE_SUBJECTS = [
     "task.onCall",
     "task.leadAssist",
     "task.assisting",
+    "task.monitoring",
     "task.media",
     "task.acceptance",
     "task.dispositions",
@@ -60,6 +61,8 @@ function observeTask(value, seen) {
         seen.add("task.leadAssist");
     if (value.assisting !== undefined)
         seen.add("task.assisting");
+    if (value.monitoring !== undefined)
+        seen.add("task.monitoring");
     if (value.media !== undefined)
         seen.add("task.media");
     if (value.acceptance !== undefined)
@@ -225,6 +228,8 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                 requireMethod(on, "executeTeamBreak", "the login declares capabilities.team.breakControl");
             if (capabilities.team?.leadAssistControl === true)
                 requireMethod(on, "executeTeamLeadAssist", "the login declares capabilities.team.leadAssistControl");
+            if (capabilities.team?.monitorControl !== undefined)
+                requireMethod(on, "executeTeamMonitor", "the login declares capabilities.team.monitorControl");
             if (capabilities.team?.policyControl === true)
                 requireMethod(on, "executeTeamPolicy", "the login declares capabilities.team.policyControl");
             if (some(capabilities.preferences))
@@ -405,7 +410,8 @@ function publishesUserIds(snapshot) {
 const teamNamesUsers = (team) => isRecord(team) && (some(team.members) || some(team.requests));
 const taskNamesUsers = (task) => isRecord(task) && ((isRecord(task.handlingHistory) && Array.isArray(task.handlingHistory.steps) && task.handlingHistory.steps.some(step => isRecord(step) && step.by !== undefined)) ||
     (isRecord(task.leadAssist) && task.leadAssist.leadId !== undefined) ||
-    isRecord(task.assisting));
+    isRecord(task.assisting) ||
+    isRecord(task.monitoring));
 /** Mute is the leg the host performs, so a task that allows it obliges the provider to take the record. */
 const taskDeclaresMute = (task) => isRecord(task) && isRecord(task.capabilities) && task.capabilities.mute !== undefined;
 function eventDeclaresMute(envelope) {
@@ -517,7 +523,8 @@ export function assertCapabilityWithdrawal(states, snapshot, manifest) {
     const withdrawn = (before.breaks === true && after.breaks !== true) ||
         (before.team !== undefined && after.team === undefined) ||
         (before.team?.breakControl === true && after.team?.breakControl !== true) ||
-        (before.team?.leadAssistControl === true && after.team?.leadAssistControl !== true);
+        (before.team?.leadAssistControl === true && after.team?.leadAssistControl !== true) ||
+        (before.team?.monitorControl !== undefined && after.team?.monitorControl === undefined);
     if (!withdrawn) {
         throw new Error("Capability withdrawal must end with at least one capability the first login declared withdrawn");
     }

package/dist/validation.d.ts

@@ -59,7 +59,7 @@ export declare function validateHostGuarantees(guarantees: unknown, path?: strin
 export declare function validateHandlingReport(report: unknown, path?: string, manifest?: unknown): ProtocolViolation[];
 export declare function validateHostReport(report: unknown, path?: string): ProtocolViolation[];
 /** The connection methods whose results `validateResult` knows. */
-export type ResultMethod = "execute" | "dial" | "setCapacity" | "requestBreak" | "commitBreak" | "cancelBreak" | "endBreak" | "executeTeamBreak" | "executeTeamLeadAssist" | "openMedia" | "setPreference" | "recordStep" | "executeTeamPolicy";
+export type ResultMethod = "execute" | "dial" | "setCapacity" | "requestBreak" | "commitBreak" | "cancelBreak" | "endBreak" | "executeTeamBreak" | "executeTeamLeadAssist" | "executeTeamMonitor" | "openMedia" | "setPreference" | "recordStep" | "executeTeamPolicy";
 /**
  * Validates what a connection method answered. A result is untrusted for the same reason a
  * snapshot is: it comes from an adapter that may be compiled against another version, and Omni

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") {
@@ -84,7 +84,8 @@ const MEMBER_BREAKS = membersOf({
 const OFFERABLE_PHASES = membersOf({
     pending: true, confirmed: true, preparing: true,
 });
-const TEAM_CAPABILITIES = membersOf({ breakControl: true, leadAssistControl: true, policyControl: true });
+const TEAM_CAPABILITIES = membersOf({ breakControl: true, leadAssistControl: true, policyControl: true, monitorControl: true });
+const MONITOR_MODES = membersOf({ monitor: true, whisper: true, barge: true });
 const COMPLETED_BY = membersOf({ agent: true, provider: true });
 const EXPIRABLE_PHASES = membersOf({
     pending: true, confirmed: true, preparing: true,
@@ -835,6 +836,21 @@ function validateAssisting(value, channel, path, into) {
         into.filled(value.note, "task.assisting.note", `${path}.note`, "a note must not be empty when present");
     into.timestamp(value.since, "task.assisting.since", `${path}.since`);
 }
+/** The lead's own task while they listen: whose call, which call, and how they are heard. Voice only. */
+function validateMonitoring(value, channel, path, into) {
+    if (value === undefined)
+        return;
+    if (!into.require(channel === "voice", "task.monitoring.channel", path, `a ${channel} task has no call to listen to`))
+        return;
+    if (!isPlainObject(value)) {
+        into.add("task.monitoring.shape", path, "monitoring must be an object when present");
+        return;
+    }
+    into.require(isUserId(value.memberId), "task.monitoring.memberId", `${path}.memberId`, "a monitored call names the member on it");
+    into.require(isTaskId(value.taskId), "task.monitoring.taskId", `${path}.taskId`, "a monitored call names the member's task");
+    into.oneOf(value.mode, MONITOR_MODES, "task.monitoring.mode", `${path}.mode`);
+    into.timestamp(value.since, "task.monitoring.since", `${path}.since`);
+}
 export function validateTask(task, context, path = "task") {
     const into = new Collector();
     validateTaskInto(task, context, path, into);
@@ -888,6 +904,11 @@ function validateTaskInto(task, context, path, into) {
     validateTaskMedia(task.media, context.channel, `${path}.media`, into);
     validateLeadAssist(task.leadAssist, context.channel, `${path}.leadAssist`, into);
     validateAssisting(task.assisting, context.channel, `${path}.assisting`, into);
+    validateMonitoring(task.monitoring, context.channel, `${path}.monitoring`, into);
+    // A lead's task is one thing: a call they joined on request, or a call they listen to unasked.
+    if (task.assisting !== undefined && task.monitoring !== undefined) {
+        into.add("task.monitoring.assisting", `${path}.monitoring`, "a task is a joined call or a monitored one, never both");
+    }
     const capabilities = task.capabilities;
     if (!isPlainObject(capabilities)) {
         into.add("task.capabilities.shape", `${path}.capabilities`, "a task needs a capabilities object");
@@ -1146,14 +1167,20 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
     else {
         const seen = new Set();
         let assisting;
+        let monitoring;
         snapshot.tasks.forEach((task, index) => {
             validateTaskInto(task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest) }, `${path}.tasks[${index}]`, into);
-            // A lead assists one call at a time.
+            // A lead assists one call at a time, and listens to one at a time.
             if (isPlainObject(task) && task.assisting !== undefined) {
                 if (assisting !== undefined)
                     into.add("snapshot.assisting.single", `${path}.tasks[${index}].assisting`, "a lead assists one call at a time");
                 assisting = index;
             }
+            if (isPlainObject(task) && task.monitoring !== undefined) {
+                if (monitoring !== undefined)
+                    into.add("snapshot.monitoring.single", `${path}.tasks[${index}].monitoring`, "a lead listens to one call at a time");
+                monitoring = index;
+            }
             if (isPlainObject(task) && isTaskId(task.id)) {
                 if (seen.has(task.id))
                     into.add("task.id.unique", `${path}.tasks[${index}].id`, `duplicate task id: ${task.id}`);
@@ -1161,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.
@@ -1622,6 +1669,7 @@ const RESULT_STATUSES = {
     endBreak: { success: "ended", failure: "failed" },
     executeTeamBreak: { success: "applied", failure: "failed" },
     executeTeamLeadAssist: { success: "applied", failure: "failed" },
+    executeTeamMonitor: { success: "applied", failure: "failed" },
     openMedia: { success: "opened", failure: "unavailable" },
     setPreference: { success: "applied", failure: "failed" },
     recordStep: { success: "recorded", failure: "failed" },
@@ -1708,6 +1756,10 @@ function validateUserCapabilitiesInto(value, path, into, levels) {
                     continue;
                 if (!into.require(TEAM_CAPABILITIES.includes(control), "authentication.capability.team.unknown", `${path}.team.${control}`, `unsupported team capability: ${control}`))
                     continue;
+                if (control === "monitorControl") {
+                    validateMonitorControl(on, `${path}.team.monitorControl`, into);
+                    continue;
+                }
                 into.require(on === true, "authentication.capability.value", `${path}.team.${control}`, `${control} is declared by presence: send true or omit it`);
             }
             continue;
@@ -1715,6 +1767,22 @@ function validateUserCapabilitiesInto(value, path, into, levels) {
         into.require(declared === true, "authentication.capability.value", `${path}.${name}`, `${name} is declared by presence: send true or omit it`);
     }
 }
+/**
+ * The modes a lead may listen in, as a list: whisper and barge begin from a monitor, so a list
+ * without `monitor` names modes the lead could never reach.
+ */
+function validateMonitorControl(value, path, into) {
+    if (!Array.isArray(value) || value.length === 0) {
+        into.add("authentication.capability.team.monitorControl.shape", path, "monitorControl lists the modes this lead may listen in: a non-empty array, or omitted for a lead who may not");
+        return;
+    }
+    value.forEach((mode, index) => {
+        if (into.oneOf(mode, MONITOR_MODES, "authentication.capability.team.monitorControl.mode", `${path}[${index}]`) && value.indexOf(mode) !== index) {
+            into.add("authentication.capability.team.monitorControl.unique", `${path}[${index}]`, `duplicate monitor mode: ${String(mode)}`);
+        }
+    });
+    into.require(value.includes("monitor"), "authentication.capability.team.monitorControl.monitor", path, "whisper and barge begin from a monitor: a lead who may listen in any mode may monitor");
+}
 export function validateAuthenticationState(state, path = "authentication", context = {}) {
     const into = new Collector();
     if (!isPlainObject(state)) {

package/guide.md

@@ -36,6 +36,7 @@ are used precisely throughout and mean nothing looser here.
 | **Break** | A reported, supervised state in which the agent is not working — one with a reason, a decision behind it and a return. It covers what a platform may call *not-ready*, including equipment trouble. An agent who is merely at capacity is not on a break. |
 | **Workspace** | What Omni shows the agent. The **task workspace** holds the selected task, its controls and its browsers; the **idle workspace** holds what a provider contributes when no task is selected — dialpad, contacts, calendar, roster. |
 | **Dial** | One outbound call the host asks a provider to place — from the idle dialpad, a transfer, a conference add, or a connect-back. Identified by the host's `dialId`, accepted as `dialling`, and ended by exactly one `dial-outcome`. See **Every dial has an outcome**. |
+| **Monitor** | A lead listening to a member's call unasked, from the roster: `monitor` in silence, `whisper` heard by the agent alone, `barge` heard by everyone. Nothing of it reaches the member's task, and there is no take-over in it. See **Monitoring a call**. |
 | **On the call** | Who a voice task's audio joins, or is bringing in, as the provider states it on `Task.onCall`: the party, the agents, and anyone consulted or conferenced in from the moment their dial is placed. |
 
 Six words describe *what state a thing is in*, and they are not interchangeable: each belongs to
@@ -229,9 +230,12 @@ type AuthenticationContext = {
   log?: (entry: unknown) => void;
 };
 
+type MonitorMode = "monitor" | "whisper" | "barge";
+
 type TeamCapabilities = {
   breakControl?: true;
   leadAssistControl?: true;
+  monitorControl?: MonitorMode[];
   policyControl?: true;
 };
 
@@ -610,6 +614,13 @@ type TaskAssisting = {
   since: IsoTimestamp;
 };
 
+type TaskMonitoring = {
+  memberId: UserId;
+  taskId: TaskId;
+  mode: MonitorMode;
+  since: IsoTimestamp;
+};
+
 type Level = string;
 
 type LevelDeclaration = {
@@ -641,8 +652,8 @@ type Task<C extends Channel = Channel> = {
   handlingHistory?: TaskHandlingHistory;
 } & TaskCompletion & (
   C extends "voice"
-    ? { onCall?: OnCall[]; leadAssist?: TaskLeadAssist; assisting?: TaskAssisting; media?: TaskMediaState }
-    : { onCall?: never; leadAssist?: never; assisting?: never; media?: never }
+    ? { onCall?: OnCall[]; leadAssist?: TaskLeadAssist; assisting?: TaskAssisting; monitoring?: TaskMonitoring; media?: TaskMediaState }
+    : { onCall?: never; leadAssist?: never; assisting?: never; monitoring?: never; media?: never }
 );
 
 type AcceptanceMode =
@@ -928,6 +939,16 @@ type TeamLeadAssistCommandRequest = {
   command: TeamLeadAssistCommand;
 };
 
+type TeamMonitorCommand =
+  | { type: "monitor"; memberId: UserId }
+  | { type: "whisper" }
+  | { type: "barge" }
+  | { type: "leave" };
+
+type TeamMonitorCommandRequest = {
+  command: TeamMonitorCommand;
+};
+
 type TeamCommandResult =
   | { status: "applied" }
   | { status: "failed"; failure: ProtocolFailure };
@@ -1022,6 +1043,7 @@ type Connection<C extends Channel = Channel> = {
 
   executeTeamBreak?(request: TeamBreakCommandRequest): Promise<TeamCommandResult>;
   executeTeamLeadAssist?(request: TeamLeadAssistCommandRequest): Promise<TeamCommandResult>;
+  executeTeamMonitor?(request: TeamMonitorCommandRequest): Promise<TeamCommandResult>;
   openMedia?(request: OpenMediaRequest): Promise<OpenMediaResult>;
   setPreference?(request: SetPreferenceRequest): Promise<PreferenceResult>;
   recordStep?(report: HandlingReport): Promise<HandlingReportResult>;
@@ -1732,6 +1754,7 @@ them from what arrives later.
 | `team` | This login leads a team. The provider publishes a `TeamRoster` to it on every snapshot — `[]` when nobody is in it — and to nobody else. |
 | `team.breakControl` | This lead may act on their team's breaks through `executeTeamBreak` — place, release, decide, set policy — as far as the provider supports; a command it lacks answers `omni.capability-not-enabled`. Omni asks for a decision only against a member whose `break` is `awaiting-decision`, so a provider that grants on request is never asked to decide. Requires `executeTeamBreak`. |
 | `team.leadAssistControl` | This lead may join a member's call on request. Requires `executeTeamLeadAssist`. |
+| `team.monitorControl` | This lead may listen to a member's call unasked, in the listed modes and no others: `monitor`, `whisper`, `barge`. The list always includes `monitor`, since the other two begin from one. Requires `executeTeamMonitor`. See **Monitoring a call**. |
 | `team.policyControl` | This lead sets the team's policy per capability — on, off, or the person's — within what the queue allows. Requires `executeTeamPolicy`; the roster carries `policies`. |
 | `preferences` | What the team left to this person, with where each stands and who set it. Omitted when nothing was. Requires `setPreference`. See **Who decides what an agent may do**. |
 
@@ -1928,6 +1951,7 @@ surface in one place, and what obliges an adapter to implement each one.
 | `endBreak()` | The login declares `capabilities.breaks`. |
 | `executeTeamBreak(command)` | The login declares `capabilities.team.breakControl`. |
 | `executeTeamLeadAssist(command)` | The login declares `capabilities.team.leadAssistControl`. |
+| `executeTeamMonitor(command)` | The login declares `capabilities.team.monitorControl`. |
 | `setPreference(request)` | The login declares `capabilities.preferences`: the person's choice has to have somewhere to go. |
 | `recordStep(report)` | A task declares `mute`: the host performs that leg, and the provider's record has to have somewhere to take it. See **The host records what it performs**. |
 | `executeTeamPolicy(command)` | The login declares `capabilities.team.policyControl`. |
@@ -2138,6 +2162,7 @@ time. Runtime conformance checks also require the task channel to match its prov
 | `onCall` | Voice only. Who is on the call, or being brought onto it, as the provider states it, replaced whole with the task: `party` is the customer, `agent` a person by user id, `consulted` and `conferenced` somebody a dial is bringing in, listed from the moment the dial is placed -- with the `destination` dialled, the `dialId` where a host placed it, the `stage` reached (`ringing` until answered, `joined` after), and `held: true` on anyone joined and parked. A `consulted` entry is what makes `transfer` `complete` and `cancel` issuable. `label` names a destination -- a person, a queue -- not a phrase; the host supplies the verb. Present when the provider knows the room, absent when it does not. See **Every dial has an outcome**. |
 | `leadAssist` | Voice only. Present from the agent's request for a lead until the lead leaves or the request ends: `requested` while nobody has joined, `joined` with the lead's `leadId` once somebody has. See **Lead assist**. |
 | `assisting` | Voice only, on the lead's own task for a call they joined: which member asked, with their note. Its presence is what makes `lead-assist` `take-over` and `leave` issuable. See **Lead assist**. |
+| `monitoring` | Voice only, on the lead's own task while they listen to a member's call: whose call, which call, and the `mode` they are heard in, restated on every change. Never on the member's task, and never together with `assisting`. See **Monitoring a call**. |
 
 `TaskAttribute` entries carry typed detail alongside the task:
 
@@ -2908,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
@@ -3400,6 +3425,73 @@ const leadAssistCapable = {
 Lead and member alike are `UserId`s of this provider, so an adapter publishing them implements
 `describeUsers()`; names never travel on a task or a roster.
 
+### Monitoring a call
+
+A lead may listen to a member's call without being asked -- to coach, to check quality, to step in
+when it goes wrong. This is not lead assist: nobody requested it, the member's task says nothing
+about it, and there is no take-over in it. A lead who wants the call itself uses lead assist. The
+three modes are the call centre's own words:
+
+| Mode | Who hears the lead |
+| --- | --- |
+| `monitor` | Nobody. The lead hears both sides in silence. |
+| `whisper` | The agent alone. The customer hears nothing. |
+| `barge` | Everyone on the call. |
+
+The login says which modes this lead has, as a list on `team.monitorControl`, and it always
+includes `monitor`, because whisper and barge begin from one
+(`authentication.capability.team.monitorControl.monitor`). A centre that lets every lead listen but
+reserves barging declares `["monitor", "whisper"]`, and Omni offers no Barge to that lead. The
+declaration requires `executeTeamMonitor`, gated exactly as `executeTeamLeadAssist` is by
+`team.leadAssistControl`.
+
+```ts
+// 1. The lead picks a member from the roster and starts silent.
+executeTeamMonitor({ command: { type: "monitor", memberId: "A-1" } })
+
+// 2. The lead's own task arrives -- task-offered with `automatic`, as a joined call does -- and
+//    carries `monitoring`; the task id is the lead's, the member's call is named inside it.
+//    monitoring: { memberId: "A-1", taskId: "call-42", mode: "monitor", since }
+
+// 3. The lead changes how they are heard; the provider restates the task with the new mode.
+executeTeamMonitor({ command: { type: "whisper" } })
+executeTeamMonitor({ command: { type: "barge" } })
+
+// 4. The lead leaves; their task ends with `{ type: "left" }`. The member's call goes on.
+executeTeamMonitor({ command: { type: "leave" } })
+```
+
+**The lead's task is what gives them audio**: Omni opens media on it as on any voice task, and the
+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`). 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
+platform's business and travels on the audio, not on this wire.
+
+```ts
+const monitoringLead = {
+  channel: "voice",
+  capabilities: {},
+  phase: "in-progress",
+  monitoring: { memberId: "A-1", taskId: "call-42", mode: "whisper", since: "2026-08-21T09:04:00Z" },
+} satisfies Pick<Task<"voice">, "channel" | "capabilities" | "phase" | "monitoring">;
+```
+
 ### A member waiting for a break
 
 A member who has asked for a break **keeps working** until Omni commits it, so asking is not an

package/package.json

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