@xema/omni-protocol 0.1.2 → 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;
@@ -426,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"];
 };
@@ -450,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

@@ -39,6 +39,10 @@ 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. */

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);

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 }),

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;
@@ -459,6 +460,7 @@ const TASK_COMMAND_NAMES = {
     "hold",
     "resume",
     "disconnect",
+    "callback",
     "transfer",
     "conference",
     "recording",
@@ -481,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" }
@@ -1658,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
@@ -1712,6 +1716,42 @@ and the agent takes as long as the work needs. Moving the task to `completing` l
 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 = {
   completionMode: "provider-automatic",
@@ -1905,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. |
@@ -2619,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

package/package.json

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