@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/GLOSSARY.md +2 -2
- package/README.md +6 -8
- package/dist/index.d.ts +138 -87
- package/dist/index.js +24 -9
- package/dist/testing.d.ts +14 -14
- package/dist/testing.js +79 -82
- package/dist/validation.d.ts +23 -23
- package/dist/validation.js +174 -121
- package/guide/agent.md +23 -23
- package/guide/breaks.md +1 -1
- package/guide/lead.md +34 -17
- package/guide/phone.md +22 -22
- package/guide/queue.md +7 -7
- package/guide/voice.md +64 -54
- package/guide.md +163 -143
- package/package.json +1 -1
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,
|
|
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;
|
|
44
|
-
| **Lead** | An agent whose
|
|
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
|
|
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
|
-
| **
|
|
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
|
|
55
|
-
| **Connection** | The `Connection` object Omni holds for one
|
|
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,
|
|
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
|
|
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
|
|
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
|
-
|
|
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?:
|
|
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;
|
|
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
|
|
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
|
-
|
|
438
|
+
sessionId: string;
|
|
425
439
|
autoAcceptTasks: boolean;
|
|
426
440
|
timeZone: TimeZone;
|
|
427
441
|
languages: readonly LanguageTag[];
|
|
428
|
-
store:
|
|
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
|
-
|
|
541
|
+
sessionId: string;
|
|
528
542
|
providerTime?: IsoTimestamp;
|
|
529
543
|
break: BreakState;
|
|
530
544
|
tasks: Task[];
|
|
531
545
|
taskCount: number;
|
|
532
|
-
contacts?:
|
|
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
|
|
590
|
-
|
|
591
|
-
|
|
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
|
-
|
|
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
|
-
| "
|
|
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
|
-
|
|
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" | "
|
|
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: "
|
|
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
|
-
"
|
|
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: "
|
|
862
|
-
| { type: "
|
|
863
|
-
| { type: "
|
|
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,
|
|
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
|
|
963
|
-
`
|
|
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
|
|
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
|
|
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;
|
|
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:
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
"
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
2053
|
-
| `
|
|
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
|
|
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
|
|
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
|
|
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
|
|
2087
|
-
|
|
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
|
|
2091
|
-
kept, under the same `
|
|
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
|
|
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
|
|
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
|
|
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
|
|
2128
|
+
### What the user may do
|
|
2109
2129
|
|
|
2110
|
-
`capabilities` declares provider actions available to this
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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 `
|
|
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
|
|
2325
|
-
| `
|
|
2326
|
-
| `autoAcceptTasks` | Agent local policy policy relayed to the provider at
|
|
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
|
|
2330
|
-
| `store` | The
|
|
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
|
|
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
|
|
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
|
|
2397
|
-
| `
|
|
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
|
|
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
|
|
2429
|
-
| `commitBreak()` | The
|
|
2430
|
-
| `cancelBreak()` | The
|
|
2431
|
-
| `endBreak()` | The
|
|
2432
|
-
| `requestNextCall()`, `cancelNextCall()`, `releaseLinedUp()` | The
|
|
2433
|
-
| `executeTeam(request)` | The
|
|
2434
|
-
| `setPreference(request)` | The
|
|
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
|
|
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
|
-
|
|
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
|
|
2517
|
-
| `
|
|
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
|
|
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
|
|
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,
|
|
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
|
|
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
|
|
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
|
|
2738
|
+
died; the agent application knows how to run a sign-in. `recovery` joins the two:
|
|
2719
2739
|
|
|
2720
|
-
- **`reconnect`** — 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
|
|
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
|
|
2725
|
-
- **`reauthenticate`** — the
|
|
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 `
|
|
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
|
|
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
|
-
|
|
2738
|
-
they are signed in elsewhere, with a way to take the
|
|
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
|
|
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/
|
|
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,
|
|
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
|
|
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
|
|
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
|
|
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,
|
|
3091
|
-
| `validateProviderTimeEstimate(estimate, scope)` | Optional agent application estimate shape and provider/
|
|
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
|
|
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
|
-
| `
|
|
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
|
|
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`,
|
|
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
|
|
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
|
|
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
|
|
3121
|
-
reports `team.unentitled`, and a team event to such a
|
|
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
|
|
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.
|
|
3179
|
-
latest
|
|
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
|
|
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
|
|
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
|
|
3212
|
-
before it reads anything (`test.reload.
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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. |
|