@xema/omni-protocol 0.1.51 → 0.1.53

package/dist/testing.d.ts

@@ -33,6 +33,16 @@ export interface AdapterContractResult {
 export interface ExerciseAdapterOptions {
     /** Return violations in the result instead of throwing. Defaults to `false`. */
     collectOnly?: boolean;
+    /**
+     * Drive one ordinary lifecycle on the first task the provider offers -- accept it, open its
+     * media on a softphone, hold and resume where offered, end the call where offered, complete it
+     * where the agent completes -- so the rules about a live call are reached rather than listed
+     * under `notExercised`. Off by default, since it issues commands against whatever platform the
+     * adapter is connected to: turn it on against a test backend.
+     */
+    drive?: boolean;
+    /** How long the drive waits for each thing the provider owes it. Defaults to 5000. */
+    driveTimeoutMs?: number;
 }
 /**
  * Adapter conformance exercise: validates the manifest, opens an authenticated session,

package/dist/testing.js

@@ -1,5 +1,5 @@
 import { browserSessionKey, effectiveLevels, sameCapabilities, } from "./index.js";
-import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateManifest, validateResult, validateSnapshot, validateTimeZone, validatePhone, isTimeZone, sameTimeZone, } from "./validation.js";
+import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateManifest, validateResult, validateSnapshot, validateTimeZone, validatePhone, validateTaskCommand, isTimeZone, sameTimeZone, } from "./validation.js";
 export { ProtocolConformanceError, assertNoViolations } from "./validation.js";
 /**
  * A part of the contract a run may never reach: state nothing obliges an adapter to publish, so
@@ -290,6 +290,8 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         if (softphone)
             requireMethod(live, "openMedia", "the login is on a softphone");
         const eventIds = new Set();
+        // The drive waits on events: each waiter is offered every envelope as it lands.
+        const waiters = new Set();
         unsubscribe = connection.subscribe(envelope => {
             observeEvent(envelope, seen);
             violations.push(...validateEventEnvelope(envelope, adapter.manifest, "event", reader()));
@@ -312,6 +314,8 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                 eventIds.add(envelope.id);
             }
             events.push(envelope);
+            for (const waiter of waiters)
+                waiter(envelope);
         });
         const snapshot = await connection.snapshot();
         observeSnapshot(snapshot, seen);
@@ -359,6 +363,14 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                 message: `the provider would not accept a capacity: ${capacity.failure.code}`,
             });
         }
+        if (options.drive) {
+            const localAudio = isRecord(first) && isRecord(first.audio) && isRecord(first.audio.input) && first.audio.input.status === "available"
+                ? first.audio.input.localAudio : undefined;
+            violations.push(...await driveOneCall({
+                connection: live, channel: adapter.manifest.channel, softphone, snapshot, events, waiters, stream, localAudio,
+                timeoutMs: options.driveTimeoutMs ?? 5000,
+            }));
+        }
     }
     finally {
         let clean = true;
@@ -801,6 +813,179 @@ export class TaskStream {
         return found;
     }
 }
+/**
+ * One ordinary lifecycle on the first task offered, each step held to the rules a host holds a
+ * provider to: the command validated against the task as published, the result validated for the
+ * method, and the event the provider owes in return awaited -- a step that never arrives is a
+ * violation naming what was owed. The drive stops where the task offers no way on (no `endCall`,
+ * a provider that completes for itself) and says nothing about what it could not reach.
+ */
+async function driveOneCall(drive) {
+    const found = [];
+    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 => {
+        for (let index = from; index < drive.events.length; index += 1) {
+            const hit = matches(drive.events[index]);
+            if (hit !== undefined) {
+                resolve({ found: hit, at: index + 1 });
+                return;
+            }
+        }
+        const timer = setTimeout(() => {
+            drive.waiters.delete(waiter);
+            refuse("drive.timeout", "drive", `the provider owed ${what} within ${drive.timeoutMs}ms and it never arrived`);
+            resolve(undefined);
+        }, drive.timeoutMs);
+        const waiter = (envelope) => {
+            const hit = matches(envelope);
+            if (hit === undefined)
+                return;
+            clearTimeout(timer);
+            drive.waiters.delete(waiter);
+            resolve({ found: hit, at: drive.events.length });
+        };
+        drive.waiters.add(waiter);
+    });
+    // The task, as first seen: on the snapshot, or on the first offer.
+    let cursor = 0;
+    let task = isRecord(drive.snapshot) && Array.isArray(drive.snapshot.tasks) ? drive.snapshot.tasks.find(isTask) : undefined;
+    if (task === undefined) {
+        const offered = await waitFor("a task-offered", envelope => {
+            const event = envelope.event;
+            return event.type === "task-offered" && isTask(event.task) ? event.task : undefined;
+        }, 0);
+        if (offered === undefined)
+            return found;
+        task = offered.found;
+        cursor = offered.at;
+    }
+    const taskId = task.id;
+    const latestTask = () => task;
+    const updated = (until, what) => waitFor(what, envelope => {
+        const event = envelope.event;
+        if ((event.type === "task-updated" || event.type === "task-offered") && isTask(event.task) && event.task.id === taskId) {
+            task = event.task;
+            return until(event.task) ? event.task : undefined;
+        }
+        return undefined;
+    }, cursor).then(hit => { if (hit)
+        cursor = hit.at; return hit; });
+    const ended = () => waitFor("a task-ended for the driven task", envelope => {
+        const event = envelope.event;
+        return event.type === "task-ended" && event.taskId === taskId ? event : undefined;
+    }, cursor);
+    // Every command the drive sends is validated against the task as published, and its answer for its method.
+    const send = async (command, dialId) => {
+        const own = validateTaskCommand(command, latestTask(), `drive.command.${String(command.type)}`);
+        found.push(...own);
+        if (own.length > 0)
+            return undefined;
+        let result;
+        try {
+            result = await drive.connection.execute({ taskId, command });
+        }
+        catch (error) {
+            refuse("drive.command.rejected", `drive.command.${String(command.type)}`, `execute rejected rather than answered: ${String(error)}`);
+            return undefined;
+        }
+        found.push(...validateResult(result, "execute", `drive.command.${String(command.type)}.result`, dialId));
+        if (isRecord(result) && result.status === "failed") {
+            refuse("drive.command.failed", `drive.command.${String(command.type)}`, `the provider refused ${String(command.type)} on a task that offered it: ${String(isRecord(result.failure) ? result.failure.code : result.failure)}`);
+            return undefined;
+        }
+        return isRecord(result) ? result : undefined;
+    };
+    const offers = (name) => {
+        const capabilities = isRecord(latestTask().capabilities) ? latestTask().capabilities : {};
+        const declared = capabilities[name];
+        return declared !== undefined && !(isRecord(declared) && declared.lockedBy !== undefined);
+    };
+    // 1. Accept the offer, if it is one.
+    if (latestTask().phase === "pending") {
+        if (await send({ type: drive.channel === "voice" ? "answer" : "accept" }) === undefined)
+            return found;
+        if (await updated(t => t.phase !== "pending", "the task leaving pending after it was accepted") === undefined)
+            return found;
+    }
+    // 2. A preview: press Call, which is a dial.
+    if (latestTask().phase === "preview") {
+        const dialId = `drive-${taskId}`;
+        drive.stream.dialled(dialId);
+        if (await send({ type: "call", dialId }, dialId) === undefined)
+            return found;
+        if (await updated(t => t.phase === "in-progress" || t.phase === "completing", "the task leaving preview after Call") === undefined)
+            return found;
+    }
+    if (latestTask().phase === "confirmed") {
+        if (await updated(t => t.phase !== "confirmed", "the task leaving confirmed") === undefined)
+            return found;
+    }
+    // 3. On a softphone, the audio arrives and the host opens it.
+    let session;
+    if (drive.softphone && latestTask().phase === "in-progress") {
+        if (latestTask().media !== "started") {
+            const started = await waitFor("task-media-started for the driven task", envelope => {
+                const event = envelope.event;
+                return event.type === "task-media-started" && event.taskId === taskId ? event : undefined;
+            }, cursor);
+            if (started === undefined)
+                return found;
+            cursor = started.at;
+        }
+        const opened = await drive.connection.openMedia?.({ taskId, localAudio: drive.localAudio });
+        found.push(...validateResult(opened, "openMedia", "drive.openMedia"));
+        if (isRecord(opened) && opened.status === "opened")
+            session = opened.session;
+        else if (isRecord(opened))
+            refuse("drive.openMedia.unavailable", "drive.openMedia", "a softphone login's adapter could not open the call's audio");
+    }
+    // 4. Hold and resume, where offered.
+    if (latestTask().phase === "in-progress" && offers("hold")) {
+        if (await send({ type: drive.channel === "chat" ? "pause" : "hold" }) !== undefined) {
+            if (await updated(t => t.phase === "paused", "the task pausing after hold") !== undefined) {
+                if (await send({ type: "resume" }) !== undefined) {
+                    await updated(t => t.phase === "in-progress", "the task resuming after resume");
+                }
+            }
+        }
+    }
+    // 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) {
+            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;
+            }, cursor);
+            if (mediaEnded !== undefined)
+                cursor = mediaEnded.at;
+            await updated(t => t.phase === "completing", "the task completing after its media ended");
+        }
+    }
+    if (typeof session?.close === "function") {
+        try {
+            session.close();
+        }
+        catch {
+            refuse("drive.openMedia.close", "drive.openMedia", "the media session threw on close");
+        }
+    }
+    // 6. Complete, where the agent completes; otherwise the provider does, and the drive waits for it.
+    if (latestTask().completionMode === "agent-command" && latestTask().phase === "completing") {
+        const command = { type: "complete" };
+        const dispositions = isRecord(latestTask().capabilities) ? latestTask().capabilities.dispositions : undefined;
+        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();
+    }
+    else if (latestTask().phase === "completing") {
+        await ended();
+    }
+    return found;
+}
 // A request goes not-requested -> awaiting-decision | granted; a commit goes granted ->
 // starting-after-task | in-effect; work ending goes starting-after-task -> in-effect; a denial,
 // a cancel, an end or a release goes back to not-requested; a placed break arrives in-effect

