@xema/omni-protocol 0.1.123 → 0.1.125

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,
@@ -2095,6 +2117,20 @@ export declare const HISTORY_STEPS_WITH_A_PERSON: readonly ["offered", "answered
 /** The steps a dial writes, and so the only ones that carry a `dialId` and a `destinationId`. */
 export declare const HISTORY_STEPS_THAT_DIAL: readonly ["transferred", "conferenced", "unanswered"];
 export declare const historyStepDials: (step: HistoryStep) => boolean;
+/**
+ * Consecutive entries of one step, shown as one span. The record keeps an entry per occurrence --
+ * two holds are counted as two -- and this is how the agent sees them: once, from the first
+ * entry's `at`, lasting the sum of their `seconds` when every entry states one, and with no
+ * duration when any does not, never a sum that silently leaves a running leg out.
+ */
+export interface HistorySpan {
+    step: HistoryStep;
+    at: IsoTimestamp;
+    seconds?: DurationSeconds;
+    entries: TaskHistoryStep[];
+}
+/** Groups a record's consecutive same-step entries into spans, oldest first. */
+export declare function historySpans(steps: readonly TaskHistoryStep[]): HistorySpan[];
 /** Whether an absent `by` means "could not attribute" rather than "nobody was involved". */
 export declare function historyStepExpectsAPerson(step: HistoryStep): boolean;
 export interface BrowserSessionKeyInput {

package/dist/index.js

@@ -201,6 +201,23 @@ export const historyStepDials = (step) => HISTORY_STEPS_THAT_DIAL.includes(step)
 // Pinned both ways: a step added to `HistoryStep` has to be placed here, and a step listed here
 // has to exist there. `satisfies` on the list covers the second; this statement covers the first.
 true;
+/** Groups a record's consecutive same-step entries into spans, oldest first. */
+export function historySpans(steps) {
+    const spans = [];
+    for (const entry of steps) {
+        const last = spans[spans.length - 1];
+        if (last !== undefined && last.step === entry.step)
+            last.entries.push(entry);
+        else
+            spans.push({ step: entry.step, at: entry.at, entries: [entry] });
+    }
+    for (const span of spans) {
+        if (span.entries.every(entry => entry.seconds !== undefined)) {
+            span.seconds = span.entries.reduce((total, entry) => total + entry.seconds, 0);
+        }
+    }
+    return spans;
+}
 /** Whether an absent `by` means "could not attribute" rather than "nobody was involved". */
 export function historyStepExpectsAPerson(step) {
     return HISTORY_STEPS_WITH_A_PERSON.includes(step);

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

@@ -3090,6 +3090,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/agent.md

@@ -443,13 +443,16 @@ arrive omits it rather than guessing an instant. Omni shows it as *Incoming call
 Amazon Connect keeps an initiation time, Genesys Cloud a conversation start and NICE CXone a contact
 start, separate from the queue.
 
-**Time with the IVR or a bot is `self-service`.** The caller pressing through a menu, talking to a
-voice bot, or a chat customer with a bot before a person takes over: one step for all of them, on
-every channel, the way Genesys Cloud and NICE CXone report IVR and bot time together as
-self-service. Nobody from the provider takes part, so it has no `by`. `at` is when the customer
-entered it and `seconds`, once it ended, how long they spent there; a customer sent back to a menu
-after a transfer has a second entry, one per visit, as a second queue is a second `queued`. A
-customer that words it *IVR* for its agents does so in `labels.historySteps`.
+**Time the platform handles the customer before a queue is `self-service`.** The caller pressing
+through a menu, talking to a voice bot, hearing an announcement, or waiting while the platform
+looks them up; a chat customer with a bot before a person takes over: one step for all of them, on
+every channel. Genesys Cloud and NICE CXone report IVR and bot time as self-service; here it also
+takes in the routing time Genesys Cloud keeps as a separate system segment, so a provider that
+measures the gap before each queue without knowing what played in it reports it here rather than
+nowhere. It is therefore not evidence that the customer used a menu. Nobody from the provider takes
+part, so it has no `by`. `at` is when it began and `seconds`, once it ended, how long it lasted; a
+customer routed again after a transfer has a second entry, one per visit, as a second queue is a
+second `queued`. A customer that words it *IVR* for its agents does so in `labels.historySteps`.
 
 **A callback carries the call it comes back to.** When a caller asks to be called back, or an agent
 arranges it, the provider writes a `callback-requested` step: `by` names the agent who arranged it, and
@@ -483,7 +486,13 @@ provider closed it. One publisher of the closed leg, and no order between them t
 hold, at the entry's `at` plus its `seconds`, and nothing is lost by not naming it twice. The same goes for every step: two mutes are two
 `muted` entries, and a call that joined two queues -- a menu's, then this one -- has two `queued`
 entries, one per join. Order is enforced: an entry earlier than the one before it is refused
-(`task.history.order`). **Intervals between steps are the agent application's to subtract**, never a
+(`task.history.order`).
+
+**Shown as spans.** The record keeps one entry per occurrence, because leads count them — two holds
+are two holds, the way Amazon Connect counts holds per contact, and two queues say which queue the
+call waited in. The agent sees consecutive entries of one step as one span: `historySpans(steps)`
+groups them, as Genesys Cloud keeps segments apart in its record and joins them in the agent's
+timeline. A provider never merges entries to get that look. **Intervals between steps are the agent application's to subtract**, never a
 total the provider adds: *time to offer*, from the call joining its queue to the agent's screen lighting
 up, is the `offered` entry's `at` minus the last `queued` entry's, and the ring is outside it.
 `queueSeconds` keeps the industry's meaning -- the whole wait until somebody answered -- and is not

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 =
@@ -725,6 +727,13 @@ type TaskHistoryStep = {
   mutedBy?: MutedBy;
 };
 
+type HistorySpan = {
+  step: HistoryStep;
+  at: IsoTimestamp;
+  seconds?: DurationSeconds;
+  entries: TaskHistoryStep[];
+};
+
 type TaskCompletion =
   | { completionMode: "agent-command"; wrapAllowance?: DurationSeconds }
   | { completionMode: "provider-automatic"; wrapAllowance: DurationSeconds };
@@ -2125,17 +2134,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
 {
@@ -2150,7 +2174,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.
@@ -2288,8 +2315,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
 
@@ -2682,6 +2710,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
@@ -2990,6 +3031,14 @@ Whether two logins declare the same capabilities, field by field — key order a
 `team: {}` distinct from `team` absent. It is the comparison an adapter makes before republishing
 `authenticated`, and the one `testAdapter` holds `refreshing` to.
 
+### `historySpans(steps)`
+
+Groups a record's consecutive entries of one step into a `HistorySpan` each — `step`, the first
+entry's `at`, `seconds` summed when every entry states one and absent when any does not, and the
+`entries` themselves — so every agent application shows *Self-service · 30s* once where the
+record has two self-service entries in a row. Only neighbours are grouped: a hold, an answer and
+another hold are three spans. See **Shown as spans** in `guide/agent.md`.
+
 ## Runtime validation
 
 Structural rules in this document are executable through the runtime validators Omni applies to
@@ -3019,6 +3068,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.123",
+  "version": "0.1.125",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",