@xema/omni-protocol 0.1.72 → 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

@@ -1217,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) {
@@ -1227,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)
@@ -1368,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) => {
@@ -1564,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");

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
 
@@ -4492,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.72",
+  "version": "0.1.73",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",