@xema/omni-protocol 0.1.129 → 0.1.131

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/GLOSSARY.md CHANGED
@@ -20,7 +20,7 @@ for orientation only: each platform's own documentation is the authority on its
20
20
  | **Agent computer** | The agent's screen and machine, where the agent application runs. | *Desktop*, *workstation*, *station*. |
21
21
  | **Manifest** | What a provider declares about itself up front: its name, channel, phones and features. | *Integration definition*, *app manifest* (Twilio Flex plugins, Salesforce call center definition file). |
22
22
  | **Channel** | The kind of work: voice, chat or email. | *Media type* (Genesys Cloud), *channel* (Amazon Connect, Salesforce Omni-Channel), *media* (NICE). |
23
- | **Login** | One signed-in session of one agent on one provider. | *Session*, *agent session*. |
23
+ | **Session** | One agent signed in on one provider, from sign-in until it ends. | *Session*, *agent session*. |
24
24
 
25
25
  ## The work
26
26
 
@@ -58,7 +58,7 @@ for orientation only: each platform's own documentation is the authority on its
58
58
  | **Mute** | Silence the agent's microphone. The caller hears nothing from the agent. | The same everywhere. |
59
59
  | **End call** | End the agent's part. The caller carries on to wherever the provider sends them, such as a survey. | *Leave*, *drop*, *hang up* (agent leg only). |
60
60
  | **Terminate call** | End the whole call for everyone. | *Disconnect all*, *end conversation*. |
61
- | **Conference** | Bring a colleague into the call. | *Conference*, *add participant*, *three-way call*. |
61
+ | **Add to call** | Bring someone onto the call while the agent stays; they leave when the agent ends their part. | *Conference*, *add participant*, *three-way call*. |
62
62
  | **Connect back** | Call the customer again after the call has ended, during the wrap. | *Callback from wrap*, *re-dial*. |
63
63
  | **Schedule** | Put a follow-up with this customer on the calendar. | *Scheduled callback* (Amazon Connect, Genesys Cloud), *personal callback* (Five9). |
64
64
  | **Callback requested** | The customer asked to be called back, or an agent arranged it. | *Queued callback* (Amazon Connect), *callback* (Genesys Cloud), *virtual hold*. |
package/README.md CHANGED
@@ -47,7 +47,7 @@ at such as `snapshot.tasks[0].browsers[1].url`, and a `message`.
47
47
 
48
48
  Some rules need more than the object in hand. A team member list never carries the agent it is published to,
49
49
  a lead's snapshot always carries one and nobody else's ever does — and a validator cannot know who
50
- is reading, or what their login declares, from the snapshot alone. `validateTeamMembers`,
50
+ is reading, or what their session declares, from the snapshot alone. `validateTeamMembers`,
51
51
  `validateSnapshot`, and `validateEventEnvelope` each take an optional final `{ self, capabilities }`
52
52
  from the `authenticated` state; given them, they report `team.member.self`, `team.request.self`,
53
53
  `team.required`, `team.unentitled`, `team.requests.capability`, and `team.requests.required`.
