@xema/omni-protocol 0.1.107 → 0.1.109

package/README.md

@@ -12,7 +12,7 @@ system.
 | Path | |
 | --- | --- |
 | `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. |
+| `guide/` | One file per role and channel: `agent.md`, `lead.md`, `queue.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
@@ -251,6 +296,12 @@ export declare const LISTENING_MODES: readonly ["listen", "coach", "join-call"];
 export interface UserCapabilities {
     /** This login may request a break. Requires the four break methods. */
     breaks?: true;
+    /**
+     * The platform lines calls up for this agent: the agent may press Next call while on one to
+     * have the next queued call put in their own queue, to start when their wrap ends unless
+     * somebody else takes it first. Requires `requestNextCall`, `cancelNextCall` and `releaseLinedUp`.
+     */
+    nextCall?: true;
     /** The choices the team left to this person, with where each stands. Omitted when there are none. Requires `setPreference`. */
     preferences?: AgentPreference[];
     /**
@@ -1273,6 +1324,53 @@ export type BreakEndResult = {
     status: "failed";
     failure: ProtocolFailure;
 };
+/**
+ * The agent's standing ask for the next call, made by pressing Next call while an assignment is
+ * at work. It lives only as long as its purpose: the provider clears it when a call is lined up,
+ * when the agent withdraws it, and when the assignment it was pressed on ends.
+ */
+export interface NextCallRequest {
+    since: IsoTimestamp;
+}
+/**
+ * A call waiting for this agent in their own queue: still in the platform's queue, not yet a task,
+ * ringing nothing. It starts when the agent's wrap ends, as an ordinary `task-offered` with
+ * `acceptance: "automatic"`, unless somebody else answered first or the caller gave up, and then
+ * the entry goes and no task ever was. One at a time: the phone only ever takes the next one.
+ * Lined up on the agent's ask, or on the platform's own routing -- a repeat caller put in front
+ * of the agent they spoke to last.
+ */
+export interface LinedUpCall {
+    /** The caller, as the provider shows them to this audience. */
+    party?: Contact;
+    /** The queue the call is in, by the platform's label. */
+    queue?: string;
+    /** When the caller entered the queue: their wait, counted from the provider's clock. */
+    queuedSince?: IsoTimestamp;
+    /** When the call was lined up for this agent. */
+    since: IsoTimestamp;
+    /** The agent may let this call go back to the queue for anyone: the provider's say, per call, by presence. */
+    release?: true;
+}
+/** `requested` says the provider holds the ask, not that anything is lined up. */
+export type NextCallResult = {
+    status: "requested";
+} | {
+    status: "failed";
+    failure: ProtocolFailure;
+};
+export type NextCallCancelResult = {
+    status: "cancelled";
+} | {
+    status: "failed";
+    failure: ProtocolFailure;
+};
+export type LinedUpReleaseResult = {
+    status: "released";
+} | {
+    status: "failed";
+    failure: ProtocolFailure;
+};
 /** `elsewhere`: signed in here, and the host holds this agent's capacity for another provider (`count: 0`, host-stopped); not receiving this provider's work. */
 export type TeamMemberAvailability = "ready" | "on-task" | "on-break" | "elsewhere" | "signed-out";
 export interface TeamMember {
@@ -1290,6 +1388,12 @@ 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;
+    /** The member's standing ask for the next call, as their own snapshot carries it. */
+    nextCall?: NextCallRequest;
+    /** The call lined up in the member's own queue, as their own snapshot carries it. */
+    linedUp?: LinedUpCall;
 }
 /** This member asking their lead to join a call: which assignment, the note they wrote, since when. */
 export interface MemberRequest {
@@ -1589,6 +1693,12 @@ 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;
+    /** The agent's standing ask for the next call, while it stands; replaced whole by `next-call`. */
+    nextCall?: NextCallRequest;
+    /** The call waiting in the agent's own queue, while one is; replaced whole by `lined-up`. */
+    linedUp?: LinedUpCall;
     team?: TeamMembers;
 }
 /**
@@ -1705,6 +1815,21 @@ 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 agent's ask for the next call as it now stands: present while it stands, absent once met, withdrawn or outlived. */
+ | {
+    type: "next-call";
+    nextCall?: NextCallRequest;
+}
+/** The agent's own queue as it now stands: the call lined up for them, or nothing. */
+ | {
+    type: "lined-up";
+    linedUp?: LinedUpCall;
 };
 /**
  * The `Provider` prefix survives here for a mechanical reason rather than a naming one: `Event`
@@ -1776,6 +1901,14 @@ export interface Connection<C extends Channel = Channel> {
     commitBreak?(): Promise<BreakCommitResult>;
     cancelBreak?(): Promise<BreakCancelResult>;
     endBreak?(): Promise<BreakEndResult>;
+    /**
+     * The three stand together with `capabilities.nextCall`. Next call asks for the next queued
+     * call to be lined up in the agent's own queue; cancel withdraws the ask before it is met;
+     * release lets a lined-up call go back to the queue for anyone, where the entry grants it.
+     */
+    requestNextCall?(): Promise<NextCallResult>;
+    cancelNextCall?(): Promise<NextCallCancelResult>;
+    releaseLinedUp?(): Promise<LinedUpReleaseResult>;
     /** Required when the login declares `capabilities.lead`: every lead act, on the team surface and nowhere else. */
     executeTeam?(request: TeamCommandRequest): Promise<TeamCommandResult>;
     /** Required of a voice adapter whose manifest lists `softphone`: on one, the call's audio lands in Omni. */

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. */
@@ -179,10 +181,11 @@ export function historyStepExpectsAPerson(step) {
 export function sameCapabilities(a, b) {
     // Every field, so a capability added later cannot be missed here: `satisfies` pins the field
     // list to the type, and a new key is a compile error until it is compared.
-    void { breaks: true, preferences: true, lead: true };
+    void { breaks: true, preferences: true, lead: true, nextCall: true };
     const preferences = (list) => list === undefined ? undefined : list.map(p => [p.id, p.label, p.enabled, p.setBy, p.lockedBy ?? "", p.reason ?? ""].join("\u0000")).sort().join("\u0001");
     return a.breaks === b.breaks &&
         a.lead === b.lead &&
+        a.nextCall === b.nextCall &&
         preferences(a.preferences) === preferences(b.preferences);
 }
 /**

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", "team.nextCall", "team.linedUp", "shift", "phone", "nextCall", "linedUp", "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,13 @@ const STATE_SUBJECTS = [
     "team.tasks",
     "team.listening",
     "team.shift",
+    "team.phone",
+    "team.nextCall",
+    "team.linedUp",
     "shift",
+    "phone",
+    "nextCall",
+    "linedUp",
     "contacts",
     "calendar",
     "team.policies",
@@ -39,7 +45,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, "next-call": true, "lined-up": true,
 };
 const CONTRACT_SUBJECTS = [
     ...STATE_SUBJECTS,
@@ -101,6 +107,12 @@ function observeMember(member, seen) {
         seen.add("team.shift");
     if (member.request !== undefined)
         seen.add("team.request");
+    if (member.phone !== undefined)
+        seen.add("team.phone");
+    if (member.nextCall !== undefined)
+        seen.add("team.nextCall");
+    if (member.linedUp !== undefined)
+        seen.add("team.linedUp");
 }
 function observePolicies(value, seen) {
     if (isRecord(value) && Object.keys(value).length > 0)
@@ -129,6 +141,12 @@ function observeSnapshot(value, seen) {
         seen.add("calendar");
     if (value.shift !== undefined)
         seen.add("shift");
+    if (value.phone !== undefined)
+        seen.add("phone");
+    if (value.nextCall !== undefined)
+        seen.add("nextCall");
+    if (value.linedUp !== undefined)
+        seen.add("linedUp");
 }
 function observeEvent(envelope, seen) {
     const event = isRecord(envelope) ? envelope.event : undefined;
@@ -168,6 +186,17 @@ function observeEvent(envelope, seen) {
         case "shift-updated":
             seen.add("shift");
             break;
+        case "phone-updated":
+            seen.add("phone");
+            break;
+        case "next-call":
+            if (event.nextCall !== undefined)
+                seen.add("nextCall");
+            break;
+        case "lined-up":
+            if (event.linedUp !== undefined)
+                seen.add("linedUp");
+            break;
         default: break;
     }
 }
@@ -237,6 +266,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,
@@ -265,6 +295,12 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             }
             if (capabilities.lead === true)
                 requireMethod(on, "executeTeam", "the login declares capabilities.lead");
+            if (capabilities.nextCall === true) {
+                // The ask, its withdrawal and the release stand together: a lined-up call the agent could neither withdraw nor let go is a promise with no way out.
+                for (const method of ["requestNextCall", "cancelNextCall", "releaseLinedUp"]) {
+                    requireMethod(on, method, "the login declares capabilities.nextCall");
+                }
+            }
             if (some(capabilities.preferences))
                 requireMethod(on, "setPreference", "the login declares capabilities.preferences");
         };
@@ -1074,7 +1110,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", "next-call", "lined-up",
 ]);
 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,12 @@ 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 agent's standing ask for the next call: since when. */
+export declare function validateNextCall(value: unknown, path?: string): ProtocolViolation[];
+/** A call waiting in the agent's own queue: the caller as shown to this audience, the queue, the waits, and whether the agent may let it go. */
+export declare function validateLinedUp(value: unknown, path?: string, levels?: readonly string[]): 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
@@ -154,7 +165,7 @@ export declare function validateTaskCommandRequest(request: unknown, task: unkno
  */
 export declare function validateTaskCommand(command: unknown, task?: unknown, path?: string, taskContext?: Omit<TaskValidationContext, "channel">): ProtocolViolation[];
 /** The connection methods whose results `validateResult` knows. */
-export type ResultMethod = "execute" | "dial" | "setCapacity" | "requestBreak" | "commitBreak" | "cancelBreak" | "endBreak" | "executeTeam" | "openAudio" | "setPreference" | "recordStep";
+export type ResultMethod = "execute" | "dial" | "setCapacity" | "requestBreak" | "commitBreak" | "cancelBreak" | "endBreak" | "requestNextCall" | "cancelNextCall" | "releaseLinedUp" | "executeTeam" | "openAudio" | "setPreference" | "recordStep";
 /**
  * Validates what a connection method answered. A result is untrusted for the same reason a
  * snapshot is: it comes from an adapter that may be compiled against another version, and Omni

package/dist/validation.js

@@ -78,7 +78,7 @@ const DIALLING_CAPABILITIES = ["connectBack", "conference"];
 const SNAPSHOT_REASONS = membersOf({
     reconnected: true, "provider-requested": true,
 });
-const SESSION_CAPABILITIES = membersOf({ breaks: true, lead: true, preferences: true });
+const SESSION_CAPABILITIES = membersOf({ breaks: true, lead: true, preferences: true, nextCall: true });
 const MEMBER_BREAKS = membersOf({
     "awaiting-approval": true, granted: true, "starting-after-task": true,
 });
@@ -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,14 @@ 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 own queue, as their own snapshot carries it.
+    if (member.nextCall !== undefined)
+        validateNextCallInto(member.nextCall, `${at}.nextCall`, into);
+    if (member.linedUp !== undefined)
+        validateLinedUpInto(member.linedUp, `${at}.linedUp`, into, context.levels);
     // 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 +1793,47 @@ 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;
+    // The agent's own queue: an ask needs an assignment at work to be next after, and one call at most waits.
+    if (snapshot.nextCall !== undefined) {
+        validateNextCallInto(snapshot.nextCall, `${path}.nextCall`, into);
+        const atWork = Array.isArray(snapshot.tasks) && snapshot.tasks.some((task) => isPlainObject(task) && (task.phase === "in-progress" || task.phase === "paused" || task.phase === "completing"));
+        into.require(atWork, "snapshot.nextCall.idle", `${path}.nextCall`, "an ask for the next call stands only while an assignment is at work to be next after: the provider clears it when that assignment ends");
+    }
+    if (snapshot.linedUp !== undefined)
+        validateLinedUpInto(snapshot.linedUp, `${path}.linedUp`, into, levels);
+    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 +2120,18 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
                 event.contacts.forEach((contact, index) => validateContactInto(contact, `${at}.contacts[${index}]`, into, levels));
             }
             break;
+        case "next-call":
+            if (event.nextCall !== undefined)
+                validateNextCallInto(event.nextCall, `${at}.nextCall`, into);
+            break;
+        case "lined-up":
+            if (event.linedUp !== undefined)
+                validateLinedUpInto(event.linedUp, `${at}.linedUp`, 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 +2213,92 @@ 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 agent's standing ask for the next call: since when. */
+export function validateNextCall(value, path = "nextCall") {
+    const into = new Collector();
+    validateNextCallInto(value, path, into);
+    return into.violations;
+}
+function validateNextCallInto(value, path, into) {
+    if (!isPlainObject(value)) {
+        into.add("nextCall.shape", path, "the ask must be an object");
+        return;
+    }
+    into.timestamp(value.since, "nextCall.since", `${path}.since`);
+    for (const key of Object.keys(value))
+        into.require(key === "since", "nextCall.field", `${path}.${key}`, "unsupported field on the ask");
+}
+/** A call waiting in the agent's own queue: the caller as shown to this audience, the queue, the waits, and whether the agent may let it go. */
+export function validateLinedUp(value, path = "linedUp", levels) {
+    const into = new Collector();
+    validateLinedUpInto(value, path, into, levels);
+    return into.violations;
+}
+function validateLinedUpInto(value, path, into, levels) {
+    if (!isPlainObject(value)) {
+        into.add("linedUp.shape", path, "a lined-up call must be an object");
+        return;
+    }
+    if (value.party !== undefined)
+        validateContactInto(value.party, `${path}.party`, into, levels);
+    if (value.queue !== undefined)
+        into.filled(value.queue, "linedUp.queue", `${path}.queue`, "the queue's label must not be empty when present");
+    if (value.queuedSince !== undefined)
+        into.timestamp(value.queuedSince, "linedUp.queuedSince", `${path}.queuedSince`);
+    into.timestamp(value.since, "linedUp.since", `${path}.since`);
+    if (value.release !== undefined)
+        into.require(value.release === true, "linedUp.release", `${path}.release`, "letting the call go is granted by presence: send true or omit it");
+    for (const key of Object.keys(value))
+        into.require(["party", "queue", "queuedSince", "since", "release"].includes(key), "linedUp.field", `${path}.${key}`, "unsupported field on a lined-up call");
+}
+/** 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");
@@ -2696,6 +2849,9 @@ const RESULT_STATUSES = {
     commitBreak: { success: "committed", failure: "failed" },
     cancelBreak: { success: "cancelled", failure: "failed" },
     endBreak: { success: "ended", failure: "failed" },
+    requestNextCall: { success: "requested", failure: "failed" },
+    cancelNextCall: { success: "cancelled", failure: "failed" },
+    releaseLinedUp: { success: "released", failure: "failed" },
     executeTeam: { success: "applied", failure: "failed" },
     openAudio: { success: "opened", failure: "unavailable" },
     setPreference: { success: "applied", failure: "failed" },

package/guide/agent.md

@@ -381,6 +381,8 @@ 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`) |
+| the agent's readiness for the next call read into setCapacity | the agent's own queue: `capabilities.nextCall`, `requestNextCall`/`cancelNextCall`/`releaseLinedUp`, `Snapshot.nextCall` and `linedUp`, the `next-call` and `lined-up` events (`snapshot.nextCall.idle`, `nextCall.*`, `linedUp.*`) |
 
 Update producers, consumers, saved task snapshots, and validation-rule assertions together.
 History and report rule names use `history` and `historyReport`; assignment rules use