@xema/omni-protocol 0.1.53 → 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/testing.js

@@ -902,6 +902,10 @@ async function driveOneCall(drive) {
         const declared = capabilities[name];
         return declared !== undefined && !(isRecord(declared) && declared.lockedBy !== undefined);
     };
+    // Media may arrive any time after the accept, before or after the task's own update says
+    // in-progress: the event is the provider's word that the audio should attach, never a reply to
+    // openMedia, so the drive looks for it from the accept rather than from the last update it read.
+    const acceptedAt = drive.events.length;
     // 1. Accept the offer, if it is one.
     if (latestTask().phase === "pending") {
         if (await send({ type: drive.channel === "voice" ? "answer" : "accept" }) === undefined)
@@ -929,10 +933,10 @@ async function driveOneCall(drive) {
             const started = await waitFor("task-media-started for the driven task", envelope => {
                 const event = envelope.event;
                 return event.type === "task-media-started" && event.taskId === taskId ? event : undefined;
-            }, cursor);
+            }, acceptedAt);
             if (started === undefined)
                 return found;
-            cursor = started.at;
+            cursor = Math.max(cursor, started.at);
         }
         const opened = await drive.connection.openMedia?.({ taskId, localAudio: drive.localAudio });
         found.push(...validateResult(opened, "openMedia", "drive.openMedia"));
@@ -972,7 +976,10 @@ async function driveOneCall(drive) {
         }
     }
     // 6. Complete, where the agent completes; otherwise the provider does, and the drive waits for it.
-    if (latestTask().completionMode === "agent-command" && latestTask().phase === "completing") {
+    // A conversation has no media to end and no completing phase to wait for: a chat or an email,
+    // and a voice task offering no end-call, is completed from where it stands.
+    const completable = latestTask().phase === "completing" || latestTask().phase === "in-progress" || latestTask().phase === "paused";
+    if (latestTask().completionMode === "agent-command" && completable) {
         const command = { type: "complete" };
         const dispositions = isRecord(latestTask().capabilities) ? latestTask().capabilities.dispositions : undefined;
         if (isRecord(dispositions) && dispositions.required === true && Array.isArray(dispositions.codes) && isRecord(dispositions.codes[0])) {

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`. |
@@ -4127,6 +4144,9 @@ partial patch.
 The provider's word that the task's audio should now attach. Omni calls `openMedia` on it — and on
 a task carried with `media: "started"`, which is how a reconnect snapshot reattaches audio an
 earlier event brought — and renders the call as live from that word, never from its own senses. It
+precedes `openMedia` and is never a reply to it: a provider whose media state comes from the
+platform, a station going in use the moment a call is answered, sends it then, before any host has
+opened anything, and `openMedia` has its own answer for what the host did. It
 names a task whose work has begun, and it alternates with `task-media-ended`: media that never
 started cannot end, so a live call whose provider says nothing about its audio is a provider in
 breach, not a state a desk fills in from its own devices.
@@ -4267,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. |
@@ -4338,8 +4359,14 @@ complete it with a disposition where the agent completes -- and holds every step
 host holds a provider to. Each command is validated against the task as published
 (`drive.command.*`), each answer for its method, a refusal of a control the task offered is a
 violation (`drive.command.failed`), and an event the provider owes and never sends is one too
-(`drive.timeout`, after `driveTimeoutMs`, 5000 by default). The drive stops where the task offers
-no way on and says nothing about what it could not reach. It is off by default because it issues
+(`drive.timeout`, after `driveTimeoutMs`, 5000 by default). A task the agent completes is
+completed from wherever it stands once the drive has nothing left to do on it -- from `completing`
+after an `end-call`, or from `in-progress` where there is no call to end, which is every chat and
+email and a voice task offering no `endCall` -- so a conversation reaches its end as a call does.
+The drive stops where the task offers no way on and says nothing about what it could not reach. A
+softphone adapter written for a browser needs its media APIs supplied by whatever runs the
+harness: the drive opens media outside a browser, and a provider that quietly stopped carrying audio
+where `AudioContext` was missing would be lying about the one thing the channel is for. It is off by default because it issues
 commands against whatever platform the adapter is connected to: turn it on against a test backend.
 
 ```ts
@@ -4349,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.53",
+  "version": "0.1.55",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",