@xema/omni-protocol 0.1.42 → 0.1.44

package/README.md

@@ -97,17 +97,16 @@ const task = {
 };
 ```
 
-**The blind transfer arm is `action?: never`.** Switch on `command.action` with `case undefined`
-for it, never a `default`: a `default` turns a future action into a silent blind transfer, and
-switching on `command.action ?? "blind"` loses the narrowing that lets you read `destination`
-without a cast. Dropping an arm then fails the build — indirectly, as a missing return.
+**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.
 
 ```ts
 switch (command.action) {
-  case undefined:  return blindTransfer(command.destination);
-  case "consult":  return consultTransfer(command.destination);
-  case "complete": return completeConsultation();
-  case "cancel":   return cancelConsultation();
+  case "cold":     return coldTransfer(command.destination);
+  case "warm":     return warmTransfer(command.destination);
+  case "complete": return completeWarmTransfer();
+  case "cancel":   return cancelWarmTransfer();
 }
 ```
 

package/dist/index.d.ts

@@ -451,9 +451,9 @@ 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>;
-    blindTransfer?: Lockable<true | DestinationDirectory>;
+    coldTransfer?: Lockable<true | DestinationDirectory>;
     /** Park the customer and call a destination first; then `complete` or `cancel`. */
-    consultTransfer?: Lockable<true | DestinationDirectory>;
+    warmTransfer?: Lockable<true | 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>;
@@ -512,10 +512,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 {
@@ -710,6 +715,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[];
@@ -747,7 +759,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 +769,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 +782,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,17 +802,17 @@ export type VoiceTaskCommand = {
     type: "connect-back";
     dialId: DialId;
 }
-/** Blind: hand the customer to `destination` with nobody consulted. Gated by `blindTransfer`. */
+/** Cold: hand the customer to `destination` with nobody spoken to first. Gated by `coldTransfer`. */
  | {
     type: "transfer";
+    action: "cold";
     dialId: DialId;
     destination: string;
-    action?: never;
 }
-/** Park the customer and call `destination` first. Gated by `consultTransfer`. */
+/** Warm: park the customer and call `destination` first. Gated by `warmTransfer`. */
  | {
     type: "transfer";
-    action: "consult";
+    action: "warm";
     dialId: DialId;
     destination: string;
 }
@@ -1255,7 +1270,6 @@ export type ProviderEvent<C extends Channel = Channel> = {
     type: "task-offered";
     task: Task<C>;
     allocationExpiresAt?: IsoTimestamp;
-    preparationEndsAt?: IsoTimestamp;
 } | {
     type: "task-updated";
     task: Task<C>;
@@ -1372,7 +1386,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 +1394,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 +1402,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";

package/dist/index.js

@@ -71,16 +71,16 @@ 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 === undefined || command.action === "consult"))
+    if (command.type === "transfer" && (command.action === "cold" || command.action === "warm"))
         return command.dialId;
     if (command.type === "conference" && command.action === "add")
         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",
     },
 };

package/dist/testing.js

@@ -70,7 +70,7 @@ function observeTask(value, seen) {
     const capabilities = isRecord(value.capabilities) ? value.capabilities : {};
     if (isRecord(capabilities.dispositions))
         seen.add("task.dispositions");
-    for (const directory of ["blindTransfer", "consultTransfer", "conference"]) {
+    for (const directory of ["coldTransfer", "warmTransfer", "conference"]) {
         const declared = capabilities[directory];
         if (isRecord(declared) && some(declared.destinations))
             seen.add("task.destinations");

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({
@@ -73,7 +73,7 @@ const EXPLAINED_FAILURES = ["busy", "no-answer", "unreachable", "rejected", "can
 const ON_CALL_ROLES = membersOf({ party: true, agent: true, consulted: true, conferenced: true });
 const ON_CALL_STAGES = membersOf({ ringing: true, joined: true });
 /** The task capabilities under which a command dials, and so need the manifest to say how a dial ends. */
-const DIALLING_CAPABILITIES = ["connectBack", "blindTransfer", "consultTransfer", "conference"];
+const DIALLING_CAPABILITIES = ["connectBack", "coldTransfer", "warmTransfer", "conference"];
 const SNAPSHOT_REASONS = membersOf({
     reconnected: true, "provider-requested": true,
 });
@@ -82,20 +82,21 @@ 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. */
 const TASK_CAPABILITIES = {
     voice: membersOf({
         browsers: true, dispositions: true, custom: true, decline: true, mute: true, hold: true,
-        agentDisconnect: true, connectBack: true, blindTransfer: true, consultTransfer: true, leadAssist: true, conference: true, recording: true,
+        agentDisconnect: true, connectBack: true, coldTransfer: true, warmTransfer: true, leadAssist: true, conference: true, recording: true,
     }),
     chat: membersOf({ browsers: true, dispositions: true, custom: true, decline: true, hold: true }),
     email: membersOf({ browsers: true, dispositions: true, custom: true, decline: true }),
@@ -864,7 +865,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) {
@@ -948,8 +970,8 @@ function validateTaskInto(task, context, path, into) {
             case "custom":
                 validateCustomCapabilities(declared, `${path}.capabilities.custom`, into);
                 break;
-            case "blindTransfer":
-            case "consultTransfer":
+            case "coldTransfer":
+            case "warmTransfer":
             case "conference":
                 validateDestinationDirectory(declared, `${path}.capabilities.${name}`, into);
                 break;
@@ -1386,10 +1408,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);

package/guide.md

@@ -35,7 +35,7 @@ are used precisely throughout and mean nothing looser here.
 | **Event** | One completed transaction reported after a snapshot established the baseline. |
 | **Break** | A reported, supervised state in which the agent is not working — one with a reason, a decision behind it and a return. It covers what a platform may call *not-ready*, including equipment trouble. An agent who is merely at capacity is not on a break. |
 | **Workspace** | What Omni shows the agent. The **task workspace** holds the selected task, its controls and its browsers; the **idle workspace** holds what a provider contributes when no task is selected — dialpad, contacts, calendar, roster. |
-| **Dial** | One outbound call the host asks a provider to place — from the idle dialpad, a transfer, a conference add, or a connect-back. Identified by the host's `dialId`, accepted as `dialling`, and ended by exactly one `dial-outcome`. See **Every dial has an outcome**. |
+| **Dial** | One outbound call the host asks a provider to place — from the idle dialpad, a cold or warm transfer, a conference add, or a connect-back. Identified by the host's `dialId`, accepted as `dialling`, and ended by exactly one `dial-outcome`. See **Every dial has an outcome**. |
 | **Monitor** | A lead listening to a member's call unasked, from the roster: `monitor` in silence, `whisper` heard by the agent alone, `barge` heard by everyone. Nothing of it reaches the member's task, and there is no take-over in it. See **Monitoring a call**. |
 | **On the call** | Who a voice task's audio joins, or is bringing in, as the provider states it on `Task.onCall`: the party, the agents, and anyone consulted or conferenced in from the moment their dial is placed. |
 
@@ -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` |
@@ -481,8 +481,8 @@ type TaskCapabilities<C extends Channel = Channel> =
         hold?: Lockable<true>;
         agentDisconnect?: Lockable<true>;
         connectBack?: Lockable<true>;
