@xema/omni-protocol 0.1.128 → 0.1.130

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/guide/voice.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # `@xema/omni-protocol`: Voice
2
2
 
3
- What is true of a call and of nothing else: preview, connecting back, ending a call, conference, every dial and its outcome, recording. Part of the contract in `guide.md`, which holds the terms, the shapes and the rules every file here relies on; a reference in bold names the file it points into where that is not this one.
3
+ What is true of a call and of nothing else: preview, connecting back, ending a call, adding to a call, every dial and its outcome, recording. Part of the contract in `guide.md`, which holds the terms, the shapes and the rules every file here relies on; a reference in bold names the file it points into where that is not this one.
4
4
 
5
5
  ## Preview: the agent presses Call
6
6
 
@@ -62,10 +62,10 @@ publication carried, counted from its receipt: the agent application infers no d
62
62
  was stated and reads no clock against another. Neither elapsed time nor submission changes the
63
63
  task phase: subsequent authoritative events state ringing, answer, audio and completion.
64
64
 
65
- An agent application must serialize manual clicks and its timer under the exact provider/login/task/assignment
65
+ An agent application must serialize manual clicks and its timer under the exact provider/session/task/assignment
66
66
  scope, allowing at most one unresolved submission. Recheck the current phase, deadline owner,
67
67
  assignment and whether an attempt already exists before dispatch. A new snapshot or policy update
68
- cancels an obsolete timer; login loss, disconnect, task end and assignment replacement fence its
68
+ cancels an obsolete timer; session loss, disconnect, task end and assignment replacement fence its
69
69
  callback. Reconnect past a deadline first reconciles current task and attempt state; it must not
70
70
  blindly submit again. An uncertain prior submission remains unresolved, without automatic retry.
71
71
  The provider atomically arbitrates any residual manual/timer race and does not accept a second
@@ -87,7 +87,7 @@ provider is told through `refused` exactly which rule, so the state that looked
87
87
  is named on its side. The task past preview has no deadline to wait for, so it carries neither
88
88
  field.
89
89
 
90
- **Provider execution and agent application controls are distinct.** Answer, hold/resume, conference,
90
+ **Provider execution and agent application controls are distinct.** Answer, hold/resume, add to call,
91
91
  lead assist and interaction completion are executed by the provider
92
92
  through the adapter. The task's applicable capability, phase, completion mode and command-specific
93
93
  prerequisites decide which controls are offered. Caller disconnect also executes at the provider. Microphone mute is agent application-owned, never a provider
@@ -99,7 +99,7 @@ own assignment, and two open at once carry two assignment ids. Restore them unch
99
99
  reconnect. Commands, audio, endings and history reports name the exact assignment; never retarget
100
100
  an old command to the newest interaction of a journey. `validateTaskCommandRequest` checks the
101
101
  request's assignment against the supplied published task and then its command prerequisites. The
102
- caller must select that task within the correct provider/login and recheck at the provider; the
102
+ caller must select that task within the correct provider/session and recheck at the provider; the
103
103
  validator cannot prove source freshness or authorization.
104
104
  `task-ended` retires only that interaction's resources. Another interaction, caller channel or IVR/queue
105
105
  portion must not be cleared because this task ended. Snapshot counts include all still-owned wrap
@@ -107,7 +107,7 @@ and active interactions; task completion is not caller hangup.
107
107
 
108
108
  **Voice describes the agent's interaction within the wider call.** The task defines that agent's
109
109
  workspace, tools, permissions, audio participation and completion work. The caller's channel may
110
- continue through IVR, queues, other agents, holds or conferences while this interaction ends or wraps.
110
+ continue through IVR, queues, other agents, holds or people added while this interaction ends or wraps.
111
111
  Completing this task ends this interaction responsibility; it is not evidence that the caller's channel
112
112
  or journey ended. Task audio describes this agent's attachment, not the lifetime of every party's
113
113
  connection. Commands retain their explicit targets and effects; task completion must not silently
@@ -116,7 +116,7 @@ become a caller-disconnect operation.
116
116
  **A task is never its audio.** A voice task represents the agent’s interaction: the call is offered when it is
117
117
  routed to the agent and accepted as its `acceptance` dictates, and its presence and phase follow
118
118
  the provider's reports about the work — never the audio. Wherever audio moves — an offer, a hold, a
