@xema/omni-protocol 0.1.52 → 0.1.54

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,186 @@ 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);
+    };
+    // Media may arrive any time after the accept, before or after the task's own update says
+    // in-progress: the event is the provider's word that the audio should attach, never a reply to
+    // openMedia, so the drive looks for it from the accept rather than from the last update it read.
+    const acceptedAt = drive.events.length;
+    // 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;
+            }, acceptedAt);
+            if (started === undefined)
+                return found;
+            cursor = Math.max(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.
+    // A conversation has no media to end and no completing phase to wait for: a chat or an email,
+    // and a voice task offering no end-call, is completed from where it stands.
+    const completable = latestTask().phase === "completing" || latestTask().phase === "in-progress" || latestTask().phase === "paused";
+    if (latestTask().completionMode === "agent-command" && completable) {
+        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/guide.md

@@ -4127,6 +4127,9 @@ partial patch.
 The provider's word that the task's audio should now attach. Omni calls `openMedia` on it — and on
 a task carried with `media: "started"`, which is how a reconnect snapshot reattaches audio an
 earlier event brought — and renders the call as live from that word, never from its own senses. It
+precedes `openMedia` and is never a reply to it: a provider whose media state comes from the
+platform, a station going in use the moment a call is answered, sends it then, before any host has
+opened anything, and `openMedia` has its own answer for what the host did. It
 names a task whose work has begun, and it alternates with `task-media-ended`: media that never
 started cannot end, so a live call whose provider says nothing about its audio is a provider in
 breach, not a state a desk fills in from its own devices.
@@ -4327,6 +4330,32 @@ 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). A task the agent completes is
+completed from wherever it stands once the drive has nothing left to do on it -- from `completing`
+after an `end-call`, or from `in-progress` where there is no call to end, which is every chat and
+email and a voice task offering no `endCall` -- so a conversation reaches its end as a call does.
+The drive stops where the task offers no way on and says nothing about what it could not reach. A
+softphone adapter written for a browser needs its media APIs supplied by whatever runs the
+harness: the drive opens media outside a browser, and a provider that quietly stopped carrying audio
+where `AudioContext` was missing would be lying about the one thing the channel is for. 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.52",
+  "version": "0.1.54",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",