@xema/omni-protocol 0.1.3 → 0.1.5

package/README.md

@@ -59,6 +59,35 @@ assignments, break denial and retry, command idempotency, wrap timeout, browser
 > conforming one. A suite that only asserts "this conforming case does not throw" passes unchanged
 > if the helper is gutted, so pair every positive case with the violating twin.
 
+## Two things TypeScript will not catch for you
+
+Both found by adapters against this contract, and both produce a green build over a wrong shape.
+
+**Conditional spreads are the blind spot on a task literal.** A key inside
+`...(cond ? { … } : {})` is never checked against the task type, and `satisfies Task<C>` on the
+surrounding literal does not reach it. Put the check on the spread operand itself:
+
+```ts
+const task = {
+  id, title, channel: "voice", taskType, capabilities, browsers, phase, completionMode,
+  ...(contact ? { contact } satisfies Partial<Task<"voice">> : {}),
+};
+```
+
+**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.
+
+```ts
+switch (command.action) {
+  case undefined:  return blindTransfer(command.destination);
+  case "consult":  return consultTransfer(command.destination);
+  case "complete": return completeConsultation();
+  case "cancel":   return cancelConsultation();
+}
+```
+
 ## Building
 
 ```

package/dist/index.d.ts

@@ -293,6 +293,10 @@ export type TaskCapabilities<C extends Channel = Channel> = C extends "voice" ?
     /** Reach the party again while `completing`; the task returns to `in-progress`. */
     callback?: true;
     blindTransfer?: true | DestinationDirectory;
+    /** Park the customer and call a destination first; then `complete` or `cancel`. */
+    consultTransfer?: true | DestinationDirectory;
+    /** Ask a lead to join this call, with a note. The lead's decision arrives on `Task.lead`. */
+    consultLead?: true;
     conference?: true | DestinationDirectory;
     recording?: true;
 } : C extends "chat" ? SharedTaskCapabilities & {
@@ -392,6 +396,35 @@ export type TaskCompletion = {
     completionMode: "provider-automatic";
     completionAllowance: DurationSeconds;
 };
+/**
+ * A consultation in progress on a task: who is being consulted, and since when where the provider
+ * records it. Present between `transfer` `consult` and whichever of `complete` or `cancel`
+ * follows; its presence is what makes those two issuable.
+ */
+export interface TaskConsultation {
+    destination: string;
+    label?: string;
+    since?: IsoTimestamp;
+}
+/**
+ * The agent's request for a lead, from asking until the lead leaves or the request ends.
+ * `requested` while nobody has joined; `joined`, with `leadId`, once somebody has.
+ */
+export interface TaskLead {
+    status: "requested" | "joined";
+    leadId?: UserId;
+    note?: string;
+    since: IsoTimestamp;
+}
+/**
+ * On the lead's own task for a call they joined: which member asked, with their note. Its
+ * presence is what makes `lead` `take-over` and `leave` issuable.
+ */
+export interface TaskAssisting {
+    memberId: UserId;
+    note?: string;
+    since: IsoTimestamp;
+}
 export type Task<C extends Channel = Channel> = {
     id: TaskId;
     title: string;
@@ -406,7 +439,15 @@ export type Task<C extends Channel = Channel> = {
     reference?: string;
     attributes?: TaskAttribute[];
     handlingHistory?: TaskHandlingStep[];
-} & TaskCompletion;
+} & TaskCompletion & (C extends "voice" ? {
+    consultation?: TaskConsultation;
+    lead?: TaskLead;
+    assisting?: TaskAssisting;
+} : {
+    consultation?: never;
+    lead?: never;
+    assisting?: never;
+});
 /** 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 = {
@@ -423,12 +464,16 @@ export type TaskOutcome = {
  | {
     type: "expired";
     phase: "pending" | "confirmed" | "preparing";
+}
+/** This agent left a call that continues without them: a lead who joined and dropped. */
+ | {
+    type: "left";
 } | {
     type: "failed";
     failure: ProtocolFailure;
 };
 export declare const TASK_COMMAND_NAMES: {
-    readonly voice: readonly ["answer", "decline", "start-call", "mute", "hold", "resume", "disconnect", "callback", "transfer", "conference", "recording", "complete"];
+    readonly voice: readonly ["answer", "decline", "start-call", "mute", "hold", "resume", "disconnect", "callback", "transfer", "lead", "conference", "recording", "complete"];
     readonly chat: readonly ["accept", "reject", "pause", "resume", "complete"];
     readonly email: readonly ["accept", "reject", "complete"];
 };
@@ -456,9 +501,49 @@ export type VoiceTaskCommand = {
 /** Issuable only in `completing`, under the `callback` capability. Carries no destination. */
  | {
     type: "callback";
-} | {
+}
+/** Blind: hand the customer to `destination` with nobody consulted. Gated by `blindTransfer`. */
+ | {
+    type: "transfer";
+    destination: string;
+    action?: never;
+}
+/** Park the customer and call `destination` first. Gated by `consultTransfer`. */
+ | {
     type: "transfer";
+    action: "consult";
     destination: string;
+}
+/** Hand the customer to the consulted destination and leave. Needs `Task.consultation`. */
+ | {
+    type: "transfer";
+    action: "complete";
+}
+/** Drop the consulted destination and return to the customer. Needs `Task.consultation`. */
+ | {
+    type: "transfer";
+    action: "cancel";
+}
+/** Ask a lead to join, with a note. Gated by `consultLead`. */
+ | {
+    type: "lead";
+    action: "request";
+    note?: string;
+}
+/** Withdraw a standing request. Needs `Task.lead` with status `requested`. */
+ | {
+    type: "lead";
+    action: "cancel";
+}
+/** The lead keeps the customer; the agent's task ends `transferred`. Needs `Task.assisting`. */
+ | {
+    type: "lead";
+    action: "take-over";
+}
+/** The lead drops; the agent continues. The lead's task ends `left`. Needs `Task.assisting`. */
+ | {
+    type: "lead";
+    action: "leave";
 } | {
     type: "conference";
     participant: string;
@@ -636,9 +721,33 @@ export interface TeamMember {
  * Published only to an agent entitled to one. Its presence is the permission -- nothing else
  * makes somebody a lead, and there is no separate flag to fall out of step with the data.
  */
+/** A member asking this lead to join their call. */
+export interface LeadRequest {
+    id: string;
+    memberId: UserId;
+    taskId: TaskId;
+    note?: string;
+    since: IsoTimestamp;
+}
 export interface TeamRoster {
     members: TeamMember[];
     breakControl?: true;
+    /** Present when this lead may join a member's call on request. */
+    consultControl?: true;
+    /** Omitted when the lead may not be asked; `[]` when nobody is asking. */
+    requests?: LeadRequest[];
+}
+export type TeamConsultCommand = {
+    type: "join";
+    requestId: string;
+} | {
+    type: "decline";
+    requestId: string;
+    reason?: string;
+};
+export interface TeamConsultCommandRequest {
+    commandId: string;
+    command: TeamConsultCommand;
 }
 export type TeamBreakCommand = {
     type: "decide";
@@ -805,6 +914,8 @@ export interface Connection<C extends Channel = Channel> {
     endBreak?(): Promise<BreakEndResult>;
     /** Required when the adapter publishes a `TeamRoster` carrying `breakControl`. */
     executeTeamBreak?(request: TeamBreakCommandRequest): Promise<TeamCommandResult>;
+    /** Required when the adapter publishes a `TeamRoster` carrying `consultControl`. */
+    executeTeamConsult?(request: TeamConsultCommandRequest): Promise<TeamCommandResult>;
     /** Required of every voice adapter: all voice audio lands in Omni. */
     openMedia?(request: OpenMediaRequest): Promise<OpenMediaResult>;
 }

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",
-        "callback", "transfer", "conference", "recording", "complete"],
+        "callback", "transfer", "lead", "conference", "recording", "complete"],
     chat: ["accept", "reject", "pause", "resume", "complete"],
     email: ["accept", "reject", "complete"],
 };

package/dist/testing.js

@@ -76,6 +76,8 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         }
         if (snapshot?.team?.breakControl === true)
             requireMethod("executeTeamBreak", "the roster carries breakControl");
+        if (snapshot?.team?.consultControl === true)
+            requireMethod("executeTeamConsult", "the roster carries consultControl");
         if (publishesUserIds(snapshot))
             requireMethod("describeUsers", "the snapshot publishes a UserId");
         // Capacity is stated, not requested: nothing may be allocated until it is, so a connection

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, callback: true, blindTransfer: true, conference: true, recording: true,
+        agentDisconnect: true, callback: true, blindTransfer: true, consultTransfer: true, consultLead: 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 }),
@@ -502,6 +502,61 @@ function validateHandlingHistory(value, path, into) {
         }
     });
 }
+/** Present only while consulting, and only on voice: elsewhere there is nobody to consult. */
+function validateConsultation(value, channel, path, into) {
+    if (value === undefined)
+        return;
+    if (!into.require(channel === "voice", "task.consultation.channel", path, `a ${channel} task cannot carry a consultation`))
+        return;
+    if (!isPlainObject(value)) {
+        into.add("task.consultation.shape", path, "a consultation must be an object when present");
+        return;
+    }
+    into.filled(value.destination, "task.consultation.destination", `${path}.destination`, "a consultation names the destination being consulted");
+    if (value.label !== undefined) {
+        into.filled(value.label, "task.consultation.label", `${path}.label`, "a label must not be empty when present");
+    }
+    if (value.since !== undefined)
+        into.timestamp(value.since, "task.consultation.since", `${path}.since`);
+}
+const LEAD_STATUSES = membersOf({ requested: true, joined: true });
+/** The agent's request for a lead. Voice only; `joined` names the lead, `requested` cannot. */
+function validateLead(value, channel, path, into) {
+    if (value === undefined)
+        return;
+    if (!into.require(channel === "voice", "task.lead.channel", path, `a ${channel} task cannot carry a lead request`))
+        return;
+    if (!isPlainObject(value)) {
+        into.add("task.lead.shape", path, "lead must be an object when present");
+        return;
+    }
+    if (into.oneOf(value.status, LEAD_STATUSES, "task.lead.status", `${path}.status`)) {
+        if (value.status === "joined") {
+            into.require(isUserId(value.leadId), "task.lead.leadId", `${path}.leadId`, "a joined lead is named by their user id");
+        }
+        else {
+            into.require(value.leadId === undefined, "task.lead.leadId.unexpected", `${path}.leadId`, "nobody has joined a requested lead, so there is no lead to name");
+        }
+    }
+    if (value.note !== undefined)
+        into.filled(value.note, "task.lead.note", `${path}.note`, "a note must not be empty when present");
+    into.timestamp(value.since, "task.lead.since", `${path}.since`);
+}
+/** The lead's own task for a call they joined. Voice only. */
+function validateAssisting(value, channel, path, into) {
+    if (value === undefined)
+        return;
+    if (!into.require(channel === "voice", "task.assisting.channel", path, `a ${channel} task cannot be a joined call`))
+        return;
+    if (!isPlainObject(value)) {
+        into.add("task.assisting.shape", path, "assisting must be an object when present");
+        return;
+    }
+    into.require(isUserId(value.memberId), "task.assisting.memberId", `${path}.memberId`, "a joined call names the member who asked");
+    if (value.note !== undefined)
+        into.filled(value.note, "task.assisting.note", `${path}.note`, "a note must not be empty when present");
+    into.timestamp(value.since, "task.assisting.since", `${path}.since`);
+}
 export function validateTask(task, context, path = "task") {
     const into = new Collector();
     validateTaskInto(task, context, path, into);
@@ -537,6 +592,9 @@ function validateTaskInto(task, context, path, into) {
     validateBrowsers(task.browsers, `${path}.browsers`, into);
     validateTaskAttributes(task.attributes, `${path}.attributes`, into);
     validateHandlingHistory(task.handlingHistory, `${path}.handlingHistory`, into);
+    validateConsultation(task.consultation, context.channel, `${path}.consultation`, into);
+    validateLead(task.lead, context.channel, `${path}.lead`, into);
+    validateAssisting(task.assisting, context.channel, `${path}.assisting`, into);
     const capabilities = task.capabilities;
     if (!isPlainObject(capabilities)) {
         into.add("task.capabilities.shape", `${path}.capabilities`, "a task needs a capabilities object");
@@ -556,6 +614,7 @@ function validateTaskInto(task, context, path, into) {
                 validateCustomCapabilities(declared, `${path}.capabilities.custom`, into);
                 break;
             case "blindTransfer":
+            case "consultTransfer":
             case "conference":
                 validateDestinationDirectory(declared, `${path}.capabilities.${name}`, into);
                 break;
@@ -650,6 +709,36 @@ function validateTeamRosterInto(roster, path, into) {
     if (roster.breakControl !== undefined) {
         into.require(roster.breakControl === true, "team.breakControl", `${path}.breakControl`, "breakControl is declared by presence: send true or omit it");
     }
+    if (roster.consultControl !== undefined) {
+        into.require(roster.consultControl === true, "team.consultControl", `${path}.consultControl`, "consultControl is declared by presence: send true or omit it");
+    }
+    if (roster.requests !== undefined) {
+        // Requests are what a lead acts on, so a lead who may not act has no business receiving them.
+        into.require(roster.consultControl === true, "team.requests.capability", `${path}.requests`, "requests require consultControl: a lead who may not join has nothing to decide");
+        if (!Array.isArray(roster.requests)) {
+            into.add("team.requests.shape", `${path}.requests`, "requests must be an array when present");
+        }
+        else {
+            const seenRequests = new Set();
+            roster.requests.forEach((request, index) => {
+                const at = `${path}.requests[${index}]`;
+                if (!isPlainObject(request)) {
+                    into.add("team.request.shape", at, "each request must be an object");
+                    return;
+                }
+                if (into.filled(request.id, "team.request.id", `${at}.id`, "a request needs an id")) {
+                    if (seenRequests.has(request.id))
+                        into.add("team.request.unique", `${at}.id`, `duplicate request id: ${request.id}`);
+                    seenRequests.add(request.id);
+                }
+                into.require(isUserId(request.memberId), "team.request.memberId", `${at}.memberId`, "a request names the member asking");
+                into.require(isTaskId(request.taskId), "team.request.taskId", `${at}.taskId`, "a request names the task the lead would join");
+                if (request.note !== undefined)
+                    into.filled(request.note, "team.request.note", `${at}.note`, "a note must not be empty when present");
+                into.timestamp(request.since, "team.request.since", `${at}.since`);
+            });
+        }
+    }
     if (!Array.isArray(roster.members)) {
         into.add("team.members.shape", `${path}.members`, "a roster must carry a members array");
         return;
@@ -770,6 +859,8 @@ function validateTaskOutcome(value, path, into) {
             // Only the phases in which a task is still waiting on somebody can expire.
             into.oneOf(value.phase, EXPIRABLE_PHASES, "event.taskEnded.outcome.expired", `${path}.phase`);
             break;
+        case "left":
+            break;
         case "failed":
             if (!isPlainObject(value.failure)) {
                 into.add("event.taskEnded.outcome.failed", `${path}.failure`, "a failed outcome must carry a failure");

package/guide.md

@@ -337,6 +337,8 @@ type TaskCapabilities<C extends Channel = Channel> =
         agentDisconnect?: true;
         callback?: true;
         blindTransfer?: true | DestinationDirectory;
+        consultTransfer?: true | DestinationDirectory;
+        consultLead?: true;
         conference?: true | DestinationDirectory;
         recording?: true;
       }
@@ -421,6 +423,25 @@ type TaskCompletion =
   | { completionMode: "agent-command"; completionAllowance?: DurationSeconds }
   | { completionMode: "provider-automatic"; completionAllowance: DurationSeconds };
 
+type TaskConsultation = {
+  destination: string;
+  label?: string;
+  since?: IsoTimestamp;
+};
+
+type TaskLead = {
+  status: "requested" | "joined";
+  leadId?: UserId;
+  note?: string;
+  since: IsoTimestamp;
+};
+
+type TaskAssisting = {
+  memberId: UserId;
+  note?: string;
+  since: IsoTimestamp;
+};
+
 type Task<C extends Channel = Channel> = {
   id: TaskId;
   title: string;
@@ -433,7 +454,11 @@ type Task<C extends Channel = Channel> = {
   reference?: string;
   attributes?: TaskAttribute[];
   handlingHistory?: TaskHandlingStep[];
-} & TaskCompletion;
+} & TaskCompletion & (
+  C extends "voice"
+    ? { consultation?: TaskConsultation; lead?: TaskLead; assisting?: TaskAssisting }
+    : { consultation?: never; lead?: never; assisting?: never }
+);
 
 type AcceptanceMode =
   | "no-preference"
@@ -445,6 +470,7 @@ type TaskOutcome =
   | { type: "transferred"; destination?: string }
   | { type: "cancelled"; reason?: string }
   | { type: "expired"; phase: "pending" | "confirmed" | "preparing" }
+  | { type: "left" }
   | { type: "failed"; failure: ProtocolFailure };
 ```
 
