@xema/omni-protocol 0.1.75 → 0.1.77

package/dist/index.d.ts

@@ -904,11 +904,14 @@ export type TaskOutcome = {
 } | {
     type: "transferred";
     destinationId?: string;
-} | {
+}
+/** Who called the work off: the agent declining, the provider withdrawing or re-routing, the party abandoning. */
+ | {
     type: "cancelled";
+    by: "agent" | "provider" | "party";
     reason?: string;
 }
-/** Only the phases in which somebody is still being waited on can expire. */
+/** Only the phases in which somebody is still being waited on can expire; an offer that lapses at `allocationExpiresAt` names `pending`. */
  | {
     type: "expired";
     phase: "pending" | "confirmed" | "preview";

package/dist/testing.d.ts

@@ -170,6 +170,15 @@ export declare class TaskStream {
     /** What a restated record lost of the one read before it: nothing, or the entries by step and instant. */
     private static lost;
     private static stated;
+    /**
+     * Takes a resync snapshot -- a `snapshot` event, or the read a reloaded client makes -- as the
+     * state now, and first holds it to what the stream knew. A snapshot replaces state; it does not
+     * get to forget it. A task it carries that the stream already held may not go backwards, lose an
+     * entry of its record, return to undetermined terms, or be at work without the audio the stream
+     * held up: media ends on task-media-ended and the call moves on, so a task still in-progress or
+     * paused without its media is a snapshot that lost state, not a call that ended.
+     */
+    resync(snapshot: unknown, at: string): ProtocolViolation[];
     /** Replaces what is known with a snapshot's tasks, as a snapshot replaces Omni's state. */
     seed(snapshot: unknown): void;
     /** Applies one envelope and returns what it may not say given what came before. */

package/dist/testing.js

@@ -1043,7 +1043,52 @@ export class TaskStream {
                     stages.set(entry.dialId, entry.stage);
             }
         }
-        return { phase: String(isRecord(task) ? task.phase : undefined), media, source: String(isRecord(task) ? task.capabilitySource : undefined), stages, record: TaskStream.record(task), allocation: String(isRecord(task) ? task.allocationId : undefined) };
+        return { channel: String(isRecord(task) ? task.channel : undefined), completionMode: String(isRecord(task) ? task.completionMode : undefined),
+            wrapAllowance: isRecord(task) && typeof task.wrapAllowance === "number" ? task.wrapAllowance : undefined,
+            phase: String(isRecord(task) ? task.phase : undefined), media, source: String(isRecord(task) ? task.capabilitySource : undefined), stages, record: TaskStream.record(task), allocation: String(isRecord(task) ? task.allocationId : undefined) };
+    }
+    /**
+     * Takes a resync snapshot -- a `snapshot` event, or the read a reloaded client makes -- as the
+     * state now, and first holds it to what the stream knew. A snapshot replaces state; it does not
+     * get to forget it. A task it carries that the stream already held may not go backwards, lose an
+     * entry of its record, return to undetermined terms, or be at work without the audio the stream
+     * held up: media ends on task-media-ended and the call moves on, so a task still in-progress or
+     * paused without its media is a snapshot that lost state, not a call that ended.
+     */
+    resync(snapshot, at) {
+        const found = [];
+        const refuse = (rule, where, message) => found.push({ rule, path: where, message });
+        ruleEvaluated("stream.snapshot.capabilitySource", "stream.snapshot.handlingHistory", "stream.snapshot.phase", "stream.snapshot.media");
+        if (isRecord(snapshot) && Array.isArray(snapshot.tasks)) {
+            snapshot.tasks.forEach((task, index) => {
+                if (!isRecord(task) || typeof task.id !== "string")
+                    return;
+                const was = this.tasks.get(task.id);
+                if (was === undefined || was.allocation !== String(task.allocationId))
+                    return;
+                if ((was.source === "queue" || was.source === "ungoverned") && task.capabilitySource === "undetermined") {
+                    refuse("stream.snapshot.capabilitySource", `${at}.tasks[${index}].capabilitySource`, `${task.id} was published under ${was.source} terms and the snapshot says undetermined: terms once read stay read`);
+                }
+                // A record once read is not unread: a resync restates it whole, or with more, never with less.
+                const lost = TaskStream.lost(was.record, TaskStream.record(task));
+                if (lost.length > 0) {
+                    refuse("stream.snapshot.handlingHistory", `${at}.tasks[${index}].handlingHistory`, `${task.id}'s record lost ${lost.join(", ")} on the snapshot: an entry read by the host stays in the record until the task ends`);
+                }
+                const to = String(task.phase);
+                const reachable = REACHABLE_PHASES[was.phase];
+                if (reachable !== undefined && TASK_PHASES_ORDERED.includes(to) && !reachable.has(to)) {
+                    const connectingBack = was.phase === "completing" && TaskStream.partyDialled(task) && (to === "in-progress" || to === "paused");
+                    if (!connectingBack) {
+                        refuse("stream.snapshot.phase", `${at}.tasks[${index}].phase`, `${task.id} was ${was.phase} and the snapshot says ${to}: a task does not go backwards, on an update or on a resync`);
+                    }
+                }
+                if (was.media === "started" && (to === "in-progress" || to === "paused") && task.media !== "started") {
+                    refuse("stream.snapshot.media", `${at}.tasks[${index}].media`, `${task.id}'s audio was up and the snapshot carries it ${to} without it: media ends on task-media-ended and the call moves on, so a snapshot that forgets the audio lost state`);
+                }
+            });
+        }
+        this.seed(snapshot);
+        return found;
     }
     /** Replaces what is known with a snapshot's tasks, as a snapshot replaces Omni's state. */
     seed(snapshot) {
@@ -1071,24 +1116,7 @@ export class TaskStream {
         const known = id === undefined ? undefined : this.tasks.get(id);
         switch (event.type) {
             case "snapshot":
-                ruleEvaluated("stream.snapshot.capabilitySource", "stream.snapshot.handlingHistory");
-                // A snapshot replaces what is known, and still may not say a task lost terms it had read.
-                if (isRecord(event.snapshot) && Array.isArray(event.snapshot.tasks)) {
-                    event.snapshot.tasks.forEach((task, index) => {
-                        if (!isRecord(task) || typeof task.id !== "string")
-                            return;
-                        const was = this.tasks.get(task.id);
-                        if (was !== undefined && (was.source === "queue" || was.source === "ungoverned") && task.capabilitySource === "undetermined") {
-                            refuse("stream.snapshot.capabilitySource", `${at}.snapshot.tasks[${index}].capabilitySource`, `${task.id} was published under ${was.source} terms and the snapshot says undetermined: terms once read stay read`);
-                        }
-                        // A record once read is not unread: a resync restates it whole, or with more, never with less.
-                        const lost = TaskStream.lost(was?.record, TaskStream.record(task));
-                        if (lost.length > 0) {
-                            refuse("stream.snapshot.handlingHistory", `${at}.snapshot.tasks[${index}].handlingHistory`, `${task.id}'s record lost ${lost.join(", ")} on the snapshot: an entry read by the host stays in the record until the task ends`);
-                        }
-                    });
-                }
-                this.seed(event.snapshot);
+                found.push(...this.resync(event.snapshot, `${at}.snapshot`));
                 break;
             case "task-offered": {
                 ruleEvaluated("stream.taskOffered.duplicate", "stream.taskOffered.allocation");
@@ -1231,6 +1259,15 @@ export class TaskStream {
                 // A late ending for a life that is over must not end the life that is open under the same id.
                 if (!this.namesTheOpenLife(event, known, at, refuse))
                     break;
+                // Off voice there is no media event, so the update that moves a task to completing is the
+                // provider's word that handling ended and the moment the wrap allowance starts. A provider
+                // that completes the task itself with an allowance to run has to have started the clock:
+                // completed from in-progress, the allowance it stated was never given.
+                ruleEvaluated("stream.taskEnded.unwrapped");
+                if (known.channel !== "voice" && known.completionMode === "provider-automatic" && known.wrapAllowance !== undefined && known.wrapAllowance > 0
+                    && known.phase !== "completing" && isRecord(event.outcome) && event.outcome.type === "completed") {
+                    refuse("stream.taskEnded.unwrapped", `${at}.outcome`, `${id} was completed from ${known.phase} with a wrap allowance of ${known.wrapAllowance}s under provider-automatic: off voice, completing is the provider's word that handling ended and the allowance's start, and it was never published`);
+                }
                 this.endedAllocations.add(known.allocation);
                 this.tasks.delete(id);
                 break;
@@ -1335,9 +1372,11 @@ async function driveOneCall(drive) {
             drive.handOver.up(session, second);
             drive.connection = second;
             const snapshot = await second.snapshot();
-            // The second adapter's snapshot is held to everything a first one is, and the streams take it as the state now.
+            // The second adapter's snapshot is held to everything a first one is, and the streams take it
+            // as the state now the way they take any resync: held to what they knew, then replaced. A reload
+            // is a place the stream's rules keep working, not one where they all stop.
             found.push(...validateSnapshot(snapshot, again.manifest, "drive.reload.snapshot", drive.reader()));
-            drive.streams.stream.seed(snapshot);
+            found.push(...drive.streams.stream.resync(snapshot, "drive.reload.snapshot"));
             drive.streams.breaks.seed(snapshot);
             const carried = isRecord(snapshot) && Array.isArray(snapshot.tasks)
                 ? snapshot.tasks.find(task => isRecord(task) && task.id === taskId) : undefined;

package/dist/validation.js

@@ -89,6 +89,7 @@ const PHONES = membersOf({ softphone: true, deskPhone: true });
 const TEAM_CAPABILITIES = membersOf({ breakControl: true, leadAssistControl: true, policyControl: true, monitorControl: true });
 const MONITOR_MODES = membersOf({ monitor: true, whisper: true, barge: true });
 const COMPLETED_BY = membersOf({ agent: true, provider: true });
+const CANCELLED_BY = membersOf({ agent: true, provider: true, party: true });
 const EXPIRABLE_PHASES = membersOf({
     pending: true, confirmed: true, preview: true,
 });
@@ -994,6 +995,12 @@ function validateMonitoring(value, channel, path, into) {
     into.oneOf(value.mode, MONITOR_MODES, "task.monitoring.mode", `${path}.mode`);
     into.timestamp(value.since, "task.monitoring.since", `${path}.since`);
 }
+/** Whether a task is the agent's own doing: a dial the host placed on its onCall, a lead's join, a lead's monitor. */
+function originatedByTheAgent(task) {
+    if (Array.isArray(task.onCall) && task.onCall.some(entry => isPlainObject(entry) && typeof entry.dialId === "string"))
+        return true;
+    return task.assisting !== undefined || task.monitoring !== undefined;
+}
 export function validateTask(task, context, path = "task") {
     const into = new Collector();
     validateTaskInto(task, context, path, into);
@@ -1032,15 +1039,27 @@ function validateTaskInto(task, context, path, into) {
     }
     // 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.
+    // Work the agent originated -- a dial or connect-back, carrying the host's dialId on onCall; a
+    // lead's join, carrying assisting; a monitor, carrying monitoring -- was accepted by the command
+    // that created it, and says so whatever the provisioning: the desk shows no Accept for a call
+    // the agent placed. The provisioning governs work the queue routes, and nothing else.
+    const originated = task.phase === "pending" && originatedByTheAgent(task);
+    ruleEvaluated("task.acceptance.originated");
     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 (originated) {
+            into.require(task.acceptance === "automatic", "task.acceptance.originated", `${path}.acceptance`, "work the agent originated -- a dial, a connect-back, a join, a monitor -- was accepted by the command that created it, and says automatic whatever the provisioning");
+        }
         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");
+            into.add("task.acceptance.unexpected", `${path}.acceptance`, "autoAcceptTasks is off, so every task the queue routes requires agent acceptance and a pending task carries no acceptance");
         }
     }
+    else if (originated) {
+        into.add("task.acceptance.originated", `${path}.acceptance`, "work the agent originated -- a dial, a connect-back, a join, a monitor -- says acceptance: automatic whatever the provisioning: the command that created it accepted it");
+    }
     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");
     }
@@ -1469,6 +1488,9 @@ function validateTaskOutcome(value, path, into) {
             }
             break;
         case "cancelled":
+            // One word covered the agent declining, the provider withdrawing and the party abandoning the
+            // ring; a record that cannot tell them apart is not a record. by says who, as completed does.
+            into.oneOf(value.by, CANCELLED_BY, "event.taskEnded.outcome.cancelled.by", `${path}.by`);
             if (value.reason !== undefined) {
                 into.filled(value.reason, "event.taskEnded.outcome.cancelled", `${path}.reason`, "a reason must not be empty when present");
             }

package/guide.md

@@ -702,7 +702,7 @@ type AcceptanceMode =
 type TaskOutcome =
   | { type: "completed"; by: "agent" | "provider" }
   | { type: "transferred"; destinationId?: string }
-  | { type: "cancelled"; reason?: string }
+  | { type: "cancelled"; by: "agent" | "provider" | "party"; reason?: string }
   | { type: "expired"; phase: "pending" | "confirmed" | "preview" }
   | { type: "left" }
   | { type: "failed"; failure: ProtocolFailure };
@@ -2170,8 +2170,8 @@ person's behalf for want of a word:
 | `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 `acceptance` and every task
-requires agent acceptance. The two are never confused on the wire: `consent` is always the
+When Omni sent `autoAcceptTasks: false`, the provider omits `acceptance` and every task the
+queue routes 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**
 press is Omni's doing, not the provider's.
@@ -2185,8 +2185,13 @@ belongs, whatever the host was configured with.
 
 An automatically accepted task still arrives through `task-offered`.
 
-Agent-initiated work arrives through `task-offered` with the task's
-`acceptance: "automatic"`.
+**Work the agent originated is accepted by the command that created it.** A task born of the
+agent's own act — a dialpad call or a connect-back, recognisable by the host's `dialId` on
+`onCall`; a lead's join, carrying `assisting`; a lead's monitor, carrying `monitoring` — arrives
+through `task-offered` with `acceptance: "automatic"` whatever `autoAcceptTasks` says, and the
+validator holds it there under either provisioning and under none (`task.acceptance.originated`):
+the desk shows no **Accept** for a call the agent placed. The provisioning governs work the queue
+routes to the agent, and nothing else.
 
 ### Pending
 
@@ -2220,14 +2225,20 @@ on a desk phone — and is not in question per call. See **How the agent hears t
 Automatic acceptance still begins with `task-offered`.
 
 `allocationExpiresAt` is the deadline after which the offer lapses. Where present, Omni counts
-down and stops offering **Accept** once it passes. **Omit it unless the provider can observe it.**
+down and stops offering **Accept** once it passes; the provider ends the lapsed offer with
+`task-ended` and an `expired` outcome naming `pending`, since nobody cancelled it. **Omit it unless the provider can observe it.**
 A provider that reports only elapsed ring time after the fact cannot say when an offer is due
 to end, and a computed value would have Omni withdraw **Accept** from a task still pending.
 
 A preview's deadline is not on the offer. It travels on the task, as `previewEndsAt` with
 `atDeadline`, so a snapshot carries it too -- see **Preview: the agent presses Call**.
 
-A provider may withdraw a pending task by emitting `task-ended` with a `cancelled` outcome.
+A provider may withdraw a pending task by emitting `task-ended` with a `cancelled` outcome, `by:
+"provider"`. **`cancelled` says who called the work off**, as `completed` says who completed it:
+`agent` for a decline, `provider` for a withdrawal or a re-route, `party` for a caller who abandoned
+the ring. One word for the three left a supervisor's record unable to tell them apart, so `by` is
+required and closed (`event.taskEnded.outcome.cancelled.by`). An offer nobody acted on before
+`allocationExpiresAt` is not cancelled by anyone: it lapses, and ends `expired` naming `pending`.
 
 ### Tasks already in progress
 
@@ -2309,7 +2320,8 @@ The canonical task transitions are:
 | `preview` | Agent presses Call (`call`) and the customer answers, or the deadline `calls` and they answer | `in-progress` |
 | `preview` | The call goes out and nobody answers | `completing` |
 | `preview` | The deadline `expires` | Removed by `task-ended` with `expired` outcome |
-| `pending` | Provider withdraws the allocation | Removed by `task-ended` with `cancelled` outcome |
+| `pending` | Provider withdraws the allocation, the agent declines, or the party abandons the ring | Removed by `task-ended` with `cancelled` outcome, `by` saying which |
+| `pending` | The offer lapses at `allocationExpiresAt` | Removed by `task-ended` with `expired` outcome naming `pending` |
 | No task | Snapshot reports work already underway | `in-progress` |
 | `in-progress` | Provider or agent pauses the task | `paused` |
 | `in-progress` | Agent starts a warm transfer (`transfer` `warm`); the customer is parked | `paused` |
@@ -2420,9 +2432,18 @@ whether the channel carries real-time media:
 | Channel | Wrap allowance starts at |
 | --- | --- |
 | Voice and any channel with real-time media | The `task-media-ended` event |
-| Chat | When the conversation ends and the task enters `completing` |
-| Email | After the message is sent and the task enters `completing` |
-| Other non-media channels | The moment the task enters `completing` |
+| Chat | The `task-updated` that moves the task to `completing`: the provider's word that the conversation is closed on its side, the allowance running from that publication's `occurredAt` |
+| Email | The `task-updated` that moves the task to `completing`: the provider's word that the platform has accepted the outgoing message, the allowance running from that publication's `occurredAt` |
+| Other non-media channels | The `task-updated` that moves the task to `completing` |
+
+**Off voice, `completing` is the provider's word that handling ended.** There is no media event to
+carry it, so the phase does; a host starts the wrap clock at that publication and nowhere else. It
+is optional: a conversation with nothing to wrap moves from `in-progress` to `task-ended` and
+`completing` is never published. Under `provider-automatic` with a non-zero `wrapAllowance` it is
+required, because the clock has to start somewhere: a chat or email task the provider completes
+from `in-progress` with an allowance to run gave the agent none of it, and the stream refuses the
+ending (`stream.taskEnded.unwrapped`). Under `agent-command` the agent's `complete` is the end,
+from `in-progress` or from `completing` alike.
 
 ```ts
 const emailCompletion = {
@@ -2867,7 +2888,10 @@ last statement stands and the failure is a `diagnostic`, and a task that was pub
 `queue` or `ungoverned` never returns to `undetermined`, on an update (`stream.taskUpdated.capabilitySource`)
 or on a resync snapshot (`stream.snapshot.capabilitySource`); a record once read never loses an
 entry the same two ways (`stream.taskUpdated.handlingHistory`, `stream.snapshot.handlingHistory`);
-and a task does not go backwards (`stream.taskUpdated.phase`): the stream sees publications, not
+a snapshot carrying a task still at work does not forget the audio the stream held up, since media
+ends on `task-media-ended` and the call moves on (`stream.snapshot.media`); and a task does not go
+backwards, on an update or on a resync (`stream.taskUpdated.phase`, `stream.snapshot.phase`): the
+stream sees publications, not
 transitions, and a task may pass through a phase between two, so `pending` to `in-progress` stands
 with `confirmed` between them, and what is refused is a phase unreachable from the last one read by
 the transition table -- back to `pending`, back to `confirmed` or `preview` once work began, out of
@@ -4268,8 +4292,8 @@ beside the mapped one is what the full check costs a host; an adapter has it for
 validator holds a command only to a task that stands: a task handed in that is not one the wire
 published is named (`command.task`) rather than checked against.
 
-Declining or rejecting a pending offer ends it without accepting or completing it. The provider
-confirms the end with `task-ended` and a `cancelled` outcome.
+Declining a pending offer ends it without accepting or completing it. The provider confirms the
+end with `task-ended` and a `cancelled` outcome, `by: "agent"`.
 
 ### `execute(request)`
 
@@ -4760,7 +4784,11 @@ built and connected for the same login with the same context and the same `store
 must carry the task with that leg and the host's word, and the run goes on with the second as its
 connection to the end. A platform that holds the record hands it back, and an adapter that composed
 the record in memory has nothing and is named (`drive.reload.snapshot`, `drive.reload.history`,
-`.rejected`). The second adapter is held to what the first was: the same provider
+`.rejected`). The second adapter's snapshot is taken as any resync is: held to what the stream knew
+before it replaces it, so a phase gone backwards, a record that shrank or audio forgotten on a task
+still at work is named by the stream's own rules (`stream.snapshot.phase`, `.handlingHistory`,
+`.media`) and a reload is a place those rules keep working, not one where they stop. The second
+adapter is held to what the first was: the same provider
 (`drive.reload.manifest`), a snapshot that stands as any snapshot must, and a record that lost none
 of the entries the first had published -- a record once read is not unread across a reload either.
 A reconnect on the same adapter object would prove nothing, since an in-process adapter's memory

package/package.json

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