@xema/omni-protocol 0.1.108 → 0.1.110

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

@@ -296,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[];
     /**
@@ -1318,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 {
@@ -1337,6 +1390,10 @@ export interface TeamMember {
     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 {
@@ -1638,6 +1695,10 @@ export interface Snapshot<C extends Channel = Channel> {
     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;
 }
 /**
@@ -1759,6 +1820,16 @@ export type ProviderEvent<C extends Channel = Channel> = {
  | {
     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`
@@ -1830,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

@@ -181,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", "team.phone", "shift", "phone", "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

@@ -29,8 +29,12 @@ const STATE_SUBJECTS = [
     "team.listening",
     "team.shift",
     "team.phone",
+    "team.nextCall",
+    "team.linedUp",
     "shift",
     "phone",
+    "nextCall",
+    "linedUp",
     "contacts",
     "calendar",
     "team.policies",
@@ -41,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, "phone-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,
@@ -105,6 +109,10 @@ function observeMember(member, seen) {
         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)
@@ -135,6 +143,10 @@ function observeSnapshot(value, seen) {
         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;
@@ -177,6 +189,14 @@ function observeEvent(envelope, seen) {
         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;
     }
 }
@@ -275,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");
         };
@@ -408,6 +434,16 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                         message: `a task was offered with ${stream.openCount()} already open against a stated capacity of ${capacityStated}` });
                 }
             }
+            // The agent's own queue lives within capacity: told count 0, the provider clears the ask and
+            // lets the lined-up call go, so an entry published after that is a promise it cannot keep.
+            if (capacityStated === 0 && isRecord(envelope?.event)) {
+                if (envelope.event.type === "next-call" && envelope.event.nextCall !== undefined) {
+                    violations.push({ rule: "stream.nextCall.stopped", path: "event.nextCall", message: "an ask for the next call was published after the host stated count 0: the agent's capacity is elsewhere, and the ask is cleared with it" });
+                }
+                if (envelope.event.type === "lined-up" && envelope.event.linedUp !== undefined) {
+                    violations.push({ rule: "stream.linedUp.stopped", path: "event.linedUp", message: "a call was lined up after the host stated count 0: the agent's capacity is elsewhere, and the call goes back to the queue for anyone" });
+                }
+            }
             // A re-delivered envelope is harmless and applied once; the same id carrying a different
             // payload is a reused id, which no dedupe can make harmless, and is named.
             if (typeof envelope?.id === "string") {
@@ -1084,7 +1120,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", "phone-updated",
+    "contacts-updated", "calendar-updated", "shift-updated", "phone-updated", "next-call", "lined-up",
 ]);
 export class TaskStream {
     tasks = new Map();

package/dist/validation.d.ts

@@ -126,6 +126,10 @@ 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[];
 /**
@@ -161,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,
 });
@@ -1751,6 +1751,11 @@ function validateTeamMemberInto(member, at, context, into) {
     // 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)) {
@@ -1790,6 +1795,21 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
         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: the ask and the lined-up call need an assignment at work to be next
+    // after, and neither stands beside a break the agent asked for or was put on -- the break wins.
+    const atWork = Array.isArray(snapshot.tasks) && snapshot.tasks.some((task) => isPlainObject(task) && (task.phase === "in-progress" || task.phase === "paused" || task.phase === "completing"));
+    const breakStatus = isPlainObject(snapshot.break) ? snapshot.break.status : undefined;
+    const breakStands = typeof breakStatus === "string" && breakStatus !== "not-requested";
+    if (snapshot.nextCall !== undefined) {
+        validateNextCallInto(snapshot.nextCall, `${path}.nextCall`, into);
+        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");
+        into.require(!breakStands, "snapshot.nextCall.break", `${path}.nextCall`, `an ask for the next call does not stand beside a break that is ${String(breakStatus)}: the break wins, and the provider clears the ask`);
+    }
+    if (snapshot.linedUp !== undefined) {
+        validateLinedUpInto(snapshot.linedUp, `${path}.linedUp`, into, levels);
+        into.require(atWork, "snapshot.linedUp.idle", `${path}.linedUp`, "a call is lined up for an agent with an assignment at work; with nothing at work it is an offer, and travels as task-offered");
+        into.require(!breakStands, "snapshot.linedUp.break", `${path}.linedUp`, `a lined-up call does not stand beside a break that is ${String(breakStatus)}: the break wins, and the call goes back to the queue for anyone`);
+    }
     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");
     }
@@ -2107,6 +2127,14 @@ 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);
@@ -2192,6 +2220,44 @@ 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();
@@ -2790,6 +2856,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

@@ -382,6 +382,7 @@ Migration from the earlier spellings:
 | 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

package/guide/breaks.md

@@ -250,291 +250,9 @@ against it (`stream.taskOffered.overCapacity`).
 idle dialpad arrives through `task-offered` like any other task, and a full agent does not forbid
 it: the ceiling binds assignment, not the agent's own hand.
 
-### Runtime break prerequisite checks
-
-Use `validateBreakCommand(method, request, state, context)` from the validation entry point
-before any agent break dispatch. The context supplies current authentication and transport;
-all four methods require the live login's break capability and active transport. Pass the
-request object only to the request method, and undefined to the other three.
-
-| Method | Required current state |
-| --- | --- |
-| `requestBreak` | `not-requested`; selected current reason code when codes exist; `canRequestBreak` or the selected reason's `alwaysAvailable` exception. Free text does not replace a code. |
-| `commitBreak` | `granted`, or already committed for an idempotent repeat. A later change to `canRequestBreak` does not revoke the grant. |
-| `cancelBreak` | `awaiting-approval` or `granted`. A concurrent commit winning still answers `omni.break-already-committed` and requires recovery. |
-| `endBreak` | `on-break` or `starting-after-task` during reconciliation; the agent may explicitly end a requested or forced break. |
-
-Use `validateTeamCommand(request, context)` before every lead act: the team feature switch, break
-decisions, forcing and ending a forced break, policy, and every act on a member's call. It requires
-the live `lead` flag and active transport, a current team member list for any command naming a
-member, and the target's complete break state for forcing/ending a break. Approve/deny requires an
-awaiting decision; forcing a break uses the target's reason codes; ending a forced break requires a
-forced committed break; join and decline need the member's request on the list; coach, join-call
-and leave need the lead already on that member's call; an assignment named must be one the list
-shows the member holding. The context's target state must belong to the named member; that
-association and backend authorization are provider responsibilities.
-
-Use `validateBreakStatus(state, tasks)` on the complete retained task view after each transaction,
-as well as `validateBreakTransition` for event ordering. Snapshot validation shares the status
-checks. Pending and completing tasks still count as work. Only a call a lead took over
-(`takenOver`) sits beside a break in effect. Validate full task shapes and the envelope separately.
-
-These validators report violations without dispatching, rewriting state or proving freshness.
-Recheck prerequisites atomically at the provider; client validation cannot prevent a race.
-Continue to use `validateResult` for each method's response vocabulary. A request acknowledgment
-is not a grant, and no method response overwrites a newer state emission. Rejected promises
-remain unknown and recover by snapshot, not automatic retry. The agent application's frozen provider set,
-durable mutually exclusive commit/cancel decision and reconciliation obligations under
-**Coordinating a multi-provider break** remain
-required; per-provider validation does not implement the multi-provider coordinator.
-
-### `requestBreak(request)`
-
-**Explanatory text is optional.** An agent may omit `BreakRequest.reason` for any break type.
-A lead may likewise omit reason text from `force-break`. Do not require a text explanation
-just because a break is agent-requested or forced. If supplied, text must be nonempty; omit
-it rather than sending an empty string. A selected `reasonId` identifies a published break
-choice and is separate from this optional text.
-
-With published choices, `{ reasonId: "lunch" }` is a valid request without explanation;
-without published choices, `{}` is valid. A lead can similarly send a `force-break` command
-with its member ID and, where required, the selected reason ID, without reason text.
-
-Requests permission to stop the agent later; it does not itself stop work. The provider continues
-offering work and reports `awaiting-approval` or `granted` through `break-state` events. If the request is denied, the
-provider reports `not-requested` directly, with `decisionReason` when one was supplied.
-
-**An agent asks from anywhere — idle or on a task** — and Omni offers the request in the task
-workspace as it does on the idle dashboard. Asked on a task, the break is decided and committed like
-any other and begins when the work ends: that is `starting-after-task`, and
-`assertBreakBeginsAfterTask` is the scenario that holds a provider to it.
-
-#### Break reasons
-
-A provider that defines not-ready reason codes publishes them on `Snapshot.break.reasons`,
-and Omni returns the agent's choice as `BreakRequest.reasonId`:
-
-```ts
-break: {
-  reasons: [
-    { id: "lunch", label: "Lunch" },
-    { id: "training", label: "Training", group: "Scheduled" },
-  ]
-}
-```
-
-Reason ids are non-empty and unique within the provider. They live on the snapshot rather than the
-manifest because a provider may change the codes it offers during a shift; a `snapshot` event
-replaces the list. `BreakRequest.reason` remains available for free text and is never a substitute
-for `reasonId` when the provider publishes codes. A provider that defines no codes omits the
-field.
-
-#### One break across several providers
-
-An agent connected to several providers takes **one** break, not one per platform. Omni gathers
-what every connected provider offers, shows the distinct breaks, and on a choice sends one request
-per provider: the same `reason`, and each provider's own `reasonId`.
-
-To do that, Omni has to know when two providers mean the same break. Say so with `kind`:
-
-```ts
-break: {
-  reasons: [
-    { id: "lunch", label: "Lunch", kind: "meal" },
-    { id: "rest",  label: "Mandatory rest period", kind: "rest", alwaysAvailable: true },
-  ]
-}
-```
-
-A provider decides which breaks it offers and what it calls them. `BREAK_KINDS` is the list Omni
-supports mapping them onto, and every member means something specific:
-
-| Kind | What it means |
-| --- | --- |
-| `short-break` | A brief rest between contacts — the comfort break a shift plan allows for. |
-| `meal` | A meal: lunch, dinner, whatever the shift calls it. |
-| `rest` | A rest period the agent is entitled to and a busy hour cannot cancel. Usually the reason also marked `alwaysAvailable`, though the two are separate: this says what the break *is*, that says whether policy can withdraw it. |
-| `training` | Learning something the agent is expected to know afterwards: a course, e-learning, a product walkthrough. However it is delivered, and whoever attends. |
-| `coaching` | Reviewing this agent's own work with somebody accountable for it: a call listened back, quality feedback, a one-to-one about their interactions. Even where the outcome is that they learn something. |
-| `meeting` | A scheduled gathering that is neither — a team huddle, a project call, a town hall. The agent attends and contributes; nobody is assessing their work and there is nothing they must know by the end. |
-| `administrative` | Paperwork and follow-up not attached to a particular contact. |
-| `technical` | Equipment or system trouble stopping the agent taking work: a dead headset, a phone that never registered, a tool that will not load. The one member that is not an activity — it says why the agent *cannot* work rather than what they are doing, which makes it the right home for a not-ready state raised about the agent's equipment. |
-| `personal` | Personal time the deployment does not classify further. |
-| `other` | None of the above. Matches nothing, including another provider's `other`. |
-
-**The definitions are the point, not decoration.** Ten undefined strings would be the label
-problem one level up: two providers could both declare `technical`, one meaning a dead headset
-and the other scheduled maintenance, match on it, and nothing could tell the difference.
-
-`training`, `coaching` and `meeting` can all fit one session, so take them in that order of
-specificity: about this agent's own work is `coaching`, else something they must know afterwards is
-`training`, else `meeting`.
-
-**A break somebody forced on the agent is not automatically one of these.** Where the agent was
-stopped rather than choosing to stop — see **Forced breaks** — set `BreakState.forced` and prefer
-omitting `kind` to reaching for `other`. None of the ten describes "something was done to this
-agent", and `other` claims a classification that was never made.
-
-Omni matches in this order:
-
-1. **`kind`**, where both providers declare one. This wins over the label, so `{ id: "MEAL",
-   label: "Meal", kind: "meal" }` lines up with `{ id: "lunch", label: "Lunch", kind: "meal" }`
-   and nobody has to word their codes the same way.
-2. **The label**, folded for case and surrounding spacing, where a kind is missing. `"other"`
-   counts as missing: two providers saying `"other"` have only said their break is not on the
-   list, which is no evidence they mean the same thing.
-
-Nothing else is matched. A break Omni cannot pair stays on its own, the agent is told how many
-platforms their break will actually reach, and they can pair the odd one by hand — Omni remembers
-that for next time.
-
-Three rules for a provider:
-
-- **Declare `kind` where you can, and leave it out where you cannot.** Leaving it out costs a
-  little precision. Getting it wrong sends an agent to lunch on one platform and to training on
-  another, and nothing can detect that.
-- **You may publish several reasons of one kind** — two meal slots, say. Omni will not choose
-  between them for the agent; saying they are the same kind is not saying they are interchangeable.
-- **Do not read `reason` as your own label.** It is the agent's single choice, in whichever
-  provider's wording they picked it from, sent unchanged to every provider in the break.
-
-A provider that publishes no reason codes still receives the request, with `reason` set and
-`reasonId` omitted.
-
-#### Coordinating a multi-provider break
-
-Sending the requests is a two-phase operation, not independent best effort. A provider first grants
-permission for the agent to stop, then Omni either commits or cancels that permission.
-
-`granted` is provider-visible state. It means only that this provider has granted the active
-request and is ready to stop the agent when Omni asks. It does not reveal that other providers exist
-or why Omni has not committed yet. While reporting `granted`, the provider remains available,
-continues to honour Omni's current capacity, and continues offering work normally.
-
-Omni separately tracks the aggregate agent application states `working`, `requesting-break`, `committing-break`,
-`cancelling-break`, and `on-break`. While `requesting-break`, Omni shows which providers remain
-outstanding and offers **Cancel break request**, but does not tell the agent that their break has
-begun.
-
-Omni offers the aggregate Break control only when every provider currently holding capacity
-declares `capabilities.breaks` at login. If one cannot be stopped, offering a global break would
-knowingly permit partial availability.
-
-Omni coordinates one break attempt as follows:
-
-1. Freeze the providers the attempt asks: every connected provider from which the agent can
-   currently receive work. A provider joining during the attempt is given no capacity until it
-   finishes. A provider whose authentication is `expired` is not one the agent can receive work
-   from and is not asked: nothing is asked of it, the break proceeds without it, and when the
-   login is restored it is reconciled from its snapshot as a set-aside provider is, with no
-   capacity until then. `refreshing` keeps a provider in — its identity and capabilities remain
-   available and work continues. `assertBreakAttemptProviders` holds an agent application to this set.
-2. Enter `requesting-break`. Keep the agent's normal capacity in place throughout this phase.
-3. Send one `requestBreak` to every asked provider. A provider reports `awaiting-approval` or
-   `granted`; neither state stops work. A denial transitions directly to `not-requested` and
-   causes Omni to take the cancel path.
-4. If every asked provider reports `granted`, durably choose commit, enter `committing-break`,
-   and send `commitBreak()` to each of them. A provider then stops offering new work
-   and reports `starting-after-task` or `on-break`. The **commit bound** — ten seconds from the
-   decision, tunable per deployment — decides who is kept: a provider that has not applied the
-   commit by then, still `granted` or unreachable, is set aside as unreconciled and the break
-   begins without it. `on-break` decides `on-break`: Omni enters it once every kept provider
-   reports `on-break`. A kept provider reporting `starting-after-task` has applied the commit
-   and is finishing a task; the bound is on delivery, not on that task. Omni shows the break as
-   settled and beginning when the task ends, and offers no cancel, because the commit is durable.
-5. If any asked provider fails or denies the request, cannot be reconciled within the bounded
-   decision timeout, or the agent cancels before commit, durably choose cancel and enter
-   `cancelling-break`. Send `cancelBreak()` to every provider still reporting
-   `awaiting-approval` or `granted`. Work continues during cancellation because no stop was
-   committed. Return to `working` only after no provider retains either state.
-
-Commit and cancel are mutually exclusive decisions for one break attempt. Once Omni chooses commit
-it never rolls that attempt back: it is reconciled by snapshot until every asked provider is stopped.
-A provider that reports `granted` must therefore preserve the request across reconnects and must
-honour a later commit or cancel. This
-durable promise prevents a provider from failing the commit after another provider has already
-stopped the agent.
-
-#### Why the commit phase is bounded and the decision is not
-
-Waiting for unanimity forever is the one way this algorithm can strand an agent. The commit is
-durable and cannot be rolled back, so a provider that crashes, has its authentication revoked,
-or is uninstalled between granting and committing would hold Omni in `committing-break` with no
-exit: the providers that did commit have already stopped the agent, and the agent is neither
-working nor on a break.
-
-Unanimity is required for a reason that survives the bound. It exists so the agent is not stopped
-on one platform while another keeps routing work to them — and **a provider Omni cannot reach is
-routing nothing.** Setting it aside therefore costs none of the property it was protecting. Waiting
-for it costs the agent their break.
-
-Setting a provider aside is not a rollback and not a cancel. The commit stands and the
-obligation stands: until that provider is stopped it has not stopped. When it returns it emits a
-snapshot before anything else, and the snapshot decides:
-
-- `on-break` or `starting-after-task` — the commit arrived after all. Nothing to send.
-- still `granted` — the commit was lost. Omni sends `commitBreak()` now. If the original turns up
-  late behind it, the provider stops an agent who is already stopped; nothing happens, because a
-  commit is a state to be in, not an act to be done.
-- `not-requested` — the grant did not survive. Omni makes a new request for that provider alone,
-  against an agent who is already on break elsewhere. **A new login is this case too**: the grant
-  belonged to the old session.
-
-The provider must not offer work in the meantime, and the commit is what stops it; Omni gives it
-no capacity until it is reconciled.
-
-**If the agent has already ended the break elsewhere, the break attempt is over** and the returning
-provider is reconciled to that instead: still `granted` gets `cancelBreak()`, because committing
-would stop an agent who is working again; `starting-after-task` or `on-break` gets `endBreak()`.
-Never rolling back is about a break that is still on, not one the agent has finished.
-
-Omni may tell the agent which platforms the break has not yet reached, as it already does when a
-break cannot be paired across every provider.
-
-The decision phase needs no such bound, because nothing has stopped. Work continues throughout
-`requesting-break`, so a provider that never answers costs the agent a wait rather than their
-availability, and the existing decision timeout resolves it by cancelling — which is safe precisely
-because no stop was ever committed.
-
-If cancel races with a late approval, the provider remains on the cancel path. If commit has already
-won, cancel returns `omni.break-already-committed`, and Omni resumes commit recovery rather than
-returning the agent to `working`.
-
-A forced break is not rolled back by this algorithm. If one appears during either the request or
-cancellation, the attempt is abandoned: Omni cancels every grant still outstanding and states
-`setCapacity({ count: 0 })` on every other usable provider, as **Forced breaks** sets out; no grant
-is committed, because the agent has already stopped everywhere.
-
-This is two-phase coordination across vendor systems: the approval phase keeps the agent working;
-the durable commit decision and snapshot reconciliation provide convergence after partial delivery.
-
-#### Reporting the break the agent is on
-
-`BreakState.activeReasonId` is the `BreakReason.id` the current break is on. Omni remembers what it
-asked for, but only until the session ends — after a reload or reconnect, or where the provider put
-the agent on the break itself, the provider is the only one who knows.
-
-Omit it when you cannot say, and when there is no break: reporting a reason alongside
-`status: "not-requested"` describes a break that is not happening, and is rejected.
-
-### `cancelBreak()`
-
-Cancels the active pre-commit request while its status is `awaiting-approval` or `granted`.
-Cancellation releases the request but does not restore work because work never stopped. If
-commit already won, the provider returns `omni.break-already-committed`. The resulting state is
-reported through `break-state`.
-
-### `commitBreak()`
-
-Commits the `granted` request. Once the provider has reported `granted`, it cannot fail for a
-business reason. On commit the provider stops offering new work and reports
-`starting-after-task` while existing work finishes, or `on-break` when the break is in effect.
-Committing a break that is already in effect changes nothing and answers `committed`.
-
-### `endBreak()`
-
-Tells a provider that an agent already on a break wants to become available again. The provider
-reports the resulting state through `break-state` and provider status events.
-
-It ends the break, which is the thing that started. Nothing about the connection was ever paused,
-so there is nothing on it to resume.
+**Capacity is not the agent's readiness.** It is the desk's division of one person across
+providers, a ceiling on assignments at once, and it says nothing about the moment. An agent who
+is about to finish a call and wants the next one lined up has a different thing to say, and says
+it as **The agent's own queue** in `guide/queue.md` sets out; the ceiling stands unchanged while they do,
+and the queue lives within it: `count: 0` clears the ask and lets a lined-up call go, and a break
+in flight or in effect does the same, since the break wins.

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**. |
+| `nextCall`, `linedUp` | The member's own queue as their own snapshot carries it: their standing ask for the next call, and the call lined up for them. See **The agent's own queue** in `guide/queue.md`. |
 | `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. |
 

package/guide/queue.md

@@ -0,0 +1,378 @@
+# `@xema/omni-protocol`: The agent's own queue
+
+The next call, lined up for this agent while they finish the one they are on: the ask, the lined-up call, and the release. Part of the contract in `guide.md`, which holds the terms, the shapes and the rules every file here relies on; a reference in bold names the file it points into where that is not this one.
+
+## The agent's own queue
+
+The phone takes one call at a time, so "I am ready for the next one" cannot mean a second
+assignment now. It means: line the next queued call up for me, to start the moment my wrap ends,
+unless somebody else takes it first. That is a queue of the agent's own, one deep, beside the
+platform's queue and never instead of it, and the contract carries it in three parts: the ask,
+the lined-up call, and the release.
+
+```ts
+// the login declares it, as it declares breaks
+{ status: "authenticated", identity: {...}, capabilities: { breaks: true, nextCall: true } }
+
+// 1. The ask. The agent presses Next call during the call or the wrap; the desk offers the button
+//    when it sees fit -- past the midpoint of the handling time is one way.
+await connection.requestNextCall()
+// -> { status: "requested" }: the provider holds the ask; nothing is promised
+{ type: "next-call", nextCall: { since: "2026-09-12T10:41:00Z" } }
+
+// 2. The lined-up call. The provider fills the ask from its queue: a caller waiting for this agent,
+//    still in the queue, not a task, ringing nothing.
+{ type: "next-call" }   // the ask is met
+{ type: "lined-up", linedUp: { party: { name: "Priya S", number: { lockedBy: "org" } }, queue: "Billing", queuedSince: "2026-09-12T10:39:20Z", since: "2026-09-12T10:41:30Z", release: true } }
+
+// The agent's wrap ends and the call is theirs: the entry goes and the task arrives, as any assignment does.
+{ type: "task-ended", assignmentId: "alloc-42", outcome: { type: "completed", by: "agent" } }
+{ type: "lined-up" }
+{ type: "task-offered", task: { assignmentId: "alloc-57", phase: "pending", acceptance: "automatic", party: {...}, history: { steps: [{ step: "queued", at: "2026-09-12T10:39:20Z", seconds: 131 }] }, ... } }
+
+// Or somebody else answered first, or the caller gave up: the entry goes and no task ever was.
+{ type: "lined-up" }
+
+// 3. The release. Where the entry grants it, the agent lets the call go back to the queue for anyone.
+await connection.releaseLinedUp()
+// -> { status: "released" }, then { type: "lined-up" } with nothing
+```
+
+**The ask lives only as long as its purpose.** It needs an assignment at work to be next after,
+so an idle agent has nothing to press (`snapshot.nextCall.idle`), and the provider clears it on
+its own when that assignment ends, when a call is lined up to meet it, and when the agent
+withdraws it with `cancelNextCall()`. The desk never keeps it past any of those. `requested` says
+the provider holds the ask, not that a call will come: a queue may be empty.
+
+**The queue lives within capacity, and never beside a break.** The ask and the lined-up call are
+promises to assign, and a promise the provider can no longer keep goes:
+
+- **Told `count: 0`**, host-stopped, the provider assigns nothing, so it clears the ask and lets the
+  lined-up call go back to the queue for anyone; an entry published after that is refused
+  (`stream.nextCall.stopped`, `stream.linedUp.stopped`). The queue is per provider, as the ask
+  was made on that provider's call, and the desk's division of capacity is what it was.
+- **A break wins.** An agent who has asked for a break, been granted one starting after this
+  task, or been put on one has said the opposite of "line up my next call", and the two never
+  stand together: while a break is in flight or in effect -- any status but `not-requested` --
+  `requestNextCall()` is refused with `omni.unavailable`, and a break arriving after a
+  call was lined up drops the call, the caller going back to the queue for anyone
+  (`snapshot.nextCall.break`, `snapshot.linedUp.break`). The desk shows Next call or the break
+  controls, never both.
+- **A lined-up call needs an agent at work** as the ask does: a call lined up for an agent with
+  nothing at work is an offer that has not been made, and travels as `task-offered`
+  (`snapshot.linedUp.idle`). The repeat caller for an idle agent is an ordinary offer.
+
+**The lined-up call is not a task, and rides no task event.** Until the offer there is no
+assignment and nothing to accept, so it has no phase, no capabilities and no history, and it
+rings nothing: the caller is still in the platform's queue, the phone has no channel for it, and
+the desk shows "next for you" and nothing to act on but the release. It becomes a task by the
+ordinary `task-offered`, with `acceptance: "automatic"` since the agent asked, and counts against
+capacity from that moment as any assignment does; the `queued` step in its history carries the
+caller's whole wait. One at a time: the phone only ever takes the next one, so `linedUp` is an
+object, not a list. Nothing is guaranteed: the queue may give the call to whoever is free first,
+and then the entry goes and no task ever was.
+
+**A repeat caller is the same shape, unasked.** A provider whose routing prefers the agent a
+caller spoke to last lines the call up for that agent without a press, so they see it in their own
+queue and can take it before another agent does. The ask is only what the agent adds on top of
+the platform's routing: releasing one call, or withdrawing the ask, ends nothing of that routing,
+and the provider may line a repeat caller up again.
+
+**Letting go is the provider's say.** `release: true` on the lined-up call grants the agent Let
+go; absent, the platform means them to take the call and the desk offers nothing
+(`linedUp.release`). `releaseLinedUp()` against an entry without it is refused with
+`omni.capability-not-enabled`, as any control the provider did not grant. `cancelNextCall()`
+withdraws the ask alone: once a call is lined up the ask is met, and what happens to that call is
+the release.
+
+**The lead sees the member's queue as the member does.** The member on the team member list
+carries `nextCall` and `linedUp` as the member's own snapshot does, republished with the member.
+
+### Runtime break prerequisite checks
+
+Use `validateBreakCommand(method, request, state, context)` from the validation entry point
+before any agent break dispatch. The context supplies current authentication and transport;
+all four methods require the live login's break capability and active transport. Pass the
+request object only to the request method, and undefined to the other three.
+
+| Method | Required current state |
+| --- | --- |
+| `requestBreak` | `not-requested`; selected current reason code when codes exist; `canRequestBreak` or the selected reason's `alwaysAvailable` exception. Free text does not replace a code. |
+| `commitBreak` | `granted`, or already committed for an idempotent repeat. A later change to `canRequestBreak` does not revoke the grant. |
+| `cancelBreak` | `awaiting-approval` or `granted`. A concurrent commit winning still answers `omni.break-already-committed` and requires recovery. |
+| `endBreak` | `on-break` or `starting-after-task` during reconciliation; the agent may explicitly end a requested or forced break. |
+
+Use `validateTeamCommand(request, context)` before every lead act: the team feature switch, break
+decisions, forcing and ending a forced break, policy, and every act on a member's call. It requires
+the live `lead` flag and active transport, a current team member list for any command naming a
+member, and the target's complete break state for forcing/ending a break. Approve/deny requires an
+awaiting decision; forcing a break uses the target's reason codes; ending a forced break requires a
+forced committed break; join and decline need the member's request on the list; coach, join-call
+and leave need the lead already on that member's call; an assignment named must be one the list
+shows the member holding. The context's target state must belong to the named member; that
+association and backend authorization are provider responsibilities.
+
+Use `validateBreakStatus(state, tasks)` on the complete retained task view after each transaction,
+as well as `validateBreakTransition` for event ordering. Snapshot validation shares the status
+checks. Pending and completing tasks still count as work. Only a call a lead took over
+(`takenOver`) sits beside a break in effect. Validate full task shapes and the envelope separately.
+
+These validators report violations without dispatching, rewriting state or proving freshness.
+Recheck prerequisites atomically at the provider; client validation cannot prevent a race.
+Continue to use `validateResult` for each method's response vocabulary. A request acknowledgment
+is not a grant, and no method response overwrites a newer state emission. Rejected promises
+remain unknown and recover by snapshot, not automatic retry. The agent application's frozen provider set,
+durable mutually exclusive commit/cancel decision and reconciliation obligations under
+**Coordinating a multi-provider break** remain
+required; per-provider validation does not implement the multi-provider coordinator.
+
+### `requestBreak(request)`
+
+**Explanatory text is optional.** An agent may omit `BreakRequest.reason` for any break type.
+A lead may likewise omit reason text from `force-break`. Do not require a text explanation
+just because a break is agent-requested or forced. If supplied, text must be nonempty; omit
+it rather than sending an empty string. A selected `reasonId` identifies a published break
+choice and is separate from this optional text.
+
+With published choices, `{ reasonId: "lunch" }` is a valid request without explanation;
+without published choices, `{}` is valid. A lead can similarly send a `force-break` command
+with its member ID and, where required, the selected reason ID, without reason text.
+
+Requests permission to stop the agent later; it does not itself stop work. The provider continues
+offering work and reports `awaiting-approval` or `granted` through `break-state` events. If the request is denied, the
+provider reports `not-requested` directly, with `decisionReason` when one was supplied.
+
+**An agent asks from anywhere — idle or on a task** — and Omni offers the request in the task
+workspace as it does on the idle dashboard. Asked on a task, the break is decided and committed like
+any other and begins when the work ends: that is `starting-after-task`, and
+`assertBreakBeginsAfterTask` is the scenario that holds a provider to it.
+
+#### Break reasons
+
+A provider that defines not-ready reason codes publishes them on `Snapshot.break.reasons`,
+and Omni returns the agent's choice as `BreakRequest.reasonId`:
+
+```ts
+break: {
+  reasons: [
+    { id: "lunch", label: "Lunch" },
+    { id: "training", label: "Training", group: "Scheduled" },
+  ]
+}
+```
+
+Reason ids are non-empty and unique within the provider. They live on the snapshot rather than the
+manifest because a provider may change the codes it offers during a shift; a `snapshot` event
+replaces the list. `BreakRequest.reason` remains available for free text and is never a substitute
+for `reasonId` when the provider publishes codes. A provider that defines no codes omits the
+field.
+
+#### One break across several providers
+
+An agent connected to several providers takes **one** break, not one per platform. Omni gathers
+what every connected provider offers, shows the distinct breaks, and on a choice sends one request
+per provider: the same `reason`, and each provider's own `reasonId`.
+
+To do that, Omni has to know when two providers mean the same break. Say so with `kind`:
+
+```ts
+break: {
+  reasons: [
+    { id: "lunch", label: "Lunch", kind: "meal" },
+    { id: "rest",  label: "Mandatory rest period", kind: "rest", alwaysAvailable: true },
+  ]
+}
+```
+
+A provider decides which breaks it offers and what it calls them. `BREAK_KINDS` is the list Omni
+supports mapping them onto, and every member means something specific:
+
+| Kind | What it means |
+| --- | --- |
+| `short-break` | A brief rest between contacts — the comfort break a shift plan allows for. |
+| `meal` | A meal: lunch, dinner, whatever the shift calls it. |
+| `rest` | A rest period the agent is entitled to and a busy hour cannot cancel. Usually the reason also marked `alwaysAvailable`, though the two are separate: this says what the break *is*, that says whether policy can withdraw it. |
+| `training` | Learning something the agent is expected to know afterwards: a course, e-learning, a product walkthrough. However it is delivered, and whoever attends. |
+| `coaching` | Reviewing this agent's own work with somebody accountable for it: a call listened back, quality feedback, a one-to-one about their interactions. Even where the outcome is that they learn something. |
+| `meeting` | A scheduled gathering that is neither — a team huddle, a project call, a town hall. The agent attends and contributes; nobody is assessing their work and there is nothing they must know by the end. |
+| `administrative` | Paperwork and follow-up not attached to a particular contact. |
+| `technical` | Equipment or system trouble stopping the agent taking work: a dead headset, a phone that never registered, a tool that will not load. The one member that is not an activity — it says why the agent *cannot* work rather than what they are doing, which makes it the right home for a not-ready state raised about the agent's equipment. |
+| `personal` | Personal time the deployment does not classify further. |
+| `other` | None of the above. Matches nothing, including another provider's `other`. |
+
+**The definitions are the point, not decoration.** Ten undefined strings would be the label
+problem one level up: two providers could both declare `technical`, one meaning a dead headset
+and the other scheduled maintenance, match on it, and nothing could tell the difference.
+
+`training`, `coaching` and `meeting` can all fit one session, so take them in that order of
+specificity: about this agent's own work is `coaching`, else something they must know afterwards is
+`training`, else `meeting`.
+
+**A break somebody forced on the agent is not automatically one of these.** Where the agent was
+stopped rather than choosing to stop — see **Forced breaks** — set `BreakState.forced` and prefer
+omitting `kind` to reaching for `other`. None of the ten describes "something was done to this
+agent", and `other` claims a classification that was never made.
+
+Omni matches in this order:
+
+1. **`kind`**, where both providers declare one. This wins over the label, so `{ id: "MEAL",
+   label: "Meal", kind: "meal" }` lines up with `{ id: "lunch", label: "Lunch", kind: "meal" }`
+   and nobody has to word their codes the same way.
+2. **The label**, folded for case and surrounding spacing, where a kind is missing. `"other"`
+   counts as missing: two providers saying `"other"` have only said their break is not on the
+   list, which is no evidence they mean the same thing.
+
+Nothing else is matched. A break Omni cannot pair stays on its own, the agent is told how many
+platforms their break will actually reach, and they can pair the odd one by hand — Omni remembers
+that for next time.
+
+Three rules for a provider:
+
+- **Declare `kind` where you can, and leave it out where you cannot.** Leaving it out costs a
+  little precision. Getting it wrong sends an agent to lunch on one platform and to training on
+  another, and nothing can detect that.
+- **You may publish several reasons of one kind** — two meal slots, say. Omni will not choose
+  between them for the agent; saying they are the same kind is not saying they are interchangeable.
+- **Do not read `reason` as your own label.** It is the agent's single choice, in whichever
+  provider's wording they picked it from, sent unchanged to every provider in the break.
+
+A provider that publishes no reason codes still receives the request, with `reason` set and
+`reasonId` omitted.
+
+#### Coordinating a multi-provider break
+
+Sending the requests is a two-phase operation, not independent best effort. A provider first grants
+permission for the agent to stop, then Omni either commits or cancels that permission.
+
+`granted` is provider-visible state. It means only that this provider has granted the active
+request and is ready to stop the agent when Omni asks. It does not reveal that other providers exist
+or why Omni has not committed yet. While reporting `granted`, the provider remains available,
+continues to honour Omni's current capacity, and continues offering work normally.
+
+Omni separately tracks the aggregate agent application states `working`, `requesting-break`, `committing-break`,
+`cancelling-break`, and `on-break`. While `requesting-break`, Omni shows which providers remain
+outstanding and offers **Cancel break request**, but does not tell the agent that their break has
+begun.
+
+Omni offers the aggregate Break control only when every provider currently holding capacity
+declares `capabilities.breaks` at login. If one cannot be stopped, offering a global break would
+knowingly permit partial availability.
+
+Omni coordinates one break attempt as follows:
+
+1. Freeze the providers the attempt asks: every connected provider from which the agent can
+   currently receive work. A provider joining during the attempt is given no capacity until it
+   finishes. A provider whose authentication is `expired` is not one the agent can receive work
+   from and is not asked: nothing is asked of it, the break proceeds without it, and when the
+   login is restored it is reconciled from its snapshot as a set-aside provider is, with no
+   capacity until then. `refreshing` keeps a provider in — its identity and capabilities remain
+   available and work continues. `assertBreakAttemptProviders` holds an agent application to this set.
+2. Enter `requesting-break`. Keep the agent's normal capacity in place throughout this phase.
+3. Send one `requestBreak` to every asked provider. A provider reports `awaiting-approval` or
+   `granted`; neither state stops work. A denial transitions directly to `not-requested` and
+   causes Omni to take the cancel path.
+4. If every asked provider reports `granted`, durably choose commit, enter `committing-break`,
+   and send `commitBreak()` to each of them. A provider then stops offering new work
+   and reports `starting-after-task` or `on-break`. The **commit bound** — ten seconds from the
+   decision, tunable per deployment — decides who is kept: a provider that has not applied the
+   commit by then, still `granted` or unreachable, is set aside as unreconciled and the break
+   begins without it. `on-break` decides `on-break`: Omni enters it once every kept provider
+   reports `on-break`. A kept provider reporting `starting-after-task` has applied the commit
+   and is finishing a task; the bound is on delivery, not on that task. Omni shows the break as
+   settled and beginning when the task ends, and offers no cancel, because the commit is durable.
+5. If any asked provider fails or denies the request, cannot be reconciled within the bounded
+   decision timeout, or the agent cancels before commit, durably choose cancel and enter
+   `cancelling-break`. Send `cancelBreak()` to every provider still reporting
+   `awaiting-approval` or `granted`. Work continues during cancellation because no stop was
+   committed. Return to `working` only after no provider retains either state.
+
+Commit and cancel are mutually exclusive decisions for one break attempt. Once Omni chooses commit
+it never rolls that attempt back: it is reconciled by snapshot until every asked provider is stopped.
+A provider that reports `granted` must therefore preserve the request across reconnects and must
+honour a later commit or cancel. This
+durable promise prevents a provider from failing the commit after another provider has already
+stopped the agent.
+
+#### Why the commit phase is bounded and the decision is not
+
+Waiting for unanimity forever is the one way this algorithm can strand an agent. The commit is
+durable and cannot be rolled back, so a provider that crashes, has its authentication revoked,
+or is uninstalled between granting and committing would hold Omni in `committing-break` with no
+exit: the providers that did commit have already stopped the agent, and the agent is neither
+working nor on a break.
+
+Unanimity is required for a reason that survives the bound. It exists so the agent is not stopped
+on one platform while another keeps routing work to them — and **a provider Omni cannot reach is
+routing nothing.** Setting it aside therefore costs none of the property it was protecting. Waiting
+for it costs the agent their break.
+
+Setting a provider aside is not a rollback and not a cancel. The commit stands and the
+obligation stands: until that provider is stopped it has not stopped. When it returns it emits a
+snapshot before anything else, and the snapshot decides:
+
+- `on-break` or `starting-after-task` — the commit arrived after all. Nothing to send.
+- still `granted` — the commit was lost. Omni sends `commitBreak()` now. If the original turns up
+  late behind it, the provider stops an agent who is already stopped; nothing happens, because a
+  commit is a state to be in, not an act to be done.
+- `not-requested` — the grant did not survive. Omni makes a new request for that provider alone,
+  against an agent who is already on break elsewhere. **A new login is this case too**: the grant
+  belonged to the old session.
+
+The provider must not offer work in the meantime, and the commit is what stops it; Omni gives it
+no capacity until it is reconciled.
+
+**If the agent has already ended the break elsewhere, the break attempt is over** and the returning
+provider is reconciled to that instead: still `granted` gets `cancelBreak()`, because committing
+would stop an agent who is working again; `starting-after-task` or `on-break` gets `endBreak()`.
+Never rolling back is about a break that is still on, not one the agent has finished.
+
+Omni may tell the agent which platforms the break has not yet reached, as it already does when a
+break cannot be paired across every provider.
+
+The decision phase needs no such bound, because nothing has stopped. Work continues throughout
+`requesting-break`, so a provider that never answers costs the agent a wait rather than their
+availability, and the existing decision timeout resolves it by cancelling — which is safe precisely
+because no stop was ever committed.
+
+If cancel races with a late approval, the provider remains on the cancel path. If commit has already
+won, cancel returns `omni.break-already-committed`, and Omni resumes commit recovery rather than
+returning the agent to `working`.
+
+A forced break is not rolled back by this algorithm. If one appears during either the request or
+cancellation, the attempt is abandoned: Omni cancels every grant still outstanding and states
+`setCapacity({ count: 0 })` on every other usable provider, as **Forced breaks** sets out; no grant
+is committed, because the agent has already stopped everywhere.
+
+This is two-phase coordination across vendor systems: the approval phase keeps the agent working;
+the durable commit decision and snapshot reconciliation provide convergence after partial delivery.
+
+#### Reporting the break the agent is on
+
+`BreakState.activeReasonId` is the `BreakReason.id` the current break is on. Omni remembers what it
+asked for, but only until the session ends — after a reload or reconnect, or where the provider put
+the agent on the break itself, the provider is the only one who knows.
+
+Omit it when you cannot say, and when there is no break: reporting a reason alongside
+`status: "not-requested"` describes a break that is not happening, and is rejected.
+
+### `cancelBreak()`
+
+Cancels the active pre-commit request while its status is `awaiting-approval` or `granted`.
+Cancellation releases the request but does not restore work because work never stopped. If
+commit already won, the provider returns `omni.break-already-committed`. The resulting state is
+reported through `break-state`.
+
+### `commitBreak()`
+
+Commits the `granted` request. Once the provider has reported `granted`, it cannot fail for a
+business reason. On commit the provider stops offering new work and reports
+`starting-after-task` while existing work finishes, or `on-break` when the break is in effect.
+Committing a break that is already in effect changes nothing and answers `committed`.
+
+### `endBreak()`
+
+Tells a provider that an agent already on a break wants to become available again. The provider
+reports the resulting state through `break-state` and provider status events.
+
+It ends the break, which is the thing that started. Nothing about the connection was ever paused,
+so there is nothing on it to resume.

package/guide.md

@@ -25,6 +25,7 @@ every cross-reference names the file it points into.
 | `guide/phone.md` | **The phone.** How the agent hears the call: softphone and desk phone, the station and its headset, opening the audio, the microphone and the record. |
 | `guide/chat.md` | **Chat.** What is true of a chat and of nothing else. |
 | `guide/email.md` | **Email.** What is true of an email and of nothing else. |
+| `guide/queue.md` | **The agent's own queue.** The next call, lined up for this agent while they finish the one they are on: the ask, the lined-up call, and the release. |
 | `guide/breaks.md` | **Breaks.** Asking for a break, a break forced on the agent, capacity, and one break across several providers. |
 | `guide/lead.md` | **Team leads.** The lead's own surface: the team member list, the lead's commands, lead assist, listening to a call. |
 
@@ -292,6 +293,7 @@ type UserCapabilities = {
   breaks?: true;
   preferences?: AgentPreference[];
   lead?: true;
+  nextCall?: true;
 };
 
 type AuthenticationState =
@@ -518,6 +520,8 @@ type Snapshot = {
   calendar?: ScheduledActivity[];
   shift?: Shift;
   phone?: PhoneState;
+  nextCall?: NextCallRequest;
+  linedUp?: LinedUpCall;
   team?: TeamMembers;
 };
 
@@ -1010,6 +1014,30 @@ type BreakCancelResult =
 type BreakEndResult =
   | { status: "ended" }
   | { status: "failed"; failure: ProtocolFailure };
+
+type NextCallRequest = {
+  since: IsoTimestamp;
+};
+
+type LinedUpCall = {
+  party?: Contact;
+  queue?: string;
+  queuedSince?: IsoTimestamp;
+  since: IsoTimestamp;
+  release?: true;
+};
+
+type NextCallResult =
+  | { status: "requested" }
+  | { status: "failed"; failure: ProtocolFailure };
+
+type NextCallCancelResult =
+  | { status: "cancelled" }
+  | { status: "failed"; failure: ProtocolFailure };
+
+type LinedUpReleaseResult =
+  | { status: "released" }
+  | { status: "failed"; failure: ProtocolFailure };
 ```
 
 ### Team
@@ -1027,6 +1055,8 @@ type TeamMember = {
   shift?: Shift;
   request?: MemberRequest;
   phone?: PhoneState;
+  nextCall?: NextCallRequest;
+  linedUp?: LinedUpCall;
 };
 
 type MemberRequest = {
@@ -1184,7 +1214,9 @@ type ProviderEvent =
   | { type: "contacts-updated"; contacts: Contact[] }
   | { type: "calendar-updated"; calendar: ScheduledActivity[] }
   | { type: "shift-updated"; shift: Shift }
-  | { type: "phone-updated"; phone: PhoneState };
+  | { type: "phone-updated"; phone: PhoneState }
+  | { type: "next-call"; nextCall?: NextCallRequest }
+  | { type: "lined-up"; linedUp?: LinedUpCall };
 
 type ProviderEventEnvelope = {
   id: string;
@@ -1237,6 +1269,9 @@ type Connection<C extends Channel = Channel> = {
   commitBreak?(): Promise<BreakCommitResult>;
   cancelBreak?(): Promise<BreakCancelResult>;
   endBreak?(): Promise<BreakEndResult>;
+  requestNextCall?(): Promise<NextCallResult>;
+  cancelNextCall?(): Promise<NextCallCancelResult>;
+  releaseLinedUp?(): Promise<LinedUpReleaseResult>;
 
   executeTeam?(request: TeamCommandRequest): Promise<TeamCommandResult>;
   openAudio?(request: OpenAudioRequest): Promise<OpenAudioResult>;
@@ -1990,6 +2025,7 @@ to infer them from what arrives later.
 | Field | Contract |
 | --- | --- |
 | `breaks` | This login may request a break. Requires the four break methods on the connection. |
+| `nextCall` | The platform lines calls up for this agent: pressing Next call while on a call puts the next queued call in the agent's own queue, to start when their wrap ends unless somebody else takes it first. Requires `requestNextCall`, `cancelNextCall` and `releaseLinedUp` on the connection. See **The agent's own queue** in `guide/queue.md`. |
 | `lead` | This login leads a team. The flag alone turns on the team feature in the agent application, and every lead act comes with it; there is no per-action permission beside it. While the lead has the feature on, the provider publishes a `TeamMembers` object to them on every snapshot — `members: []` when nobody is in it — and to nobody else. Requires `executeTeam`. See **Team leads** in `guide/lead.md`. |
 | `preferences` | What the team left to this person, with where each stands and who set it. Omitted when nothing was. Requires `setPreference`. See **Who decides what an agent may do**. |
 
@@ -2207,6 +2243,8 @@ a capability it agrees with the login: a lead's snapshot carries `team`, nobody
 | `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`. |
+| `nextCall` | The agent's standing ask for the next call, while it stands: `since`. It needs an assignment at work to be next after (`snapshot.nextCall.idle`) and the provider clears it when that assignment ends, when a call is lined up, and when the agent withdraws it. Replaced whole by `next-call`. See **The agent's own queue** in `guide/queue.md`. |
+| `linedUp` | The call waiting in the agent's own queue, while one is: the caller as shown to this audience, the queue, the caller's wait, when it was lined up, and `release` where the provider lets the agent let it go. Not a task yet. Replaced whole by `lined-up`. See **The agent's own queue** in `guide/queue.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. |
 
@@ -2231,6 +2269,7 @@ surface in one place, and what obliges an adapter to implement each one.
 | `commitBreak()` | The login declares `capabilities.breaks`. Commit and cancel are not optional halves of it. |
 | `cancelBreak()` | The login declares `capabilities.breaks`. |
 | `endBreak()` | The login declares `capabilities.breaks`. |
+| `requestNextCall()`, `cancelNextCall()`, `releaseLinedUp()` | The login declares `capabilities.nextCall`. The three stand together: a lined-up call the agent could neither withdraw nor let go is a promise with no way out. See **The agent's own queue** in `guide/queue.md`. |
 | `executeTeam(request)` | The login declares `capabilities.lead`: every lead act, on the team surface and nowhere else. See **Lead commands** in `guide/lead.md`. |
 | `setPreference(request)` | The login declares `capabilities.preferences`: the person's choice has to have somewhere to go. |
 | `recordStep(report)` | The manifest lists `softphone` among its `phones`. On a softphone the agent application mutes its own microphone on any call, and the provider's record has to have somewhere to take that leg; a desk phone's microphone is the phone's. See **The agent application records what it performs** in `guide/agent.md`. |
@@ -2767,6 +2806,19 @@ the `contacts` idle capability.
 Replaces this provider's complete scheduled-activity contribution. It is emitted only when the manifest
 declares the `calendar` idle capability.
 
+### `next-call`
+
+The agent's ask for the next call as it now stands, replacing `Snapshot.nextCall`: present while
+the ask stands, absent once it was met by a lined-up call, withdrawn by the agent, or outlived by
+the assignment it was pressed on. See **The agent's own queue** in `guide/queue.md`.
+
+### `lined-up`
+
+The agent's own queue as it now stands, replacing `Snapshot.linedUp`: the call lined up for them,
+or nothing. It clears when the call becomes a task, on the ordinary `task-offered`, and when the
+queue gave the call to somebody else, the caller gave up, or the agent let it go. See **The
+agent's own queue** in `guide/queue.md`.
+
 ### `phone-updated`
 
 The phone as the platform now sees it, whole, replacing `Snapshot.phone`: a registration lost or

package/package.json

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