@xema/omni-protocol 0.1.107 → 0.1.108

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");

package/guide/agent.md

@@ -381,6 +381,7 @@ Migration from the earlier spellings:
 | MemberTask.capabilities, capabilitySource, browsers | gone: the workspace never travels to a lead (`team.member.task.workspace`); the record and the completion terms do |
 | a member republished on a hold, a mute, a take-over | on every publication of the member's task to the member |
 | two clients on one login | the later wins; the first is ended with `recovery: "displaced"` |
+| the phone unspoken | `PhoneState` -- the device, its mute, its channels -- on `Snapshot.phone`, `phone-updated` and `TeamMember.phone`, from a manifest declaring `phoneStatus` (`snapshot.phone.required`, `.unexpected`, `phone.*`, `phone.channel.*`, `event.phone.capability`) |
 
 Update producers, consumers, saved task snapshots, and validation-rule assertions together.
 History and report rule names use `history` and `historyReport`; assignment rules use

package/guide/lead.md

@@ -32,6 +32,7 @@ computes nothing. See **`team-updated`** in `guide.md` and its companions.
 | `tasks` | The member's open tasks as `MemberTask`s: the same task the member's desk holds, less the workspace. The assignment, title, task type, phase, party, room, audio and completion terms -- `completionMode`, `wrapAllowance`, `wrapEndsInSeconds` -- are what the lead reads, and the task's record -- `history`, steps and totals -- travels whole, exactly as the member's desk holds it, so the lead's screen and the member's show the same record. The workspace -- `capabilities`, `capabilitySource`, `browsers` and their URLs -- is the member's desk's alone and never travels (`team.member.task.workspace`). The party's number and email are shown to leads or locked as the provider decides for leads, apart from what it decides for the member -- see **What the queue locks is locked on the whole task**. `[]` when the member holds none; omitted only where the provider cannot see them. |
 | `listening` | Every lead on this member's call — listening, coaching or joined — published to every lead alike: each entry names the lead by `leadId`, which of the member's calls by `assignmentId`, the `mode` they are heard in, and since when. The entry naming the signed-in lead is what their own audio opens on. Absent while nobody is on the call, never `[]` (`team.member.listening.*`); a lead is on one member's call at a time (`team.listening.single`), and a lead who is heard is also in the task's `onCall` (`team.member.listening.heard`). |
 | `request` | Present while the member is asking a lead to join one of their calls: which assignment, the note they wrote, since when. The call named is one their `tasks` carry (`team.member.request.assignment`). Absent when they are not asking. See **Lead assist**. |
+| `phone` | The member's phone as the platform sees it: the same `PhoneState` the member's own snapshot carries, so a lead sees a desk phone that is down, or a call on it that is no task, as the member does. Present where the provider declares `phoneStatus`. See **The phone's own view** in `guide/phone.md`. |
 | `shift` | The member's own history for the day, about the person rather than any one call: `signedInAt`, `signedOutAt` once it has happened, today's totals as the provider counts them — `talkSeconds`, `holdSeconds`, `breakSeconds`, `tasksHandled`, each present only when the provider knows it — and the day's sign-in, sign-out and break `events`, oldest first. The same `Shift` the member's own snapshot carries, the same numbers from the same count. Omitted where the provider cannot say. |
 
 Each availability value means one thing:

package/guide/phone.md

@@ -272,3 +272,68 @@ call, the same line in the ready state, so an agent does not learn of it from a
 whether work is held back is the adapter's decision from the report, as it is for every station
 fact. Where a provider's own platform holds a mute of its own -- a bridge that silences a leg --
 that is a fact about the switch, reported as the provider sees fit, and never the agent application's Mute.