119
- conference leg joining or leaving, a lead joining, a take-over, a connect-back — the audio follows
119
+ someone added joining or leaving, a lead joining, a take-over, a connect-back — the audio follows
120
120
  separately, arriving on `task-audio-started`, attaching through `openAudio` and ending with
121
121
  `task-audio-ended`. Omni does not ring,
122
122
  bridge, or hold a line. How the phone rings, whether it rings at all, and where legs join and leave
@@ -154,7 +154,7 @@ deadline.
154
154
 
155
155
  **The room shows the party being dialled.** From the moment any agent application dial places the party -- a
156
156
  dialpad call, a preview Call, a connect-back -- the `party` entry carries `stage: "ringing"` and
157
- the agent application's `dialId`, exactly as a conferenced entry does from its dial; `joined` on
157
+ the agent application's `dialId`, exactly as an added entry does from its dial; `joined` on
158
158
  the publication that follows the answered `dial-outcome` and never before it
159
159
  (`stream.taskUpdated.stage`); and no stage from the next publication on, so `joined` is transient
160
160
  and a later copy still carrying it is stale (`stream.taskUpdated.stage.lingering`). An agent application shows a
@@ -199,48 +199,58 @@ const immediateProviderCompletion = {
199
199
  | Capability | Omni UI | Contract |
200
200
  | --- | --- | --- |
201
201
  | `decline` | Pending-task button: Decline | The provider can decline a pending voice offer. Omni shows it only when local policy also permits declining. |
202
- | `hold` | Primary toggle: Hold | Omni may issue voice-task `hold` and `resume` commands. |
202
+ | `hold` | Primary toggle: Hold | Omni may issue voice-task `hold` and `resume` commands. Hold holds the caller: while the task is `paused` the party waits on hold and the agent keeps talking with everyone else on the call -- an added colleague, a lead who joined -- and `onCall` marks the party `held: true`. |
203
203
  | `endCall` | Primary button: End call | The provider ends the agent's channel and every channel the agent added; the caller continues on the provider's path. The task goes to its wrap. See **Ending a call, and removing one person from it**. |
204
204
  | `terminateCall` | Primary button: Terminate call | The provider ends the whole call: every channel on it, the agent's, the caller's, any colleague's and anyone else's. The task goes to its wrap. See **Ending a call, and removing one person from it**. |
205
205
  | `connectBack` | Completing-task button: Connect back | Omni may have the provider connect the agent back to the task's party while the task is `completing`, returning it to `in-progress` on the same task. Not offered where there is no `completing` window: `provider-automatic` with a zero allowance completes the task at provider end. See **Connecting back during completion**. |
206
206
  | `schedule` | Secondary menu item: Schedule | Omni may put a follow-up for this party on the calendar, from the call or from its wrap: a time, and a note. See **Scheduling a follow-up** in `guide/agent.md`. |
207
207
  | `leadAssist` | Secondary menu item: Lead assist | Omni may ask a lead to join this call, with a note. The lead's decision reaches the agent on `Task.leadAssist`. See **Lead assist** in `guide/lead.md`. |
208
- | `conference` | Secondary button: Conference | Omni may dial a destination into the active call, and remove one person from it -- a conferenced entry, one still ringing included, which calls the dial off, or the party, leaving the agent with the colleague. See **Ending a call, and removing one person from it**. |
208
+ | `addToCall` | Secondary button: Add to call | Omni may dial a contact or a typed number into the active call (`add-to-call`), and remove one person from it (`remove-from-call`) -- an added entry, one still ringing included, which calls the dial off, or the party, leaving the agent with the colleague. See **Ending a call, and removing one person from it**. |
209
209
  | `recording` | Overflow menu item: Recording | Per-task provider and agent application policies expose only their permitted recording actions; each has independent state and routing. |
210
210
  | `outcomes` | Primary button: Complete | Omni may request task completion with a provider outcome and notes. |
211
211
 
212
- ## `conference`
212
+ ## `addToCall`
213
213
 
214
214
  ```ts
215
215
  capabilities: {
216
- conference: {
217
- destinations: [
218
- { id: "tier2", label: "Tier 2 support" },
219
- { id: "main-menu", label: "Back to the main menu" },
220
- ],
221
- },
216
+ addToCall: { destinations: "any-number", contactIds: ["c-17", "c-20"] },
222
217
  }
223
218
  ```
224
219
 
225
220
  | Field | Contract |
226
221
  | --- | --- |
227
- | `destinations` | The items the control offers, at least one, with unique `id` values. Each is a button or a menu item on the agent computer. |
228
- | `id` | What Omni sends as `destinationId` on a `conference` command, and what the provider executes. |
229
- | `label` | What the agent reads. |
230
-
231
- **The protocol does not say what an item does.** A queue, an IVR menu, an outside line, a
232
- skill group -- that is the queue's configuration and the provider's business. The agent sees a
233
- list of labels, picks one, and Omni sends its `id`; the provider executes whatever the item is. No
234
- kind travels, nothing is typed, and a control with an empty directory has nothing to offer and is
235
- refused (`task.destinations.offer`). A control declared as bare `true` is refused for the same
236
- reason (`task.destinations.shape`): once nothing is typed, the directory is the control.
237
-
238
- **The provider chooses the supported destinations.** A published item may route to an IVR,
239
- queue, named agent or another configured destination. No destination kind is inferred from its
240
- label. The agent application offers only the directory attached to this task's `conference` capability,
241
- and sends the exact destination ID; it does not invent an agent picker or arbitrary dial target.
242
- The provider rechecks eligibility and executes the routing. Returning to an IVR or queue does not
243
- end the caller journey; a later assignment to the same agent is a new interaction.
222
+ | `destinations` | Whom the agent may bring in, in the dialpad's own words (`task.addToCall.destinations`): `contacts-only`, an entry of this provider's contacts; `any-number`, a number the agent types as well. |
223
+ | `contactIds` | Optional. The contacts this task offers, by id: a billing call may offer the billing specialist and the translator line and nothing else (`task.addToCall.contactIds`, `.unique`). Omitted, every contact is offered. Ids only -- the agent computer shows the names it holds -- and an add naming another contact is refused before it is sent (`command.addToCall.contactId.unlisted`). |
224
+
225
+ **The directory is the provider's contacts, at the agent computer.** It reaches the agent
226
+ computer once, with the snapshot, and again whenever it changes (`contacts-updated`), never on a
227
+ task, a call or a history. Each entry is a contact with a unique `id` (`contact.id`,
228
+ `contact.id.unique`), a name, and a number that may be withheld: a person the agent can reach -- a
229
+ colleague, a specialist, an outside number such as a translator line. Adding to the call brings a
230
+ person in while the agent stays; it is not a way to send the caller to a queue or a menu. The wire
231
+ names a contact by its `id` alone, and the agent computer shows the name it holds for it:
232
+
233
+ ```ts
234
+ const contacts: ContactEntry[] = [
235
+ { id: "c-17", name: "Ravi, billing specialist", number: "+914023400000" },
236
+ { id: "c-20", name: "Translator line" },
237
+ ];
238
+ ```
239
+
240
+ **Adding to the call names a contact by its id, or a typed number where the task allows any number.**
241
+
242
+ ```ts
243
+ { type: "add-to-call", dialId: "dial-7f2", contactId: "c-17" } // from the contacts
244
+ { type: "add-to-call", dialId: "dial-9b4", number: "+914023456789" } // typed
245
+ ```
246
+
247
+ A typed number on a `contacts-only` task is refused before it is sent
248
+ (`command.addToCall.number.contactsOnly`), and an add names one of the two, never both
249
+ (`command.addToCall.number.both`). The provider rechecks either and may refuse it
250
+ (`omni.destination-not-permitted`). A typed number becomes a contact: the provider enters it in its
251
+ contacts under an id of its own, publishes the entry, and names the person by that id from then
252
+ on -- on `onCall`, in the `added` step, on the dial's outcome and on a remove -- as it names
253
+ everyone else.
244
254
 
245
255
  ## Ending a call, and removing one person from it
246
256
 
@@ -250,12 +260,12 @@ provider. Two of them end the agent's part; they differ in what happens to the c
250
260
  ```ts
251
261
  { type: "end-call" } // the agent's channel and the channels the agent added end; the caller continues
252
262
  { type: "terminate-call" } // every channel on the call ends
253
- { type: "conference", action: "remove", party: true } // the customer leaves; the agent stays with the colleague
254
- { type: "conference", action: "remove", destinationId: "tier2" } // the conferenced person leaves; ringing, this calls the dial off
263
+ { type: "remove-from-call", party: true } // the customer leaves; the agent stays with the colleague
264
+ { type: "remove-from-call", contactId: "c-17" } // the added person leaves; ringing, this calls the dial off
255
265
  ```
256
266
 
257
267
  **`end-call` ends my part.** The agent's channel and every channel the agent added -- a
258
- conferenced colleague, a lead who joined -- end, and the caller continues on the path the
268
+ added colleague, a lead who joined -- end, and the caller continues on the path the
259
269
  provider decides: another IVR, a queue, a survey, or the end of the call. Gated by `endCall`.
260
270
 
261
271
  **Never from hold.** An `end-call` while the task is `paused` would leave the caller in the hold
@@ -280,8 +290,8 @@ capabilities** sets out. The provider knows which channels are the agent's and w
280
290
  the agent application sends the command and no channel list, and the provider rechecks ownership
281
291
  when it acts.
282
292
 
283
- `conference` `remove` takes one person off, named as the room names them, and the call goes on
284
- for the rest; it is gated by `conference`, since it only means something with a third person on
293
+ `addToCall` `remove` takes one person off, named as the room names them, and the call goes on
294
+ for the rest; it is gated by `addToCall`, since it only means something with a third person on
285
295
  the line. Removing the party leaves the agent with the colleague, a warm hand-over in reverse. A
286
296
  remove that would leave the agent alone is not a remove but an `end-call`, and a provider answers
287
297
  it `failed`.
@@ -314,7 +324,7 @@ inside Omni.
314
324
  ## Every dial has an outcome
315
325
 
316
326
  Four commands place a call: `dial()` from the idle dialpad, the `dial` command from preview, a
317
- `conference` `add`, and `connect-back`. Each is accepted or refused at once, and each then ends later
327
+ `addToCall` `add`, and `connect-back`. Each is accepted or refused at once, and each then ends later
318
328
  and apart from its answer -- the destination picks up, is busy, or never does -- and a dial placed
319
329
  late in a call routinely outlives the call. Nothing in between is reported: the wire says
320
330
  `dialling`, then says how it ended, once.
@@ -327,16 +337,16 @@ declare const connection: Connection<"voice">;
327
337
  declare const assignmentId: AssignmentId;
328
338
 
329
339
  // 1. Out, minted by the agent application.
330
- const result = await connection.execute({ assignmentId, command: { type: "conference", action: "add", dialId: "dial-7f2", destinationId: "tier2" } });
340
+ const result = await connection.execute({ assignmentId, command: { type: "add-to-call", dialId: "dial-7f2", contactId: "c-17" } });
331
341
 
332
342
  // 2. Back on the result, restated, so the agent application compares and confirms.
333
343
  expect(result).toEqual({ status: "dialling", dialId: "dial-7f2" });
334
344
 
335
345
  // 3. On the outcome, however late, against the task it belonged to.
336
- const outcome: ProviderEvent<"voice"> = { type: "dial-outcome", dialId: "dial-7f2", assignmentId, destinationId: "tier2", outcome: "no-answer", reason: "No route to destination" };
346
+ const outcome: ProviderEvent<"voice"> = { type: "dial-outcome", dialId: "dial-7f2", assignmentId, contactId: "c-17", outcome: "no-answer", reason: "No route to destination" };
337
347
 
338
348
  // 4. In the record, so a dial made before a take-over is placeable by whoever holds the task now.
339
- const step: TaskHistoryStep = { step: "unanswered", at: "2026-08-21T09:15:30Z", by: "A-12", dialId: "dial-7f2", destinationId: "tier2" };
349
+ const step: TaskHistoryStep = { step: "unanswered", at: "2026-08-21T09:15:30Z", by: "A-12", dialId: "dial-7f2", contactId: "c-17" };
340
350
  ```
341
351
 
342
352
  The identity is a correlation handle between agent application and provider and **is never shown to the
@@ -352,11 +362,11 @@ nothing, is refused (`result.status`). `validateResult(result, method, path, dia
352
362
  `dialId` the agent application sent for that reason.
353
363
 
354
364
  **The outcome is stated, once, either way.** A `dial-outcome` names the `dialId`, the task where
355
- there was one, the directory item it went to where there was one, and how the dial ended -- from a closed
365
+ there was one, the contact it went to where there was one, and how the dial ended -- from a closed
356
366
  set: `answered`, `busy`, `no-answer`, `unreachable`, `rejected`, `cancelled`, `unexplained`.
357
367
  `answered` is stated rather than read off somebody appearing on the call, because an agent application that infers
358
368
  success cannot tell "reached" from "still ringing". `cancelled` is the dialler calling the dial off
359
- before anyone answered -- the agent hanging up while a conferenced colleague still rings -- which is not a
369
+ before anyone answered -- the agent hanging up while an added colleague still rings -- which is not a
360
370
  `no-answer` the destination never gave. `unexplained` is the switch dropping the call with no cause among
361
371
  those named here: a statement about the switch, sent instead of the nearest cause it did not give.
362
372
  `reason` is the switch's own words, optional, and shown to the agent attributed to the switch rather
@@ -393,7 +403,7 @@ provider does report -- `busy`, `no-answer`, `unreachable`, `rejected` or `cance
393
403
  switch gave none, while one that reports none would be sending the generic failure this set exists
394
404
  to refuse. A provider that dials at all declares it: an idle
395
405
  dialpad requires it (`manifest.dialOutcomes.required`), and a task that declares `connectBack`
396
- or `conference` under a manifest without it is refused
406
+ or `addToCall` under a manifest without it is refused
397
407
  (`task.capability.dialOutcomes.required`). Off voice nothing dials, and the field is a compile
398
408
  error there.
399
409
 
@@ -405,14 +415,14 @@ knows the room:
405
415
  const onCall: OnCall[] = [
406
416
  { role: "party", since: "2026-08-21T09:12:00Z" },
407
417
  { role: "agent", userId: "A-12", since: "2026-08-21T09:12:04Z" },
408
- { role: "conferenced", destinationId: "tier2", dialId: "dial-7f2", stage: "joined", held: true, since: "2026-08-21T09:15:30Z" },
409
- { role: "conferenced", destinationId: "main-menu", dialId: "dial-3c9", stage: "ringing", since: "2026-08-21T09:16:02Z" },
418
+ { role: "added", contactId: "c-17", dialId: "dial-7f2", stage: "joined", held: true, since: "2026-08-21T09:15:30Z" },
419
+ { role: "added", contactId: "c-20", dialId: "dial-3c9", stage: "ringing", since: "2026-08-21T09:16:02Z" },
410
420
  ];
411
421
  ```
412
422
 
413
423
  `party` is the customer and `agent` a person by user id; neither was dialled from anywhere, so
414
- neither carries a destination. A `conferenced` colleague was, so the entry carries the
415
- `destinationId` of the directory item and, where an agent application's dial brought them, its `dialId`; a person
424
+ neither carries a destination. A `added` colleague was, so the entry carries the
425
+ `contactId` of its entry in the provider's contacts, a typed number's included, and, where an agent application's dial brought them, its `dialId`; a person
416
426
  the platform added itself carries none. `held: true` is presence as claim. A snapshot establishes state, so an agent application that attaches
417
427
  after a take-over reads the room from here rather than inferring it from a sequence of outcomes it
418
428
  never saw.
@@ -436,10 +446,10 @@ describing the room live was never followed by one saying it had emptied, and ev
436
446
  derived anything from it was wrong in a way that looked like its own bug.
437
447
 
438
448
  **A dialled entry is listed from the moment the dial is placed, not from the answer.** The entry is
439
- what `conference` `remove` names, and a destination the agent cannot call off while it rings is a
449
+ what `addToCall` `remove` names, and a destination the agent cannot call off while it rings is a
440
450
  customer kept waiting with no way back -- which is the very case `cancelled` exists for. The
441
- `conferenced` entry appears with its `dialId` when the dial is placed, and a `conference` `remove`
442
- naming a still-ringing `destinationId` calls that dial off, with `cancelled` as its outcome.
451
+ `added` entry appears with its `dialId` when the dial is placed, and a `addToCall` `remove`
452
+ naming a still-ringing `contactId` calls that dial off, with `cancelled` as its outcome.
443
453
 
444
454
  **The entry says where it stands.** A dialled entry carries `stage`: `ringing` until its dial is
445
455
  answered, `joined` after. The `dial-outcome` is the transition and the stage is the state, the same
@@ -548,7 +558,7 @@ recording, and what the agent sees is the recording. Retention is not a promise
548
558
  audio.
549
559
 
550
560
  Provider commands go only to `Connection.execute`; agent application commands go only to
551
- `HostRecording.execute`. Both name the assignment. Ids are opaque and scoped by provider login,
561
+ `HostRecording.execute`. Both name the assignment. Ids are opaque and scoped by provider session,
552
562
  task and recorder; they are never inferred from filenames or the current agent. Reconnect creates
553
563
  no recording; the recorder restates its list. There is no automatic restart, hand-over to another
554
564
  recorder, or stop on task hold or disconnect. Task removal does not prove recording stopped: