@xema/omni-protocol 0.1.86 → 0.1.88

package/dist/index.d.ts

@@ -244,8 +244,8 @@ export interface TeamCapabilities {
     /** 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
+     * This lead may listen to a member's call unasked, in these modes and no others. Coach and
+     * join-call begin from a monitor, so the list always includes `monitor`. Nothing of it reaches the
      * member's task. Requires `executeTeamMonitor`.
      */
     monitorControl?: MonitorMode[];
@@ -254,10 +254,10 @@ export interface TeamCapabilities {
 }
 /**
  * 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.
+ * `coach` is heard by the agent alone, `join-call` by everyone on the call.
  */
-export type MonitorMode = "monitor" | "whisper" | "barge";
-export declare const MONITOR_MODES: readonly ["monitor", "whisper", "barge"];
+export type MonitorMode = "monitor" | "coach" | "join-call";
+export declare const MONITOR_MODES: readonly ["monitor", "coach", "join-call"];
 /**
  * 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.
@@ -1373,16 +1373,16 @@ export interface TeamLeadAssistCommandRequest {
 }
 /**
  * A lead listening to a member's call. `monitor` starts one, silent, on a member from the team member list;
- * `whisper` and `barge` change how the standing one is heard; `leave` ends it. One member at a
+ * `coach` and `join-call` 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: "coach";
 } | {
-    type: "barge";
+    type: "join-call";
 } | {
     type: "leave";
 };

package/dist/index.js

@@ -26,7 +26,7 @@ export const IDLE_CAPABILITY_UI = {
     calendar: "Calendar",
     contacts: "Contacts",
 };
-export const MONITOR_MODES = ["monitor", "whisper", "barge"];
+export const MONITOR_MODES = ["monitor", "coach", "join-call"];
 export const MUTED_BY = ["host", "station"];
 export const HOST_MUTES = ["stream", "station"];
 export const RECORDING_ACTIONS = ["start", "pause", "resume", "stop", "cancel"];

package/dist/validation.js

@@ -88,7 +88,7 @@ const OFFERABLE_PHASES = membersOf({
 const PREVIEW_DEADLINES = membersOf({ calls: true, "host-calls": true, waits: true });
 const PHONES = membersOf({ softphone: true, deskPhone: true });
 const TEAM_CAPABILITIES = membersOf({ breakControl: true, leadAssistControl: true, policyControl: true, monitorControl: true });
-const MONITOR_MODES = membersOf({ monitor: true, whisper: true, barge: true });
+const MONITOR_MODES = membersOf({ monitor: true, coach: true, "join-call": true });
 const COMPLETED_BY = membersOf({ agent: true, provider: true });
 const CANCELLED_BY = membersOf({ agent: true, provider: true, party: true });
 const EXPIRABLE_PHASES = membersOf({
@@ -2716,7 +2716,7 @@ function validateUserCapabilitiesInto(value, path, into, levels) {
     }
 }
 /**
- * The modes a lead may listen in, as a list: whisper and barge begin from a monitor, so a list
+ * The modes a lead may listen in, as a list: coach and join-call begin from a monitor, so a list
  * without `monitor` names modes the lead could never reach.
  */
 function validateMonitorControl(value, path, into) {
@@ -2729,7 +2729,7 @@ function validateMonitorControl(value, path, into) {
             into.add("authentication.capability.team.monitorControl.unique", `${path}[${index}]`, `duplicate monitor mode: ${describeValue(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");
+    into.require(value.includes("monitor"), "authentication.capability.team.monitorControl.monitor", path, "coach and join-call begin from a monitor: a lead who may listen in any mode may monitor");
 }
 /**
  * A failure an authentication reports: on a `rejected` start or completion, or on an `expired`

package/guide.md

@@ -40,7 +40,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, team member list. |
 | **Dial** | One outbound call the host asks a provider to place — from the idle dialpad, a cold or warm 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 team member list: `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**. |
+| **Monitor** | A lead listening to a member's call unasked, from the team member list: `monitor` in silence, `coach` heard by the agent alone, `join-call` 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
@@ -246,7 +246,7 @@ type AuthenticationContext = {
   log?: (entry: unknown) => void;
 };
 
-type MonitorMode = "monitor" | "whisper" | "barge";
+type MonitorMode = "monitor" | "coach" | "join-call";
 
 type TeamCapabilities = {
   breakControl?: true;
@@ -1049,8 +1049,8 @@ type TeamLeadAssistCommandRequest = {
 
 type TeamMonitorCommand =
   | { type: "monitor"; memberId: UserId }
-  | { type: "whisper" }
-  | { type: "barge" }
+  | { type: "coach" }
+  | { type: "join-call" }
   | { type: "leave" };
 
 type TeamMonitorCommandRequest = {
@@ -1926,7 +1926,7 @@ them from what arrives later.
 | `team` | This login leads a team. The provider publishes a `TeamMembers` object to it on every snapshot — `members: []` 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.monitorControl` | This lead may listen to a member's call unasked, in the listed modes and no others: `monitor`, `coach`, `join-call`. 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 team member list 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**. |
 
@@ -4185,21 +4185,35 @@ Lead and member alike are `UserId`s of this provider, so an adapter publishing t
 
 ### Monitoring a call
 
+**Coach** lets the lead speak privately to the agent; the caller cannot hear the lead.
+The command and monitoring mode are `coach`. Migration: replace the former whisper literal
+in `TeamMonitorCommand`, `MonitorMode`, `team.monitorControl`, and the task’s `monitoring.mode`.
+`MONITOR_MODES` exports `coach`; update command producers, permissions and retained snapshots
+together. No legacy alias is accepted. The lead must already be monitoring and permitted to
+coach. This mode does not join the audible caller conversation or take over the task.
+
+The user-facing action is **Join call**. The command and monitoring mode are `join-call`.
+Migration: replace the former barge literal in `TeamMonitorCommand`, `MonitorMode`,
+`team.monitorControl`, and the task’s `monitoring.mode`. `MONITOR_MODES` exports the new literal;
+no legacy alias is accepted. Update commands, capability declarations and retained snapshots
+together. The lead must already be monitoring and permitted to use this mode. Everyone on the
+call hears the lead; this does not transfer ownership or invoke lead-assist takeover.
+
 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:
+three modes determine who hears the lead:
 
 | 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. |
+| `coach` | The agent alone. The customer hears nothing. |
+| `join-call` | 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
+includes `monitor`, because coach and join-call 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
+reserves joining the call declares `["monitor", "coach"]`, and Omni offers no Join call to that lead. The
 declaration requires `executeTeamMonitor`, gated exactly as `executeTeamLeadAssist` is by
 `team.leadAssistControl`.
 
@@ -4212,8 +4226,8 @@ executeTeamMonitor({ command: { type: "monitor", memberId: "A-1" } })
 //    monitoring: { memberId: "A-1", taskId: "call-42", allocationId: "alloc-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" } })
+executeTeamMonitor({ command: { type: "coach" } })
+executeTeamMonitor({ command: { type: "join-call" } })
 
 // 4. The lead leaves; their task ends with `{ type: "left" }`. The member's call goes on.
 executeTeamMonitor({ command: { type: "leave" } })
@@ -4221,9 +4235,10 @@ 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
+the state, restated on every change, and a `coach` or `join-call` 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
+a task carries lead assistance or monitoring, never both (`task.monitoring.assisting`).
+The `join-call` mode still belongs to monitoring; it does not create `assisting`. The member's
 call ending ends the lead's task as it ends the member's, with `left`, since the lead was never
 working on it.
 
@@ -4238,7 +4253,7 @@ during a break whose active reason is of any other kind, or of no stated kind, i
 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
+mode: not on `onCall`, not in the record. Whether coaching is announced to the agent is the
 platform's business and travels on the audio, not on this wire.
 
 ```ts
@@ -4246,7 +4261,7 @@ const monitoringLead = {
   channel: "voice",
   capabilities: {},
   phase: "in-progress",
-  monitoring: { memberId: "A-1", taskId: "call-42", allocationId: "alloc-42", mode: "whisper", since: "2026-08-21T09:04:00Z" },
+  monitoring: { memberId: "A-1", taskId: "call-42", allocationId: "alloc-42", mode: "coach", since: "2026-08-21T09:04:00Z" },
 } satisfies Pick<Task<"voice">, "channel" | "capabilities" | "phase" | "monitoring">;
 ```
 

package/package.json

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