+
+### The phone's own view
+
+There are two views of a call, and the contract carries both. The task side says which calls are
+the agent's work and where each stands: the phase, the audio, the room. The phone side is the
+device: whether it can take a call at all, its own mute, and the calls on it, which exist whether
+or not a task is behind them -- an internal call on the extension, a lead's listening leg, a call
+the platform put on the phone that the desk never saw as a task. The host's report covers neither:
+it says what the station has, a microphone and a speaker, and cannot say whether the phone is
+registered. The platform sees the phone, so this is the provider's to publish, as `Snapshot.phone`
+and `phone-updated`, from a manifest that declares `phoneStatus` (`snapshot.phone.required`,
+`snapshot.phone.unexpected`, `event.phone.capability`).
+
+```ts
+// a conference in progress on alloc-42 -- one channel, since the bridge mixes -- with alloc-43 parked
+const busy: PhoneState = { phone: "deskPhone", status: "ready", muted: true, channels: [
+  { state: "active", since: "2026-09-12T10:30:04Z", assignmentId: "alloc-42" },
+  { state: "held", since: "2026-09-12T10:35:20Z", assignmentId: "alloc-43" },
+] };
+// an internal call on the extension the desk never saw as a task
+const internal: PhoneState = { phone: "deskPhone", status: "ready", channels: [{ state: "active", since: "2026-09-12T11:02:00Z" }] };
+// a desk phone the platform lost
+const down: PhoneState = { phone: "deskPhone", status: "unregistered", since: "2026-09-12T10:41:00Z", channels: [] };
+```
+
+**The device.** `status` is the phone itself: `ready` is registered and usable, idle or busy, and
+the other three are the states in which nothing can land, each wanting a different fix.
+
+| `status` | Meaning |
+| --- | --- |
+| `ready` | Registered and usable, idle or busy. |
+| `unregistered` | The platform has lost the phone: no registration from the extension, no route to the handset. Nothing can land, and no channel is on it (`phone.status.channels`). |
+| `do-not-disturb` | The agent pressed it on the device. Nothing lands until they clear it; it is not a break, and the provider assigns or not as its platform does. |
+| `off-hook` | The handset is up with no call on it, and no channel is on it. |
+
+`phone` is the agent's device for this provider: the one the host chose for the login at
+connect, from the manifest's phones, as the way the agent hears this provider's calls. A state
+naming the other is the wrong phone (`phone.phone.mismatch`). The phone is the agent's; the login
+is the agent's session with the provider, and what belongs to the login is that choice. `since` is when the status began, counted from the
+provider's clock like every duration off the active call, and omitted rather than invented.
+
+**The channels.** The phone has one active audio channel and any number held
+(`phone.channel.active.single`), and a bridge is one channel: a conference is one entry, and its
+members are on the task's `onCall`, never repeated here. Each channel is `ringing`, `active` or
+`held`, since when, and names the task its call is where it is one. **Where a channel is a task's,
+the two views agree** (`phone.channel.task`): `active` with the task at work and its audio
+started, `held` with the task `paused`, `ringing` with the task `pending` or its party ringing on
+`onCall`; and a task with its audio started has a channel (`phone.channel.missing`), since the
+phone carries every call the desk is on. A channel naming no task is the phone's alone, and the
+desk shows it as a call it cannot act on.
+
+**The mute is the phone's, and it silences whatever is active.** It is one flag on the phone, not
+a property of a channel: whichever channel is active is silent while it is set, and the held
+channels are unaffected. Who owns it follows the phone. On a desk phone the mute button is the
+handset's, and the platform observes it or does not: `muted: true` where it does, absent where it
+does not, never invented. On a softphone the microphone is the host's, its mute is the host's
+report as **The station is the agent application's** sets out, and nothing the provider publishes
+moves it: `muted` on a softphone's state is the platform echoing the host, and is refused
+(`phone.muted.softphone`). The `muted` step in the record stays what it is, the account of a leg,
+never the live flag.
+
+**The lead sees the member's phone as the member does.** The member on the team member list
+carries the same `PhoneState`, republished with the member on every change, so a desk phone that
+is down, or a call on it that is no task, shows the same on both screens, and neither derives it
+from anything else.

package/guide.md

@@ -199,6 +199,24 @@ type DialOutcome = "answered" | "busy" | "no-answer" | "unreachable" | "rejected
 
 type Phone = "softphone" | "deskPhone";
 