@@ -462,6 +488,7 @@ const TASK_COMMAND_NAMES = {
     "disconnect",
     "callback",
     "transfer",
+    "lead",
     "conference",
     "recording",
     "complete",
@@ -484,7 +511,14 @@ type VoiceTaskCommand =
   | { type: "resume" }
   | { type: "disconnect" }
   | { type: "callback" }
-  | { type: "transfer"; destination: string }
+  | { type: "transfer"; destination: string; action?: never }
+  | { type: "transfer"; action: "consult"; destination: string }
+  | { type: "transfer"; action: "complete" }
+  | { type: "transfer"; action: "cancel" }
+  | { type: "lead"; action: "request"; note?: string }
+  | { type: "lead"; action: "cancel" }
+  | { type: "lead"; action: "take-over" }
+  | { type: "lead"; action: "leave" }
   | { type: "conference"; participant: string; action: "add" | "remove" }
   | { type: "recording"; action: "start" | "pause" | "resume" | "stop" }
   | ({ type: "complete" } & DispositionPayload);
@@ -567,11 +601,25 @@ type TeamMember = {
   break?: BreakApproval;
 };
 
+type LeadRequest = {
+  id: string;
+  memberId: UserId;
+  taskId: TaskId;
+  note?: string;
+  since: IsoTimestamp;
+};
+
 type TeamRoster = {
   members: TeamMember[];
   breakControl?: true;
+  consultControl?: true;
+  requests?: LeadRequest[];
 };
 
+type TeamConsultCommand =
+  | { type: "join"; requestId: string }
+  | { type: "decline"; requestId: string; reason?: string };
+
 type TeamBreakCommand =
   | { type: "decide"; memberId: UserId; decision: "granted" | "denied"; reason?: string }
   | { type: "policy"; policy: "ask" | "auto-approve" | "suspended" }
@@ -1427,6 +1475,7 @@ surface in one place, and what obliges an adapter to implement each one.
 | `cancelBreak(requestId)` | `sessionCapabilities.breaks` is declared. |
 | `endBreak()` | `sessionCapabilities.breaks` is declared. |
 | `executeTeamBreak(command)` | The adapter publishes a `TeamRoster` carrying `breakControl`. |
+| `executeTeamConsult(command)` | The adapter publishes a `TeamRoster` carrying `consultControl`. |
 | `openMedia(request)` | The manifest channel is `voice`. Every voice task's audio lands in Omni, so there is no voice adapter that does not implement it. |
 
 **The four break methods stand or fall together.** Declaring `sessionCapabilities.breaks` and then
@@ -1624,6 +1673,9 @@ time. Runtime conformance checks also require the task channel to match its prov
 | `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. |
+| `consultation` | Voice only. Present while the agent is consulting a transfer destination: who is being consulted, and since when where the provider records it. Its presence is what makes `transfer` `complete` and `cancel` issuable. `label` is a name for the destination -- a person, a queue -- not a phrase; the host supplies the verb. See **Consult transfer**. |
+| `lead` | Voice only. Present from the agent's request for a lead until the lead leaves or the request ends: `requested` while nobody has joined, `joined` with the lead's `leadId` once somebody has. See **Consulting a lead**. |
+| `assisting` | Voice only, on the lead's own task for a call they joined: which member asked, with their note. Its presence is what makes `lead` `take-over` and `leave` issuable. See **Consulting a lead**. |
 
 `TaskAttribute` entries carry typed detail alongside the task:
 
@@ -1659,7 +1711,9 @@ The canonical task transitions are:
 | `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` |
 | `paused` | Provider or agent resumes the task | `in-progress` |
+| `paused` | Agent cancels a consultation (`transfer` `cancel`) | `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 |
@@ -1947,13 +2001,15 @@ const taskCapabilities = {
 | `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. |
+| `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**. |
+| `consultLead` | Secondary menu item: Consult lead | Omni may ask a lead to join this call, with a note. The lead's decision reaches the agent on `Task.lead`. See **Consulting a lead**. |
 | `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. |
 | `dispositions` | Primary button: Complete | Omni may request task disposal with a provider disposition and notes. |
 
 ### Publishing codes and destinations
 
-Three capabilities accept an object instead of `true` when the provider wants Omni to render real
+Four capabilities accept an object instead of `true` when the provider wants Omni to render real
 choices. `true` remains valid and means "offer the control with nothing published".
 
 #### `dispositions`
@@ -1980,7 +2036,7 @@ capabilities: {
 With `dispositions: true` Omni shows a Complete control and sends `complete` with no code, because
 the provider published none.
 
-#### `blindTransfer` and `conference`
+#### `blindTransfer`, `consultTransfer` and `conference`
 
 ```ts
 capabilities: {
@@ -2012,6 +2068,42 @@ 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
+
+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.
+
+```ts
+// 1. Consult. The provider parks the customer and calls the destination; the task reports
+//    `paused` and carries `consultation` while the call to the destination stands.
+{ type: "transfer", action: "consult", destination: "+14155550111" }
+
+// 2a. Hand the customer to the consulted destination and leave.
+{ type: "transfer", action: "complete" }
+
+// 2b. Or drop the destination and return to the customer.
+{ type: "transfer", action: "cancel" }
+```
+
+`consult` is gated by the `consultTransfer` capability and takes a destination exactly as a blind
+transfer does, from the same kind of directory. While the consultation stands the task carries
+`consultation`, and that presence is what makes `complete` and `cancel` issuable -- they name no
+destination because there is exactly one they could mean. 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.
+
+`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
+the provider reports `task-media-ended`, any completion allowance runs, and the task ends with a
+`transferred` outcome naming the destination. `applied` on `cancel` says the destination is
+dropped; the task returns to `in-progress` with `consultation` gone. Omni waits for the
+provider's report of both, as it does for every command.
+
+A destination that does not answer is a consultation that ended: the provider clears
+`consultation`, returns the task to `in-progress`, and the agent is back with the customer.
+
 ### Chat capabilities
 
 | Capability | Omni UI | Contract |
@@ -2444,6 +2536,8 @@ A lead who also takes calls sees their team on the idle dashboard. `Snapshot.tea
 | --- | --- |
 | `members` | Every member of this lead's team, whatever their state. `[]` says the lead has a team with nobody in it; omitting the roster says something else entirely — see **Its presence is the permission** below. |
 | `breakControl` | Present when this lead decides their team's breaks, absent when they do not. |
+| `consultControl` | Present when this lead may join a member's call on request, absent when they may not. |
+| `requests` | The members currently asking this lead to join a call, each with the task and the note. Omitted when the lead may not be asked; `[]` when nobody is asking. See **Consulting a lead**. |
 
 | `TeamMember` field | Contract |
 | --- | --- |
@@ -2501,6 +2595,70 @@ on their own `BreakState`, or they are stopped from working with no way to see w
 What happens when no lead is online — auto-approving, for instance — is the provider's decision and is
 never expressed here.
 
+### Consulting a lead
+
+An agent on a call may ask a lead to join it -- a dispute that needs approval, a customer who
+asks for a manager, a moment the agent wants a second pair of ears. The capability is
+`consultLead` on the task; the lead's side is the roster, which is already the lead's view of the
+team, and a second lead method beside `executeTeamBreak`:
+
+```ts
+executeTeamConsult({ commandId, command: TeamConsultCommand }): Promise<TeamCommandResult>
+```
+
+Required when the roster carries `consultControl`, and gated by it exactly as `executeTeamBreak`
+is by `breakControl`. The flow, in order:
+
+```ts
+// 1. The agent asks, with a small note. Their task carries `lead` from here on.
+execute({ commandId, taskId: "call-42", command: { type: "lead", action: "request", note: "Refund dispute, needs approval" } })
+//    task.lead = { status: "requested", note: "Refund dispute, needs approval", since }
+
+// 2. Every lead entitled to it sees the request on their roster.
+//    team-updated: requests: [{ id: "req-7", memberId: "A-1", taskId: "call-42", note, since }]
+
+// 3. A lead joins, or declines.
+executeTeamConsult({ commandId, command: { type: "join", requestId: "req-7" } })
+executeTeamConsult({ commandId, command: { type: "decline", requestId: "req-7", reason: "In a call" } })
+```
+
+**On `join` the provider bridges three parties and the lead is on a task of their own**, on the
+same task id, arriving on the lead's connection as `task-offered` with `require-automatic-acceptance`
+-- the way a call an agent placed themselves arrives -- and carrying `assisting`. The agent's task
+moves to `lead: { status: "joined", leadId }`. A join is the lead's own act, so capacity does not
+trigger it; but from then on it is an outstanding task the provider counts against the lead's
+stated ceiling like any other, nothing more is allocated to the lead while it stands, and a
+provider whose lead is already at the ceiling answers the join `failed`.
+
+**On `decline`, or a request the agent withdraws with `{ type: "lead", action: "cancel" }`, the
+provider clears `lead` from the agent's task** and drops the request from every roster. Nothing
+else changes; the agent is still on the call.
+
+The lead then has two commands on their copy, gated by `assisting` being present, and a third
+choice that is no command at all:
+
+| The lead | The agent's task | The lead's task |
+| --- | --- | --- |
+| `{ type: "lead", action: "take-over" }` | `task-ended` with `{ type: "transferred", destination: leadId }`, straight from `in-progress`: **no `completing` window**, the agent is idle at once | Continues alone, and ends as any call does |
+| `{ type: "lead", action: "leave" }` | Continues; `lead` is cleared | `task-ended` with `{ type: "left" }` -- the call goes on without them |
+| Stays until the customer hangs up | `task-media-ended`, `completing`, its own disposition | The same, independently: **both have the disposal window** |
+
+`left` is the one outcome that ends a task without ending the call: this agent left a call that
+continues without them. It reads as neither a completion nor a cancellation, because it is
+neither.
+
+```ts
+const consultLeadCapable = {
+  channel: "voice",
+  capabilities: { hold: true, consultLead: true, dispositions: true },
+  phase: "in-progress",
+  lead: { status: "joined", leadId: "L-9", note: "Refund dispute, needs approval", since: "2026-08-21T09:04:00Z" },
+} satisfies Pick<Task<"voice">, "channel" | "capabilities" | "phase" | "lead">;
+```
+
+Lead and member alike are `UserId`s of this provider, so an adapter publishing them implements
+`describeUsers()`; names never travel on a task or a roster.
+
 ### A member waiting for a break
 
 A member who has asked for a break **keeps working** until Omni commits it, so asking is not an
@@ -2661,6 +2819,10 @@ declared:
 | `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. |
+| `transfer` with `action: "consult"` | The `consultTransfer` capability. Blind `transfer` is gated by `blindTransfer`; the two are declared and offered separately. |
+| `transfer` with `action: "complete"` or `"cancel"` | A consultation in progress -- `Task.consultation` present. Without one there is nothing to complete or cancel, and a provider that receives either answers `failed`. |
+| `lead` with `action: "request"` or `"cancel"` | The `consultLead` capability. `cancel` needs a request standing -- `Task.lead` with status `requested`. |
+| `lead` 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`. |
 | Everything else | Its own named capability. |
 
 Declining or rejecting a pending offer ends it without accepting or completing it. The provider
@@ -2841,6 +3003,9 @@ Every outcome ends the task for this agent. On `task-ended`, Omni:
 - releases task-scoped resources; and
 - selects another task or returns to the idle workspace.
 
+A `left` outcome ends the task for this agent alone: the call continues without them, as it does
+when a lead who joined it leaves -- see **Consulting a lead**.
+
 A successful `complete` or `transfer` command does not clear the task. Omni waits for `task-ended`.
 The `task-media-ended` event and the `completing` phase are likewise non-terminal. A replacement
 snapshot that no longer contains the task also clears it. Repeated `task-ended` delivery with the

package/package.json

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