@xema/omni-protocol 0.1.28 → 0.1.29

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;
 } | {

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",
@@ -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");

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");

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;
     }
@@ -1830,7 +1830,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 +1974,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 +1990,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 +2000,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 +2021,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 +2084,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 +2136,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
@@ -3548,8 +3550,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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xema/omni-protocol",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "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",