+type PhoneStatus = "ready" | "unregistered" | "do-not-disturb" | "off-hook";
+
+type PhoneChannelState = "ringing" | "active" | "held";
+
+type PhoneChannel = {
+  state: PhoneChannelState;
+  since: IsoTimestamp;
+  assignmentId?: AssignmentId;
+};
+
+type PhoneState = {
+  phone: Phone;
+  status: PhoneStatus;
+  muted?: true;
+  since?: IsoTimestamp;
+  channels: PhoneChannel[];
+};
+
 type IdleCapabilities<C extends Channel = Channel> = {
   personalBrowser?: PersonalBrowserCapability;
   calendar?: true;
@@ -219,6 +237,7 @@ type Manifest<C extends Channel = Channel> = {
   orgLevels?: LevelDeclaration[];
   dialOutcomes?: C extends "voice" ? DialOutcome[] : never;
   phones?: C extends "voice" ? Phone[] : never;
+  phoneStatus?: C extends "voice" ? true : never;
   runningStepReports?: true;
   settleMs: number;
 };
@@ -498,6 +517,7 @@ type Snapshot = {
   contacts?: Contact[];
   calendar?: ScheduledActivity[];
   shift?: Shift;
+  phone?: PhoneState;
   team?: TeamMembers;
 };
 
@@ -1006,6 +1026,7 @@ type TeamMember = {
   listening?: MemberListening[];
   shift?: Shift;
   request?: MemberRequest;
+  phone?: PhoneState;
 };
 
 type MemberRequest = {
@@ -1162,7 +1183,8 @@ type ProviderEvent =
   | { type: "team-policies-updated"; policies: TeamPolicies }
   | { type: "contacts-updated"; contacts: Contact[] }
   | { type: "calendar-updated"; calendar: ScheduledActivity[] }
-  | { type: "shift-updated"; shift: Shift };
+  | { type: "shift-updated"; shift: Shift }
+  | { type: "phone-updated"; phone: PhoneState };
 
 type ProviderEventEnvelope = {
   id: string;
@@ -1654,6 +1676,7 @@ compile time.
 | `taskTypePresentation` | Optional static adapter-defined presentation keyed by exact `taskType`. It names the item and its optional agent-facing reference. |
 | `orgLevels` | The organisation's whole ladder as the provider calls it, each level with the label a desk shows for "who decided". Stated outright, `person` included: what it leaves out does not exist. Omitted for the typical four, `DEFAULT_LEVELS`. See **Who decides what an agent may do**. |
 | `phones` | Voice only, and required there: the phones this platform can put an agent on, `softphone` (the call's audio lands in the agent application) and/or `deskPhone` (a handset the platform rings; the agent application shows the call and opens nothing). The agent application picks one per login. See **How the agent hears the call** in `guide/phone.md`. |
+| `phoneStatus` | Voice only, declared by presence as `true`: the platform sees the phone itself -- its registration, its do-not-disturb, its hook, its calls -- and publishes it as `Snapshot.phone` and `phone-updated`. A platform that cannot see the phone omits it, and then publishes no phone (`manifest.phoneStatus`). See **The phone's own view** in `guide/phone.md`. |
 | `dialOutcomes` | Voice only. How a dial can end on this platform, as it distinguishes them: `answered` and at least one way of not reaching the destination. Required of a provider that dials at all — an idle dialpad, or tasks that conference or call back — and a `dial-outcome` carries only a declared member. See **Every dial has an outcome** in `guide/voice.md`. |
 | `timeCheck` | `true`: implements `checkTime` and states `providerTime` on every snapshot. Required of a provider that publishes an instant the desk renders as a running duration -- a member's `since`, a `listening[].since`, an `onCall.since`, a shift's `signedInAt` -- so every screen counts from the provider's clock (`manifest.timeCheck.required`); agent application polling is independently opt-in. See **Every screen counts from the provider's clock**. |
 | `timestampAuthority` | Optional `"provider"`: provider timestamps are final; agent application instants are advisory. Omission makes no trust promise. |
@@ -2183,6 +2206,7 @@ a capability it agrees with the login: a lead's snapshot carries `team`, nobody
 | `taskCount` | The provider's own count of those tasks, stated rather than inferred, and it must equal `tasks.length`. A snapshot with no work says `taskCount: 0` in so many words — a blank or unanswered state lacks the count and cannot pass as a confirmed empty. |
 | `contacts` | Required complete contact contribution when the manifest declares `contacts`; `[]` clears it. Omitted only when it does not. |
 | `calendar` | Required complete calendar contribution when the manifest declares `calendar`; `[]` clears it. Omitted only when it does not. |
+| `phone` | The phone as the platform sees it -- the device, whether it can take a call, its own mute where observed -- from a provider whose manifest declares `phoneStatus`; required there (`snapshot.phone.required`) and forbidden otherwise (`snapshot.phone.unexpected`). Replaced whole by `phone-updated`. See **The phone's own view** in `guide/phone.md`. |
 | `shift` | The agent's own day so far, as the provider counts it -- the same `Shift` their lead sees on the team member list, the same numbers from the same count. Replaced whole by `shift-updated`. Omitted only where the provider cannot say. See **The agent's day is on the wire**. |
 | `team` | Required `TeamMembers` when the login declares `capabilities.lead` and the lead has the team feature on, `members: []` when nobody is in it. Forbidden otherwise — the login is the permission, and a lead who turned the feature off gets nothing of the team. |
 
@@ -2743,6 +2767,14 @@ the `contacts` idle capability.
 Replaces this provider's complete scheduled-activity contribution. It is emitted only when the manifest
 declares the `calendar` idle capability.
 
+### `phone-updated`
+
+The phone as the platform now sees it, whole, replacing `Snapshot.phone`: a registration lost or
+back, do-not-disturb pressed or cleared, the handset lifted with no call or replaced, the desk
+phone's own mute. Emitted only by a provider whose manifest declares `phoneStatus`
+(`event.phone.capability`). The lead's member carries the same `PhoneState`, republished with the
+member. See **The phone's own view** in `guide/phone.md`.
+
 ### `shift-updated`
 
 The agent's own day, whole, replacing `Snapshot.shift`: emitted whenever a total moves -- a task

package/package.json

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