@xema/omni-protocol 0.1.48 → 0.1.50

package/dist/index.d.ts

@@ -494,7 +494,8 @@ export type TaskCapabilities<C extends Channel = Channel> = C extends "voice" ?
     decline?: Lockable<true>;
     mute?: Lockable<true>;
     hold?: Lockable<true>;
-    agentDisconnect?: Lockable<true>;
+    /** The agent may end the whole call: everyone leaves and the media ends, the task stays for its wrap-up. */
+    endCall?: Lockable<true>;
     /** Connect back to the party while `completing`, whoever placed the call; the task returns to `in-progress`. */
     connectBack?: Lockable<true>;
     coldTransfer?: Lockable<DestinationDirectory>;
@@ -815,7 +816,7 @@ export type TaskOutcome = {
     failure: ProtocolFailure;
 };
 export declare const TASK_COMMAND_NAMES: {
-    readonly voice: readonly ["answer", "decline", "call", "mute", "hold", "resume", "disconnect", "connect-back", "transfer", "lead-assist", "conference", "recording", "complete"];
+    readonly voice: readonly ["answer", "decline", "call", "mute", "hold", "resume", "end-call", "connect-back", "transfer", "lead-assist", "conference", "recording", "complete"];
     readonly chat: readonly ["accept", "decline", "pause", "resume", "complete"];
     readonly email: readonly ["accept", "decline", "complete"];
 };
