@xema/omni-protocol 0.1.44 → 0.1.45

package/README.md

@@ -99,12 +99,12 @@ const task = {
 
 **Switch on `command.action` with no `default`.** A `default` turns a future action into whatever
 the default does, silently; naming every arm means dropping one fails the build — indirectly, as a
-missing return — and keeps the narrowing that lets you read `destination` without a cast.
+missing return — and keeps the narrowing that lets you read `destinationId` without a cast.
 
 ```ts
 switch (command.action) {
-  case "cold":     return coldTransfer(command.destination);
-  case "warm":     return warmTransfer(command.destination);
+  case "cold":     return coldTransfer(command.destinationId);
+  case "warm":     return warmTransfer(command.destinationId);
   case "complete": return completeWarmTransfer();
   case "cancel":   return cancelWarmTransfer();
 }

package/dist/index.d.ts

@@ -409,16 +409,18 @@ export interface DispositionRules {
     notes?: "required" | "optional" | "none";
     codes?: DispositionCode[];
 }
+/**
+ * One item the queue configured for the agent to send a contact to: a button or a menu item. The
+ * protocol does not say what it does -- a queue, a menu, a line -- the provider executes it when a
+ * command names its `id`. Never a named agent: who takes a contact next is the queue's decision.
+ */
 export interface Destination {
     id: string;
     label: string;
-    address: string;
-    /** `agent` here is a routing target, not the person signed in. */
-    kind: "queue" | "agent" | "external";
 }
+/** The items a transfer or conference control offers. Nothing is typed; the agent picks one. */
 export interface DestinationDirectory {
-    destinations?: Destination[];
-    allowManualEntry: boolean;
+    destinations: Destination[];
 }
 export interface CustomCapability {
     id: string;
@@ -451,12 +453,12 @@ export type TaskCapabilities<C extends Channel = Channel> = C extends "voice" ?
     agentDisconnect?: Lockable<true>;
     /** Connect back to the party while `completing`, whoever placed the call; the task returns to `in-progress`. */
     connectBack?: Lockable<true>;
-    coldTransfer?: Lockable<true | DestinationDirectory>;
+    coldTransfer?: Lockable<DestinationDirectory>;
     /** Park the customer and call a destination first; then `complete` or `cancel`. */
-    warmTransfer?: Lockable<true | DestinationDirectory>;
+    warmTransfer?: Lockable<DestinationDirectory>;
     /** Ask a lead to join this call, with a note. The lead's decision arrives on `Task.leadAssist`. */
     leadAssist?: Lockable<true>;
-    conference?: Lockable<true | DestinationDirectory>;
+    conference?: Lockable<DestinationDirectory>;
     recording?: Lockable<true>;
 } : C extends "chat" ? SharedTaskCapabilities & {
     decline?: Lockable<true>;
@@ -561,10 +563,10 @@ export interface TaskHandlingStep {
     at: IsoTimestamp;
     /**
      * On a step that dialled -- `transferred`, `conferenced`, `unanswered` -- the host's identity for
-     * that dial when a host placed it, and the address it went to. Neither belongs on any other step.
+     * that dial when a host placed it, and the directory item it went to. Neither belongs on any other step.
      */
     dialId?: DialId;
-    destination?: string;
+    destinationId?: string;
     /**
      * Reported, never derived. An entry may be written while its leg is still running, so there is
      * no end to subtract from -- and omitted is the honest report of that, where nought would
@@ -616,7 +618,7 @@ export type OnCall = {
     userId: UserId;
 } | {
     role: "consulted" | "conferenced";
-    destination: string;
+    destinationId: string;
     stage: OnCallStage;
     dialId?: DialId;
     label?: string;
@@ -751,7 +753,7 @@ export type TaskOutcome = {
     by: "agent" | "provider";
 } | {
     type: "transferred";
-    destination?: string;
+    destinationId?: string;
 } | {
     type: "cancelled";
     reason?: string;
@@ -802,19 +804,19 @@ export type VoiceTaskCommand = {
     type: "connect-back";
     dialId: DialId;
 }
-/** Cold: hand the customer to `destination` with nobody spoken to first. Gated by `coldTransfer`. */
+/** Cold: hand the customer to the directory item `destinationId` with nobody spoken to first. Gated by `coldTransfer`. */
  | {
     type: "transfer";
     action: "cold";
     dialId: DialId;
-    destination: string;
+    destinationId: string;
 }
-/** Warm: park the customer and call `destination` first. Gated by `warmTransfer`. */
+/** Warm: park the customer and call the directory item `destinationId` first. Gated by `warmTransfer`. */
  | {
     type: "transfer";
     action: "warm";
     dialId: DialId;
-    destination: string;
+    destinationId: string;
 }
 /** Hand the customer to the consulted destination and leave. Needs a `consulted` entry on `Task.onCall`. */
  | {
@@ -847,18 +849,18 @@ export type VoiceTaskCommand = {
     type: "lead-assist";
     action: "leave";
 }
-/** Dial `destination` into the call. Gated by `conference`. */
+/** Dial the directory item `destinationId` into the call. Gated by `conference`. */
  | {
     type: "conference";
     action: "add";
     dialId: DialId;
-    destination: string;
+    destinationId: string;
 }
-/** Drop the `conferenced` entry on `Task.onCall` with this destination; while it still rings, this calls the dial off. */
+/** Drop the `conferenced` entry on `Task.onCall` with this `destinationId`; while it still rings, this calls the dial off. */
  | {
     type: "conference";
     action: "remove";
-    destination: string;
+    destinationId: string;
 } | {
     type: "recording";
     action: "start" | "pause" | "resume" | "stop";
@@ -1296,7 +1298,7 @@ export type ProviderEvent<C extends Channel = Channel> = {
     dialId: DialId;
     outcome: DialOutcome;
     taskId?: TaskId;
-    destination?: string;
+    destinationId?: string;
     reason?: string;
 } | {
     type: "announcement";
@@ -1443,7 +1445,7 @@ export declare const taskKey: (providerId: string, taskId: TaskId) => string;
 export declare const userKey: (providerId: string, userId: UserId) => string;
 /** Every handling step somebody takes part in. `queued` is the one nobody does. */
 export declare const HANDLING_STEPS_WITH_A_PERSON: readonly ["offered", "answered", "held", "muted", "transferred", "conferenced", "unanswered"];
-/** The steps a dial writes, and so the only ones that carry a `dialId` and a `destination`. */
+/** The steps a dial writes, and so the only ones that carry a `dialId` and a `destinationId`. */
 export declare const HANDLING_STEPS_THAT_DIAL: readonly ["transferred", "conferenced", "unanswered"];
 export declare const handlingStepDials: (step: HandlingStep) => boolean;
 /** Whether an absent `by` means "could not attribute" rather than "nobody was involved". */

package/dist/index.js

@@ -157,7 +157,7 @@ export const userKey = (providerId, userId) => `${encodeURIComponent(providerId)
 export const HANDLING_STEPS_WITH_A_PERSON = [
     "offered", "answered", "held", "muted", "transferred", "conferenced", "unanswered",
 ];
-/** The steps a dial writes, and so the only ones that carry a `dialId` and a `destination`. */
+/** The steps a dial writes, and so the only ones that carry a `dialId` and a `destinationId`. */
 export const HANDLING_STEPS_THAT_DIAL = ["transferred", "conferenced", "unanswered"];
 export const handlingStepDials = (step) => HANDLING_STEPS_THAT_DIAL.includes(step);
 // Pinned both ways: a step added to `HandlingStep` has to be placed here, and a step listed here

package/dist/validation.js

@@ -58,7 +58,6 @@ const TEAM_AVAILABILITIES = membersOf({
 const HANDLING_STEPS = membersOf({
     queued: true, offered: true, answered: true, held: true, muted: true, transferred: true, conferenced: true, unanswered: true,
 });
-const DESTINATION_KINDS = membersOf({ queue: true, agent: true, external: true });
 const CUSTOM_UI_CONTROLS = membersOf({ button: true, toggle: true, "menu-item": true });
 const CUSTOM_UI_PLACEMENTS = membersOf({ primary: true, secondary: true, overflow: true });
 const NOTES_RULES = membersOf({ required: true, optional: true, none: true });
@@ -418,23 +417,18 @@ export function validateManifest(manifest, path = "manifest") {
 // Task.
 // ---------------------------------------------------------------------------
 function validateDestinationDirectory(value, path, into) {
-    if (value === true)
-        return;
     if (!isPlainObject(value)) {
-        into.add("task.destinations.shape", path, "must be true or a destination directory");
+        into.add("task.destinations.shape", path, "a transfer or conference control carries the directory it offers: { destinations: [...] }");
         return;
     }
-    into.require(typeof value.allowManualEntry === "boolean", "task.destinations.allowManualEntry", `${path}.allowManualEntry`, "a directory must say whether manual entry is allowed");
-    // A directory with nothing in it and no typing is a control with nothing to offer.
-    if (value.allowManualEntry === false && !(Array.isArray(value.destinations) && value.destinations.length > 0)) {
-        into.add("task.destinations.offer", path, "a directory with no destinations must allow manual entry, or the control has nothing to offer");
-    }
-    if (value.destinations === undefined)
-        return;
     if (!Array.isArray(value.destinations)) {
-        into.add("task.destinations.list", `${path}.destinations`, "destinations must be an array when present");
+        into.add("task.destinations.list", `${path}.destinations`, "destinations must be an array");
         return;
     }
+    // Nothing is typed, so a directory with nothing in it is a control with nothing to offer.
+    if (value.destinations.length === 0) {
+        into.add("task.destinations.offer", path, "a directory offers at least one item; with none, omit the capability");
+    }
     const seen = new Set();
     value.destinations.forEach((destination, index) => {
         const at = `${path}.destinations[${index}]`;
@@ -448,8 +442,6 @@ function validateDestinationDirectory(value, path, into) {
             seen.add(destination.id);
         }
         into.filled(destination.label, "task.destination.label", `${at}.label`, "a destination needs a label");
-        into.filled(destination.address, "task.destination.address", `${at}.address`, "a destination needs an address");
-        into.oneOf(destination.kind, DESTINATION_KINDS, "task.destination.kind", `${at}.kind`);
     });
 }
 function validateDispositions(value, path, into) {
@@ -724,7 +716,7 @@ function validateHandlingHistory(value, path, into) {
         }
         // A step that dialled says where to and, when a host placed it, which dial; no other step dialled.
         const dialled = typeof entry.step === "string" && HANDLING_STEPS_THAT_DIAL.includes(entry.step);
-        for (const field of ["dialId", "destination"]) {
+        for (const field of ["dialId", "destinationId"]) {
             if (entry[field] === undefined)
                 continue;
             if (into.filled(entry[field], `task.handlingHistory.${field}`, `${at}.${field}`, `${field} must not be empty when present`)) {
@@ -780,7 +772,7 @@ function validateOnCall(value, channel, path, into) {
             into.require(entry.userId === undefined, "task.onCall.userId.unexpected", `${at}.userId`, `a ${role} is not named by a user id`);
         }
         if (role === "consulted" || role === "conferenced") {
-            into.filled(entry.destination, "task.onCall.destination", `${at}.destination`, `a ${role} entry names the destination that was dialled`);
+            into.filled(entry.destinationId, "task.onCall.destinationId", `${at}.destinationId`, `a ${role} entry names the directory item 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");
@@ -791,7 +783,7 @@ function validateOnCall(value, channel, path, into) {
                 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", "stage"]) {
+            for (const field of ["destinationId", "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`);
             }
         }
@@ -1297,8 +1289,8 @@ function validateTaskOutcome(value, path, into) {
             into.oneOf(value.by, COMPLETED_BY, "event.taskEnded.outcome.completed", `${path}.by`);
             break;
         case "transferred":
-            if (value.destination !== undefined) {
-                into.filled(value.destination, "event.taskEnded.outcome.transferred", `${path}.destination`, "a destination must not be empty when present");
+            if (value.destinationId !== undefined) {
+                into.filled(value.destinationId, "event.taskEnded.outcome.transferred", `${path}.destinationId`, "a destinationId must not be empty when present");
             }
             break;
         case "cancelled":
@@ -1433,8 +1425,8 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             }
             if (event.taskId !== undefined)
                 into.require(isTaskId(event.taskId), "event.dialOutcome.taskId", `${at}.taskId`, "taskId must be a task id when present");
-            if (event.destination !== undefined)
-                into.filled(event.destination, "event.dialOutcome.destination", `${at}.destination`, "a destination must not be empty when present");
+            if (event.destinationId !== undefined)
+                into.filled(event.destinationId, "event.dialOutcome.destinationId", `${at}.destinationId`, "a destinationId must not be empty when present");
             if (event.reason !== undefined)
                 into.filled(event.reason, "event.dialOutcome.reason", `${at}.reason`, "a reason must not be empty when present");
             break;

package/guide.md

@@ -20,7 +20,7 @@ are used precisely throughout and mean nothing looser here.
 | **Host** | Omni, named that way where the contrast with a provider is the point — *the host carries the audio*, *host-side input*. |
 | **Provider** | One independently connected external system: a voice platform, a chat platform, a mail platform. |
 | **Adapter** | The package implementing this contract for one provider. One adapter is one provider, so the words are often interchangeable; *provider* names the system, *adapter* the code speaking for it. |
-| **Agent** | The person signed in and taking work. Not to be confused with a transfer destination whose `kind` is `agent`, which is a routing target. |
+| **Agent** | The person signed in and taking work. On `onCall`, `agent` is a person on the call by user id; a transfer never names one, since a contact goes back to a queue. |
 | **Lead** | An agent whose login declares `capabilities.team`. The provider publishes a `TeamRoster` to them and to nobody else: **the login is the permission**. |
 | **Provisioning** | Omni-side policy about this agent, configured outside the protocol and never sent to a provider. It gates whether an offer may be rejected, whether the agent goes ready on login, and whether tasks are auto-accepted. Where a capability and provisioning disagree, the stricter wins. |
 | **Task** | One unit of assigned work — a call, a chat, a mail. |
@@ -447,13 +447,10 @@ type DispositionRules = {
 type Destination = {
   id: string;
   label: string;
-  address: string;
-  kind: "queue" | "agent" | "external";
 };
 
 type DestinationDirectory = {
-  destinations?: Destination[];
-  allowManualEntry: boolean;
+  destinations: Destination[];
 };
 
 type CustomCapability = {
@@ -481,10 +478,10 @@ type TaskCapabilities<C extends Channel = Channel> =
         hold?: Lockable<true>;
         agentDisconnect?: Lockable<true>;
         connectBack?: Lockable<true>;
-        coldTransfer?: Lockable<true | DestinationDirectory>;
-        warmTransfer?: Lockable<true | DestinationDirectory>;
+        coldTransfer?: Lockable<DestinationDirectory>;
+        warmTransfer?: Lockable<DestinationDirectory>;
         leadAssist?: Lockable<true>;
-        conference?: Lockable<true | DestinationDirectory>;
+        conference?: Lockable<DestinationDirectory>;
         recording?: Lockable<true>;
       }
     : C extends "chat"
@@ -582,7 +579,7 @@ type TaskHandlingStep = {
   step: HandlingStep;
   at: IsoTimestamp;
   dialId?: DialId;
-  destination?: string;
+  destinationId?: string;
   seconds?: DurationSeconds;
   by?: UserId;
 };
@@ -598,7 +595,7 @@ type OnCallStage = "ringing" | "joined";
 type OnCall = { since: IsoTimestamp; held?: true } & (
   | { role: "party" }
   | { role: "agent"; userId: UserId }
-  | { role: "consulted" | "conferenced"; destination: string; stage: OnCallStage; dialId?: DialId; label?: string }
+  | { role: "consulted" | "conferenced"; destinationId: string; stage: OnCallStage; dialId?: DialId; label?: string }
 );
 
 type TaskLeadAssist = {
@@ -667,7 +664,7 @@ type AcceptanceMode =
 
 type TaskOutcome =
   | { type: "completed"; by: "agent" | "provider" }
-  | { type: "transferred"; destination?: string }
+  | { type: "transferred"; destinationId?: string }
   | { type: "cancelled"; reason?: string }
   | { type: "expired"; phase: "pending" | "confirmed" | "preview" }
   | { type: "left" }
@@ -711,16 +708,16 @@ type VoiceTaskCommand =
   | { type: "resume" }
   | { type: "disconnect" }
   | { type: "connect-back"; dialId: DialId }
-  | { type: "transfer"; action: "cold"; dialId: DialId; destination: string }
-  | { type: "transfer"; action: "warm"; dialId: DialId; destination: string }
+  | { type: "transfer"; action: "cold"; dialId: DialId; destinationId: string }
+  | { type: "transfer"; action: "warm"; dialId: DialId; destinationId: string }
   | { type: "transfer"; action: "complete" }
   | { type: "transfer"; action: "cancel" }
   | { type: "lead-assist"; action: "request"; note?: string }
   | { type: "lead-assist"; action: "cancel" }
   | { type: "lead-assist"; action: "take-over" }
   | { type: "lead-assist"; action: "leave" }
-  | { type: "conference"; action: "add"; dialId: DialId; destination: string }
-  | { type: "conference"; action: "remove"; destination: string }
+  | { type: "conference"; action: "add"; dialId: DialId; destinationId: string }
+  | { type: "conference"; action: "remove"; destinationId: string }
   | { type: "recording"; action: "start" | "pause" | "resume" | "stop" }
   | ({ type: "complete" } & DispositionPayload);
 
@@ -1006,7 +1003,7 @@ type ProviderEvent =
   | { type: "task-media-started"; taskId: TaskId }
   | { type: "task-media-ended"; taskId: TaskId }
   | { type: "task-ended"; taskId: TaskId; outcome: TaskOutcome }
-  | { type: "dial-outcome"; dialId: DialId; outcome: DialOutcome; taskId?: TaskId; destination?: string; reason?: string }
+  | { type: "dial-outcome"; dialId: DialId; outcome: DialOutcome; taskId?: TaskId; destinationId?: string; reason?: string }
   | { type: "announcement"; text: string; html?: string; announcedAt: IsoTimestamp; expiresAt?: IsoTimestamp }
   | { type: "queue-summary"; summary: QueueSummary }
   | { type: "diagnostic"; expected: string; observed: string; taskId?: TaskId }
@@ -2161,7 +2158,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, 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**. |
+| `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 `destinationId` 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**. |
 | `leadAssist` | 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 **Lead assist**. |
 | `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-assist` `take-over` and `leave` issuable. See **Lead assist**. |
 | `monitoring` | Voice only, on the lead's own task while they listen to a member's call: whose call, which call, and the `mode` they are heard in, restated on every change. Never on the member's task, and never together with `assisting`. See **Monitoring a call**. |
@@ -2414,7 +2411,7 @@ executes** — so without a step the provider, which alone keeps the task's reco
 account of a period the agent could not be heard.
 
 **A step that dialled says which dial and where.** `transferred`, `conferenced` and `unanswered`
-each end a dial, so the entry carries the `destination` it went to and, where a host placed it, the
+each end a dial, so the entry carries the `destinationId` it went to and, where a host placed it, the
 `dialId` the host minted; no other step dialled, and either field on one is refused
 (`task.handlingHistory.dialId.unexpected`). This is how a dial made before a transfer is placeable
 by whoever holds the task now: a `dial-outcome` naming a `dialId` the host never minted is looked
@@ -2674,9 +2671,9 @@ the provider published none.
 ```ts
 capabilities: {
   coldTransfer: {
-    allowManualEntry: false,
     destinations: [
-      { id: "tier2", label: "Tier 2 support", address: "+14155550111", kind: "queue" },
+      { id: "tier2", label: "Tier 2 support" },
+      { id: "main-menu", label: "Back to the main menu" },
     ],
   },
 }
@@ -2684,22 +2681,23 @@ capabilities: {
 
 | Field | Contract |
 | --- | --- |
-| `destinations` | Directory Omni renders, with unique `id` values. |
-| `address` | The value Omni sends as `destination` on a `transfer` or a `conference` command. |
-| `kind` | Where the contact is going. See below. |
-| `allowManualEntry` | Whether the agent may type a destination that is not in the directory. A directory with no destinations must allow manual entry, or the control has nothing to offer. |
-
-`kind` says who receives the contact and whether this provider still holds it afterwards:
-
-| Kind | What it means |
-| --- | --- |
-| `queue` | A routing point on this provider. Whoever is next takes it, nobody is named, and the provider keeps the contact. |
-| `agent` | One named person on this provider. The provider keeps the contact and knows who has it. |
-| `external` | An address outside this provider — another platform, a PSTN number, a partner's line. The contact leaves, and the provider generally stops being able to report on it. |
-
-A destination the agent types is not in the directory and has no `kind`. Omni treats it as
-`external` unless the provider says otherwise in its response, because that is the assumption that
-does not overstate what the provider can still see.
+| `destinations` | The items the control offers, at least one, with unique `id` values. Each is a button or a menu item on the desk. |
+| `id` | What Omni sends as `destinationId` on a `transfer` or `conference` command, and what the provider executes. |
+| `label` | What the agent reads. |
+
+**The protocol does not say what an item does.** A queue, an IVR menu, an outside line, a
+skill group -- that is the queue's configuration and the provider's business. The agent sees a
+list of labels, picks one, and Omni sends its `id`; the provider executes whatever the item is. No
+kind travels, nothing is typed, and a control with an empty directory has nothing to offer and is
+refused (`task.destinations.offer`). A control declared as bare `true` is refused for the same
+reason (`task.destinations.shape`): once nothing is typed, the directory is the control.
+
+**An agent never transfers to a named agent**, warm or cold. A contact that needs another pair of
+hands goes back to a queue or a menu the queue configured, and who takes it next is the queue's
+decision: routing by skill, availability and fairness is what the queue is for, and a hand-off to a
+chosen colleague bypasses all three. The desk shows no agent picker and no dial pad on a transfer.
+The one way a named person ends up with an agent's call is a lead taking it over through lead
+assist, which is the lead's act, not a transfer the agent chose.
 
 #### Warm transfer
 
@@ -2713,7 +2711,7 @@ offer any of the three without the others, and each is declared on its own.
 // 1. Warm. A dial: the provider parks the customer and calls the destination, answers
 //    `dialling`, and the task reports `paused` with the destination `consulted` on `onCall`
 //    while the call to it stands.
-{ type: "transfer", action: "warm", dialId: "dial-7f2", destination: "+14155550111" }
+{ type: "transfer", action: "warm", dialId: "dial-7f2", destinationId: "tier2" }
 
 // 2a. Hand the customer to the consulted destination and leave.
 { type: "transfer", action: "complete" }
@@ -2722,7 +2720,7 @@ offer any of the three without the others, and each is declared on its own.
 { type: "transfer", action: "cancel" }
 ```
 
-`warm` is gated by the `warmTransfer` capability and takes a destination exactly as a cold
+`warm` is gated by the `warmTransfer` capability and names a directory item exactly as a cold
 transfer does, from the same kind of directory. It is a dial, so it carries the host's `dialId`
 and is answered `dialling`, and its `dial-outcome` says whether the destination was reached. While
 the destination is on the line the task carries a `consulted` entry on `onCall`, and that presence
@@ -2832,16 +2830,16 @@ declare const connection: Connection<"voice">;
 declare const taskId: TaskId;
 
 // 1. Out, minted by the host.
-const result = await connection.execute({ taskId, command: { type: "conference", action: "add", dialId: "dial-7f2", destination: "+14155550111" } });
+const result = await connection.execute({ taskId, command: { type: "conference", action: "add", dialId: "dial-7f2", destinationId: "tier2" } });
 
 // 2. Back on the result, restated, so the host compares and confirms.
 expect(result).toEqual({ status: "dialling", dialId: "dial-7f2" });
 
 // 3. On the outcome, however late, against the task it belonged to.
-const outcome: ProviderEvent<"voice"> = { type: "dial-outcome", dialId: "dial-7f2", taskId, destination: "+14155550111", outcome: "no-answer", reason: "No route to destination" };
+const outcome: ProviderEvent<"voice"> = { type: "dial-outcome", dialId: "dial-7f2", taskId, destinationId: "tier2", outcome: "no-answer", reason: "No route to destination" };
 
 // 4. In the record, so a dial made before a transfer is placeable by whoever holds the task now.
-const step: TaskHandlingStep = { step: "unanswered", at: "2026-08-21T09:15:30Z", by: "A-12", dialId: "dial-7f2", destination: "+14155550111" };
+const step: TaskHandlingStep = { step: "unanswered", at: "2026-08-21T09:15:30Z", by: "A-12", dialId: "dial-7f2", destinationId: "tier2" };
 ```
 
 The identity is a correlation handle between host and provider and **is never shown to the
@@ -2857,7 +2855,7 @@ nothing, is refused (`result.status`). `validateResult(result, method, path, dia
 `dialId` the host sent for that reason.
 
 **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
+there was one, the directory item it went to where there was one, and how the dial ended -- from a closed
 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
@@ -2910,15 +2908,15 @@ 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", 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" },
+  { role: "conferenced", destinationId: "tier2", dialId: "dial-7f2", stage: "joined", held: true, since: "2026-08-21T09:15:30Z" },
+  { role: "conferenced", destinationId: "main-menu", dialId: "dial-3c9", stage: "ringing", since: "2026-08-21T09:16:02Z" },
 ];
 ```
 
 `party` is the customer and `agent` a person by user id; neither was dialled from anywhere, so
-neither carries a destination. `consulted` and `conferenced` were, so both carry the `destination`
-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
+neither carries a destination. `consulted` and `conferenced` were, so both carry the
+`destinationId` of the directory item 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.
 
@@ -2927,7 +2925,7 @@ what makes `transfer` `cancel` issuable and what `conference` `remove` names, an
 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.
+still-ringing `destinationId` 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
@@ -3806,7 +3804,7 @@ react rather than only display the message:
 | `omni.not-authenticated` | The provider session is no longer usable. The adapter has published `expired` at or before this answer — the state is what Omni surfaces reauthentication from; the code says why this action failed, and is never the only signal. |
 | `omni.capability-not-enabled` | The action targets a capability this task, manifest, or login did not declare — including a lead command from a login whose `capabilities` no longer carry it. |
 | `omni.task-not-found` | The provider-local task id is unknown, typically after the task already ended. |
-| `omni.destination-not-permitted` | The dial or transfer destination violates the provider's policy. |
+| `omni.destination-not-permitted` | The dialled number, or the `destinationId` named, is not one the provider offers this agent. |
 | `omni.rate-limited` | The action was throttled. Pair with `retryAfterMs`. |
 | `omni.unavailable` | The provider is temporarily unable to serve the action, including any command sent while `transport-status` is not `active`. |
 | `omni.break-already-committed` | Cancellation lost the commit/cancel race; Omni must finish commit recovery. |

package/package.json

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