@xema/omni-protocol 0.1.35 → 0.1.37

package/dist/index.d.ts

@@ -576,15 +576,18 @@ export type TaskCompletion = {
     wrapAllowance: DurationSeconds;
 };
 export type OnCallRole = "party" | "agent" | "consulted" | "conferenced";
+/** Where a dialled entry stands: `ringing` until its dial is answered, `joined` after. */
+export type OnCallStage = "ringing" | "joined";
 export declare const ON_CALL_ROLES: readonly ["party", "agent", "consulted", "conferenced"];
 /**
  * Somebody on the call, or being brought onto it, as the provider states it: who, since when, and
  * whether they are held aside. `party` is the customer; `agent` a person, by user id; `consulted`
  * and `conferenced` someone a dial is bringing in -- listed from the moment the dial is placed, so
- * the agent can call it off while it rings -- carrying the dial when a host placed it and the
- * address either way. Whether they answered is the `dial-outcome`'s to say. `label` names a
- * destination -- a person, a queue -- not a phrase. At most one `party` and one `consulted`: the
- * consult commands name neither because there is exactly one.
+ * the agent can call it off while it rings -- carrying the dial when a host placed it, the address
+ * either way, and the `stage` it has reached: `ringing` until the dial is answered, `joined` after,
+ * stated so a snapshot says who is present without anyone having seen the outcome. Nobody ringing is
+ * held. `label` names a destination -- a person, a queue -- not a phrase. At most one `party` and
+ * one `consulted`: the consult commands name neither because there is exactly one.
  */
 export type OnCall = {
     since: IsoTimestamp;
@@ -597,6 +600,7 @@ export type OnCall = {
 } | {
     role: "consulted" | "conferenced";
     destination: string;
+    stage: OnCallStage;
     dialId?: DialId;
     label?: string;
 });

package/dist/testing.js

