@xema/omni-protocol 0.1.28 → 0.1.30

package/README.md

@@ -15,6 +15,7 @@ system.
 | `src/index.ts` | The TypeScript declarations. |
 | `src/validation.ts` | Runtime validators Omni applies to adapter output. |
 | `src/testing.ts` | Conformance helpers an adapter runs against its own test state. |
+| `tests/` | One test file per source module, plus the guards over the guide and the repository's own text. |
 
 ## Entry points
 

package/dist/index.d.ts

@@ -607,6 +607,13 @@ export type Task<C extends Channel = Channel> = {
     /** The person or entity on the other end of this task. Who the task is with; `contacts` on the snapshot is the directory. */
     party?: Contact;
     phase: TaskPhase;
+    /**
+     * How this offer is accepted, stated on the pending task rather than the offer so a reconnect
+     * snapshot says it too: an offer the host never received is not accepted on the person's behalf
+     * for want of a word. Required while `pending` when Omni said it may auto-accept
+     * (`autoAcceptTasks: true`), forbidden when it said not, and absent past `pending`.
+     */
+    acceptance?: AcceptanceMode;
     /** The identifier an agent reads back to a customer, where the provider has one. */
     reference?: string;
     attributes?: TaskAttribute[];
@@ -1077,7 +1084,6 @@ export type ProviderEvent<C extends Channel = Channel> = {
 } | {
     type: "task-offered";
     task: Task<C>;
-    acceptanceMode?: AcceptanceMode;
     allocationExpiresAt?: IsoTimestamp;
     preparationEndsAt?: IsoTimestamp;
 } | {
@@ -1102,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.d.ts

@@ -7,7 +7,7 @@ export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation }
  * rules -- each optional part of a task, each optional part of the break state and roster, each
  * declared contribution, and each event type.
  */
-declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.handlingHistory", "task.consultation", "task.lead", "task.assisting", "task.media", "task.dispositions", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.imposed", "team.members", "team.requests", "contacts", "scheduledActivities", "team.policies"];
+declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.handlingHistory", "task.consultation", "task.lead", "task.assisting", "task.media", "task.acceptance", "task.dispositions", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.imposed", "team.members", "team.requests", "contacts", "scheduledActivities", "team.policies"];
 export type ContractSubject = (typeof STATE_SUBJECTS)[number] | `event.${ProviderEvent["type"]}`;
 export interface AdapterContractResult {
     events: ProviderEventEnvelope[];

package/dist/testing.js

@@ -16,6 +16,7 @@ const STATE_SUBJECTS = [
     "task.lead",
     "task.assisting",
     "task.media",
+    "task.acceptance",
     "task.dispositions",
     "task.destinations",
     "task.custom",
@@ -32,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 = [
@@ -61,6 +62,8 @@ function observeTask(value, seen) {
         seen.add("task.assisting");
     if (value.media !== undefined)
         seen.add("task.media");
+    if (value.acceptance !== undefined)
+        seen.add("task.acceptance");
     const capabilities = isRecord(value.capabilities) ? value.capabilities : {};
     if (isRecord(capabilities.dispositions))
         seen.add("task.dispositions");
@@ -278,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.d.ts

@@ -15,6 +15,8 @@ export interface TaskValidationContext {
     channel: string;
     /** The level ids in force, from the manifest. The defaults when absent. */
     levels?: readonly string[];
+    /** `ConnectContext.autoAcceptTasks` as sent, absent meaning `true`: whether a pending task states its `acceptance`. */
+    autoAcceptTasks?: boolean;
 }
 export declare function validateTask(task: unknown, context: TaskValidationContext, path?: string): ProtocolViolation[];
 /**
@@ -36,7 +38,7 @@ export interface ReaderContext {
     levels?: readonly string[];
     /** The login's `loginId`. A snapshot or event naming another belongs to a login that is gone. */
     loginId?: string;
-    /** `ConnectContext.autoAcceptTasks` as sent, absent meaning `true`: whether `task-offered` carries an `acceptanceMode`. */
+    /** `ConnectContext.autoAcceptTasks` as sent, absent meaning `true`: whether a pending task states its `acceptance`. */
     autoAcceptTasks?: boolean;
 }
 export declare function validateTeamRoster(roster: unknown, path?: string, context?: ReaderContext): ProtocolViolation[];

package/dist/validation.js

@@ -729,6 +729,20 @@ function validateTaskInto(task, context, path, into) {
     into.filled(task.title, "task.title", `${path}.title`, "a task needs a title");
     into.filled(task.taskType, "task.taskType", `${path}.taskType`, "a task needs a task type");
     into.oneOf(task.phase, TASK_PHASES, "task.phase", `${path}.phase`);
+    // Acceptance is the offer's word, carried on the pending task so a snapshot can say it: it
+    // travels exactly when Omni said tasks may be auto-accepted, and only while the task is pending.
+    if (task.acceptance !== undefined) {
+        into.oneOf(task.acceptance, ACCEPTANCE_MODES, "task.acceptance", `${path}.acceptance`);
+        if (task.phase !== "pending") {
+            into.add("task.acceptance.unexpected", `${path}.acceptance`, "acceptance is an offer's word; a task past pending has been accepted");
+        }
+        else if (context.autoAcceptTasks === false) {
+            into.add("task.acceptance.unexpected", `${path}.acceptance`, "autoAcceptTasks is off, so every task requires agent acceptance and a pending task carries no acceptance");
+        }
+    }
+    else if (task.phase === "pending" && context.autoAcceptTasks === true) {
+        into.add("task.acceptance.required", `${path}.acceptance`, "autoAcceptTasks is on, so a pending task states how it is accepted");
+    }
     into.oneOf(task.completionMode, COMPLETION_MODES, "task.completionMode", `${path}.completionMode`);
     // The allowance is coupled to the mode: a provider that will complete the task itself is going
     // to act on the allowance, so it must state one; a provider waiting for `complete` may omit it
@@ -1009,7 +1023,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
         const seen = new Set();
         let assisting;
         snapshot.tasks.forEach((task, index) => {
-            validateTaskInto(task, { channel, levels }, `${path}.tasks[${index}]`, into);
+            validateTaskInto(task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks }, `${path}.tasks[${index}]`, into);
             // A lead assists one call at a time.
             if (isPlainObject(task) && task.assisting !== undefined) {
                 if (assisting !== undefined)
@@ -1196,28 +1210,18 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             validateBreakState(event.break, `${at}.break`, into);
             break;
         case "task-offered":
-            validateTaskInto(event.task, { channel, levels }, `${at}.task`, into);
+            validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks }, `${at}.task`, into);
             // An offer introduces work that is not yet under way; work in progress arrives only on a snapshot.
             if (isPlainObject(event.task) && typeof event.task.phase === "string") {
                 into.require(OFFERABLE_PHASES.includes(event.task.phase), "event.taskOffered.phase", `${at}.task.phase`, `task-offered introduces a task as ${OFFERABLE_PHASES.join(", ")}, never as ${event.task.phase}`);
             }
-            if (event.acceptanceMode !== undefined) {
-                into.oneOf(event.acceptanceMode, ACCEPTANCE_MODES, "event.taskOffered.acceptanceMode", `${at}.acceptanceMode`);
-            }
-            // The mode travels exactly when Omni said tasks may be auto-accepted.
-            if (context.autoAcceptTasks === true) {
-                into.require(event.acceptanceMode !== undefined, "event.taskOffered.acceptanceMode.required", `${at}.acceptanceMode`, "autoAcceptTasks is on, so task-offered carries an acceptanceMode");
-            }
-            else if (context.autoAcceptTasks === false) {
-                into.require(event.acceptanceMode === undefined, "event.taskOffered.acceptanceMode.unexpected", `${at}.acceptanceMode`, "autoAcceptTasks is off, so every task requires agent acceptance and task-offered carries no acceptanceMode");
-            }
             for (const field of ["allocationExpiresAt", "preparationEndsAt"]) {
                 if (event[field] !== undefined)
                     into.timestamp(event[field], `event.taskOffered.${field}`, `${at}.${field}`);
             }
             break;
         case "task-updated":
-            validateTaskInto(event.task, { channel, levels }, `${at}.task`, into);
+            validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks }, `${at}.task`, into);
             break;
         case "task-media-started":
             into.require(isTaskId(event.taskId), "event.taskMediaStarted.taskId", `${at}.taskId`, "a task id is required");
@@ -1238,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

@@ -604,6 +604,7 @@ type Task<C extends Channel = Channel> = {
   browsers: TaskBrowser[];
   party?: Contact;
   phase: TaskPhase;
+  acceptance?: AcceptanceMode;
   reference?: string;
   attributes?: TaskAttribute[];
   handlingHistory?: TaskHandlingStep[];
@@ -941,7 +942,6 @@ type ProviderEvent =
   | {
       type: "task-offered";
       task: Task;
-      acceptanceMode?: AcceptanceMode;
       allocationExpiresAt?: IsoTimestamp;
       preparationEndsAt?: IsoTimestamp;
     }
@@ -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[] };
@@ -1830,7 +1831,7 @@ Creates one live provider connection for the signed-in agent.
 | --- | --- |
 | `protocolVersion` | Version negotiated before authentication. Fixed for this login. |
 | `loginId` | Omni-generated identity for this login. It is the same value passed as `AuthenticationContext.loginId`, so an adapter can correlate this connection with the session that authenticated it. Stable across transport reconnects and changed only by a new login. |
-| `autoAcceptTasks` | Agent provisioning policy relayed to the provider at login. Treated as `true` when omitted. When `true`, `task-offered` carries an `acceptanceMode`; when `false`, every task requires agent acceptance. |
+| `autoAcceptTasks` | Agent provisioning policy relayed to the provider at login. Treated as `true` when omitted. When `true`, a pending task states its `acceptance`; when `false`, every task requires agent acceptance. Fixed for this connection, like everything else here: the provider states or omits `acceptance` by the value it was sent, and Omni validates by that same value, not by a policy that has since moved — a change reaches the provider through a fresh `connect()`. |
 | `host` | The host'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 host reports, the adapter decides**. |
 | `signal` | Optional cancellation signal. Stop startup promptly when aborted and do not begin new work. |
 | `log` | Optional structured logging callback. Never include credentials, tokens, or sensitive contact data. |
@@ -1974,13 +1975,15 @@ deliver again once it has gone quiet. Hold the capacity and deliver when work ar
 **4. A provider offers a task.** The provider emits `task-offered` within the stated capacity.
 
 **5. Omni decides how the task is accepted.** When `autoAcceptTasks` is `false`, every task requires
-agent acceptance. When it is `true`, the event's `acceptanceMode` states the provider's
+agent acceptance. When it is `true`, the pending task's `acceptance` states the provider's
 intent.
 
 ### Acceptance modes
 
 During login, Omni sends the agent's `autoAcceptTasks` value to the provider. When it is `true`, the
-provider includes an acceptance directive with each allocation:
+provider states `acceptance` on each pending task — on the task rather than the offer, so a
+reconnect snapshot says it too and an offer the host never received is not accepted on the
+person's behalf for want of a word:
 
 | Directive | Contract |
 | --- | --- |
@@ -1988,7 +1991,7 @@ provider includes an acceptance directive with each allocation:
 | `consent` | The provider requires the person's explicit consent: Omni presents **Accept** and waits, whatever its own policy would have done. A host that declares `guarantees.personConsent` promises exactly this; a provider checks it before offering work only a person may take. |
 | `automatic` | Omni accepts immediately without agent interaction. |
 
-When Omni sent `autoAcceptTasks: false`, the provider omits `acceptanceMode` and every task
+When Omni sent `autoAcceptTasks: false`, the provider omits `acceptance` and every task
 requires agent acceptance. The two are never confused on the wire: `consent` is always the
 provider's requirement, stated on a wire where Omni was willing to accept for the agent; Omni's own
 no-auto-accept policy puts no word on the wire at all — the field is absent, and the **Accept**
@@ -1998,19 +2001,19 @@ press is Omni's doing, not the provider's.
 gone ready is telling the deployment they are working. Requiring a press before every contact is
 the exception a provisioning file asks for, not the state it falls into when a flag is missing.
 
-Nothing is given away by that default. `acceptanceMode` is the provider's own control and outranks
+Nothing is given away by that default. `acceptance` is the provider's own control and outranks
 it: `consent` puts the decision back in the agent's hands for any task where it
 belongs, whatever the host was configured with.
 
 An automatically accepted task still arrives through `task-offered`.
 
-Agent-initiated work arrives through `task-offered` with
-`acceptanceMode: "automatic"`.
+Agent-initiated work arrives through `task-offered` with the task's
+`acceptance: "automatic"`.
 
 ### Pending
 
 A task in the `pending` phase has been **offered to the agent and not yet accepted**. Omni applies
-`autoAcceptTasks` and the allocation's `acceptanceMode` to decide whether acceptance is
+`autoAcceptTasks` and the task's `acceptance` to decide whether acceptance is
 automatic or requires the agent. A provider that requires automatic acceptance still emits
 `task-offered`; it does not introduce new work as `in-progress`.
 
@@ -2019,8 +2022,7 @@ declare const task: Task;
 
 const allocation = {
   type: "task-offered",
-  task,
-  acceptanceMode: "consent",
+  task: { ...task, phase: "pending", acceptance: "consent" },
   allocationExpiresAt: "2026-08-25T10:41:07.000Z",
   preparationEndsAt: "2026-08-25T10:40:37.000Z",
 } satisfies Extract<ProviderEvent, { type: "task-offered" }>;
@@ -2083,6 +2085,7 @@ time. Runtime conformance checks also require the task channel to match its prov
 | `party` | The person or entity on the other end of this task, as a `Contact`: often a name and one address; a withheld caller ID may leave nothing to send at all. Optional. The party is who the task is *with*; `contacts` is the directory. |
 | `phase` | Current canonical task phase: `pending`, `confirmed`, `preparing`, `in-progress`, `paused`, or `completing`. |
 | `media` | Voice only. The task's real-time audio as the provider holds it: `started` while audio is attached, `ended` once it ended, omitted while none is. The provider's word — see **`task-media-started`**. |
+| `acceptance` | How this offer is accepted — `no-preference`, `consent`, or `automatic` — stated on the pending task so a reconnect snapshot says it too. Required while `pending` when `autoAcceptTasks` was `true`, forbidden when it was `false`, and absent past `pending`. See **Acceptance modes**. |
 | `reference` | Optional agent-facing reference such as a case, call, conversation, ticket, or message number. It is distinct from the protocol `id`. |
 | `completionMode` | `agent-command` waits for the channel's `complete` command; `provider-automatic` completes without one. |
 | `wrapAllowance` | Fixed time allowed to complete the task after primary handling ends. For real-time media, it begins after `task-media-ended`. Required under `provider-automatic`, where the provider acts on it. Optional under `agent-command`: omitted says the provider imposes no deadline, and Omni counts nothing down. |
@@ -2134,12 +2137,12 @@ The canonical task transitions are:
 | Any phase | Provider emits `task-ended` | Removed |
 
 Allocation, acceptance, and progress are distinct. Acceptance follows `autoAcceptTasks` and the
-allocation's `acceptanceMode`, moving the task from `pending` to `confirmed`. The provider reports
+task's `acceptance`, moving the task from `pending` to `confirmed`. The provider reports
 subsequent transitions to `preparing` or `in-progress`; Omni does not infer them from the acceptance
 command.
 
 **A task is never its audio.** A voice task is the allocation: the call is offered when it is
-routed to the agent and accepted as `acceptanceMode` dictates, and its presence and phase follow
+routed to the agent and accepted as its `acceptance` dictates, and its presence and phase follow
 the provider's reports about the work — never the audio. Wherever audio moves — an offer, a hold, a
 consult, a conference leg joining or leaving, a transfer, a callback — the media follows
 separately, arriving on `task-media-started`, attaching through `openMedia` and ending with
@@ -3464,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
 
@@ -3521,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
@@ -3548,8 +3558,8 @@ multi-provider break**.
 ### `task-offered`
 
 Offers a task to Omni without a separate offer acknowledgement. An offer does not accept
-the task: when its phase is `pending`, Omni applies `autoAcceptTasks` and the event's
-`acceptanceMode`. `task-offered` must not introduce a task as `in-progress`; only a reconnect or
+the task: when its phase is `pending`, Omni applies `autoAcceptTasks` and the task's
+`acceptance`. `task-offered` must not introduce a task as `in-progress`; only a reconnect or
 resync snapshot may report work already in progress. The provider should include the task in later
 snapshots until it ends.
 
@@ -3604,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.28",
+  "version": "0.1.30",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,7 @@
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "pnpm run clean && tsc -p tsconfig.json",
-    "test": "tsc -p tsconfig.type-tests.json && vitest run"
+    "test": "tsc -p tsconfig.test.json && vitest run"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",