-        blindTransfer?: Lockable<true | DestinationDirectory>;
-        consultTransfer?: Lockable<true | DestinationDirectory>;
+        coldTransfer?: Lockable<true | DestinationDirectory>;
+        warmTransfer?: Lockable<true | DestinationDirectory>;
         leadAssist?: Lockable<true>;
         conference?: Lockable<true | DestinationDirectory>;
         recording?: Lockable<true>;
@@ -542,7 +542,7 @@ default — see **Choosing an isolation scheme**.
 type TaskPhase =
   | "pending"
   | "confirmed"
-  | "preparing"
+  | "preview"
   | "in-progress"
   | "paused"
   | "completing";
@@ -647,6 +647,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 +658,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"
@@ -665,7 +669,7 @@ type TaskOutcome =
   | { type: "completed"; by: "agent" | "provider" }
   | { type: "transferred"; destination?: 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 +681,7 @@ const TASK_COMMAND_NAMES = {
   voice: [
     "answer",
     "decline",
-    "start-call",
+    "call",
     "mute",
     "hold",
     "resume",
@@ -701,14 +705,14 @@ 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"; dialId: DialId; destination: string; action?: never }
-  | { type: "transfer"; action: "consult"; dialId: DialId; destination: string }
+  | { type: "transfer"; action: "cold"; dialId: DialId; destination: string }
+  | { type: "transfer"; action: "warm"; dialId: DialId; destination: string }
   | { type: "transfer"; action: "complete" }
   | { type: "transfer"; action: "cancel" }
   | { type: "lead-assist"; action: "request"; note?: string }
@@ -997,7 +1001,6 @@ type ProviderEvent =
       type: "task-offered";
       task: Task;
       allocationExpiresAt?: IsoTimestamp;
-      preparationEndsAt?: IsoTimestamp;
     }
   | { type: "task-updated"; task: Task }
   | { type: "task-media-started"; taskId: TaskId }
@@ -1163,7 +1166,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 +1174,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 +1182,7 @@ const DEFAULT_TASK_PHASE_LABELS = {
   email: {
     pending: "Assigned",
     confirmed: "Accepted",
-    preparing: "Reviewing",
+    preview: "Preview",
     "in-progress": "Working",
     paused: "Paused",
     completing: "Completing",
@@ -1283,7 +1286,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 +2095,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 +2116,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,9 +2151,11 @@ 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. |
@@ -2192,24 +2194,64 @@ 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` |
-| `in-progress` | Agent consults a transfer destination (`transfer` `consult`); the customer is parked | `paused` |
+| `in-progress` | Agent starts a warm transfer (`transfer` `warm`); the customer is parked | `paused` |
 | `paused` | Provider or agent resumes the task | `in-progress` |
-| `paused` | Agent cancels a consultation (`transfer` `cancel`) | `in-progress` |
+| `paused` | Agent cancels a warm transfer (`transfer` `cancel`) | `in-progress` |
 | `in-progress` or `paused` | Contact handling ends and follow-up work remains | `completing` |
 | `completing` | Agent connects back to the party (`connect-back`) | `in-progress` |
 | Any phase | Provider emits `task-ended` | Removed |
 
 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
@@ -2591,8 +2633,8 @@ const taskCapabilities = {
 | `hold` | Primary toggle: Hold | Omni may issue voice-task `hold` and `resume` commands. |
 | `agentDisconnect` | Primary button: Disconnect | Omni may disconnect real-time media without disposing the task. |
 | `connectBack` | Completing-task button: Connect back | Omni may have the provider connect the agent back to the task's party while the task is `completing`, returning it to `in-progress` on the same task. Not offered where there is no `completing` window: `provider-automatic` with a zero allowance disposes at provider end. See **Connecting back during completion**. |
-| `blindTransfer` | Secondary menu item: Blind transfer | Omni may transfer the caller directly to a destination. |
-| `consultTransfer` | Secondary menu item: Consult transfer | Omni may park the customer and call a destination first, then hand the customer over or cancel back. See **Consult transfer**. |
+| `coldTransfer` | Secondary menu item: Cold transfer | Omni may hand the customer straight to a destination, with nobody spoken to first. |
+| `warmTransfer` | Secondary menu item: Warm transfer | Omni may park the customer and call a destination first, then hand the customer over or cancel back. See **Warm transfer**. |
 | `leadAssist` | Secondary menu item: Lead assist | Omni may ask a lead to join this call, with a note. The lead's decision reaches the agent on `Task.leadAssist`. See **Lead assist**. |
 | `conference` | Secondary button: Conference | Omni may dial a destination into the active call, and drop a `conferenced` entry from it -- one still ringing included, which calls the dial off. |
 | `recording` | Overflow menu item: Recording | Omni may expose start, pause, resume, and stop recording controls. |
@@ -2627,11 +2669,11 @@ capabilities: {
 With `dispositions: true` Omni shows a Complete control and sends `complete` with no code, because
 the provider published none.
 
-#### `blindTransfer`, `consultTransfer` and `conference`
+#### `coldTransfer`, `warmTransfer` and `conference`
 
 ```ts
 capabilities: {
-  blindTransfer: {
+  coldTransfer: {
     allowManualEntry: false,
     destinations: [
       { id: "tier2", label: "Tier 2 support", address: "+14155550111", kind: "queue" },
@@ -2659,18 +2701,19 @@ A destination the agent types is not in the directory and has no `kind`. Omni tr
 `external` unless the provider says otherwise in its response, because that is the assumption that
 does not overstate what the provider can still see.
 
-#### Consult transfer
+#### Warm transfer
 
-A consult transfer parks the customer, calls the destination so the agent can speak to it first,
-and then either hands the customer over or returns to them. It is its own capability, distinct
-from `blindTransfer` (a hand-over with nobody consulted) and from `conference` (everybody on one
-call): a queue may offer any of the three without the others, and each is declared on its own.
+A warm transfer parks the customer, calls the destination so the agent can speak to it first, and
+then either hands the customer over or returns to them. Cold and warm are the words agents use;
+telephony says blind and consult. It is its own capability, distinct from `coldTransfer` (a
+hand-over with nobody spoken to first) and from `conference` (everybody on one call): a queue may
+offer any of the three without the others, and each is declared on its own.
 
 ```ts
-// 1. Consult. A dial: the provider parks the customer and calls the destination, answers
+// 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: "consult", dialId: "dial-7f2", destination: "+14155550111" }
+{ type: "transfer", action: "warm", dialId: "dial-7f2", destination: "+14155550111" }
 
 // 2a. Hand the customer to the consulted destination and leave.
 { type: "transfer", action: "complete" }
@@ -2679,7 +2722,7 @@ call): a queue may offer any of the three without the others, and each is declar
 { type: "transfer", action: "cancel" }
 ```
 
-`consult` is gated by the `consultTransfer` capability and takes a destination exactly as a blind
+`warm` is gated by the `warmTransfer` capability and takes a destination 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
@@ -2687,7 +2730,7 @@ is what makes `complete` and `cancel` issuable -- they name no destination becau
 one they could mean, which is why a task carries at most one `consulted` entry
 (`task.onCall.consulted.single`). A consultation that could be started but not finished would
 strand the customer and the destination both, which is why all three are commands and a provider
-that offers `consultTransfer` implements all three.
+that offers `warmTransfer` implements all three.
 
 `applied` on `complete` says the provider is bridging the customer to the destination and
 dropping the agent's leg. What follows is what follows any transfer: the agent's media ends and
@@ -2836,7 +2879,7 @@ call it belonged to and never against the next one.
 The stream knows a dial from three places: `TaskStream.dialled(dialId)`, which a host calls when it
 places one; an entry on a task's `onCall`; and a step in its `handlingHistory`. Since a dialled entry
 is listed from placement, `dialled()` is load-bearing only for a dial that never has an entry -- a
-blind transfer, a connect-back, an idle dialpad call -- or whose entry has already left the room; an
+cold transfer, a connect-back, an idle dialpad call -- or whose entry has already left the room; an
 outcome for a dial nobody placed and no task mentions is what `stream.dialOutcome.unknown` refuses.
 
 **`answered` says what happened to the dial; `onCall` says who is in the room.** They are two
@@ -2855,7 +2898,7 @@ provider does report -- `busy`, `no-answer`, `unreachable`, `rejected` or `cance
 switch gave none, while one that reports none would be sending the generic failure this set exists
 to refuse. A provider that dials at all declares it: an idle
 dialpad requires it (`manifest.dialOutcomes.required`), and a task that declares `connectBack`,
-`blindTransfer`, `consultTransfer` or `conference` under a manifest without it is refused
+`coldTransfer`, `warmTransfer` or `conference` under a manifest without it is refused
 (`task.capability.dialOutcomes.required`). Off voice nothing dials, and the field is a compile
 error there.
 
@@ -3706,10 +3749,10 @@ 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: "consult"` | The `consultTransfer` capability. Blind `transfer` is gated by `blindTransfer`; the two are declared and offered separately. |
+| `transfer` with `action: "warm"` | The `warmTransfer` capability. `action: "cold"` is gated by `coldTransfer`; the two are declared and offered separately. |
 | `transfer` with `action: "complete"` or `"cancel"` | A consultation in progress -- a `consulted` entry on `Task.onCall`. Without one there is nothing to complete or cancel, and a provider that receives either answers `failed`. |
 | `lead-assist` with `action: "request"` or `"cancel"` | The `leadAssist` capability. `cancel` needs a request standing -- `Task.leadAssist` with status `requested`. |
 | `lead-assist` with `action: "take-over"` or `"leave"` | The lead's own task, on a call they joined -- `Task.assisting` present. An agent's task never has it, and a provider that receives either without it answers `failed`. |
@@ -3784,7 +3827,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.42",
+  "version": "0.1.44",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",