@@ -840,8 +841,10 @@ export type VoiceTaskCommand = {
     type: "hold";
 } | {
     type: "resume";
-} | {
-    type: "disconnect";
+}
+/** End the whole call: everyone leaves and the task's media ends; the task stays for its wrap-up. Gated by `endCall`. */
+ | {
+    type: "end-call";
 }
 /** Issuable only in `completing`, under the `connectBack` capability. Dials the party's own number, so it names none. */
  | {
@@ -900,11 +903,22 @@ export type VoiceTaskCommand = {
     dialId: DialId;
     destinationId: string;
 }
-/** Drop the `conferenced` entry on `Task.onCall` with this `destinationId`; while it still rings, this calls the dial off. */
+/**
+ * Remove one person from the call, named as `onCall` names them, and the call goes on for the
+ * rest: a `conferenced` entry by its `destinationId`, which while it still rings calls the dial
+ * off, or the `party`, leaving the agent with the colleague. A remove that would leave the agent
+ * alone is `end-call`, and a provider answers it `failed`.
+ */
  | {
     type: "conference";
     action: "remove";
     destinationId: string;
+    party?: never;
+} | {
+    type: "conference";
+    action: "remove";
+    party: true;
+    destinationId?: never;
 } | {
     type: "recording";
     action: "start" | "pause" | "resume" | "stop";

package/dist/index.js

@@ -72,7 +72,7 @@ export function effectiveLevels(declared) {
 // Task commands.
 // ---------------------------------------------------------------------------
 export const TASK_COMMAND_NAMES = {
-    voice: ["answer", "decline", "call", "mute", "hold", "resume", "disconnect",
+    voice: ["answer", "decline", "call", "mute", "hold", "resume", "end-call",
         "connect-back", "transfer", "lead-assist", "conference", "recording", "complete"],
     chat: ["accept", "decline", "pause", "resume", "complete"],
     email: ["accept", "decline", "complete"],

package/dist/testing.js

@@ -1,5 +1,5 @@
 import { browserSessionKey, effectiveLevels, sameCapabilities, } from "./index.js";
-import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateManifest, validateResult, validateSnapshot, validateTimeZone, validatePhone, isTimeZone, } from "./validation.js";
+import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateManifest, validateResult, validateSnapshot, validateTimeZone, validatePhone, isTimeZone, sameTimeZone, } from "./validation.js";
 export { ProtocolConformanceError, assertNoViolations } from "./validation.js";
 /**
  * A part of the contract a run may never reach: state nothing obliges an adapter to publish, so
@@ -257,18 +257,6 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         violations.push(...validateHostGuarantees(context.host.guarantees, "context.host.guarantees"));
         // The zone is the host's to state, so a context without one is a host that cannot exist.
         violations.push(...validateTimeZone(context.timeZone, "context.timeZone"));
-        // A provider that reads its own clock passes the round trip on any machine in the host's zone,
-        // which for a demo and a runner in one datacentre is most of them. A conformance run states a
-        // zone this machine is not in, so the only way the identity carries it is that the provider
-        // took it from the host.
-        if (isTimeZone(context.timeZone)) {
-            const canonical = (zone) => new Intl.DateTimeFormat("en", { timeZone: zone }).resolvedOptions().timeZone;
-            const local = Intl.DateTimeFormat().resolvedOptions().timeZone;
-            if (canonical(context.timeZone) === canonical(local)) {
-                violations.push({ rule: "context.timeZone.local", path: "context.timeZone",
-                    message: `a conformance run states a zone this machine is not in; ${context.timeZone} is this machine's, so a provider reading its own clock would pass the round trip` });
-            }
-        }
         // How the agent hears the call decides what the host owns: on a softphone the host has the
         // audio and reports it; on a desk phone, or off voice, there is none for it to report.
         violations.push(...validatePhone(context.phone, adapter.manifest, "context.phone"));
@@ -354,7 +342,9 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         // The provider republishes the agent's day: once connected, the identity carries the zone the
         // host sent. That proves the round trip, not the store -- an echo passes it -- and the name
         // says only what it tests; storage is proved by a colleague's zone arriving from describeUsers().
-        if (isTimeZone(context.timeZone) && current().identity.timeZone !== context.timeZone) {
+        // A zone is judged by what it denotes: Asia/Kolkata and Asia/Calcutta are one zone, and a
+        // provider that keeps the canonical name has kept the zone.
+        if (isTimeZone(context.timeZone) && !sameTimeZone(current().identity.timeZone, context.timeZone)) {
             violations.push({
                 rule: "authentication.identity.timeZone.republished",
                 path: "authentication.identity.timeZone",

package/dist/validation.d.ts

@@ -63,6 +63,14 @@ 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[];
+/**
+ * What a command needs to be issuable, checked against the task it names: the capability the
+ * guide's table gates it on, the phase it belongs to, and the state that has to stand -- a
+ * consulted entry, a lead requested, somebody else on the call. Without a task only the command's
+ * own shape is checked. A host validates before sending, and an adapter before acting: a command
+ * for a control the task never offered is the host's error, and this names it.
+ */
+export declare function validateTaskCommand(command: unknown, task?: unknown, path?: string): ProtocolViolation[];
 /** The connection methods whose results `validateResult` knows. */
 export type ResultMethod = "execute" | "dial" | "setCapacity" | "requestBreak" | "commitBreak" | "cancelBreak" | "endBreak" | "executeTeamBreak" | "executeTeamLeadAssist" | "executeTeamMonitor" | "openMedia" | "setPreference" | "recordStep" | "executeTeamPolicy";
 /**
@@ -74,6 +82,8 @@ export type ResultMethod = "execute" | "dial" | "setCapacity" | "requestBreak" |
 export declare function validateResult(result: unknown, method: ResultMethod, path?: string, dialId?: string): ProtocolViolation[];
 /** An IANA zone name the runtime knows: `Asia/Kolkata` is one, an offset or a made-up name is not. */
 export declare function isTimeZone(value: unknown): value is string;
+/** Whether two zone names denote one zone: `Asia/Kolkata` and `Asia/Calcutta` do, and a name is judged by what it denotes. */
+export declare function sameTimeZone(a: unknown, b: unknown): boolean;
 /** The zone a host sends at connect: required, and an IANA name. */
 export declare function validateTimeZone(value: unknown, path?: string): ProtocolViolation[];
 /** What a login is validated against beyond its own shape. */

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, 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";
+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, TASK_COMMAND_NAMES, negotiateProtocolVersion, DEFAULT_LEVELS, effectiveLevels, } from "./index.js";
 export class ProtocolConformanceError extends Error {
     violations;
     constructor(violations, summary = "Adapter violates the Omni protocol") {
@@ -96,7 +96,7 @@ const ISOLATION_SCHEME_VALUES = Object.values(BROWSER_ISOLATION_SCHEMES);
 const TASK_CAPABILITIES = {
     voice: membersOf({
         browsers: true, dispositions: true, custom: true, decline: true, mute: true, hold: true,
-        agentDisconnect: true, connectBack: true, coldTransfer: true, warmTransfer: true, leadAssist: true, conference: true, recording: true,
+        endCall: true, connectBack: true, coldTransfer: true, warmTransfer: true, leadAssist: true, conference: true, recording: true,
     }),
     chat: membersOf({ browsers: true, dispositions: true, custom: true, decline: true, hold: true }),
     email: membersOf({ browsers: true, dispositions: true, custom: true, decline: true }),
@@ -1710,6 +1710,178 @@ export function validateHostReport(report, path = "host") {
     }
     return into.violations;
 }
+// ---------------------------------------------------------------------------
+// Commands.
+// ---------------------------------------------------------------------------
+const TRANSFER_ACTIONS = ["cold", "warm", "complete", "cancel"];
+const LEAD_ASSIST_ACTIONS = ["request", "cancel", "take-over", "leave"];
+const CONFERENCE_ACTIONS = ["add", "remove"];
+const RECORDING_ACTIONS = ["start", "pause", "resume", "stop"];
+/**
+ * What a command needs to be issuable, checked against the task it names: the capability the
+ * guide's table gates it on, the phase it belongs to, and the state that has to stand -- a
+ * consulted entry, a lead requested, somebody else on the call. Without a task only the command's
+ * own shape is checked. A host validates before sending, and an adapter before acting: a command
+ * for a control the task never offered is the host's error, and this names it.
+ */
+export function validateTaskCommand(command, task, path = "command") {
+    const into = new Collector();
+    if (!isPlainObject(command)) {
+        into.add("command.shape", path, "a command must be an object");
+        return into.violations;
+    }
+    const type = command.type;
+    const channel = isPlainObject(task) && typeof task.channel === "string" && isChannel(task.channel) ? task.channel : undefined;
+    const names = channel !== undefined
+        ? TASK_COMMAND_NAMES[channel]
+        : [...new Set([...TASK_COMMAND_NAMES.voice, ...TASK_COMMAND_NAMES.chat, ...TASK_COMMAND_NAMES.email])];
+    if (type === "custom") {
+        into.filled(command.name, "command.custom.name", `${path}.name`, "a custom command names the control it presses");
+        return into.violations;
+    }
+    if (!into.require(typeof type === "string" && names.includes(type), "command.type", `${path}.type`, channel === undefined ? `unsupported command: ${String(type)}` : `a ${channel} task has no ${String(type)} command`)) {
+        return into.violations;
+    }
+    const dial = (rule) => into.filled(command.dialId, rule, `${path}.dialId`, "a command that dials carries the host's dialId");
+    switch (type) {
+        case "mute":
+            into.require(typeof command.muted === "boolean", "command.mute.muted", `${path}.muted`, "mute says whether the agent is muted");
+            break;
+        case "call":
+            dial("command.call.dialId");
+            break;
+        case "connect-back":
+            dial("command.connectBack.dialId");
+            break;
+        case "transfer":
+            if (into.oneOf(command.action, TRANSFER_ACTIONS, "command.transfer.action", `${path}.action`)) {
+                if (command.action === "cold" || command.action === "warm") {
+                    dial("command.transfer.dialId");
+                    into.filled(command.destinationId, "command.transfer.destinationId", `${path}.destinationId`, "a transfer names the directory item it goes to");
+                }
+                else {
+                    into.require(command.dialId === undefined && command.destinationId === undefined, "command.transfer.unexpected", path, `${String(command.action)} names no destination: there is exactly one it could mean`);
+                }
+            }
+            break;
+        case "lead-assist":
+            into.oneOf(command.action, LEAD_ASSIST_ACTIONS, "command.leadAssist.action", `${path}.action`);
+            if (command.note !== undefined)
+                into.filled(command.note, "command.leadAssist.note", `${path}.note`, "a note must not be empty when present");
+            break;
+        case "conference":
+            if (into.oneOf(command.action, CONFERENCE_ACTIONS, "command.conference.action", `${path}.action`)) {
+                if (command.action === "add") {
+                    dial("command.conference.dialId");
+                    into.filled(command.destinationId, "command.conference.destinationId", `${path}.destinationId`, "a conference names the directory item it dials in");
+                }
+                else {
+                    const party = command.party === true;
+                    const item = isFilled(command.destinationId);
+                    into.require(party !== item, "command.conference.remove.target", path, "a remove names one person: the party, or a conferenced entry by its destinationId, never both and never neither");
+                }
+            }
+            break;
+        case "recording":
+            into.oneOf(command.action, RECORDING_ACTIONS, "command.recording.action", `${path}.action`);
+            break;
+        case "complete":
+            if (command.disposition !== undefined)
+                into.filled(command.disposition, "command.complete.disposition", `${path}.disposition`, "a disposition must not be empty when present");
+            if (command.notes !== undefined)
+                into.require(typeof command.notes === "string", "command.complete.notes", `${path}.notes`, "notes must be a string when present");
+            break;
+        default:
+            break;
+    }
+    if (!isPlainObject(task))
+        return into.violations;
+    // What the task has to offer or be in for the command to be issuable.
+    const capabilities = isPlainObject(task.capabilities) ? task.capabilities : {};
+    const offered = (name) => {
+        const declared = capabilities[name];
+        if (declared === undefined) {
+            into.add(`command.capability.${name}`, path, `${String(type)} needs the ${name} capability, and the task does not offer it`);
+            return false;
+        }
+        if (isLocked(declared)) {
+            into.add("command.capability.locked", path, `${name} stands locked by ${String(declared.lockedBy)}: the control is present without permission`);
+            return false;
+        }
+        return true;
+    };
+    const inPhase = (rule, ...phases) => into.require(phases.includes(String(task.phase)), rule, path, `${String(type)} belongs to ${phases.join(" or ")}, and the task is ${String(task.phase)}`);
+    const onCall = Array.isArray(task.onCall) ? task.onCall.filter(isPlainObject) : [];
+    switch (type) {
+        case "answer":
+        case "accept":
+        case "decline":
+        case "reject":
+            inPhase("command.phase.pending", "pending");
+            if (type === "decline")
+                offered("decline");
+            break;
+        case "call":
+            inPhase("command.phase.preview", "preview");
+            break;
+        case "mute":
+            offered("mute");
+            break;
+        case "hold":
+        case "resume":
+        case "pause":
+            offered("hold");
+            break;
+        case "end-call":
+            offered("endCall");
+            break;
+        case "recording":
+            offered("recording");
+            break;
+        case "connect-back":
+            offered("connectBack");
+            inPhase("command.phase.completing", "completing");
+            break;
+        case "transfer":
+            if (command.action === "cold")
+                offered("coldTransfer");
+            else if (command.action === "warm")
+                offered("warmTransfer");
+            else if (command.action === "complete" || command.action === "cancel") {
+                into.require(onCall.some(entry => entry.role === "consulted"), "command.transfer.consulted", path, `${String(command.action)} needs a consulted entry on onCall: without one there is nothing to complete or cancel`);
+            }
+            break;
+        case "lead-assist":
+            if (command.action === "request" || command.action === "cancel") {
+                offered("leadAssist");
+                if (command.action === "cancel") {
+                    into.require(isPlainObject(task.leadAssist) && task.leadAssist.stage === "requested", "command.leadAssist.requested", path, "cancel needs a request standing: leadAssist with stage requested");
+                }
+            }
+            else {
+                into.require(task.assisting !== undefined, "command.leadAssist.assisting", path, `${String(command.action)} is the lead's own act on a call they joined: the task carries assisting`);
+            }
+            break;
+        case "conference":
+            if (offered("conference") && command.action === "remove") {
+                const others = onCall.filter(entry => entry.role !== "agent");
+                if (command.party === true) {
+                    into.require(others.some(entry => entry.role !== "party"), "command.conference.remove.alone", path, "removing the party would leave the agent alone: that is end-call");
+                }
+                else if (isFilled(command.destinationId)) {
+                    into.require(onCall.some(entry => entry.role === "conferenced" && entry.destinationId === command.destinationId), "command.conference.remove.unknown", path, `no conferenced entry on onCall has destinationId ${String(command.destinationId)}`);
+                    into.require(others.length > 1, "command.conference.remove.alone", path, "removing the last other person would leave the agent alone: that is end-call");
+                }
+            }
+            break;
+        case "complete":
+            into.require(task.completionMode === "agent-command", "command.complete.mode", path, "complete belongs to agent-command; a provider-automatic task completes itself");
+            break;
+        default:
+            break;
+    }
+    return into.violations;
+}
 // Pinned to the result unions: each method's one success status, and the status that carries a
 // failure. A method added to `Connection` without a row here is a compile error at the call site.
 const RESULT_STATUSES = {
@@ -1788,6 +1960,13 @@ export function isTimeZone(value) {
         return false;
     }
 }
+/** Whether two zone names denote one zone: `Asia/Kolkata` and `Asia/Calcutta` do, and a name is judged by what it denotes. */
+export function sameTimeZone(a, b) {
+    if (!isTimeZone(a) || !isTimeZone(b))
+        return false;
+    const canonical = (zone) => new Intl.DateTimeFormat("en", { timeZone: zone }).resolvedOptions().timeZone;
+    return a === b || canonical(a) === canonical(b);
+}
 /** The zone a host sends at connect: required, and an IANA name. */
 export function validateTimeZone(value, path = "context.timeZone") {
     const into = new Collector();

package/guide.md

@@ -26,7 +26,7 @@ are used precisely throughout and mean nothing looser here.
 | **Task** | One unit of assigned work — a call, a chat, a mail. |
 | **Channel** | The kind of work a provider carries: `voice`, `chat`, or `email`. Fixed per provider by its manifest. |
 | **Task type** | The provider's own name for a category of work — a queue, a mailbox folder, a chat source. Free-form, and finer-grained than a channel. |
-| **Capability** | A provider's declaration that a control exists for a task or a session. It says *offer this*, and nothing about who carries it out — that is fixed per command, see **Where a command executes**. |
+| **Capability** | A provider's declaration that a control exists for a task or a session. It says *offer this*; the provider performs it, and the host only offers it — see **Where a command executes**. |
 | **Login** | One authenticated sign-in to one provider, identified by `loginId`. A transport reconnect keeps it; signing in again replaces it, and nothing tied to the old `loginId` survives. |
 | **Transport** | The adapter's connection to its platform: a WebSocket or SignalR connection, required to be persistent and ordered. Which one and how it reconnects are the adapter's business; losing it does not end a login. |
 | **Connection** | The `Connection` object Omni holds for one login: the methods it can call and the events it receives. |
@@ -486,7 +486,7 @@ type TaskCapabilities<C extends Channel = Channel> =
         decline?: Lockable<true>;
         mute?: Lockable<true>;
         hold?: Lockable<true>;
-        agentDisconnect?: Lockable<true>;
+        endCall?: Lockable<true>;
         connectBack?: Lockable<true>;
         coldTransfer?: Lockable<DestinationDirectory>;
         warmTransfer?: Lockable<DestinationDirectory>;
@@ -692,7 +692,7 @@ const TASK_COMMAND_NAMES = {
     "mute",
     "hold",
     "resume",
-    "disconnect",
+    "end-call",
     "connect-back",
     "transfer",
     "lead-assist",
@@ -716,7 +716,7 @@ type VoiceTaskCommand =
   | { type: "mute"; muted: boolean }
   | { type: "hold" }
   | { type: "resume" }
-  | { type: "disconnect" }
+  | { type: "end-call" }
   | { type: "connect-back"; dialId: DialId }
   | { type: "transfer"; action: "cold"; dialId: DialId; destinationId: string }
   | { type: "transfer"; action: "warm"; dialId: DialId; destinationId: string }
@@ -727,7 +727,8 @@ type VoiceTaskCommand =
   | { type: "lead-assist"; action: "take-over" }
   | { type: "lead-assist"; action: "leave" }
   | { type: "conference"; action: "add"; dialId: DialId; destinationId: string }
-  | { type: "conference"; action: "remove"; destinationId: string }
+  | { type: "conference"; action: "remove"; destinationId: string; party?: never }
+  | { type: "conference"; action: "remove"; party: true; destinationId?: never }
   | { type: "recording"; action: "start" | "pause" | "resume" | "stop" }
   | ({ type: "complete" } & DispositionPayload);
 
@@ -1939,10 +1940,9 @@ field to fill in later: an identity without one is refused (`authentication.iden
 so is a zone that is not an IANA name, wherever it appears. Nothing is ever assumed in its place --
 not the viewer's browser, which gives a different answer per reader for the same record, and not the
 provider's clock. The harness holds a provider to the round trip: the identity carries the zone the
-host stated (`authentication.identity.timeZone.republished`), and a conformance run states a zone
-the machine running it is not in (`context.timeZone.local`): a provider that read its own clock
-would otherwise pass the round trip on any runner in the host's zone, which for a demo and a runner
-in one datacentre is most of them. **The round trip is not the store.**
+host stated (`authentication.identity.timeZone.republished`), judged by what the name denotes:
+`Asia/Kolkata` and `Asia/Calcutta` are one zone, and a provider that keeps the canonical name has
+kept the zone. **The round trip is not the store.**
 An adapter that echoes the stated zone back onto the identity passes that check with nothing kept,
 and a lead reading a colleague's day would still get the wrong one. What proves the store is a zone
 the run never sent: a colleague's `User` from `describeUsers()` carrying theirs. A provider's own
@@ -2681,12 +2681,12 @@ const taskCapabilities = {
 | `decline` | Pending-task button: Decline | The provider can decline a pending voice offer. Omni shows it only when provisioning also permits declining. |
 | `mute` | Primary toggle: Mute | Omni may mute and unmute the agent's outbound audio. |
 | `hold` | Primary toggle: Hold | Omni may issue voice-task `hold` and `resume` commands. |
-| `agentDisconnect` | Primary button: Disconnect | Omni may disconnect real-time media without disposing the task. |
+| `endCall` | Primary button: End call | Omni may end the whole call: everyone leaves, the media ends, and the task stays for its wrap-up. See **Ending a call, and removing one person from it**. |
 | `connectBack` | Completing-task button: Connect back | Omni may have the provider connect the agent back to the task's party while the task is `completing`, returning it to `in-progress` on the same task. Not offered where there is no `completing` window: `provider-automatic` with a zero allowance disposes at provider end. See **Connecting back during completion**. |
 | `coldTransfer` | Secondary menu item: Cold transfer | Omni may hand the customer straight to a destination, with nobody spoken to first. |
 | `warmTransfer` | Secondary menu item: Warm transfer | Omni may park the customer and call a destination first, then hand the customer over or cancel back. See **Warm transfer**. |
 | `leadAssist` | Secondary menu item: Lead assist | Omni may ask a lead to join this call, with a note. The lead's decision reaches the agent on `Task.leadAssist`. See **Lead assist**. |
-| `conference` | Secondary button: Conference | Omni may dial a destination into the active call, and drop a `conferenced` entry from it -- one still ringing included, which calls the dial off. |
+| `conference` | Secondary button: Conference | Omni may dial a destination into the active call, and remove one person from it -- a conferenced entry, one still ringing included, which calls the dial off, or the party, leaving the agent with the colleague. See **Ending a call, and removing one person from it**. |
 | `recording` | Overflow menu item: Recording | Omni may expose start, pause, resume, and stop recording controls. |
 | `dispositions` | Primary button: Complete | Omni may request task disposal with a provider disposition and notes. |
 
@@ -2752,6 +2752,27 @@ chosen colleague bypasses all three. The desk shows no agent picker and no dial
 The one way a named person ends up with an agent's call is a lead taking it over through lead
 assist, which is the lead's act, not a transfer the agent chose.
 
+#### Ending a call, and removing one person from it
+
+A call has everyone on `Task.onCall`, and two commands take people off it, both performed by the
+provider.
+
+```ts
+{ type: "end-call" }                                             // everyone leaves; the media ends; the task stays for its wrap-up
+{ type: "conference", action: "remove", party: true }            // the customer leaves; the agent stays with the colleague
+{ type: "conference", action: "remove", destinationId: "tier2" } // the conferenced person leaves; ringing, this calls the dial off
+```
+
+`end-call` ends the whole conversation for everyone on it, and is gated by `endCall`. The task does
+not end with it: `task-media-ended` follows, any wrap allowance runs, and the agent dispositions
+the call. `conference` `remove` takes one person off, named as the room names them, and the call
+goes on for the rest; it is gated by `conference`, since it only means something with a third
+person on the line. Removing the party leaves the agent with the colleague, a warm hand-over in
+reverse. A remove that would leave the agent alone is not a remove but an `end-call`, and a
+provider answers it `failed`. The consulted destination of a warm transfer is not removed this way:
+`transfer` `cancel` is its own step, which returns the agent to the parked customer, and a remove
+never promises that.
+
 #### Warm transfer
 
 A warm transfer parks the customer, calls the destination so the agent can speak to it first, and
@@ -3824,7 +3845,17 @@ already did.
 | Command | The provider's part |
 | --- | --- |
 | `mute` | **Record it, and keep the history.** The microphone is the host's, so Omni has already stopped the audio through `VoiceMediaSession.setMuted()` — no adapter can do that on the host's behalf. The command still arrives because the provider owns the task's record: it holds the current state for supervision, and each change as a `muted` handling step, exactly as it does for `held`. A platform that never hears about it shows a supervisor an agent who sounds absent for no reason, and reports a call with a silence it cannot explain. |
-| Every other command | **Perform it.** `hold`, `transfer`, `conference`, `recording`, `disconnect` and the rest act on the platform's own call leg, its bridge, or its record of the task. Nothing has happened until the provider applies them. |
+| Every other command | **Perform it.** `hold`, `transfer`, `conference`, `end-call`, `recording` and the rest act on the platform's own call leg, its bridge, or its record of the task. Nothing has happened until the provider applies them. |
+
+**The provider performs every action; the host only offers it.** A control drawn on the host is
+an affordance, never the enforcement: the host asks, and the provider does or declines. A provider
+answers `failed` for a command whose capability it did not publish, and that is the provider
+honouring its own declaration, not the host deciding policy -- a host that refuses a command on
+its own reading of a queue's flag has decided something that was never its to decide. What a
+command means on the platform is the provider's to work out: `end-call` ends the conversation, and
+which legs on which bridge that touches is a fact about the switch, never a choice the host makes.
+The one leg the host performs physically is the microphone, and even there the provider owns the
+record.
 
 **A failed `mute` does not unmute the agent.** The agent asked, Omni holds the microphone, and it
 is already done; a failure means only that the provider did not record it, leaving its view stale
@@ -3843,6 +3874,8 @@ declared:
 | Command | What makes it available |
 | --- | --- |
 | `answer`, `accept` | Nothing. A task that was offered can be accepted, or offering it meant nothing. |
+| `end-call` | The `endCall` capability. |
+| `conference` with `action: "remove"` | The `conference` capability, and somebody else on the call: a remove that would leave the agent alone is `end-call`, and a provider answers it `failed`. |
 | `decline` | The `decline` capability on any channel, **and** Omni provisioning permitting it. One word for refusing an offer, whatever the channel. |
 | `call` | The `preview` phase. A record put in front of an agent is there to be called, so the phase is the gate and there is no capability. It is a dial, with a `dialId` and a `dial-outcome`. |
 | `complete` | `completionMode: "agent-command"`. The `dispositions` capability decides whether a code travels with the command, never whether the command exists — a task Omni cannot complete never ends. |
@@ -3853,6 +3886,9 @@ declared:
 | `lead-assist` with `action: "take-over"` or `"leave"` | The lead's own task, on a call they joined -- `Task.assisting` present. An agent's task never has it, and a provider that receives either without it answers `failed`. |
 | Everything else | Its own named capability. |
 
+`validateTaskCommand(command, task)` holds a command to this table at runtime, both ways: the
+capability it needs, the phase it belongs to, and the state that has to stand.
+
 Declining or rejecting a pending offer ends it without accepting or completing it. The provider
 confirms the end with `task-ended` and a `cancelled` outcome.
 
@@ -4205,6 +4241,7 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | `validateHostGuarantees(guarantees)` | What a host promises: only the guarantees this contract names, each declared by presence and never `false`. The harness validates the guarantees of whatever host a test hands the adapter. |
 | `validateHandlingReport(report, path?, manifest?)` | What the host reports of a leg it performed, for an adapter to check before forwarding: a task, a step, when it began, a positive `seconds` where stated, and an explicit `ended` that carries the final duration. Given the manifest, a running report is refused unless it declares `runningStepReports`. |
 | `validateHostReport(report)` | The host's own report as published to an adapter: `online`, and where there is audio, an input that is `available` with the microphone and `flowing`, or `unavailable` with a reason and the failure that says why, and an output that is `available` or `unavailable` with its failure. The harness validates whatever host a test hands the adapter; `stillHost(report)` builds one that never changes. |
+| `validateTaskCommand(command, task?)` | What a command needs to be issuable, against the task it names: its own shape -- a dial's `dialId`, a transfer's item, a remove naming exactly one person -- and, with the task, the capability the table above gates it on (`command.capability.<name>`, `.locked`), the phase it belongs to (`command.phase.*`), and the state that has to stand: a consulted entry, a lead requested, somebody else still on the call (`command.conference.remove.alone`). A host validates before sending and an adapter before acting. |
 | `validateResult(result, method)` | What a connection method answered: the status it gives, a failure where the status says so and nowhere else, the failure's shape, and that an `omni.` code is one this contract names. |
 | `validateAuthenticationState(state)` | The identity each state must carry, the capabilities a usable login declares, and the expiry that only `authenticated` may. Omni applies it to every state a session publishes — the republished as much as the first. |
 

package/package.json

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