@xema/omni-protocol 0.1.129 → 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.md CHANGED
@@ -21,7 +21,7 @@ every cross-reference names the file it points into.
21
21
  | File | |
22
22
  | --- | --- |
23
23
  | `guide/agent.md` | **The agent's work.** What an agent does on any channel: the assignment from offer to wrap, the task and its record, the controls a task offers, the commands the agent computer sends. |
24
- | `guide/voice.md` | **Voice.** What is true of a call and of nothing else: preview, connecting back, ending a call, conference, every dial and its outcome, recording. |
24
+ | `guide/voice.md` | **Voice.** 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. |
25
25
  | `guide/phone.md` | **The phone.** How the agent hears the call: softphone and hardphone, the station and its headset, opening the audio, the microphone and the record. |
26
26
  | `guide/chat.md` | **Chat.** What is true of a chat and of nothing else. |
27
27
  | `guide/email.md` | **Email.** What is true of an email and of nothing else. |
@@ -40,9 +40,9 @@ are used precisely throughout and mean nothing looser here.
40
40
  | **Agent application** | The software the agent uses, such as Omni, whether web or desktop. It presents provider tasks and controls and manages local audio where supported. Existing API names use `Host` and `host` for this role. |
41
41
  | **Provider** | One independently connected external system: a voice platform, a chat platform, a mail platform. |
42
42
  | **Adapter** | The package implementing this contract for one provider. One adapter is one provider, so the words are often interchangeable; *provider* names the system, *adapter* the code speaking for it. |
43
- | **Agent** | The person signed in and taking work. On `onCall`, `agent` is a person on the call by user id; a conference directory may include an agent when the provider publishes that directory item. |
44
- | **Lead** | An agent whose login declares `capabilities.lead`. The flag lets the agent application offer the team feature; the application switches it on with `lead-features` on every connect, and only then does the provider publish the team -- whole on `team-updated`, then one member at a time -- to that login and to nobody else: **the login is the permission**. The lead sees their members with their tasks and stats, and acts on them with the authority the flag carries. |
45
- | **Local policy** | Rules configured by the agent application about this agent, outside the provider protocol and never sent to a provider. It gates whether an offer may be rejected, whether the agent goes ready on login, and whether tasks are auto-accepted. Where a capability and local policy disagree, the stricter wins. |
43
+ | **Agent** | The person signed in and taking work. On `onCall`, `agent` is a person on the call by user id; the provider's contacts may include an agent, whom an add to the call then names by contact id. |
44
+ | **Lead** | An agent whose capabilities include `lead`, the lead capabilities they hold for the session. Its presence lets the agent application offer the team feature; the application switches it on with `lead-features` on every connect, and only then does the provider publish the team -- whole on `team-updated`, then one member at a time -- to that sign-in and to nobody else: **the session is the permission**. The lead sees their members with their tasks and stats, and acts on them with the lead capabilities the session holds. |
45
+ | **Local policy** | Rules configured by the agent application about this agent, outside the provider protocol and never sent to a provider. It gates whether an offer may be rejected, whether the agent goes ready on session, and whether tasks are auto-accepted. Where a capability and local policy disagree, the stricter wins. |
46
46
  | **Call** | The caller’s complete phone call, which may continue through IVRs, queues and several agents. The protocol never describes the IVR or the queue; it carries the call's history and details to whichever agent holds it now. |
47
47
  | **Assignment** | The call routed to this agent, from the offer until the task ends. It is the one thing that crosses: the provider assigns, names the assignment with `assignmentId`, and that is the only name the agent computer ever uses back. A call that comes back is a new assignment on the same call, and a declined or lapsed offer is an assignment that became nothing more. What the platform calls its own record, and whether it reuses that name, is the adapter's business and unknown to the agent computer. |
48
48
  | **Interaction** | The agent's time on the call, from answer until their audio ends: the `in-progress` and `paused` phases. An assignment produces at most one interaction, and a call that returns produces a new assignment and so a new interaction. |
@@ -50,17 +50,17 @@ are used precisely throughout and mean nothing looser here.
50
50
  | **Channel** | The kind of work a provider carries: `voice`, `chat`, or `email`. Fixed per provider by its manifest. |
51
51
  | **Task type** | The provider's own name for a category of work — a queue, a mailbox folder, a chat source. Free-form, and finer-grained than a channel. |
52
52
  | **Capability** | A provider's declaration that a control exists for a task or a session. It says *offer this*; the provider performs it, and the agent application only offers it — see **Where a command executes** in `guide/agent.md`. |
53
- | **Login** | One authenticated sign-in to one provider, identified by `loginId`. A transport reconnect keeps it; signing in again replaces it, and nothing tied to the old `loginId` survives. |
54
- | **Transport** | The adapter's connection to its platform: a WebSocket or SignalR connection, required to be persistent and ordered. Which one and how it reconnects are the adapter's business; losing it does not end a login. |
55
- | **Connection** | The `Connection` object Omni holds for one login: the methods it can call and the events it receives. |
53
+ | **Session** | One authenticated sign-in to one provider, identified by `sessionId`. A transport reconnect keeps it; signing in again replaces it, and nothing tied to the old `sessionId` survives. |
54
+ | **Transport** | The adapter's connection to its platform: a WebSocket or SignalR connection, required to be persistent and ordered. Which one and how it reconnects are the adapter's business; losing it does not end a session. |
55
+ | **Connection** | The `Connection` object Omni holds for one session: the methods it can call and the events it receives. |
56
56
  | **Concurrent capacity** | How many tasks this provider may have assigned to the agent at once — an absolute ceiling, stated as `AgentCapacity.count` and standing until Omni restates it. The provider counts its own outstanding tasks against it. |
57
57
  | **Snapshot** | The provider's complete state at one moment. It replaces what Omni holds; it is never a patch. |
58
58
  | **Event** | One completed transaction reported after a snapshot established the baseline. |
59
59
  | **Break** | A reported, supervised state in which the agent is not working — one with a reason, a decision behind it and a return. It covers what a platform may call *not-ready*, including equipment trouble. An agent who is merely at capacity is not on a break. |
60
60
  | **Workspace** | What Omni shows the agent. The **task workspace** holds the selected task, its controls and its browsers; the **idle workspace** holds what a provider contributes when no task is selected — dialpad, contacts, calendar, team member list. |
61
- | **Dial** | One outbound call the agent application asks a provider to place — from the idle dialpad, a preview's Call, a conference add, or a connect-back. Identified by the agent application's `dialId`, accepted as `dialling`, and ended by exactly one `dial-outcome`. See **Every dial has an outcome** in `guide/voice.md`. |
61
+ | **Dial** | One outbound call the agent application asks a provider to place — from the idle dialpad, a preview's Call, an add to the call, or a connect-back. Identified by the agent application's `dialId`, accepted as `dialling`, and ended by exactly one `dial-outcome`. See **Every dial has an outcome** in `guide/voice.md`. |
62
62
  | **Listen** | A lead's channel in a member's call, unasked, from the team member list: `listen` in silence, `coach` heard by the agent alone, `join-call` heard by everyone. It is a team act naming the member, never a task on the lead's computer; `listen` and `coach` leave no trace on the member's task, while a lead heard by everyone is on its `onCall` as an `agent`. Every lead sees every lead on the call. A lead who wants the call takes it over. See **Listening to a call** in `guide/lead.md`. |
63
- | **On the call** | Who a voice task's audio joins, or is bringing in, as the provider states it on `Task.onCall`: the party, the agents, and anyone conferenced in from the moment their dial is placed. |
63
+ | **On the call** | Who a voice task's audio joins, or is bringing in, as the provider states it on `Task.onCall`: the party, the agents, and anyone added from the moment their dial is placed. |
64
64
 
65
65
  These fields describe state within their containing objects. Both authentication and break
66
66
  state use `status`; name the object when discussing them to avoid ambiguity.
@@ -111,7 +111,7 @@ negotiateProtocolVersion([1], [2]); // undefined — refuse to connect
111
111
 
112
112
  Omni negotiates the version before it creates an authentication session. The selected
113
113
  `protocolVersion` is included in both `AuthenticationContext` and `ConnectContext` and remains
114
- fixed for that login, including transport reconnects. An adapter that advertises several versions
114
+ fixed for that sign-in, including transport reconnects. An adapter that advertises several versions
115
115
  must use this value to select the corresponding contract behavior.
116
116
 
117
117
  ## Semantic types
