@xema/omni-protocol 0.1.43 → 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>;
@@ -512,10 +514,15 @@ export type TaskPhase =
 "pending"
 /** Accepted, and not yet started. */
  | "confirmed"
-/** Being made ready -- a preview the agent reads before the work begins. */
- | "preparing" | "in-progress" | "paused"
+/**
+ * Voice only: the customer's record is on the agent's screen and no call has gone out. The agent
+ * presses Call, or `previewEndsAt` arrives and `atDeadline` says what the system does instead.
+ */
+ | "preview" | "in-progress" | "paused"
 /** The work is over and the agent is finishing up. */
  | "completing";
+/** What the system does when a preview's deadline passes with no Call pressed. */
+export type PreviewDeadline = "calls" | "expires";
 /** Who ends the task: the agent issuing `complete`, or the provider deciding it is over. */
 export type CompletionMode = "agent-command" | "provider-automatic";
 export interface TaskAttributeBase {
@@ -556,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
@@ -611,7 +618,7 @@ export type OnCall = {
     userId: UserId;
 } | {
     role: "consulted" | "conferenced";
-    destination: string;
+    destinationId: string;
     stage: OnCallStage;
     dialId?: DialId;
     label?: string;
@@ -710,6 +717,13 @@ export type Task<C extends Channel = Channel> = {
      * (`autoAcceptTasks: true`), forbidden when it said not, and absent past `pending`.
      */
     acceptance?: AcceptanceMode;
+    /**
+     * In `preview` only, and together: when the system stops waiting for the agent to press Call,
+     * and what it does then -- `calls` places the call itself, `expires` takes the record back and
+     * the task ends `expired`. Absent, the agent has as long as they need.
+     */
+    previewEndsAt?: IsoTimestamp;
+    atDeadline?: PreviewDeadline;
     /** The identifier an agent reads back to a customer, where the provider has one. */
     reference?: string;
     attributes?: TaskAttribute[];
@@ -739,7 +753,7 @@ export type TaskOutcome = {
     by: "agent" | "provider";
 } | {
     type: "transferred";
-    destination?: string;
+    destinationId?: string;
 } | {
     type: "cancelled";
     reason?: string;
@@ -747,7 +761,7 @@ export type TaskOutcome = {
 /** Only the phases in which somebody is still being waited on can expire. */
  | {
     type: "expired";
-    phase: "pending" | "confirmed" | "preparing";
+    phase: "pending" | "confirmed" | "preview";
 }
 /** This agent left a call that continues without them: a lead who joined and dropped. */
  | {
@@ -757,7 +771,7 @@ export type TaskOutcome = {
     failure: ProtocolFailure;
 };
 export declare const TASK_COMMAND_NAMES: {
-    readonly voice: readonly ["answer", "decline", "start-call", "mute", "hold", "resume", "disconnect", "connect-back", "transfer", "lead-assist", "conference", "recording", "complete"];
+    readonly voice: readonly ["answer", "decline", "call", "mute", "hold", "resume", "disconnect", "connect-back", "transfer", "lead-assist", "conference", "recording", "complete"];
     readonly chat: readonly ["accept", "decline", "pause", "resume", "complete"];
     readonly email: readonly ["accept", "decline", "complete"];
 };
@@ -770,8 +784,11 @@ export type VoiceTaskCommand = {
     type: "answer";
 } | {
     type: "decline";
-} | {
-    type: "start-call";
+}
+/** In `preview`: place the call to the party whose record the agent has read. A dial, gated by the phase alone. */
+ | {
+    type: "call";
+    dialId: DialId;
 } | {
     type: "mute";
     muted: boolean;
@@ -787,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`. */
  | {
@@ -832,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";
@@ -1255,7 +1272,6 @@ export type ProviderEvent<C extends Channel = Channel> = {
     type: "task-offered";
     task: Task<C>;
     allocationExpiresAt?: IsoTimestamp;
-    preparationEndsAt?: IsoTimestamp;
 } | {
     type: "task-updated";
     task: Task<C>;
@@ -1282,7 +1298,7 @@ export type ProviderEvent<C extends Channel = Channel> = {
     dialId: DialId;
     outcome: DialOutcome;
     taskId?: TaskId;
-    destination?: string;
+    destinationId?: string;
     reason?: string;
 } | {
     type: "announcement";
@@ -1372,7 +1388,7 @@ export declare const DEFAULT_TASK_PHASE_LABELS: {
     readonly voice: {
         readonly pending: "Offered";
         readonly confirmed: "Accepted";
-        readonly preparing: "Preview";
+        readonly preview: "Preview";
         readonly "in-progress": "On Call";
         readonly paused: "On Hold";
         readonly completing: "After Call Work";
@@ -1380,7 +1396,7 @@ export declare const DEFAULT_TASK_PHASE_LABELS: {
     readonly chat: {
         readonly pending: "Incoming Chat";
         readonly confirmed: "Accepted";
-        readonly preparing: "Preparing";
+        readonly preview: "Preview";
         readonly "in-progress": "In Chat";
         readonly paused: "Paused";
         readonly completing: "Wrap-up";
@@ -1388,7 +1404,7 @@ export declare const DEFAULT_TASK_PHASE_LABELS: {
     readonly email: {
         readonly pending: "Assigned";
         readonly confirmed: "Accepted";
-        readonly preparing: "Reviewing";
+        readonly preview: "Preview";
         readonly "in-progress": "Working";
         readonly paused: "Paused";
         readonly completing: "Completing";
@@ -1429,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

@@ -71,14 +71,14 @@ export function effectiveLevels(declared) {
 // Task commands.
 // ---------------------------------------------------------------------------
 export const TASK_COMMAND_NAMES = {
-    voice: ["answer", "decline", "start-call", "mute", "hold", "resume", "disconnect",
+    voice: ["answer", "decline", "call", "mute", "hold", "resume", "disconnect",
         "connect-back", "transfer", "lead-assist", "conference", "recording", "complete"],
     chat: ["accept", "decline", "pause", "resume", "complete"],
     email: ["accept", "decline", "complete"],
 };
 /** The dial a command places, by the host's identity for it; `undefined` for a command that dials nothing. */
 export function commandDialId(command) {
-    if (command.type === "connect-back")
+    if (command.type === "connect-back" || command.type === "call")
         return command.dialId;
     if (command.type === "transfer" && (command.action === "cold" || command.action === "warm"))
         return command.dialId;
@@ -117,15 +117,15 @@ export function defineAdapter(adapter) {
 // ---------------------------------------------------------------------------
 export const DEFAULT_TASK_PHASE_LABELS = {
     voice: {
-        pending: "Offered", confirmed: "Accepted", preparing: "Preview",
+        pending: "Offered", confirmed: "Accepted", preview: "Preview",
         "in-progress": "On Call", paused: "On Hold", completing: "After Call Work",
     },
     chat: {
-        pending: "Incoming Chat", confirmed: "Accepted", preparing: "Preparing",
+        pending: "Incoming Chat", confirmed: "Accepted", preview: "Preview",
         "in-progress": "In Chat", paused: "Paused", completing: "Wrap-up",
     },
     email: {
-        pending: "Assigned", confirmed: "Accepted", preparing: "Reviewing",
+        pending: "Assigned", confirmed: "Accepted", preview: "Preview",
         "in-progress": "Working", paused: "Paused", completing: "Completing",
     },
 };
@@ -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

@@ -38,7 +38,7 @@ const membersOf = (members) => Object.keys(members);
 const CHANNELS = membersOf({ voice: true, chat: true, email: true });
 const TRANSPORT_RECOVERIES = membersOf({ reconnect: true, reauthenticate: true });
 const TASK_PHASES = membersOf({
-    pending: true, confirmed: true, preparing: true, "in-progress": true, paused: true, completing: true,
+    pending: true, confirmed: true, preview: true, "in-progress": true, paused: true, completing: true,
 });
 const COMPLETION_MODES = membersOf({ "agent-command": true, "provider-automatic": true });
 const ACCEPTANCE_MODES = membersOf({
@@ -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 });
@@ -82,13 +81,14 @@ const MEMBER_BREAKS = membersOf({
     "awaiting-decision": true, granted: true, "starting-after-task": true,
 });
 const OFFERABLE_PHASES = membersOf({
-    pending: true, confirmed: true, preparing: true,
+    pending: true, confirmed: true, preview: true,
 });
+const PREVIEW_DEADLINES = membersOf({ calls: true, expires: true });
 const TEAM_CAPABILITIES = membersOf({ breakControl: true, leadAssistControl: true, policyControl: true, monitorControl: true });
 const MONITOR_MODES = membersOf({ monitor: true, whisper: true, barge: true });
 const COMPLETED_BY = membersOf({ agent: true, provider: true });
 const EXPIRABLE_PHASES = membersOf({
-    pending: true, confirmed: true, preparing: true,
+    pending: true, confirmed: true, preview: true,
 });
 const ISOLATION_SCHEME_VALUES = Object.values(BROWSER_ISOLATION_SCHEMES);
 /** The capabilities each channel arm of `TaskCapabilities` declares, keyed off the type itself. */
@@ -417,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}]`;
@@ -447,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) {
@@ -723,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`)) {
@@ -779,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");
@@ -790,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`);
             }
         }
@@ -864,7 +857,28 @@ function validateTaskInto(task, context, path, into) {
     into.require(isTaskId(task.id), "task.id", `${path}.id`, "a task needs a non-empty id");
     into.filled(task.title, "task.title", `${path}.title`, "a task needs a title");
     into.filled(task.taskType, "task.taskType", `${path}.taskType`, "a task needs a task type");
-    into.oneOf(task.phase, TASK_PHASES, "task.phase", `${path}.phase`);
+    if (into.oneOf(task.phase, TASK_PHASES, "task.phase", `${path}.phase`) && task.phase === "preview") {
+        // A preview is a record waiting for the agent to press Call: only voice has a call to place,
+        // and pressing Call is a dial, so the manifest has to have said how a dial ends.
+        into.require(context.channel === "voice", "task.phase.channel", `${path}.phase`, `a ${context.channel} task has no call to preview`);
+        into.require(context.dialOutcomesDeclared !== false, "task.preview.dialOutcomes.required", `${path}.phase`, "a preview ends in the agent pressing Call, which dials, and the manifest declares no dialOutcomes to say how a dial ends");
+    }
+    // The deadline and what happens at it travel together, and only while the record is being previewed.
+    if (task.previewEndsAt !== undefined || task.atDeadline !== undefined) {
+        into.require(task.phase === "preview", "task.preview.deadline.unexpected", `${path}.previewEndsAt`, "previewEndsAt and atDeadline belong to a task in preview; past it there is nothing to wait for");
+        if (task.previewEndsAt === undefined) {
+            into.add("task.preview.previewEndsAt.required", `${path}.previewEndsAt`, "atDeadline says what happens at a deadline, so there has to be one");
+        }
+        else {
+            into.timestamp(task.previewEndsAt, "task.preview.previewEndsAt", `${path}.previewEndsAt`);
+        }
+        if (task.atDeadline === undefined) {
+            into.add("task.preview.atDeadline.required", `${path}.atDeadline`, "a preview with a deadline says what the system does at it: calls, or expires -- an agent counting down has to know which");
+        }
+        else {
+            into.oneOf(task.atDeadline, PREVIEW_DEADLINES, "task.preview.atDeadline", `${path}.atDeadline`);
+        }
+    }
     // Acceptance is the offer's word, carried on the pending task so a snapshot can say it: it
     // travels exactly when Omni said tasks may be auto-accepted, and only while the task is pending.
     if (task.acceptance !== undefined) {
@@ -1275,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":
@@ -1386,10 +1400,8 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             if (isPlainObject(event.task) && typeof event.task.phase === "string") {
                 into.require(OFFERABLE_PHASES.includes(event.task.phase), "event.taskOffered.phase", `${at}.task.phase`, `task-offered introduces a task as ${OFFERABLE_PHASES.join(", ")}, never as ${event.task.phase}`);
             }
-            for (const field of ["allocationExpiresAt", "preparationEndsAt"]) {
-                if (event[field] !== undefined)
-                    into.timestamp(event[field], `event.taskOffered.${field}`, `${at}.${field}`);
-            }
+            if (event.allocationExpiresAt !== undefined)
+                into.timestamp(event.allocationExpiresAt, "event.taskOffered.allocationExpiresAt", `${at}.allocationExpiresAt`);
             break;
         case "task-updated":
             validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest) }, `${at}.task`, into);
@@ -1413,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. |
@@ -45,7 +45,7 @@ transport, a task, a break and a call each have a word of their own:
 
 | Word | Belongs to | Values |
 | --- | --- | --- |
-| `phase` | A task | `pending`, `confirmed`, `preparing`, `in-progress`, `paused`, `completing` |
+| `phase` | A task | `pending`, `confirmed`, `preview`, `in-progress`, `paused`, `completing` |
 | `media` | A task's audio | `started`, `ended` |
 | `transport` | A connection | `connecting`, `active`, `error` |
 | `status` | An authentication session | `signed-out`, `authenticating`, `authenticated`, `refreshing`, `expired` |
@@ -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"
@@ -542,7 +539,7 @@ default — see **Choosing an isolation scheme**.
 type TaskPhase =
   | "pending"
   | "confirmed"
-  | "preparing"
+  | "preview"
   | "in-progress"
   | "paused"
   | "completing";
@@ -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 = {
@@ -647,6 +644,8 @@ type Task<C extends Channel = Channel> = {
   party?: Contact;
   phase: TaskPhase;
   acceptance?: AcceptanceMode;
+  previewEndsAt?: IsoTimestamp;
+  atDeadline?: PreviewDeadline;
   reference?: string;
   attributes?: TaskAttribute[];
   handlingHistory?: TaskHandlingHistory;
@@ -656,6 +655,8 @@ type Task<C extends Channel = Channel> = {
     : { onCall?: never; leadAssist?: never; assisting?: never; monitoring?: never; media?: never }
 );
 
+type PreviewDeadline = "calls" | "expires";
+
 type AcceptanceMode =
   | "no-preference"
   | "consent"
@@ -663,9 +664,9 @@ 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" | "preparing" }
+  | { type: "expired"; phase: "pending" | "confirmed" | "preview" }
   | { type: "left" }
   | { type: "failed"; failure: ProtocolFailure };
 ```
@@ -677,7 +678,7 @@ const TASK_COMMAND_NAMES = {
   voice: [
     "answer",
     "decline",
-    "start-call",
+    "call",
     "mute",
     "hold",
     "resume",
@@ -701,22 +702,22 @@ type DispositionPayload = { disposition?: string; notes?: string };
 type VoiceTaskCommand =
   | { type: "answer" }
   | { type: "decline" }
-  | { type: "start-call" }
+  | { type: "call"; dialId: DialId }
   | { type: "mute"; muted: boolean }
   | { type: "hold" }
   | { 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);
 
@@ -997,13 +998,12 @@ type ProviderEvent =
       type: "task-offered";
       task: Task;
       allocationExpiresAt?: IsoTimestamp;
-      preparationEndsAt?: IsoTimestamp;
     }
   | { type: "task-updated"; task: Task }
   | { 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 }
@@ -1163,7 +1163,7 @@ const DEFAULT_TASK_PHASE_LABELS = {
   voice: {
     pending: "Offered",
     confirmed: "Accepted",
-    preparing: "Preview",
+    preview: "Preview",
     "in-progress": "On Call",
     paused: "On Hold",
     completing: "After Call Work",
@@ -1171,7 +1171,7 @@ const DEFAULT_TASK_PHASE_LABELS = {
   chat: {
     pending: "Incoming Chat",
     confirmed: "Accepted",
-    preparing: "Preparing",
+    preview: "Preview",
     "in-progress": "In Chat",
     paused: "Paused",
     completing: "Wrap-up",
@@ -1179,7 +1179,7 @@ const DEFAULT_TASK_PHASE_LABELS = {
   email: {
     pending: "Assigned",
     confirmed: "Accepted",
-    preparing: "Reviewing",
+    preview: "Preview",
     "in-progress": "Working",
     paused: "Paused",
     completing: "Completing",
@@ -1283,7 +1283,7 @@ only where the corresponding capability is declared; an absent capability means
 there is no separate permission flag.
 
 The commands every task has are authorized by other fields the provider declared — a task that was
-offered can be accepted, one in `preparing` can be started, one whose `completionMode` is
+offered can be accepted, one in `preview` can be called, one whose `completionMode` is
 `agent-command` can be completed. Nothing is issuable that the provider did not publish; only
 which field says so varies. See **Which commands need a capability**.
 
@@ -2092,7 +2092,6 @@ const allocation = {
   type: "task-offered",
   task: { ...task, phase: "pending", acceptance: "consent" },
   allocationExpiresAt: "2026-08-25T10:41:07.000Z",
-  preparationEndsAt: "2026-08-25T10:40:37.000Z",
 } satisfies Extract<ProviderEvent, { type: "task-offered" }>;
 ```
 
@@ -2114,10 +2113,8 @@ down and stops offering **Accept** once it passes. **Omit it unless the provider
 A provider that reports only elapsed ring time after the fact cannot say when an offer is due
 to end, and a computed value would have Omni withdraw **Accept** from a task still pending.
 
-`preparationEndsAt` is the time available for the agent to review the task context before acting.
-Omni presents the deadline with the allocation so a preview-based dialer can show how long remains
-before the agent must start the contact. Reaching the timestamp does not imply a transition; the
-provider reports what happens next through an event.
+A preview's deadline is not on the offer. It travels on the task, as `previewEndsAt` with
+`atDeadline`, so a snapshot carries it too -- see **Preview: the agent presses Call**.
 
 A provider may withdraw a pending task by emitting `task-ended` with a `cancelled` outcome.
 
@@ -2151,15 +2148,17 @@ time. Runtime conformance checks also require the task channel to match its prov
 | `capabilities` | Controls and workspace features available for this specific task. |
 | `browsers` | Named browser definitions for the task workspace: at least one when the task declares the `browsers` capability, empty when it does not. |
 | `party` | The person or entity on the other end of this task, as a `Contact`: often a name and one address; a withheld caller ID may leave nothing to send at all. Optional. The party is who the task is *with*; `contacts` is the directory. |
-| `phase` | Current canonical task phase: `pending`, `confirmed`, `preparing`, `in-progress`, `paused`, or `completing`. |
+| `phase` | Current canonical task phase: `pending`, `confirmed`, `preview`, `in-progress`, `paused`, or `completing`. `preview` is voice only. |
 | `media` | Voice only. The task's real-time audio as the provider holds it: `started` while audio is attached, `ended` once it ended, omitted while none is. The provider's word — see **`task-media-started`**. |
 | `acceptance` | How this offer is accepted — `no-preference`, `consent`, or `automatic` — stated on the pending task so a reconnect snapshot says it too. Required while `pending` when `autoAcceptTasks` was `true`, forbidden when it was `false`, and absent past `pending`. See **Acceptance modes**. |
+| `previewEndsAt` | Voice only, in `preview`: when the system stops waiting for the agent to press Call. Absent, the agent has as long as they need. Always with `atDeadline`. See **Preview: the agent presses Call**. |
+| `atDeadline` | Voice only, in `preview`, with `previewEndsAt`: what the system does at the deadline -- `calls` places the call itself, `expires` takes the record back and the task ends `expired`. |
 | `reference` | Optional agent-facing reference such as a case, call, conversation, ticket, or message number. It is distinct from the protocol `id`. |
 | `completionMode` | `agent-command` waits for the channel's `complete` command; `provider-automatic` completes without one. |
 | `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**. |
@@ -2192,9 +2191,11 @@ The canonical task transitions are:
 | --- | --- | --- |
 | No task | Provider allocates a task | `pending` |
 | `pending` | Task is accepted | `confirmed` |
-| `confirmed` | Preparation begins | `preparing` |
-| `confirmed` | Work begins without preparation | `in-progress` |
-| `preparing` | Agent starts the contact | `in-progress` |
+| `confirmed` | The customer's record is put in front of the agent before any call goes out (voice) | `preview` |
+| `confirmed` | Work begins | `in-progress` |
+| `preview` | Agent presses Call (`call`) and the customer answers, or the deadline `calls` and they answer | `in-progress` |
+| `preview` | The call goes out and nobody answers | `completing` |
+| `preview` | The deadline `expires` | Removed by `task-ended` with `expired` outcome |
 | `pending` | Provider withdraws the allocation | Removed by `task-ended` with `cancelled` outcome |
 | No task | Snapshot reports work already underway | `in-progress` |
 | `in-progress` | Provider or agent pauses the task | `paused` |
@@ -2207,9 +2208,47 @@ The canonical task transitions are:
 
 Allocation, acceptance, and progress are distinct. Acceptance follows `autoAcceptTasks` and the
 task's `acceptance`, moving the task from `pending` to `confirmed`. The provider reports
-subsequent transitions to `preparing` or `in-progress`; Omni does not infer them from the acceptance
+subsequent transitions to `preview` or `in-progress`; Omni does not infer them from the acceptance
 command.
 
+#### Preview: the agent presses Call
+
+An outbound campaign that lets the agent see who they are about to call is a **preview**: the
+record arrives as a task, the task sits in `preview` with the party on it, and no call has gone
+out. The agent reads and presses Call. That is the whole phase, and it exists on voice alone --
+chat and email have no call to place, and their reading is ordinary work in `in-progress`.
+
+```ts
+const previewed = {
+  channel: "voice",
+  capabilities: {},
+  phase: "preview",
+  party: { name: "Maya Rao", number: "+919876543210" },
+  previewEndsAt: "2026-08-25T10:40:37.000Z",
+  atDeadline: "calls",
+} satisfies Pick<Task<"voice">, "channel" | "capabilities" | "phase" | "party" | "previewEndsAt" | "atDeadline">;
+
+// The agent presses Call. It is a dial like any other.
+const pressed: TaskCommand<"voice"> = { type: "call", dialId: "dial-7f2" };
+```
+
+**Call is a dial.** It carries the host's `dialId`, is answered `dialling`, and ends in exactly one
+`dial-outcome`; the phase is its gate and there is no capability, since a record put in front of an
+agent is there to be called. On `answered` the task is `in-progress` and its media follows on
+`task-media-started`. On any other outcome the task goes to `completing`, so the agent records the
+no-answer as the disposition it is -- in a campaign that is the commonest outcome there is, and it
+is work, not a cancellation. A `preview` task therefore needs a manifest that says how a dial ends
+(`task.preview.dialOutcomes.required`).
+
+**The deadline says what the system will do.** A provider that will not wait forever states
+`previewEndsAt`, and with it `atDeadline`: `calls` means the system places the call itself when the
+time runs out, which is progressive dialling; `expires` means the record is taken back and the task
+ends with an `expired` outcome naming `preview`. The two travel together
+(`task.preview.atDeadline.required`, `task.preview.previewEndsAt.required`), only while the task is in
+`preview` (`task.preview.deadline.unexpected`), and Omni's countdown reads "calling in 12s" or
+"expires in 12s" from the provider's word. With neither, the agent has as long as they need.
+Reaching the instant is not itself a transition: the provider reports what it did, as an event.
+
 **A task is never its audio.** A voice task is the allocation: the call is offered when it is
 routed to the agent and accepted as its `acceptance` dictates, and its presence and phase follow
 the provider's reports about the work — never the audio. Wherever audio moves — an offer, a hold, a
@@ -2372,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
@@ -2632,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" },
     ],
   },
 }
@@ -2642,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
 
@@ -2671,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" }
@@ -2680,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
@@ -2790,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
@@ -2815,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
@@ -2868,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.
 
@@ -2885,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
@@ -3707,7 +3747,7 @@ declared:
 | --- | --- |
 | `answer`, `accept` | Nothing. A task that was offered can be accepted, or offering it meant nothing. |
 | `decline` | The `decline` capability on any channel, **and** Omni provisioning permitting it. One word for refusing an offer, whatever the channel. |
-| `start-call` | The `preparing` phase. It starts the contact a preview gave the agent time to read, so the phase is the gate and there is no capability. |
+| `call` | The `preview` phase. A record put in front of an agent is there to be called, so the phase is the gate and there is no capability. It is a dial, with a `dialId` and a `dial-outcome`. |
 | `complete` | `completionMode: "agent-command"`. The `dispositions` capability decides whether a code travels with the command, never whether the command exists — a task Omni cannot complete never ends. |
 | `connect-back` | The `connectBack` capability **and** the `completing` phase. It exists to reach the party again after the call, so it has no meaning while the call is up. |
 | `transfer` with `action: "warm"` | The `warmTransfer` capability. `action: "cold"` is gated by `coldTransfer`; the two are declared and offered separately. |
@@ -3764,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. |
@@ -3785,7 +3825,7 @@ They are published as `OMNI_FAILURE_CODES`.
 #### Provider instants are read against a provider clock
 
 Every deadline in this contract is a provider instant that Omni counts down: `allocationExpiresAt`,
-`preparationEndsAt`, and the wrap deadline of `task-media-ended` plus `wrapAllowance` where
+`previewEndsAt`, and the wrap deadline of `task-media-ended` plus `wrapAllowance` where
 one is stated.
 Comparing those against the host clock is wrong by whatever the two machines disagree by, and the
 damaging direction is early — **Accept** withdrawn from an offer still ringing, a wrap timer

package/package.json

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