@xema/omni-protocol 0.1.75 → 0.1.76

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.js

@@ -1043,7 +1043,9 @@ 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) };
     }
     /** Replaces what is known with a snapshot's tasks, as a snapshot replaces Omni's state. */
     seed(snapshot) {
@@ -1231,6 +1233,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;

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 = {
@@ -4268,8 +4289,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)`
 

package/package.json

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