@@ -62,14 +62,14 @@ validateSnapshot(snapshot, manifest, "snapshot", { self: identity.id, capabiliti
62
62
 
63
63
  `testAdapter` validates the manifest, opens an authenticated session, connects, checks
64
64
  required capability methods, subscribes, validates the snapshot, every delivered event, and every
65
- authentication state published during the run — against the latest login — states a capacity,
65
+ authentication state published during the run — against the latest session — states a capacity,
66
66
  then unsubscribes and disconnects. `result.notTested` names what the run never reached — each
67
67
  optional part of a task, of the break state and team member list, each contribution, each event type — so a
68
68
  clean result is read for what it covers and not for the whole contract; `assertReached(result,
69
69
  subjects)` is the paired assertion.
70
70
 
71
71
  ```ts
72
- const context = { protocolVersion: OMNI_PROTOCOL_VERSION, loginId: "session-1", host: stillHost(report) };
72
+ const context = { protocolVersion: OMNI_PROTOCOL_VERSION, sessionId: "session-1", host: stillHost(report) };
73
73
  const result = await testAdapter(adapter, context, { collectOnly: true });
74
74
  expect(result.violations).toEqual([]);
75
75
  expect(result.disconnectWasClean).toBe(true);
@@ -102,14 +102,12 @@ const task = {
102
102
 
103
103
  **Switch on `command.action` with no `default`.** A `default` turns a future action into whatever
104
104
  the default does, silently; naming every arm means dropping one fails the build — indirectly, as a
105
- missing return — and keeps the narrowing that lets you read `destinationId` without a cast.
105
+ missing return — and keeps the narrowing that lets you read `dialId` without a cast.
106
106
 
107
107
  ```ts
108
108
  switch (command.action) {
109
- case "cold": return coldTransfer(command.destinationId);
110
- case "warm": return warmTransfer(command.destinationId);
111
- case "complete": return completeWarmTransfer();
112
- case "cancel": return cancelWarmTransfer();
109
+ case "add": return addToCall(command.dialId, command.contactId ?? command.number);
110
+ case "remove": return removeFromCall(command.party === true ? "party" : command.contactId);
113
111
  }
114
112
  ```
115
113
 
package/dist/index.d.ts CHANGED
@@ -27,8 +27,8 @@ export type UserId = string;
27
27
  /**
28
28
  * The provider's name for one assignment: the call routed to this agent, from the offer until the
29
29
  * task ends. Non-empty, opaque, unique within the provider and never reused while the provider is
30
- * still speaking about it -- a lead names a member's assignment from another login, so the scope is
31
- * the provider, not the login. What the platform calls its own record, and whether it reuses that
30
+ * still speaking about it -- a lead names a member's assignment from another session, so the scope is
31
+ * the provider, not the session. What the platform calls its own record, and whether it reuses that
32
32
  * name, is the adapter's business: a platform that reoffers a closed call under the same handle
33
33
  * seconds later is why the adapter, not the agent computer, is held to this. Scope it with `assignmentKey()`.
34
34
  */
@@ -108,7 +108,7 @@ export declare const DIAL_OUTCOMES: readonly ["answered", "busy", "no-answer", "
108
108
  * How the agent hears the call: on a `softphone`, where the host owns the audio and opens it
109
109
  * through `openAudio`, or on a `hardphone`, a handset the platform rings, where the host opens
110
110
  * nothing and only shows the call. A voice manifest lists the phones its platform supports, and
111
- * the host picks one for the login at authentication.
111
+ * the host picks one for the session at authentication.
112
112
  */
113
113
  export type Phone = "softphone" | "hardphone";
114
114
  export declare const PHONES: readonly ["softphone", "hardphone"];
@@ -124,7 +124,7 @@ export type PhoneChannelState = "ringing" | "active" | "held";
124
124
  export declare const PHONE_CHANNEL_STATES: readonly ["ringing", "active", "held"];
125
125
  /**
126
126
  * One call on the phone, as the phone sees it: ringing, the one active, or held. A bridge is one
127
- * channel, so a conference is one entry and its members are on the task's `onCall`. Where the call
127
+ * channel, so a call with people added is one entry and they are on the task's `onCall`. Where the call
128
128
  * is a task's, `assignmentId` names it and the two views agree; absent, the call is the phone's
129
129
  * alone -- an internal call on the extension, a lead's listening leg.
130
130
  */
@@ -134,7 +134,7 @@ export interface PhoneChannel {
134
134
  assignmentId?: AssignmentId;
135
135
  }
136
136
  /**
137
- * The phone's own view, published by a provider that declares `phoneStatus`: the device the login
137
+ * The phone's own view, published by a provider that declares `phoneStatus`: the device the session
138
138
  * is on, whether it can take a call, its own mute where the platform observes it, and its channels
139
139
  * -- one active at most, any number held. The task side says which of those calls are the agent's
140
140
  * work and where each stands; the phone side exists whether or not a task is behind a call. `muted`
@@ -142,7 +142,7 @@ export interface PhoneChannel {
142
142
  * never a softphone's, whose microphone is the host's and whose mute is the host's report.
143
143
  */
144
144
  export interface PhoneState {
145
- /** The agent's phone for this provider, as the host chose it for the login at connect: which of the manifest's phones the agent hears this provider's calls on. */
145
+ /** The agent's phone for this provider, as the host chose it for the session at connect: which of the manifest's phones the agent hears this provider's calls on. */
146
146
  phone: Phone;
147
147
  status: PhoneStatus;
148
148
  /** The phone's own mute, on a hardphone the platform observes; absent where it does not, or on a softphone. */
@@ -227,12 +227,12 @@ export interface Manifest<C extends Channel = Channel> {
227
227
  /**
228
228
  * The outcomes this platform distinguishes when a dial ends, `answered` and at least one way of
229
229
  * not reaching the destination. Required of a provider that dials at all -- an idle dialpad, or
230
- * a task that may conference or call back -- and forbidden off voice, where nothing dials.
230
+ * a task that may add to the call or call back -- and forbidden off voice, where nothing dials.
231
231
  */
232
232
  dialOutcomes?: C extends "voice" ? DialOutcome[] : never;
233
233
  /**
234
234
  * The phones this platform can put an agent on. Required of every voice manifest, and forbidden
235
- * off voice, where there is no call to hear. The host picks one of these per login.
235
+ * off voice, where there is no call to hear. The host picks one of these per session.
236
236
  */
237
237
  phones?: C extends "voice" ? Phone[] : never;
238
238
  /**
@@ -260,21 +260,21 @@ export interface SecretStore {
260
260
  delete(key: string): Promise<void>;
261
261
  }
262
262
  /**
263
- * A small store for one login's operational state -- what an adapter holds about open work that
263
+ * A small store for one session's operational state -- what an adapter holds about open work that
264
264
  * its platform cannot hold for it, such as the interaction legs a host reported. Kept by the host for
265
- * the life of the login, across a reload of the host, and cleared at sign-out. Never for anything
265
+ * the life of the session, across a reload of the host, and cleared at sign-out. Never for anything
266
266
  * sensitive: that is `SecretStore`, whose contract is that a host may clear it aggressively, and
267
267
  * clears it once the session has ended.
268
268
  */
269
- export interface LoginStore {
269
+ export interface SessionStore {
270
270
  get(key: string): Promise<string | undefined>;
271
271
  set(key: string, value: string): Promise<void>;
272
272
  delete(key: string): Promise<void>;
273
273
  }
274
274
  export interface AuthenticationContext {
275
275
  protocolVersion: number;
276
- /** Omni's identity for this login. The same value arrives later as `ConnectContext.loginId`. */
277
- loginId: string;
276
+ /** Omni's identity for this session. The same value arrives later as `ConnectContext.sessionId`. */
277
+ sessionId: string;
278
278
  /**
279
279
  * The zone the agent's day is reckoned in, as the host's clock has it, stated before any
280
280
  * identity exists so the first `authenticated` state already carries it. The same value arrives
@@ -289,7 +289,7 @@ export interface AuthenticationContext {
289
289
  */
290
290
  languages: readonly LanguageTag[];
291
291
  /**
292
- * How this login hears its calls, chosen by the host from the manifest's `phones`. Required for
292
+ * How this session hears its calls, chosen by the host from the manifest's `phones`. Required for
293
293
  * a voice provider and absent for any other. The same value arrives later as `ConnectContext.phone`.
294
294
  */
295
295
  phone?: Phone;
@@ -322,12 +322,12 @@ export interface AuthenticationFailure {
322
322
  export type ListeningMode = "listen" | "coach" | "join-call";
323
323
  export declare const LISTENING_MODES: readonly ["listen", "coach", "join-call"];
324
324
  /**
325
- * What this login may do, beyond any one task. It travels with the identity because it is part
326
- * of who the agent is on this provider: the provider knows the roles and says so at sign-in.
327
- * Current as of the latest `authenticated` state, never fixed for the login.
325
+ * What this user may do for the session, beyond any one task. It travels with the identity
326
+ * because it is part of who the agent is on this provider: the provider knows the roles and says
327
+ * so at sign-in. Current as of the latest `authenticated` state, never fixed for the session.
328
328
  */
329
329
  export interface UserCapabilities {
330
- /** This login may request a break. Requires the four break methods. */
330
+ /** This session may request a break. Requires the four break methods. */
331
331
  breaks?: true;
332
332
  /**
333
333
  * The platform lines calls up for this agent: the agent may press Next call while on one to
@@ -338,15 +338,48 @@ export interface UserCapabilities {
338
338
  /** The choices the team left to this person, with where each stands. Omitted when there are none. Requires `setPreference`. */
339
339
  preferences?: AgentPreference[];
340
340
  /**
341
- * This login leads a team. The flag alone turns on the team feature in the agent application:
342
- * the lead sees their members with their tasks and stats, and acts on them through `executeTeam`
343
- * with the authority the flag carries. No per-action permission rides beside it. The provider
344
- * assumes nothing of the switch: the application sends `lead-features` on every connect, and
345
- * only while it is on does the team reach the lead -- `team-updated` whole after the switch and
346
- * on any snapshot, then one member at a time as members change; to nobody else, ever.
341
+ * This session leads a team, with the lead capabilities it holds for the whole session. Its
342
+ * presence turns on the team feature in the agent application: the lead sees their members with
343
+ * their tasks and stats, and acts on them through `executeTeam` with the commands its lead
344
+ * capabilities allow, and no others. The provider assumes nothing of the switch: the
345
+ * application sends `lead-features` on every connect, and only while it is on does the team
346
+ * reach the lead -- `team-updated` whole after the switch and on any snapshot, then one member at
347
+ * a time as members change; to nobody else, ever.
347
348
  */
348
- lead?: true;
349
- }
349
+ lead?: LeadCapabilities;
350
+ }
351
+ /**
352
+ * What a lead may do, for the whole session: one key per lead command it allows, each stated by
353
+ * presence. Switching the team feature (`lead-features`) and leaving a call (`leave`) are every
354
+ * lead's and are not listed. At least one is stated: a session with none leads nobody.
355
+ */
356
+ export interface LeadCapabilities {
357
+ join?: true;
358
+ decline?: true;
359
+ listen?: true;
360
+ coach?: true;
361
+ joinCall?: true;
362
+ takeOverCall?: true;
363
+ decideBreakRequest?: true;
364
+ setBreakPolicy?: true;
365
+ forceBreak?: true;
366
+ endForcedBreak?: true;
367
+ setPolicy?: true;
368
+ }
369
+ /** The lead capability each lead command needs; `lead-features` and `leave` need none. */
370
+ export declare const LEAD_COMMAND_CAPABILITY: {
371
+ readonly join: "join";
372
+ readonly decline: "decline";
373
+ readonly listen: "listen";
374
+ readonly coach: "coach";
375
+ readonly "join-call": "joinCall";
376
+ readonly "take-over-call": "takeOverCall";
377
+ readonly "decide-break-request": "decideBreakRequest";
378
+ readonly "set-break-policy": "setBreakPolicy";
379
+ readonly "force-break": "forceBreak";
380
+ readonly "end-forced-break": "endForcedBreak";
381
+ readonly "set-policy": "setPolicy";
382
+ };
350
383
  /**
351
384
  * Only `authenticated` and `refreshing` know who the agent is and what they may do, and only
352
385
  * `authenticated` has something to expire. A state carrying more than it knows is a state Omni
@@ -477,7 +510,7 @@ export declare const MUTED_BY: readonly ["host", "station"];
477
510
  * What pressing Mute does on this host. `stream`: the host stops the audio it sends, and the
478
511
  * microphone keeps capturing. `station`: the host mutes the microphone itself at the operating
479
512
  * system, which every application on the machine then shares. A browser can only do the first;
480
- * a native host says which it does. Stated by the host on a softphone login, never inferred
513
+ * a native host says which it does. Stated by the host on a softphone session, never inferred
481
514
  * from what kind of application it is.
482
515
  */
483
516
  export type HostMute = "stream" | "station";
@@ -649,13 +682,13 @@ export interface HostGuarantees {
649
682
  /**
650
683
  * The host's Mute is its own control on any call and is never offered while the task is
651
684
  * `paused`; a mute standing when a hold begins stands through it. Required of a softphone
652
- * login's host and refused of any other, since a hardphone's mute is the handset's.
685
+ * session's host and refused of any other, since a hardphone's mute is the handset's.
653
686
  */
654
687
  muteUnavailableOnHold?: true;
655
688
  }
656
689
  export interface ProviderTimeScope {
657
690
  providerId: string;
658
- loginId: string;
691
+ sessionId: string;
659
692
  }
660
693
  /** Best-effort host estimate, never a provider observation or accuracy guarantee. The provider may ignore it and timestamp receipt itself. */
661
694
  export interface ProviderTimeEstimate extends ProviderTimeScope {
@@ -670,7 +703,7 @@ export interface Host {
670
703
  /** Voice softphone recording support; policy and destination remain per task. */
671
704
  recording?: HostRecording;
672
705
  guarantees: HostGuarantees;
673
- /** What pressing Mute does on this host. Stated on a softphone login, where the host holds the microphone; absent on a hardphone and off voice. */
706
+ /** What pressing Mute does on this host. Stated on a softphone session, where the host holds the microphone; absent on a hardphone and off voice. */
674
707
  mute?: HostMute;
675
708
  report(): HostReport;
676
709
  subscribe(listener: (report: HostReport) => void): Unsubscribe;
@@ -678,7 +711,7 @@ export interface Host {
678
711
  export type ConnectContext = {
679
712
  protocolVersion: number;
680
713
  /** The session that authenticated this connection. */
681
- loginId: string;
714
+ sessionId: string;
682
715
  /** Omni-side policy: whether the agent's tasks are accepted without asking them. Stated, never assumed: a host says which. */
683
716
  autoAcceptTasks: boolean;
684
717
  /**
@@ -689,9 +722,9 @@ export type ConnectContext = {
689
722
  timeZone: TimeZone;
690
723
  /** The same value passed as `AuthenticationContext.languages`: what the agent reads, most preferred first. */
691
724
  languages: readonly LanguageTag[];
692
- /** Where the adapter keeps this login's operational state across a reload of the host. */
693
- store: LoginStore;
694
- /** The same value passed as `AuthenticationContext.phone`: how this login hears its calls. Narrowed by the arms below. */
725
+ /** Where the adapter keeps this session's operational state across a reload of the host. */
726
+ store: SessionStore;
727
+ /** The same value passed as `AuthenticationContext.phone`: how this session hears its calls. Narrowed by the arms below. */
695
728
  phone?: Phone;
696
729
  /**
697
730
  * The host's report of the agent's station, to consult before declaring the agent ready to the
@@ -731,11 +764,11 @@ export type ConnectContext = {
731
764
  });
732
765
  export type TransportStatus = "connecting" | "active" | "error";
733
766
  /**
734
- * What revives a connection that reported `error`: `reconnect` -- the login is good, dispose this
767
+ * What revives a connection that reported `error`: `reconnect` -- the session is good, dispose this
735
768
  * connection and call `connect()` again -- or `reauthenticate` -- run the authentication flow
736
769
  * first. The adapter knows which; the host acts on its word.
737
770
  */
738
- /** What revives an errored connection: `displaced` says another client took the login, and nothing revives this one until the agent takes it back. */
771
+ /** What revives an errored connection: `displaced` says another client took the session, and nothing revives this one until the agent takes it back. */
739
772
  export type TransportRecovery = "reconnect" | "reauthenticate" | "displaced";
740
773
  /** Every field is optional: a provider sends what it knows and omits what it does not. */
741
774
  export interface Contact {
@@ -746,6 +779,15 @@ export interface Contact {
746
779
  email?: Lockable<string>;
747
780
  attributes?: Attribute[];
748
781
  }
782
+ /**
783
+ * One entry of the provider's contacts, the agent computer's directory: a unique `id`, which is how
784
+ * the wire names this contact on a call, in its history and on a dial's outcome, with the name and
785
+ * the number, either of which may be absent or withheld. The agent computer shows the name it holds
786
+ * for an id.
787
+ */
788
+ export interface ContactEntry extends Contact {
789
+ id: string;
790
+ }
749
791
  export interface ScheduledActivity {
750
792
  id: string;
751
793
  title: string;
@@ -766,17 +808,15 @@ export interface OutcomeRules {
766
808
  codes?: OutcomeCode[];
767
809
  }
768
810
  /**
769
- * One item the queue configured for the agent to send a contact to: a button or a menu item. The
770
- * protocol does not say what it does -- a queue, a menu, a line -- the provider executes it when a
771
- * command names its `id`. The provider may publish a queue, IVR, named agent or other supported destination; the host does not invent one.
811
+ * Whom the agent may add to the call, in the dialpad's own words: `contacts-only`, an entry of
812
+ * this provider's contacts, named by its `id`; or `any-number`, a number the agent types as well.
813
+ * `contactIds` narrows the contacts this task offers to those ids -- a billing call offering the
814
+ * billing specialist and the translator line -- and omitted, every contact is offered. Ids only: the names are the
815
+ * agent computer's, from the contacts.
772
816
  */
773
- export interface Destination {
774
- id: string;
775
- label: string;
776
- }
777
- /** The items a conference control offers. Nothing is typed; the agent picks one. */
778
- export interface DestinationDirectory {
779
- destinations: Destination[];
817
+ export interface AddToCallCapability {
818
+ destinations: DialDestinations;
819
+ contactIds?: string[];
780
820
  }
781
821
  export interface CustomCapability {
782
822
  id: string;
@@ -814,7 +854,7 @@ export type TaskCapabilities<C extends Channel = Channel> = C extends "voice" ?
814
854
  schedule?: Lockable<true>;
815
855
  /** Ask a lead to join this call, with a note. The lead's decision arrives on `Task.leadAssist`. */
816
856
  leadAssist?: Lockable<true>;
817
- conference?: Lockable<DestinationDirectory>;
857
+ addToCall?: Lockable<AddToCallCapability>;
818
858
  recording?: Lockable<TaskRecordingPolicy>;
819
859
  } : C extends "chat" ? SharedTaskCapabilities & {
820
860
  decline?: Lockable<true>;
@@ -848,19 +888,19 @@ export interface Browser {
848
888
  }
849
889
  /**
850
890
  * A tab the task brought: fixed at the task's definition -- count and details -- with why it is
851
- * there, whether its session is shared across tasks, and whether the agent may read its URL. The
891
+ * there, whether its profile is shared across tasks, and whether the agent may read its URL. The
852
892
  * union is what makes a reusing browser with no scheme fail to compile rather than inherit a
853
- * default -- which is how two tasks end up sharing a session nobody intended.
893
+ * default -- which is how two tasks end up sharing a profile nobody intended.
854
894
  */
855
895
  export type TaskBrowser = Browser & {
856
896
  purpose: string;
857
897
  /** Hide this tab's URL from the agent in Omni's chrome. Omitted, the URL shows as any browser's does; a provider says `hidden` where the URL carries what the agent may not read. */
858
898
  urlVisibility?: UrlVisibility;
859
899
  } & ({
860
- sharedSession: false;
900
+ sharedProfile: false;
861
901
  isolationScheme?: never;
862
902
  } | {
863
- sharedSession: true;
903
+ sharedProfile: true;
864
904
  isolationScheme: BrowserIsolationScheme;
865
905
  });
866
906
  /** A tab the agent opened in the personal workspace: theirs, as many as they like, and never on the wire. */
@@ -903,7 +943,7 @@ export type TaskAttribute = TaskAttributeBase & ({
903
943
  type: "timestamp";
904
944
  at: IsoTimestamp;
905
945
  });
906
- export type HistoryStep = "arrived" | "self-service" | "queued" | "offered" | "answered" | "held" | "muted" | "transferred" | "conferenced" | "unanswered" | "callback-requested";
946
+ export type HistoryStep = "arrived" | "self-service" | "queued" | "offered" | "answered" | "held" | "muted" | "transferred" | "added" | "unanswered" | "callback-requested";
907
947
  /**
908
948
  * The call record: the steps that brought the task here, one entry per occurrence and oldest
909
949
  * first, and what they add up to before this agent -- stated by the provider from its own record,
@@ -926,11 +966,12 @@ export interface TaskHistoryStep {
926
966
  step: HistoryStep;
927
967
  at: IsoTimestamp;
928
968
  /**
929
- * On a step that dialled -- `transferred`, `conferenced`, `unanswered` -- the host's identity for
930
- * that dial when a host placed it, and the directory item it went to. Neither belongs on any other step.
969
+ * On a step that dialled -- `transferred`, `added`, `unanswered` -- the host's identity for
970
+ * that dial when a host placed it, and the contact it went to, by the contacts entry's `id`. Neither
971
+ * belongs on any other step.
931
972
  */
932
973
  dialId?: DialId;
933
- destinationId?: string;
974
+ contactId?: string;
934
975
  /**
935
976
  * Reported, never derived. An entry may be written while its leg is still running, so there is
936
977
  * no end to subtract from -- and omitted is the honest report of that, where nought would
@@ -961,18 +1002,20 @@ export type TaskCompletion = {
961
1002
  completionMode: "provider-automatic";
962
1003
  wrapAllowance: DurationSeconds;
963
1004
  };
964
- export type OnCallRole = "party" | "agent" | "conferenced";
1005
+ export type OnCallRole = "party" | "agent" | "added";
965
1006
  /** Where a dialled entry stands: `ringing` until its dial is answered, `joined` after. */
966
1007
  export type OnCallStage = "ringing" | "joined";
967
- export declare const ON_CALL_ROLES: readonly ["party", "agent", "conferenced"];
1008
+ export declare const ON_CALL_ROLES: readonly ["party", "agent", "added"];
968
1009
  /**
969
1010
  * Somebody on the call, or being brought onto it, as the provider states it: who, since when, and
970
- * whether they are held aside. `party` is the customer; `agent` a person, by user id; `conferenced`
1011
+ * whether they are held aside. `party` is the customer; `agent` a person, by user id; `added`
971
1012
  * someone a dial is bringing in -- listed from the moment the dial is placed, so the agent can call
972
- * it off while it rings -- carrying the dial when a host placed it, the address either way, and the
1013
+ * it off while it rings -- carrying the dial when a host placed it, the contact either way (the
1014
+ * `contactId` of its entry in the provider's contacts, a typed number included), and the
973
1015
  * `stage` it has reached: `ringing` until the dial is answered, `joined` after, stated so a snapshot
974
1016
  * says who is present without anyone having seen the outcome. Nobody ringing is held. `label` names
975
- * a destination -- a person, a queue -- not a phrase. At most one `party`. The `party`
1017
+ * a person or a line -- not a phrase. `coaching` marks a lead the agent alone hears,
1018
+ * present while they coach and gone when they stop. At most one `party`. The `party`
976
1019
  * carries a `stage` while being dialled -- by any host dial, a dialpad call, a preview Call or a
977
1020
  * connect-back, carrying its `dialId`, or by a callback the platform places itself, carrying none --
978
1021
  * `ringing` from the moment the dial is placed, `joined` on the publication that follows its
@@ -994,9 +1037,10 @@ export type OnCall = {
994
1037
  } | {
995
1038
  role: "agent";
996
1039
  userId: UserId;
1040
+ coaching?: true;
997
1041
  } | {
998
- role: "conferenced";
999
- destinationId: string;
1042
+ role: "added";
1043
+ contactId: string;
1000
1044
  stage: OnCallStage;
1001
1045
  dialId?: DialId;
1002
1046
  label?: string;
@@ -1158,7 +1202,7 @@ export type TaskOutcome = {
1158
1202
  failure: ProtocolFailure;
1159
1203
  };
1160
1204
  export declare const TASK_COMMAND_NAMES: {
1161
- readonly voice: readonly ["answer", "decline", "dial", "hold", "resume", "end-call", "terminate-call", "connect-back", "lead-assist", "conference", "recording", "schedule", "complete"];
1205
+ readonly voice: readonly ["answer", "decline", "dial", "hold", "resume", "end-call", "terminate-call", "connect-back", "lead-assist", "add-to-call", "remove-from-call", "recording", "schedule", "complete"];
1162
1206
  readonly chat: readonly ["accept", "decline", "pause", "resume", "schedule", "complete"];
1163
1207
  readonly email: readonly ["accept", "decline", "schedule", "complete"];
1164
1208
  };
@@ -1208,29 +1252,36 @@ export type VoiceTaskCommand = {
1208
1252
  type: "lead-assist";
1209
1253
  action: "cancel";
1210
1254
  }
1211
- /** Dial the directory item `destinationId` into the call. Gated by `conference`. */
1255
+ /**
1256
+ * Dial a contact into the call: an entry of the provider's contacts by `contactId`, or, where the
1257
+ * capability allows `any-number`, a `number` the agent typed, which the provider enters in its
1258
+ * contacts under an id of its own. Gated by `addToCall`.
1259
+ */
1212
1260
  | {
1213
- type: "conference";
1214
- action: "add";
1261
+ type: "add-to-call";
1262
+ dialId: DialId;
1263
+ contactId: string;
1264
+ number?: never;
1265
+ } | {
1266
+ type: "add-to-call";
1215
1267
  dialId: DialId;
1216
- destinationId: string;
1268
+ number: string;
1269
+ contactId?: never;
1217
1270
  }
1218
1271
  /**
1219
1272
  * Remove one person from the call, named as `onCall` names them, and the call goes on for the
1220
- * rest: a `conferenced` entry by its `destinationId`, which while it still rings calls the dial
1273
+ * rest: a `added` entry by its `contactId`, which while it still rings calls the dial
1221
1274
  * off, or the `party`, leaving the agent with the colleague. A remove that would leave the agent
1222
1275
  * alone is `end-call`, and a provider answers it `failed`.
1223
1276
  */
1224
1277
  | {
1225
- type: "conference";
1226
- action: "remove";
1227
- destinationId: string;
1278
+ type: "remove-from-call";
1279
+ contactId: string;
1228
1280
  party?: never;
1229
1281
  } | {
1230
- type: "conference";
1231
- action: "remove";
1282
+ type: "remove-from-call";
1232
1283
  party: true;
1233
- destinationId?: never;
1284
+ contactId?: never;
1234
1285
  } | (RecordingCommand & {
1235
1286
  source: "provider";
1236
1287
  }) | ({
@@ -1547,7 +1598,7 @@ export interface Shift {
1547
1598
  events?: ShiftEvent[];
1548
1599
  }
1549
1600
  /**
1550
- * The lead's view of their team: published to a login that declares `capabilities.lead` while the
1601
+ * The lead's view of their team: published to a user whose capabilities include `lead` while the
1551
1602
  * lead has the team feature on, and to nobody else. Whole on `team-updated` -- after the switch,
1552
1603
  * and on any snapshot -- and from then on one member at a time: `team-member-updated` carries the
1553
1604
  * member whole, so applying it twice changes nothing, and `team-member-removed` takes one off.
@@ -1761,7 +1812,7 @@ export type PreferenceResult = {
1761
1812
  };
1762
1813
  export interface Snapshot<C extends Channel = Channel> {
1763
1814
  transport: TransportStatus;
1764
- loginId: string;
1815
+ sessionId: string;
1765
1816
  /**
1766
1817
  * The provider's own instant of this read, required of a provider that declares `timeCheck`:
1767
1818
  * every duration the agent computer renders off the active call is counted from the provider's clock, and
@@ -1773,7 +1824,7 @@ export interface Snapshot<C extends Channel = Channel> {
1773
1824
  tasks: Task<C>[];
1774
1825
  /** The provider's own count of those tasks, stated rather than inferred: it must equal `tasks.length`, so a blank or unanswered state can never pass as a confirmed empty. */
1775
1826
  taskCount: number;
1776
- contacts?: Contact[];
1827
+ contacts?: ContactEntry[];
1777
1828
  calendar?: ScheduledActivity[];
1778
1829
  /** The agent's own day so far, as the provider counts it; replaced whole by `shift-updated`. Omitted where the provider cannot say. */
1779
1830
  shift?: Shift;
@@ -1858,7 +1909,7 @@ export type ProviderEvent<C extends Channel = Channel> = {
1858
1909
  dialId: DialId;
1859
1910
  outcome: DialOutcome;
1860
1911
  assignmentId?: AssignmentId;
1861
- destinationId?: string;
1912
+ contactId?: string;
1862
1913
  reason?: string;
1863
1914
  } | {
1864
1915
  type: "announcement";
@@ -1892,7 +1943,7 @@ export type ProviderEvent<C extends Channel = Channel> = {
1892
1943
  policies: TeamPolicies;
1893
1944
  } | {
1894
1945
  type: "contacts-updated";
1895
- contacts: Contact[];
1946
+ contacts: ContactEntry[];
1896
1947
  } | {
1897
1948
  type: "calendar-updated";
1898
1949
  calendar: ScheduledActivity[];
@@ -1929,8 +1980,8 @@ export type ProviderEvent<C extends Channel = Channel> = {
1929
1980
  */
1930
1981
  export interface ProviderEventEnvelope<C extends Channel = Channel> {
1931
1982
  id: string;
1932
- /** The login this belongs to. */
1933
- loginId: string;
1983
+ /** The session this belongs to. */
1984
+ sessionId: string;
1934
1985
  occurredAt: IsoTimestamp;
1935
1986
  event: ProviderEvent<C>;
1936
1987
  }
@@ -1961,7 +2012,7 @@ export interface ProviderTimeCheckRequest {
1961
2012
  }
1962
2013
  export interface ProviderTimeCheckResult {
1963
2014
  requestId: string;
1964
- loginId: string;
2015
+ sessionId: string;
1965
2016
  /** Provider clock domain/incarnation; changes on clock discontinuity or authority replacement. */
1966
2017
  clockId: string;
1967
2018
  /** Provider-domain ISO instant sampled after this request arrived, before its response leaves. */
@@ -1984,7 +2035,7 @@ export interface Connection<C extends Channel = Channel> {
1984
2035
  /** Required when the manifest declares `idleCapabilities.dial`. */
1985
2036
  dial?(request: DialRequest): Promise<DialResult>;
1986
2037
  /**
1987
- * The four break methods stand or fall together. Declaring `capabilities.breaks` at login and
2038
+ * The four break methods stand or fall together. Declaring `capabilities.breaks` at sign-in and
1988
2039
  * implementing `requestBreak` without `commitBreak` leaves an agent granted a break that can
1989
2040
  * never start, and the two-phase coordination has no way to report it.
1990
2041
  */
@@ -2000,13 +2051,13 @@ export interface Connection<C extends Channel = Channel> {
2000
2051
  requestNextCall?(): Promise<NextCallResult>;
2001
2052
  cancelNextCall?(): Promise<NextCallCancelResult>;
2002
2053
  releaseLinedUp?(): Promise<LinedUpReleaseResult>;
2003
- /** Required when the login declares `capabilities.lead`: every lead act, on the team surface and nowhere else. */
2054
+ /** Required when the user's capabilities include `lead`: every lead act, on the team surface and nowhere else. */
2004
2055
  executeTeam?(request: TeamCommandRequest): Promise<TeamCommandResult>;
2005
2056
  /** Required of a voice adapter whose manifest lists `softphone`: on one, the call's audio lands in Omni. */
2006
2057
  openAudio?(request: OpenAudioRequest): Promise<OpenAudioResult>;
2007
- /** Required when the login declares `capabilities.preferences`: the person's own choice, kept by the provider and republished as `authenticated`. */
2058
+ /** Required when the user's capabilities include `preferences`: the person's own choice, kept by the provider and republished as `authenticated`. */
2008
2059
  setPreference?(request: SetPreferenceRequest): Promise<PreferenceResult>;
2009
- /** Records an interaction leg the host performed. Required of a softphone login's connection: the host mutes its microphone on any call, and the record is the provider's. */
2060
+ /** Records an interaction leg the host performed. Required of a softphone session's connection: the host mutes its microphone on any call, and the record is the provider's. */
2010
2061
  recordStep?(report: HistoryReport): Promise<HistoryReportResult>;
2011
2062
  }
2012
2063
  export interface Adapter<C extends Channel = Channel> {
@@ -2071,7 +2122,7 @@ export declare const DEFAULT_HISTORY_STEP_LABELS: {
2071
2122
  readonly held: "On hold";
2072
2123
  readonly muted: "Muted";
2073
2124
  readonly transferred: "Transferred";
2074
- readonly conferenced: "Conferenced";
2125
+ readonly added: "Added";
2075
2126
  readonly unanswered: "Unanswered";
2076
2127
  readonly "callback-requested": "Callback requested";
2077
2128
  };
@@ -2102,9 +2153,9 @@ export declare const userKey: (providerId: string, userId: UserId) => string;
2102
2153
  * `queued` are the ones nobody does, and `callback-requested` is the caller's choice unless an agent arranged it, so none
2103
2154
  * of them is here.
2104
2155
  */
2105
- export declare const HISTORY_STEPS_WITH_A_PERSON: readonly ["offered", "answered", "held", "muted", "transferred", "conferenced", "unanswered"];
2106
- /** The steps a dial writes, and so the only ones that carry a `dialId` and a `destinationId`. */
2107
- export declare const HISTORY_STEPS_THAT_DIAL: readonly ["transferred", "conferenced", "unanswered"];
2156
+ export declare const HISTORY_STEPS_WITH_A_PERSON: readonly ["offered", "answered", "held", "muted", "transferred", "added", "unanswered"];
2157
+ /** The steps a dial writes, and so the only ones that carry a `dialId` and a `contactId`. */
2158
+ export declare const HISTORY_STEPS_THAT_DIAL: readonly ["transferred", "added", "unanswered"];
2108
2159
  export declare const historyStepDials: (step: HistoryStep) => boolean;
2109
2160
  /**
2110
2161
  * Consecutive entries of one step, shown as one span. The record keeps an entry per occurrence --
@@ -2122,7 +2173,7 @@ export interface HistorySpan {
2122
2173
  export declare function historySpans(steps: readonly TaskHistoryStep[]): HistorySpan[];
2123
2174
  /** Whether an absent `by` means "could not attribute" rather than "nobody was involved". */
2124
2175
  export declare function historyStepExpectsAPerson(step: HistoryStep): boolean;
2125
- export interface BrowserSessionKeyInput {
2176
+ export interface BrowserProfileKeyInput {
2126
2177
  /** `Manifest.id`, never `displayName`: only the id is unique across an installation and stable. */
2127
2178
  providerId: string;
2128
2179
  /** The task's assignment: a task-scoped session lives one assignment, never the next customer's. */
@@ -2132,7 +2183,7 @@ export interface BrowserSessionKeyInput {
2132
2183
  browser: TaskBrowser;
2133
2184
  }
2134
2185
  /**
2135
- * Whether two logins declare the same capabilities, field by field. The comparison an adapter
2186
+ * Whether two sessions declare the same capabilities, field by field. The comparison an adapter
2136
2187
  * makes before republishing `authenticated`: capabilities are current, not fixed, and the natural
2137
2188
  * guard -- comparing the identity -- never fires on a demotion, because the thing that changed is
2138
2189
  * not the thing being compared. Key order does not matter, and a withdrawn `lead` is a change.
@@ -2141,13 +2192,13 @@ export declare function sameCapabilities(a: UserCapabilities, b: UserCapabilitie
2141
2192
  /**
2142
2193
  * The storage-profile key a reusing browser shares, or `undefined` where it shares nothing.
2143
2194
  *
2144
- * Fails closed. A browser with `sharedSession: false` has no key; nor does a reusing one whose scheme is
2195
+ * Fails closed. A browser with `sharedProfile: false` has no key; nor does a reusing one whose scheme is
2145
2196
  * missing or unknown -- the type forbids that, but an adapter compiled against another version can
2146
2197
  * still send it, and the safe reading is "do not share", never "share with everyone named the
2147
2198
  * same". Every part is encoded, separator included, before joining, so a tab called `a.b`
2148
2199
  * cannot collide with a provider called `a` and a tab called `b`.
2149
2200
  */
2150
- export declare function browserSessionKey(input: BrowserSessionKeyInput): string | undefined;
2201
+ export declare function browserProfileKey(input: BrowserProfileKeyInput): string | undefined;
2151
2202
  /**
2152
2203
  * The comparison key for a contact number. Never for display: keep the original value for that.
2153
2204
  *