@xema/omni-protocol 0.1.58 → 0.1.60

package/dist/index.d.ts

@@ -335,13 +335,34 @@ export interface AuthenticationSession {
  * does not decide for the adapter what a missing one means. The adapter does what its platform
  * needs: go not-ready, refuse calls, or carry on because audio lands elsewhere.
  */
+/**
+ * Who silenced a device that is present and permitted: the host, by its own Mute, or the station --
+ * a slider on the headset, the operating system -- which the host observes and, on a browser,
+ * cannot touch. The same word on a `muted` handling leg says whose the silence was.
+ */
+export type MutedBy = "host" | "station";
+export declare const MUTED_BY: readonly ["host", "station"];
+/**
+ * What pressing Mute does on this host. `stream`: the host stops the audio it sends, and the
+ * microphone keeps capturing. `station`: the host mutes the microphone itself at the operating
+ * system, which every application on the machine then shares. A browser can only do the first;
+ * a native host says which it does. Stated by the host on a softphone login, never inferred
+ * from what kind of application it is.
+ */
+export type HostMute = "stream" | "station";
+export declare const HOST_MUTES: readonly ["stream", "station"];
 export type HostAudioInput = 
-/** Omni has the microphone. `flowing` is false while the hardware or OS says no audio moves through it. */
-{
+/** Omni has the microphone. `flowing` is false while no audio moves through it, and then `mutedBy` says who stopped it. */
+({
     status: "available";
     localAudio: MediaStream;
-    flowing: boolean;
-}
+} & ({
+    flowing: true;
+    mutedBy?: never;
+} | {
+    flowing: false;
+    mutedBy: MutedBy;
+}))
 /** Omni does not, and `reason` says which fix the agent needs; `failure` is the words Omni showed them. */
  | {
     status: "unavailable";
@@ -356,9 +377,17 @@ export type HostAudioInput =
 export type HostAudioUnavailableReason = "no-device" | "denied" | "not-asked" | "in-use" | "lost";
 /** Why the host has no speaker: no device, or one that was removed. */
 export type HostOutputUnavailableReason = "no-device" | "lost";
-export type HostAudioOutput = {
+export type HostAudioOutput = 
+/** Omni has a speaker. `flowing` is stated only where the host can know it: false while the output is silenced, and then `mutedBy` says who did it. */
+({
     status: "available";
+} & ({
+    flowing?: true;
+    mutedBy?: never;
 } | {
+    flowing: false;
+    mutedBy: MutedBy;
+})) | {
     status: "unavailable";
     reason: HostOutputUnavailableReason;
     failure: ProtocolFailure;
@@ -393,6 +422,8 @@ export interface HostGuarantees {
 }
 export interface Host {
     guarantees: HostGuarantees;
+    /** What pressing Mute does on this host. Stated on a softphone login, where the host holds the microphone; absent on a desk phone and off voice. */
+    mute?: HostMute;
     report(): HostReport;
     subscribe(listener: (report: HostReport) => void): Unsubscribe;
 }
@@ -492,7 +523,6 @@ export interface SharedTaskCapabilities {
  */
 export type TaskCapabilities<C extends Channel = Channel> = C extends "voice" ? SharedTaskCapabilities & {
     decline?: Lockable<true>;
-    mute?: Lockable<true>;
     hold?: Lockable<true>;
     /** The agent may end the whole call: everyone leaves and the media ends, the task stays for its wrap-up. */
     endCall?: Lockable<true>;
@@ -623,6 +653,8 @@ export interface TaskHandlingStep {
      * provider could not attribute it, which is a different claim and a legitimate one.
      */
     by?: UserId;
+    /** On a `muted` step, and only there: whose the silence was, as the host reported it. */
+    mutedBy?: MutedBy;
 }
 /**
  * How the task ends, and how long after handling the provider allows for it.
@@ -830,7 +862,7 @@ export type TaskOutcome = {
     failure: ProtocolFailure;
 };
 export declare const TASK_COMMAND_NAMES: {
-    readonly voice: readonly ["answer", "decline", "call", "mute", "hold", "resume", "end-call", "connect-back", "transfer", "lead-assist", "conference", "recording", "complete"];
+    readonly voice: readonly ["answer", "decline", "call", "hold", "resume", "end-call", "connect-back", "transfer", "lead-assist", "conference", "recording", "complete"];
     readonly chat: readonly ["accept", "decline", "pause", "resume", "complete"];
     readonly email: readonly ["accept", "decline", "complete"];
 };
@@ -848,9 +880,6 @@ export type VoiceTaskCommand = {
  | {
     type: "call";
     dialId: DialId;
-} | {
-    type: "mute";
-    muted: boolean;
 } | {
     type: "hold";
 } | {
@@ -1128,7 +1157,7 @@ export interface TeamRoster {
 }
 /** A capability a team policy can name: any task control, new call, or a skill by its provider id. */
 export type PolicyKey = Exclude<keyof TaskCapabilities<"voice">, keyof SharedTaskCapabilities> | Exclude<keyof TaskCapabilities<"chat">, keyof SharedTaskCapabilities> | Exclude<keyof TaskCapabilities<"email">, keyof SharedTaskCapabilities> | "dial" | `skill:${string}`;
-/** On for everyone, off for everyone, or the agent's own choice. Only `hold`, `mute` and skills may be `agent`. */
+/** On for everyone, off for everyone, or the agent's own choice. Only `hold` and skills may be `person`. */
 export type TeamPolicySetting = "on" | "off" | "person";
 /** One policy as the lead sees it: the setting, who set it, and `lockedBy` when a level above the team made it theirs to keep. */
 export interface TeamPolicy extends Resolved {
@@ -1222,12 +1251,12 @@ export type OpenMediaResult = {
 };
 /** The provider's complete state at one moment. It replaces what Omni holds; never a patch. */
 /**
- * What the team may leave to the person: a capability by its own name -- `hold`, `mute` -- or a
+ * What the team may leave to the person: a capability by its own name -- `hold` -- or a
  * skill by its provider id. The same key as in `Task.capabilities`, because it is the same
  * capability seen at another level. Connecting back and a new call are never the person's; they
  * are the team's, on or off, within what the queue allows.
  */
-export type PreferenceId = "hold" | "mute" | `skill:${string}`;
+export type PreferenceId = "hold" | `skill:${string}`;
 /**
  * Who stated a value as it stands: a level -- `person` among them -- or `provisioning`, the
  * protocol's own word for "no level has said anything and the provider's default applies".
@@ -1260,8 +1289,8 @@ export type SetPreferenceRequest = {
     inherit: true;
 };
 /**
- * The host's report of a handling leg it performed itself -- a mute, which Omni does rather than
- * the provider -- so the provider's record has an account of it. Keyed by `step` and `at`: the
+ * The host's report of a handling leg it performed itself -- a mute, which is the host's and
+ * never the provider's -- so the provider's record has an account of it. Keyed by `step` and `at`: the
  * same entry is reported when it begins, as often as the host cares to while it runs, and once
  * more with `ended`, when `seconds` is the final duration. The host is the authority for the
  * legs it performs, so `seconds` may say how long so far at any time; the end is stated, never
@@ -1269,9 +1298,16 @@ export type SetPreferenceRequest = {
  */
 export type HandlingReport = {
     taskId: TaskId;
-    step: HandlingStep;
     at: IsoTimestamp;
-} & ({
+} & (
+/** A muted leg says whose the silence was: the host's own Mute, or the station's slider or system. */
+{
+    step: "muted";
+    mutedBy: MutedBy;
+} | {
+    step: Exclude<HandlingStep, "muted">;
+    mutedBy?: never;
+}) & ({
     ended: true;
     seconds: DurationSeconds;
 } | {
@@ -1443,7 +1479,7 @@ export interface Connection<C extends Channel = Channel> {
     openMedia?(request: OpenMediaRequest): Promise<OpenMediaResult>;
     /** Required when the login declares `capabilities.preferences`: the person's own choice, kept by the provider and republished as `authenticated`. */
     setPreference?(request: SetPreferenceRequest): Promise<PreferenceResult>;
-    /** Records a handling leg the host performed. Required of a connection whose tasks may declare `mute`. */
+    /** Records a handling leg the host performed. Required of a softphone login's connection: the host mutes its microphone on any call, and the record is the provider's. */
     recordStep?(report: HandlingReport): Promise<HandlingReportResult>;
 }
 export interface Adapter<C extends Channel = Channel> {

package/dist/index.js

@@ -27,6 +27,8 @@ export const IDLE_CAPABILITY_UI = {
     contacts: "Contacts",
 };
 export const MONITOR_MODES = ["monitor", "whisper", "barge"];
+export const MUTED_BY = ["host", "station"];
+export const HOST_MUTES = ["stream", "station"];
 // ---------------------------------------------------------------------------
 // Task workspace.
 // ---------------------------------------------------------------------------
@@ -73,7 +75,7 @@ export const CAPABILITY_SOURCES = ["queue", "ungoverned", "undetermined"];
 // Task commands.
 // ---------------------------------------------------------------------------
 export const TASK_COMMAND_NAMES = {
-    voice: ["answer", "decline", "call", "mute", "hold", "resume", "end-call",
+    voice: ["answer", "decline", "call", "hold", "resume", "end-call",
         "connect-back", "transfer", "lead-assist", "conference", "recording", "complete"],
     chat: ["accept", "decline", "pause", "resume", "complete"],
     email: ["accept", "decline", "complete"],

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Snapshot, type Task, type TaskCompletion, type BreakApproval, type BrowserSessionKeyInput, type Channel, type ConnectContext, type Host, type HostGuarantees, type HostReport, type Manifest, type ProviderEvent } from "./index.js";
+import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Snapshot, type Task, type TaskCompletion, type BreakApproval, type BrowserSessionKeyInput, type Channel, type ConnectContext, type Host, type HostGuarantees, type HostMute, type HostReport, type Manifest, type ProviderEvent } from "./index.js";
 import { type ProtocolViolation } from "./validation.js";
 export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation } from "./validation.js";
 /**
@@ -153,8 +153,11 @@ export declare function assertBreakFollowsItsRequests(envelopes: readonly Provid
  * follows the media ending is `completing` or `task-ended`.
  */
 export declare function assertMediaFollowsTheTask(envelopes: readonly ProviderEventEnvelope[], snapshot?: Snapshot): void;
-/** A host that reports one thing and never changes: what most adapter tests hand `exerciseAdapter`. */
-export declare function stillHost(report?: HostReport, guarantees?: HostGuarantees): Host;
+/**
+ * A host that reports one thing and never changes: what most adapter tests hand `exerciseAdapter`.
+ * A softphone host states what its Mute does; a desk-phone or conversation host has no microphone and states nothing.
+ */
+export declare function stillHost(report?: HostReport, guarantees?: HostGuarantees, mute?: HostMute): Host;
 /** One provider as the host sees it when freezing the providers a break attempt asks. */
 export interface BreakCandidate {
     id: string;

package/dist/testing.js

@@ -1,5 +1,5 @@
 import { browserSessionKey, effectiveLevels, sameCapabilities, } from "./index.js";
-import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateManifest, validateResult, validateSnapshot, validateTask, validateTimeZone, validatePhone, validateTaskCommand, isTimeZone, sameTimeZone, } from "./validation.js";
+import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateHostMute, validateHandlingReport, validateManifest, validateResult, validateSnapshot, validateTask, validateTimeZone, validatePhone, validateTaskCommand, isTimeZone, sameTimeZone, } from "./validation.js";
 export { ProtocolConformanceError, assertNoViolations } from "./validation.js";
 /**
  * A part of the contract a run may never reach: state nothing obliges an adapter to publish, so
@@ -271,6 +271,8 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             violations.push({ rule: "context.host.audio.unexpected", path: "context.host.audio",
                 message: adapter.manifest.channel === "voice" ? "a desk-phone login has no audio in the host to report" : `a ${adapter.manifest.channel} connection has no audio for the host to report` });
         }
+        // What the host's Mute does is stated where the host holds a microphone, and nowhere else.
+        violations.push(...validateHostMute(context.host.mute, softphone, "context.host.mute"));
         unsubscribeHost = context.host.subscribe(report => {
             violations.push(...validateHostReport(report, "context.host"));
         });
@@ -289,6 +291,10 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         // On a softphone the call's audio lands in Omni, so the adapter has to open it; on a desk phone the host opens nothing.
         if (softphone)
             requireMethod(live, "openMedia", "the login is on a softphone");
+        // The microphone is the host's, so on a softphone every call can be muted by it, and the
+        // record of that leg is the provider's to take; on a desk phone the host holds no microphone.
+        if (softphone)
+            requireMethod(live, "recordStep", "the login is on a softphone, whose microphone the host mutes");
         const eventIds = new Set();
         // The drive waits on events: each waiter is offered every envelope as it lands.
         const waiters = new Set();
@@ -304,8 +310,6 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             violations.push(...undeterminedTasks(eventTasks(envelope), "event"));
             if (eventNamesUsers(envelope))
                 requireMethod(live, "describeUsers", "an event publishes a UserId");
-            if (eventDeclaresMute(envelope))
-                requireMethod(live, "recordStep", "a task declares mute, which the host performs and must have somewhere to record");
             // Cross-event rules apply once the stream has a beginning: the connect snapshot.
             if (seeded)
                 violations.push(...stream.apply(envelope), ...breaks.apply(envelope));
@@ -328,9 +332,6 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         requireCapabilityMethods(live, current().capabilities);
         if (publishesUserIds(snapshot))
             requireMethod(live, "describeUsers", "the snapshot publishes a UserId");
-        if (isRecord(snapshot) && Array.isArray(snapshot.tasks) && snapshot.tasks.some(taskDeclaresMute)) {
-            requireMethod(live, "recordStep", "a task declares mute, which the host performs and must have somewhere to record");
-        }
         // Capacity is stated, not requested: nothing may be allocated until it is, so a connection
         // that will not accept one is a connection nothing can be given to.
         // The guide's obligation on a voice adapter: consult the host before declaring the agent
@@ -369,7 +370,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             const localAudio = isRecord(first) && isRecord(first.audio) && isRecord(first.audio.input) && first.audio.input.status === "available"
                 ? first.audio.input.localAudio : undefined;
             violations.push(...await driveOneCall({
-                connection: live, channel: adapter.manifest.channel, softphone, snapshot, events, waiters, stream, localAudio,
+                connection: live, manifest: adapter.manifest, channel: adapter.manifest.channel, softphone, snapshot, events, waiters, stream, localAudio,
                 timeoutMs: options.driveTimeoutMs ?? 5000,
             }));
         }
@@ -445,18 +446,6 @@ const taskNamesUsers = (task) => isRecord(task) && ((isRecord(task.handlingHisto
     (isRecord(task.leadAssist) && task.leadAssist.leadId !== undefined) ||
     isRecord(task.assisting) ||
     isRecord(task.monitoring));
-/** Mute is the leg the host performs, so a task that allows it obliges the provider to take the record. */
-const taskDeclaresMute = (task) => isRecord(task) && isRecord(task.capabilities) && task.capabilities.mute !== undefined;
-function eventDeclaresMute(envelope) {
-    const event = isRecord(envelope) ? envelope.event : undefined;
-    if (!isRecord(event))
-        return false;
-    if (event.type === "task-offered" || event.type === "task-updated")
-        return taskDeclaresMute(event.task);
-    if (event.type === "snapshot" && isRecord(event.snapshot) && Array.isArray(event.snapshot.tasks))
-        return event.snapshot.tasks.some(taskDeclaresMute);
-    return false;
-}
 /** Whether an event publishes a `UserId`, on a roster, a task, or the snapshot a reconnect carries. */
 function eventNamesUsers(envelope) {
     const event = isRecord(envelope) ? envelope.event : undefined;
@@ -1034,6 +1023,49 @@ async function driveOneCall(drive) {
         else if (isRecord(opened))
             refuse("drive.openMedia.unavailable", "drive.openMedia", "a softphone login's adapter could not open the call's audio");
     }
+    // 3b. The microphone is the host's. With the audio open, the drive mutes it for a moment and
+    // reports the leg the provider's record would otherwise miss -- begun, then ended -- and
+    // expects each report recorded. If the provider restates the task's record afterwards, the leg is in it.
+    let mutedLeg;
+    if (session !== undefined && typeof session.setMuted === "function" && typeof drive.connection.recordStep === "function") {
+        const at = new Date().toISOString();
+        const report = async (body) => {
+            // The drive holds its own report to the contract before it crosses, as a host must.
+            const leg = { taskId, step: "muted", at, mutedBy: "host", ...body };
+            const own = validateHandlingReport(leg, "drive.recordStep.report", drive.manifest);
+            found.push(...own);
+            if (own.length > 0)
+                return;
+            let answer;
+            try {
+                answer = await drive.connection.recordStep(leg);
+            }
+            catch (error) {
+                refuse("drive.recordStep.rejected", "drive.recordStep", `recordStep rejected rather than answered: ${String(error)}`);
+                return;
+            }
+            found.push(...validateResult(answer, "recordStep", "drive.recordStep.result"));
+            if (isRecord(answer) && answer.status === "failed") {
+                refuse("drive.recordStep.failed", "drive.recordStep", `the provider refused to record the host's muted leg: ${String(isRecord(answer.failure) ? answer.failure.code : answer.failure)}`);
+            }
+        };
+        const setMuted = (muted) => {
+            try {
+                session.setMuted(muted);
+            }
+            catch {
+                refuse("drive.openMedia.setMuted", "drive.openMedia", `the media session threw on setMuted(${String(muted)})`);
+            }
+        };
+        const began = Date.now();
+        setMuted(true);
+        await report({});
+        // A leg's duration is whole seconds and a leg shorter than one cannot be stated, so the mute holds for one.
+        await new Promise(resolve => setTimeout(resolve, 1000));
+        setMuted(false);
+        await report({ seconds: Math.round((Date.now() - began) / 1000), ended: true });
+        mutedLeg = { at, task: latestTask() };
+    }
     // 4. Hold and resume, where offered.
     if (latestTask().phase === "in-progress" && offers("hold")) {
         if (await send({ type: drive.channel === "chat" ? "pause" : "hold" }) !== undefined) {
@@ -1053,7 +1085,21 @@ async function driveOneCall(drive) {
             }, cursor);
             if (mediaEnded !== undefined)
                 cursor = mediaEnded.at;
-            await updated(t => t.phase === "completing", "the task completing after its media ended");
+            if (await updated(t => t.phase === "completing", "the task completing after its media ended") !== undefined && offers("hold")) {
+                // The other direction of step 4: the same control, still declared, on a call that is over.
+                // A host holds it back (command.phase.handling), and an adapter that receives it anyway
+                // must refuse it -- so the drive sends it past the validator and expects failed.
+                let answer;
+                try {
+                    answer = await drive.connection.execute({ taskId, command: { type: "hold" } });
+                }
+                catch (error) {
+                    refuse("drive.command.rejected", "drive.command.hold", `execute rejected rather than answered: ${String(error)}`);
+                }
+                if (isRecord(answer) && answer.status !== "failed") {
+                    refuse("drive.command.handling", "drive.command.hold", `the provider applied hold on a completing task: a control on the contact belongs to in-progress or paused, and the adapter is the second gate`);
+                }
+            }
         }
     }
     if (typeof session?.close === "function") {
@@ -1080,6 +1126,20 @@ async function driveOneCall(drive) {
     else if (latestTask().phase === "completing") {
         await ended();
     }
+    // The record kept by the provider has the leg the host reported, wherever the provider restated it.
+    if (mutedLeg !== undefined && latestTask() !== mutedLeg.task) {
+        const history = latestTask().handlingHistory;
+        if (isRecord(history) && Array.isArray(history.steps)) {
+            const { at } = mutedLeg;
+            const leg = history.steps.find(entry => isRecord(entry) && entry.step === "muted" && entry.at === at);
+            if (leg === undefined) {
+                refuse("drive.recordStep.history", "drive.recordStep", `the provider restated the task's record after the host reported a muted leg at ${at}, and the leg is not in it`);
+            }
+            else if (leg.mutedBy !== "host") {
+                refuse("drive.recordStep.history", "drive.recordStep", `the record's muted leg at ${at} says mutedBy ${String(leg.mutedBy)}; the host reported host, and the record keeps the host's word`);
+            }
+        }
+    }
     return found;
 }
 // A request goes not-requested -> awaiting-decision | granted; a commit goes granted ->
@@ -1159,9 +1219,12 @@ export function assertMediaFollowsTheTask(envelopes, snapshot) {
     envelopes.forEach((envelope, index) => found.push(...stream.apply(envelope, `envelopes[${index}]`)));
     assertNoViolations(found, "The media follows the task");
 }
-/** A host that reports one thing and never changes: what most adapter tests hand `exerciseAdapter`. */
-export function stillHost(report = { online: true }, guarantees = {}) {
-    return { guarantees, report: () => report, subscribe: () => () => undefined };
+/**
+ * A host that reports one thing and never changes: what most adapter tests hand `exerciseAdapter`.
+ * A softphone host states what its Mute does; a desk-phone or conversation host has no microphone and states nothing.
+ */
+export function stillHost(report = { online: true }, guarantees = {}, mute) {
+    return { guarantees, ...(mute === undefined ? {} : { mute }), report: () => report, subscribe: () => () => undefined };
 }
 const usableLogin = (status) => status === "authenticated" || status === "refreshing";
 /**

package/dist/validation.d.ts

@@ -51,6 +51,12 @@ export interface ReaderContext {
 export declare function validateTeamRoster(roster: 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[];
+/**
+ * What pressing Mute does on this host, stated on a softphone login and nowhere else: on a desk
+ * phone the microphone is the phone's, and off voice there is none. Neither the value nor its
+ * absence is inferred from what kind of application the host is.
+ */
+export declare function validateHostMute(mute: unknown, softphone: boolean, path?: string): ProtocolViolation[];
 /**
  * What a host promises. Presence is the guarantee, so a key declared `false` is refused: a
  * promise withheld is an absent key, never a false one, exactly as a capability is.

package/dist/validation.js

@@ -96,7 +96,7 @@ const ISOLATION_SCHEME_VALUES = Object.values(BROWSER_ISOLATION_SCHEMES);
 /** The capabilities each channel arm of `TaskCapabilities` declares, keyed off the type itself. */
 const TASK_CAPABILITIES = {
     voice: membersOf({
-        browsers: true, dispositions: true, custom: true, decline: true, mute: true, hold: true,
+        browsers: true, dispositions: true, custom: true, decline: true, hold: true,
         endCall: true, connectBack: true, coldTransfer: true, warmTransfer: true, leadAssist: true, conference: true, recording: true,
     }),
     chat: membersOf({ browsers: true, dispositions: true, custom: true, decline: true, hold: true }),
@@ -574,7 +574,7 @@ const POLICY_SETTINGS = membersOf({ on: true, off: true, person: true });
 const POLICY_KEYS = new Set([
     ...TASK_CAPABILITIES.voice, ...TASK_CAPABILITIES.chat, ...TASK_CAPABILITIES.email, "dial",
 ].filter(name => name !== "browsers" && name !== "dispositions" && name !== "custom"));
-const PERSON_SETTABLE = /^(hold|mute|skill:.+)$/;
+const PERSON_SETTABLE = /^(hold|skill:.+)$/;
 const isLocked = (value) => isPlainObject(value) && value.lockedBy !== undefined;
 /** The level ids in force: the manifest's, or the defaults when the caller holds no manifest. */
 const levelIds = (levels) => levels ?? DEFAULT_LEVEL_IDS;
@@ -751,6 +751,12 @@ function validateHandlingHistory(value, path, into) {
             // Omitted while a leg is still running. Nought is a claim that it took no time.
             into.require(isDurationSeconds(entry.seconds) && entry.seconds > 0, "task.handlingHistory.seconds", `${at}.seconds`, "seconds must be a positive whole number; omit it while the step is still running");
         }
+        // A muted entry carries whose the silence was, as the host reported it; no other step has it.
+        if (entry.step === "muted")
+            into.oneOf(entry.mutedBy, MUTED_BY, "task.handlingHistory.mutedBy", `${at}.mutedBy`);
+        else if (HANDLING_STEPS.includes(entry.step)) {
+            into.require(entry.mutedBy === undefined, "task.handlingHistory.mutedBy.unexpected", `${at}.mutedBy`, "only a muted step says who silenced the microphone");
+        }
         if (entry.by !== undefined) {
             into.require(isUserId(entry.by), "task.handlingHistory.by", `${at}.by`, "by must be a non-empty user id; omit it when the person cannot be identified");
             // On `queued` nobody takes part, so there is nothing to name.
@@ -992,8 +998,13 @@ function validateTaskInto(task, context, path, into) {
     for (const [name, declared] of Object.entries(capabilities)) {
         if (declared === undefined)
             continue;
-        if (!into.require(allowed.includes(name), "task.capability.channel", `${path}.capabilities.${name}`, `a ${context.channel} task may not declare ${name}`))
+        if (!allowed.includes(name)) {
+            // A name another channel owns is a channel error; one no channel owns is not a capability at
+            // all -- mute among them, since the microphone is the host's and no provider declares it.
+            const known = Object.values(TASK_CAPABILITIES).some(names => names.includes(name));
+            into.add(known ? "task.capability.channel" : "task.capability.unknown", `${path}.capabilities.${name}`, known ? `a ${context.channel} task may not declare ${name}` : `${name} is not a capability a provider declares on any channel`);
             continue;
+        }
         // A control that dials needs the manifest to have said how a dial ends, or its outcome has no words.
         if (DIALLING_CAPABILITIES.includes(name) && context.dialOutcomesDeclared === false) {
             into.add("task.capability.dialOutcomes.required", `${path}.capabilities.${name}`, `${name} dials, and the manifest declares no dialOutcomes to say how a dial ends`);
@@ -1538,7 +1549,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
 // Results. A result crosses the same boundary a snapshot does, from an adapter that may be
 // compiled against another version, and Omni shows the agent what it says.
 // ---------------------------------------------------------------------------
-const PREFERENCE_ID = /^(hold|mute|skill:.+)$/;
+const PREFERENCE_ID = /^(hold|skill:.+)$/;
 /** The choices left to the person, each with where it stands. */
 function validatePreferencesInto(value, path, into, levels) {
     if (!Array.isArray(value)) {
@@ -1552,7 +1563,7 @@ function validatePreferencesInto(value, path, into, levels) {
             into.add("preference.shape", at, "each preference must be an object");
             return;
         }
-        if (into.require(typeof preference.id === "string" && PREFERENCE_ID.test(preference.id), "preference.id", `${at}.id`, "a preference is hold, mute, or skill:<id>: nothing else is the person's to set")) {
+        if (into.require(typeof preference.id === "string" && PREFERENCE_ID.test(preference.id), "preference.id", `${at}.id`, "a preference is hold or skill:<id>: nothing else is the person's to set")) {
             if (seen.has(preference.id))
                 into.add("preference.unique", `${at}.id`, `duplicate preference: ${preference.id}`);
             seen.add(preference.id);
@@ -1579,7 +1590,7 @@ function validateTeamPoliciesInto(value, path, into, levels) {
             continue;
         }
         if (into.oneOf(policy.setting, POLICY_SETTINGS, "team.policy.setting", `${at}.setting`)) {
-            into.require(policy.setting !== "person" || PERSON_SETTABLE.test(key), "team.policy.person", `${at}.setting`, `${key} is the team's, on or off; only hold, mute and skills may be left to the person`);
+            into.require(policy.setting !== "person" || PERSON_SETTABLE.test(key), "team.policy.person", `${at}.setting`, `${key} is the team's, on or off; only hold and skills may be left to the person`);
         }
         validateResolvedInto(policy, "team.policy", at, levels, into);
         into.require(policy.setBy !== "person", "team.policy.setBy", `${at}.setBy`, "a team policy is not set by a person");
@@ -1621,6 +1632,23 @@ function validateUnavailable(value, rule, path, into) {
  * hands the adapter.
  */
 const HOST_GUARANTEES = membersOf({ browserUrlVisibility: true, personConsent: true });
+const MUTED_BY = membersOf({ host: true, station: true });
+const HOST_MUTES = membersOf({ stream: true, station: true });
+/**
+ * What pressing Mute does on this host, stated on a softphone login and nowhere else: on a desk
+ * phone the microphone is the phone's, and off voice there is none. Neither the value nor its
+ * absence is inferred from what kind of application the host is.
+ */
+export function validateHostMute(mute, softphone, path = "host.mute") {
+    const into = new Collector();
+    if (mute === undefined) {
+        into.require(!softphone, "host.mute.required", path, "a softphone login's host states what its Mute does: stream or station");
+    }
+    else if (into.require(softphone, "host.mute.unexpected", path, "only a softphone login's host holds a microphone to mute; a desk phone's is the phone's, and a conversation has none")) {
+        into.oneOf(mute, HOST_MUTES, "host.mute", path);
+    }
+    return into.violations;
+}
 /**
  * What a host promises. Presence is the guarantee, so a key declared `false` is refused: a
  * promise withheld is an absent key, never a false one, exactly as a capability is.
@@ -1654,6 +1682,12 @@ export function validateHandlingReport(report, path = "handlingReport", manifest
     into.require(isTaskId(report.taskId), "handlingReport.taskId", `${path}.taskId`, "a report names the task");
     into.oneOf(report.step, HANDLING_STEPS, "handlingReport.step", `${path}.step`);
     into.timestamp(report.at, "handlingReport.at", `${path}.at`);
+    // A muted leg says whose the silence was; no other leg has anyone to name for it.
+    if (report.step === "muted")
+        into.oneOf(report.mutedBy, MUTED_BY, "handlingReport.mutedBy", `${path}.mutedBy`);
+    else if (HANDLING_STEPS.includes(report.step)) {
+        into.require(report.mutedBy === undefined, "handlingReport.mutedBy.unexpected", `${path}.mutedBy`, "only a muted leg says who silenced the microphone");
+    }
     if (report.seconds !== undefined) {
         into.require(isDurationSeconds(report.seconds) && report.seconds > 0, "handlingReport.seconds", `${path}.seconds`, "seconds must be a positive whole number; omit it rather than report nought");
     }
@@ -1669,6 +1703,15 @@ export function validateHandlingReport(report, path = "handlingReport", manifest
     }
     return into.violations;
 }
+/** A silenced device says who silenced it; one that flows, or whose flow the host cannot know, says nothing. */
+function validateMutedBy(device, rule, path, into) {
+    if (device.flowing === false) {
+        into.oneOf(device.mutedBy, MUTED_BY, `${rule}.mutedBy`, `${path}.mutedBy`);
+    }
+    else {
+        into.require(device.mutedBy === undefined, `${rule}.mutedBy.unexpected`, `${path}.mutedBy`, "mutedBy says who silenced a device that is not flowing; a flowing one names nobody");
+    }
+}
 export function validateHostReport(report, path = "host") {
     const into = new Collector();
     if (!isPlainObject(report)) {
@@ -1690,6 +1733,7 @@ export function validateHostReport(report, path = "host") {
     else if (input.status === "available") {
         into.require(typeof input.localAudio === "object" && input.localAudio !== null, "host.audio.input.localAudio", `${at}.localAudio`, "a ready input carries the captured microphone");
         into.require(typeof input.flowing === "boolean", "host.audio.input.flowing", `${at}.flowing`, "a ready input says whether audio is flowing through it");
+        validateMutedBy(input, "host.audio.input", at, into);
         into.require(input.failure === undefined, "host.audio.input.failure.unexpected", `${at}.failure`, "a ready input carries no failure");
         into.require(input.reason === undefined, "host.audio.input.reason.unexpected", `${at}.reason`, "a ready input has no reason to be unavailable");
     }
@@ -1698,6 +1742,7 @@ export function validateHostReport(report, path = "host") {
         validateUnavailable(input, "host.audio.input", at, into);
         into.require(input.localAudio === undefined, "host.audio.input.localAudio.unexpected", `${at}.localAudio`, "an unavailable input carries no microphone");
         into.require(input.flowing === undefined, "host.audio.input.flowing.unexpected", `${at}.flowing`, "an unavailable input has nothing to flow");
+        into.require(input.mutedBy === undefined, "host.audio.input.mutedBy.unexpected", `${at}.mutedBy`, "an unavailable input was not silenced; it is absent");
     }
     else {
         into.add("host.audio.input.status", `${at}.status`, `an input is available or unavailable, not ${String(input.status)}`);
@@ -1708,12 +1753,19 @@ export function validateHostReport(report, path = "host") {
         into.add("host.audio.output.shape", out, "audio carries its output");
     }
     else if (output.status === "available") {
+        // Whether the speaker is silenced is stated only where the host can know it: a browser mostly cannot, and omits it.
+        if (output.flowing !== undefined) {
+            into.require(typeof output.flowing === "boolean", "host.audio.output.flowing", `${out}.flowing`, "flowing says whether audio reaches the speaker, when the host can know");
+        }
+        validateMutedBy(output, "host.audio.output", out, into);
         into.require(output.failure === undefined, "host.audio.output.failure.unexpected", `${out}.failure`, "a ready output carries no failure");
         into.require(output.reason === undefined, "host.audio.output.reason.unexpected", `${out}.reason`, "a ready output has no reason to be unavailable");
     }
     else if (output.status === "unavailable") {
         into.oneOf(output.reason, HOST_OUTPUT_REASONS, "host.audio.output.reason", `${out}.reason`);
         validateUnavailable(output, "host.audio.output", out, into);
+        into.require(output.flowing === undefined, "host.audio.output.flowing.unexpected", `${out}.flowing`, "an unavailable output has nothing to flow");
+        into.require(output.mutedBy === undefined, "host.audio.output.mutedBy.unexpected", `${out}.mutedBy`, "an unavailable output was not silenced; it is absent");
     }
     else {
         into.add("host.audio.output.status", `${out}.status`, `an output is available or unavailable, not ${String(output.status)}`);
@@ -1754,9 +1806,6 @@ export function validateTaskCommand(command, task, path = "command") {
     }
     const dial = (rule) => into.filled(command.dialId, rule, `${path}.dialId`, "a command that dials carries the host's dialId");
     switch (type) {
-        case "mute":
-            into.require(typeof command.muted === "boolean", "command.mute.muted", `${path}.muted`, "mute says whether the agent is muted");
-            break;
         case "call":
             dial("command.call.dialId");
             break;
@@ -1831,6 +1880,10 @@ export function validateTaskCommand(command, task, path = "command") {
         return true;
     };
     const inPhase = (rule, ...phases) => into.require(phases.includes(String(task.phase)), rule, path, `${String(type)} belongs to ${phases.join(" or ")}, and the task is ${String(task.phase)}`);
+    // A control on the contact acts on a contact being handled. Before in-progress there is nothing
+    // to act on yet, and in completing the handling has ended: a call with nobody on it, a
+    // conversation closed. What a capability offers, the phase decides whether there is anything to use it on.
+    const handling = () => inPhase("command.phase.handling", "in-progress", "paused");
     const onCall = Array.isArray(task.onCall) ? task.onCall.filter(isPlainObject) : [];
     switch (type) {
         case "answer":
@@ -1844,25 +1897,26 @@ export function validateTaskCommand(command, task, path = "command") {
         case "call":
             inPhase("command.phase.preview", "preview");
             break;
-        case "mute":
-            offered("mute");
-            break;
         case "hold":
         case "resume":
         case "pause":
             offered("hold");
+            handling();
             break;
         case "end-call":
             offered("endCall");
+            handling();
             break;
         case "recording":
             offered("recording");
+            handling();
             break;
         case "connect-back":
             offered("connectBack");
             inPhase("command.phase.completing", "completing");
             break;
         case "transfer":
+            handling();
             if (command.action === "cold")
                 offered("coldTransfer");
             else if (command.action === "warm")
@@ -1872,6 +1926,7 @@ export function validateTaskCommand(command, task, path = "command") {
             }
             break;
         case "lead-assist":
+            handling();
             if (command.action === "request" || command.action === "cancel") {
                 offered("leadAssist");
                 if (command.action === "cancel") {
@@ -1883,6 +1938,7 @@ export function validateTaskCommand(command, task, path = "command") {
             }
             break;
         case "conference":
+            handling();
             if (offered("conference") && command.action === "remove") {
                 const others = onCall.filter(entry => entry.role !== "agent");
                 if (command.party === true) {

package/guide.md

@@ -271,12 +271,16 @@ type AuthenticationFailure = {
 type HostAudioUnavailableReason = "no-device" | "denied" | "not-asked" | "in-use" | "lost";
 type HostOutputUnavailableReason = "no-device" | "lost";
 
+type MutedBy = "host" | "station";
+
+type HostMute = "stream" | "station";
+
 type HostAudioInput =
-  | { status: "available"; localAudio: MediaStream; flowing: boolean }
+  | ({ status: "available"; localAudio: MediaStream } & ({ flowing: true; mutedBy?: never } | { flowing: false; mutedBy: MutedBy }))
   | { status: "unavailable"; reason: HostAudioUnavailableReason; failure: ProtocolFailure };
 
 type HostAudioOutput =
-  | { status: "available" }
+  | ({ status: "available" } & ({ flowing?: true; mutedBy?: never } | { flowing: false; mutedBy: MutedBy }))
   | { status: "unavailable"; reason: HostOutputUnavailableReason; failure: ProtocolFailure };
 
 type UrlVisibility = "full" | "domain" | "hidden";
@@ -296,6 +300,7 @@ type HostGuarantees = {
 
 type Host = {
   guarantees: HostGuarantees;
+  mute?: HostMute;
   report(): HostReport;
   subscribe(listener: (report: HostReport) => void): Unsubscribe;
 };
@@ -361,7 +366,7 @@ type AuthenticationSession = {
 ### Provider state
 
 ```ts
-type PreferenceId = "hold" | "mute" | `skill:${string}`;
+type PreferenceId = "hold" | `skill:${string}`;
 
 type SetBy = Level | "provider";
 
@@ -381,7 +386,10 @@ type SetPreferenceRequest =
   | { id: PreferenceId; enabled: boolean }
   | { id: PreferenceId; inherit: true };
 
-type HandlingReport = { taskId: TaskId; step: HandlingStep; at: IsoTimestamp } & (
+type HandlingReport = { taskId: TaskId; at: IsoTimestamp } & (
+  | { step: "muted"; mutedBy: MutedBy }
+  | { step: Exclude<HandlingStep, "muted">; mutedBy?: never }
+) & (
   | { ended: true; seconds: DurationSeconds }
   | { ended?: never; seconds?: DurationSeconds }
 );
@@ -484,7 +492,6 @@ type TaskCapabilities<C extends Channel = Channel> =
   C extends "voice"
     ? SharedTaskCapabilities & {
         decline?: Lockable<true>;
-        mute?: Lockable<true>;
         hold?: Lockable<true>;
         endCall?: Lockable<true>;
         connectBack?: Lockable<true>;
@@ -592,6 +599,7 @@ type TaskHandlingStep = {
   destinationId?: string;
   seconds?: DurationSeconds;
   by?: UserId;
+  mutedBy?: MutedBy;
 };
 
 type TaskCompletion =
@@ -692,7 +700,6 @@ const TASK_COMMAND_NAMES = {
     "answer",
     "decline",
     "call",
-    "mute",
     "hold",
     "resume",
     "end-call",
@@ -716,7 +723,6 @@ type VoiceTaskCommand =
   | { type: "answer" }
   | { type: "decline" }
   | { type: "call"; dialId: DialId }
-  | { type: "mute"; muted: boolean }
   | { type: "hold" }
   | { type: "resume" }
   | { type: "end-call" }
@@ -767,7 +773,7 @@ type TaskCommandResult =
 ### Who decides what an agent may do
 
 An agent desk has two managers, not one. **The queue** — a process, a work type — is owned by a
-process manager and **allows** a set of capabilities: hold, mute, connect back, new call, conference,
+process manager and **allows** a set of capabilities: hold, connect back, new call, conference,
 whether the number is visible, the actions it offers, the skills it needs. **The people** are
 managed through the organisation's structure — a team, a location, the organisation itself, in
 whatever combination the structure defines for a person — and **decide** per capability within
@@ -801,8 +807,8 @@ against them, not only the sign-in. What the wire carries is the resolution:
 **On a task, a control the queue could allow may stand locked in its place.** `Task.capabilities`
 is the effective set. What the queue does not allow is absent and nothing is shown. What the queue
 allows and a level above the person locked is present as `{ lockedBy, reason? }` where the control's
-value would be — `mute: { lockedBy: "team", reason: "Nobody on this team mutes" }` — and Omni
-renders that control disabled, saying who decided, so an agent who cannot press Mute knows whether
+value would be — `recording: { lockedBy: "team", reason: "Nobody on this team records" }` — and Omni
+renders that control disabled, saying who decided, so an agent who cannot press Record knows whether
 to ask their lead or their site. `lockedBy` is the discriminant: a value that carries it is the
 lock, so nothing that can be locked — a directory, a number — may carry that key itself. A
 contact's number and email are the same, since each identifies a person: where the queue says
@@ -813,14 +819,14 @@ controls — is content, and is never locked.
 
 **A lead sets the team's policy from their roster.** A login that declares
 `capabilities.team.policyControl` may `executeTeamPolicy({ type: "set", capability, setting })`
-with `on`, `off`, or `person`, for any task control, `dial`, or a skill — and only `hold`, `mute`
+with `on`, `off`, or `person`, for any task control, `dial`, or a skill — and only `hold`
 and skills may be `person`; connect back and new call are the team's, on or off, within what the queue
 allows. The roster carries `policies` for such a login: every policy as it stands, who set it, and
 `lockedBy` where a level above the team made it theirs to keep, which the lead sees and cannot
 change — `executeTeamPolicy` on it answers `failed` with `omni.capability-not-enabled`.
 
 **What the team left to the person is the person's, and the provider keeps it.** The login's
-`capabilities.preferences` lists every preference the person may hold — `hold`, `mute`, a skill —
+`capabilities.preferences` lists every preference the person may hold — `hold`, a skill —
 with where it stands and who set it: `setBy: "team"` while they inherit the team's default,
 `"person"` once they have set their own, `"provider"` where no level has said anything. Nothing
 is hidden for want of a row, and a preference a level above has since locked is listed with
@@ -831,8 +837,10 @@ inherit: true }` to give it up and inherit again — answered `applied` and repu
 person's preference from their own screen, which arrives the same way. A preference is keyed by
 the capability's own name because it is the same capability at another level: effective in
 `Task.capabilities`, set for the team in `policies`, left to the person in `preferences`. The
-command `mute` acts on one call; the preference `mute` says whether the person wants the control
-at all, and a host renders it in its settings, never as the button on a call.
+command `hold` acts on one call; the preference `hold` says whether the person wants the control
+at all, and a host renders it in its settings, never as the button on a call. Mute is in none of
+these ladders: the microphone is the host's, and nobody on the provider's side allows, locks or
+keeps a choice about it. See **The station is the host's**.
 
 ## Breaks
 
@@ -2003,7 +2011,7 @@ surface in one place, and what obliges an adapter to implement each one.
 | `executeTeamLeadAssist(command)` | The login declares `capabilities.team.leadAssistControl`. |
 | `executeTeamMonitor(command)` | The login declares `capabilities.team.monitorControl`. |
 | `setPreference(request)` | The login declares `capabilities.preferences`: the person's choice has to have somewhere to go. |
-| `recordStep(report)` | A task declares `mute`: the host performs that leg, and the provider's record has to have somewhere to take it. See **The host records what it performs**. |
+| `recordStep(report)` | The manifest lists `softphone` among its `phones`. On a softphone the host 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 host records what it performs**. |
 | `executeTeamPolicy(command)` | The login declares `capabilities.team.policyControl`. |
 | `openMedia(request)` | The manifest lists `softphone` among its `phones`. On a softphone the call's audio lands in Omni, so the adapter has to open it; a platform of desk phones alone never does. |
 
@@ -2187,7 +2195,7 @@ into a new session.
 `task-offered` introduces a new task and does not imply acceptance.
 
 `Task<C>` is channel-discriminated. For example, `Task<"email">` accepts
-`browsers` and `dispositions`, but rejects voice-only controls such as `mute` and `hold` at compile
+`browsers` and `dispositions`, but rejects voice-only controls such as `hold` and `endCall` at compile
 time. Runtime conformance checks also require the task channel to match its provider manifest.
 
 | Field | Contract |
@@ -2464,9 +2472,11 @@ history — until the task's media ends, and a hold neither pauses nor resets it
 duration is the `held` entry's `seconds`, and a desk that restarts its counter on resume is
 counting the wrong thing.
 
-`muted` is there because Omni performs the mute rather than the provider — see **Where a command
-executes** — so without a step the provider, which alone keeps the task's record, would have no
-account of a period the agent could not be heard.
+`muted` is there because the mute is the host's and never the provider's — see **The station is
+the host's** — so without a step the provider, which alone keeps the task's record, would have no
+account of a period the agent could not be heard. Each `muted` entry carries `mutedBy`, as the host
+reported it: `host` for the agent's own Mute, `station` for a headset or system mute the host
+observed. No other step has it (`task.handlingHistory.mutedBy`, `.mutedBy.unexpected`).
 
 **A step that dialled says which dial and where.** `transferred`, `conferenced` and `unanswered`
 each end a dial, so the entry carries the `destinationId` it went to and, where a host placed it, the
@@ -2522,8 +2532,8 @@ added here as a need is shown, not invented ahead of one.
 
 #### The host records what it performs
 
-`muted` is the one leg Omni performs rather than the provider, and a record kept by the provider
-would have a hole exactly there. So the host reports it, through `recordStep`, and the provider
+`muted` is the one leg the host performs rather than the provider, and a record kept by the
+provider would have a hole exactly there. So the host reports it, through `recordStep`, and the provider
 writes it into its record as it writes every other leg:
 
 ```ts
@@ -2531,9 +2541,9 @@ declare const connection: Connection<"voice">;
 declare const taskId: TaskId;
 declare const at: IsoTimestamp;
 
-void connection.recordStep?.({ taskId, step: "muted", at });                          // the moment the agent mutes
-void connection.recordStep?.({ taskId, step: "muted", at, seconds: 15 });             // still running, if the host chooses to say
-void connection.recordStep?.({ taskId, step: "muted", at, seconds: 42, ended: true }); // the moment they unmute
+void connection.recordStep?.({ taskId, step: "muted", at, mutedBy: "host" });                          // the moment the agent mutes
+void connection.recordStep?.({ taskId, step: "muted", at, mutedBy: "host", seconds: 15 });             // still running, if the host chooses to say
+void connection.recordStep?.({ taskId, step: "muted", at, mutedBy: "host", seconds: 42, ended: true }); // the moment they unmute
 ```
 
 The entry is keyed by `step` and `at`, so every report about one leg names the same instant. The
@@ -2546,7 +2556,11 @@ leg, when it began and when it ended, and `validateHandlingReport(report, path,
 a running one it was never asked for (`handlingReport.running.unexpected`). What a provider that
 did ask for them forwards upstream, and how often, is its own business. The step appears in
 `handlingHistory` when the *provider* publishes it: Omni never writes the record itself.
-`recordStep` is required of a connection whose tasks declare `mute`, and answers `recorded`.
+`recordStep` is required of every softphone login's connection, since every call on a softphone
+can be muted by the host, and answers `recorded`. A `muted` report says whose the silence was,
+`mutedBy: "host"` or `"station"`, and no other report has the word (`handlingReport.mutedBy`,
+`.mutedBy.unexpected`). On a desk phone the microphone is the phone's:
+the host mutes nothing and records nothing.
 
 **A host-performed leg still open when the task's media ends, or the task ends, is ended by the
 host at that instant** — `ended: true`, `seconds` to the end, the same `at` — since a provider
@@ -2762,12 +2776,16 @@ const taskCapabilities = {
 } satisfies Pick<Task<"voice">, "channel" | "capabilities" | "browsers">;
 ```
 
+A capability says the control may be offered; the task's phase says whether there is anything to use
+it on. Every control below that acts on the call or the conversation -- everything but `decline`,
+`connectBack` and `dispositions` -- is offered only while the task is `in-progress` or `paused`.
+See **Which commands need a capability**.
+
 ### Voice capabilities
 
 | Capability | Omni UI | Contract |
 | --- | --- | --- |
 | `decline` | Pending-task button: Decline | The provider can decline a pending voice offer. Omni shows it only when provisioning also permits declining. |
-| `mute` | Primary toggle: Mute | Omni may mute and unmute the agent's outbound audio. |
 | `hold` | Primary toggle: Hold | Omni may issue voice-task `hold` and `resume` commands. |
 | `endCall` | Primary button: End call | Omni may end the whole call: everyone leaves, the media ends, and the task stays for its wrap-up. See **Ending a call, and removing one person from it**. |
 | `connectBack` | Completing-task button: Connect back | Omni may have the provider connect the agent back to the task's party while the task is `completing`, returning it to `in-progress` on the same task. Not offered where there is no `completing` window: `provider-automatic` with a zero allowance disposes at provider end. See **Connecting back during completion**. |
@@ -3782,7 +3800,9 @@ what failed, and reports. It never decides for the adapter what a missing microp
 **The host 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 host 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. So `ConnectContext.host.guarantees` says which promises the
+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 host's**). So `ConnectContext.host.guarantees` says which promises the
 connected host makes, declared once per connection, presence being the guarantee exactly as it is
 the permission everywhere else:
 
@@ -3798,8 +3818,8 @@ refuses a false one, as it refuses a name this contract does not list.
 | --- | --- |
 | `online` | Whether the host 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 host 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 `openMedia` receives — and `flowing`, false while the hardware or OS says no audio moves through it (a headset's own mute switch, which Omni's Mute control never touches). `unavailable` with `reason`, since each wants a different fix from the agent: `no-device`; `denied`; `not-asked`, which a host 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. A host 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`, 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. |
+| `audio.input` | `available` with `localAudio` — the microphone as captured, the same stream `openMedia` receives — and `flowing`, false while no audio moves through it, when `mutedBy` says who stopped it: `host`, the host's own Mute on a host that mutes the station, or `station`, a slider on the headset or the operating system, which the host 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 a host 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. A host 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 host can know whether audio reaches the speaker — a browser mostly cannot, and omits it; a native host 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
@@ -3811,7 +3831,8 @@ The host's own obligations here — asking at connect, never publishing `not-ask
 publishing a state and not a flicker — are Omni's tests' to hold. `exerciseAdapter` holds the
 other side: it validates the shape of whatever host 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`) -- and refuses a voice adapter that never asked the
+(`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
 host anything (`connection.host.consulted`).
 
 ### Capacity around setup
@@ -3952,8 +3973,8 @@ unions are declared under **Shapes**.
 
 **A toggle carries the state it wants, not a flip.** Inverting whatever is found cannot converge
 with a stale view: a flip against a state the provider has already changed turns something on and
-then off again. `mute` therefore carries `muted`, and a custom `toggle` control carries its own
-boolean. `hold` and `resume`, `pause` and `resume` need no flag, being pairs rather than toggles.
+then off again. A custom `toggle` control therefore carries its own boolean. `hold` and `resume`,
+`pause` and `resume` need no flag, being pairs rather than toggles.
 
 **`complete` sends a disposition only where one was published.** `disposition` is a
 `DispositionCode.id` from the task's own `dispositions` capability, and `notes` obeys that
@@ -3961,14 +3982,10 @@ capability's `notes` setting. A task publishing no codes still receives `complet
 
 ### Where a command executes
 
-Every command reaches the provider through `execute`, with no branch at the call site. What differs
-is what the provider is being asked for: to **perform** the command, or to **record** that Omni
-already did.
-
-| Command | The provider's part |
-| --- | --- |
-| `mute` | **Record it, and keep the history.** The microphone is the host's, so Omni has already stopped the audio through `VoiceMediaSession.setMuted()` — no adapter can do that on the host's behalf. The command still arrives because the provider owns the task's record: it holds the current state for supervision, and each change as a `muted` handling step, exactly as it does for `held`. A platform that never hears about it shows a supervisor an agent who sounds absent for no reason, and reports a call with a silence it cannot explain. |
-| Every other command | **Perform it.** `hold`, `transfer`, `conference`, `end-call`, `recording` and the rest act on the platform's own call leg, its bridge, or its record of the task. Nothing has happened until the provider applies them. |
+Every command reaches the provider through `execute`, with no branch at the call site, and every
+command asks the provider to **perform** something: `hold`, `transfer`, `conference`, `end-call`,
+`recording` and the rest act on the platform's own call leg, its bridge, or its record of the
+task. Nothing has happened until the provider applies them, and `failed` means nothing happened.
 
 **The provider performs every action; the host only offers it.** A control drawn on the host is
 an affordance, never the enforcement: the host asks, and the provider does or declines. A provider
@@ -3977,16 +3994,75 @@ honouring its own declaration, not the host deciding policy -- a host that refus
 its own reading of a queue's flag has decided something that was never its to decide. What a
 command means on the platform is the provider's to work out: `end-call` ends the conversation, and
 which legs on which bridge that touches is a fact about the switch, never a choice the host makes.
-The one leg the host performs physically is the microphone, and even there the provider owns the
-record.
-
-**A failed `mute` does not unmute the agent.** The agent asked, Omni holds the microphone, and it
-is already done; a failure means only that the provider did not record it, leaving its view stale
-until the next snapshot. That is the safe direction to fail in, and it is the one place where
-`failed` does not mean *nothing happened* — everywhere else it does.
-
-`mute` carries `muted` rather than flipping, so a stale view converges on the stated state
-instead of flipping it back — see **Task commands**.
+The one thing the host performs physically is the microphone, and that is not a command at all.
+
+### The station is the host's
+
+The microphone, the speaker, the headset and its buttons are the station's, and the station is the
+host'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 host report,
+and the record of when the agent could not be heard, through `recordStep`. A host offers Mute on
+every voice task with media open, under its own provisioning, in `in-progress` and `paused`
+alone, and performs it through `VoiceMediaSession.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 host states which its Mute performs.** A *stream* mute stops the audio the
+host sends: the microphone keeps capturing, the party hears silence, nothing else on the machine
+changes, and every softphone host 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 host can do it. `Host.mute` says which
+this host does -- `stream` or `station` -- stated on a softphone login, where the host holds the
+microphone, and absent on a desk phone and off voice (`host.mute.required` / `.unexpected`). A
+browser says `stream`. A native host says whichever it does. Nothing on the wire says what kind of
+application the host is; a provider reads only what the host declared.
+
+**A silenced device says who silenced it.** `audio.input.flowing: false` and
+`audio.output.flowing: false` carry `mutedBy`: `host` when the host's own Mute did it -- which is
+only ever true of a host 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 host
+observed and did not do. Without the word, a station-muting host'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 host 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` handling leg is a period the agent could not be
+heard, and the record exists so that period is not a hole. The host 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.handlingHistory.mutedBy`). 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 host records what it performs**.
+
+**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 media starts, `mutedBy: "station"`. Media that
+ends while any leg is open ends the leg at that instant, as every host-performed leg ends. And the
+host's own Mute starts off on every call: an agent is never muted by the call before.
+
+**Every press on a headset is the agent's own press**, performed the host's way, and the lights
+follow the host'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 host 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 host writes back | A press of the host's Mute, performed the host's way; the LED follows the host'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 host'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 with no dial pad on a transfer, 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 host 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; a host 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 host 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 a host 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 host'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 host's Mute.
 
 ### Which commands need a capability
 
@@ -4009,6 +4085,17 @@ declared:
 | `lead-assist` with `action: "take-over"` or `"leave"` | The lead's own task, on a call they joined -- `Task.assisting` present. An agent's task never has it, and a provider that receives either without it answers `failed`. |
 | Everything else | Its own named capability. |
 
+**A control on the contact belongs to the handling phases**, `in-progress` and `paused`:
+`hold`, `resume` and `pause`, `end-call`, `recording`, every `transfer` and `conference` action, and
+every `lead-assist` action. Each acts on the call or the conversation, and only while there is one.
+Before `in-progress` nothing has been placed or opened; in `completing` the handling has ended -- a
+call with nobody on it, a conversation closed -- and a wrap-up that still shows Transfer shows it
+for nothing. The capability stays declared, because it is a property of the task and the task is
+still open; the phase says there is nothing to use it on. Omni shows none of these controls outside
+the two phases, and `validateTaskCommand` refuses each of them there (`command.phase.handling`).
+The commands with a phase of their own -- `answer`, `accept`, `decline` and `reject` in `pending`,
+`call` in `preview`, `connect-back` in `completing`, `complete` in any -- are not among them.
+
 `validateTaskCommand(command, task)` holds a command to this table at runtime, both ways: the
 capability it needs, the phase it belongs to, and the state that has to stand. The task it wants
 is the one the provider published, not a host's own mapping of it: a host that keeps only its
@@ -4376,8 +4463,9 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | `validateHostGuarantees(guarantees)` | What a host promises: only the guarantees this contract names, each declared by presence and never `false`. The harness validates the guarantees of whatever host a test hands the adapter. |
 | `validateHandlingReport(report, path?, manifest?)` | What the host reports of a leg it performed, for an adapter to check before forwarding: a task, a step, when it began, a positive `seconds` where stated, and an explicit `ended` that carries the final duration. Given the manifest, a running report is refused unless it declares `runningStepReports`. |
 | `validateHostReport(report)` | The host's own report as published to an adapter: `online`, and where there is audio, an input that is `available` with the microphone and `flowing`, or `unavailable` with a reason and the failure that says why, and an output that is `available` or `unavailable` with its failure. The harness validates whatever host a test hands the adapter; `stillHost(report)` builds one that never changes. |
+| `validateHostMute(mute, softphone)` | What the host's Mute does, stated on a softphone login and nowhere else: `stream` or `station` (`host.mute`), required where the host holds a microphone (`host.mute.required`) and refused where it does not (`host.mute.unexpected`). The harness holds `ConnectContext.host.mute` to it. |
 | `validateAuthenticationResult(result, method)` | What `start()` or `complete()` answered: a challenge or a rejection, a login or a rejection. A rejection's failure is held to its rules -- an `omni.` code the contract lists, and `omni.phone-not-permitted` never retryable, since the agent's station is configuration. `validateAuthenticationFailure(failure)` is the same check on a failure alone. |
-| `validateTaskCommand(command, task?)` | What a command needs to be issuable, against the task it names: its own shape -- a dial's `dialId`, a transfer's item, a remove naming exactly one person -- and, with the task, the capability the table above gates it on (`command.capability.<name>`, `.locked`), the phase it belongs to (`command.phase.*`), and the state that has to stand: a consulted entry, a lead requested, somebody else still on the call (`command.conference.remove.alone`). A host validates before sending and an adapter before acting. |
+| `validateTaskCommand(command, task?)` | What a command needs to be issuable, against the task it names: its own shape -- a dial's `dialId`, a transfer's item, a remove naming exactly one person -- and, with the task, the capability the table above gates it on (`command.capability.<name>`, `.locked`), the phase it belongs to (`command.phase.*`, `command.phase.handling` for every control on the call or the conversation), and the state that has to stand: a consulted entry, a lead requested, somebody else still on the call (`command.conference.remove.alone`). A host validates before sending and an adapter before acting. |
 | `validateResult(result, method)` | What a connection method answered: the status it gives, a failure where the status says so and nowhere else, the failure's shape, and that an `omni.` code is one this contract names. |
 | `validateAuthenticationState(state)` | The identity each state must carry, the capabilities a usable login declares, and the expiry that only `authenticated` may. Omni applies it to every state a session publishes — the republished as much as the first. |
 
@@ -4448,7 +4536,14 @@ complete it with a disposition where the agent completes -- and holds every step
 host holds a provider to. Each command is validated against the task as published
 (`drive.command.*`), each answer for its method, a refusal of a control the task offered is a
 violation (`drive.command.failed`), and an event the provider owes and never sends is one too
-(`drive.timeout`, after `driveTimeoutMs`, 5000 by default). A task the agent completes is
+(`drive.timeout`, after `driveTimeoutMs`, 5000 by default). With the audio open on a softphone,
+the drive mutes it for one second and reports the leg through `recordStep`, begun and then ended,
+expecting each report `recorded` (`drive.recordStep.failed`, `.rejected`); and where the provider
+restates the task's record afterwards, the leg is in it or the hole is named
+(`drive.recordStep.history`). Once the call has ended and the task is
+`completing`, the drive sends `hold` once more, past the validator that would hold it back, and
+expects `failed`: the adapter is the second gate on a control on the contact, and one that applies
+it on a call that is over is named (`drive.command.handling`). A task the agent completes is
 completed from wherever it stands once the drive has nothing left to do on it -- from `completing`
 after an `end-call`, or from `in-progress` where there is no call to end, which is every chat and
 email and a voice task offering no `endCall` -- so a conversation reaches its end as a call does.

package/package.json

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