package/dist/validation.js

@@ -956,6 +956,12 @@ function validateTaskInto(task, context, path, into) {
     validateTaskAttributes(task.attributes, `${path}.attributes`, into);
     validateHandlingHistory(task.handlingHistory, `${path}.handlingHistory`, into);
     validateOnCall(task.onCall, context.channel, `${path}.onCall`, 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.
+    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`);
+    }
     validateTaskMedia(task.media, context.channel, `${path}.media`, into);
     validateLeadAssist(task.leadAssist, context.channel, `${path}.leadAssist`, into);
     validateAssisting(task.assisting, context.channel, `${path}.assisting`, into);

package/guide.md

@@ -2994,6 +2994,26 @@ the platform added itself carries none. `held: true` is presence as claim. A sna
 after a transfer reads the room from here rather than inferring it from a sequence of outcomes it
 never saw.
 
+**`onCall` is who is on the call now, and a task outlives its call.** Wrap-up is not an ending:
+the task is alive, the agent is working, and nothing arrives to say the call ended until they
+dispose. So the room must not be the last word about a call that has ended. Once the call is over
+-- the task `completing`, or its `media` ended -- `onCall` is empty, or absent only where the
+provider never publishes the room at all, and a task carrying people on a call that has ended is
+refused (`task.onCall.ended`). Empty says nobody is on the call; absent says the provider does not
+say who is, which is a different claim, so a provider that publishes the room publishes one last
+change: the empty room.
+
+**A field that describes the present is cleared by the transition that ends it.** `onCall`,
+`previewEndsAt` and `atDeadline` are three instances of one shape, and there will be more: each
+describes a state that is true now, and each is carried past the moment it stops being true by the
+most natural implementation there is, building the next task by spreading the last one. The
+provider's own state looks right, the claim on the wire is stale, and only the host sees it. An
+adapter that builds each transition from what is true after it, rather than from what was true
+before, needs none of these rules named. Two agents were
+once shown on calls for the better part of an hour while callers queued, because the last message
+describing the room live was never followed by one saying it had emptied, and every consumer that
+derived anything from it was wrong in a way that looked like its own bug.
+
 **A dialled entry is listed from the moment the dial is placed, not from the answer.** The entry is
 what makes `transfer` `cancel` issuable and what `conference` `remove` names, and a destination the
 agent cannot call off while it rings is a parked customer with no way back -- which is the very case
@@ -4307,6 +4327,26 @@ optional part of a task (`task.browsers`, `task.handlingHistory`, `task.leadAssi
 each event type (`event.task-ended`, …) — and so what a clean `violations` says nothing about.
 Nothing there is a violation: an adapter with no team has nothing to exercise. But a fixture with
 no tasks exercises no task rule, and a pass over it reads as coverage it is not.
+
+**A static run never answers a call.** It states a capacity and disconnects, so everything
+downstream of `answer` -- the room, the stage, media, every phase past `pending`, every dial
+outcome -- stays in `notExercised` for every adapter, and a rule about a live call is enforced only
+in each adopter's own tests. `{ drive: true }` closes that: the exercise takes the first task the
+provider offers through one ordinary lifecycle -- accept it, wait for its media and open it on a
+softphone, hold and resume where the task offers `hold`, end the call where it offers `endCall`,
+complete it with a disposition where the agent completes -- and holds every step to the rules a
+host holds a provider to. Each command is validated against the task as published
+(`drive.command.*`), each answer for its method, a refusal of a control the task offered is a
+violation (`drive.command.failed`), and an event the provider owes and never sends is one too
+(`drive.timeout`, after `driveTimeoutMs`, 5000 by default). The drive stops where the task offers
+no way on and says nothing about what it could not reach. It is off by default because it issues
+commands against whatever platform the adapter is connected to: turn it on against a test backend.
+
+```ts
+const driven = await exerciseAdapter(adapter, context, { collectOnly: true, drive: true });
+expect(driven.violations).toEqual([]);
+assertReached(driven, ["task.onCall", "task.media", "event.task-ended"]);
+```
 `assertReached(result, subjects)` is the paired assertion: it throws naming every subject the run
 never met, so a test that meant to check a roster cannot pass on a fixture that never produced one.
 

package/package.json

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