@xema/omni-protocol 0.1.113 → 0.1.114

package/dist/index.d.ts

@@ -1106,7 +1106,10 @@ export type VoiceTaskCommand = {
 } | {
     type: "resume";
 }
-/** End the agent's channel and every channel the agent added; the caller continues on the provider's path. Gated by `endCall`. */
+/**
+ * End the agent's channel and every channel the agent added; the caller continues on the provider's
+ * path. Gated by `endCall`, and never from hold: a `paused` task is resumed first (`command.endCall.held`).
+ */
  | {
     type: "end-call";
 }

package/dist/testing.js

@@ -1959,11 +1959,33 @@ async function testOneCall(call) {
                 return found;
         }
     }
+    // Ending my part from hold would leave the caller in the hold with nobody coming back to them: a
+    // host holds it back (command.endCall.held), and an adapter that receives it anyway must refuse
+    // it -- so the test sends it past the validator and expects failed.
+    const endCallRefusedOnHold = async () => {
+        ruleTested("test.command.rejected", "test.command.held");
+        let answer;
+        try {
+            answer = await call.connection.execute({ assignmentId: taskId, command: { type: "end-call" } });
+        }
+        catch (error) {
+            refuse("test.command.rejected", "test.command.end-call", `execute rejected rather than answered: ${String(error)}`);
+            return;
+        }
+        if (isRecord(answer) && answer.status !== "failed") {
+            refuse("test.command.held", "test.command.end-call", "the provider ended the agent's part with the caller on hold: end-call waits for resume, and the adapter is the second gate");
+            // Applied, the task leaves paused; the run reads where the adapter put it rather than resuming a call it ended.
+            await updated(t => t.phase !== "paused", "the task after an end-call applied from hold");
+        }
+    };
     // 4. Hold and resume, where offered.
     if (latestTask().phase === "in-progress" && offers("hold")) {
         if (await send({ type: call.channel === "chat" ? "pause" : "hold" }) !== undefined) {
             if (await updated(t => t.phase === "paused", "the task pausing after hold") !== undefined) {
-                if (await send({ type: "resume" }) !== undefined) {
+                if (call.channel === "voice" && offers("endCall"))
+                    await endCallRefusedOnHold();
+                // An adapter that ended the agent's part from hold has nothing left to resume; the run goes on from where it put the task.
+                if (latestTask().phase === "paused" && await send({ type: "resume" }) !== undefined) {
                     await updated(t => t.phase === "in-progress", "the task resuming after resume");
                 }
             }

package/dist/validation.js

@@ -2758,6 +2758,8 @@ export function validateTaskCommand(command, task, path = "command", taskContext
         case "end-call":
             offered("endCall");
             interaction();
+            // Ending my part with the caller on hold leaves them in the hold, with nobody coming back to them.
+            into.require(task.phase !== "paused", "command.endCall.held", path, "the caller is on hold: resume before ending your part");
             break;
         case "terminate-call":
             offered("terminateCall");

package/guide/agent.md

@@ -384,6 +384,7 @@ Migration from the earlier spellings:
 | the phone unspoken | `PhoneState` -- the device, its mute, its channels -- on `Snapshot.phone`, `phone-updated` and `TeamMember.phone`, from a manifest declaring `phoneStatus` (`snapshot.phone.required`, `.unexpected`, `phone.*`, `phone.channel.*`, `event.phone.capability`) |
 | the agent's readiness for the next call read into setCapacity | the agent's own queue: `capabilities.nextCall`, `requestNextCall`/`cancelNextCall`/`releaseLinedUp`, `Snapshot.nextCall` and `linedUp`, the `next-call` and `lined-up` events (`snapshot.nextCall.idle`, `nextCall.*`, `linedUp.*`) |
 | a harness that exercised an adapter, drove a call and evaluated rules | the harness reads as a test: `testAdapter`, `withCall`, `timeoutMs`, `notTested`, `rulesTested`, rules `test.*` (`test.timeout`, `test.offer.expired`, `test.preview.deadline`, ...) |
+| an `end-call` while the caller was on hold | refused: a `paused` task is resumed first (`command.endCall.held`), the desk shows End call disabled on hold, the provider answers `failed`, and the test names an adapter that ends from hold (`test.command.held`); `terminate-call` is not gated, it ends the caller's channel too |
 
 Update producers, consumers, saved task snapshots, and validation-rule assertions together.
 History and report rule names use `history` and `historyReport`; assignment rules use
@@ -1005,7 +1006,7 @@ declared:
 | Command | What makes it available |
 | --- | --- |
 | `answer`, `accept` | Nothing. A task that was offered can be accepted, or offering it meant nothing. |
-| `end-call` | The `endCall` capability: ends my part, the caller continues. |
+| `end-call` | The `endCall` capability: ends my part, the caller continues. Never from hold: a `paused` task is resumed first (`command.endCall.held`), or the caller is left in the hold. |
 | `terminate-call` | The `terminateCall` capability: ends the whole call, every channel on it. |
 | `conference` with `action: "remove"` | The `conference` capability, and somebody else on the call: a remove that would leave the agent alone is `end-call`, and a provider answers it `failed`. |
 | `decline` | The `decline` capability on any channel, **and** Omni local policy permitting it. One word for refusing an offer, whatever the channel. |
@@ -1020,7 +1021,8 @@ declared:
 
 **A control on the contact belongs to the interaction phases**, `in-progress` and `paused`:
 `hold`, `resume` and `pause`, `end-call` and `terminate-call`, every `conference` action, and
-every `lead-assist` action; `schedule` alone reaches into `completing`. These controls act within this agent's current interaction.
+every `lead-assist` action; `schedule` alone reaches into `completing`, and `end-call` alone stops
+short of `paused` (`command.endCall.held`), since ending my part from hold leaves the caller in it. These controls act within this agent's current interaction.
 In `completing`, that interaction has ended and its wrap work remains. The caller may still be in
 an IVR, queue or another agent's interaction, and other channels may remain connected. Completion
 of this interaction does not establish that the caller or bridge ended. The capability stays

package/guide/voice.md

@@ -258,6 +258,13 @@ provider. Two of them end the agent's part; they differ in what happens to the c
 conferenced colleague, a lead who joined -- end, and the caller continues on the path the
 provider decides: another IVR, a queue, a survey, or the end of the call. Gated by `endCall`.
 
+**Never from hold.** An `end-call` while the task is `paused` would leave the caller in the hold
+with nobody coming back to them, and the provider's path for a caller who continues never begins.
+So the caller is taken off hold first: the desk holds the command back while the task is `paused`
+(`command.endCall.held`) and shows End call disabled on hold, and a provider that receives it
+anyway answers `failed`. Resume, then end. `terminate-call` needs no such gate: it ends the
+caller's channel with the rest, held or not, and nobody is left waiting.
+
 **`terminate-call` ends the whole call.** Every channel on it ends at the provider: the agent's,
 the caller's, any colleague the agent added, and anyone else on the call. Nobody is left on the
 line. Gated by `terminateCall`, a separate permission, since ending a customer's call is a

package/guide.md

@@ -2902,7 +2902,7 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | `validateLoginStore(store)` | The login's store the agent application hands every connection: an object with `get`, `set` and `delete` (`store.shape`, `store.get`, `.set`, `.delete`). The harness holds `ConnectContext.store` to it. |
 | `validateCapacity(capacity)` | What the agent application states as capacity: a whole number of zero or more (`capacity.count`), zero being agent application-stopped. The harness states one on connect and two, one and zero after the test, each answered `applied`, and holds any offer to the count in force (`stream.taskOffered.overCapacity`). |
 | `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 conference's item, a schedule's time, 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.interaction` for every control on the call or the conversation), and the state that has to stand: a lead requested, somebody else still on the call (`command.conference.remove.alone`). An agent application 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 conference's item, a schedule's time, 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.interaction` for every control on the call or the conversation), and the state that has to stand: a lead requested, somebody else still on the call (`command.conference.remove.alone`), the caller off hold before the agent's part ends (`command.endCall.held`). An agent application 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. |
 
@@ -3050,7 +3050,9 @@ interaction phases with `hold` still declared -- in
 `confirmed`, where the provider publishes it, and in `completing` once this agent's interaction has ended -- the
 test sends `hold` 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 outside this task's
-current interaction is named (`test.command.interaction`). The test cannot put a task into a phase the provider
+current interaction is named (`test.command.interaction`). With the task on hold, the test sends `end-call` past the
+validator the same way and expects `failed`, naming an adapter that ends the agent's part with the caller in the
+hold (`test.command.held`). The test cannot put a task into a phase the provider
 never publishes, so a provider that goes straight from `pending` to `in-progress` is checked in
 `completing` alone. A task the agent completes is
 completed from wherever it stands once the test has nothing left to do on it -- from `completing`

package/package.json

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