@xema/omni-protocol 0.1.54 → 0.1.55

package/dist/index.d.ts

@@ -1394,7 +1394,7 @@ export interface ProviderEventEnvelope<C extends Channel = Channel> {
     occurredAt: IsoTimestamp;
     event: ProviderEvent<C>;
 }
-export declare const OMNI_FAILURE_CODES: readonly ["omni.not-authenticated", "omni.capability-not-enabled", "omni.task-not-found", "omni.destination-not-permitted", "omni.rate-limited", "omni.unavailable", "omni.break-already-committed"];
+export declare const OMNI_FAILURE_CODES: readonly ["omni.not-authenticated", "omni.capability-not-enabled", "omni.task-not-found", "omni.destination-not-permitted", "omni.phone-not-permitted", "omni.rate-limited", "omni.unavailable", "omni.break-already-committed"];
 export type OmniFailureCode = (typeof OMNI_FAILURE_CODES)[number];
 export interface Connection<C extends Channel = Channel> {
     snapshot(): Snapshot<C> | Promise<Snapshot<C>>;

package/dist/index.js

@@ -102,6 +102,7 @@ export const OMNI_FAILURE_CODES = [
     "omni.capability-not-enabled",
     "omni.task-not-found",
     "omni.destination-not-permitted",
+    "omni.phone-not-permitted",
     "omni.rate-limited",
     "omni.unavailable",
     "omni.break-already-committed",

package/dist/validation.d.ts

@@ -91,4 +91,11 @@ export interface LoginValidationContext {
     /** The level ids in force, from the manifest. The defaults when absent. */
     levels?: readonly string[];
 }
+export declare function validateAuthenticationFailure(failure: 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
+ * to the same rules as any `authenticated` state.
+ */
+export declare function validateAuthenticationResult(result: unknown, method: "start" | "complete", path?: string, context?: LoginValidationContext): ProtocolViolation[];
 export declare function validateAuthenticationState(state: unknown, path?: string, context?: LoginValidationContext): ProtocolViolation[];

package/dist/validation.js

@@ -2053,6 +2053,61 @@ function validateMonitorControl(value, path, into) {
     });
     into.require(value.includes("monitor"), "authentication.capability.team.monitorControl.monitor", path, "whisper and barge begin from a monitor: a lead who may listen in any mode may monitor");
 }
+/**
+ * A failure an authentication reports: on a `rejected` start or completion, or on an `expired`
+ * state. A provider names its own codes freely; an `omni.` code is the contract's and has to be one
+ * it lists. `omni.phone-not-permitted` is never retryable: the agent's station is administrator
+ * configuration, and trying again does not reconfigure it.
+ */
+function validateAuthenticationFailureInto(value, path, into) {
+    if (!isPlainObject(value)) {
+        into.add("authentication.failure.shape", path, "a failure must be an object");
+        return;
+    }
+    if (into.filled(value.code, "authentication.failure.code", `${path}.code`, "a failure needs a code") && value.code.startsWith("omni.")) {
+        into.require(OMNI_FAILURE_CODES.includes(value.code), "failure.code.unknown", `${path}.code`, `${String(value.code)} is not a failure code this contract defines`);
+    }
+    into.filled(value.message, "authentication.failure.message", `${path}.message`, "a failure needs a message");
+    into.require(typeof value.retryable === "boolean", "authentication.failure.retryable", `${path}.retryable`, "a failure must say whether it is retryable");
+    if (value.code === "omni.phone-not-permitted") {
+        into.require(value.retryable === false, "authentication.failure.phone.retryable", `${path}.retryable`, "a phone the platform does not permit for this agent is configuration: trying again does not change it, so the refusal is not retryable");
+    }
+    if (value.retryAfterMs !== undefined) {
+        into.require(typeof value.retryAfterMs === "number" && value.retryAfterMs >= 0, "authentication.failure.retryAfterMs", `${path}.retryAfterMs`, "retryAfterMs must be a non-negative number when present");
+    }
+    if (value.field !== undefined)
+        into.filled(value.field, "authentication.failure.field", `${path}.field`, "field names a declared credentials field when present");
+}
+export function validateAuthenticationFailure(failure, path = "failure") {
+    const into = new Collector();
+    validateAuthenticationFailureInto(failure, path, into);
+    return into.violations;
+}
+/**
+ * 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
+ * to the same rules as any `authenticated` state.
+ */
+export function validateAuthenticationResult(result, method, path = "result", context = {}) {
+    const into = new Collector();
+    if (!isPlainObject(result)) {
+        into.add("authentication.result.shape", path, `${method} must answer an object`);
+        return into.violations;
+    }
+    if (result.status === "rejected") {
+        validateAuthenticationFailureInto(result.failure, `${path}.failure`, into);
+    }
+    else if (method === "start" && result.status === "interaction-required") {
+        into.require(isPlainObject(result.challenge), "authentication.result.challenge", `${path}.challenge`, "interaction-required carries the challenge to put to the person");
+    }
+    else if (method === "complete" && result.status === "authenticated") {
+        into.violations.push(...validateAuthenticationState(result, path, context));
+    }
+    else {
+        into.add("authentication.result.status", `${path}.status`, `${method} answers ${method === "start" ? "interaction-required" : "authenticated"} or rejected, not ${String(result.status)}`);
+    }
+    return into.violations;
+}
 export function validateAuthenticationState(state, path = "authentication", context = {}) {
     const into = new Collector();
     if (!isPlainObject(state)) {
@@ -2072,14 +2127,7 @@ export function validateAuthenticationState(state, path = "authentication", cont
         if (state.identity !== undefined)
             validateUser(state.identity, "authentication.identity", `${path}.identity`, into);
         if (state.failure !== undefined) {
-            if (!isPlainObject(state.failure)) {
-                into.add("authentication.failure.shape", `${path}.failure`, "a failure must be an object when present");
-            }
-            else {
-                into.filled(state.failure.code, "authentication.failure.code", `${path}.failure.code`, "a failure needs a code");
-                into.filled(state.failure.message, "authentication.failure.message", `${path}.failure.message`, "a failure needs a message");
-                into.require(typeof state.failure.retryable === "boolean", "authentication.failure.retryable", `${path}.failure.retryable`, "a failure must say whether it is retryable");
-            }
+            validateAuthenticationFailureInto(state.failure, `${path}.failure`, into);
         }
     }
     else {

package/guide.md

@@ -1120,6 +1120,7 @@ const OMNI_FAILURE_CODES = [
   "omni.capability-not-enabled",
   "omni.task-not-found",
   "omni.destination-not-permitted",
+  "omni.phone-not-permitted",
   "omni.rate-limited",
   "omni.unavailable",
   "omni.break-already-committed",
@@ -3799,6 +3800,21 @@ that is a telephone. The harness requires no `openMedia` of such an adapter 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.
 
+**A declared phone the platform does not permit for this agent is a login that cannot be
+established.** The manifest says what the platform can do; the agent's record, kept by an
+administrator, says what this agent is configured for, and the two can disagree with the host's
+declaration -- a softphone declared for an agent whose record says desk phone. Honouring that
+declaration on a switch that allows one registration per endpoint would evict the handset: the
+agent's phone stops ringing and their calls land in a tab, and nobody is told. So the provider
+refuses the login at authentication, with `omni.phone-not-permitted` and a message the host shows
+-- "this agent is configured for a desk phone" -- and refusing is correct, not an override of the
+host. It is a refusal, never a negotiation afterwards and never a quiet substitution, and it is
+never retryable: trying again does not reconfigure the agent, and a host validating the answer
+(`validateAuthenticationResult`) refuses a phone refusal marked otherwise
+(`authentication.failure.phone.retryable`). And **a
+provider never makes a declared phone true by changing the platform's configuration**: the record
+is the administrator's, and a login is not a request to reconfigure an agent.
+
 ### Opening the audio
 
 `openMedia` hands Omni the remote audio for one task. Every adapter whose manifest lists
@@ -3963,6 +3979,7 @@ react rather than only display the message:
 | `omni.not-authenticated` | The provider session is no longer usable. The adapter has published `expired` at or before this answer — the state is what Omni surfaces reauthentication from; the code says why this action failed, and is never the only signal. |
 | `omni.capability-not-enabled` | The action targets a capability this task, manifest, or login did not declare — including a lead command from a login whose `capabilities` no longer carry it. |
 | `omni.task-not-found` | The provider-local task id is unknown, typically after the task already ended. |
+| `omni.phone-not-permitted` | The host declared a `phone` the platform does not permit for this agent -- a softphone for an agent configured for a desk phone, or the reverse. The login is refused at authentication, and the provider never reconfigures the agent to make the declaration true. See **How the agent hears the call**. |
 | `omni.destination-not-permitted` | The dialled number, or the `destinationId` named, is not one the provider offers this agent. |
 | `omni.rate-limited` | The action was throttled. Pair with `retryAfterMs`. |
 | `omni.unavailable` | The provider is temporarily unable to serve the action, including any command sent while `transport-status` is not `active`. |
@@ -4270,6 +4287,7 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | `validateHostGuarantees(guarantees)` | What a host promises: only the guarantees this contract names, each declared by presence and never `false`. The harness validates the guarantees of whatever host a test hands the adapter. |
 | `validateHandlingReport(report, path?, manifest?)` | What the host reports of a leg it performed, for an adapter to check before forwarding: a task, a step, when it began, a positive `seconds` where stated, and an explicit `ended` that carries the final duration. Given the manifest, a running report is refused unless it declares `runningStepReports`. |
 | `validateHostReport(report)` | The host's own report as published to an adapter: `online`, and where there is audio, an input that is `available` with the microphone and `flowing`, or `unavailable` with a reason and the failure that says why, and an output that is `available` or `unavailable` with its failure. The harness validates whatever host a test hands the adapter; `stillHost(report)` builds one that never changes. |
+| `validateAuthenticationResult(result, method)` | What `start()` or `complete()` answered: a challenge or a rejection, a login or a rejection. A rejection's failure is held to its rules -- an `omni.` code the contract lists, and `omni.phone-not-permitted` never retryable, since the agent's station is configuration. `validateAuthenticationFailure(failure)` is the same check on a failure alone. |
 | `validateTaskCommand(command, task?)` | What a command needs to be issuable, against the task it names: its own shape -- a dial's `dialId`, a transfer's item, a remove naming exactly one person -- and, with the task, the capability the table above gates it on (`command.capability.<name>`, `.locked`), the phase it belongs to (`command.phase.*`), and the state that has to stand: a consulted entry, a lead requested, somebody else still on the call (`command.conference.remove.alone`). A host validates before sending and an adapter before acting. |
 | `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. |
@@ -4358,6 +4376,10 @@ assertReached(driven, ["task.onCall", "task.media", "event.task-ended"]);
 ```
 `assertReached(result, subjects)` is the paired assertion: it throws naming every subject the run
 never met, so a test that meant to check a roster cannot pass on a fixture that never produced one.
+It reads like a guarantee and is a claim the adopter keeps making: it catches an adapter that
+stopped reaching a subject, not a list that stopped asking, so a list can rot to nothing and stay
+green. Keep it honest with a control beside it -- one subject the run genuinely cannot reach,
+asserted to throw -- so the assertion is shown to be looking rather than agreeing.
 
 Three properties of the harness matter to adapter authors:
 

package/package.json

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