@xema/omni-protocol 0.1.125 → 0.1.127

package/dist/index.d.ts

@@ -281,6 +281,13 @@ export interface AuthenticationContext {
      * later as `ConnectContext.timeZone`.
      */
     timeZone: TimeZone;
+    /**
+     * The languages the agent reads, as BCP 47 tags, most preferred first, from the host's own
+     * setting. Never empty: the host states at least one. The provider words what the agent reads
+     * -- failure and transport messages -- by it, looked up as `localizedText()` does. The same
+     * value arrives later as `ConnectContext.languages`.
+     */
+    languages: readonly LanguageTag[];
     /**
      * 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`.
@@ -680,6 +687,8 @@ export type ConnectContext = {
      * identity; a roaming agent corrects it by signing in.
      */
     timeZone: TimeZone;
+    /** The same value passed as `AuthenticationContext.languages`: what the agent reads, most preferred first. */
+    languages: readonly LanguageTag[];
     /** Where the adapter keeps this login's operational state across a reload of the host. */
     store: LoginStore;
     /** The same value passed as `AuthenticationContext.phone`: how this login hears its calls. Narrowed by the arms below. */
@@ -1836,7 +1845,7 @@ export type ProviderEvent<C extends Channel = Channel> = {
     type: "transport-status";
     status: "error";
     recovery: TransportRecovery;
-    message?: string;
+    message: string;
 } | {
     type: "break-state";
     break: BreakState;

package/dist/testing.js

@@ -1,5 +1,5 @@
 import { browserSessionKey, effectiveLevels, sameCapabilities, } from "./index.js";
-import { assertNoViolations, validateAuthenticationState, validateBreakTransition, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateUserDetails, observeRules, ruleTested, validateHostMute, validateHostRecording, validateLoginStore, validateHistoryReport, validateManifest, validateResult, validateSnapshot, validateTask, validateTimeZone, validatePhone, validateTaskCommand, isTimeZone, sameTimeZone, } from "./validation.js";
+import { assertNoViolations, validateAuthenticationState, validateBreakTransition, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateUserDetails, observeRules, ruleTested, validateHostMute, validateHostRecording, validateLoginStore, validateHistoryReport, validateManifest, validateResult, validateSnapshot, validateTask, validateLanguages, 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
@@ -345,6 +345,8 @@ export async function testAdapter(adapter, context, options = {}) {
         violations.push(...validateHostGuarantees(context.host.guarantees, "context.host.guarantees", adapter.manifest.channel === "voice" ? context.phone : undefined));
         // 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"));
+        // So are the languages: what the agent reads is stated, never assumed.
+        violations.push(...validateLanguages(context.languages, "context.languages"));
         // How the agent hears the call decides what the host owns: on a softphone the host has the
         // audio and reports it; on a hardphone, or off voice, there is none for it to report.
         violations.push(...validatePhone(context.phone, adapter.manifest, "context.phone"));

package/dist/validation.d.ts

@@ -30,6 +30,8 @@ export declare function validateProviderTimeCheckRequest(value: unknown, path?:
 /** Checks response shape/correlation, not source-clock accuracy, round-trip delay or freshness. */
 export declare function validateProviderTimeCheckResult(value: unknown, request: unknown, loginId: string, path?: string): ProtocolViolation[];
 export declare function validateManifest(manifest: unknown, path?: string): ProtocolViolation[];
+/** The agent's languages, as a host states them on both contexts: BCP 47 tags, most preferred first, at least one. */
+export declare function validateLanguages(value: unknown, path?: string): ProtocolViolation[];
 /** The customer's own words, as `Snapshot.labels` and `labels-updated` carry them. */
 export declare function validateLabels(value: unknown, path?: string): ProtocolViolation[];
 export interface TaskValidationContext {

package/dist/validation.js

@@ -563,6 +563,25 @@ export function validateManifest(manifest, path = "manifest") {
 }
 /** Language tags as BCP 47 writes them: a language, then subtags of up to eight letters or digits. */
 const LANGUAGE_TAG = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8})*$/;
+/** The agent's languages, as a host states them on both contexts: BCP 47 tags, most preferred first, at least one. */
+export function validateLanguages(value, path = "context.languages") {
+    const into = new Collector();
+    if (!Array.isArray(value) || value.length === 0) {
+        into.add("context.languages", path, "the host states the languages the agent reads: at least one BCP 47 tag, most preferred first");
+        return into.violations;
+    }
+    const seen = new Set();
+    value.forEach((tag, index) => {
+        if (typeof tag !== "string" || !LANGUAGE_TAG.test(tag)) {
+            into.add("context.languages.tag", `${path}[${index}]`, `${describeValue(tag)} is not a BCP 47 language tag`);
+            return;
+        }
+        const key = tag.toLowerCase();
+        into.require(!seen.has(key), "context.languages.unique", `${path}[${index}]`, `${tag} is listed twice`);
+        seen.add(key);
+    });
+    return into.violations;
+}
 /** The customer's own words, as `Snapshot.labels` and `labels-updated` carry them. */
 export function validateLabels(value, path = "labels") {
     const into = new Collector();
@@ -2070,7 +2089,12 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             else {
                 into.require(event.recovery === undefined, "event.transportStatus.recovery.unexpected", `${at}.recovery`, "recovery goes with an error; nothing needs reviving here");
             }
-            if (event.message !== undefined) {
+            if (event.status === "error") {
+                if (into.require(event.message !== undefined, "event.transportStatus.message.required", `${at}.message`, "an error says why, in words the agent sees")) {
+                    into.filled(event.message, "event.transportStatus.message", `${at}.message`, "a message must not be empty");
+                }
+            }
+            else if (event.message !== undefined) {
                 into.filled(event.message, "event.transportStatus.message", `${at}.message`, "a message must not be empty when present");
             }
             break;

package/guide.md

@@ -289,6 +289,7 @@ type AuthenticationContext = {
   protocolVersion: number;
   loginId: string;
   timeZone: TimeZone;
+  languages: readonly LanguageTag[];
   phone?: Phone;
   redirectUri?: string;
   secrets: SecretStore;
@@ -423,6 +424,7 @@ type ConnectContext = {
   loginId: string;
   autoAcceptTasks: boolean;
   timeZone: TimeZone;
+  languages: readonly LanguageTag[];
   store: LoginStore;
   phone?: Phone;
   host: Host;
@@ -1215,7 +1217,7 @@ type TransportRecovery = "reconnect" | "reauthenticate" | "displaced";
 type ProviderEvent =
   | { type: "snapshot"; reason: "reconnected" | "provider-requested"; snapshot: Snapshot }
   | { type: "transport-status"; status: "connecting" | "active"; message?: string }
-  | { type: "transport-status"; status: "error"; recovery: TransportRecovery; message?: string }
+  | { type: "transport-status"; status: "error"; recovery: TransportRecovery; message: string }
   | { type: "break-state"; break: BreakState }
   | {
       type: "task-offered";
@@ -2051,6 +2053,7 @@ 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 agent application'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**. |
+| `languages` | The languages the agent reads, as BCP 47 tags, most preferred first, from the agent application's own setting: `["hi-IN", "en"]`. Never empty (`context.languages`), each a well-formed tag (`context.languages.tag`), none twice (`context.languages.unique`). The same value Omni later passes as `ConnectContext.languages`. See **The agent's languages**. |
 | `phone` | How this login hears its calls, chosen by the agent application 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** in `guide/phone.md`. |
 | `secrets` | Omni-provided `SecretStore`, scoped to this provider's manifest id. |
 | `signal` | Optional cancellation signal. |
@@ -2075,7 +2078,7 @@ reports later changes.
 | `authenticated` | A usable session exists. Includes the provider identity, the login's `capabilities`, and optional token expiry time. |
 | `refreshing` | The adapter is refreshing its session. Existing provider identity and capabilities remain available, unchanged: a change to either is published as `authenticated`. |
 | `expired` | The session's time ran out, or its refresh is failing. It may include an identity and typed failure. The agent signs in again on the same login, and the workspace stays. |
-| `terminated` | The session was ended from outside this agent computer: by a supervisor, by the agent on another screen, or by the platform itself. `by` says who, a person by `UserId` or `provider` where no person was behind it (`authentication.terminated.by`), and `failure` says why and is never retryable (`authentication.terminated.failure`, `.retryable`). It is never reported as `expired`, which would hide who ended it, nor as `signed-out`, which is the agent's own act. |
+| `terminated` | The session was ended from outside this agent computer: by a supervisor, by the agent on another screen, or by the platform itself. `by` says who, a person by `UserId` or `provider` where no person was behind it (`authentication.terminated.by`), and `failure` says why and is never retryable (`authentication.terminated.failure`, `.retryable`). It is never reported as `expired`, which would hide who ended it, nor as `signed-out`, which is the agent's own act. The session's ending is the whole message: the agent application disposes the connection with `disconnect()` and shows `failure.message` on the sign-in, and the adapter reports no transport `error` beside it -- `reauthenticate` would say this session is restored, and it is not. |
 
 Omni calls `connect()` only after authentication reaches `authenticated`. Token refresh remains
 adapter-owned; the adapter publishes `refreshing`, followed by `authenticated` or `expired`.
@@ -2095,6 +2098,14 @@ calls `connect()` afresh, as for `reconnect` -- see **`transport-status`**. What
 replaces the login" describes is a new `AuthenticationSession` under a new `loginId`, after
 `signed-out`.
 
+**A sign-in the platform no longer allows is ended, not restored.** A role changed mid-shift can
+take away what the login was built on -- an agent made a supervisor may no longer have a phone, and
+the platform refuses to renew the softphone. Retrying cannot help and the same session cannot carry
+on, so the adapter deletes the secrets and publishes `terminated`, `by: "provider"`, with a failure
+in the agent's words: `{ code: "phone-not-allowed", message: "Your sign-in no longer allows a phone.
+Sign in again.", retryable: false }`. The agent application disposes the connection and shows that
+message on the sign-in.
+
 ### What the login may do
 
 `capabilities` declares provider actions available to this login rather than to one task: whether
@@ -2242,6 +2253,9 @@ short bound the adapter states, and then given up: a provider that cannot be rea
 token on the agent's machine. If it was not told, `signOut()` still deletes and still reaches
 `signed-out`, and answers `failed`, so the agent application can show that a session may remain at
 the provider. `close()` stops authentication-state observation but does not sign the agent out.
+The agent application ends the connection itself, with `disconnect()`: the sign-out is its own act,
+so the adapter reports no transport `error` for it, and a connection closed by the platform as the
+sign-out lands is not news to anyone.
 
 **The final moments are the agent application's to finish.** Its own steps before signing out --
 stopping capacity, putting tasks down -- may be retried within a short bound it states, and then
@@ -2312,6 +2326,7 @@ Creates one live provider connection for the signed-in agent.
 | `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 local policy policy relayed to the provider at login, stated by the agent application on every connection and never assumed from its absence. 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**. |
+| `languages` | The same value passed as `AuthenticationContext.languages`. See **The agent's languages**. |
 | `phone` | The same value passed as `AuthenticationContext.phone`: how this login hears its calls. The type ties `host.mute` to it: a `softphone` login's agent application states what its Mute does, and a hardphone or conversation login's agent application cannot, so the omission is a compile error rather than a live seat's discovery. See **The station is the agent application's** in `guide/phone.md`. |
 | `store` | The login's operational store, kept by the agent application for the life of the login, across a reload of the agent application, and cleared at sign-out: where an adapter that composes a record keeps what its platform cannot hold for it, such as the interaction legs an agent application reported. Three functions, by key. Never for anything sensitive, which is `AuthenticationContext.secrets`, a store an agent application may clear aggressively. **A task's keys carry its assignment id and go with the task**: a key written about a task names the assignment id in the key, and is deleted before the task's end is published, so that nothing of a closed task survives its ending and nothing is left for whatever comes next -- a record with legs the agent application never reported against it. A login-scoped key carries no assignment id and outlives any task. The harness requires the store of every connection (`store.shape`, `store.get`, `.set`, `.delete`), watches the one it hands over, and names a task's key still held after `task-ended` (`test.store.retained`) or written about the task after its end -- a persist hung off a timer that saw the task as it was (`test.store.late`). The ordinary late write is the agent application's, not the adapter's: an agent application reports a leg without waiting for the answer, so an unmute can follow `complete` by a tick, and the adapter answers a report about a task that has ended `failed` with `omni.assignment-not-found` and writes nothing -- the agent application ends its own open legs at the task's end, so such a report is the agent application's error to see, and an agent application reads every `recordStep` answer and awaits the one for the leg it closes at a task's end, the only moment a refusal is expected, since a report nobody waits for is an error nobody can see; an adapter that names no task in its keys gets no cleanup check, which is a gap rather than a pass, never an exemption: the obligation is that nothing of a closed task survives its ending, and an adapter that keeps every open task in one login-scoped value owes exactly that inside the value, where the harness cannot look. One key per task, named for it, is the shape the harness can hold, and the shape to reach for. The store lists nothing, so an adapter that needs to find its tasks keeps a login-scoped index of ids beside them; at the task's end it deletes the body first and reindexes after, since a crash between the two then leaves an index naming a task with no body, which a reader skips, where the other order leaves a body for a task that has ended, which is the hazard itself. A reader of the index tolerates an id with no body as an ending that was underway, not as corruption. |
 | `host` | The agent application'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 agent application reports, the adapter decides** in `guide/phone.md`. |
@@ -2349,6 +2364,17 @@ and a lead reading a colleague's day would still get the wrong one. What proves
 the run never sent: a colleague's `User` from `getUserDetails()` carrying theirs. A provider's own
 tests are where that is shown, with a second agent whose zone arrived through another session.
 
+### The agent's languages
+
+Everything the provider writes for the agent to read -- a failure's `message`, a transport
+`message`, a refusal's reason -- is written for one person, and the agent application says which
+languages that person reads: `languages`, BCP 47 tags in order of preference, on both contexts and
+the same value in each. It is stated, never assumed, as the zone is: never empty, because an empty
+list would be a default nobody chose, and the provider's own default is what the agent application
+falls back to only when no tag it was given matches. The provider picks a language the way
+`localizedText()` does -- each tag whole, then without its last subtag, in the agent's order -- and
+words its messages in the first it has. The harness holds the host to the shape (`validateLanguages`).
+
 ### Who the agent is
 
 `ConnectContext` names no agent. The adapter already knows who is connected: it authenticated them,
@@ -2687,7 +2713,7 @@ safe for the agent to see.
 | --- | --- |
 | `connecting` | No usable transport right now, and the adapter expects to recover on its own. Nobody needs to act. Startup and every reconnect pass through this value. |
 | `active` | The transport is up and the provider is serving this session. It is the only value under which work arrives. |
-| `error` | The adapter cannot serve the session and is not simply mid-reconnect. Say why in `message`, and say what revives it in `recovery` — required here, forbidden on any other status. It is not terminal: an adapter that recovers on its own still reports `connecting` and then `active`, and one that cannot is revived as `recovery` says. |
+| `error` | The adapter cannot serve the session and is not simply mid-reconnect. Say why in `message` (`event.transportStatus.message.required`), and say what revives it in `recovery` — both required here, and `recovery` forbidden on any other status. It is not terminal: an adapter that recovers on its own still reports `connecting` and then `active`, and one that cannot is revived as `recovery` says. |
 
 **An error names its recovery, and the agent application acts on that word.** The adapter knows why its session
 died; the agent application knows how to run a login. `recovery` joins the two:
@@ -2697,7 +2723,10 @@ died; the agent application knows how to run a login. `recovery` joins the two:
   `connect()` again on the same login — same `loginId` — and the fresh connect snapshot
   re-establishes state exactly as a reconnect snapshot does. `connect()` is once per
   `Connection`, not once per login.
-- **`reauthenticate`** — the session under the login died: a token rejected, a remote logout. Omni
+- **`reauthenticate`** — the session under the login lapsed and the same login can be restored: a
+  token rejected, published as `expired`. A session ended from outside -- a remote logout, a
+  permission withdrawn -- is `terminated`, which is the whole message and gets no transport `error`
+  beside it (see **Authentication state**). Omni
   runs the authentication flow first, on the same session and `loginId`, never through
   `signed-out`; the authentication session decides whether stored material refreshes it silently or
   the agent must act, exactly as at sign-in. Once the state returns to `authenticated`, Omni
@@ -2740,7 +2769,10 @@ adapter that leaves a stale `active` in place is telling Omni to keep waiting fo
 come — see **Liveness**.
 
 **The status is seen, not merely known.** An agent application renders the transport's status where the agent
-works — `connecting` from the moment it is reported, `error` with what revives it — and never a
+works — `connecting` from the moment it is reported, `error` with what revives it — and shows the
+provider's `message` as written, never a generic "disconnected" in its place: the provider knows why,
+and the words are what tell the agent whether to wait, sign in again or call somebody. The same holds
+for the `failure.message` of an `expired` or `terminated` session. Never a
 healthy workspace over a transport that cannot serve it: an agent talking on an agent computer whose transport
 died was an incident, and it happened because the agent computer knew and did not say. The same obligation
 covers a `diagnostic`: shown where the agent works, and counted.
@@ -3065,6 +3097,7 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | `validateLabels(value, path?)` | The customer's words on their own, as `labels-updated` and `Snapshot.labels` carry them: renames of the protocol's phases and steps only, and every word one text per well-formed language tag (`labels.*`). |
 | `validatePhoneState(value, path?, context?)` | The phone as the platform sees it, on its own as `phone-updated` and `Snapshot.phone` carry it: its status, its one active channel, its mute where a hardphone's is observed (`phone.*`). |
 | `validateHostMute(mute, softphone)` | What the agent application's Mute does, stated on a softphone login and nowhere else: `stream` or `station` (`host.mute`), required where the agent application holds a microphone (`host.mute.required`) and refused where it does not (`host.mute.unexpected`). The harness holds `ConnectContext.host.mute` to it. |
+| `validateLanguages(languages)` | The agent's languages a host states on both contexts: a non-empty list (`context.languages`) of well-formed BCP 47 tags (`context.languages.tag`), none twice ignoring case (`context.languages.unique`). The harness holds `ConnectContext.languages` to it. |
 | `validateLoginStore(store)` | The login's store the agent application hands every connection: an object with `get`, `set` and `delete` (`store.shape`, `store.get`, `.set`, `.delete`). The harness holds `ConnectContext.store` to it. |
 | `validateCapacity(capacity)` | What the agent application states as capacity: a whole number of zero or more (`capacity.count`), zero being agent application-stopped. The harness states one on connect and two, one and zero after the test, each answered `applied`, and holds any offer to the count in force (`stream.taskOffered.overCapacity`). |
 | `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. |

package/package.json

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