@xema/omni-protocol 0.1.45 → 0.1.47

package/dist/index.d.ts

@@ -36,9 +36,21 @@ export type DialId = string;
 export type DurationSeconds = number;
 /** New channels require a later protocol version. */
 export type Channel = "voice" | "chat" | "email";
+/**
+ * An IANA time zone name, such as `Asia/Kolkata` -- never an offset, which cannot survive a
+ * daylight-saving boundary, and a day boundary is exactly where that bites.
+ */
+export type TimeZone = string;
 export interface User {
     id: UserId;
     displayName: string;
+    /**
+     * The zone this person's day is reckoned in, as the provider keeps it: stated by the host at
+     * authentication, stored on the agent, and carried on every identity and every described user
+     * so a day-scoped figure -- theirs or a colleague's a lead is reading -- is bucketed by the
+     * right day. Never absent: a person whose day nobody can name is not on this wire.
+     */
+    timeZone: TimeZone;
 }
 /** Key/value detail on a `Contact` or a `ScheduledActivity`. A task's attributes are typed. */
 export interface Attribute {
@@ -84,6 +96,14 @@ export interface DialCapability {
  */
 export type DialOutcome = "answered" | "busy" | "no-answer" | "unreachable" | "rejected" | "cancelled" | "unexplained";
 export declare const DIAL_OUTCOMES: readonly ["answered", "busy", "no-answer", "unreachable", "rejected", "cancelled", "unexplained"];
+/**
+ * How the agent hears the call: on a `softphone`, where the host owns the audio and opens it
+ * through `openMedia`, or on a `deskPhone`, a handset the platform rings, where the host opens
+ * nothing and only shows the call. A voice manifest lists the phones its platform supports, and
+ * the host picks one for the login at authentication.
+ */
+export type Phone = "softphone" | "deskPhone";
+export declare const PHONES: readonly ["softphone", "deskPhone"];
 /** Every idle capability a provider may declare. Only voice may `dial`; the channel arm says so. */
 export declare const IDLE_CAPABILITIES: readonly ["dial", "personalBrowser", "calendar", "contacts"];
 export type IdleCapability = (typeof IDLE_CAPABILITIES)[number];
@@ -135,6 +155,11 @@ export interface Manifest<C extends Channel = Channel> {
      * a task that may transfer, conference, or call back -- and forbidden off voice, where nothing dials.
      */
     dialOutcomes?: C extends "voice" ? DialOutcome[] : never;
+    /**
+     * The phones this platform can put an agent on. Required of every voice manifest, and forbidden
+     * off voice, where there is no call to hear. The host picks one of these per login.
+     */
+    phones?: C extends "voice" ? Phone[] : never;
     /**
      * The provider takes running reports of a host-performed step -- `recordStep` with `seconds`
      * so far and no `ended`. Absent, the host sends exactly two reports per leg, when it began and
@@ -151,6 +176,17 @@ export interface AuthenticationContext {
     protocolVersion: number;
     /** Omni's identity for this login. The same value arrives later as `ConnectContext.loginId`. */
     loginId: string;
+    /**
+     * The zone the agent's day is reckoned in, as the host's clock has it, stated before any
+     * identity exists so the first `authenticated` state already carries it. The same value arrives
+     * later as `ConnectContext.timeZone`.
+     */
+    timeZone: TimeZone;
+    /**
+     * How this login hears its calls, chosen by the host from the manifest's `phones`. Required for
+     * a voice provider and absent for any other. The same value arrives later as `ConnectContext.phone`.
+     */
+    phone?: Phone;
     /** Scoped to this provider's manifest id. */
     secrets: SecretStore;
     signal?: AbortSignal;
@@ -366,6 +402,14 @@ export interface ConnectContext {
     loginId: string;
     /** Omni-side policy: whether the agent's tasks are accepted without asking them. */
     autoAcceptTasks?: boolean;
+    /**
+     * The zone the agent's day is reckoned in, the same value passed as
+     * `AuthenticationContext.timeZone`. The provider stores it on the agent and carries it on the
+     * identity; a roaming agent corrects it by signing in.
+     */
+    timeZone: TimeZone;
+    /** The same value passed as `AuthenticationContext.phone`: how this login hears its calls. */
+    phone?: Phone;
     /**
      * The host's report of the agent's station, to consult before declaring the agent ready to the
      * platform and whenever it changes. Omni reports; the adapter decides.
@@ -1367,7 +1411,7 @@ export interface Connection<C extends Channel = Channel> {
     executeTeamMonitor?(request: TeamMonitorCommandRequest): Promise<TeamCommandResult>;
     /** Required when the login declares `capabilities.team.policyControl`. */
     executeTeamPolicy?(request: TeamPolicyCommandRequest): Promise<TeamCommandResult>;
-    /** Required of every voice adapter: all voice audio lands in Omni. */
+    /** Required of a voice adapter whose manifest lists `softphone`: on one, the call's audio lands in Omni. */
     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>;

package/dist/index.js

@@ -16,6 +16,7 @@ export function negotiateProtocolVersion(adapterVersions, hostVersions = OMNI_SU
     return shared.length === 0 ? undefined : Math.max(...shared);
 }
 export const DIAL_OUTCOMES = ["answered", "busy", "no-answer", "unreachable", "rejected", "cancelled", "unexplained"];
+export const PHONES = ["softphone", "deskPhone"];
 /** Every idle capability a provider may declare. Only voice may `dial`; the channel arm says so. */
 export const IDLE_CAPABILITIES = ["dial", "personalBrowser", "calendar", "contacts"];
 /** What Omni calls each idle capability. */

package/dist/testing.js

@@ -1,5 +1,5 @@
 import { browserSessionKey, effectiveLevels, sameCapabilities, } from "./index.js";
-import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateManifest, validateResult, validateSnapshot, } from "./validation.js";
+import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateManifest, validateResult, validateSnapshot, validateTimeZone, validatePhone, isTimeZone, } 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
@@ -255,14 +255,21 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         // voice connection's host reports its audio and no other does, and the host the adapter
         // receives is wrapped so the harness can tell whether the adapter ever asked.
         violations.push(...validateHostGuarantees(context.host.guarantees, "context.host.guarantees"));
+        // The zone is the host's to state, so a context without one is a host that cannot exist.
+        violations.push(...validateTimeZone(context.timeZone, "context.timeZone"));
+        // How the agent hears the call decides what the host owns: on a softphone the host has the
+        // audio and reports it; on a desk phone, or off voice, there is none for it to report.
+        violations.push(...validatePhone(context.phone, adapter.manifest, "context.phone"));
+        const softphone = adapter.manifest.channel === "voice" && context.phone === "softphone";
         const first = context.host.report();
         violations.push(...validateHostReport(first, "context.host"));
         const hasAudio = isRecord(first) && first.audio !== undefined;
-        if (adapter.manifest.channel === "voice" && !hasAudio) {
-            violations.push({ rule: "context.host.audio.required", path: "context.host.audio", message: "a voice connection's host reports its audio" });
+        if (softphone && !hasAudio) {
+            violations.push({ rule: "context.host.audio.required", path: "context.host.audio", message: "a softphone login's host reports its audio" });
         }
-        if (adapter.manifest.channel !== "voice" && hasAudio) {
-            violations.push({ rule: "context.host.audio.unexpected", path: "context.host.audio", message: `a ${adapter.manifest.channel} connection has no audio for the host to report` });
+        if (!softphone && hasAudio) {
+            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` });
         }
         unsubscribeHost = context.host.subscribe(report => {
             violations.push(...validateHostReport(report, "context.host"));
@@ -279,9 +286,9 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         // than an `enabled` flag, so its presence is the declaration.
         if (adapter.manifest.idleCapabilities?.dial !== undefined)
             requireMethod(live, "dial", "the manifest declares dial");
-        // Every voice task's audio lands in Omni, so there is no voice adapter that does not open it.
-        if (adapter.manifest.channel === "voice")
-            requireMethod(live, "openMedia", "the manifest channel is voice");
+        // 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");
         const eventIds = new Set();
         unsubscribe = connection.subscribe(envelope => {
             observeEvent(envelope, seen);
@@ -332,6 +339,16 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         const capacity = await connection.setCapacity({ count: 1 });
         const malformed = validateResult(capacity, "setCapacity", "connection.setCapacity");
         violations.push(...malformed);
+        // The provider republishes the agent's day: once connected, the identity carries the zone the
+        // host sent. That proves the round trip, not the store -- an echo passes it -- and the name
+        // says only what it tests; storage is proved by a colleague's zone arriving from describeUsers().
+        if (isTimeZone(context.timeZone) && current().identity.timeZone !== context.timeZone) {
+            violations.push({
+                rule: "authentication.identity.timeZone.republished",
+                path: "authentication.identity.timeZone",
+                message: `the host sent ${context.timeZone} at connect and the identity says ${String(current().identity.timeZone)}: the provider republishes the agent's time zone on the identity`,
+            });
+        }
         // A refusal is read only from a result that has the shape of one.
         if (malformed.length === 0 && capacity.status === "failed") {
             violations.push({

package/dist/validation.d.ts

@@ -9,6 +9,11 @@ export declare function assertNoViolations(violations: readonly ProtocolViolatio
 /** Every field is optional, so this checks what is present rather than what is missing. */
 export declare function validateContact(contact: unknown, path?: string): ProtocolViolation[];
 export declare function validateScheduledActivity(activity: unknown, path?: string): ProtocolViolation[];
+/**
+ * The host's choice of phone for a login, held to the manifest: one the platform listed, required
+ * on voice, absent elsewhere.
+ */
+export declare function validatePhone(value: unknown, manifest: unknown, path?: string): ProtocolViolation[];
 export declare function validateManifest(manifest: unknown, path?: string): ProtocolViolation[];
 export interface TaskValidationContext {
     /** The provider's channel, from its manifest. A task must agree with it. */
@@ -67,6 +72,10 @@ export type ResultMethod = "execute" | "dial" | "setCapacity" | "requestBreak" |
  * failure, a success carrying one, or an `omni.` code the contract lacks are each refused.
  */
 export declare function validateResult(result: unknown, method: ResultMethod, path?: string, dialId?: string): ProtocolViolation[];
+/** An IANA zone name the runtime knows: `Asia/Kolkata` is one, an offset or a made-up name is not. */
+export declare function isTimeZone(value: unknown): value is string;
+/** The zone a host sends at connect: required, and an IANA name. */
+export declare function validateTimeZone(value: unknown, path?: string): ProtocolViolation[];
 /** What a login is validated against beyond its own shape. */
 export interface LoginValidationContext {
     /** The level ids in force, from the manifest. The defaults when absent. */

package/dist/validation.js

@@ -84,6 +84,7 @@ const OFFERABLE_PHASES = membersOf({
     pending: true, confirmed: true, preview: true,
 });
 const PREVIEW_DEADLINES = membersOf({ calls: true, expires: true });
+const PHONES = membersOf({ softphone: true, deskPhone: true });
 const TEAM_CAPABILITIES = membersOf({ breakControl: true, leadAssistControl: true, policyControl: true, monitorControl: true });
 const MONITOR_MODES = membersOf({ monitor: true, whisper: true, barge: true });
 const COMPLETED_BY = membersOf({ agent: true, provider: true });
@@ -307,6 +308,45 @@ function validateDialOutcomes(manifest, path, into) {
         into.require(declared.some((outcome) => EXPLAINED_FAILURES.includes(outcome)), "manifest.dialOutcomes.unexplained.alone", path, "unexplained says the switch gave no cause, which is a claim only a provider that reports causes can make: declare at least one of busy, no-answer, unreachable, rejected, cancelled beside it");
     }
 }
+/**
+ * A voice platform says which phones it can put an agent on -- a softphone in the host, a desk
+ * phone it rings -- and nothing off voice does, since there is no call to hear.
+ */
+function validatePhones(manifest, path, into) {
+    const declared = manifest.phones;
+    if (manifest.channel !== "voice") {
+        into.require(declared === undefined, "manifest.phones.channel", path, `a ${String(manifest.channel)} provider has no call to hear and declares no phones`);
+        return;
+    }
+    if (!Array.isArray(declared) || declared.length === 0) {
+        into.add("manifest.phones.required", path, "a voice manifest lists the phones its platform can put an agent on: softphone, deskPhone, or both");
+        return;
+    }
+    declared.forEach((phone, index) => {
+        if (into.oneOf(phone, PHONES, "manifest.phone", `${path}[${index}]`) && declared.indexOf(phone) !== index) {
+            into.add("manifest.phone.unique", `${path}[${index}]`, `duplicate phone: ${String(phone)}`);
+        }
+    });
+}
+/**
+ * The host's choice of phone for a login, held to the manifest: one the platform listed, required
+ * on voice, absent elsewhere.
+ */
+export function validatePhone(value, manifest, path = "context.phone") {
+    const into = new Collector();
+    const channel = isPlainObject(manifest) ? manifest.channel : undefined;
+    const phones = isPlainObject(manifest) && Array.isArray(manifest.phones) ? manifest.phones : [];
+    if (channel !== "voice") {
+        into.require(value === undefined, "context.phone.unexpected", path, `a ${String(channel)} login has no call to hear and chooses no phone`);
+        return into.violations;
+    }
+    if (!into.require(value !== undefined, "context.phone.required", path, "a voice login says how the agent hears the call: one of the manifest's phones"))
+        return into.violations;
+    if (into.oneOf(value, PHONES, "context.phone", path)) {
+        into.require(phones.includes(value), "context.phone.unsupported", path, `the host chose ${String(value)} and the manifest lists ${phones.length === 0 ? "no phones" : phones.join(", ")}`);
+    }
+    return into.violations;
+}
 /** Whether a manifest says how a dial ends, and so may publish tasks that dial. `undefined` where there is no manifest to ask. */
 function manifestDials(manifest) {
     return isPlainObject(manifest) ? Array.isArray(manifest.dialOutcomes) : undefined;
@@ -347,6 +387,7 @@ export function validateManifest(manifest, path = "manifest") {
     if (channelValid)
         validateIdleCapabilities(manifest.idleCapabilities, manifest.channel, `${path}.idleCapabilities`, into);
     validateDialOutcomes(manifest, `${path}.dialOutcomes`, into);
+    validatePhones(manifest, `${path}.phones`, into);
     if (manifest.phaseLabels !== undefined) {
         if (!isPlainObject(manifest.phaseLabels)) {
             into.add("manifest.phaseLabels.shape", `${path}.phaseLabels`, "phaseLabels must be an object when present");
@@ -1733,6 +1774,26 @@ export function validateResult(result, method, path = "result", dialId) {
 // ---------------------------------------------------------------------------
 // Authentication.
 // ---------------------------------------------------------------------------
+/** An IANA zone name the runtime knows: `Asia/Kolkata` is one, an offset or a made-up name is not. */
+export function isTimeZone(value) {
+    // The runtime accepts a bare offset such as +05:30 as a zone; this wire does not, since an
+    // offset cannot say what day it is on either side of a daylight-saving change.
+    if (typeof value !== "string" || value.trim() === "" || /^[+-]/.test(value))
+        return false;
+    try {
+        new Intl.DateTimeFormat("en", { timeZone: value });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The zone a host sends at connect: required, and an IANA name. */
+export function validateTimeZone(value, path = "context.timeZone") {
+    const into = new Collector();
+    into.require(isTimeZone(value), "context.timeZone", path, "a host states the agent's time zone at connect as an IANA name, such as Asia/Kolkata; an offset cannot survive a daylight-saving boundary");
+    return into.violations;
+}
 function validateUser(value, rule, path, into) {
     if (!isPlainObject(value)) {
         into.add(rule, path, "an identity must be an object");
@@ -1740,6 +1801,8 @@ function validateUser(value, rule, path, into) {
     }
     into.require(isUserId(value.id), `${rule}.id`, `${path}.id`, "an identity needs a provider-issued user id");
     into.filled(value.displayName, `${rule}.displayName`, `${path}.displayName`, "an identity needs a display name");
+    // Never absent: the host stated the zone at authentication, before this identity existed.
+    into.require(isTimeZone(value.timeZone), `${rule}.timeZone`, `${path}.timeZone`, "every identity carries the agent's time zone as an IANA name, such as Asia/Kolkata; the host stated it at authentication");
 }
 function validateUserCapabilitiesInto(value, path, into, levels) {
     if (!isPlainObject(value)) {

package/guide.md

@@ -135,9 +135,12 @@ adapter**, **Live connection**, and **Authenticating with a provider**.
 ```ts
 type Channel = "voice" | "chat" | "email";
 
+type TimeZone = string;
+
 type User = {
   id: UserId;
   displayName: string;
+  timeZone: TimeZone;
 };
 
 type Attribute = { key: string; value: string };
@@ -168,6 +171,8 @@ type DialCapability = { destinations: DialDestinations };
 
 type DialOutcome = "answered" | "busy" | "no-answer" | "unreachable" | "rejected" | "cancelled" | "unexplained";
 
+type Phone = "softphone" | "deskPhone";
+
 type IdleCapabilities<C extends Channel = Channel> = {
   personalBrowser?: PersonalBrowserCapability;
   calendar?: true;
@@ -185,6 +190,7 @@ type Manifest<C extends Channel = Channel> = {
   taskTypePresentation?: Record<string, TaskTypePresentation>;
   orgLevels?: LevelDeclaration[];
   dialOutcomes?: C extends "voice" ? DialOutcome[] : never;
+  phones?: C extends "voice" ? Phone[] : never;
   runningStepReports?: true;
 };
 ```
@@ -225,6 +231,8 @@ type SecretStore = {
 type AuthenticationContext = {
   protocolVersion: number;
   loginId: string;
+  timeZone: TimeZone;
+  phone?: Phone;
   secrets: SecretStore;
   signal?: AbortSignal;
   log?: (entry: unknown) => void;
@@ -296,6 +304,8 @@ type ConnectContext = {
   protocolVersion: number;
   loginId: string;
   autoAcceptTasks?: boolean;
+  timeZone: TimeZone;
+  phone?: Phone;
   host: Host;
   signal?: AbortSignal;
   log?: (entry: unknown) => void;
@@ -1445,6 +1455,7 @@ compile time.
 | `phaseLabels` | Optional static adapter-defined display names for canonical `TaskPhase` values. They cannot vary at runtime. |
 | `taskTypePresentation` | Optional static adapter-defined presentation keyed by exact `taskType`. It names the item and its optional agent-facing reference. |
 | `orgLevels` | The organisation's whole ladder as the provider calls it, each level with the label a desk shows for "who decided". Stated outright, `person` included: what it leaves out does not exist. Omitted for the typical four, `DEFAULT_LEVELS`. See **Who decides what an agent may do**. |
+| `phones` | Voice only, and required there: the phones this platform can put an agent on, `softphone` (the call's audio lands in the host) and/or `deskPhone` (a handset the platform rings; the host shows the call and opens nothing). The host picks one per login. See **How the agent hears the call**. |
 | `dialOutcomes` | Voice only. How a dial can end on this platform, as it distinguishes them: `answered` and at least one way of not reaching the destination. Required of a provider that dials at all — an idle dialpad, or tasks that transfer, conference or call back — and a `dial-outcome` carries only a declared member. See **Every dial has an outcome**. |
 | `runningStepReports` | The provider takes running reports of a host-performed step — `recordStep` with `seconds` so far and no `ended`. Omitted, the host sends exactly two reports per leg, when it began and when it ended, and a running one is refused. See **The host records what it performs**. |
 
@@ -1700,6 +1711,8 @@ Creates the provider-scoped authentication session.
 | --- | --- |
 | `protocolVersion` | The negotiated version, fixed for this login. |
 | `loginId` | Omni-generated identity for this login. The same value Omni later passes as `ConnectContext.loginId`, and how an adapter ties a connection back to the session that authenticated it. |
+| `timeZone` | The zone the agent's day is reckoned in, as an IANA name from the host's clock, stated before any identity exists so the first `authenticated` state already carries it. The same value Omni later passes as `ConnectContext.timeZone`. See **The agent's day**. |
+| `phone` | How this login hears its calls, chosen by the host from the manifest's `phones`: required for a voice provider, absent for any other. The same value Omni later passes as `ConnectContext.phone`. See **How the agent hears the call**. |
 | `secrets` | Omni-provided `SecretStore`, scoped to this provider's manifest id. |
 | `signal` | Optional cancellation signal. |
 | `log` | Optional structured logging callback. Never include credentials, tokens, or sensitive contact data. |
@@ -1847,7 +1860,7 @@ too, by the rule that a command asking for a state answers success when that sta
 failure:
 
 ```ts
-{ status: "authenticated", identity: { id: "1042", displayName: "Asha Rao" }, capabilities: { breaks: true } }
+{ status: "authenticated", identity: { id: "1042", displayName: "Asha Rao", timeZone: "Asia/Kolkata" }, capabilities: { breaks: true } }
 ```
 
 The `User` it carries is the **root of this provider's user namespace**. Every other person this
@@ -1898,10 +1911,40 @@ Creates one live provider connection for the signed-in agent.
 | `protocolVersion` | Version negotiated before authentication. Fixed for this login. |
 | `loginId` | Omni-generated identity for this login. It is the same value passed as `AuthenticationContext.loginId`, so an adapter can correlate this connection with the session that authenticated it. Stable across transport reconnects and changed only by a new login. |
 | `autoAcceptTasks` | Agent provisioning policy relayed to the provider at login. Treated as `true` when omitted. When `true`, a pending task states its `acceptance`; when `false`, every task requires agent acceptance. Fixed for this connection, like everything else here: the provider states or omits `acceptance` by the value it was sent, and Omni validates by that same value, not by a policy that has since moved — a change reaches the provider through a fresh `connect()`. |
+| `timeZone` | The same value passed as `AuthenticationContext.timeZone`. The provider stores it on the agent and carries it on the identity. See **The agent's day**. |
+| `phone` | The same value passed as `AuthenticationContext.phone`: how this login hears its calls. |
 | `host` | The host's report of the agent's station — devices, permissions, network — to consult before declaring the agent ready to the platform, and on every change. See **The host reports, the adapter decides**. |
 | `signal` | Optional cancellation signal. Stop startup promptly when aborted and do not begin new work. |
 | `log` | Optional structured logging callback. Never include credentials, tokens, or sensitive contact data. |
 
+### The agent's day
+
+Every instant on this wire carries an explicit offset, so a moment is unambiguous everywhere and
+a desk renders it in the viewer's clock without help. A **day** is different: hours toward
+target, an answer streak, a per-queue count for today -- anything bucketed by day -- is bucketed
+by somebody's day, and a platform that was never told whose uses its own. An agent in Chennai
+then finds their day rolling at 05:30, and a night shift in Chicago lands in two buckets.
+
+So the host says whose day it is, and it says so first. `AuthenticationContext.timeZone` is the
+agent's zone as an IANA name -- `Asia/Kolkata`, `America/Chicago` -- never an offset, since an
+offset cannot survive a daylight-saving boundary and a day boundary is exactly where that bites
+(`context.timeZone`). It is stated before any identity exists, and `ConnectContext.timeZone` is the
+same value again. The provider **stores it on the agent** and carries it as `identity.timeZone` on
+every `authenticated` state and on every `User` it returns from `describeUsers()`, so a lead
+reading a colleague's yesterday sees the colleague's yesterday and a summary is bucketed by the
+right day after a session has ended. A roaming agent corrects it by signing in from where they are.
+
+**The zone is never absent.** Time zone awareness is a first-party property of this wire, not a
+field to fill in later: an identity without one is refused (`authentication.identity.timeZone`), and
+so is a zone that is not an IANA name, wherever it appears. Nothing is ever assumed in its place --
+not the viewer's browser, which gives a different answer per reader for the same record, and not the
+provider's clock. The harness holds a provider to the round trip: the identity carries the zone the
+host stated (`authentication.identity.timeZone.republished`). **The round trip is not the store.**
+An adapter that echoes the stated zone back onto the identity passes that check with nothing kept,
+and a lead reading a colleague's day would still get the wrong one. What proves the store is a zone
+the run never sent: a colleague's `User` from `describeUsers()` carrying theirs. A provider's own
+tests are where that is shown, with a second agent whose zone arrived through another session.
+
 ### Who the agent is
 
 `ConnectContext` names no agent. The adapter already knows who is connected: it authenticated them,
@@ -1943,7 +1986,7 @@ surface in one place, and what obliges an adapter to implement each one.
 | `disconnect()` | Always. |
 | `setCapacity(capacity)` | Always. Nothing may be allocated until a capacity is stated, so there is no connection that does not receive it. |
 | `execute(request)` | Always. Every channel has commands no capability gates — see **Which commands need a capability**. |
-| `describeUsers(ids)` | The adapter publishes any `UserId`: on `ImposedBreak.by`, a roster, or `handlingHistory[].by`. |
+| `describeUsers(ids)` | The adapter publishes any `UserId`: on `ImposedBreak.by`, a roster, or `handlingHistory[].by`. Each `User` carries its `timeZone` where the provider knows it. |
 | `dial(request)` | The manifest declares `idleCapabilities.dial`, and with it `dialOutcomes`. |
 | `requestBreak(request)` | The login declares `capabilities.breaks`. |
 | `commitBreak()` | The login declares `capabilities.breaks`. Commit and cancel are not optional halves of it. |
@@ -1955,7 +1998,7 @@ surface in one place, and what obliges an adapter to implement each one.
 | `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**. |
 | `executeTeamPolicy(command)` | The login declares `capabilities.team.policyControl`. |
-| `openMedia(request)` | The manifest channel is `voice`. Every voice task's audio lands in Omni, so there is no voice adapter that does not implement it. |
+| `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. |
 
 **The four break methods stand or fall together.** Declaring `capabilities.breaks` at login and then
 implementing `requestBreak` without `commitBreak` leaves an agent granted a break that can never
@@ -2104,7 +2147,8 @@ medium the task arrives on, not a separate decision.
 
 **Once a task is accepted, the call that comes with it is answered.** Omni has no discretion
 there and the provider is not consulted twice: one decision about the work, and the medium
-follows it. Where the audio lands is not in question — it opens in Omni, as it always does.
+follows it. Where the audio lands was settled at sign-in — in Omni on a softphone, on the handset
+on a desk phone — and is not in question per call. See **How the agent hears the call**.
 
 Automatic acceptance still begins with `task-offered`.
 
@@ -2249,6 +2293,12 @@ ends with an `expired` outcome naming `preview`. The two travel together
 "expires in 12s" from the provider's word. With neither, the agent has as long as they need.
 Reaching the instant is not itself a transition: the provider reports what it did, as an event.
 
+**Drop both fields when the phase moves.** A provider that builds the `in-progress` task by
+spreading the `preview` one carries `previewEndsAt` and `atDeadline` with it, and the host refuses
+the update (`task.preview.deadline.unexpected`) while the provider's own state looks right: the
+desk hears nothing and the provider sees nothing wrong. The task past preview has no deadline to
+wait for, so it carries neither field.
+
 **A task is never its audio.** A voice task is the allocation: the call is offered when it is
 routed to the agent and accepted as its `acceptance` dictates, and its presence and phase follow
 the provider's reports about the work — never the audio. Wherever audio moves — an offer, a hold, a
@@ -3628,8 +3678,9 @@ is the one that knows whether an agent without a microphone, or without a speake
 The host'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 host a test hands the adapter, requires `audio` on
-a voice connection and none elsewhere (`context.host.audio.required` / `.unexpected`), and
-refuses a voice adapter that never asked the host anything (`connection.host.consulted`).
+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
+host anything (`connection.host.consulted`).
 
 ### Capacity around setup
 
@@ -3661,10 +3712,53 @@ once; a break says they are not working. Collapsing the two would leave a provid
 an agent at their limit 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 host
+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 host 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
+host makes for that agent -- so the manifest declares and the host chooses.
+
+```ts
+// Manifest: what the platform can do
+phones: ["softphone", "deskPhone"]
+// The host, 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 host'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 host reports its
+audio, the adapter implements `openMedia`, and `task-media-started` is the word to open it; on a
+desk phone the host reports no audio, opens nothing, and `task-media-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 `openMedia`; one that lists `softphone` always does.
+
+**The mode comes from the host; the status comes from the provider.** The host 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 a host in a browser cannot see. So the host's `phone` selects the branch, and
+the provider's own knowledge of the device decides readiness within it. A provider never overrides
+the host'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 host never calls `openMedia`.** There is no stream to hand over and
+no audio to attach; a host 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 `openMedia` 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: a host declares `phone` and nothing more. What a platform
+asks on surfaces of its own is its own decision.
+
 ### Opening the audio
 
-`openMedia` hands Omni the remote audio for one task. Every voice adapter implements it, because
-every voice task's audio lands in Omni:
+`openMedia` 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
 openMedia({ taskId, localAudio }): Promise<OpenMediaResult>

package/package.json

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