@xema/omni-protocol 0.1.43 → 0.1.44

package/dist/index.d.ts

@@ -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;
@@ -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,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",
     },
 };

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({
@@ -82,13 +82,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. */
@@ -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) {
@@ -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

@@ -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` |
@@ -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,7 +705,7 @@ 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" }
@@ -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,9 +2194,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 +2211,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
@@ -3707,7 +3749,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. |
@@ -3785,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.43",
+  "version": "0.1.44",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",