@xema/omni-protocol 0.1.29 → 0.1.30

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

@@ -1242,6 +1242,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[] };
@@ -3466,7 +3467,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 +3525,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 +3614,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.30",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",