@xema/omni-protocol 0.1.106 → 0.1.107

package/guide/lead.md

@@ -0,0 +1,333 @@
+# `@xema/omni-protocol`: Team leads
+
+The lead's own surface: the team member list, the lead's commands, lead assist, listening to a call. 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.
+
+## Team leads
+
+The team feature is the lead's own surface, beside the agent's and never mixed with it. The
+login's `lead` flag turns it on in the agent application; the lead retrieves their members and
+sees, for each, their assignments as they stand and the full history of each, and acts on them
+with the authority the flag carries. Nothing the lead does here is a task on their desk. A lead
+who also takes calls is an agent like any other on the agent side, and a lead who does not want
+the agent role for now places themself on a break of a working kind and keeps the team feature on.
+
+The team reaches the lead whole once, on `team-updated` after the lead switches the feature on
+and on every snapshot while it is on, and from then on one member at a time: when a member is
+offered a call, answers, holds, mutes or is taken over, the provider publishes that member whole
+on `team-member-updated`, so the lead's screen moves when the member's does and a team of two
+hundred is never resent because one of them held. The agent application asks for nothing and
+computes nothing. See **`team-updated`** in `guide.md` and its companions.
+
+| Field | Contract |
+| --- | --- |
+| `members` | Every member of this lead's team, whatever their state, each with their open tasks. `[]` says the lead has a team with nobody in it; omitting the team member list says something else entirely — see **The login is the permission** below. |
+| `policies` | The team's policy per capability as it stands — the setting, who set it, and `lockedBy` where a level above the team made it theirs to keep. Present where the provider offers policy control; absent where it does not. See **Who decides what an agent may do** in `guide.md`. |
+
+| `TeamMember` field | Contract |
+| --- | --- |
+| `id` | Required `UserId`. A task carries no names and neither does a team member list: Omni resolves what to display with `getUserDetails()`. |
+| `availability` | Required. What the member is doing now. |
+| `since` | Optional. When the current `availability` began — not when they signed in, and not when the team member list was read. |
+| `break` | Present only while the member has an outstanding break request. See **A member waiting for a break**. |
+| `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**. |
+| `shift` | The member's own history for the day, about the person rather than any one call: `signedInAt`, `signedOutAt` once it has happened, today's totals as the provider counts them — `talkSeconds`, `holdSeconds`, `breakSeconds`, `tasksHandled`, each present only when the provider knows it — and the day's sign-in, sign-out and break `events`, oldest first. The same `Shift` the member's own snapshot carries, the same numbers from the same count. Omitted where the provider cannot say. |
+
+Each availability value means one thing:
+
+| Value | Meaning |
+| --- | --- |
+| `ready` | Signed in, able to take work, none assigned. |
+| `on-task` | Working on at least one task. It says nothing about how many, and nothing about whether more will fit. |
+| `on-break` | Stopped and not taking work, whether they asked or somebody stopped them. The reason lives on their own `BreakState`, not here. |
+| `elsewhere` | Signed in here, and the agent application holds this agent's capacity for another provider (`count: 0`, agent application-stopped): not receiving this provider's work, and not on a break. See **Capacity**. |
+| `signed-out` | Known to this team but not signed in to this provider. |
+
+**Publish the whole team once, then each member whole.** Team presence typically reaches an
+adapter over a best-effort channel with no ordering and no delivery guarantee, so the adapter
+reconciles against its own authoritative read before it publishes anything. What it publishes is
+the whole team on `team-updated` -- after the switch, and on every snapshot -- and after that one
+member at a time on `team-member-updated`, carrying the member whole: their availability, their
+tasks, their listening, their shift, their request, as they now stand. Applying the same member
+twice changes nothing, so a redelivery is harmless, and a member the team never carried is added
+by it, as a colleague signing in is. `team-member-removed` takes one off. Never a field of a
+member, never a task of theirs on its own: a hold on a member's desk is that member republished
+whole on the lead's, and nothing else on the lead's screen moves.
+
+**Whatever the member's desk hears of a task, every lead hears of the member.** The trigger is
+not a list of changes but the publication itself: each `task-offered`, `task-updated`,
+`task-audio-started`, `task-audio-ended` and `task-ended` the provider sends to the member is
+matched by a `team-member-updated` to every lead with the feature on, carrying the member whole
+with the task as it now stands, or without it once it has ended. A held leg closing with its
+`seconds`, a room restated, a phase moving, the wrap left ticking on a restatement: each reaches
+the lead's copy in the same round it reaches the member's, and the two copies of the record never
+part for longer than the delay between them.
+
+**The agent's day is on the wire.** The lead sees `shift` totals as the provider counts them, and
+the agent sees the same: `Snapshot.shift` and `shift-updated` carry the agent's own day in the same
+shape, from the same count, so "calls today: 12" is one number on both screens. The desk computes
+nothing of the day; `tasksHandled` moves when a task ends and `talkSeconds` when a leg closes, and
+the active call's running time is the screen's own until then, as **Every screen counts from the
+provider's clock** sets out.
+
+**Omit `since` rather than inventing one.** Omni renders it as a duration, so a timestamp
+synthesised from the adapter's own clock at seed time reads as "on task for 0 seconds" for
+everybody — worse than showing nothing, because it looks like data. Send it only when the provider
+knows when the state actually began. It times the current `availability`, so it moves every time
+that value does. And it is counted from the provider's clock, never the screen's, so a provider
+that publishes it declares `timeCheck` -- see **Every screen counts from the provider's clock** in `guide.md`.
+
+**The login is the permission.** A team member list goes to a login that declares
+`capabilities.lead`, once the team feature is on, and to nobody else. Omni never decides who
+leads a team: the provider said so at sign-in, and the team member list agrees with it — owed,
+`members: []` included, once a lead has switched the feature on; absent for everybody else, which
+is the correct rendering for an agent who leads nobody (`team.required`, `team.unentitled`). What
+the lead may do with it comes with the flag: there is no per-action permission on the login or on
+the list.
+
+**The lead switches the feature on and off, and the provider is told.** A lead may work as an
+agent alone, as agent and lead, or as lead alone, and moves between them on the fly. The
+agent application says which with `{ type: "lead-features", enabled }`: while it is on, the
+provider sends team events scoped to the lead's team and the lead may act; while it is off, the
+lead is an ordinary agent, nothing of the team is owed or expected (`team.unexpected`,
+`event.team.features`), and no lead act is possible, since the lead learns their members'
+assignments only from the list.
+
+**The provider assumes nothing.** The switch is not remembered across connections: the agent
+application sends `lead-features` on every connect, after it has stated capacity, and until it has
+the provider treats the feature as off. The connect snapshot therefore carries no team, whatever
+the login declares; the whole team arrives on `team-updated` once the switch is on, and every
+snapshot after that carries it. A conformance run switches the feature on for a lead and holds the
+provider to that first `team-updated` (`team.required`); a team on the connect snapshot is the
+provider assuming (`team.unexpected`).
+
+**The team member list never carries the agent it is published to.** A lead does not report to
+themself: their own break request and their own ask for a lead go up to whoever leads them and
+appear on *that* person's team member list, as a member with a `request`, while the requester sees
+only their own `BreakState` and their task's `leadAssist` move. An adapter whose platform lists the lead
+among their own members filters the signed-in identity out before publishing. **Being a lead is a
+role the provider knows, never inferred from who is listed:** it is declared at sign-in, a lead
+with nobody in their team publishes `members: []`, an agent with no such role publishes nothing, and no
+member count can tell those two apart.
+
+### Lead commands
+
+One method, `executeTeam`, taking a discriminated command exactly as `execute` takes a
+`TaskCommand`. Every act on a member's call names the member, `memberId`, and may name the
+assignment, `assignmentId`, where the lead has it; the provider resolves the member's current
+assignment from the member alone.
+
+| Command | Effect |
+| --- | --- |
+| `{ type: "lead-features", enabled }` | The team feature on or off. See **The lead switches the feature on and off** above. |
+| `{ type: "decide-break-request", memberId, decision, reason? }` | Settles one pending request. `decision` is `granted` or `denied`. A grant moves the member to `granted`; a denial ends the request and moves it directly to `not-requested`. |
+| `{ type: "set-break-policy", policy }` | `approval-required`, `automatically-approved`, or `requests-suspended`. |
+| `{ type: "force-break", memberId, reasonId?, reason?, expectedDurationMs? }` | Puts a member on a break they did not ask for. `reasonId` names a published `BreakReason.id` and is required whenever the provider publishes `reasons`; the member's forced break carries it as `activeReasonId`, so its kind is known. Optional `expectedDurationMs` is advisory; the resulting forced break publishes what is left of it as `expectedEndsInSeconds`, restated on every publication. |
+| `{ type: "end-forced-break", memberId }` | Asks the provider to lift a forced-break restriction a lead asked for, by clearing `BreakState.forced`; one the platform imposed is its own to lift (`team.command.endForcedBreak.provider`, `omni.break-forced-by-provider`). The committed break continues; only the agent resumes work. |
+| `{ type: "join", memberId, assignmentId? }` | Answers the member's request: the provider bridges the lead's channel into the call. See **Lead assist**. |
+| `{ type: "decline", memberId, assignmentId?, reason? }` | Refuses the member's request. |
+| `{ type: "listen", memberId, assignmentId? }` | The lead's channel joins the member's call unasked, in silence. See **Listening to a call**. |
+| `{ type: "coach", memberId, assignmentId? }` | The lead is heard by the member alone. Needs the lead on that member's call. |
+| `{ type: "join-call", memberId, assignmentId? }` | The lead is heard by everyone on the call. Needs the lead on that member's call. |
+| `{ type: "leave", memberId, assignmentId? }` | The lead's channel leaves the member's call, however it got there. The member's call goes on. |
+| `{ type: "take-over-call", memberId, assignmentId? }` | The provider moves the call to the lead as its new agent, from a joined call or a listened one alike. See **Lead assist**. |
+| `{ type: "set-policy", capability, setting }` | Sets the team's policy for one capability: `on`, `off`, or `person`. See **Who decides what an agent may do** in `guide.md`. |
+
+`memberId` is this provider's own identifier for the member, as published on its team member list. It is
+never an identifier from another provider, and Omni does not translate between them; names come
+from `getUserDetails()`. `validateTeamCommand` holds each command to the team member list as it
+stands -- see **Runtime break prerequisite checks** in `guide/breaks.md`.
+
+`requests-suspended` means requests are **rejected outright** rather than left pending — nobody is coming to
+approve them. A provider that suspends break requests must also publish `canRequestBreak: false` to the team's
+agents so they see it before asking. A `force-break` must likewise reach that member as a `forced` break
+on their own `BreakState`, or they are stopped from working with no way to see why.
+
+What happens when no lead is online — auto-approving, for instance — is the provider's decision and is
+never expressed here.
+
+### Lead assist
+
+An agent on a call may ask a lead to join it -- a dispute that needs approval, a customer who
+asks for a manager, a moment the agent wants a second pair of ears. A call centre calls this
+assistance or escalation, and the name says who assists: the capability is `leadAssist` on the
+task; the lead's side is the team member list, which is already the lead's view of the team. The
+flow, in order:
+
+```ts
+// 1. The agent asks, with a small note. Their task carries `leadAssist` from here on.
+execute({ assignmentId: "alloc-42", command: { type: "lead-assist", action: "request", note: "Refund dispute, needs approval" } })
+//    task.leadAssist = { stage: "requested", note: "Refund dispute, needs approval", since }
+
+// 2. Every lead with the team feature on sees the request on the member.
+//    team-member-updated: member: { id: "A-1", ..., request: { assignmentId: "alloc-42", note, since } }
+
+// 3. A lead joins, or declines.
+executeTeam({ command: { type: "join", memberId: "A-1", assignmentId: "alloc-42" } })
+executeTeam({ command: { type: "decline", memberId: "A-1", reason: "In a call" } })
+```
+
+**On `join` the provider bridges the lead's channel into the call.** The member's task moves to
+`leadAssist: { stage: "joined", leadId }` and its `onCall` gains the lead as an `agent`, since a
+lead who is heard is in the room; the member on the team member list carries
+`listening: [{ leadId, assignmentId, mode: "join-call", since }]`, and the lead's audio opens on
+it as **Listening to a call** describes. Nothing is a task on the lead's desk: a join is the lead's act on the team surface, not
+work assigned to them.
+
+**A lead is on one member's call at a time.** A `join` from a lead already on a call -- their own
+or a member's -- is answered `failed`; the request stands for another lead, or until it is
+withdrawn or declined. A join is work, so Omni offers Join only to a lead whose voice channel is
+free, and a provider answers a `join` from one whose channel is not `failed`.
+
+**On `decline`, or a request the agent withdraws with `{ type: "lead-assist", action: "cancel" }`, the
+provider clears `leadAssist` from the agent's task** and drops the request from every team member list. Nothing
+else changes; the agent is still on the call.
+
+**On `leave`, the lead's channel drops and the call goes on**: the member's task loses its
+`leadAssist`, the member loses this lead's entry in `listening`, and the lead is free. Nothing ended for the member.
+
+**On `take-over-call`, the provider moves the call from the member to the lead**, and the lead is
+its new agent. There are two paths to it -- the agent asked and the lead joined, or the lead was
+listening unasked -- and one act at the end of either. What follows is the same on both:
+
+| | The member's task | The lead's desk |
+| --- | --- | --- |
+| Take-over | `task-audio-ended`, then `completing`: the member's interaction is over and their wrap runs, exactly as after `end-call`. The audio ends first, as before every voice ending (`stream.taskEnded.audioOpen`). The member loses this lead's `listening` entry on the team member list no later than the offer, and the lead's listening audio closes. | An ordinary assignment arrives: `task-offered` with `acceptance: "automatic"`, carrying the call's history and `takenOver: { memberId, since }`, within the lead's capacity. |
+| The member completes | `task-ended` with `{ type: "taken-over", leadId }`, at the member's own completion. The lead is named by user id, since a lead is not a directory item. | The lead works the call as any agent would, and ends it as any call ends. |
+
+**The taken-over call is offered whatever break the lead is on, and counted like any other.** A
+lead working as lead alone is on a break of a working kind, and the provider assigns the call
+regardless: it is the one task a break in effect may hold (`break.on-break.tasks` allows it, and
+nothing else). It is a call landing on the lead's desk, so it counts against their capacity as
+every call does, with no exemption: a lead at capacity cannot take over, and the provider answers
+`failed`. The other conditions are that the lead is not already on another call and their voice
+channel is free. A lead with the team feature off cannot take over, since they have no member's
+assignment to name.
+
+```ts
+const leadAssistCapable = {
+  channel: "voice",
+  capabilities: { hold: true, leadAssist: true, outcomes: true },
+  phase: "in-progress",
+  leadAssist: { stage: "joined", leadId: "L-9", note: "Refund dispute, needs approval", since: "2026-08-21T09:04:00Z" },
+} satisfies Pick<Task<"voice">, "channel" | "capabilities" | "phase" | "leadAssist">;
+
+const takenOver = {
+  channel: "voice",
+  capabilities: { hold: true, endCall: true, outcomes: true },
+  phase: "in-progress",
+  takenOver: { memberId: "A-1", since: "2026-08-21T09:06:00Z" },
+} satisfies Pick<Task<"voice">, "channel" | "capabilities" | "phase" | "takenOver">;
+```
+
+Lead and member alike are `UserId`s of this provider, so an adapter publishing them implements
+`getUserDetails()`; names never travel on a task or a team member list.
+
+### Listening to a call
+
+A lead may listen to a member's call without being asked -- to coach, to check quality, to step in
+when it goes wrong. It is a team act naming the member, and no task on the lead's desk carries it:
+the lead's view of the call is the member's task on the team member list, with its room and its
+history. The three modes determine who hears the lead:
+
+| Mode | Who hears the lead |
+| --- | --- |
+| `listen` | Nobody. The lead hears both sides in silence. |
+| `coach` | The agent alone. The customer hears nothing. |
+| `join-call` | Everyone on the call. |
+
+All three come with the `lead` flag; a centre reserves none of them per lead.
+
+**There is no team audio.** Audio is the agent's or the lead's, and the lead's audio while
+listening follows the provider's published state exactly as a task's does: the entry naming this
+lead in `listening` on the member is the provider's word that the lead's channel is in the call.
+When it appears, the application opens `openAudio({ assignmentId })` on the lead's connection for
+the call it names, and plays the `CallAudio` returned; when it goes, the application closes it.
+Another lead's entry opens nothing: it is shown, and that is all. Nothing else says
+when the lead's audio is up, and a reload reopens it from the snapshot's team member list as a task
+carried with `audio: "started"` is reopened.
+
+The flow, end to end:
+
+```ts
+// 1. The lead, with the feature on, sees a member on-task with their tasks, and picks a call.
+// 2. The lead's channel joins it in silence. Conditions: the lead's voice channel is free --
+//    not on a call, not listening elsewhere. Capacity is not involved: nothing is assigned.
+executeTeam({ command: { type: "listen", memberId: "A-1", assignmentId: "alloc-42" } })
+// 3. The provider publishes the member whole on team-member-updated, to every lead; the member carries
+//    listening: [{ leadId: "L-9", assignmentId: "alloc-42", mode: "listen", since }]
+//    -- L-9's application opens openAudio({ assignmentId: "alloc-42" }) on its own connection; every
+//    other lead's shows L-9 on the call and opens nothing.
+// 4. The lead changes how they are heard; the member is published again with the entry's new mode. The audio stays open.
+//    join-call is heard by everyone, so the member's task is also republished with L-9 on onCall as an agent.
+executeTeam({ command: { type: "coach", memberId: "A-1" } })
+executeTeam({ command: { type: "join-call", memberId: "A-1" } })
+// 5. The lead leaves: the provider publishes the member without L-9's entry, and the task without L-9 in the room; the application closes the audio.
+executeTeam({ command: { type: "leave", memberId: "A-1" } })
+// 6. The member's call ends: the same as leave, from the provider's side.
+// 7. The lead takes the call: the member loses this lead's listening entry no later than the offer, the application
+//    closes the listening audio, and the lead's own call arrives as an ordinary assignment marked
+//    takenOver, counted against capacity, with its audio following task-audio-started as any call's does.
+//    At capacity the take-over is refused and the lead stays listening.
+executeTeam({ command: { type: "take-over-call", memberId: "A-1" } })
+// 8. A join on the member's request is the same flow entered at step 3 with mode: "join-call",
+//    and the member's task shows leadAssist: joined.
+// 9. A reload of the lead's application: the switch is sent again, the team-updated that follows
+//    still carries this lead's entry in listening on the member, so the audio is reopened.
+```
+
+**`listening` on the member is the state**, one entry per lead on the call, restated on every
+change of mode, naming the lead (`team.member.listening.leadId`, once per member,
+`team.member.listening.unique`) and the call, so the application knows which audio is its own to
+open (`team.member.listening.assignmentId`, and one the member's tasks carry,
+`team.member.listening.assignment`). Every lead sees every entry: a silent lead is hidden from
+the agent, never from the other leads and managers watching the same member on other screens.
+A lead is on one member's call at a time (`team.listening.single`).
+
+**A lead listens while holding no call of their own.** Omni offers Listen to a lead whose voice
+channel is free, and a provider answers a `listen` from one whose channel is not `failed`. That
+includes a lead on a break: a lead working as lead alone is on a break of a working kind, and
+listens through it.
+
+**A silent lead reaches nobody but the leads.** In `listen` and `coach` the member's task carries
+no trace of the lead: not on `onCall`, not in the record. Whether coaching is announced to the
+agent is the platform's business and travels on the audio, not on this wire. In `join-call`, and
+on a `join` answering a request, the lead is heard by everyone and is in the room: the task's
+`onCall` carries them as an `agent` by user id, on the member's desk and on every lead's copy of
+the task alike, and `leave` takes the entry off as it takes the channel off
+(`team.member.listening.heard`).
+
+### A member waiting for a break
+
+A member who has asked for a break **keeps working** until Omni commits it, so asking is not an
+availability of its own — it rides alongside one on `break`. That a request exists says nothing
+about whether anybody has to act on it, and the difference is a lead's entire action list:
+
+| `break` | Means |
+| --- | --- |
+| `awaiting-approval` | Somebody has to decide. This is the lead's queue. |
+| `granted` | Decided yes, but Omni has not told the provider to stop yet. Work continues and nobody needs to decide. |
+| `starting-after-task` | Already granted; it begins when their current task ends. Nobody needs to act. |
+
+Those three are the only values that appear here. `not-requested` is absence — omit `break`
+instead. `on-break` is `availability: "on-break"`, and a denial transitions to `not-requested`,
+so neither survives to be reported. It is otherwise the same `BreakStatus` the member's own
+break state uses, rather than a parallel vocabulary for the lead's view, so the two cannot drift
+apart.
+
+Omni offers Approve and Deny only while a member is `awaiting-approval`, shows `granted` as agreed
+but not started, and shows `starting-after-task` as settled.
+
+**Live status, not a record.** The provider derives it from what is true now — not stored, not
+historical, carrying no decision made earlier. Like the team member list it belongs to, it is published
+whole and replaced whole, and a provider that cannot say omits it.
+
+**An agent is not waiting on one person.** Authority is held by several, everyone who holds it
+sees the request on their own console, and **any one of them settles it**. Omni offers the
+decision to every login that declares `lead` and has the team feature on — which is how the provider already
+says who may decide — and does not try to work out whose turn it is.
+
+A request needing *more than one* approval is not something this contract describes. There is
+no partial state to report and no progress to display: a request is either still owed a
+decision or it is not.

package/guide/phone.md

@@ -0,0 +1,274 @@
+# `@xema/omni-protocol`: 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. 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.
+
+## Real-time audio
+
+Every voice provider has audio: `channel: "voice"` says audio exists. Where the agent hears it
+depends on the `phone` the agent application selected at authentication and connect from the manifest's
+`phones`. On a softphone, audio lands in Omni; on a desk phone, it lands on the handset and Omni
+opens no audio. See **How the agent hears the call**. Audio transitions are voice-only;
+chat and email publish none (`event.audio.channel`, `stream.taskAudio.channel`).
+
+The provider owns signalling and the platform's endpoint configuration. The agent application selects the
+declared phone mode; it does not enumerate or reconfigure the platform's devices. The selected
+mode stays with the login rather than being inferred from a snapshot or a device failure.
+
+Nor does the audio ever stand in for the task: a task's presence and
+phase follow the provider's reports about the work, and the audio — attaching, moving through a
+hold, a conference, a lead joining or a take-over, and ending — is transient beside it. See **A task is
+never its audio** under **Task assignment lifecycle**.
+
+### The agent application reports, the adapter decides
+
+The adapter runs inside Omni and sees nothing of the station for itself: the devices, the
+permissions, the audio element and the network are the agent application's, and only the agent application can tell. So
+the agent application reports, and the adapter asks. **An adapter consults `ConnectContext.host` before it
+declares the agent ready to its platform, and again whenever the report changes**, and it decides
+what any of it means and what to relay upstream — go not-ready, refuse calls, carry on because the
+platform's audio lands elsewhere. Omni facilitates and does not take responsibility: it captures
+the microphone once as the voice connection opens, so the permission prompt lands while the agent
+is signing in rather than over a contact, prompts, retries on the agent's request, tells the agent
+what failed, and reports. It never decides for the adapter what a missing microphone means.
+
+**The agent application also guarantees, and a promise the provider cannot see is not one it can rely on.**
+Two of this contract's obligations fall on the agent application rather than the provider — honouring a task
+browser's `urlVisibility`, and taking a `consent` offer only on the person's own press — and more
+than one desk speaks this contract: a browser and a native application differ in what they can
+reach, and a provider never branches on which it is talking to, only on what it has declared —
+here, and in `host.mute` (see **The station is the agent application's**). So `ConnectContext.host.guarantees` says which promises the
+connected agent application makes, declared once per connection, presence being the guarantee exactly as it is
+the permission everywhere else:
+
+| Guarantee | Contract |
+| --- | --- |
+| `browserUrlVisibility` | Every task browser's `urlVisibility` is honoured in this agent application's chrome, tab by tab. A provider that would send a caller's number in a URL checks this first and tokenises where the promise is absent. |
+| `personConsent` | A `consent` offer is accepted only by the person's own explicit act, never on their behalf. A provider whose work may only be taken by a human checks this first and does not offer it where the promise is absent. |
+
+A guarantee the agent application does not make is an absent key, never `false` — `validateHostGuarantees`
+refuses a false one, as it refuses a name this contract does not list.
+
+| Field | Contract |
+| --- | --- |
+| `online` | Whether the agent application has a network interface up. Not a claim that anything is reachable — the adapter knows whether it can reach its own platform far better than the agent application does — so `false` is a reason not to go ready and `true` is not a reason to. |
+| `audio` | Present on a voice connection, absent where there is no audio. |
+| `audio.input` | `available` with `localAudio` — the microphone as captured, the same stream `openAudio` receives — and `flowing`, false while no audio moves through it, when `mutedBy` says who stopped it: `host`, the agent application's own Mute on an agent application that mutes the station, or `station`, a slider on the headset or the operating system, which the agent application observed and did not do. An adapter treats `host` as the agent's act on a call and `station` as a condition of the station. `unavailable` with `reason`, since each wants a different fix from the agent: `no-device`; `denied`; `not-asked`, which an agent application that asks at connect never publishes; `in-use`, a device present and permitted that another application holds — on an agent desktop the commonest of all; `lost`, a capture that ended. An agent application decides the reason from the devices before the error name: a browser can report a permission error on a machine with no microphone at all, and "grant permission" is the wrong instruction for an agent who needs to plug one in. `failure` carries the words Omni showed them. |
+| `audio.output` | `available`, with `flowing` where the agent application can know whether audio reaches the speaker — a browser mostly cannot, and omits it; a native agent application reads the endpoint — false while it is silenced, when `mutedBy` says who did it, as on input. Or `unavailable` with `reason` — `no-device`, or `lost` for one removed — and `failure`: an agent who cannot hear is as unable to take a call as one who cannot speak. |
+
+Omni republishes the report whenever it changes — a permission granted late, a headset unplugged,
+a network gone — and it publishes a state, not a flicker: a change that resolves within moments is
+not reported, so an adapter may act on what it reads without debouncing it again. Nothing in the
+report is a task fact or a capacity fact; it is what the station can do, and the adapter's platform
+is the one that knows whether an agent without a microphone, or without a speaker, can work.
+
+The agent application's own obligations here — asking at connect, never publishing `not-asked` when it does,
+publishing a state and not a flicker — are Omni's tests' to hold. `exerciseAdapter` holds the
+other side: it validates the shape of whatever agent application a test hands the adapter, requires `audio` on
+a softphone login and none elsewhere -- not on a desk phone, not off voice
+(`context.host.audio.required` / `.unexpected`), holds `host.mute` to the same line (`host.mute.required`
+/ `.unexpected`, `host.mute` for a third word) -- and refuses a voice adapter that never asked the
+agent application anything (`connection.host.consulted`), and one that subscribed to nothing will never hear of a
+change (`connection.host.subscribed`): the obligation has two halves, and each is held.
+
+### Capacity around setup
+
+Connecting is not the same as being able to take a call. A provider that treats a live connection
+as reachability opens a window where it believes the agent is available and the agent is not yet
+set up — the adapter's own registration incomplete, its credentials not yet renewed.
+
+Nothing closes that window, because nothing opens it: **Omni states no capacity until the
+connection is established**, and **Work is pulled, never pushed** makes an assignment with none
+stated a violation. Capacity does not wait on the microphone: whether an agent without agent application audio
+can take calls is the platform's question, answered by the adapter from the agent application's report, not by
+Omni withholding capacity for every platform alike.
+
+Capacity follows **automatically** once the connection is established; the agent does not press
+anything to become available.
+
+| Situation | What Omni sends |
+| --- | --- |
+| Connecting | Nothing. No capacity has been stated, so nothing may be assigned. |
+| Connected and idle | `setCapacity({ count: n })`, with the agent application's report already available to consult. |
+| A task starts or ends | Nothing. The provider counts its own against the ceiling. |
+| The agent's provisioned capacity changes | `setCapacity({ count: n })` |
+| Agent asks for a break | `requestBreak`. Capacity is unchanged and work continues. |
+| Omni commits a break | `commitBreak`. The break stops assignment, not the ceiling. |
+| Agent returns from break | `endBreak` |
+
+**A break is not a capacity of zero, and neither is the reverse.** Capacity says how much of this
+agent this provider may carry; a break says they are not working at all. A provider told
+`count: 0` shows an agent whose capacity is elsewhere, `elsewhere`; a provider told a break shows
+`on-break`. Collapsing the two would leave a provider unable to tell an agent working on another
+provider from an agent who has gone to lunch, and only one of those needs a reason, a decision and
+a return.
+
+### How the agent hears the call
+
+A voice platform can put an agent on a **softphone**, where the call's audio lands in the agent application
+and Omni owns the microphone and the playback, or on a **desk phone**, a handset on the platform's
+switch that the platform rings, where the agent application owns no audio and only shows the call. Which of
+these a platform can do is a fact about the platform, and which one a login is on is a choice the
+agent application makes for that agent -- so the manifest declares and the agent application chooses.
+
+```ts
+// Manifest: what the platform can do
+phones: ["softphone", "deskPhone"]
+// The agent application, at authentication and again at connect: which one this login is on
+{ phone: "softphone" }
+```
+
+A voice manifest lists its `phones` and any other channel lists none (`manifest.phones.required`,
+`manifest.phones.channel`). The agent application's `phone` is required on a voice login, absent on any other,
+and one the manifest listed (`context.phone.required`, `.unexpected`, `.unsupported`). Everything
+about audio then follows the phone rather than the channel: on a softphone the agent application reports its
+audio, the adapter implements `openAudio`, and `task-audio-started` is the word to open it; on a
+desk phone the agent application reports no audio, opens nothing, and `task-audio-started` still marks the
+moment the call is live so the desk shows it, with the sound on the handset. A platform that lists
+`deskPhone` alone never implements `openAudio`; one that lists `softphone` always does.
+
+**The mode comes from the agent application; the status comes from the provider.** The agent application knows which kind
+of station the agent signed in at, because the person chose it, and nothing else can know that.
+The provider knows whether that station can carry a call right now -- whether a handset is
+registered -- which an agent application in a browser cannot see. So the agent application's `phone` selects the branch, and
+the provider's own knowledge of the device decides readiness within it. A provider never overrides
+the agent application's declaration from its device record: treating a desk-phone login as a softphone because
+the handset is momentarily unregistered, and demanding a microphone of it, is the reading this
+sentence exists to refuse. What the provider does when the handset is not registered is what it
+does for any station that cannot take a call -- hold the agent not-ready and say why.
+
+**On a desk-phone login the agent application never calls `openAudio`.** There is no stream to hand over and
+no audio to attach; an agent application that calls it anyway is in error, and an adapter that receives the call
+answers `unavailable` with a non-retryable failure, since waiting changes nothing about a station
+that is a telephone. The harness requires no `openAudio` of such an adapter and never calls it.
+
+**Which handset a desk-phone login rings is the platform's configuration for that agent**, and
+this wire never asks the agent for it: an agent application declares `phone` and nothing more. What a platform
+asks on surfaces of its own is its own decision.
+
+**A declared phone the platform does not permit for this agent is a login that cannot be
+established.** The manifest says what the platform can do; the agent's record, kept by an
+administrator, says what this agent is configured for, and the two can disagree with the agent application's
+declaration -- a softphone declared for an agent whose record says desk phone. Honouring that
+declaration on a switch that allows one registration per endpoint would evict the handset: the
+agent's phone stops ringing and their calls land in a tab, and nobody is told. So the provider
+refuses the login at authentication, with `omni.phone-not-permitted` and a message the agent application shows
+-- "this agent is configured for a desk phone" -- and refusing is correct, not an override of the
+agent application. It is a refusal, never a negotiation afterwards and never a quiet substitution, and it is
+never retryable: trying again does not reconfigure the agent, and an agent application validating the answer
+(`validateAuthenticationResult`) refuses a phone refusal marked otherwise
+(`authentication.failure.phone.retryable`). And **a
+provider never makes a declared phone true by changing the platform's configuration**: the record
+is the administrator's, and a login is not a request to reconfigure an agent.
+
+### Opening the audio
+
+`openAudio` hands Omni the remote audio for one task. Every adapter whose manifest lists
+`softphone` implements it, because on a softphone the call's audio lands in Omni:
+
+```ts
+openAudio({ assignmentId, localAudio }): Promise<OpenAudioResult>
+// { status: "opened", session } | { status: "unavailable", failure }
+```
+
+The adapter speaks whatever its platform speaks — SIP over WebSocket, a vendor SDK, plain
+WebRTC — and **none of that appears in this contract**. Registration, signalling, credential
+renewal and reconnect are the adapter's, exactly as its authentication and transport already
+are. Omni owns what belongs to the agent application: the microphone, the output element, mute, and when a
+session ends — owning the microphone meaning capturing it, prompting, retrying and reporting how
+it stands, never deciding for the adapter what a missing one means (see **The agent application reports, the
+adapter decides**).
+
+| Member | Contract |
+| --- | --- |
+| `remoteAudio` | `MediaStream` Omni plays. |
+| `setMuted(muted)` | Mutes the agent's microphone on this session. |
+| `close()` | Releases the session. Omni calls it when the task ends. |
+
+`localAudio` is the agent's microphone as Omni captured it, the same stream the agent application's report
+carries as `audio.input.localAudio`, and absent while that input is `unavailable`. A provider that
+bridges audio without an application-side input may ignore it; one that needs it and finds it absent
+answers `unavailable` with a failure Omni shows the agent.
+
+**When to ask is the provider's word, not Omni's guess.** On a softphone login, Omni opens audio on `task-audio-started`,
+and on a task arriving with `audio: "started"` on a snapshot; it closes on `task-audio-ended` and
+when the task ends. Between those words, nothing Omni's own senses report — a stream that drops, a
+track that ends — moves the task or its audio.
+
+**A task-scoped session does not oblige one call per task.** A platform holding a nailed-up
+leg for a whole shift may return the same session for every task and release the underlying
+path only when the connection closes. A platform placing a call per contact returns a new one
+each time. Omni asks when it needs audio and closes when it is done; how that maps to the
+platform is the adapter's business.
+
+### The station is the agent application's
+
+The microphone, the speaker, the headset and its buttons are the station's, and the station is the
+agent application's. So mute is not a capability a provider declares, not a control a queue allows or a team
+locks, not a preference the person keeps with the provider, and not a command: nothing about the
+station crosses to the provider except two things -- the station's condition, in the agent application report,
+and the record of when the agent could not be heard, through `recordStep`. An agent application offers Mute on
+every voice task with audio open, under its own local policy, in `in-progress` and `paused`
+alone, and performs it through `CallAudio.setMuted()`. A task carrying
+`capabilities.mute` is refused (`task.capability.unknown`), and so is a `mute` command
+(`command.type`), a `mute` preference (`preference.id`) and a `mute` policy (`team.policy.key`).
+
+**Two mutes, and the agent application states which its Mute performs.** A *stream* mute stops the audio the
+agent application sends: the microphone keeps capturing, the party hears silence, nothing else on the machine
+changes, and every softphone agent application can do it. A *station* mute silences the microphone itself at
+the operating system: every application on the machine goes quiet, the system shows it, and a
+headset that follows the system follows it. Only a native agent application can do it. `Host.mute` says which
+this agent application does -- `stream` or `station` -- stated on a softphone login, where the agent application holds the
+microphone, and absent on a desk phone and off voice (`host.mute.required` / `.unexpected`). A
+browser says `stream`. A native agent application says whichever it does. Nothing on the wire says what kind of
+application the agent application is; a provider reads only what the agent application declared.
+
+**A silenced device says who silenced it.** `audio.input.flowing: false` and
+`audio.output.flowing: false` carry `mutedBy`: `host` when the agent application's own Mute did it -- which is
+only ever true of an agent application whose mute is `station`, since a stream mute leaves the microphone
+flowing -- and `station` when a slider on the headset or the operating system did, which the agent application
+observed and did not do. Without the word, a station-muting agent application's own Mute would read as a fault
+and an adapter would take the agent out of ready in the middle of a call. A browser reads a station
+mute through the capture track's muted state, read-only, and cannot lift it; a native agent application reads
+the endpoint and can clear an operating-system mute. A hardware slider is nobody's to clear.
+
+**The record carries the same word.** A `muted` interaction leg is a period the agent could not be
+heard, and the record exists so that period is not a hole. The agent application reports every such period
+through `recordStep` -- its own Mute, and a station mute it observed during a call -- with
+`mutedBy` saying whose the silence was, and the provider writes the word into the entry
+(`task.history.mutedBy`). The report names no agent because the agent application has exactly one, and
+the provider knows who that is: it attributes the leg to the login's agent in `by`, a fact it
+holds and not an inference, for a station mute as much as for the agent application's own. An unattributed
+`muted` entry is refused (`task.history.muted.by`); a shared handset's unattributed hold
+is a different claim, and stands. A supervisor reading the record then sees "the agent muted for
+forty seconds" and "the agent's headset was muted for forty seconds" as the different things they
+are. See **The agent application records what it performs** in `guide/agent.md`.
+
+**Mute has a lifecycle, and none of it is inferred.** A call that starts while the station is
+already muted begins a `muted` leg the moment its audio starts, `mutedBy: "station"`. Audio that
+ends while any leg is open ends the leg at that instant, as every agent application-performed leg ends. And the
+agent application's own Mute starts off on every call, which is every `task-audio-started` -- a connect-back
+opens a second call on the same task with no offer -- so an agent is never muted by the call before.
+
+**Every press on a headset is the agent's own press**, performed the agent application's way, and the lights
+follow the agent application's state. The `personConsent` guarantee is honoured by a hook-switch press exactly
+as by a click. What a call-control headset sends, and what becomes of it:
+
+| Input | Where it comes from | What the agent application does | What crosses to the provider |
+| --- | --- | --- | --- |
+| Mute button | The headset, on the HID Telephony usage page: a Phone Mute report on the press, a Mute LED the agent application writes back | A press of the agent application's Mute, performed the agent application's way; the LED follows the agent application's state, so button, light and control are one state with one owner | The `muted` leg, `mutedBy: "host"` |
+| Hook switch | The headset, HID Telephony | A press of the agent application's Answer or End call, only where the task is in a phase that has one; the off-hook and ring lights follow the task | The existing `answer` and `end-call` commands |
+| Flash, redial, speed dial | Older headsets and desk-phone style devices | Flash is Hold and Resume where the task offers `hold`; redial and speed dial map to nothing on a desk that never redials, and are ignored | Nothing new |
+| Volume up and down | The headset's own amplifier, or the operating system through the consumer-control keys | Nothing: the device and the system handle it | Nothing, except that a speaker at nought is `audio.output.flowing: false` where the agent application can know it |
+| Microphone gain and level | The operating system, the headset's own boost | A level meter, so the agent can see they are heard | Nothing: a level is a flicker, not a state |
+| Hardware or operating-system mute | A slider on the headset, the system's input mute | Observes it, publishes `flowing: false, mutedBy: "station"`, records the leg during a call, and tells the agent which it is where it knows -- headset or system -- and what to do; an agent application whose mute is `station` clears a system mute itself, a browser can only say so | The report and the leg |
+| Device changed, unplugged, permission revoked | The operating system | Re-capture, prompt, report | Already `audio.input` and `audio.output` with `lost`, `denied`, `no-device` |
+
+**What the agent application shows.** Beside Mute, a standing line while the station is muted, saying which and
+what to do, with a button that clears a system mute only on an agent application whose mute is `station`. The
+Mute control does not pretend: while the station is muted it shows the agent cannot be heard and
+that pressing it will not change that, and a press still toggles the agent application's own mute, so the two
+states stay separate and the agent is not unmuted by surprise when the slider moves back. Before a
+call, the same line in the ready state, so an agent does not learn of it from a silent customer;
+whether work is held back is the adapter's decision from the report, as it is for every station
+fact. Where a provider's own platform holds a mute of its own -- a bridge that silences a leg --
+that is a fact about the switch, reported as the provider sees fit, and never the agent application's Mute.