@@ -287,7 +287,7 @@ type SecretStore = {
287
287
 
288
288
  type AuthenticationContext = {
289
289
  protocolVersion: number;
290
- loginId: string;
290
+ sessionId: string;
291
291
  timeZone: TimeZone;
292
292
  languages: readonly LanguageTag[];
293
293
  phone?: Phone;
@@ -302,10 +302,24 @@ type ListeningMode = "listen" | "coach" | "join-call";
302
302
  type UserCapabilities = {
303
303
  breaks?: true;
304
304
  preferences?: AgentPreference[];
305
- lead?: true;
305
+ lead?: LeadCapabilities;
306
306
  nextCall?: true;
307
307
  };
308
308
 
309
+ type LeadCapabilities = {
310
+ join?: true;
311
+ decline?: true;
312
+ listen?: true;
313
+ coach?: true;
314
+ joinCall?: true;
315
+ takeOverCall?: true;
316
+ decideBreakRequest?: true;
317
+ setBreakPolicy?: true;
318
+ forceBreak?: true;
319
+ endForcedBreak?: true;
320
+ setPolicy?: true;
321
+ };
322
+
309
323
  type AuthenticationState =
310
324
  | { status: "signed-out" }
311
325
  | { status: "authenticating" }
@@ -397,7 +411,7 @@ type HostGuarantees = {
397
411
  muteUnavailableOnHold?: true;
398
412
  };
399
413
 
400
- type ProviderTimeScope = { providerId: string; loginId: string };
414
+ type ProviderTimeScope = { providerId: string; sessionId: string };
401
415
  type ProviderTimeEstimate = ProviderTimeScope & {
402
416
  at: IsoTimestamp;
403
417
  clockId: string;
@@ -413,7 +427,7 @@ type Host = {
413
427
  subscribe(listener: (report: HostReport) => void): Unsubscribe;
414
428
  };
415
429
 
416
- type LoginStore = {
430
+ type SessionStore = {
417
431
  get(key: string): Promise<string | undefined>;
418
432
  set(key: string, value: string): Promise<void>;
419
433
  delete(key: string): Promise<void>;
@@ -421,11 +435,11 @@ type LoginStore = {
421
435
 
422
436
  type ConnectContext = {
423
437
  protocolVersion: number;
424
- loginId: string;
438
+ sessionId: string;
425
439
  autoAcceptTasks: boolean;
426
440
  timeZone: TimeZone;
427
441
  languages: readonly LanguageTag[];
428
- store: LoginStore;
442
+ store: SessionStore;
429
443
  phone?: Phone;
430
444
  host: Host;
431
445
  signal?: AbortSignal;
@@ -524,12 +538,12 @@ type PreferenceResult =
524
538
 
525
539
  type Snapshot = {
526
540
  transport: TransportStatus;
527
- loginId: string;
541
+ sessionId: string;
528
542
  providerTime?: IsoTimestamp;
529
543
  break: BreakState;
530
544
  tasks: Task[];
531
545
  taskCount: number;
532
- contacts?: Contact[];
546
+ contacts?: ContactEntry[];
533
547
  calendar?: ScheduledActivity[];
534
548
  shift?: Shift;
535
549
  phone?: PhoneState;
@@ -556,6 +570,10 @@ type Contact = {
556
570
  attributes?: Attribute[];
557
571
  };
558
572
 
573
+ type ContactEntry = Contact & {
574
+ id: string;
575
+ };
576
+
559
577
  type ScheduledActivity = {
560
578
  id: string;
561
579
  title: string;
@@ -586,13 +604,9 @@ type OutcomeRules = {
586
604
  codes?: OutcomeCode[];
587
605
  };
588
606
 
589
- type Destination = {
590
- id: string;
591
- label: string;
592
- };
593
-
594
- type DestinationDirectory = {
595
- destinations: Destination[];
607
+ type AddToCallCapability = {
608
+ destinations: DialDestinations;
609
+ contactIds?: string[];
596
610
  };
597
611
 
598
612
  type CustomCapability = {
@@ -622,7 +636,7 @@ type TaskCapabilities<C extends Channel = Channel> =
622
636
  connectBack?: Lockable<true>;
623
637
  schedule?: Lockable<true>;
624
638
  leadAssist?: Lockable<true>;
625
- conference?: Lockable<DestinationDirectory>;
639
+ addToCall?: Lockable<AddToCallCapability>;
626
640
  recording?: Lockable<TaskRecordingPolicy>;
627
641
  }
628
642
  : C extends "chat"
@@ -707,7 +721,7 @@ type HistoryStep =
707
721
  | "held"
708
722
  | "muted"
709
723
  | "transferred"
710
- | "conferenced"
724
+ | "added"
711
725
  | "unanswered"
712
726
  | "callback-requested";
713
727
 
@@ -723,7 +737,7 @@ type TaskHistoryStep = {
723
737
  step: HistoryStep;
724
738
  at: IsoTimestamp;
725
739
  dialId?: DialId;
726
- destinationId?: string;
740
+ contactId?: string;
727
741
  seconds?: DurationSeconds;
728
742
  by?: UserId;
729
743
  mutedBy?: MutedBy;
@@ -740,15 +754,15 @@ type TaskCompletion =
740
754
  | { completionMode: "agent-command"; wrapAllowance?: DurationSeconds }
741
755
  | { completionMode: "provider-automatic"; wrapAllowance: DurationSeconds };
742
756
 
743
- type OnCallRole = "party" | "agent" | "conferenced";
757
+ type OnCallRole = "party" | "agent" | "added";
744
758
 
745
759
  type OnCallStage = "ringing" | "joined";
746
760
 
747
761
  type OnCall = { since: IsoTimestamp; held?: true } & (
748
762
  | { role: "party"; dialId?: never; stage?: never }
749
763
  | { role: "party"; stage: OnCallStage; dialId?: DialId }
750
- | { role: "agent"; userId: UserId }
751
- | { role: "conferenced"; destinationId: string; stage: OnCallStage; dialId?: DialId; label?: string }
764
+ | { role: "agent"; userId: UserId; coaching?: true }
765
+ | { role: "added"; contactId: string; stage: OnCallStage; dialId?: DialId; label?: string }
752
766
  );
753
767
 
754
768
  type TaskLeadAssist = { note?: string; since: IsoTimestamp } & (
@@ -832,7 +846,8 @@ const TASK_COMMAND_NAMES = {
832
846
  "terminate-call",
833
847
  "connect-back",
834
848
  "lead-assist",
835
- "conference",
849
+ "add-to-call",
850
+ "remove-from-call",
836
851
  "recording",
837
852
  "schedule",
838
853
  "complete",
@@ -858,9 +873,10 @@ type VoiceTaskCommand =
858
873
  | ScheduleCommand
859
874
  | { type: "lead-assist"; action: "request"; note?: string }
860
875
  | { type: "lead-assist"; action: "cancel" }
861
- | { type: "conference"; action: "add"; dialId: DialId; destinationId: string }
862
- | { type: "conference"; action: "remove"; destinationId: string; party?: never }
863
- | { type: "conference"; action: "remove"; party: true; destinationId?: never }
876
+ | { type: "add-to-call"; dialId: DialId; contactId: string; number?: never }
877
+ | { type: "add-to-call"; dialId: DialId; number: string; contactId?: never }
878
+ | { type: "remove-from-call"; contactId: string; party?: never }
879
+ | { type: "remove-from-call"; party: true; contactId?: never }
864
880
  | (RecordingCommand & { source: "provider" })
865
881
  | ({ type: "complete" } & OutcomePayload);
866
882
 
@@ -900,7 +916,7 @@ type TaskCommandResult =
900
916
  ### Who decides what an agent may do
901
917
 
902
918
  An agent agent computer has two managers, not one. **The queue** — a process, a work type — is owned by a
903
- process manager and **allows** a set of capabilities: hold, connect back, dial, conference,
919
+ process manager and **allows** a set of capabilities: hold, connect back, dial, add to call,
904
920
  whether the number is visible, the actions it offers, the skills it needs. **The people** are
905
921
  managed through the organisation's structure — a team, a location, the organisation itself, in
906
922
  whatever combination the structure defines for a person — and **decide** per capability within
@@ -959,15 +975,15 @@ nothing else on that copy carries it, exactly as on the member's (`task.locked.l
959
975
  member's tasks with the same `lockedValues`). What the queue provides rather than permits — browsers, outcomes, custom
960
976
  controls — is content, and is never locked.
961
977
 
962
- **A lead sets the team's policy from their team member list.** A login that declares
963
- `capabilities.lead` may `executeTeam({ command: { type: "set-policy", capability, setting } })`, where the provider offers policy control and says so by publishing `policies`,
978
+ **A lead sets the team's policy from their team member list.** A user whose
979
+ capabilities include `lead` may `executeTeam({ command: { type: "set-policy", capability, setting } })`, where the provider offers policy control and says so by publishing `policies`,
964
980
  with `on`, `off`, or `person`, for any task control, `dial`, or a skill — and only `hold`
965
981
  and skills may be `person`; connect back and dial are the team's, on or off, within what the queue
966
- allows. The team member list carries `policies` for such a login: every policy as it stands, who set it, and
982
+ allows. The team member list carries `policies` for such a session: every policy as it stands, who set it, and
967
983
  `lockedBy` where a level above the team made it theirs to keep, which the lead sees and cannot
968
984
  change — `set-policy` on it answers `failed` with `omni.capability-not-enabled`.
969
985
 
970
- **What the team left to the person is the person's, and the provider keeps it.** The login's
986
+ **What the team left to the person is the person's, and the provider keeps it.** The session's
971
987
  `capabilities.preferences` lists every preference the person may hold — `hold`, a skill —
972
988
  with where it stands and who set it: `setBy: "team"` while they inherit the team's default,
973
989
  `"person"` once they have set their own, `"provider"` where no level has said anything. Nothing
@@ -1227,7 +1243,7 @@ type ProviderEvent =
1227
1243
  | { type: "task-audio-started"; assignmentId: AssignmentId }
1228
1244
  | { type: "task-audio-ended"; assignmentId: AssignmentId }
1229
1245
  | { type: "task-ended"; assignmentId: AssignmentId; outcome: TaskOutcome }
1230
- | { type: "dial-outcome"; dialId: DialId; outcome: DialOutcome; assignmentId?: AssignmentId; destinationId?: string; reason?: string }
1246
+ | { type: "dial-outcome"; dialId: DialId; outcome: DialOutcome; assignmentId?: AssignmentId; contactId?: string; reason?: string }
1231
1247
  | { type: "announcement"; text: string; html?: string; announcedAt: IsoTimestamp; expiresAt?: IsoTimestamp }
1232
1248
  | { type: "queue-summary"; summary: QueueSummary }
1233
1249
  | { type: "diagnostic"; expected: string; observed: string; assignmentId?: AssignmentId }
@@ -1235,7 +1251,7 @@ type ProviderEvent =
1235
1251
  | { type: "team-member-updated"; member: TeamMember }
1236
1252
  | { type: "team-member-removed"; memberId: UserId }
1237
1253
  | { type: "team-policies-updated"; policies: TeamPolicies }
1238
- | { type: "contacts-updated"; contacts: Contact[] }
1254
+ | { type: "contacts-updated"; contacts: ContactEntry[] }
1239
1255
  | { type: "calendar-updated"; calendar: ScheduledActivity[] }
1240
1256
  | { type: "shift-updated"; shift: Shift }
1241
1257
  | { type: "phone-updated"; phone: PhoneState }
@@ -1245,7 +1261,7 @@ type ProviderEvent =
1245
1261
 
1246
1262
  type ProviderEventEnvelope = {
1247
1263
  id: string;
1248
- loginId: string;
1264
+ sessionId: string;
1249
1265
  occurredAt: IsoTimestamp;
1250
1266
  event: ProviderEvent;
1251
1267
  };
@@ -1273,7 +1289,7 @@ type ProviderTimeCheckPolicy = {
1273
1289
  type ProviderTimeCheckRequest = { requestId: string };
1274
1290
  type ProviderTimeCheckResult = {
1275
1291
  requestId: string;
1276
- loginId: string;
1292
+ sessionId: string;
1277
1293
  clockId: string;
1278
1294
  providerTime: IsoTimestamp;
1279
1295
  };
@@ -1347,7 +1363,7 @@ const HISTORY_STEPS_WITH_A_PERSON = [
1347
1363
  "held",
1348
1364
  "muted",
1349
1365
  "transferred",
1350
- "conferenced",
1366
+ "added",
1351
1367
  "unanswered",
1352
1368
  ] as const;
1353
1369
 
@@ -1457,7 +1473,7 @@ const DEFAULT_HISTORY_STEP_LABELS = {
1457
1473
  held: "On hold",
1458
1474
  muted: "Muted",
1459
1475
  transferred: "Transferred",
1460
- conferenced: "Conferenced",
1476
+ added: "Added",
1461
1477
  unanswered: "Unanswered",
1462
1478
  "callback-requested": "Callback requested",
1463
1479
  } as const satisfies Readonly<Record<HistoryStep, string>>;
@@ -1604,7 +1620,7 @@ Snapshots establish and replace provider state when an agent signs in, reconnect
1604
1620
  **A snapshot is the provider's answer, and an adapter that got no answer publishes nothing.** A
1605
1621
  state read that answers unknown — a session not yet associated, a backend mid-failover — is not an
1606
1622
  empty state: the adapter keeps what it holds, stays `connecting`, and publishes a snapshot only
1607
- once the provider has actually answered for this login, exactly as `connect()` may not resolve
1623
+ once the provider has actually answered for this session, exactly as `connect()` may not resolve
1608
1624
  before it can provide a meaningful one. And emptiness is stated, never inferred: every snapshot
1609
1625
  carries `taskCount`, the provider's own count reconciled against `tasks.length`, so a snapshot
1610
1626
  with no work says `taskCount: 0` in so many words and a blank or half-built state — which lacks
@@ -1709,22 +1725,22 @@ connection is up nothing has been lost, and when it comes back the adapter sends
1709
1725
 
1710
1726
  Request/response polling does not have those properties and is not a transport for this contract.
1711
1727
 
1712
- ### 3. An adapter's memory is the platform's and the login's, never the connection's
1728
+ ### 3. An adapter's memory is the platform's and the session's, never the connection's
1713
1729
 
1714
1730
  Everything an adapter publishes about a task is derived from what the platform states, or kept in
1715
- the login's store where the platform cannot hold it. Per offer, the `assignmentId` comes from what
1731
+ the session's store where the platform cannot hold it. Per offer, the `assignmentId` comes from what
1716
1732
  the offer itself states; per call, the audio follows `task-audio-started` and `task-audio-ended`,
1717
1733
  never a flag set when the audio was opened; per session, the phone the agent holds is what the
1718
1734
  platform restates on activation, not a mapping read once over HTTP. What the platform cannot hold
1719
1735
  -- an agent application's muted leg -- goes in `ConnectContext.store`, keyed by the task and gone with it.
1720
1736
 
1721
1737
  A fact read once over a connection and kept in the adapter object dies with the client. An agent application
1722
- reload is the first client dying and a second coming up for the same login, and the second
1738
+ reload is the first client dying and a second coming up for the same session, and the second
1723
1739
  publishes the same truth about the same task as the first did, or the first was publishing
1724
1740
  something it made up: an assignment minted for the connection, audio remembered as a boolean, a
1725
1741
  phone the second never read. Three pieces of exactly that state were found in one adapter in an
1726
1742
  afternoon, and none of it was visible until the adapter was built twice. The test's `rebuild` is the test of this
1727
- principle: given a way to build the adapter again, the run hands the login over and holds the
1743
+ principle: given a way to build the adapter again, the run hands the session over and holds the
1728
1744
  second to what the first published (`test.reload.snapshot`, `.history`, `.openAudio`, and the
1729
1745
  stream's own rules across the resync). An adapter that cannot be built twice against its platform
1730
1746
  and publish the same task is not a conformant adapter yet, whatever a single run says.
@@ -1788,12 +1804,12 @@ compile time.
1788
1804
  | `displayName` | Human-readable provider label. |
1789
1805
  | `channel` | Protocol-v1 value `voice`, `chat`, or `email`. New channels require a later protocol version. |
1790
1806
  | `supportedProtocolVersions` | Required non-empty list of versions this adapter can speak. Must share at least one with Omni. |
1791
- | `authenticationMethods` | Required non-empty list of supported login methods. |
1807
+ | `authenticationMethods` | Required non-empty list of supported sign-in methods. |
1792
1808
  | `idleCapabilities` | Declares actions Omni may offer while the agent has no active task, such as voice dialing. Task controls do not belong here. |
1793
1809
  | `orgLevels` | The organisation's whole ladder as the provider calls it, each level with the label an agent computer shows for "who decided", one text per language as `{ en: "Your region", hi: "आपका क्षेत्र" }`, from which the agent application picks with `localizedText()` (`manifest.orgLevel.label`, `.language`, `.text`). Required of every provider (`manifest.orgLevels.required`), stated outright, `person` included: what it leaves out does not exist. There is no default ladder. See **Who decides what an agent may do**. |
1794
- | `phones` | Voice only, and required there: the phones this platform can put an agent on, `softphone` (the call's audio lands in the agent application) and/or `hardphone` (a handset the platform rings; the agent application shows the call and opens nothing). The agent application picks one per login. See **How the agent hears the call** in `guide/phone.md`. |
1810
+ | `phones` | Voice only, and required there: the phones this platform can put an agent on, `softphone` (the call's audio lands in the agent application) and/or `hardphone` (a handset the platform rings; the agent application shows the call and opens nothing). The agent application picks one per session. See **How the agent hears the call** in `guide/phone.md`. |
1795
1811
  | `phoneStatus` | Voice only, declared by presence as `true`: the platform sees the phone itself -- its registration, its do-not-disturb, its hook, its calls -- and publishes it as `Snapshot.phone` and `phone-updated`. A platform that cannot see the phone omits it, and then publishes no phone (`manifest.phoneStatus`). See **The phone's own view** in `guide/phone.md`. |
1796
- | `dialOutcomes` | Voice only. How a dial can end on this platform, as it distinguishes them: `answered` and at least one way of not reaching the destination. Required of a provider that dials at all — an idle dialpad, or tasks that conference or call back — and a `dial-outcome` carries only a declared member. See **Every dial has an outcome** in `guide/voice.md`. |
1812
+ | `dialOutcomes` | Voice only. How a dial can end on this platform, as it distinguishes them: `answered` and at least one way of not reaching the destination. Required of a provider that dials at all — an idle dialpad, or tasks that add to the call or call back — and a `dial-outcome` carries only a declared member. See **Every dial has an outcome** in `guide/voice.md`. |
1797
1813
  | `timeCheck` | `true`: implements `checkTime` and states `providerTime` on every snapshot. Required of a provider that publishes an instant the agent computer renders as a running duration -- a member's `since`, a `listening[].since`, an `onCall.since`, a shift's `signedInAt` -- so every screen counts from the provider's clock (`manifest.timeCheck.required`); agent application polling is independently opt-in. See **Every screen counts from the provider's clock**. |
1798
1814
  | `timestampAuthority` | Optional `"provider"`: provider timestamps are final; agent application instants are advisory. Omission makes no trust promise. |
1799
1815
  | `runningStepReports` | The provider takes running reports of an agent application-performed step — `recordStep` with `seconds` so far and no `ended`. Omitted, the agent application sends exactly two reports per leg, when it began and when it ended, and a running one is refused. See **The agent application records what it performs** in `guide/agent.md`. |
@@ -1801,7 +1817,7 @@ compile time.
1801
1817
 
1802
1818
  ### Authentication methods
1803
1819
 
1804
- A provider declares one or both protocol-v1 login methods:
1820
+ A provider declares one or both protocol-v1 sign-in methods:
1805
1821
 
1806
1822
  | Value | Contract |
1807
1823
  | --- | --- |
@@ -1815,7 +1831,7 @@ authenticationMethods: [
1815
1831
  ]
1816
1832
  ```
1817
1833
 
1818
- The list must not be empty or contain duplicates. It declares available login methods only;
1834
+ The list must not be empty or contain duplicates. It declares available sign-in methods only;
1819
1835
  credentials and tokens never belong in the manifest.
1820
1836
 
1821
1837
  `manifest.id` partitions the `SecretStore`, so an id is first-claimed: an adapter whose id another
@@ -1972,7 +1988,10 @@ idleCapabilities: { contacts: true }
1972
1988
 
1973
1989
  Omit `contacts` to make no contact contribution. When declared, the provider
1974
1990
  publishes its authoritative list through `Snapshot.contacts` and replaces it with a
1975
- `contacts-updated` event when it changes. Every field is optional:
1991
+ `contacts-updated` event when it changes. The list is the agent computer's directory: each entry
1992
+ carries a unique `id`, which is how the wire names that contact -- in an add to the call, on the call, in
1993
+ its history and on a dial's outcome -- and the agent computer shows the name it holds for an id.
1994
+ Every other field is optional:
1976
1995
 
1977
1996
  > **Note:** Omni derives normalized number and email keys for indexing and deduplication while
1978
1997
  > preserving the original values for display. A number supplied by multiple providers appears only once, with source icons indicating
@@ -1982,6 +2001,7 @@ publishes its authoritative list through `Snapshot.contacts` and replaces it wit
1982
2001
 
1983
2002
  | Field | Contract |
1984
2003
  | --- | --- |
2004
+ | `id` | Required on every entry of the list, unique within it (`contact.id`, `contact.id.unique`). A typed number the provider dials becomes an entry under an id of its own. A task's party is not a list entry and carries none. |
1985
2005
  | `name` | Optional agent-facing display name. |
1986
2006
  | `number` | Optional original dialable address, preserved for display. |
1987
2007
  | `email` | Optional original email address, preserved for display. |
@@ -2049,11 +2069,11 @@ Creates the provider-scoped authentication session.
2049
2069
 
2050
2070
  | `AuthenticationContext` field | Contract |
2051
2071
  | --- | --- |
2052
- | `protocolVersion` | The negotiated version, fixed for this login. |
2053
- | `loginId` | Omni-generated identity for this login. The same value Omni later passes as `ConnectContext.loginId`, and how an adapter ties a connection back to the session that authenticated it. |
2072
+ | `protocolVersion` | The negotiated version, fixed for this session. |
2073
+ | `sessionId` | Omni-generated identity for this session. The same value Omni later passes as `ConnectContext.sessionId`, and how an adapter ties a connection back to the session that authenticated it. |
2054
2074
  | `timeZone` | The zone the agent's day is reckoned in, as an IANA name from the agent application's clock, stated before any identity exists so the first `authenticated` state already carries it. The same value Omni later passes as `ConnectContext.timeZone`. See **The agent's day**. |
2055
2075
  | `languages` | The languages the agent reads, as BCP 47 tags, most preferred first, from the agent application's own setting: `["hi-IN", "en"]`. Never empty (`context.languages`), each a well-formed tag (`context.languages.tag`), none twice (`context.languages.unique`). The same value Omni later passes as `ConnectContext.languages`. See **The agent's languages**. |
2056
- | `phone` | How this login hears its calls, chosen by the agent application from the manifest's `phones`: required for a voice provider, absent for any other. The same value Omni later passes as `ConnectContext.phone`. See **How the agent hears the call** in `guide/phone.md`. |
2076
+ | `phone` | How this session hears its calls, chosen by the agent application from the manifest's `phones`: required for a voice provider, absent for any other. The same value Omni later passes as `ConnectContext.phone`. See **How the agent hears the call** in `guide/phone.md`. |
2057
2077
  | `secrets` | Omni-provided `SecretStore`, scoped to this provider's manifest id. |
2058
2078
  | `signal` | Optional cancellation signal. |
2059
2079
  | `log` | Optional structured logging callback. Never include credentials, tokens, or sensitive contact data. |
@@ -2074,40 +2094,40 @@ reports later changes.
2074
2094
  | --- | --- |
2075
2095
  | `signed-out` | No usable provider session exists, because the agent signed out on this agent computer, or never signed in. Only the agent's own Sign out here leads to it. |
2076
2096
  | `authenticating` | An interactive `browser-sso` or `credentials` flow is active. |
2077
- | `authenticated` | A usable session exists. Includes the provider identity, the login's `capabilities`, and optional token expiry time. |
2097
+ | `authenticated` | A usable session exists. Includes the provider identity, the user's `capabilities` for the session, and optional token expiry time. |
2078
2098
  | `refreshing` | The adapter is refreshing its session. Existing provider identity and capabilities remain available, unchanged: a change to either is published as `authenticated`. |
2079
- | `expired` | The session's time ran out, or its refresh is failing. It may include an identity and typed failure. The agent signs in again on the same login, and the workspace stays. |
2099
+ | `expired` | The session's time ran out, or its refresh is failing. It may include an identity and typed failure. The agent signs in again on the same session, and the workspace stays. |
2080
2100
  | `terminated` | The session was ended from outside this agent computer: by a supervisor, by the agent on another screen, or by the platform itself. `by` says who, a person by `UserId` or `provider` where no person was behind it (`authentication.terminated.by`), and `failure` says why and is never retryable (`authentication.terminated.failure`, `.retryable`). It is never reported as `expired`, which would hide who ended it, nor as `signed-out`, which is the agent's own act. The session's ending is the whole message: the agent application disposes the connection with `disconnect()` and shows `failure.message` on the sign-in, and the adapter reports no transport `error` beside it -- `reauthenticate` would say this session is restored, and it is not. |
2081
2101
 
2082
2102
  Omni calls `connect()` only after authentication reaches `authenticated`. Token refresh remains
2083
2103
  adapter-owned; the adapter publishes `refreshing`, followed by `authenticated` or `expired`.
2084
2104
  `refreshing` asks nothing of the agent and Omni shows nothing for it. If authentication expires
2085
2105
  during active work, Omni preserves the task workspace and shows reauthentication for that
2086
- provider: the transport is still up and the tasks still on it, so this is a login problem with a
2087
- login fix, rendered apart from a provider Omni cannot reach. Commands meanwhile answer
2106
+ provider: the transport is still up and the tasks still on it, so this is a session problem with a
2107
+ session fix, rendered apart from a provider Omni cannot reach. Commands meanwhile answer
2088
2108
  `omni.not-authenticated`.
2089
2109
 
2090
- **Re-authentication restores the login; it does not replace it.** It runs on the session Omni
2091
- kept, under the same `loginId` — the old `flowId` died with the expiry, so the adapter issues a
2110
+ **Re-authentication restores the session; it does not replace it.** It runs on the session Omni
2111
+ kept, under the same `sessionId` — the old `flowId` died with the expiry, so the adapter issues a
2092
2112
  new challenge — and when the state returns to `authenticated` the connection and everything on it
2093
2113
  carry on: Omni does not call `connect()` again, since a second connection would be a second
2094
2114
  session for one agent. The exception is a transport that reported `error` with `recovery:
2095
- "reauthenticate"`: that connection is finished, and once the login is restored Omni disposes it and
2115
+ "reauthenticate"`: that connection is finished, and once the session is restored Omni disposes it and
2096
2116
  calls `connect()` afresh, as for `reconnect` -- see **`transport-status`**. What "signing in again
2097
- replaces the login" describes is a new `AuthenticationSession` under a new `loginId`, after
2117
+ replaces the session" describes is a new `AuthenticationSession` under a new `sessionId`, after
2098
2118
  `signed-out`.
2099
2119
 
2100
2120
  **A sign-in the platform no longer allows is ended, not restored.** A role changed mid-shift can
2101
- take away what the login was built on -- an agent made a supervisor may no longer have a phone, and
2121
+ take away what the session was built on -- an agent made a supervisor may no longer have a phone, and
2102
2122
  the platform refuses to renew the softphone. Retrying cannot help and the same session cannot carry
2103
2123
  on, so the adapter deletes the secrets and publishes `terminated`, `by: "provider"`, with a failure
2104
2124
  in the agent's words: `{ code: "phone-not-allowed", message: "Your sign-in no longer allows a phone.
2105
2125
  Sign in again.", retryable: false }`. The agent application disposes the connection and shows that
2106
2126
  message on the sign-in.
2107
2127
 
2108
- ### What the login may do
2128
+ ### What the user may do
2109
2129
 
2110
- `capabilities` declares provider actions available to this login rather than to one task: whether
2130
+ `capabilities` declares provider actions available to this user for the session rather than to one task: whether
2111
2131
  the agent may ask for a break, and whether they lead a team. It is declared by presence, like every
2112
2132
  capability in this contract, and it travels with the identity because it is part of who the agent
2113
2133
  is on this provider: the provider knows the roles, and says so at sign-in rather than leaving Omni
@@ -2115,14 +2135,14 @@ to infer them from what arrives later.
2115
2135
 
2116
2136
  | Field | Contract |
2117
2137
  | --- | --- |
2118
- | `breaks` | This login may request a break. Requires the four break methods on the connection. |
2138
+ | `breaks` | This session may request a break. Requires the four break methods on the connection. |
2119
2139
  | `nextCall` | The platform lines calls up for this agent: pressing Next call while on a call puts the next queued call in the agent's own queue, to start when their wrap ends unless somebody else takes it first. Requires `requestNextCall`, `cancelNextCall` and `releaseLinedUp` on the connection. See **The agent's own queue** in `guide/queue.md`. |
2120
- | `lead` | This login leads a team. The flag alone turns on the team feature in the agent application, and every lead act comes with it; there is no per-action permission beside it. While the lead has the feature on, the provider publishes a `TeamMembers` object to them on every snapshot — `members: []` when nobody is in it — and to nobody else. Requires `executeTeam`. See **Team leads** in `guide/lead.md`. |
2140
+ | `lead` | This session leads a team, with the `LeadCapabilities` it holds for the whole session: one key per lead command it allows -- `join`, `decline`, `listen`, `coach`, `joinCall`, `takeOverCall`, `decideBreakRequest`, `setBreakPolicy`, `forceBreak`, `endForcedBreak`, `setPolicy` -- each by presence, at least one (`authentication.capability.lead.*`). Switching the team feature and leaving a call are every lead's and are not listed. Its presence turns on the team feature in the agent application, which offers only the lead commands the lead holds; any other is refused before it is sent (`team.command.notGranted`). A team lead may hold listen, coach and break decisions, a floor manager all of them. While the lead has the feature on, the provider publishes a `TeamMembers` object to them on every snapshot — `members: []` when nobody is in it — and to nobody else. Requires `executeTeam`. See **Team leads** in `guide/lead.md`. |
2121
2141
  | `preferences` | What the team left to this person, with where each stands and who set it. Omitted when nothing was. Requires `setPreference`. See **Who decides what an agent may do**. |
2122
2142
 
2123
2143
  A session action is available only when both the capability and Omni local policy permit it.
2124
2144
 
2125
- **Capabilities are current, not fixed.** They describe the login as of its latest `authenticated`
2145
+ **Capabilities are current, not fixed.** They describe the session as of its latest `authenticated`
2126
2146
  state. A provider that reads roles live — a lead demoted mid-shift — republishes `authenticated`
2127
2147
  with the new set through `subscribe()` on the authentication session, which Omni keeps open for
2128
2148
  the life of the connection for exactly this reason, and the next snapshot agrees with it. Omni
@@ -2236,7 +2256,7 @@ is identified from the same directory and carries the same `UserId` type.
2236
2256
 
2237
2257
  | Field | Contract |
2238
2258
  | --- | --- |
2239
- | `id` | Required `UserId`. Unique within this provider and stable across logins: it is what Omni scopes and stores, so a value that changes between sessions breaks every reference to this person. |
2259
+ | `id` | Required `UserId`. Unique within this provider and stable across sessions: it is what Omni scopes and stores, so a value that changes between sessions breaks every reference to this person. |
2240
2260
  | `displayName` | Required agent-facing name. Presentation only — never an identifier, never compared. |
2241
2261
 
2242
2262
  `AuthenticationFailure` contains a stable `code`, safe agent-facing `message`, `retryable` flag,
@@ -2291,7 +2311,7 @@ by any script running on its page, so a browser agent application is only as saf
2291
2311
 
2292
2312
  Adapters may store refresh tokens or equivalent session material, but never raw submitted
2293
2313
  credentials, and they put a secret nowhere but the `SecretStore`: never in manifests, logs,
2294
- events, snapshots, task attributes, errors, the login's `store`, or browser storage of their own.
2314
+ events, snapshots, task attributes, errors, the session's `store`, or browser storage of their own.
2295
2315
 
2296
2316
  ## Connecting to a provider
2297
2317
 
@@ -2303,17 +2323,17 @@ Creates one live provider connection for the signed-in agent.
2303
2323
  - Must resolve only when the connection can provide a meaningful snapshot.
2304
2324
  - May reject for authentication, configuration, or startup failure.
2305
2325
  - Must not create a second agent session merely because the underlying transport reconnects.
2306
- - **One client at a time per login, and the later one wins.** A second `connect()` on a login
2326
+ - **One client at a time per session, and the later one wins.** A second `connect()` on a session
2307
2327
  that already has a live client is the agent moving agent computers -- an agent computer left open at work, signed in
2308
2328
  from home. The provider takes the new connection, and ends the first with `transport-status`
2309
2329
  `error` and `recovery: "displaced"`, so the first agent computer stops stating capacity and reporting legs
2310
- and shows the agent they are signed in elsewhere. Two live clients on one login would be two
2330
+ and shows the agent they are signed in elsewhere. Two live clients on one session would be two
2311
2331
  sources for one agent, and the lead's list would follow whichever spoke last.
2312
2332
  - The returned connection owns reconnect until Omni calls `disconnect()` or aborts `context.signal`.
2313
- - May be called again on the same login after that: once per `Connection`, not once per login.
2333
+ - May be called again on the same session after that: once per `Connection`, not once per session.
2314
2334
  Omni disposes a connection whose `error` named `recovery: "reconnect"` with `disconnect()` and
2315
2335
  calls `connect()` afresh — see **`transport-status`**. `recovery: "reauthenticate"` ends the same
2316
- way, after the authentication flow has run on the same session and `loginId`: once the state
2336
+ way, after the authentication flow has run on the same session and `sessionId`: once the state
2317
2337
  returns to `authenticated`, Omni disposes the errored connection and calls `connect()` afresh.
2318
2338
  `expired` alone, with the transport not in `error`, keeps the connection.
2319
2339
 
@@ -2321,13 +2341,13 @@ Creates one live provider connection for the signed-in agent.
2321
2341
 
2322
2342
  | Field | Contract |
2323
2343
  | --- | --- |
2324
- | `protocolVersion` | Version negotiated before authentication. Fixed for this login. |
2325
- | `loginId` | Omni-generated identity for this login. It is the same value passed as `AuthenticationContext.loginId`, so an adapter can correlate this connection with the session that authenticated it. Stable across transport reconnects and changed only by a new login. |
2326
- | `autoAcceptTasks` | Agent local policy policy relayed to the provider at login, stated by the agent application on every connection and never assumed from its absence. When `true`, a pending task states its `acceptance`; when `false`, every task requires agent acceptance. Fixed for this connection, like everything else here: the provider states or omits `acceptance` by the value it was sent, and Omni validates by that same value, not by a policy that has since moved — a change reaches the provider through a fresh `connect()`. |
2344
+ | `protocolVersion` | Version negotiated before authentication. Fixed for this session. |
2345
+ | `sessionId` | Omni-generated identity for this session. It is the same value passed as `AuthenticationContext.sessionId`, so an adapter can correlate this connection with the session that authenticated it. Stable across transport reconnects and changed only by a new session. |
2346
+ | `autoAcceptTasks` | Agent local policy policy relayed to the provider at sign-in, stated by the agent application on every connection and never assumed from its absence. When `true`, a pending task states its `acceptance`; when `false`, every task requires agent acceptance. Fixed for this connection, like everything else here: the provider states or omits `acceptance` by the value it was sent, and Omni validates by that same value, not by a policy that has since moved — a change reaches the provider through a fresh `connect()`. |
2327
2347
  | `timeZone` | The same value passed as `AuthenticationContext.timeZone`. The provider stores it on the agent and carries it on the identity. See **The agent's day**. |
2328
2348
  | `languages` | The same value passed as `AuthenticationContext.languages`. See **The agent's languages**. |
2329
- | `phone` | The same value passed as `AuthenticationContext.phone`: how this login hears its calls. The type ties `host.mute` to it: a `softphone` login's agent application states what its Mute does, and a hardphone or conversation login's agent application cannot, so the omission is a compile error rather than a live seat's discovery. See **The station is the agent application's** in `guide/phone.md`. |
2330
- | `store` | The login's operational store, kept by the agent application for the life of the login, across a reload of the agent application, and cleared at sign-out: where an adapter that composes a record keeps what its platform cannot hold for it, such as the interaction legs an agent application reported. Three functions, by key. Never for anything sensitive, which is `AuthenticationContext.secrets`, a store an agent application may clear aggressively. **A task's keys carry its assignment id and go with the task**: a key written about a task names the assignment id in the key, and is deleted before the task's end is published, so that nothing of a closed task survives its ending and nothing is left for whatever comes next -- a record with legs the agent application never reported against it. A login-scoped key carries no assignment id and outlives any task. The harness requires the store of every connection (`store.shape`, `store.get`, `.set`, `.delete`), watches the one it hands over, and names a task's key still held after `task-ended` (`test.store.retained`) or written about the task after its end -- a persist hung off a timer that saw the task as it was (`test.store.late`). The ordinary late write is the agent application's, not the adapter's: an agent application reports a leg without waiting for the answer, so an unmute can follow `complete` by a tick, and the adapter answers a report about a task that has ended `failed` with `omni.assignment-not-found` and writes nothing -- the agent application ends its own open legs at the task's end, so such a report is the agent application's error to see, and an agent application reads every `recordStep` answer and awaits the one for the leg it closes at a task's end, the only moment a refusal is expected, since a report nobody waits for is an error nobody can see; an adapter that names no task in its keys gets no cleanup check, which is a gap rather than a pass, never an exemption: the obligation is that nothing of a closed task survives its ending, and an adapter that keeps every open task in one login-scoped value owes exactly that inside the value, where the harness cannot look. One key per task, named for it, is the shape the harness can hold, and the shape to reach for. The store lists nothing, so an adapter that needs to find its tasks keeps a login-scoped index of ids beside them; at the task's end it deletes the body first and reindexes after, since a crash between the two then leaves an index naming a task with no body, which a reader skips, where the other order leaves a body for a task that has ended, which is the hazard itself. A reader of the index tolerates an id with no body as an ending that was underway, not as corruption. |
2349
+ | `phone` | The same value passed as `AuthenticationContext.phone`: how this session hears its calls. The type ties `host.mute` to it: a `softphone` session's agent application states what its Mute does, and a hardphone or conversation session's agent application cannot, so the omission is a compile error rather than a live seat's discovery. See **The station is the agent application's** in `guide/phone.md`. |
2350
+ | `store` | The session's operational store, kept by the agent application for the life of the session, across a reload of the agent application, and cleared at sign-out: where an adapter that composes a record keeps what its platform cannot hold for it, such as the interaction legs an agent application reported. Three functions, by key. Never for anything sensitive, which is `AuthenticationContext.secrets`, a store an agent application may clear aggressively. **A task's keys carry its assignment id and go with the task**: a key written about a task names the assignment id in the key, and is deleted before the task's end is published, so that nothing of a closed task survives its ending and nothing is left for whatever comes next -- a record with legs the agent application never reported against it. A session-scoped key carries no assignment id and outlives any task. The harness requires the store of every connection (`store.shape`, `store.get`, `.set`, `.delete`), watches the one it hands over, and names a task's key still held after `task-ended` (`test.store.retained`) or written about the task after its end -- a persist hung off a timer that saw the task as it was (`test.store.late`). The ordinary late write is the agent application's, not the adapter's: an agent application reports a leg without waiting for the answer, so an unmute can follow `complete` by a tick, and the adapter answers a report about a task that has ended `failed` with `omni.assignment-not-found` and writes nothing -- the agent application ends its own open legs at the task's end, so such a report is the agent application's error to see, and an agent application reads every `recordStep` answer and awaits the one for the leg it closes at a task's end, the only moment a refusal is expected, since a report nobody waits for is an error nobody can see; an adapter that names no task in its keys gets no cleanup check, which is a gap rather than a pass, never an exemption: the obligation is that nothing of a closed task survives its ending, and an adapter that keeps every open task in one session-scoped value owes exactly that inside the value, where the harness cannot look. One key per task, named for it, is the shape the harness can hold, and the shape to reach for. The store lists nothing, so an adapter that needs to find its tasks keeps a session-scoped index of ids beside them; at the task's end it deletes the body first and reindexes after, since a crash between the two then leaves an index naming a task with no body, which a reader skips, where the other order leaves a body for a task that has ended, which is the hazard itself. A reader of the index tolerates an id with no body as an ending that was underway, not as corruption. |
2331
2351
  | `host` | The agent application's report of the agent's station — devices, permissions, network — to consult before declaring the agent ready to the platform, and on every change. See **The agent application reports, the adapter decides** in `guide/phone.md`. |
2332
2352
  | `signal` | Optional cancellation signal: the agent application giving up on this sign-in. When it is aborted, stop startup promptly, begin no new work, and reject `connect()` with `signal.reason`, as the web platform's own fetch does. The harness hands `connect()` a signal already aborted and names a connection made anyway (`connect.signal.aborted`) or a failure with anything but `signal.reason` (`connect.signal.reason`). |
2333
2353
  | `log` | Optional structured logging callback. Never include credentials, tokens, or sensitive contact data. |
@@ -2387,14 +2407,14 @@ because Omni renders that form itself. That is a local convenience and never rea
2387
2407
 
2388
2408
  ### `Snapshot`
2389
2409
 
2390
- What the login may do is declared on its `AuthenticationState` — see **What the login may do** —
2410
+ What the user may do is declared on the `AuthenticationState` — see **What the user may do** —
2391
2411
  not here. The snapshot carries what the provider holds for the agent now, and where that depends on
2392
- a capability it agrees with the login: a lead's snapshot carries `team`, nobody else's does.
2412
+ a capability it agrees with the user's capabilities: a lead's snapshot carries `team`, nobody else's does.
2393
2413
 
2394
2414
  | Field | Contract |
2395
2415
  | --- | --- |
2396
- | `transport` | Current `TransportStatus` — whether this provider's transport can serve the login. Defined under **`transport-status`**. |
2397
- | `loginId` | Identity of this login. It must match the connection context. |
2416
+ | `transport` | Current `TransportStatus` — whether this provider's transport can serve the session. Defined under **`transport-status`**. |
2417
+ | `sessionId` | Identity of this session. It must match the connection context. |
2398
2418
  | `providerTime` | The provider's own instant of this read. Required of a provider that declares `timeCheck` (`snapshot.providerTime`), forbidden of one that does not (`snapshot.providerTime.unexpected`): a clock sample the agent computer counts durations from, saving it a `checkTime`. |
2399
2419
  | `break` | Complete break state, including status, whether the agent may ask, reasons, retry details, and any forced break. |
2400
2420
  | `tasks` | Complete set of tasks currently offered to or owned by this agent. |
@@ -2406,7 +2426,7 @@ a capability it agrees with the login: a lead's snapshot carries `team`, nobody
2406
2426
  | `linedUp` | The call waiting in the agent's own queue, while one is: the caller as shown to this audience, the queue, the caller's wait, when it was lined up, and `release` where the provider lets the agent let it go. Not a task yet. Replaced whole by `lined-up`. See **The agent's own queue** in `guide/queue.md`. |
2407
2427
  | `labels` | The signed-in customer's own words for phases, history steps and kinds of work, per language, as its admin set them in the provider. Replaced whole by `labels-updated`. Omitted where the customer set none. See **Presentation labels**. |
2408
2428
  | `shift` | The agent's own day so far, as the provider counts it -- the same `Shift` their lead sees on the team member list, the same numbers from the same count. Replaced whole by `shift-updated`. Omitted only where the provider cannot say. See **The agent's day is on the wire**. |
2409
- | `team` | Required `TeamMembers` when the login declares `capabilities.lead` and the lead has the team feature on, `members: []` when nobody is in it. Forbidden otherwise — the login is the permission, and a lead who turned the feature off gets nothing of the team. |
2429
+ | `team` | Required `TeamMembers` when the user's capabilities include `lead` and the lead has the team feature on, `members: []` when nobody is in it. Forbidden otherwise — the user's capabilities are the permission, and a lead who turned the feature off gets nothing of the team. |
2410
2430
 
2411
2431
  ## Live connection
2412
2432
 
@@ -2425,17 +2445,17 @@ surface in one place, and what obliges an adapter to implement each one.
2425
2445
  | `execute(request)` | Always. Every channel has commands no capability gates — see **Which commands need a capability** in `guide/agent.md`. |
2426
2446
  | `getUserDetails(ids)` | The adapter publishes any `UserId`: on `ForcedBreak.by` where a person forced it, a team member list, or `history[].by`. Each `User` carries its `timeZone`; a person whose zone the provider cannot name is omitted from the answer, as any unresolvable id is. |
2427
2447
  | `dial(request)` | The manifest declares `idleCapabilities.dial`, and with it `dialOutcomes`. |
2428
- | `requestBreak(request)` | The login declares `capabilities.breaks`. |
2429
- | `commitBreak()` | The login declares `capabilities.breaks`. Commit and cancel are not optional halves of it. |
2430
- | `cancelBreak()` | The login declares `capabilities.breaks`. |
2431
- | `endBreak()` | The login declares `capabilities.breaks`. |
2432
- | `requestNextCall()`, `cancelNextCall()`, `releaseLinedUp()` | The login declares `capabilities.nextCall`. The three stand together: a lined-up call the agent could neither withdraw nor let go is a promise with no way out. See **The agent's own queue** in `guide/queue.md`. |
2433
- | `executeTeam(request)` | The login declares `capabilities.lead`: every lead act, on the team surface and nowhere else. See **Lead commands** in `guide/lead.md`. |
2434
- | `setPreference(request)` | The login declares `capabilities.preferences`: the person's choice has to have somewhere to go. |
2448
+ | `requestBreak(request)` | The user's capabilities include `breaks`. |
2449
+ | `commitBreak()` | The user's capabilities include `breaks`. Commit and cancel are not optional halves of it. |
2450
+ | `cancelBreak()` | The user's capabilities include `breaks`. |
2451
+ | `endBreak()` | The user's capabilities include `breaks`. |
2452
+ | `requestNextCall()`, `cancelNextCall()`, `releaseLinedUp()` | The user's capabilities include `nextCall`. The three stand together: a lined-up call the agent could neither withdraw nor let go is a promise with no way out. See **The agent's own queue** in `guide/queue.md`. |
2453
+ | `executeTeam(request)` | The user's capabilities include `lead`: the lead commands its lead capabilities allow, on the team surface and nowhere else. See **Lead commands** in `guide/lead.md`. |
2454
+ | `setPreference(request)` | The user's capabilities include `preferences`: the person's choice has to have somewhere to go. |
2435
2455
  | `recordStep(report)` | The manifest lists `softphone` among its `phones`. On a softphone the agent application mutes its own microphone on any call, and the provider's record has to have somewhere to take that leg; a hardphone's microphone is the phone's. See **The agent application records what it performs** in `guide/agent.md`. |
2436
2456
  | `openAudio(request)` | The manifest lists `softphone` among its `phones`. On a softphone the call's audio lands in Omni, so the adapter has to open it; a platform of hardphones alone never does. |
2437
2457
 
2438
- **The four break methods stand or fall together.** Declaring `capabilities.breaks` at login and then
2458
+ **The four break methods stand or fall together.** Declaring `capabilities.breaks` at sign-in and then
2439
2459
  implementing `requestBreak` without `commitBreak` leaves an agent granted a break that can never
2440
2460
  start, and the two-phase coordination in **Coordinating a multi-provider break** in `guide/breaks.md` has no way to
2441
2461
  report that: `granted` is a promise to honour a later commit.
@@ -2490,7 +2510,7 @@ that reads as a database key.
2490
2510
  - **Take the whole list in one call.** Omni resolves a team member list or an interaction history as a batch, and
2491
2511
  a per-id round trip multiplies that by its length.
2492
2512
  - **Omni caches a result for one hour, then resolves it again.** The identifier is stable across
2493
- logins but the name behind it is not, so the cache expires on a clock rather than living for the
2513
+ sessions but the name behind it is not, so the cache expires on a clock rather than living for the
2494
2514
  session. One hour is a starting figure and may be tuned; an adapter must not depend on any
2495
2515
  particular value, or on Omni asking again at any particular moment.
2496
2516
 
@@ -2513,8 +2533,8 @@ Stops the connection and releases adapter-owned resources.
2513
2533
 
2514
2534
  | Field | Contract |
2515
2535
  | --- | --- |
2516
- | `id` | Required identifier for this event, unique within the login. Omni does not act on it; it exists so an agent application log line and an adapter log line can be matched when something has to be traced. |
2517
- | `loginId` | Login session that produced the event. Omni rejects any other value, which only reaches it if an adapter kept an old connection emitting after a re-login. |
2536
+ | `id` | Required identifier for this event, unique within the session. Omni does not act on it; it exists so an agent application log line and an adapter log line can be matched when something has to be traced. |
2537
+ | `sessionId` | The session that produced the event. Omni rejects any other value, which only reaches it if an adapter kept an old connection emitting after signing in again. |
2518
2538
  | `occurredAt` | Valid RFC-3339 timestamp with an explicit timezone, representing provider observation time. |
2519
2539
  | `event` | Typed `ProviderEvent` payload. |
2520
2540
 
@@ -2603,13 +2623,13 @@ While the connection is active, the agent application checks immediately on opt-
2603
2623
  using a monotonic scheduler. Only one check may be outstanding. Missed ticks are skipped, never
2604
2624
  replayed in a burst. Each request has a fresh ID. The provider samples its own event/deadline
2605
2625
  clock after receiving the request and before returning `providerTime` as an ISO/RFC3339 instant,
2606
- with the request ID, authenticated login ID and `clockId`. No cached sample or adapter-local time
2626
+ with the request ID, authenticated session ID and `clockId`. No cached sample or adapter-local time
2607
2627
  may masquerade as provider time. A provider unable to sample that domain must not declare support.
2608
2628
  Clock authority replacement or a discontinuity changes `clockId`.
2609
2629
 
2610
2630
  Validate requests and responses with `validateProviderTimeCheckRequest` and
2611
2631
  `validateProviderTimeCheckResult`. The agent application also checks the outstanding request, provider/connection
2612
- and login, monotonic elapsed time and cancellation after the await: a late successful response is
2632
+ and session, monotonic elapsed time and cancellation after the await: a late successful response is
2613
2633
  still rejected. Reject samples at or beyond `timeoutMs`, or above `maxRoundTripMs`. Cancel local
2614
2634
  tracking and invalidate estimates on disconnect, logout, policy disable, clock change or clock
2615
2635
  jump; late results cannot restore them. Resume with a fresh check after reconnection. Expire a
@@ -2619,7 +2639,7 @@ Checking failure alone does not assert call/recording state or require a healthy
2619
2639
  This read-only check is not a task command. Protocol supplies declarations and validators; the
2620
2640
  agent application implements the scheduler and the provider implements the clock read.
2621
2641
 
2622
- The agent application may also expose `Host.estimateProviderTime({ providerId, loginId })`. It returns an ISO
2642
+ The agent application may also expose `Host.estimateProviderTime({ providerId, sessionId })`. It returns an ISO
2623
2643
  `at` in that provider's clock domain, the same explicit scope and `clockId`, or `undefined` when
2624
2644
  unavailable. Optional `uncertaintyMs` is an estimate, not a guaranteed bound. The method is optional
2625
2645
  at the agent application level and is deliberately absent from `HostGuarantees`. A provider declaring time
@@ -2664,7 +2684,7 @@ Loss has exactly one shape: the connection went away. The adapter reports `conne
2664
2684
  reconnects, and emits a `snapshot` event carrying complete state. That snapshot is the repair —
2665
2685
  whatever was missed while the connection was down is in it, and Omni replaces its provider view
2666
2686
  rather than reasoning about what it did not receive. A repair is an answer like any other: a
2667
- platform that has not yet answered for this login after a reconnect — a state read served empty by
2687
+ platform that has not yet answered for this session after a reconnect — a state read served empty by
2668
2688
  a backend that does not know the session yet — yields no snapshot, and the adapter stays
2669
2689
  `connecting` holding what it holds. See **Snapshots establish state; events report transactions**.
2670
2690
 
@@ -2699,7 +2719,7 @@ direction — the provider asking Omni to reconcile — and neither replaces the
2699
2719
  Carries a complete `Snapshot` after reconnect or when the provider explicitly requests
2700
2720
  reconciliation. `reason` is `reconnected` or `provider-requested`. Omni replaces the provider's
2701
2721
  current status, break state, tasks, contacts, scheduled activities, the agent's day and the team
2702
- member list with this snapshot. It carries what the login and its switches call for — the whole
2722
+ member list with this snapshot. It carries what the session and its switches call for — the whole
2703
2723
  team for a lead with the feature on, on every snapshot — and nothing they do not; a capability is withdrawn by a republished `authenticated`,
2704
2724
  never by an omission from a snapshot.
2705
2725
 
@@ -2715,27 +2735,27 @@ safe for the agent to see.
2715
2735
  | `error` | The adapter cannot serve the session and is not simply mid-reconnect. Say why in `message` (`event.transportStatus.message.required`), and say what revives it in `recovery` — both required here, and `recovery` forbidden on any other status. It is not terminal: an adapter that recovers on its own still reports `connecting` and then `active`, and one that cannot is revived as `recovery` says. |
2716
2736
 
2717
2737
  **An error names its recovery, and the agent application acts on that word.** The adapter knows why its session
2718
- died; the agent application knows how to run a login. `recovery` joins the two:
2738
+ died; the agent application knows how to run a sign-in. `recovery` joins the two:
2719
2739
 
2720
- - **`reconnect`** — the login is good and this connection is not: a backend restart, a session the
2740
+ - **`reconnect`** — the session is good and this connection is not: a backend restart, a session the
2721
2741
  platform no longer recognises. Omni calls `disconnect()` on the dead connection and then
2722
- `connect()` again on the same login — same `loginId` — and the fresh connect snapshot
2742
+ `connect()` again on the same session — same `sessionId` — and the fresh connect snapshot
2723
2743
  re-establishes state exactly as a reconnect snapshot does. `connect()` is once per
2724
- `Connection`, not once per login.
2725
- - **`reauthenticate`** — the session under the login lapsed and the same login can be restored: a
2744
+ `Connection`, not once per session.
2745
+ - **`reauthenticate`** — the provider's authorization lapsed and the same session can be restored: a
2726
2746
  token rejected, published as `expired`. A session ended from outside -- a remote logout, a
2727
2747
  permission withdrawn -- is `terminated`, which is the whole message and gets no transport `error`
2728
2748
  beside it (see **Authentication state**). Omni
2729
- runs the authentication flow first, on the same session and `loginId`, never through
2749
+ runs the authentication flow first, on the same session and `sessionId`, never through
2730
2750
  `signed-out`; the authentication session decides whether stored material refreshes it silently or
2731
2751
  the agent must act, exactly as at sign-in. Once the state returns to `authenticated`, Omni
2732
2752
  disposes the errored connection with `disconnect()` and calls `connect()` afresh, as for
2733
2753
  `reconnect`, and the fresh snapshot re-establishes state. The adapter tears nothing down itself
2734
2754
  and expects nothing to carry on: the connection that reported `error` is finished.
2735
- - **`displaced`** — another client connected on this login and took it: the agent moved agent computers.
2755
+ - **`displaced`** — another client connected on this session and took it: the agent moved agent computers.
2736
2756
  Nothing revives this connection on its own -- Omni does not reconnect, or it would take the
2737
- login straight back from the agent computer the agent just sat down at -- and the agent computer shows the agent
2738
- they are signed in elsewhere, with a way to take the login back, which is a `connect()` that
2757
+ session straight back from the agent computer the agent just sat down at -- and the agent computer shows the agent
2758
+ they are signed in elsewhere, with a way to take the session back, which is a `connect()` that
2739
2759
  displaces the other. See **`Adapter.connect(context)`**.
2740
2760
 
2741
2761
  **Before the connection exists.** A provider can hold a sign-in back before any connection
@@ -2760,7 +2780,7 @@ for the other to blink.
2760
2780
  whether they are on a break, or how much work they can take: capacity travels on `setCapacity`,
2761
2781
  availability on `BreakState`. Nor does it carry authentication — a session that expired reports
2762
2782
  `expired` on `AuthenticationState` and fails actions with `omni.not-authenticated`, while
2763
- the transport underneath may be perfectly `active`. Provider login identity likewise belongs to
2783
+ the transport underneath may be perfectly `active`. Provider sign-in identity likewise belongs to
2764
2784
  authentication state, not here.
2765
2785
 
2766
2786
  **Only `active` means work can arrive.** Omni stops expecting assignments in any other value, so an
@@ -2796,13 +2816,13 @@ Adapters and hosts can call `validateBreakTransition(before, after)` from the pa
2796
2816
  with two complete break objects before applying an event. It checks shape and the transition
2797
2817
  rules above; it does not mutate either state or apply the event. Report a violation visibly,
2798
2818
  retain the last accepted state without claiming it remains current, and reconcile from the
2799
- source. Continue to validate the full envelope/login and task/break consistency separately.
2819
+ source. Continue to validate the full envelope/session and task/break consistency separately.
2800
2820
  The conformance `BreakStream` validates its baseline, retains the last accepted state on a
2801
2821
  rejected delta, and sets `needsRecovery`. Transport loss also requires reseeding; an `active` transport
2802
2822
  notification alone does not restore a break baseline. Until a fresh validated snapshot is seeded, further
2803
2823
  break deltas are refused (`stream.breakState.baseline`); the first delta is never an implicit
2804
2824
  snapshot. `seed(snapshot)` returns violations, which callers must check. This is a conformance
2805
- tracker, not a complete production reducer: snapshot freshness, login/connection fencing and
2825
+ tracker, not a complete production reducer: snapshot freshness, session/connection fencing and
2806
2826
  full task consistency remain separately required.
2807
2827
 
2808
2828
  **Both sides must enforce the order.** The agent application validates immediately before dispatch; the
@@ -2972,7 +2992,7 @@ each connected provider.
2972
2992
  The whole `TeamMembers`, replacing what the lead had. It is emitted once, after the lead switches
2973
2993
  the team feature on, and to nobody the provider does not publish a team to; every snapshot while
2974
2994
  the feature is on carries the same whole team. The changes that follow arrive one member at a
2975
- time, below; the whole team is never resent for one of them. Nothing of the team goes to a login
2995
+ time, below; the whole team is never resent for one of them. Nothing of the team goes to a session
2976
2996
  that no longer declares `capabilities.lead` on a republished `authenticated`, or to a lead who
2977
2997
  turned the feature off (`event.team.features`).
2978
2998
 
@@ -3058,7 +3078,7 @@ wider goes through this key.
3058
3078
 
3059
3079
  ### `sameCapabilities(a, b)`
3060
3080
 
3061
- Whether two logins declare the same capabilities, field by field — key order aside, and with
3081
+ Whether two sessions declare the same capabilities, field by field — key order aside, and with
3062
3082
  `team: {}` distinct from `team` absent. It is the comparison an adapter makes before republishing
3063
3083
  `authenticated`, and the one `testAdapter` holds `refreshing` to.
3064
3084
 
@@ -3084,26 +3104,26 @@ same exported checks are used by Omni and adapter tests so their interpretations
3084
3104
  | `validateEventEnvelope(envelope, manifest)` | Envelope identity, timestamp, and the payload for each event type. |
3085
3105
  | `validateContact(contact, levels)` | Contact field shapes and attribute keys, and a locked number or email locked by a level `levels` names. Every field is optional, so this checks what is present rather than what is missing. |
3086
3106
  | `validateScheduledActivity(activity, levels)` | Required activity fields and start/end ordering, and its party as `validateContact` holds one. |
3087
- | `validateHostGuarantees(guarantees, path?, phone?)` | What an agent application promises: only the guarantees this contract names, each declared by presence and never `false`. Given the login's phone, the mute promise is held to it: `muteUnavailableOnHold` required of a softphone login's agent application and refused of any other (`host.guarantee.muteUnavailableOnHold.required` / `.unexpected`). The harness validates the guarantees of whatever agent application a test hands the adapter, against the phone it chose. |
3107
+ | `validateHostGuarantees(guarantees, path?, phone?)` | What an agent application promises: only the guarantees this contract names, each declared by presence and never `false`. Given the session's phone, the mute promise is held to it: `muteUnavailableOnHold` required of a softphone session's agent application and refused of any other (`host.guarantee.muteUnavailableOnHold.required` / `.unexpected`). The harness validates the guarantees of whatever agent application a test hands the adapter, against the phone it chose. |
3088
3108
  | `validateProviderTimeCheckPolicy(policy)` | Explicit optional polling settings, positive safe-integer durations and round-trip/timeout/interval ordering. |
3089
3109
  | `validateProviderTimeCheckRequest(request)` | Fresh-request shape; the agent application enforces actual uniqueness and outstanding-request lifetime. |
3090
- | `validateProviderTimeCheckResult(result, request, loginId)` | ISO timestamp, clock identity, exact request/login correlation; timing and source accuracy remain runtime checks. |
3091
- | `validateProviderTimeEstimate(estimate, scope)` | Optional agent application estimate shape and provider/login scope; no accuracy guarantee. |
3110
+ | `validateProviderTimeCheckResult(result, request, sessionId)` | ISO timestamp, clock identity, exact request/session correlation; timing and source accuracy remain runtime checks. |
3111
+ | `validateProviderTimeEstimate(estimate, scope)` | Optional agent application estimate shape and provider/session scope; no accuracy guarantee. |
3092
3112
  | `validateHistoryReport(report, path?, manifest?, task?)` | What the agent application reports of a leg it performed, for an adapter to check before forwarding: a task, a step, when it began, a positive `seconds` where stated, and an explicit `ended` that carries the final duration. Given the manifest, a running report is refused unless it declares `runningStepReports`. Given the task, the agent application's own mute beginning on a `paused` task is refused (`historyReport.muted.held`): the Mute waits for resume. |
3093
3113
  | `validateHostReport(report)` | The agent application's own report as published to an adapter: `online`, and where there is audio, an input that is `available` with the microphone and `flowing`, or `unavailable` with a reason and the failure that says why, and an output that is `available` or `unavailable` with its failure. The harness validates whatever agent application a test hands the adapter; `stillHost(report)` builds one that never changes. |
3094
3114
  | `validateNextCall(value)` | The agent's standing ask for the next call, on its own as `next-call` and `Snapshot.nextCall` carry it: since when, and nothing else (`nextCall.since`, `nextCall.field`). |
3095
3115
  | `validateLinedUp(value, levels, path?)` | A call lined up in the agent's own queue, on its own as `lined-up` and `Snapshot.linedUp` carry it: the caller under the same contact rules as a task's party, the queue's label, the waits, and `release` by presence (`linedUp.*`). |
3096
3116
  | `validateLabels(value, path?)` | The customer's words on their own, as `labels-updated` and `Snapshot.labels` carry them: renames of the protocol's phases and steps only, and every word one text per well-formed language tag (`labels.*`). |
3097
3117
  | `validatePhoneState(value, path?, context?)` | The phone as the platform sees it, on its own as `phone-updated` and `Snapshot.phone` carry it: its status, its one active channel, its mute where a hardphone's is observed (`phone.*`). |
3098
- | `validateHostMute(mute, softphone)` | What the agent application's Mute does, stated on a softphone login and nowhere else: `stream` or `station` (`host.mute`), required where the agent application holds a microphone (`host.mute.required`) and refused where it does not (`host.mute.unexpected`). The harness holds `ConnectContext.host.mute` to it. |
3118
+ | `validateHostMute(mute, softphone)` | What the agent application's Mute does, stated on a softphone session and nowhere else: `stream` or `station` (`host.mute`), required where the agent application holds a microphone (`host.mute.required`) and refused where it does not (`host.mute.unexpected`). The harness holds `ConnectContext.host.mute` to it. |
3099
3119
  | `validateLanguages(languages)` | The agent's languages a host states on both contexts: a non-empty list (`context.languages`) of well-formed BCP 47 tags (`context.languages.tag`), none twice ignoring case (`context.languages.unique`). The harness holds `ConnectContext.languages` to it. |
3100
- | `validateLoginStore(store)` | The login's store the agent application hands every connection: an object with `get`, `set` and `delete` (`store.shape`, `store.get`, `.set`, `.delete`). The harness holds `ConnectContext.store` to it. |
3120
+ | `validateSessionStore(store)` | The session's store the agent application hands every connection: an object with `get`, `set` and `delete` (`store.shape`, `store.get`, `.set`, `.delete`). The harness holds `ConnectContext.store` to it. |
3101
3121
  | `validateCapacity(capacity)` | What the agent application states as capacity: a whole number of zero or more (`capacity.count`), zero being agent application-stopped. The harness states one on connect and two, one and zero after the test, each answered `applied`, and holds any offer to the count in force (`stream.taskOffered.overCapacity`). |
3102
- | `validateAuthenticationResult(result, method, path, { levels })` | What `start()` or `complete()` answered: a challenge or a rejection, a login or a rejection. A rejection's failure is held to its rules -- an `omni.` code the contract lists, and `omni.phone-not-permitted` never retryable, since the agent's station is configuration. `validateAuthenticationFailure(failure)` is the same check on a failure alone. |
3122
+ | `validateAuthenticationResult(result, method, path, { levels })` | What `start()` or `complete()` answered: a challenge or a rejection, a session or a rejection. A rejection's failure is held to its rules -- an `omni.` code the contract lists, and `omni.phone-not-permitted` never retryable, since the agent's station is configuration. `validateAuthenticationFailure(failure)` is the same check on a failure alone. |
3103
3123
  | `validateRedirectUri(uri, path?)` | A host's fixed redirect URI in one of RFC 8252's forms: `https`, a reverse-domain private-use scheme, or loopback http to `127.0.0.1` or `[::1]`, with no fragment (`redirectUri.*`). |
3104
- | `validateTaskCommand(command, task?, path, { levels })` | What a command needs to be issuable, against the task it names: its own shape -- a dial's `dialId`, a conference's item, a schedule's time, a remove naming exactly one person -- and, with the task, the capability the table above gates it on (`command.capability.<name>`, `.locked`), the phase it belongs to (`command.phase.*`, `command.phase.interaction` for every control on the call or the conversation), and the state that has to stand: a lead requested, somebody else still on the call (`command.conference.remove.alone`), the caller off hold before the agent's part ends (`command.endCall.held`). An agent application validates before sending and an adapter before acting. |
3124
+ | `validateTaskCommand(command, task?, path, { levels })` | What a command needs to be issuable, against the task it names: its own shape -- a dial's `dialId`, an add's contact or number, a schedule's time, a remove naming exactly one person -- and, with the task, the capability the table above gates it on (`command.capability.<name>`, `.locked`), the phase it belongs to (`command.phase.*`, `command.phase.interaction` for every control on the call or the conversation), and the state that has to stand: a lead requested, somebody else still on the call (`command.removeFromCall.alone`), the caller off hold before the agent's part ends (`command.endCall.held`). An agent application validates before sending and an adapter before acting. |
3105
3125
  | `validateResult(result, method)` | What a connection method answered: the status it gives, a failure where the status says so and nowhere else, the failure's shape, and that an `omni.` code is one this contract names. |
3106
- | `validateAuthenticationState(state, path, { levels })` | The identity each state must carry, the capabilities a usable login declares, and the expiry that only `authenticated` may. Omni applies it to every state a session publishes — the republished as much as the first. |
3126
+ | `validateAuthenticationState(state, path, { levels })` | The identity each state must carry, the capabilities a usable state declares for the user, and the expiry that only `authenticated` may. Omni applies it to every state a session publishes — the republished as much as the first. |
3107
3127
 
3108
3128
  Every check that reads a level — a `lockedBy`, a `setBy` — is given `levels`, the ids of the
3109
3129
  manifest's `orgLevels`, and refuses any other; `validateSnapshot` and `validateEventEnvelope` take
@@ -3116,9 +3136,9 @@ found at such as `snapshot.tasks[0].browsers[1].url`, and a `message`.
3116
3136
 
3117
3137
  Some rules need to know who is reading. `validateTeamMembers`, `validateSnapshot`, and
3118
3138
  `validateEventEnvelope` take an optional final `{ self, capabilities, leadFeatures }` — the signed-in agent's
3119
- `AuthenticationState.identity.id` and their login's `capabilities`. Given `self`, a team member list that
3120
- carries that agent reports `team.member.self`, on a `team-member-updated` and a `team-member-removed` as on the list. Given `capabilities`, a team member list published to a login that does not lead
3121
- reports `team.unentitled`, and a team event to such a login reports `event.team.capability`; given
3139
+ `AuthenticationState.identity.id` and their `capabilities` for the session. Given `self`, a team member list that
3140
+ carries that agent reports `team.member.self`, on a `team-member-updated` and a `team-member-removed` as on the list. Given `capabilities`, a team member list published to a user who does not lead
3141
+ reports `team.unentitled`, and a team event to such a session reports `event.team.capability`; given
3122
3142
  `leadFeatures: true`, a snapshot without a team reports `team.required`, and given `leadFeatures: false`,
3123
3143
  anything of the team reaching the lead reports `team.unexpected` or `event.team.features`. Without them those rules are not checked, because they cannot be.
3124
3144
  `testAdapter` passes all three, holding the switch off until it has sent it. Given the manifest, a
@@ -3162,7 +3182,7 @@ Adapter conformance exercise from `@xema/omni-protocol/testing`.
3162
3182
 
3163
3183
  It validates the manifest, opens an authenticated session, connects, checks required capability
3164
3184
  methods, subscribes, validates the snapshot, every delivered event, and every authentication state
3165
- the session publishes during the run — each against the latest login, since capabilities are
3185
+ the authentication session publishes during the run — each against the latest such state, since capabilities are
3166
3186
  current, not fixed — states a capacity, then unsubscribes and disconnects. Provider packages should
3167
3187
  run it with a deterministic test transport and authentication state.
3168
3188
 
@@ -3175,12 +3195,12 @@ expect(result.violations).toEqual([]);
3175
3195
  expect(result.disconnectWasClean).toBe(true);
3176
3196
  ```
3177
3197
 
3178
- `result.authenticationState` is the state the session was restored with; `result.login` is the
3179
- latest the session published during the run, which differs only when the adapter republished
3198
+ `result.authenticationState` is the state the authentication session was restored with; `result.signedIn` is the
3199
+ latest it published during the run, which differs only when the adapter republished
3180
3200
  `authenticated`. A published state that fails validation is reported and not adopted, and a
3181
- `refreshing` state must carry over the login it refreshes — a different identity is
3201
+ `refreshing` state must carry over the session it refreshes — a different identity is
3182
3202
  `authentication.refreshing.identity`, a changed capability set `authentication.refreshing.capabilities`.
3183
- A capability granted by a later login requires its methods just as one declared at sign-in does.
3203
+ A capability granted by a later session requires its methods just as one declared at sign-in does.
3184
3204
 
3185
3205
  `result.notTested` lists what the run never reached — one subject per family of rules: each
3186
3206
  optional part of a task (`task.browsers`, `task.history`, `task.leadAssist`, …), the break's
@@ -3208,8 +3228,8 @@ capacity, or beyond the count with nothing dialled on it, is named
3208
3228
  (`stream.taskOffered.beforeCapacity`, `.overCapacity`); every user the snapshot names is looked up
3209
3229
  through `getUserDetails` and the answer held to the shape, nobody unasked, nobody described as
3210
3230
  nothing (`getUserDetails.user.*`, `getUserDetails.unasked`, `connection.getUserDetails.empty`); and
3211
- the second adapter a `rebuild` gives comes up signed in as the same login from the secrets alone
3212
- before it reads anything (`test.reload.login`), and is then held to everything the first was on
3231
+ the second adapter a `rebuild` gives comes up signed in as the same session from the secrets alone
3232
+ before it reads anything (`test.reload.session`), and is then held to everything the first was on
3213
3233
  connect: the methods its declarations call for, the agent application's report, a capacity stated to it, its
3214
3234
  snapshot read as the connect snapshot was, and its audio opened afresh on a task carried with
3215
3235
  `audio: "started"`, since the first client's session died with it. The result also says which rules the
@@ -3229,7 +3249,7 @@ Where the provider restates the task's record afterwards, each leg is in it or t
3229
3249
  (`test.recordStep.history`). Given `rebuild`, a way to build the adapter again as an agent application reload
3230
3250
  does, the test reloads the agent application as a reload happens: the first client is unsubscribed,
3231
3251
  disconnected and its session closed (`test.reload.handover`), and only then is a second adapter
3232
- built and connected for the same login with the same context and the same `store`; its snapshot
3252
+ built and connected for the same session with the same context and the same `store`; its snapshot
3233
3253
  must carry the task with that leg at its acknowledged provider timestamp and the reported actor, and the run goes on with the second as its
3234
3254
  connection to the end. A platform that holds the record hands it back, and an adapter that composed
3235
3255
  the record in memory has nothing and is named (`test.reload.snapshot`, `test.reload.history`,
@@ -3291,7 +3311,7 @@ Three properties of the harness matter to adapter authors:
3291
3311
  - **Resources are released even when the adapter fails.** Every unsubscribe, `disconnect()`, and
3292
3312
  `close()` run in a `finally` block, and a throw from any of them is reported as
3293
3313
  `disconnectWasClean: false` rather than being hidden.
3294
- - **The login is read, never captured.** Everything is validated against the latest
3314
+ - **The session is read, never captured.** Everything is validated against the latest
3295
3315
  `authenticated` state, so a withdrawal published before a snapshot is held against that snapshot.
3296
3316
 
3297
3317
  ### Contract scenarios
@@ -3301,7 +3321,7 @@ cannot be established from TypeScript structure alone.
3301
3321
 
3302
3322
  | Helper | Contract checked |
3303
3323
  | --- | --- |
3304
- | `assertCapabilityWithdrawal(states, snapshot, manifest)` | A capability withdrawn by a later `authenticated` state is gone from the next snapshot: no team member list for a login that no longer leads. Every state is validated on the way, `refreshing` must carry the login over, and the sequence passes only through usable states. |
3324
+ | `assertCapabilityWithdrawal(states, snapshot, manifest)` | A capability withdrawn by a later `authenticated` state is gone from the next snapshot: no team member list for a session that no longer leads. Every state is validated on the way, `refreshing` must carry the session over, and the sequence passes only through usable states. |
3305
3325
  | `assertTaskCapabilityWithdrawal(tasks, manifest, command)` | A capability withdrawn by a republish of the task is gone from the task: every task in the sequence is validated, all carry the offer's id, at least one capability the offer declared is absent at the end (a locked control is present, not withdrawn), and `command` is clean against the first task and refused against the last for want of a withdrawn capability and nothing else. Pair it with `assertCommandRefusedAfterWithdrawal` on the provider's answer. |
3306
3326
  | `assertCommandRefusedAfterWithdrawal(result)` | A command that arrives after its capability was withdrawn fails with `omni.capability-not-enabled`, named by the provider. The same assertion serves a command the provider never supported under a capability it declares. |
3307
3327
  | `assertReached(result, subjects)` | The exercise met every subject named; throws listing those it did not. Pair it with a clean `testAdapter` result. |
@@ -3312,8 +3332,8 @@ cannot be established from TypeScript structure alone.
3312
3332
  | `assertBreakFollowsItsRequests(envelopes, snapshot?)` | A break follows its requests: a commit's states only after a grant, never backwards, and a forced break arriving in effect with `forced`. The harness applies the same rules after the connect snapshot. |
3313
3333
  | `assertAudioFollowsTheTask(envelopes, snapshot?)` | The audio follows the task and never decides it: every task is introduced once, `task-audio-started` and `task-audio-ended` alternate on work that has begun, audio ends only where it arrived, and what follows the audio ending is `completing` or `task-ended`. The harness applies the same rules to every event after the connect snapshot (`stream.*`). A sequence with no audio satisfies it by never testing it — pair it with the assertion that the audio end is present. |
3314
3334
  | `assertHistoryAgreesAcrossTasks(earlier, later)` | Two tasks of one call -- a hand-over, a take-over, a callback: the later restates every earlier step in order, with the same step, instant, person, dial and destination, and any duration already stated unchanged. Throws when either carries no history. |
3315
- | `assertBreakAttemptProviders(candidates, asked)` | A break attempt asks every usable provider holding capacity, `refreshing` included, and nothing of a provider whose login is `expired`. |
3316
- | `assertForcedBreakStopsTheRest(forcedOn, candidates, stopped)` | A forced break on one provider stops the agent everywhere else: capacity zero stated on every other usable provider holding capacity, nothing on the forcing one, nothing on a dead login. See **Forced breaks** in `guide/breaks.md`. |
3335
+ | `assertBreakAttemptProviders(candidates, asked)` | A break attempt asks every usable provider holding capacity, `refreshing` included, and nothing of a provider whose session is `expired`. |
3336
+ | `assertForcedBreakStopsTheRest(forcedOn, candidates, stopped)` | A forced break on one provider stops the agent everywhere else: capacity zero stated on every other usable provider holding capacity, nothing on the forcing one, nothing on a dead session. See **Forced breaks** in `guide/breaks.md`. |
3317
3337
  | `assertBreakBeginsAfterTask(steps)` | A break asked for on a task is committed as `starting-after-task` while work remains and reaches `on-break` only once nothing is outstanding — never beside a task, never later than the step that has none. |
3318
3338
  | `assertDeniedAndRetriedBreak(states)` | A denial transitions directly to `not-requested`; a later request can still be granted. |
3319
3339
  | `assertBrowserSessionIsolation(left, right, expected)` | Browser reuse follows only the declared isolation scheme. |