@xema/omni-protocol 0.1.57 → 0.1.59

package/dist/testing.js

@@ -784,6 +784,17 @@ export class TaskStream {
         const known = id === undefined ? undefined : this.tasks.get(id);
         switch (event.type) {
             case "snapshot":
+                // A snapshot replaces what is known, and still may not say a task lost terms it had read.
+                if (isRecord(event.snapshot) && Array.isArray(event.snapshot.tasks)) {
+                    event.snapshot.tasks.forEach((task, index) => {
+                        if (!isRecord(task) || typeof task.id !== "string")
+                            return;
+                        const was = this.tasks.get(task.id);
+                        if (was !== undefined && (was.source === "queue" || was.source === "ungoverned") && task.capabilitySource === "undetermined") {
+                            refuse("stream.snapshot.capabilitySource", `${at}.snapshot.tasks[${index}].capabilitySource`, `${task.id} was published under ${was.source} terms and the snapshot says undetermined: terms once read stay read`);
+                        }
+                    });
+                }
                 this.seed(event.snapshot);
                 break;
             case "task-offered":
@@ -1042,7 +1053,21 @@ async function driveOneCall(drive) {
             }, cursor);
             if (mediaEnded !== undefined)
                 cursor = mediaEnded.at;
-            await updated(t => t.phase === "completing", "the task completing after its media ended");
+            if (await updated(t => t.phase === "completing", "the task completing after its media ended") !== undefined && offers("hold")) {
+                // The other direction of step 4: the same control, still declared, on a call that is over.
+                // A host holds it back (command.phase.handling), and an adapter that receives it anyway
+                // must refuse it -- so the drive sends it past the validator and expects failed.
+                let answer;
+                try {
+                    answer = await drive.connection.execute({ taskId, command: { type: "hold" } });
+                }
+                catch (error) {
+                    refuse("drive.command.rejected", "drive.command.hold", `execute rejected rather than answered: ${String(error)}`);
+                }
+                if (isRecord(answer) && answer.status !== "failed") {
+                    refuse("drive.command.handling", "drive.command.hold", `the provider applied hold on a completing task: a control on the contact belongs to in-progress or paused, and the adapter is the second gate`);
+                }
+            }
         }
     }
     if (typeof session?.close === "function") {

package/dist/validation.js

@@ -1831,6 +1831,10 @@ export function validateTaskCommand(command, task, path = "command") {
         return true;
     };
     const inPhase = (rule, ...phases) => into.require(phases.includes(String(task.phase)), rule, path, `${String(type)} belongs to ${phases.join(" or ")}, and the task is ${String(task.phase)}`);
+    // A control on the contact acts on a contact being handled. Before in-progress there is nothing
+    // to act on yet, and in completing the handling has ended: a call with nobody on it, a
+    // conversation closed. What a capability offers, the phase decides whether there is anything to use it on.
+    const handling = () => inPhase("command.phase.handling", "in-progress", "paused");
     const onCall = Array.isArray(task.onCall) ? task.onCall.filter(isPlainObject) : [];
     switch (type) {
         case "answer":
@@ -1846,23 +1850,28 @@ export function validateTaskCommand(command, task, path = "command") {
             break;
         case "mute":
             offered("mute");
+            handling();
             break;
         case "hold":
         case "resume":
         case "pause":
             offered("hold");
+            handling();
             break;
         case "end-call":
             offered("endCall");
+            handling();
             break;
         case "recording":
             offered("recording");
+            handling();
             break;
         case "connect-back":
             offered("connectBack");
             inPhase("command.phase.completing", "completing");
             break;
         case "transfer":
+            handling();
             if (command.action === "cold")
                 offered("coldTransfer");
             else if (command.action === "warm")
@@ -1872,6 +1881,7 @@ export function validateTaskCommand(command, task, path = "command") {
             }
             break;
         case "lead-assist":
+            handling();
             if (command.action === "request" || command.action === "cancel") {
                 offered("leadAssist");
                 if (command.action === "cancel") {
@@ -1883,6 +1893,7 @@ export function validateTaskCommand(command, task, path = "command") {
             }
             break;
         case "conference":
+            handling();
             if (offered("conference") && command.action === "remove") {
                 const others = onCall.filter(entry => entry.role !== "agent");
                 if (command.party === true) {

package/guide.md

@@ -2728,7 +2728,8 @@ the terms arrive, the task is republished under `queue` with the set as it now s
 republish as any other permission that changed while the task was open. The move goes one way.
 Terms once read stay read: a re-read that fails mid-task is not a new fact about the task, so the
 last statement stands and the failure is a `diagnostic`, and a task that was published under
-`queue` or `ungoverned` never returns to `undetermined` (`stream.taskUpdated.capabilitySource`).
+`queue` or `ungoverned` never returns to `undetermined`, on an update (`stream.taskUpdated.capabilitySource`)
+or on a resync snapshot (`stream.snapshot.capabilitySource`).
 
 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,
@@ -2736,8 +2737,16 @@ and an agent working a call has no use for the name of the rule behind its butto
 `undetermined` the agent is told, beside the controls, that these are what the provider will honour
 until the queue's terms arrive, and that the controls may change when they do -- a statement about
 the buttons in front of them now, not about the provider, because that is what changes when the
-republish lands. The two words are close in English and far apart on the desk: `ungoverned` is
-silence, `undetermined` is a notice. `exerciseAdapter` treats a
+republish lands. It stays for as long as the set is provisional, beside the controls it qualifies;
+a message that shows and clears has said nothing about the buttons still on the screen. The two
+words are close in English and far apart on the desk: `ungoverned` is silence, `undetermined` is a
+standing notice.
+
+One consequence for whoever builds the host: because a conformance run fails on `undetermined`, a
+conformant adapter never shows a host `undetermined` under test, and a clean `exerciseAdapter`
+result says nothing about how the host renders it. That rendering is tested against a fixture --
+a task published under `undetermined` shows the notice, the same task under `queue` shows none --
+and never against an adapter, even in principle. `exerciseAdapter` treats a
 task published under `undetermined` as a violation (`capabilitySource.undetermined`), as it treats
 a diagnostic: a conformance run against a platform that cannot say what it permits fails loudly
 rather than passing with a note.
@@ -2753,6 +2762,11 @@ const taskCapabilities = {
 } satisfies Pick<Task<"voice">, "channel" | "capabilities" | "browsers">;
 ```
 
+A capability says the control may be offered; the task's phase says whether there is anything to use
+it on. Every control below that acts on the call or the conversation -- everything but `decline`,
+`connectBack` and `dispositions` -- is offered only while the task is `in-progress` or `paused`.
+See **Which commands need a capability**.
+
 ### Voice capabilities
 
 | Capability | Omni UI | Contract |
@@ -4000,6 +4014,17 @@ declared:
 | `lead-assist` with `action: "take-over"` or `"leave"` | The lead's own task, on a call they joined -- `Task.assisting` present. An agent's task never has it, and a provider that receives either without it answers `failed`. |
 | Everything else | Its own named capability. |
 
+**A control on the contact belongs to the handling phases**, `in-progress` and `paused`: `mute`,
+`hold`, `resume` and `pause`, `end-call`, `recording`, every `transfer` and `conference` action, and
+every `lead-assist` action. Each acts on the call or the conversation, and only while there is one.
+Before `in-progress` nothing has been placed or opened; in `completing` the handling has ended -- a
+call with nobody on it, a conversation closed -- and a wrap-up that still shows Transfer shows it
+for nothing. The capability stays declared, because it is a property of the task and the task is
+still open; the phase says there is nothing to use it on. Omni shows none of these controls outside
+the two phases, and `validateTaskCommand` refuses each of them there (`command.phase.handling`).
+The commands with a phase of their own -- `answer`, `accept`, `decline` and `reject` in `pending`,
+`call` in `preview`, `connect-back` in `completing`, `complete` in any -- are not among them.
+
 `validateTaskCommand(command, task)` holds a command to this table at runtime, both ways: the
 capability it needs, the phase it belongs to, and the state that has to stand. The task it wants
 is the one the provider published, not a host's own mapping of it: a host that keeps only its
@@ -4368,7 +4393,7 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | `validateHandlingReport(report, path?, manifest?)` | What the host reports of a leg it performed, for an adapter to check before forwarding: a task, a step, when it began, a positive `seconds` where stated, and an explicit `ended` that carries the final duration. Given the manifest, a running report is refused unless it declares `runningStepReports`. |
 | `validateHostReport(report)` | The host's own report as published to an adapter: `online`, and where there is audio, an input that is `available` with the microphone and `flowing`, or `unavailable` with a reason and the failure that says why, and an output that is `available` or `unavailable` with its failure. The harness validates whatever host a test hands the adapter; `stillHost(report)` builds one that never changes. |
 | `validateAuthenticationResult(result, method)` | What `start()` or `complete()` answered: a challenge or a rejection, a login or a rejection. A rejection's failure is held to its rules -- an `omni.` code the contract lists, and `omni.phone-not-permitted` never retryable, since the agent's station is configuration. `validateAuthenticationFailure(failure)` is the same check on a failure alone. |
-| `validateTaskCommand(command, task?)` | What a command needs to be issuable, against the task it names: its own shape -- a dial's `dialId`, a transfer's item, a remove naming exactly one person -- and, with the task, the capability the table above gates it on (`command.capability.<name>`, `.locked`), the phase it belongs to (`command.phase.*`), and the state that has to stand: a consulted entry, a lead requested, somebody else still on the call (`command.conference.remove.alone`). A host validates before sending and an adapter before acting. |
+| `validateTaskCommand(command, task?)` | What a command needs to be issuable, against the task it names: its own shape -- a dial's `dialId`, a transfer's item, a remove naming exactly one person -- and, with the task, the capability the table above gates it on (`command.capability.<name>`, `.locked`), the phase it belongs to (`command.phase.*`, `command.phase.handling` for every control on the call or the conversation), and the state that has to stand: a consulted entry, a lead requested, somebody else still on the call (`command.conference.remove.alone`). A host validates before sending and an adapter before acting. |
 | `validateResult(result, method)` | What a connection method answered: the status it gives, a failure where the status says so and nowhere else, the failure's shape, and that an `omni.` code is one this contract names. |
 | `validateAuthenticationState(state)` | The identity each state must carry, the capabilities a usable login declares, and the expiry that only `authenticated` may. Omni applies it to every state a session publishes — the republished as much as the first. |
 
@@ -4439,7 +4464,10 @@ complete it with a disposition where the agent completes -- and holds every step
 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
+(`drive.timeout`, after `driveTimeoutMs`, 5000 by default). Once the call has ended and the task is
+`completing`, the drive sends `hold` once more, past the validator that would hold it back, and
+expects `failed`: the adapter is the second gate on a control on the contact, and one that applies
+it on a call that is over is named (`drive.command.handling`). 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.

package/package.json

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