@xema/omni-protocol 0.1.29 → 0.1.31

package/dist/index.d.ts

@@ -1108,6 +1108,11 @@ export type ProviderEvent<C extends Channel = Channel> = {
 } | {
     type: "queue-summary";
     summary: QueueSummary;
+} | {
+    type: "diagnostic";
+    expected: string;
+    observed: string;
+    taskId?: TaskId;
 } | {
     type: "team-updated";
     team: TeamRoster;

package/dist/testing.js

@@ -33,7 +33,7 @@ const STATE_SUBJECTS = [
 // `ProviderEvent` without a row here, or a row it lacks, is a compile error.
 const EVENT_TYPES = {
     snapshot: true, "transport-status": true, "break-state": true, "task-offered": true, "task-updated": true,
-    "task-media-started": true, "task-media-ended": true, "task-ended": true, announcement: true, "queue-summary": true,
+    "task-media-started": true, "task-media-ended": true, "task-ended": true, announcement: true, "queue-summary": true, diagnostic: true,
     "team-updated": true, "contacts-updated": true, "calendar-updated": true,
 };
 const CONTRACT_SUBJECTS = [
@@ -281,6 +281,12 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         unsubscribe = connection.subscribe(envelope => {
             observeEvent(envelope, seen);
             violations.push(...validateEventEnvelope(envelope, adapter.manifest, "event", reader()));
+            // A diagnostic is informational to a host and a failure to a conformance run: the platform
+            // under test broke a rule the adapter relies on, and a green result must not paper over it.
+            if (isRecord(envelope?.event) && envelope.event.type === "diagnostic") {
+                violations.push({ rule: "diagnostic.raised", path: "event.diagnostic",
+                    message: `the provider reported a diagnostic: expected ${String(envelope.event.expected)}; observed ${String(envelope.event.observed)}` });
+            }
             if (eventNamesUsers(envelope))
                 requireMethod(live, "describeUsers", "an event publishes a UserId");
             // Cross-event rules apply once the stream has a beginning: the connect snapshot.

package/dist/validation.js

@@ -632,6 +632,7 @@ function validateHandlingHistory(value, path, into) {
         into.add("task.handlingHistory.shape", path, "handlingHistory must be an array when present");
         return;
     }
+    let previous;
     value.forEach((entry, index) => {
         const at = `${path}[${index}]`;
         if (!isPlainObject(entry)) {
@@ -639,7 +640,15 @@ function validateHandlingHistory(value, path, into) {
             return;
         }
         into.oneOf(entry.step, HANDLING_STEPS, "task.handlingHistory.step", `${at}.step`);
-        into.timestamp(entry.at, "task.handlingHistory.at", `${at}.at`);
+        if (into.timestamp(entry.at, "task.handlingHistory.at", `${at}.at`)) {
+            // The record is one entry per occurrence, oldest first: a second hold is a second entry
+            // after the first, never a revision of it or an entry filed out of its turn.
+            const instant = Date.parse(entry.at);
+            if (previous !== undefined && instant < previous) {
+                into.add("task.handlingHistory.order", `${at}.at`, "handling steps are oldest first; this entry is earlier than the one before it");
+            }
+            previous = instant;
+        }
         if (entry.seconds !== undefined) {
             // Omitted while a leg is still running. Nought is a claim that it took no time.
             into.require(isDurationSeconds(entry.seconds) && entry.seconds > 0, "task.handlingHistory.seconds", `${at}.seconds`, "seconds must be a positive whole number; omit it while the step is still running");
@@ -1242,6 +1251,12 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
                 into.require(typeof event.html === "string", "event.announcement.html", `${at}.html`, "html must be a string when present");
             }
             break;
+        case "diagnostic":
+            into.filled(event.expected, "event.diagnostic.expected", `${at}.expected`, "a diagnostic states the rule that was broken, as a sentence");
+            into.filled(event.observed, "event.diagnostic.observed", `${at}.observed`, "a diagnostic states what was observed instead");
+            if (event.taskId !== undefined)
+                into.require(isTaskId(event.taskId), "event.diagnostic.taskId", `${at}.taskId`, "taskId must be a task id when present");
+            break;
         case "queue-summary":
             validateQueueSummary(event.summary, `${at}.summary`, into);
             break;

package/guide.md

@@ -951,6 +951,7 @@ type ProviderEvent =
   | { type: "task-ended"; taskId: TaskId; outcome: TaskOutcome }
   | { type: "announcement"; text: string; html?: string; announcedAt: IsoTimestamp; expiresAt?: IsoTimestamp }
   | { type: "queue-summary"; summary: QueueSummary }
+  | { type: "diagnostic"; expected: string; observed: string; taskId?: TaskId }
   | { type: "team-updated"; team: TeamRoster }
   | { type: "contacts-updated"; contacts: Contact[] }
   | { type: "calendar-updated"; scheduledActivities: ScheduledActivity[] };
@@ -2259,6 +2260,8 @@ const immediateProviderCompletion = {
 handlingHistory: [
   { step: "queued",   at: "2026-08-21T00:59:00Z", seconds: 41 },
   { step: "answered", at: "2026-08-21T00:59:41Z", by: "a-17" },
+  { step: "held",     at: "2026-08-21T01:02:10Z", seconds: 35, by: "a-17" },
+  { step: "held",     at: "2026-08-21T01:06:48Z", by: "a-17" },
 ]
 ```
 
@@ -2272,6 +2275,16 @@ It rides in the snapshot and is replaced whole like everything else there.
 Steps are `queued`, `offered`, `answered`, `held`, `muted`, `transferred`, `conferenced`,
 `unanswered`, and each is defined on `TaskHandlingStep`.
 
+**The record is one entry per occurrence, oldest first.** Each hold is its own `held` entry — `at`
+when it began, `seconds` once it ended and omitted while it runs — and a second hold is a second
+entry after the first, never a revision of it. The same goes for every step: two mutes are two
+`muted` entries. Order is enforced: an entry earlier than the one before it is refused
+(`task.handlingHistory.order`). **Handle time is anchored, not restarted.** It runs from the
+`answered` step's `at` — from the task's first `in-progress` where the provider reports no
+history — until the task's media ends, and a hold neither pauses nor resets it: the hold's own
+duration is the `held` entry's `seconds`, and a desk that restarts its counter on resume is
+counting the wrong thing.
+
 `muted` is there because Omni performs the mute rather than the provider — see **Where a command
 executes** — so without a step the one participant that keeps the task's record would have no
 account of a period the agent could not be heard.
@@ -3466,7 +3479,8 @@ Omni apply state the snapshot already superseded.
 `transport-status` is the only signal Omni has that a transport died. An adapter must emit
 `transport-status` with `connecting` or `error` as soon as it loses its transport, rather than
 leaving a stale `active` in place while it retries internally; Omni cannot distinguish a quiet
-healthy provider from a dead one.
+healthy provider from a dead one. And what Omni is told, the agent is shown — see **The status is
+seen, not merely known** under `transport-status`.
 
 #### Requesting a resync
 
@@ -3523,6 +3537,12 @@ authentication state, not here.
 adapter that leaves a stale `active` in place is telling Omni to keep waiting for work that cannot
 come — see **Liveness**.
 
+**The status is seen, not merely known.** A host renders the transport's status where the agent
+works — `connecting` from the moment it is reported, `error` with what revives it — and never a
+healthy workspace over a transport that cannot serve it: an agent talking on a desk whose transport
+died was an incident, and it happened because the desk knew and did not say. The same obligation
+covers a `diagnostic`: shown where the agent works, and counted.
+
 ### `break-state`
 
 Replaces this provider's complete `break` object. Its `approval` uses the canonical
@@ -3606,6 +3626,26 @@ Publishes an agent-facing message. `text` is always required and is the accessib
 Optional HTML is sanitized by Omni. `announcedAt` and optional `expiresAt` are RFC-3339 times with
 explicit timezones.
 
+### `diagnostic`
+
+The provider's report that something its platform answered broke a rule the adapter relies on — a
+state read that contradicted itself, a `task-ended` naming a task nobody held, a party arriving
+without a name. `expected` is the rule as a sentence, `observed` is what came instead, and
+`taskId` names the task where there is one. **Informational, never behavioural**: the provider has
+already done the safe thing before it speaks, and nothing in the task or break machinery reacts to
+a diagnostic. It exists so that the loudness reaches a person — a host renders each one where the
+agent works and keeps a count an operator can read, because a healthy workspace over a shouting
+console is the silence problem one layer up. One event per occurrence; the host counts, the
+provider does not batch. `exerciseAdapter` treats a diagnostic delivered during a run as a
+violation (`diagnostic.raised`): a conformance run against a platform that is breaking its rules
+fails loudly rather than passing with a note.
+
+| Field | Contract |
+| --- | --- |
+| `expected` | Required. The rule that was broken, as a sentence a person can read. |
+| `observed` | Required. What the platform answered instead. |
+| `taskId` | Optional. The task concerned, where there is one. |
+
 ### `queue-summary`
 
 Publishes the provider's current dashboard contribution. Omni combines only the latest summary from

package/package.json

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