@xema/omni-protocol 0.1.34 → 0.1.36

package/dist/index.d.ts

@@ -77,11 +77,13 @@ export interface DialCapability {
 /**
  * How a dial ended, as the switch distinguishes it. `answered` is the one success; the rest are
  * the ways a destination was not reached -- `cancelled` because the dialler called it off before
- * anyone answered, not because the destination failed to. A manifest declares which of these its
- * platform can tell apart (`dialOutcomes`), and a `dial-outcome` carries only a declared one.
+ * anyone answered, not because the destination failed to, and `unexplained` because the switch
+ * dropped the call and gave no cause, a statement about the switch rather than a shrug from the
+ * adapter. A manifest declares which of these its platform can tell apart (`dialOutcomes`), and a
+ * `dial-outcome` carries only a declared one.
  */
-export type DialOutcome = "answered" | "busy" | "no-answer" | "unreachable" | "rejected" | "cancelled";
-export declare const DIAL_OUTCOMES: readonly ["answered", "busy", "no-answer", "unreachable", "rejected", "cancelled"];
+export type DialOutcome = "answered" | "busy" | "no-answer" | "unreachable" | "rejected" | "cancelled" | "unexplained";
+export declare const DIAL_OUTCOMES: readonly ["answered", "busy", "no-answer", "unreachable", "rejected", "cancelled", "unexplained"];
 /** Every idle capability a provider may declare. Only voice may `dial`; the channel arm says so. */
 export declare const IDLE_CAPABILITIES: readonly ["dial", "personalBrowser", "calendar", "contacts"];
 export type IdleCapability = (typeof IDLE_CAPABILITIES)[number];
@@ -574,13 +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 right now, 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 brought in, carrying the dial when a host placed it and the address
- * either way. `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.
+ * 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, 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;
@@ -593,6 +600,7 @@ export type OnCall = {
 } | {
     role: "consulted" | "conferenced";
     destination: string;
+    stage: OnCallStage;
     dialId?: DialId;
     label?: string;
 });
@@ -804,7 +812,7 @@ export type VoiceTaskCommand = {
     dialId: DialId;
     destination: string;
 }
-/** Drop the `conferenced` entry on `Task.onCall` with this destination. */
+/** Drop the `conferenced` entry on `Task.onCall` with this destination; while it still rings, this calls the dial off. */
  | {
     type: "conference";
     action: "remove";

package/dist/index.js

@@ -15,7 +15,7 @@ export function negotiateProtocolVersion(adapterVersions, hostVersions = OMNI_SU
     const shared = adapterVersions.filter(version => host.has(version));
     return shared.length === 0 ? undefined : Math.max(...shared);
 }
-export const DIAL_OUTCOMES = ["answered", "busy", "no-answer", "unreachable", "rejected", "cancelled"];
+export const DIAL_OUTCOMES = ["answered", "busy", "no-answer", "unreachable", "rejected", "cancelled", "unexplained"];
 /** Every idle capability a provider may declare. Only voice may `dial`; the channel arm says so. */
 export const IDLE_CAPABILITIES = ["dial", "personalBrowser", "calendar", "contacts"];
 /** What Omni calls each idle capability. */

package/dist/validation.js

@@ -67,8 +67,11 @@ const ACCESS_APPLIES_TO = membersOf({
     "initial-url": true, "all-navigation": true,
 });
 const DIAL_DESTINATION_POLICIES = membersOf({ "contacts-only": true, "any-number": true });
-const DIAL_OUTCOMES = membersOf({ answered: true, busy: true, "no-answer": true, unreachable: true, rejected: true, cancelled: true });
+const DIAL_OUTCOMES = membersOf({ answered: true, busy: true, "no-answer": true, unreachable: true, rejected: true, cancelled: true, unexplained: 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({
@@ -297,6 +300,11 @@ function validateDialOutcomes(manifest, path, into) {
     });
     into.require(declared.includes("answered"), "manifest.dialOutcomes.answered", path, "a dial that reached its destination is stated, never inferred: dialOutcomes includes answered");
     into.require(declared.some((outcome) => outcome !== "answered"), "manifest.dialOutcomes.failure", path, "a provider that can only say answered can never say a destination was not reached: declare at least one other outcome");
+    // "The switch gave no cause" is honest only from a provider that reports the cause when there is
+    // one; declared alone it is the generic failure every unsure provider would send.
+    if (declared.includes("unexplained")) {
+        into.require(declared.some((outcome) => EXPLAINED_FAILURES.includes(outcome)), "manifest.dialOutcomes.unexplained.alone", path, "unexplained says the switch gave no cause, which is a claim only a provider that reports causes can make: declare at least one of busy, no-answer, unreachable, rejected, cancelled beside it");
+    }
 }
 /** Whether a manifest says how a dial ends, and so may publish tasks that dial. `undefined` where there is no manifest to ask. */
 function manifestDials(manifest) {
@@ -771,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

@@ -36,7 +36,7 @@ are used precisely throughout and mean nothing looser here.
 | **Break** | A reported, supervised state in which the agent is not working — one with a reason, a decision behind it and a return. It covers what a platform may call *not-ready*, including equipment trouble. An agent who is merely at capacity is not on a break. |
 | **Workspace** | What Omni shows the agent. The **task workspace** holds the selected task, its controls and its browsers; the **idle workspace** holds what a provider contributes when no task is selected — dialpad, contacts, calendar, roster. |
 | **Dial** | One outbound call the host asks a provider to place — from the idle dialpad, a transfer, a conference add, or a callback. Identified by the host's `dialId`, accepted as `dialling`, and ended by exactly one `dial-outcome`. See **Every dial has an outcome**. |
-| **On the call** | Who a voice task's audio joins right now, as the provider states it on `Task.onCall`: the party, the agents, and anyone consulted or conferenced in. |
+| **On the call** | Who a voice task's audio joins, or is bringing in, as the provider states it on `Task.onCall`: the party, the agents, and anyone consulted or conferenced in from the moment their dial is placed. |
 
 Six words describe *what state a thing is in*, and they are not interchangeable: each belongs to
 one thing, so a bare "status" in conversation is always the authentication session's, and a
@@ -165,7 +165,7 @@ type DialDestinations = "contacts-only" | "any-number";
 
 type DialCapability = { destinations: DialDestinations };
 
-type DialOutcome = "answered" | "busy" | "no-answer" | "unreachable" | "rejected" | "cancelled";
+type DialOutcome = "answered" | "busy" | "no-answer" | "unreachable" | "rejected" | "cancelled" | "unexplained";
 
 type IdleCapabilities<C extends Channel = Channel> = {
   personalBrowser?: PersonalBrowserCapability;
@@ -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 = {
@@ -1399,6 +1401,10 @@ export default defineAdapter({
 });
 ```
 
+`dialOutcomes` is a compile error off voice, as `dial` is. An adapter written once over
+`C extends Channel` therefore sets it the way it already sets `idleCapabilities`, with
+`as Pick<Manifest<C>, "dialOutcomes">`; an adapter written for one channel needs no cast.
+
 ### `Adapter.manifest`
 
 Static metadata that Omni can inspect before connecting.
@@ -2129,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 right now, 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 brought in -- 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**. |
 
@@ -2558,7 +2564,7 @@ const taskCapabilities = {
 | `blindTransfer` | Secondary menu item: Blind transfer | Omni may transfer the caller directly to a destination. |
 | `consultTransfer` | Secondary menu item: Consult transfer | Omni may park the customer and call a destination first, then hand the customer over or cancel back. See **Consult transfer**. |
 | `consultLead` | Secondary menu item: Consult lead | Omni may ask a lead to join this call, with a note. The lead's decision reaches the agent on `Task.lead`. See **Consulting a lead**. |
-| `conference` | Secondary button: Conference | Omni may dial a destination into the active call, and drop a `conferenced` entry from it. |
+| `conference` | Secondary button: Conference | Omni may dial a destination into the active call, and drop a `conferenced` entry from it -- one still ringing included, which calls the dial off. |
 | `recording` | Overflow menu item: Recording | Omni may expose start, pause, resume, and stop recording controls. |
 | `dispositions` | Primary button: Complete | Omni may request task disposal with a provider disposition and notes. |
 
@@ -2779,12 +2785,17 @@ nothing, is refused (`result.status`). `validateResult(result, method, path, dia
 
 **The outcome is stated, once, either way.** A `dial-outcome` names the `dialId`, the task where
 there was one, the destination where the provider knows it, and how the dial ended -- from a closed
-set: `answered`, `busy`, `no-answer`, `unreachable`, `rejected`, `cancelled`. `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. `reason` is the switch's own words, optional, and shown to the agent
-attributed to the switch rather than to Omni.
+set: `answered`, `busy`, `no-answer`, `unreachable`, `rejected`, `cancelled`, `unexplained`.
+`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 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,
@@ -2792,6 +2803,12 @@ and the harness places the outcome all the same (`TaskStream`, `stream.dialOutco
 `stream.dialOutcome.duplicate`); an agent who moved on still learns nobody was reached, against the
 call it belonged to and never against the next one.
 
+The stream knows a dial from three places: `TaskStream.dialled(dialId)`, which a host calls when it
+places one; an entry on a task's `onCall`; and a step in its `handlingHistory`. Since a dialled entry
+is listed from placement, `dialled()` is load-bearing only for a dial that never has an entry -- a
+blind transfer, a callback, an idle dialpad call -- or whose entry has already left the room; an
+outcome for a dial nobody placed and no task mentions is what `stream.dialOutcome.unknown` refuses.
+
 **`answered` says what happened to the dial; `onCall` says who is in the room.** They are two
 claims, and both are true at once when a leg answers and never joins. A desk shows `answered` as the
 dial's conclusion and says "on the call" only when the person appears on `Task.onCall`; the obvious
@@ -2802,7 +2819,11 @@ provider that cannot tell busy from unreachable must not pick one. The manifest
 `dialOutcomes`, and a `dial-outcome` carries only a declared member
 (`event.dialOutcome.undeclared`). The list includes `answered`, or the provider could never state a
 success (`manifest.dialOutcomes.answered`), and at least one other member, or it could never state
-a failure (`manifest.dialOutcomes.failure`). A provider that dials at all declares it: an idle
+a failure (`manifest.dialOutcomes.failure`). `unexplained` is declarable only beside a cause the
+provider does report -- `busy`, `no-answer`, `unreachable`, `rejected` or `cancelled`
+(`manifest.dialOutcomes.unexplained.alone`): a provider that reports causes may honestly say the
+switch gave none, while one that reports none would be sending the generic failure this set exists
+to refuse. A provider that dials at all declares it: an idle
 dialpad requires it (`manifest.dialOutcomes.required`), and a task that declares `callback`,
 `blindTransfer`, `consultTransfer` or `conference` under a manifest without it is refused
 (`task.capability.dialOutcomes.required`). Off voice nothing dials, and the field is a compile
@@ -2816,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" },
 ];
 ```
 
@@ -2825,7 +2847,25 @@ neither carries a destination. `consulted` and `conferenced` were, so both carry
 and, where a host's dial brought them, its `dialId`; a person the platform added itself carries
 none. `held: true` is presence as claim. A snapshot establishes state, so a host that attaches
 after a transfer reads the room from here rather than inferring it from a sequence of outcomes it
-never saw. A `conference` `remove` names the `destination` of the `conferenced` entry to drop.
+never saw.
+
+**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
+`cancelled` exists for. Consult and conference behave alike here: the `consulted` or `conferenced`
+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. 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.
 
 The desk shows a dial as placed on `dialling`, never as reached; shows the person in the room when
 they appear on `onCall`; and shows the outcome, with the switch's reason, against the call it

package/package.json

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