@xema/omni-protocol 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -290,6 +290,8 @@ export type TaskCapabilities<C extends Channel = Channel> = C extends "voice" ?
     mute?: true;
     hold?: true;
     agentDisconnect?: true;
+    /** Reach the party again while `completing`; the task returns to `in-progress`. */
+    callback?: true;
     blindTransfer?: true | DestinationDirectory;
     conference?: true | DestinationDirectory;
     recording?: true;
@@ -375,7 +377,22 @@ export interface TaskHandlingStep {
      */
     by?: UserId;
 }
-export interface Task<C extends Channel = Channel> {
+/**
+ * How the task ends, and how long after handling the provider allows for it.
+ *
+ * The allowance is coupled to the mode. Under `provider-automatic` the provider acts on it, so it
+ * is required. Under `agent-command` the provider will not complete the task itself, so it may
+ * omit the allowance to say it imposes no deadline -- and Omni then counts nothing down. Omitted
+ * and `0` are different claims: no deadline to see, and a deadline of now.
+ */
+export type TaskCompletion = {
+    completionMode: "agent-command";
+    completionAllowance?: DurationSeconds;
+} | {
+    completionMode: "provider-automatic";
+    completionAllowance: DurationSeconds;
+};
+export type Task<C extends Channel = Channel> = {
     id: TaskId;
     title: string;
     channel: C;
@@ -387,11 +404,9 @@ export interface Task<C extends Channel = Channel> {
     phase: TaskPhase;
     /** The identifier an agent reads back to a customer, where the provider has one. */
     reference?: string;
-    completionMode: CompletionMode;
-    completionAllowance: DurationSeconds;
     attributes?: TaskAttribute[];
     handlingHistory?: TaskHandlingStep[];
-}
+} & TaskCompletion;
 /** What the provider wants of Omni's acceptance policy for one offer. */
 export type AcceptanceMode = "no-preference" | "require-agent-acceptance" | "require-automatic-acceptance";
 export type TaskOutcome = {
@@ -413,7 +428,7 @@ export type TaskOutcome = {
     failure: ProtocolFailure;
 };
 export declare const TASK_COMMAND_NAMES: {
-    readonly voice: readonly ["answer", "decline", "start-call", "mute", "hold", "resume", "disconnect", "transfer", "conference", "recording", "complete"];
+    readonly voice: readonly ["answer", "decline", "start-call", "mute", "hold", "resume", "disconnect", "callback", "transfer", "conference", "recording", "complete"];
     readonly chat: readonly ["accept", "reject", "pause", "resume", "complete"];
     readonly email: readonly ["accept", "reject", "complete"];
 };
@@ -437,6 +452,10 @@ export type VoiceTaskCommand = {
     type: "resume";
 } | {
     type: "disconnect";
+}
+/** Issuable only in `completing`, under the `callback` capability. Carries no destination. */
+ | {
+    type: "callback";
 } | {
     type: "transfer";
     destination: string;

package/dist/index.js

@@ -55,7 +55,7 @@ export function isAllowedBrowserUrl(url) {
 // ---------------------------------------------------------------------------
 export const TASK_COMMAND_NAMES = {
     voice: ["answer", "decline", "start-call", "mute", "hold", "resume", "disconnect",
-        "transfer", "conference", "recording", "complete"],
+        "callback", "transfer", "conference", "recording", "complete"],
     chat: ["accept", "reject", "pause", "resume", "complete"],
     email: ["accept", "reject", "complete"],
 };

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Connection, type Snapshot, type Task, type BreakApproval, type BrowserSessionKeyInput, type Channel, type ConnectContext, type DialRequest, type TaskCommandRequest } from "./index.js";
+import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Connection, type Snapshot, type TaskCompletion, type BreakApproval, type BrowserSessionKeyInput, type Channel, type ConnectContext, type DialRequest, type TaskCommandRequest } from "./index.js";
 import { type ProtocolViolation } from "./validation.js";
 export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation } from "./validation.js";
 export interface AdapterContractResult {
@@ -39,16 +39,23 @@ export declare function assertReconnectWithMissedAssignments<C extends Channel>(
  * There is no `denied` approval: a refusal returns the agent to `not-requested`, because a
  * pending request nobody is coming to decide is worse than none. So the scenario is a request
  * that goes back to not-requested, and a later one that is granted.
+ *
+ * A request shows as `awaiting-decision` where a person decides, and as `granted` at once where
+ * the provider decides alone; either is the request being made, and the rule is the same for
+ * both.
  */
 export declare function assertDeniedAndRetriedBreak(approvals: readonly BreakApproval[]): void;
 /** Verifies that retrying one dial command cannot place a second call. */
 export declare function assertDialIdempotency(connection: Pick<Connection, "dial">, request: DialRequest): Promise<void>;
 /**
  * Validates the deadline derived from media end and the task's fixed wrap allowance.
- * `toleranceMs` absorbs scheduler jitter in a real implementation; pass 0 to demand
- * an exact match.
+ *
+ * A task with no allowance has no deadline, so `observedDeadline` must then be `undefined`: a
+ * host counting down what the provider left open is the violation, and so is a host counting
+ * nothing down when the provider set a clock. `toleranceMs` absorbs scheduler jitter in a real
+ * implementation; pass 0 to demand an exact match.
  */
-export declare function assertWrapTimeout(task: Pick<Task, "completionAllowance">, mediaEndedAt: string, observedDeadline: string, toleranceMs?: number): void;
+export declare function assertWrapTimeout(task: Pick<TaskCompletion, "completionMode" | "completionAllowance">, mediaEndedAt: string, observedDeadline: string | undefined, toleranceMs?: number): void;
 /** One browser in one task of one provider. `providerId` is `Manifest.id`, never `displayName`. */
 export type BrowserIsolationScenario = BrowserSessionKeyInput;
 /** Validates whether two task-browser definitions should share one browser session. */

package/dist/testing.js

@@ -209,9 +209,13 @@ export function assertReconnectWithMissedAssignments(before, reconnect, missedTa
  * There is no `denied` approval: a refusal returns the agent to `not-requested`, because a
  * pending request nobody is coming to decide is worse than none. So the scenario is a request
  * that goes back to not-requested, and a later one that is granted.
+ *
+ * A request shows as `awaiting-decision` where a person decides, and as `granted` at once where
+ * the provider decides alone; either is the request being made, and the rule is the same for
+ * both.
  */
 export function assertDeniedAndRetriedBreak(approvals) {
-    const asked = approvals.indexOf("awaiting-decision");
+    const asked = approvals.findIndex(approval => approval === "awaiting-decision" || approval === "granted");
     if (asked < 0)
         throw new Error("Break retry scenario requires an initial request");
     const refused = approvals.indexOf("not-requested", asked + 1);
@@ -245,10 +249,22 @@ export async function assertDialIdempotency(connection, request) {
 }
 /**
  * Validates the deadline derived from media end and the task's fixed wrap allowance.
- * `toleranceMs` absorbs scheduler jitter in a real implementation; pass 0 to demand
- * an exact match.
+ *
+ * A task with no allowance has no deadline, so `observedDeadline` must then be `undefined`: a
+ * host counting down what the provider left open is the violation, and so is a host counting
+ * nothing down when the provider set a clock. `toleranceMs` absorbs scheduler jitter in a real
+ * implementation; pass 0 to demand an exact match.
  */
 export function assertWrapTimeout(task, mediaEndedAt, observedDeadline, toleranceMs = 1_000) {
+    if (task.completionAllowance === undefined) {
+        if (observedDeadline !== undefined) {
+            throw new Error(`Wrap deadline mismatch: the task states no allowance, so there is no deadline, received ${observedDeadline}`);
+        }
+        return;
+    }
+    if (observedDeadline === undefined) {
+        throw new Error(`Wrap deadline mismatch: the task allows ${task.completionAllowance}s, but no deadline was observed`);
+    }
     const ended = Date.parse(mediaEndedAt);
     const deadline = Date.parse(observedDeadline);
     if (Number.isNaN(ended) || Number.isNaN(deadline))

package/dist/validation.js

@@ -79,7 +79,7 @@ const ISOLATION_SCHEME_VALUES = Object.values(BROWSER_ISOLATION_SCHEMES);
 const TASK_CAPABILITIES = {
     voice: membersOf({
         browsers: true, dispositions: true, custom: true, decline: true, mute: true, hold: true,
-        agentDisconnect: true, blindTransfer: true, conference: true, recording: true,
+        agentDisconnect: true, callback: true, blindTransfer: true, conference: true, recording: true,
     }),
     chat: membersOf({ browsers: true, dispositions: true, custom: true, reject: true, hold: true }),
     email: membersOf({ browsers: true, dispositions: true, custom: true, reject: true }),
@@ -517,7 +517,15 @@ function validateTaskInto(task, context, path, into) {
     into.filled(task.taskType, "task.taskType", `${path}.taskType`, "a task needs a task type");
     into.oneOf(task.phase, TASK_PHASES, "task.phase", `${path}.phase`);
     into.oneOf(task.completionMode, COMPLETION_MODES, "task.completionMode", `${path}.completionMode`);
-    into.require(isDurationSeconds(task.completionAllowance), "task.completionAllowance", `${path}.completionAllowance`, "completionAllowance must be a whole number of seconds, zero or more");
+    // The allowance is coupled to the mode: a provider that will complete the task itself is going
+    // to act on the allowance, so it must state one; a provider waiting for `complete` may omit it
+    // to say it imposes no deadline. Present, it is a duration either way.
+    if (task.completionAllowance === undefined) {
+        into.require(task.completionMode !== "provider-automatic", "task.completionAllowance.required", `${path}.completionAllowance`, "provider-automatic completion needs an allowance to act on");
+    }
+    else {
+        into.require(isDurationSeconds(task.completionAllowance), "task.completionAllowance", `${path}.completionAllowance`, "completionAllowance must be a whole number of seconds, zero or more, or omitted under agent-command");
+    }
     // The channel is fixed per provider by its manifest, so a task claiming another one is a
     // task Omni would render with the wrong controls.
     into.require(task.channel === context.channel, "task.channel", `${path}.channel`, `a ${context.channel} provider may not publish a ${String(task.channel)} task`);

package/guide.md

@@ -335,6 +335,7 @@ type TaskCapabilities<C extends Channel = Channel> =
         mute?: true;
         hold?: true;
         agentDisconnect?: true;
+        callback?: true;
         blindTransfer?: true | DestinationDirectory;
         conference?: true | DestinationDirectory;
         recording?: true;
@@ -416,6 +417,10 @@ type TaskHandlingStep = {
   by?: UserId;
 };
 
+type TaskCompletion =
+  | { completionMode: "agent-command"; completionAllowance?: DurationSeconds }
+  | { completionMode: "provider-automatic"; completionAllowance: DurationSeconds };
+
 type Task<C extends Channel = Channel> = {
   id: TaskId;
   title: string;
@@ -426,11 +431,9 @@ type Task<C extends Channel = Channel> = {
   contact?: Contact;
   phase: TaskPhase;
   reference?: string;
-  completionMode: CompletionMode;
-  completionAllowance: DurationSeconds;
   attributes?: TaskAttribute[];
   handlingHistory?: TaskHandlingStep[];
-};
+} & TaskCompletion;
 
 type AcceptanceMode =
   | "no-preference"
@@ -457,6 +460,7 @@ const TASK_COMMAND_NAMES = {
     "hold",
     "resume",
     "disconnect",
+    "callback",
     "transfer",
     "conference",
     "recording",
@@ -479,6 +483,7 @@ type VoiceTaskCommand =
   | { type: "hold" }
   | { type: "resume" }
   | { type: "disconnect" }
+  | { type: "callback" }
   | { type: "transfer"; destination: string }
   | { type: "conference"; participant: string; action: "add" | "remove" }
   | { type: "recording"; action: "start" | "pause" | "resume" | "stop" }
@@ -1616,7 +1621,7 @@ time. Runtime conformance checks also require the task channel to match its prov
 | `phase` | Current canonical task phase: `pending`, `confirmed`, `preparing`, `in-progress`, `paused`, or `completing`. |
 | `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. |
-| `completionAllowance` | Fixed time allowed to complete the task after primary handling ends. For real-time media, it begins after `task-media-ended`. |
+| `completionAllowance` | 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` | Optional ordered handling history for this currently open task. It is live task data, not a permanent archive. |
 
@@ -1656,6 +1661,7 @@ The canonical task transitions are:
 | `in-progress` | Provider or agent pauses the task | `paused` |
 | `paused` | Provider or agent resumes the task | `in-progress` |
 | `in-progress` or `paused` | Contact handling ends and follow-up work remains | `completing` |
+| `completing` | Agent calls the party back (`callback`) | `in-progress` |
 | Any phase | Provider emits `task-ended` | Removed |
 
 Allocation, acceptance, and progress are distinct. Acceptance follows `autoAcceptTasks` and the
@@ -1690,9 +1696,61 @@ In this example, the agent has two minutes after sending the email to add notes,
 disposition, and complete the task.
 
 `0` means completion may happen immediately. With `provider-automatic`, the provider may complete
-without waiting for a command; with `agent-command`, it still waits for `complete`. There is no
-value meaning "unlimited": a provider that does not want a deadline keeps the task `in-progress` or
-`paused` and moves it to `completing` only when the clock should start.
+without waiting for a command; with `agent-command`, it still waits for `complete`.
+
+There is no value meaning "unlimited", because a number that is not a duration would be read as
+one. A provider that imposes no deadline says so by **omitting** `completionAllowance`, which
+only `agent-command` permits: the provider will not complete the task itself, so there is nothing
+for a deadline to trigger, and Omni counts nothing down. **Omitted and empty are different
+claims** applies -- omitted says there is no deadline to see, where `0` says the deadline is now.
+Under `provider-automatic` the field is required, because the provider is going to act on it.
+
+```ts
+const untimedWrap = {
+  completionMode: "agent-command",
+} satisfies Pick<Task<"voice">, "completionMode" | "completionAllowance">;
+```
+
+Here the customer has hung up, `task-media-ended` has been sent on time, the task is `completing`,
+and the agent takes as long as the work needs. Moving the task to `completing` late to avoid a
+deadline is not an alternative on a media channel: the clock starts at a real event, and delaying
+that event would falsify the phase and everything timed from it.
+
+#### Calling back during completion
+
+A task that declares `callback` lets the agent reach the party again while the task is
+`completing` -- to finish what the call left unfinished, on the same task rather than a new one.
+Omni issues `{ type: "callback" }`; it is issuable only in `completing`, and only where the
+capability is declared. The provider knows who the party is; the command carries no destination.
+
+On `applied` the provider is placing the call and the task returns to `in-progress`: the agent is
+working again, and the completion allowance is **discarded, not paused**. From there the call is
+reported as any call is -- `paused`, `in-progress`, and when its media ends, `task-media-ended`
+again, which starts a fresh allowance from that instant. A party who does not answer is a call
+whose media ended: the task returns to `completing` through the same event and the clock starts
+again from there. At no point is an agent dialling against a deadline.
+
+**The control exists only while there is a window to use it in.** Under `agent-command` the task
+stays `completing` until the agent completes it, so the window is open for as long as they need.
+Under `provider-automatic` the window is the allowance -- and with `completionAllowance: 0` there
+is none: the provider disposes the task at provider end, and Omni does not offer Call back, whatever
+the task declares. A capability names a control that can be used; on a task with no `completing`
+window it cannot, and declaring it there changes nothing.
+
+```ts
+const callbackCapable = {
+  channel: "voice",
+  capabilities: { hold: true, callback: true, dispositions: true },
+  phase: "completing",
+  completionMode: "provider-automatic",
+  completionAllowance: 30,
+} satisfies Pick<Task<"voice">, "channel" | "capabilities" | "phase" | "completionMode" | "completionAllowance">;
+```
+
+With ten seconds of the thirty left, the agent presses Call back: `execute({ command: { type:
+"callback" } })` returns `applied`, the task is `in-progress`, and the thirty seconds are gone.
+The second call ends: `task-media-ended`, the task is `completing`, and a new thirty seconds runs
+from that instant.
 
 ```ts
 const immediateProviderCompletion = {
@@ -1887,6 +1945,7 @@ const taskCapabilities = {
 | `mute` | Primary toggle: Mute | Omni may mute and unmute the agent's outbound audio. |
 | `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. |
+| `callback` | Completing-task button: Call back | Omni may have the provider call the task's party back 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 **Calling back during completion**. |
 | `blindTransfer` | Secondary menu item: Blind transfer | Omni may transfer the caller directly to a destination. |
 | `conference` | Secondary button: Conference | Omni may add or remove participants from the active call. |
 | `recording` | Overflow menu item: Recording | Omni may expose start, pause, resume, and stop recording controls. |
@@ -2601,6 +2660,7 @@ declared:
 | `decline`, `reject` | The channel's decline or reject capability, **and** Omni provisioning permitting rejection. |
 | `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. |
 | `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. |
+| `callback` | The `callback` 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. |
 | Everything else | Its own named capability. |
 
 Declining or rejecting a pending offer ends it without accepting or completing it. The provider
@@ -2666,7 +2726,8 @@ 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 `completionAllowance`.
+`preparationEndsAt`, and the wrap deadline of `task-media-ended` plus `completionAllowance` 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
 expiring before the agent has finished.
@@ -2913,7 +2974,7 @@ cannot be established from TypeScript structure alone.
 | `assertDeniedAndRetriedBreak(states)` | A denial transitions directly to `not-requested`; a later request can still be granted. |
 | `assertCommandIdempotency(connection, request)` | Retrying a task command does not repeat its side effect. |
 | `assertDialIdempotency(connection, request)` | Retrying a dial command does not place another call. |
-| `assertWrapTimeout(task, mediaEndedAt, deadline, toleranceMs?)` | The wrap deadline equals media end plus the task allowance, within a tolerance that defaults to 1000ms. |
+| `assertWrapTimeout(task, mediaEndedAt, deadline, toleranceMs?)` | The wrap deadline equals media end plus the task allowance, within a tolerance that defaults to 1000ms; a task with no allowance has no deadline, and one observed is the violation. |
 | `assertBrowserIsolationAndReuse(left, right, expected)` | Browser reuse follows only the declared isolation scheme. |
 | `assertNoBrowserSessionKeyCollisions(scenarios)` | No two distinct scenarios derive the same session key. Feed it adversarial names. |
 

package/package.json

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