@xema/omni-protocol 0.1.71 → 0.1.73

package/dist/index.d.ts

@@ -174,6 +174,13 @@ export interface Manifest<C extends Channel = Channel> {
      * when it ended, and a running report is refused: what a provider never asked for never crosses.
      */
     runningStepReports?: true;
+    /**
+     * How long after an applied disposal -- `complete`, `transfer` `complete`, `lead-assist`
+     * `take-over` -- the provider's `task-ended` is owed, in milliseconds. `applied` says the provider
+     * has disposed of the task; the ending follows within this, or the host resyncs and shows the
+     * task as unsettled. Stated per provider, since platforms settle at different speeds.
+     */
+    disposalSettleMs: number;
 }
 export interface SecretStore {
     get(key: string): Promise<string | undefined>;

package/dist/testing.js

@@ -1055,7 +1055,7 @@ export class TaskStream {
             case "task-updated":
                 if (id === undefined)
                     break;
-                ruleEvaluated("stream.taskUpdated.unknown", "stream.taskUpdated.capabilitySource", "stream.taskUpdated.phase", "stream.taskUpdated.allocation", "stream.taskUpdated.handlingHistory", "stream.taskMediaEnded.follow", "stream.taskUpdated.media", "stream.taskUpdated.stage");
+                ruleEvaluated("stream.taskUpdated.unknown", "stream.taskUpdated.capabilitySource", "stream.taskUpdated.phase", "stream.taskUpdated.allocation", "stream.taskUpdated.mediaOpen", "stream.taskUpdated.handlingHistory", "stream.taskMediaEnded.follow", "stream.taskUpdated.media", "stream.taskUpdated.stage");
                 if (known === undefined) {
                     refuse("stream.taskUpdated.unknown", `${at}.task.id`, `${id} was never offered or carried on a snapshot`);
                     break;
@@ -1094,6 +1094,15 @@ export class TaskStream {
                         refuse("stream.taskUpdated.handlingHistory", `${at}.task.handlingHistory`, `${id}'s record lost ${lost.join(", ")} on the update: an entry read by the host stays in the record until the task ends`);
                     }
                 }
+                // A task completes after its media ends, never around it: an update that moves a task to
+                // completing while the stream holds its audio as started is a call whose audio never ended,
+                // whoever caused the ending -- the drive's end-call, a transfer, the provider's own hand.
+                {
+                    const to = isRecord(event.task) ? String(event.task.phase) : "";
+                    if (to === "completing" && known.media === "started" && known.phase !== "completing") {
+                        refuse("stream.taskUpdated.mediaOpen", `${at}.task.phase`, `${id} moves to completing with its media still started: the audio ends first, on task-media-ended, and a wrap-up with the call still up is audio that never ended`);
+                    }
+                }
                 if (known.media === "ended") {
                     const phase = isRecord(event.task) ? String(event.task.phase) : "";
                     if (phase !== "completing") {
@@ -1208,7 +1217,7 @@ async function driveOneCall(drive) {
     const refuse = (rule, path, message) => found.push({ rule, path, message });
     const isTask = (value) => isRecord(value) && typeof value.id === "string";
     // Wait for an envelope that satisfies `matches`, looking first at what already arrived.
-    const waitFor = (what, matches, from) => new Promise(resolve => {
+    const waitFor = (what, matches, from, within = { ms: drive.timeoutMs, onExpiry: () => refuse("drive.timeout", "drive", `the provider owed ${what} within ${drive.timeoutMs}ms and it never arrived`) }) => new Promise(resolve => {
         for (let index = from; index < drive.events.length; index += 1) {
             const hit = matches(drive.events[index]);
             if (hit !== undefined) {
@@ -1218,9 +1227,9 @@ async function driveOneCall(drive) {
         }
         const timer = setTimeout(() => {
             drive.waiters.delete(waiter);
-            refuse("drive.timeout", "drive", `the provider owed ${what} within ${drive.timeoutMs}ms and it never arrived`);
+            within.onExpiry();
             resolve(undefined);
-        }, drive.timeoutMs);
+        }, within.ms);
         const waiter = (envelope) => {
             const hit = matches(envelope);
             if (hit === undefined)
@@ -1359,10 +1368,10 @@ async function driveOneCall(drive) {
         return undefined;
     }, cursor).then(hit => { if (hit)
         cursor = hit.at; return hit; });
-    const ended = () => waitFor("a task-ended for the driven task", envelope => {
+    const ended = (within) => waitFor("a task-ended for the driven task", envelope => {
         const event = envelope.event;
         return event.type === "task-ended" && event.taskId === taskId ? event : undefined;
-    }, cursor);
+    }, cursor, within);
     // Every command the drive sends is validated against the task as published, and its answer for its method.
     ruleEvaluated("drive.timeout");
     const send = async (command, dialId) => {
@@ -1519,11 +1528,18 @@ async function driveOneCall(drive) {
     // 5. End the call, where the agent may.
     if (drive.channel === "voice" && latestTask().phase === "in-progress" && offers("endCall")) {
         if (await send({ type: "end-call" }) !== undefined) {
+            // A task that completes with its audio still up is refused by the stream as it passes
+            // (stream.taskUpdated.mediaOpen); the drive does not also wait out the clock for an ending
+            // that is not coming, so the run reads by the rule and not by its timeout.
             const mediaEnded = await waitFor("task-media-ended after end-call", envelope => {
                 const event = envelope.event;
-                return event.type === "task-media-ended" && event.taskId === taskId ? event : undefined;
+                if (event.type === "task-media-ended" && event.taskId === taskId)
+                    return "ended";
+                if (event.type === "task-updated" && isTask(event.task) && event.task.id === taskId && event.task.phase === "completing")
+                    return "completing";
+                return undefined;
             }, cursor);
-            if (mediaEnded !== undefined)
+            if (mediaEnded?.found === "ended")
                 cursor = mediaEnded.at;
             if (await updated(t => t.phase === "completing", "the task completing after its media ended") !== undefined && offers("hold")) {
                 await holdRefusedOutsideHandling();
@@ -1548,8 +1564,30 @@ async function driveOneCall(drive) {
         if (isRecord(dispositions) && dispositions.required === true && Array.isArray(dispositions.codes) && isRecord(dispositions.codes[0])) {
             command.disposition = dispositions.codes[0].id;
         }
-        if (await send(command) !== undefined && await ended() !== undefined)
-            await storeReleased();
+        if (await send(command) !== undefined) {
+            // applied says the provider has disposed of the task, and its ending follows within the bound
+            // the manifest stated. Past it the host resyncs: a snapshot still carrying the task is a task
+            // held open by a provider that said it was done, and the desk shows it as unsettled.
+            ruleEvaluated("drive.disposal.unsettled");
+            const settle = Number(drive.manifest.disposalSettleMs);
+            let unsettled = false;
+            const end = await ended({ ms: settle, onExpiry: () => { unsettled = true; } });
+            if (end !== undefined)
+                await storeReleased();
+            else if (unsettled) {
+                let resync;
+                try {
+                    resync = await drive.connection.snapshot();
+                }
+                catch (error) {
+                    refuse("drive.command.rejected", "drive.disposal", `snapshot() after an unsettled disposal rejected: ${String(error)}`);
+                }
+                const still = isRecord(resync) && Array.isArray(resync.tasks) && resync.tasks.some(t => isRecord(t) && t.id === taskId && t.allocationId === allocationOf());
+                refuse("drive.disposal.unsettled", "drive.disposal", still
+                    ? `complete was applied and ${settle}ms later the task-ended has not come and a snapshot still carries ${taskId}: applied says the provider disposed of the task, and it has not`
+                    : `complete was applied and ${settle}ms later the task-ended has not come; a snapshot no longer carries ${taskId}, so the ending was owed and never sent`);
+            }
+        }
     }
     else if (latestTask().phase === "completing") {
         if (await ended() !== undefined)

package/dist/validation.js

@@ -422,6 +422,7 @@ export function validateManifest(manifest, path = "manifest") {
     if (manifest.runningStepReports !== undefined) {
         into.require(manifest.runningStepReports === true, "manifest.runningStepReports", `${path}.runningStepReports`, "runningStepReports is declared by presence, as true; a provider that takes begin and end only omits it");
     }
+    into.require(typeof manifest.disposalSettleMs === "number" && Number.isInteger(manifest.disposalSettleMs) && manifest.disposalSettleMs > 0, "manifest.disposalSettleMs", `${path}.disposalSettleMs`, "disposalSettleMs is how long after an applied disposal the task-ended is owed, a positive whole number of milliseconds, stated by every provider");
     if (manifest.orgLevels !== undefined) {
         if (!Array.isArray(manifest.orgLevels)) {
             into.add("manifest.orgLevels.shape", `${path}.orgLevels`, "orgLevels must be an array when present");
@@ -1021,6 +1022,12 @@ function validateTaskInto(task, context, path, into) {
     // The room is who is on the call now, and a task outlives its call by the whole of wrap-up: a
     // task whose call has ended -- completing, or media ended -- carries nobody, or the last thing the
     // wire said about the call stays true for ever. Empty and absent both say nobody.
+    // A completing task's call is over: its media has ended, or it never started. Audio still stated
+    // as started on a task in wrap-up is a call whose audio never ended -- the customer heard through
+    // the agent's notes -- and a task stating it contradicts itself.
+    if (task.phase === "completing" && task.media === "started") {
+        into.add("task.media.completing", `${path}.media`, "a completing task's media has ended or never started: the call is over, and media still started is audio that never ended");
+    }
     if (Array.isArray(task.onCall) && task.onCall.length > 0 && (task.phase === "completing" || task.media === "ended")) {
         into.add("task.onCall.ended", `${path}.onCall`, `the call has ended (${task.phase === "completing" ? "the task is completing" : "its media ended"}) and onCall still names people on it: the room is who is on the call now, and now nobody is`);
     }

package/guide.md

@@ -193,6 +193,7 @@ type Manifest<C extends Channel = Channel> = {
   dialOutcomes?: C extends "voice" ? DialOutcome[] : never;
   phones?: C extends "voice" ? Phone[] : never;
   runningStepReports?: true;
+  disposalSettleMs: number;
 };
 ```
 
@@ -1471,6 +1472,7 @@ export default defineAdapter({
     channel: "voice",
     supportedProtocolVersions: [OMNI_PROTOCOL_VERSION],
     authenticationMethods: ["browser-sso"],
+    disposalSettleMs: 5000,
     idleCapabilities: {
       dial: { destinations: "any-number" },
     },
@@ -1506,6 +1508,7 @@ compile time.
 | `phones` | Voice only, and required there: the phones this platform can put an agent on, `softphone` (the call's audio lands in the host) and/or `deskPhone` (a handset the platform rings; the host shows the call and opens nothing). The host picks one per login. See **How the agent hears the call**. |
 | `dialOutcomes` | Voice only. How a dial can end on this platform, as it distinguishes them: `answered` and at least one way of not reaching the destination. Required of a provider that dials at all — an idle dialpad, or tasks that transfer, conference or call back — and a `dial-outcome` carries only a declared member. See **Every dial has an outcome**. |
 | `runningStepReports` | The provider takes running reports of a host-performed step — `recordStep` with `seconds` so far and no `ended`. Omitted, the host sends exactly two reports per leg, when it began and when it ended, and a running one is refused. See **The host records what it performs**. |
+| `disposalSettleMs` | Required. How long after an applied disposal -- `complete`, `transfer` `complete`, `lead-assist` `take-over` -- the provider's `task-ended` is owed, a positive whole number of milliseconds (`manifest.disposalSettleMs`). Stated per provider, since platforms settle at different speeds. See **`task-ended`**. |
 
 ### Authentication methods
 
@@ -2854,7 +2857,12 @@ which the update itself shows: the party on the call carrying a `stage`. A compl
 republished as `in-progress` from a stale copy carries no such stage, and that is the ending the
 agent never saw. Audio arrives only on a task at work: `task-media-started` on a `completing` task
 is refused as it is on a pending one (`stream.taskMediaStarted.beforeWork`), since a connect-back
-returns the task to `in-progress` before any media.
+returns the task to `in-progress` before any media. And a task completes after its audio ends,
+never around it: an update moving a task to `completing` while the stream holds its media as
+started is refused (`stream.taskUpdated.mediaOpen`), whoever caused the ending, and a task stating
+`completing` with `media: "started"` contradicts itself on any snapshot or update
+(`task.media.completing`). The consequence the rule exists for is concrete: the customer's audio
+keeps playing through the agent's wrap-up.
 
 What the agent is told differs by source, and only one source tells them anything. Under `queue`
 and `ungoverned` the agent sees controls and nothing about where they came from: both are facts,
@@ -4487,8 +4495,16 @@ Every outcome ends the task for this agent. On `task-ended`, Omni:
 A `left` outcome ends the task for this agent alone: the call continues without them, as it does
 when a lead who joined it leaves -- see **Lead assist**.
 
-A successful `complete` or `transfer` command does not clear the task. Omni waits for `task-ended`.
-The `task-media-ended` event and the `completing` phase are likewise non-terminal. A replacement
+A successful `complete` or `transfer` command does not clear the task. Omni waits for `task-ended`,
+and not for ever: `applied` to a disposal -- `complete`, `transfer` `complete`, `lead-assist`
+`take-over` -- says the provider has disposed of the task, and its `task-ended` follows within the
+manifest's `disposalSettleMs`. A provider never answers `applied` for a disposal it has not yet
+performed. Past the bound the host calls `snapshot()`: a snapshot still carrying the task is a task
+held open by a provider that said it was done, and the desk shows it as unsettled -- "Completing...
+the provider has not confirmed" -- naming the command; a snapshot no longer carrying it clears the
+task, since the ending was owed and lost. The drive holds a provider to the same bound
+(`drive.disposal.unsettled`). The `task-media-ended` event and the `completing` phase are likewise
+non-terminal. A replacement
 snapshot that no longer contains the task also clears it. Repeated `task-ended` delivery with the
 same envelope ID is harmless, and a `task-ended` naming an allocation that has already ended is
 recognised as the late event it is, never applied to the life now open under the same id.

package/package.json

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