@xema/omni-protocol 0.1.106 → 0.1.108

package/README.md

@@ -11,7 +11,8 @@ system.
 
 | Path | |
 | --- | --- |
-| `guide.md` | **The protocol.** Rules, shapes, and the reasoning behind them. |
+| `guide.md` | **The protocol.** The terms, the shapes, the rules, and how an adapter is declared, connected and held to them. |
+| `guide/` | One file per role and channel: `agent.md`, `lead.md`, `breaks.md`, `phone.md`, `voice.md`, `chat.md`, `email.md`. Each points back into `guide.md` for what it relies on. |
 | `src/index.ts` | The TypeScript declarations. |
 | `src/validation.ts` | Runtime validators Omni applies to adapter output. |
 | `src/testing.ts` | Conformance helpers an adapter runs against its own test state. |

package/dist/index.d.ts

@@ -112,6 +112,46 @@ export declare const DIAL_OUTCOMES: readonly ["answered", "busy", "no-answer", "
  */
 export type Phone = "softphone" | "deskPhone";
 export declare const PHONES: readonly ["softphone", "deskPhone"];
+/**
+ * The device itself, as the platform sees it. `ready` is registered and usable, idle or busy; the
+ * other three are the states in which no call can land: the platform has lost the phone's
+ * registration, the agent pressed do-not-disturb on it, or left the handset off the hook with no
+ * call on it.
+ */
+export type PhoneStatus = "ready" | "unregistered" | "do-not-disturb" | "off-hook";
+export declare const PHONE_STATUSES: readonly ["ready", "unregistered", "do-not-disturb", "off-hook"];
+export type PhoneChannelState = "ringing" | "active" | "held";
+export declare const PHONE_CHANNEL_STATES: readonly ["ringing", "active", "held"];
+/**
+ * One call on the phone, as the phone sees it: ringing, the one active, or held. A bridge is one
+ * channel, so a conference is one entry and its members are on the task's `onCall`. Where the call
+ * is a task's, `assignmentId` names it and the two views agree; absent, the call is the phone's
+ * alone -- an internal call on the extension, a lead's listening leg.
+ */
+export interface PhoneChannel {
+    state: PhoneChannelState;
+    since: IsoTimestamp;
+    assignmentId?: AssignmentId;
+}
+/**
+ * The phone's own view, published by a provider that declares `phoneStatus`: the device the login
+ * is on, whether it can take a call, its own mute where the platform observes it, and its channels
+ * -- one active at most, any number held. The task side says which of those calls are the agent's
+ * work and where each stands; the phone side exists whether or not a task is behind a call. `muted`
+ * is the phone's own button as the platform sees it, silencing whatever is active: a desk phone's,
+ * never a softphone's, whose microphone is the host's and whose mute is the host's report.
+ */
+export interface PhoneState {
+    /** The agent's phone for this provider, as the host chose it for the login at connect: which of the manifest's phones the agent hears this provider's calls on. */
+    phone: Phone;
+    status: PhoneStatus;
+    /** The phone's own mute, on a desk phone the platform observes; absent where it does not, or on a softphone. */
+    muted?: true;
+    /** When the status began, counted from the provider's clock. Omitted rather than invented. */
+    since?: IsoTimestamp;
+    /** The calls on the phone; `[]` when idle. None under `unregistered` or `off-hook`. */
+    channels: PhoneChannel[];
+}
 /** Every idle capability a provider may declare. Only voice may `dial`; the channel arm says so. */
 export declare const IDLE_CAPABILITIES: readonly ["dial", "personalBrowser", "calendar", "contacts"];
 export type IdleCapability = (typeof IDLE_CAPABILITIES)[number];
@@ -178,6 +218,11 @@ export interface Manifest<C extends Channel = Channel> {
      * off voice, where there is no call to hear. The host picks one of these per login.
      */
     phones?: C extends "voice" ? Phone[] : never;
+    /**
+     * The platform sees the phone itself -- its registration, its do-not-disturb, its hook -- and
+     * publishes it as `Snapshot.phone` and `phone-updated`. Voice only, declared by presence.
+     */
+    phoneStatus?: C extends "voice" ? true : never;
     /**
      * The provider takes running reports of a host-performed step -- `recordStep` with `seconds`
      * so far and no `ended`. Absent, the host sends exactly two reports per leg, when it began and
@@ -1290,6 +1335,8 @@ export interface TeamMember {
     shift?: Shift;
     /** The member's standing ask for a lead on one of their calls; absent when they are not asking. */
     request?: MemberRequest;
+    /** The member's phone as the platform sees it, the same `PhoneState` the member's own snapshot carries; present where the provider declares `phoneStatus`. */
+    phone?: PhoneState;
 }
 /** This member asking their lead to join a call: which assignment, the note they wrote, since when. */
 export interface MemberRequest {
@@ -1589,6 +1636,8 @@ export interface Snapshot<C extends Channel = Channel> {
     calendar?: ScheduledActivity[];
     /** The agent's own day so far, as the provider counts it; replaced whole by `shift-updated`. Omitted where the provider cannot say. */
     shift?: Shift;
+    /** The phone as the platform sees it, from a provider that declares `phoneStatus`; replaced whole by `phone-updated`. */
+    phone?: PhoneState;
     team?: TeamMembers;
 }
 /**
@@ -1705,6 +1754,11 @@ export type ProviderEvent<C extends Channel = Channel> = {
  | {
     type: "shift-updated";
     shift: Shift;
+}
+/** The phone as the platform now sees it, whole: a registration lost or back, do-not-disturb pressed, the handset lifted or replaced, the phone's mute. */
+ | {
+    type: "phone-updated";
+    phone: PhoneState;
 };
 /**
  * The `Provider` prefix survives here for a mechanical reason rather than a naming one: `Event`

package/dist/index.js

@@ -17,6 +17,8 @@ export function negotiateProtocolVersion(adapterVersions, hostVersions = OMNI_SU
 }
 export const DIAL_OUTCOMES = ["answered", "busy", "no-answer", "unreachable", "rejected", "cancelled", "unexplained"];
 export const PHONES = ["softphone", "deskPhone"];
+export const PHONE_STATUSES = ["ready", "unregistered", "do-not-disturb", "off-hook"];
+export const PHONE_CHANNEL_STATES = ["ringing", "active", "held"];
 /** Every idle capability a provider may declare. Only voice may `dial`; the channel arm says so. */
 export const IDLE_CAPABILITIES = ["dial", "personalBrowser", "calendar", "contacts"];
 /** What Omni calls each idle capability. */

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 team member list, each
  * declared contribution, and each event type.
  */
-declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.history", "task.onCall", "task.leadAssist", "task.takenOver", "task.audio", "task.acceptance", "task.outcomes", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.forced", "team.members", "team.request", "team.tasks", "team.listening", "team.shift", "shift", "contacts", "calendar", "team.policies"];
+declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.history", "task.onCall", "task.leadAssist", "task.takenOver", "task.audio", "task.acceptance", "task.outcomes", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.forced", "team.members", "team.request", "team.tasks", "team.listening", "team.shift", "team.phone", "shift", "phone", "contacts", "calendar", "team.policies"];
 export type ContractSubject = (typeof STATE_SUBJECTS)[number] | `event.${ProviderEvent["type"]}`;
 export interface AdapterContractResult {
     events: ProviderEventEnvelope[];

package/dist/testing.js

@@ -28,7 +28,9 @@ const STATE_SUBJECTS = [
     "team.tasks",
     "team.listening",
     "team.shift",
+    "team.phone",
     "shift",
+    "phone",
     "contacts",
     "calendar",
     "team.policies",
@@ -39,7 +41,7 @@ const EVENT_TYPES = {
     snapshot: true, "transport-status": true, "break-state": true, "task-offered": true, "task-updated": true,
     "task-audio-started": true, "task-audio-ended": true, "task-ended": true, "dial-outcome": true, announcement: true, "queue-summary": true, diagnostic: true,
     "team-updated": true, "team-member-updated": true, "team-member-removed": true, "team-policies-updated": true,
-    "contacts-updated": true, "calendar-updated": true, "shift-updated": true,
+    "contacts-updated": true, "calendar-updated": true, "shift-updated": true, "phone-updated": true,
 };
 const CONTRACT_SUBJECTS = [
     ...STATE_SUBJECTS,
@@ -101,6 +103,8 @@ function observeMember(member, seen) {
         seen.add("team.shift");
     if (member.request !== undefined)
         seen.add("team.request");
+    if (member.phone !== undefined)
+        seen.add("team.phone");
 }
 function observePolicies(value, seen) {
     if (isRecord(value) && Object.keys(value).length > 0)
@@ -129,6 +133,8 @@ function observeSnapshot(value, seen) {
         seen.add("calendar");
     if (value.shift !== undefined)
         seen.add("shift");
+    if (value.phone !== undefined)
+        seen.add("phone");
 }
 function observeEvent(envelope, seen) {
     const event = isRecord(envelope) ? envelope.event : undefined;
@@ -168,6 +174,9 @@ function observeEvent(envelope, seen) {
         case "shift-updated":
             seen.add("shift");
             break;
+        case "phone-updated":
+            seen.add("phone");
+            break;
         default: break;
     }
 }
@@ -237,6 +246,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             self: current().identity.id,
             capabilities: current().capabilities,
             leadFeatures: leadFeaturesOn,
+            phone: context.phone,
             loginId: context.loginId,
             autoAcceptTasks: context.autoAcceptTasks,
             locked: options.lockedValues,
@@ -1074,7 +1084,7 @@ const REACHABLE_PHASES = {
 export const SUPERSEDED_BY_A_SNAPSHOT = new Set([
     "snapshot", "transport-status", "break-state", "task-offered", "task-updated", "task-ended",
     "task-audio-started", "task-audio-ended", "team-updated", "team-member-updated", "team-member-removed", "team-policies-updated",
-    "contacts-updated", "calendar-updated", "shift-updated",
+    "contacts-updated", "calendar-updated", "shift-updated", "phone-updated",
 ]);
 export class TaskStream {
     tasks = new Map();

package/dist/validation.d.ts

@@ -1,4 +1,4 @@
-import { type RecordingState, type Channel, type ProtocolViolation, type UserCapabilities, type UserId } from "./index.js";
+import { type RecordingState, type Channel, type Phone, type ProtocolViolation, type UserCapabilities, type UserId } from "./index.js";
 export type { ProtocolViolation } from "./index.js";
 export declare class ProtocolConformanceError extends Error {
     readonly violations: readonly ProtocolViolation[];
@@ -99,6 +99,11 @@ export interface ReaderContext {
     levels?: readonly string[];
     /** The login's `loginId`. A snapshot or event naming another belongs to a login that is gone. */
     loginId?: string;
+    /**
+     * The phone the host chose for this login at connect, `ConnectContext.phone`. A phone state
+     * naming another is the wrong phone. Unknown to a caller without the context, and then unchecked.
+     */
+    phone?: Phone;
     /**
      * Whether the lead has the team feature on, as the application last told the provider. The
      * provider assumes nothing until told: on, a snapshot carries the team; off, nothing of the
@@ -121,6 +126,8 @@ export declare function validateTeamMembers(teamMembers: unknown, path?: string,
 export declare function validateTeamMember(member: unknown, path?: string, context?: ReaderContext): ProtocolViolation[];
 export declare function validateSnapshot(snapshot: unknown, manifest: unknown, path?: string, context?: ReaderContext): ProtocolViolation[];
 export declare function validateEventEnvelope(envelope: unknown, manifest: unknown, path?: string, context?: ReaderContext): ProtocolViolation[];
+/** The phone as the platform sees it: the agent's device for this provider, whether it can take a call, its own mute where observed. */
+export declare function validatePhoneState(value: unknown, path?: string, context?: ReaderContext): ProtocolViolation[];
 /**
  * What pressing Mute does on this host, stated on a softphone login and nowhere else: on a desk
  * phone the microphone is the phone's, and off voice there is none. Neither the value nor its

package/dist/validation.js

@@ -87,6 +87,8 @@ const OFFERABLE_PHASES = membersOf({
 });
 const PREVIEW_DEADLINES = membersOf({ "provider-dials": true, "host-dials": true, waits: true });
 const PHONES = membersOf({ softphone: true, deskPhone: true });
+const PHONE_STATUSES = membersOf({ ready: true, unregistered: true, "do-not-disturb": true, "off-hook": true });
+const PHONE_CHANNEL_STATES = membersOf({ ringing: true, active: true, held: true });
 const LISTENING_MODES = membersOf({ listen: true, coach: true, "join-call": true });
 const COMPLETED_BY = membersOf({ agent: true, provider: true });
 const CANCELLED_BY = membersOf({ agent: true, provider: true, party: true });
@@ -369,6 +371,10 @@ function validatePhones(manifest, path, into) {
             into.add("manifest.phone.unique", `${path}[${index}]`, `duplicate phone: ${describeValue(phone)}`);
         }
     });
+    // Seeing the phone itself is declared by presence, and only where there is a phone to see.
+    if (manifest.phoneStatus !== undefined) {
+        into.require(manifest.phoneStatus === true, "manifest.phoneStatus", `${path.replace(/phones$/, "phoneStatus")}`, "phoneStatus is declared by presence, as true; a platform that cannot see the phone omits it");
+    }
 }
 /**
  * The host's choice of phone for a login, held to the manifest: one the platform listed, required
@@ -1742,6 +1748,9 @@ function validateTeamMemberInto(member, at, context, into) {
     // The member's own history for the day: about the person, not any one call.
     if (member.shift !== undefined)
         validateShiftInto(member.shift, `${at}.shift`, into, "team.member.shift");
+    // The member's phone as the platform sees it, the same state the member's own desk holds.
+    if (member.phone !== undefined)
+        validatePhoneStateInto(member.phone, `${at}.phone`, {}, into);
     // The member's standing ask for a lead, on one of the calls they hold.
     if (member.request !== undefined) {
         if (!isPlainObject(member.request)) {
@@ -1779,6 +1788,39 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
     // The agent's own day, as the provider counts it: the same numbers their lead sees.
     if (snapshot.shift !== undefined)
         validateShiftInto(snapshot.shift, `${path}.shift`, into, "shift");
+    // The phone as the platform sees it: owed by a provider that declares it can, and by nobody else.
+    const seesPhone = isPlainObject(manifest) && manifest.phoneStatus === true;
+    if (seesPhone && snapshot.phone === undefined) {
+        into.add("snapshot.phone.required", `${path}.phone`, "the manifest declares phoneStatus, so every snapshot carries the phone as the platform sees it");
+    }
+    else if (!seesPhone && snapshot.phone !== undefined && isPlainObject(manifest)) {
+        into.add("snapshot.phone.unexpected", `${path}.phone`, "the manifest declares no phoneStatus: a phone the platform never said it could see is one it invented");
+    }
+    if (snapshot.phone !== undefined) {
+        validatePhoneStateInto(snapshot.phone, `${path}.phone`, context, into);
+        // The two views of one call agree: a channel that is a task's stands where the task does.
+        if (isPlainObject(snapshot.phone) && Array.isArray(snapshot.phone.channels) && Array.isArray(snapshot.tasks)) {
+            const tasks = snapshot.tasks.filter(isPlainObject);
+            snapshot.phone.channels.forEach((channel, index) => {
+                if (!isPlainObject(channel) || !isAssignmentId(channel.assignmentId))
+                    return;
+                const here = `${path}.phone.channels[${index}]`;
+                const task = tasks.find(task => task.assignmentId === channel.assignmentId);
+                if (!into.require(task !== undefined, "phone.channel.assignment", `${here}.assignmentId`, `${String(channel.assignmentId)} is not a task this login holds: a channel names the task its call is, or nothing`))
+                    return;
+                const agrees = channel.state === "active" ? task.phase === "in-progress" && task.audio === "started"
+                    : channel.state === "held" ? task.phase === "paused"
+                        : task.phase === "pending" || (Array.isArray(task.onCall) && task.onCall.some((who) => isPlainObject(who) && who.role === "party" && who.stage === "ringing"));
+                into.require(agrees, "phone.channel.task", `${here}.state`, `the phone says ${String(channel.state)} and the task ${String(channel.assignmentId)} says ${String(task.phase)}${task.audio === undefined ? "" : ` with audio ${String(task.audio)}`}: the two views of one call agree`);
+            });
+            // And a task at work with audio has a channel: the phone carries every call the desk is on.
+            tasks.forEach((task, index) => {
+                if (task.audio === "started" && !snapshot.phone.channels.some(channel => isPlainObject(channel) && channel.assignmentId === task.assignmentId)) {
+                    into.add("phone.channel.missing", `${path}.tasks[${index}]`, `${String(task.assignmentId)} has its audio started and the phone carries no channel for it`);
+                }
+            });
+        }
+    }
     if (into.filled(snapshot.loginId, "snapshot.loginId", `${path}.loginId`, "a snapshot needs the login id it belongs to")
         && context.loginId !== undefined) {
         into.require(snapshot.loginId === context.loginId, "snapshot.loginId.mismatch", `${path}.loginId`, `a snapshot for session ${describeValue(snapshot.loginId)} on a login whose session is ${context.loginId}`);
@@ -2065,6 +2107,10 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
                 event.contacts.forEach((contact, index) => validateContactInto(contact, `${at}.contacts[${index}]`, into, levels));
             }
             break;
+        case "phone-updated":
+            into.require(isPlainObject(manifest) && manifest.phoneStatus === true, "event.phone.capability", `${at}.phone`, "phone-updated comes from a provider whose manifest declares phoneStatus");
+            validatePhoneStateInto(event.phone, `${at}.phone`, context, into);
+            break;
         case "shift-updated":
             validateShiftInto(event.shift, `${at}.shift`, into, "shift");
             break;
@@ -2146,6 +2192,54 @@ function requireClockInto(value, manifest, path, into) {
         return;
     into.add("manifest.timeCheck.required", path, "this publishes an instant the desk renders as a running duration -- a since, a signedInAt -- and the manifest declares no timeCheck: every screen counts such a duration from the provider's clock, so the provider states one");
 }
+/** The phone as the platform sees it: the agent's device for this provider, whether it can take a call, its own mute where observed. */
+export function validatePhoneState(value, path = "phone", context = {}) {
+    const into = new Collector();
+    validatePhoneStateInto(value, path, context, into);
+    return into.violations;
+}
+function validatePhoneStateInto(value, path, context, into) {
+    if (!isPlainObject(value)) {
+        into.add("phone.shape", path, "the phone state must be an object");
+        return;
+    }
+    if (into.oneOf(value.phone, PHONES, "phone.phone", `${path}.phone`) && context.phone !== undefined) {
+        into.require(value.phone === context.phone, "phone.phone.mismatch", `${path}.phone`, `the host chose a ${context.phone} for this login at connect and the platform reports a ${describeValue(value.phone)}: the phone state is the phone the agent hears this provider's calls on`);
+    }
+    into.oneOf(value.status, PHONE_STATUSES, "phone.status", `${path}.status`);
+    if (value.muted !== undefined) {
+        into.require(value.muted === true, "phone.muted", `${path}.muted`, "the phone's mute is stated by presence: send true or omit it");
+        // The softphone's microphone is the host's, and its mute is the host's report; the platform observes a desk phone's button, or nothing.
+        into.require(value.phone !== "softphone", "phone.muted.softphone", `${path}.muted`, "a softphone's microphone is the host's and its mute is the host's report; the platform echoes nothing of it");
+    }
+    if (value.since !== undefined)
+        into.timestamp(value.since, "phone.since", `${path}.since`);
+    // The phone's own calls: one active at most, any number held, and none on a phone that cannot carry one.
+    if (!Array.isArray(value.channels)) {
+        into.add("phone.channels.shape", `${path}.channels`, "channels is the phone's calls, an array: [] when idle");
+    }
+    else {
+        let active = 0;
+        value.channels.forEach((channel, index) => {
+            const here = `${path}.channels[${index}]`;
+            if (!isPlainObject(channel)) {
+                into.add("phone.channel.shape", here, "each channel must be an object");
+                return;
+            }
+            if (into.oneOf(channel.state, PHONE_CHANNEL_STATES, "phone.channel.state", `${here}.state`) && channel.state === "active")
+                active += 1;
+            into.timestamp(channel.since, "phone.channel.since", `${here}.since`);
+            if (channel.assignmentId !== undefined)
+                into.require(isAssignmentId(channel.assignmentId), "phone.channel.assignmentId", `${here}.assignmentId`, "assignmentId must name an assignment when present");
+            for (const key of Object.keys(channel))
+                into.require(["state", "since", "assignmentId"].includes(key), "phone.channel.field", `${here}.${key}`, "unsupported channel field");
+        });
+        into.require(active <= 1, "phone.channel.active.single", `${path}.channels`, `${active} channels are active: the phone has one active audio channel, and every other call on it is held`);
+        into.require(!((value.status === "unregistered" || value.status === "off-hook") && value.channels.length > 0), "phone.status.channels", `${path}.channels`, `a phone that is ${String(value.status)} carries no call`);
+    }
+    for (const key of Object.keys(value))
+        into.require(["phone", "status", "muted", "since", "channels"].includes(key), "phone.field", `${path}.${key}`, "unsupported phone state field");
+}
 function validateShiftInto(value, path, into, rule) {
     if (!isPlainObject(value)) {
         into.add(`${rule}.shape`, path, "shift must be an object when present");