@xema/omni-protocol 0.1.124 → 0.1.126

package/dist/index.d.ts

@@ -286,6 +286,14 @@ export interface AuthenticationContext {
      * a voice provider and absent for any other. The same value arrives later as `ConnectContext.phone`.
      */
     phone?: Phone;
+    /**
+     * Where the provider's sign-in page sends the agent back, fixed for this host and adapter so the
+     * provider registers it once and its issuer compares it exactly (RFC 9700). Required when the
+     * host offers `browser-sso`. One of RFC 8252's three forms: `https`, a reverse-domain private-use
+     * scheme such as `com.example.omni:/auth/acme-voice`, or loopback `http://127.0.0.1:<port>/...`,
+     * where only the port varies. Never minted per flow: the flow travels in OAuth `state`.
+     */
+    redirectUri?: string;
     /** Scoped to this provider's manifest id. */
     secrets: SecretStore;
     signal?: AbortSignal;
@@ -389,7 +397,6 @@ export type AuthenticationChallenge = {
 export type StartAuthenticationRequest = {
     requestId: string;
     method: "browser-sso";
-    callbackUrl: string;
 } | {
     requestId: string;
     method: "credentials";
@@ -401,10 +408,15 @@ export type StartAuthenticationResult = {
     status: "rejected";
     failure: AuthenticationFailure;
 };
-export type CompleteAuthenticationRequest = {
-    flowId: string;
+export type CompleteAuthenticationRequest = 
+/**
+ * The whole URL the browser came back to, query included. It names no flow: the adapter finds
+ * its flow by the `state` it put in the authorization request, and refuses a state it never issued.
+ */
+{
     method: "browser-sso";
     callbackUrl: string;
+    flowId?: never;
 } | {
     flowId: string;
     method: "credentials";
@@ -678,8 +690,18 @@ export type ConnectContext = {
      * Mute is tied to the phone by the arms below.
      */
     host: Host;
+    /** The agent application giving up on this sign-in: stop promptly and reject `connect()` with `signal.reason`. */
     signal?: AbortSignal;
     log?: (entry: unknown) => void;
+    /**
+     * The transport-status `connecting` arm, for while `connect()` is still pending and there is no
+     * Connection to carry it: a seat limit, a sign-in queue. Callable only until `connect()` settles;
+     * from then on the Connection's own `transport-status` speaks. Optional for hosts.
+     */
+    transportStatus?: (update: {
+        status: "connecting";
+        message?: string;
+    }) => void;
 } & (
 /**
  * On a softphone the host holds the microphone and states what its Mute does; on a hardphone,
@@ -1814,7 +1836,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

@@ -379,8 +379,18 @@ export async function testAdapter(adapter, context, options = {}) {
             report: () => { consulted.report = true; return context.host.report(); },
             subscribe: listener => { consulted.subscribe = true; return context.host.subscribe(listener); },
         };
-        const connected = { ...context, host, store: watched.store };
-        connection = await adapter.connect(connected);
+        // A cancelled sign-in fails with the cancellation's own reason. The probe hands connect() a
+        // signal already aborted, so the answer is exact and owes nothing to the machine's speed; it
+        // gets the host and store unwrapped, so what it consults is not counted for the real connect.
+        violations.push(...await cancelledConnect(adapter, context));
+        const connecting = connectingReports({ ...context, host, store: watched.store }, violations);
+        const connected = connecting.context;
+        try {
+            connection = await adapter.connect(connected);
+        }
+        finally {
+            connecting.settled();
+        }
         // The standing client: the first connection, then the second after a hand-over. Everything the
         // harness asks of a connection it asks of the one that stands.
         let live = connection;
@@ -892,6 +902,56 @@ function refreshingCarriesOver(login, state, path) {
     }
     return found;
 }
+/** Calls `connect()` on an already-cancelled signal and names an adapter that connects anyway or fails for another reason. */
+async function cancelledConnect(adapter, context) {
+    const cancel = new AbortController();
+    cancel.abort(new Error("the agent application cancelled this sign-in"));
+    const { transportStatus: _unused, ...rest } = context;
+    try {
+        const stray = await adapter.connect({ ...rest, signal: cancel.signal });
+        try {
+            await stray.disconnect();
+        }
+        catch { /* the connection that should not exist is ended as far as it can be */ }
+        return [{ rule: "connect.signal.aborted", path: "connect.signal",
+                message: "connect() resolved on a signal already aborted; a cancelled sign-in fails with signal.reason" }];
+    }
+    catch (error) {
+        return error === cancel.signal.reason ? [] : [{ rule: "connect.signal.reason", path: "connect.signal",
+                message: `connect() on an aborted signal failed with ${String(error)}, not with signal.reason` }];
+    }
+}
+/**
+ * The host's `transportStatus`, handed on so that each report is checked: the `connecting` arm,
+ * and only while `connect()` is pending. After it settles the connection carries the status.
+ */
+function connectingReports(context, violations) {
+    const report = context.transportStatus;
+    if (report === undefined)
+        return { context, settled: () => { } };
+    let settled = false;
+    return {
+        context: {
+            ...context,
+            transportStatus: (update) => {
+                const at = "connect.transportStatus";
+                if (settled) {
+                    violations.push({ rule: "connect.transportStatus.late", path: at,
+                        message: "reported through the context after connect() settled; the connection's own transport-status speaks from then on" });
+                }
+                if (!isRecord(update) || update.status !== "connecting") {
+                    violations.push({ rule: "connect.transportStatus.status", path: `${at}.status`,
+                        message: `before a connection exists the only status is connecting, not ${JSON.stringify(isRecord(update) ? update.status : update)}` });
+                }
+                else if (update.message !== undefined && (typeof update.message !== "string" || update.message.trim() === "")) {
+                    violations.push({ rule: "connect.transportStatus.message", path: `${at}.message`, message: "a message must not be empty when present" });
+                }
+                report(update);
+            },
+        },
+        settled: () => { settled = true; },
+    };
+}
 /** Validates each state of a published sequence, and that every `refreshing` carries over the login before it. */
 function assertLoginSequence(states, summary) {
     const found = [];
@@ -1640,7 +1700,14 @@ async function testOneCall(call) {
                 catch { /* the session that would not restore is closed as far as it can be */ }
                 return;
             }
-            const second = await again.connect(call.context);
+            const reconnecting = connectingReports(call.context, found);
+            let second;
+            try {
+                second = await again.connect(reconnecting.context);
+            }
+            finally {
+                reconnecting.settled();
+            }
             // From here the second client is the run's connection, held to everything the first was on
             // connect: what it publishes is validated as before.
             await call.handOver.up(restoredSession, second);

package/dist/validation.d.ts

@@ -193,6 +193,12 @@ export interface LoginValidationContext {
     levels?: readonly string[];
 }
 export declare function validateAuthenticationFailure(failure: unknown, path?: string): ProtocolViolation[];
+/**
+ * A redirect URI in one of RFC 8252's three forms. A private-use scheme is reverse-domain (§7.1),
+ * a loopback is an IP literal rather than `localhost` (§8.3) and may vary only its port (§7.3),
+ * and none carries a fragment, which the authorization response could not be appended beside.
+ */
+export declare function validateRedirectUri(value: unknown, path?: string): ProtocolViolation[];
 /**
  * What `start()` or `complete()` answered: a challenge or a rejection from `start`, a login or a
  * rejection from `complete`. A rejection carries a failure the host can show, and a login is held

package/dist/validation.js

@@ -2070,7 +2070,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;
@@ -3090,6 +3095,33 @@ export function validateAuthenticationFailure(failure, path = "failure") {
     validateAuthenticationFailureInto(failure, path, into);
     return into.violations;
 }
+/**
+ * A redirect URI in one of RFC 8252's three forms. A private-use scheme is reverse-domain (§7.1),
+ * a loopback is an IP literal rather than `localhost` (§8.3) and may vary only its port (§7.3),
+ * and none carries a fragment, which the authorization response could not be appended beside.
+ */
+export function validateRedirectUri(value, path = "redirectUri") {
+    const into = new Collector();
+    if (!into.filled(value, "redirectUri", path, "browser SSO needs the fixed redirect URI the provider registered"))
+        return into.violations;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        into.add("redirectUri", path, `${describeValue(value)} is not an absolute URI`);
+        return into.violations;
+    }
+    into.require(url.hash === "" && !value.includes("#"), "redirectUri.fragment", path, "a redirect URI carries no fragment");
+    const scheme = url.protocol.slice(0, -1);
+    if (scheme === "http") {
+        into.require(url.hostname === "127.0.0.1" || url.hostname === "[::1]", "redirectUri.http", path, "plain http is for loopback only, as 127.0.0.1 or [::1] -- not localhost, which may resolve elsewhere");
+    }
+    else if (scheme !== "https") {
+        into.require(/^[a-z][a-z0-9+-]*(\.[a-z0-9+-]+)+$/.test(scheme), "redirectUri.scheme", path, `a private-use scheme is a reverse domain name the host controls, as com.example.omni; ${describeValue(scheme)} is not`);
+    }
+    return into.violations;
+}
 function validateAuthenticationChallenge(value, path, into) {
     if (!isPlainObject(value)) {
         into.add("authentication.result.challenge", path, "interaction-required carries the challenge to put to the person");

package/guide.md

@@ -290,6 +290,7 @@ type AuthenticationContext = {
   loginId: string;
   timeZone: TimeZone;
   phone?: Phone;
+  redirectUri?: string;
   secrets: SecretStore;
   signal?: AbortSignal;
   log?: (entry: unknown) => void;
@@ -427,6 +428,7 @@ type ConnectContext = {
   host: Host;
   signal?: AbortSignal;
   log?: (entry: unknown) => void;
+  transportStatus?: (update: { status: "connecting"; message?: string }) => void;
 } & (
   | { phone: "softphone"; host: { mute: HostMute } }
   | { phone?: "hardphone"; host: { mute?: never; recording?: never } }
@@ -447,7 +449,7 @@ type AuthenticationChallenge =
   | { flowId: string; method: "credentials"; fields: CredentialField[] };
 
 type StartAuthenticationRequest =
-  | { requestId: string; method: "browser-sso"; callbackUrl: string }
+  | { requestId: string; method: "browser-sso" }
   | { requestId: string; method: "credentials" };
 
 type StartAuthenticationResult =
@@ -455,7 +457,7 @@ type StartAuthenticationResult =
   | { status: "rejected"; failure: AuthenticationFailure };
 
 type CompleteAuthenticationRequest =
-  | { flowId: string; method: "browser-sso"; callbackUrl: string }
+  | { method: "browser-sso"; callbackUrl: string; flowId?: never }
   | { flowId: string; method: "credentials"; values: Readonly<Record<string, string>> };
 
 type CompleteAuthenticationResult =
@@ -1213,7 +1215,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";
@@ -2073,7 +2075,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`.
@@ -2093,6 +2095,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
@@ -2132,17 +2142,32 @@ short-lived, opaque `flowId`; rejection returns `AuthenticationFailure`.
 
 #### Browser SSO
 
-For `browser-sso`, Omni issues a one-time callback URL and passes it to `start()`:
+**The redirect URI is fixed, never minted per flow.** An issuer that follows current guidance
+compares the redirect URI exactly against the one registered (RFC 9700 §2.1, §4.1.3), so a path
+carrying a request id is refused by every one of them. The host states the URI once, for this host
+and adapter, as `AuthenticationContext.redirectUri`, and the provider registers it on its public
+client ahead of time. It takes one of the three forms RFC 8252 gives a native or browser app, as
+Google, Microsoft Entra and Okta register them:
+
+| Form | Example | When |
+| --- | --- | --- |
+| `https` | `https://agent.example.com/auth/acme-voice` | Omni in a browser tab, or a desktop app with a claimed https link. |
+| Private-use scheme | `com.example.omni:/auth/acme-voice` | A desktop app. The scheme is a reverse domain name the host controls (RFC 8252 §7.1). |
+| Loopback | `http://127.0.0.1:53127/auth/acme-voice` | A desktop app listening locally. Only the port varies between flows (§7.3); the host is the IP literal, never `localhost` (§8.3). |
+
+`validateRedirectUri(uri)` refuses anything else: a scheme that is not a reverse domain, such as
+`omni-agent:` (`redirectUri.scheme`), plain http to any host but the loopback literal
+(`redirectUri.http`), and a fragment (`redirectUri.fragment`). Its path names the adapter, so one
+host serves several providers on one scheme.
+
+`start()` then carries nothing about the callback:
 
 ```ts
-{
-  requestId: "auth-42",
-  method: "browser-sso",
-  callbackUrl: "omni-agent://auth/acme-voice/auth-42"
-}
+{ requestId: "auth-42", method: "browser-sso" }
 ```
 
-The adapter creates the OAuth/OIDC request, including PKCE, `state`, and OIDC `nonce`, and returns:
+The adapter creates the OAuth/OIDC request with its OAuth redirect URI set to the context's `redirectUri`,
+PKCE, OIDC `nonce`, and a `state` that names this flow, and returns:
 
 ```ts
 {
@@ -2157,7 +2182,10 @@ The adapter creates the OAuth/OIDC request, including PKCE, `state`, and OIDC `n
 ```
 
 Omni opens the requested `system` or `omni` browser. After redirect, it passes the complete callback
-URL to `complete()`. The adapter validates the flow, exchanges the authorization code, and returns
+URL, query included, to `complete()` as `{ method: "browser-sso", callbackUrl }`. The request names
+no flow: **the flow is found by `state`**, which the adapter issued and alone can read, and a
+`state` it never issued, or already used, is rejected. Omni routes the callback to the adapter by
+the URI's path and never encodes a request id in it. The adapter validates the flow, exchanges the authorization code, and returns
 the authenticated provider identity. Provider tokens never enter Omni UI or general protocol state.
 An Omni-hosted SSO browser uses a dedicated temporary authentication session and never shares
 cookies or storage with task or personal browsers.
@@ -2222,6 +2250,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
@@ -2295,8 +2326,9 @@ Creates one live provider connection for the signed-in agent.
 | `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`. |
-| `signal` | Optional cancellation signal. Stop startup promptly when aborted and do not begin new work. |
+| `signal` | Optional cancellation signal: the agent application giving up on this sign-in. When it is aborted, stop startup promptly, begin no new work, and reject `connect()` with `signal.reason`, as the web platform's own fetch does. The harness hands `connect()` a signal already aborted and names a connection made anyway (`connect.signal.aborted`) or a failure with anything but `signal.reason` (`connect.signal.reason`). |
 | `log` | Optional structured logging callback. Never include credentials, tokens, or sensitive contact data. |
+| `transportStatus` | Optional. The `connecting` arm of **`transport-status`**, for while `connect()` is still pending: same shape, same rule that `message` is safe for the agent to see. Callable only until `connect()` settles. See **Before the connection exists**. |
 
 ### The agent's day
 
@@ -2666,7 +2698,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:
@@ -2676,7 +2708,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
@@ -2689,6 +2724,19 @@ died; the agent application knows how to run a login. `recovery` joins the two:
   they are signed in elsewhere, with a way to take the login back, which is a `connect()` that
   displaces the other. See **`Adapter.connect(context)`**.
 
+**Before the connection exists.** A provider can hold a sign-in back before any connection
+stands: every agent licence on the site in use, a sign-in queue. The adapter retries as
+**Patience is the agent application's** asks, but until `connect()` resolves the agent application
+holds no `Connection` to hear `transport-status` from, and a first sign-in to a full site would
+just hang. So the adapter reports through `ConnectContext.transportStatus` -- `{ status:
+"connecting", message }`, the same arm and the same safety rule -- and the agent application
+renders it exactly as it renders `connecting`. Only `connecting`: a sign-in that cannot succeed
+rejects `connect()`. It is callable only until `connect()` settles, and from then on the
+connection's own `transport-status` speaks; the harness names a call made later
+(`connect.transportStatus.late`), a status other than `connecting` (`connect.transportStatus.status`)
+and an empty message (`connect.transportStatus.message`). A host may omit it, so an adapter calls
+it only where it is present.
+
 **Patience is the agent application's.** An adapter in `connecting` retries for as long as it takes and never
 has to decide when to stop. Omni owns giving up: after however long it chooses to wait, it may
 call `disconnect()` and either `connect()` afresh or surface the failure — so neither side waits
@@ -2706,7 +2754,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.
@@ -3034,6 +3085,7 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | `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. |
+| `validateRedirectUri(uri, path?)` | A host's fixed redirect URI in one of RFC 8252's forms: `https`, a reverse-domain private-use scheme, or loopback http to `127.0.0.1` or `[::1]`, with no fragment (`redirectUri.*`). |
 | `validateTaskCommand(command, task?)` | What a command needs to be issuable, against the task it names: its own shape -- a dial's `dialId`, a conference's item, a schedule's time, 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.interaction` for every control on the call or the conversation), and the state that has to stand: a lead requested, somebody else still on the call (`command.conference.remove.alone`), the caller off hold before the agent's part ends (`command.endCall.held`). An agent application 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. |

package/package.json

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