@@ -619,7 +619,7 @@ export class TaskStream {
     tasks = new Map();
     // Every dial the stream can place an outcome against: one the host said it placed, or one a
     // task carried on `onCall` or in its record -- which is how a dial made before a transfer is known
-    // to whoever holds the task now. `ended` once its outcome arrived, since an outcome comes once.
+    // to whoever holds the task now. `answered` or `ended` once its outcome arrived, since it comes once.
     dials = new Map();
     /** The host placed a dial: its outcome, whenever it arrives, is one the stream expects. */
     dialled(dialId) {
@@ -640,7 +640,16 @@ export class TaskStream {
     }
     static stated(task) {
         const media = isRecord(task) && (task.media === "started" || task.media === "ended") ? task.media : "none";
-        return { phase: String(isRecord(task) ? task.phase : undefined), media };
+        // The stage of every dialled entry the room names by its dial, so an update can be held to the
+        // outcome that moves it.
+        const stages = new Map();
+        if (isRecord(task) && Array.isArray(task.onCall)) {
+            for (const entry of task.onCall) {
+                if (isRecord(entry) && typeof entry.dialId === "string" && typeof entry.stage === "string")
+                    stages.set(entry.dialId, entry.stage);
+            }
+        }
+        return { phase: String(isRecord(task) ? task.phase : undefined), media, stages };
     }
     /** Replaces what is known with a snapshot's tasks, as a snapshot replaces Omni's state. */
     seed(snapshot) {
@@ -696,6 +705,14 @@ export class TaskStream {
                     if (known.media !== next.media && !(known.media === "ended" && next.media === "none")) {
                         refuse("stream.taskUpdated.media", `${at}.task.media`, `a task-updated re-states media, it does not move it: ${id} held ${known.media} and the update says ${next.media}; audio arrives on task-media-started and ends on task-media-ended`);
                     }
+                    // The same pairing for a dialled entry: the dial-outcome is the transition, the stage is
+                    // the state, and the outcome comes first. An update that joins an entry on its own is
+                    // moving what only an answered outcome moves.
+                    for (const [dialId, stage] of next.stages) {
+                        if (stage === "joined" && known.stages.get(dialId) === "ringing" && this.dials.get(dialId) !== "answered") {
+                            refuse("stream.taskUpdated.stage", `${at}.task.onCall`, `a task-updated re-states a stage, it does not move it: ${dialId} was ringing and the update says joined before any answered dial-outcome for it`);
+                        }
+                    }
                     this.tasks.set(id, next);
                 }
                 this.noteDials(event.task);
@@ -746,10 +763,10 @@ export class TaskStream {
                 if (dial === undefined) {
                     refuse("stream.dialOutcome.unknown", `${at}.dialId`, `${event.dialId} is not a dial the host placed or a task carried: an outcome ends a dial somebody made`);
                 }
-                else if (dial === "ended") {
+                else if (dial !== "placed") {
                     refuse("stream.dialOutcome.duplicate", `${at}.dialId`, `${event.dialId} already has its outcome; a dial ends once`);
                 }
-                this.dials.set(event.dialId, "ended");
+                this.dials.set(event.dialId, event.outcome === "answered" ? "answered" : "ended");
                 break;
             }
             default:

package/dist/validation.js

@@ -71,6 +71,7 @@ const DIAL_OUTCOMES = membersOf({ answered: true, busy: true, "no-answer": true,
 /** The outcomes that name a cause. `unexplained` is declarable only beside one of these. */
 const EXPLAINED_FAILURES = ["busy", "no-answer", "unreachable", "rejected", "cancelled"];
 const ON_CALL_ROLES = membersOf({ party: true, agent: true, consulted: true, conferenced: true });
+const ON_CALL_STAGES = membersOf({ ringing: true, joined: true });
 /** The task capabilities under which a command dials, and so need the manifest to say how a dial ends. */
 const DIALLING_CAPABILITIES = ["callback", "blindTransfer", "consultTransfer", "conference"];
 const SNAPSHOT_REASONS = membersOf({
@@ -778,13 +779,17 @@ function validateOnCall(value, channel, path, into) {
         }
         if (role === "consulted" || role === "conferenced") {
             into.filled(entry.destination, "task.onCall.destination", `${at}.destination`, `a ${role} entry names the destination that was dialled`);
+            // Stated, so a snapshot says who is present without anyone having seen the dial's outcome.
+            if (into.oneOf(entry.stage, ON_CALL_STAGES, "task.onCall.stage", `${at}.stage`)) {
+                into.require(!(entry.stage === "ringing" && entry.held === true), "task.onCall.held.ringing", `${at}.held`, "nobody ringing is held; held belongs to somebody who has joined");
+            }
             if (entry.dialId !== undefined)
                 into.filled(entry.dialId, "task.onCall.dialId", `${at}.dialId`, "dialId must not be empty when present");
             if (entry.label !== undefined)
                 into.filled(entry.label, "task.onCall.label", `${at}.label`, "a label must not be empty when present");
         }
         else {
-            for (const field of ["destination", "dialId", "label"]) {
+            for (const field of ["destination", "dialId", "label", "stage"]) {
                 into.require(entry[field] === undefined, `task.onCall.${field}.unexpected`, `${at}.${field}`, `a ${role} was dialled from nowhere; ${field} belongs on consulted or conferenced`);
             }
         }

package/guide.md

@@ -589,10 +589,12 @@ type TaskCompletion =
 
 type OnCallRole = "party" | "agent" | "consulted" | "conferenced";
 
+type OnCallStage = "ringing" | "joined";
+
 type OnCall = { since: IsoTimestamp; held?: true } & (
   | { role: "party" }
   | { role: "agent"; userId: UserId }
-  | { role: "consulted" | "conferenced"; destination: string; dialId?: DialId; label?: string }
+  | { role: "consulted" | "conferenced"; destination: string; stage: OnCallStage; dialId?: DialId; label?: string }
 );
 
 type TaskLead = {
@@ -2133,7 +2135,7 @@ time. Runtime conformance checks also require the task channel to match its prov
 | `wrapAllowance` | Fixed time allowed to complete the task after primary handling ends. For real-time media, it begins after `task-media-ended`. Required under `provider-automatic`, where the provider acts on it. Optional under `agent-command`: omitted says the provider imposes no deadline, and Omni counts nothing down. |
 | `attributes` | Optional ordered, typed `TaskAttribute` entries with keys unique within the task. Each contact or timestamp is a separate array item; new attribute shapes require new union members. |
 | `handlingHistory` | The call record: `steps` — the ordered handling history of this open task, one entry per occurrence, oldest first — and what they add up to before this agent, `handleSeconds`, `holdSeconds`, `queueSeconds`, `transfers`, each present when the provider knows it. Live task data restated with the task, not a permanent archive. See **How a task has been handled**. |
-| `onCall` | Voice only. Who is on the call, or being brought onto it, as the provider states it, replaced whole with the task: `party` is the customer, `agent` a person by user id, `consulted` and `conferenced` somebody a dial is bringing in, listed from the moment the dial is placed -- with the `destination` dialled, the `dialId` where a host placed it, and `held: true` on anyone parked. A `consulted` entry is what makes `transfer` `complete` and `cancel` issuable. `label` names a destination -- a person, a queue -- not a phrase; the host supplies the verb. Present when the provider knows the room, absent when it does not. See **Every dial has an outcome**. |
+| `onCall` | Voice only. Who is on the call, or being brought onto it, as the provider states it, replaced whole with the task: `party` is the customer, `agent` a person by user id, `consulted` and `conferenced` somebody a dial is bringing in, listed from the moment the dial is placed -- with the `destination` dialled, the `dialId` where a host placed it, the `stage` reached (`ringing` until answered, `joined` after), and `held: true` on anyone joined and parked. A `consulted` entry is what makes `transfer` `complete` and `cancel` issuable. `label` names a destination -- a person, a queue -- not a phrase; the host supplies the verb. Present when the provider knows the room, absent when it does not. See **Every dial has an outcome**. |
 | `lead` | Voice only. Present from the agent's request for a lead until the lead leaves or the request ends: `requested` while nobody has joined, `joined` with the lead's `leadId` once somebody has. See **Consulting a lead**. |
 | `assisting` | Voice only, on the lead's own task for a call they joined: which member asked, with their note. Its presence is what makes `lead` `take-over` and `leave` issuable. See **Consulting a lead**. |
 
@@ -2787,10 +2789,13 @@ set: `answered`, `busy`, `no-answer`, `unreachable`, `rejected`, `cancelled`, `u
 `answered` is stated rather than read off somebody appearing on the call, because a host that infers
 success cannot tell "reached" from "still ringing". `cancelled` is the dialler calling the dial off
 before anyone answered -- the agent hanging up while a consult still rings -- which is not a
-`no-answer` the destination never gave. `unexplained` is the switch dropping the call and giving no
-cause: a statement about the switch, sent instead of the nearest cause it did not give. `reason` is
-the switch's own words, optional, and shown to the agent attributed to the switch rather than to
-Omni.
+`no-answer` the destination never gave. `unexplained` is the switch dropping the call with no cause among
+those named here: a statement about the switch, sent instead of the nearest cause it did not give.
+`reason` is the switch's own words, optional, and shown to the agent attributed to the switch rather
+than to Omni. The two are different things and may travel together: a switch can say "could not
+create dialog" in words and still name no cause a code would carry, so `unexplained` with a
+`reason` is a dial the switch described but did not classify, and a desk renders the words without
+inventing the class.
 
 **`taskId` is the task the dial was placed on**, resolved from the dial's own identity and never from
 whatever task the agent is looking at when the outcome arrives. That task may already have ended,
@@ -2832,7 +2837,8 @@ knows the room:
 const onCall: OnCall[] = [
   { role: "party", since: "2026-08-21T09:12:00Z" },
   { role: "agent", userId: "A-12", since: "2026-08-21T09:12:04Z" },
-  { role: "conferenced", destination: "+14155550111", dialId: "dial-7f2", held: true, since: "2026-08-21T09:15:30Z" },
+  { role: "conferenced", destination: "+14155550111", dialId: "dial-7f2", stage: "joined", held: true, since: "2026-08-21T09:15:30Z" },
+  { role: "conferenced", destination: "+14155550199", dialId: "dial-3c9", stage: "ringing", since: "2026-08-21T09:16:02Z" },
 ];
 ```
 
@@ -2847,9 +2853,19 @@ never saw.
 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
 `cancelled` exists for. Consult and conference behave alike here: the `consulted` or `conferenced`
-entry appears with its `dialId` when the dial is placed, whether it has answered is the
-`dial-outcome`'s to say, and a `conference` `remove` naming a still-ringing `destination` calls that
-dial off, with `cancelled` as its outcome. A consult destination that never answers is a dial that
+entry appears with its `dialId` when the dial is placed, and a `conference` `remove` naming a
+still-ringing `destination` calls that dial off, with `cancelled` as its outcome.
+
+**The entry says where it stands.** A dialled entry carries `stage`: `ringing` until its dial is
+answered, `joined` after. The `dial-outcome` is the transition and the stage is the state, the same
+pairing as `task-media-started` and `media`: an `answered` outcome and the task restated with the
+entry `joined` say one thing twice, and any other outcome removes the entry. The outcome comes
+first: a `task-updated` that itself moves an entry from `ringing` to `joined` before an `answered`
+outcome for its dial is refused (`stream.taskUpdated.stage`), as an update that moves `media` is. It is stated rather
+than left to whoever placed the dial because that knowledge lives in one process: after a reload,
+on a second session, or on a supervisor's screen the snapshot is the only source, and a room that
+cannot tell ringing from joined says it contains someone who may never arrive. Nobody ringing is
+held (`task.onCall.held.ringing`). A consult destination that never answers is a dial that
 ended: the provider returns the task to `in-progress` with no `consulted` entry, as **Consult
 transfer** states, so the customer is never left parked by a conforming provider.
 

package/package.json

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