@xema/omni-protocol 0.1.132 → 0.1.134
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/CALL_FLOW.md +1 -1
- package/GLOSSARY.md +5 -4
- package/README.md +4 -4
- package/dist/index.d.ts +100 -58
- package/dist/index.js +12 -6
- package/dist/testing.d.ts +9 -1
- package/dist/testing.js +133 -2
- package/dist/validation.js +63 -24
- package/guide/agent.md +28 -19
- package/guide/breaks.md +362 -25
- package/guide/chat.md +1 -1
- package/guide/lead.md +19 -15
- package/guide/phone.md +8 -7
- package/guide/queue.md +2 -292
- package/guide/voice.md +6 -6
- package/guide.md +90 -69
- package/package.json +1 -1
package/guide.md
CHANGED
|
@@ -41,8 +41,8 @@ are used precisely throughout and mean nothing looser here.
|
|
|
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
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
|
|
45
|
-
| **Local policy** | Rules configured by the agent application about this agent, outside the provider protocol
|
|
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 user's capabilities are 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. It gates whether an offer may be rejected, whether the agent goes ready on session, and whether tasks are auto-accepted; only that last reaches the provider, as `autoAcceptTasks` at connect, so it can state `acceptance`. 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. |
|
|
@@ -167,9 +167,11 @@ type TimeZone = string;
|
|
|
167
167
|
type User = {
|
|
168
168
|
id: UserId;
|
|
169
169
|
displayName: string;
|
|
170
|
-
timeZone
|
|
170
|
+
timeZone?: TimeZone;
|
|
171
171
|
};
|
|
172
172
|
|
|
173
|
+
type SignedInUser = User & { timeZone: TimeZone };
|
|
174
|
+
|
|
173
175
|
type Attribute = { key: string; value: string };
|
|
174
176
|
```
|
|
175
177
|
|
|
@@ -323,10 +325,10 @@ type LeadCapabilities = {
|
|
|
323
325
|
type AuthenticationState =
|
|
324
326
|
| { status: "signed-out" }
|
|
325
327
|
| { status: "authenticating" }
|
|
326
|
-
| { status: "authenticated"; identity:
|
|
327
|
-
| { status: "refreshing"; identity:
|
|
328
|
-
| { status: "expired"; identity?:
|
|
329
|
-
| { status: "terminated"; by: UserId | "provider"; identity?:
|
|
328
|
+
| { status: "authenticated"; identity: SignedInUser; capabilities: UserCapabilities; expiresAt?: IsoTimestamp }
|
|
329
|
+
| { status: "refreshing"; identity: SignedInUser; capabilities: UserCapabilities }
|
|
330
|
+
| { status: "expired"; identity?: SignedInUser; failure?: AuthenticationFailure }
|
|
331
|
+
| { status: "terminated"; by: UserId | "provider"; identity?: SignedInUser; failure: AuthenticationFailure & { retryable: false } };
|
|
330
332
|
|
|
331
333
|
type AuthenticationFailure = {
|
|
332
334
|
code: string;
|
|
@@ -477,7 +479,7 @@ type CompleteAuthenticationRequest =
|
|
|
477
479
|
| { flowId: string; method: "credentials"; values: Readonly<Record<string, string>> };
|
|
478
480
|
|
|
479
481
|
type CompleteAuthenticationResult =
|
|
480
|
-
| { status: "authenticated"; identity:
|
|
482
|
+
| { status: "authenticated"; identity: SignedInUser; capabilities: UserCapabilities; expiresAt?: IsoTimestamp }
|
|
481
483
|
| { status: "rejected"; failure: AuthenticationFailure };
|
|
482
484
|
|
|
483
485
|
type AuthenticationActionResult =
|
|
@@ -536,12 +538,12 @@ type PreferenceResult =
|
|
|
536
538
|
| { status: "applied" }
|
|
537
539
|
| { status: "failed"; failure: ProtocolFailure };
|
|
538
540
|
|
|
539
|
-
type Snapshot = {
|
|
541
|
+
type Snapshot<C extends Channel = Channel> = {
|
|
540
542
|
transport: TransportStatus;
|
|
541
543
|
sessionId: string;
|
|
542
544
|
providerTime?: IsoTimestamp;
|
|
543
545
|
break: BreakState;
|
|
544
|
-
tasks: Task[];
|
|
546
|
+
tasks: Task<C>[];
|
|
545
547
|
taskCount: number;
|
|
546
548
|
contacts?: ContactEntry[];
|
|
547
549
|
calendar?: ScheduledActivity[];
|
|
@@ -554,7 +556,7 @@ type Snapshot = {
|
|
|
554
556
|
};
|
|
555
557
|
|
|
556
558
|
type AgentCapacity = {
|
|
557
|
-
count: number; // absolute ceiling, zero or more; zero is agent application
|
|
559
|
+
count: number; // absolute ceiling, zero or more; zero is stopped by the agent application
|
|
558
560
|
};
|
|
559
561
|
|
|
560
562
|
type CapacityResult = { status: "applied" };
|
|
@@ -686,7 +688,7 @@ type BrowserProfileKeyInput = {
|
|
|
686
688
|
```
|
|
687
689
|
|
|
688
690
|
That union is what makes a reusing browser with no scheme fail to compile rather than inherit a
|
|
689
|
-
default — see **Choosing an isolation scheme
|
|
691
|
+
default — see **Choosing an isolation scheme** in `guide/agent.md`.
|
|
690
692
|
|
|
691
693
|
### Task
|
|
692
694
|
|
|
@@ -723,6 +725,7 @@ type HistoryStep =
|
|
|
723
725
|
| "transferred"
|
|
724
726
|
| "added"
|
|
725
727
|
| "unanswered"
|
|
728
|
+
| "connected-back"
|
|
726
729
|
| "callback-requested";
|
|
727
730
|
|
|
728
731
|
type TaskHistory = {
|
|
@@ -915,7 +918,7 @@ type TaskCommandResult =
|
|
|
915
918
|
|
|
916
919
|
### Who decides what an agent may do
|
|
917
920
|
|
|
918
|
-
An agent
|
|
921
|
+
An agent computer has two managers, not one. **The queue** — a process, a work type — is owned by a
|
|
919
922
|
process manager and **allows** a set of capabilities: hold, connect back, dial, add to call,
|
|
920
923
|
whether the number is visible, the actions it offers, the skills it needs. **The people** are
|
|
921
924
|
managed through the organisation's structure — a team, a location, the organisation itself, in
|
|
@@ -1023,9 +1026,12 @@ type BreakRequest = {
|
|
|
1023
1026
|
reasonId?: string;
|
|
1024
1027
|
};
|
|
1025
1028
|
|
|
1029
|
+
type ForcedBreakScope = "team" | "agent";
|
|
1030
|
+
|
|
1026
1031
|
type ForcedBreak = {
|
|
1027
1032
|
by: UserId | "provider";
|
|
1028
|
-
|
|
1033
|
+
scope: ForcedBreakScope;
|
|
1034
|
+
endsInSeconds?: DurationSeconds;
|
|
1029
1035
|
};
|
|
1030
1036
|
|
|
1031
1037
|
type BreakState = {
|
|
@@ -1033,7 +1039,7 @@ type BreakState = {
|
|
|
1033
1039
|
canRequestBreak: boolean;
|
|
1034
1040
|
requestUnavailableReason?: string;
|
|
1035
1041
|
decisionReason?: string;
|
|
1036
|
-
|
|
1042
|
+
retryRequestInSeconds?: DurationSeconds;
|
|
1037
1043
|
reasons?: BreakReason[];
|
|
1038
1044
|
activeReasonId?: string;
|
|
1039
1045
|
forced?: ForcedBreak;
|
|
@@ -1136,6 +1142,13 @@ type ShiftEvent = {
|
|
|
1136
1142
|
kind: ShiftEventKind;
|
|
1137
1143
|
};
|
|
1138
1144
|
|
|
1145
|
+
type ShiftFigure = "talk" | "hold" | "break";
|
|
1146
|
+
|
|
1147
|
+
type ShiftRunning = {
|
|
1148
|
+
figure: ShiftFigure;
|
|
1149
|
+
since: IsoTimestamp;
|
|
1150
|
+
};
|
|
1151
|
+
|
|
1139
1152
|
type Shift = {
|
|
1140
1153
|
signedInAt: IsoTimestamp;
|
|
1141
1154
|
signedOutAt?: IsoTimestamp;
|
|
@@ -1143,6 +1156,7 @@ type Shift = {
|
|
|
1143
1156
|
holdSeconds?: DurationSeconds;
|
|
1144
1157
|
breakSeconds?: DurationSeconds;
|
|
1145
1158
|
tasksHandled?: number;
|
|
1159
|
+
running?: ShiftRunning[];
|
|
1146
1160
|
events?: ShiftEvent[];
|
|
1147
1161
|
};
|
|
1148
1162
|
|
|
@@ -1182,8 +1196,10 @@ type TeamCallCommand =
|
|
|
1182
1196
|
type TeamBreakCommand =
|
|
1183
1197
|
| { type: "decide-break-request"; memberId: UserId; decision: "granted" | "denied"; reason?: string }
|
|
1184
1198
|
| { type: "set-break-policy"; policy: "approval-required" | "automatically-approved" | "requests-suspended" }
|
|
1185
|
-
| { type: "force-break"; memberId: UserId; reasonId?: string; reason?: string;
|
|
1186
|
-
| { type: "
|
|
1199
|
+
| { type: "force-break"; memberId: UserId; reasonId?: string; reason?: string; durationSeconds?: DurationSeconds }
|
|
1200
|
+
| { type: "force-team-break"; reasonId?: string; reason?: string; durationSeconds: DurationSeconds }
|
|
1201
|
+
| { type: "end-forced-break"; memberId: UserId }
|
|
1202
|
+
| { type: "end-team-break" };
|
|
1187
1203
|
|
|
1188
1204
|
type TeamCommand = TeamFeatureCommand | TeamBreakCommand | TeamCallCommand | TeamPolicyCommand;
|
|
1189
1205
|
|
|
@@ -1230,16 +1246,16 @@ type QueueSummary = {
|
|
|
1230
1246
|
|
|
1231
1247
|
type TransportRecovery = "reconnect" | "reauthenticate" | "displaced";
|
|
1232
1248
|
|
|
1233
|
-
type ProviderEvent =
|
|
1234
|
-
| { type: "snapshot"; reason: "reconnected" | "provider-requested"; snapshot: Snapshot }
|
|
1249
|
+
type ProviderEvent<C extends Channel = Channel> =
|
|
1250
|
+
| { type: "snapshot"; reason: "reconnected" | "provider-requested"; snapshot: Snapshot<C> }
|
|
1235
1251
|
| { type: "transport-status"; status: "connecting" | "active"; message?: string }
|
|
1236
1252
|
| { type: "transport-status"; status: "error"; recovery: TransportRecovery; message: string }
|
|
1237
1253
|
| { type: "break-state"; break: BreakState }
|
|
1238
1254
|
| {
|
|
1239
1255
|
type: "task-offered";
|
|
1240
|
-
task: Task
|
|
1256
|
+
task: Task<C>;
|
|
1241
1257
|
}
|
|
1242
|
-
| { type: "task-updated"; task: Task }
|
|
1258
|
+
| { type: "task-updated"; task: Task<C> }
|
|
1243
1259
|
| { type: "task-audio-started"; assignmentId: AssignmentId }
|
|
1244
1260
|
| { type: "task-audio-ended"; assignmentId: AssignmentId }
|
|
1245
1261
|
| { type: "task-ended"; assignmentId: AssignmentId; outcome: TaskOutcome }
|
|
@@ -1259,11 +1275,11 @@ type ProviderEvent =
|
|
|
1259
1275
|
| { type: "lined-up"; linedUp?: LinedUpCall }
|
|
1260
1276
|
| { type: "labels-updated"; labels: Labels };
|
|
1261
1277
|
|
|
1262
|
-
type ProviderEventEnvelope = {
|
|
1278
|
+
type ProviderEventEnvelope<C extends Channel = Channel> = {
|
|
1263
1279
|
id: string;
|
|
1264
1280
|
sessionId: string;
|
|
1265
1281
|
occurredAt: IsoTimestamp;
|
|
1266
|
-
event: ProviderEvent
|
|
1282
|
+
event: ProviderEvent<C>;
|
|
1267
1283
|
};
|
|
1268
1284
|
```
|
|
1269
1285
|
|
|
@@ -1379,12 +1395,13 @@ const OMNI_FAILURE_CODES = [
|
|
|
1379
1395
|
"omni.recording-unsettled",
|
|
1380
1396
|
"omni.on-hold",
|
|
1381
1397
|
"omni.break-forced-by-provider",
|
|
1398
|
+
"omni.break-forced",
|
|
1382
1399
|
] as const;
|
|
1383
1400
|
type OmniFailureCode = (typeof OMNI_FAILURE_CODES)[number];
|
|
1384
1401
|
```
|
|
1385
1402
|
|
|
1386
1403
|
`HISTORY_STEPS_WITH_A_PERSON` is every `HistoryStep` except `arrived`, `self-service` and `queued`, which nobody
|
|
1387
|
-
takes part in, and `callback-requested`, which the caller
|
|
1404
|
+
takes part in, and `callback-requested`, which is the caller's own choice in the queue. `historyStepExpectsAPerson()` tests membership.
|
|
1388
1405
|
|
|
1389
1406
|
### Failure and validation
|
|
1390
1407
|
|
|
@@ -1475,6 +1492,7 @@ const DEFAULT_HISTORY_STEP_LABELS = {
|
|
|
1475
1492
|
transferred: "Transferred",
|
|
1476
1493
|
added: "Added",
|
|
1477
1494
|
unanswered: "Unanswered",
|
|
1495
|
+
"connected-back": "Reconnected",
|
|
1478
1496
|
"callback-requested": "Callback requested",
|
|
1479
1497
|
} as const satisfies Readonly<Record<HistoryStep, string>>;
|
|
1480
1498
|
```
|
|
@@ -1496,7 +1514,6 @@ const DEFAULT_TASK_PHASE_LABELS = {
|
|
|
1496
1514
|
chat: {
|
|
1497
1515
|
pending: "Incoming Chat",
|
|
1498
1516
|
confirmed: "Accepted",
|
|
1499
|
-
preview: "Preview",
|
|
1500
1517
|
"in-progress": "In Chat",
|
|
1501
1518
|
paused: "Paused",
|
|
1502
1519
|
completing: "Wrap-up",
|
|
@@ -1504,14 +1521,16 @@ const DEFAULT_TASK_PHASE_LABELS = {
|
|
|
1504
1521
|
email: {
|
|
1505
1522
|
pending: "Assigned",
|
|
1506
1523
|
confirmed: "Accepted",
|
|
1507
|
-
preview: "Preview",
|
|
1508
1524
|
"in-progress": "Working",
|
|
1509
1525
|
paused: "Paused",
|
|
1510
1526
|
completing: "Completing",
|
|
1511
1527
|
},
|
|
1512
|
-
} as const satisfies
|
|
1513
|
-
|
|
1514
|
-
|
|
1528
|
+
} as const satisfies {
|
|
1529
|
+
// Preview is voice only: a chat or an email has no record put in front of the agent to call.
|
|
1530
|
+
voice: Readonly<Record<TaskPhase, string>>;
|
|
1531
|
+
chat: Readonly<Record<Exclude<TaskPhase, "preview">, string>>;
|
|
1532
|
+
email: Readonly<Record<Exclude<TaskPhase, "preview">, string>>;
|
|
1533
|
+
};
|
|
1515
1534
|
```
|
|
1516
1535
|
|
|
1517
1536
|
### Naming a kind of work
|
|
@@ -1903,7 +1922,8 @@ idleCapabilities: {
|
|
|
1903
1922
|
"https://*.microsoft.com/*"
|
|
1904
1923
|
],
|
|
1905
1924
|
blockList: ["https://help.example.com/private/*"]
|
|
1906
|
-
}
|
|
1925
|
+
},
|
|
1926
|
+
accessAppliesTo: "all-navigation"
|
|
1907
1927
|
}
|
|
1908
1928
|
}
|
|
1909
1929
|
```
|
|
@@ -2071,7 +2091,7 @@ Creates the provider-scoped authentication session.
|
|
|
2071
2091
|
| --- | --- |
|
|
2072
2092
|
| `protocolVersion` | The negotiated version, fixed for this session. |
|
|
2073
2093
|
| `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. |
|
|
2074
|
-
| `timeZone` | The zone
|
|
2094
|
+
| `timeZone` | The zone this session sees every day 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**. |
|
|
2075
2095
|
| `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**. |
|
|
2076
2096
|
| `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`. |
|
|
2077
2097
|
| `secrets` | Omni-provided `SecretStore`, scoped to this provider's manifest id. |
|
|
@@ -2097,7 +2117,7 @@ reports later changes.
|
|
|
2097
2117
|
| `authenticated` | A usable session exists. Includes the provider identity, the user's `capabilities` for the session, and optional token expiry time. |
|
|
2098
2118
|
| `refreshing` | The adapter is refreshing its session. Existing provider identity and capabilities remain available, unchanged: a change to either is published as `authenticated`. |
|
|
2099
2119
|
| `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. |
|
|
2100
|
-
| `terminated` | The session was ended from outside this agent computer: by a
|
|
2120
|
+
| `terminated` | The session was ended from outside this agent computer: by a lead, 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. |
|
|
2101
2121
|
|
|
2102
2122
|
Omni calls `connect()` only after authentication reaches `authenticated`. Token refresh remains
|
|
2103
2123
|
adapter-owned; the adapter publishes `refreshing`, followed by `authenticated` or `expired`.
|
|
@@ -2118,7 +2138,7 @@ replaces the session" describes is a new `AuthenticationSession` under a new `se
|
|
|
2118
2138
|
`signed-out`.
|
|
2119
2139
|
|
|
2120
2140
|
**A sign-in the platform no longer allows is ended, not restored.** A role changed mid-shift can
|
|
2121
|
-
take away what the session was built on -- an agent made a
|
|
2141
|
+
take away what the session was built on -- an agent made a lead may no longer have a phone, and
|
|
2122
2142
|
the platform refuses to renew the softphone. Retrying cannot help and the same session cannot carry
|
|
2123
2143
|
on, so the adapter deletes the secrets and publishes `terminated`, `by: "provider"`, with a failure
|
|
2124
2144
|
in the agent's words: `{ code: "phone-not-allowed", message: "Your sign-in no longer allows a phone.
|
|
@@ -2343,8 +2363,8 @@ Creates one live provider connection for the signed-in agent.
|
|
|
2343
2363
|
| --- | --- |
|
|
2344
2364
|
| `protocolVersion` | Version negotiated before authentication. Fixed for this session. |
|
|
2345
2365
|
| `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` |
|
|
2347
|
-
| `timeZone` | The same value passed as `AuthenticationContext.timeZone`. The provider
|
|
2366
|
+
| `autoAcceptTasks` | The one piece of local policy relayed to the provider, at connect, 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()`. |
|
|
2367
|
+
| `timeZone` | The same value passed as `AuthenticationContext.timeZone`. The provider carries it on the identity and cuts every day-scoped figure this session reads by it. See **The agent's day**. |
|
|
2348
2368
|
| `languages` | The same value passed as `AuthenticationContext.languages`. See **The agent's languages**. |
|
|
2349
2369
|
| `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
2370
|
| `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. |
|
|
@@ -2358,30 +2378,31 @@ Creates one live provider connection for the signed-in agent.
|
|
|
2358
2378
|
Every instant on this wire carries an explicit offset, so a moment is unambiguous everywhere and
|
|
2359
2379
|
an agent computer renders it in the viewer's clock without help. A **day** is different: hours toward
|
|
2360
2380
|
target, an answer streak, a per-queue count for today -- anything bucketed by day -- is bucketed
|
|
2361
|
-
by somebody's day, and a platform that was never told whose uses its own.
|
|
2362
|
-
|
|
2363
|
-
|
|
2364
|
-
|
|
2365
|
-
|
|
2366
|
-
|
|
2367
|
-
|
|
2368
|
-
|
|
2369
|
-
|
|
2370
|
-
|
|
2371
|
-
|
|
2372
|
-
|
|
2373
|
-
|
|
2374
|
-
|
|
2375
|
-
|
|
2376
|
-
|
|
2377
|
-
|
|
2378
|
-
|
|
2379
|
-
|
|
2380
|
-
|
|
2381
|
-
|
|
2382
|
-
|
|
2383
|
-
|
|
2384
|
-
|
|
2381
|
+
by somebody's day, and a platform that was never told whose uses its own.
|
|
2382
|
+
|
|
2383
|
+
**Every day is the viewer's.** Each person sees every figure cut in their own zone: an agent their
|
|
2384
|
+
own day, and a lead a member's day cut by the lead's midnight, not the member's. The instants and
|
|
2385
|
+
the count are the same for both; only the day they fall in follows whoever is looking.
|
|
2386
|
+
|
|
2387
|
+
So the agent application says which zone the session sees days in, and it says so first.
|
|
2388
|
+
`AuthenticationContext.timeZone` is that zone as an IANA name -- `Asia/Kolkata`, `America/Chicago` --
|
|
2389
|
+
never an offset, since an offset cannot survive a daylight-saving boundary and a day boundary is
|
|
2390
|
+
exactly where that bites (`context.timeZone`). It is stated before any identity exists, and
|
|
2391
|
+
`ConnectContext.timeZone` is the same value again. The provider carries it as `identity.timeZone`
|
|
2392
|
+
on every `authenticated` state, and cuts every day-scoped figure this session reads by it: the
|
|
2393
|
+
agent's own `shift`, and every member's `shift` on a lead's team list.
|
|
2394
|
+
|
|
2395
|
+
**The zone is never absent from the signed-in identity.** An identity without one is refused
|
|
2396
|
+
(`authentication.identity.timeZone`), and so is a zone that is not an IANA name, wherever it
|
|
2397
|
+
appears. Nothing is ever assumed in its place -- not the viewer's browser, and not the provider's
|
|
2398
|
+
clock. The harness holds a provider to the round trip: the identity carries the zone the agent
|
|
2399
|
+
application stated (`authentication.identity.timeZone.republished`), judged by what the name
|
|
2400
|
+
denotes: `Asia/Kolkata` and `Asia/Calcutta` are one zone, and a provider that keeps the canonical
|
|
2401
|
+
name has kept the zone.
|
|
2402
|
+
|
|
2403
|
+
**A colleague's zone is information only.** On a `User` from `getUserDetails()`, `timeZone` is the
|
|
2404
|
+
zone that person last signed in from, where the provider knows it, and absent where it does not.
|
|
2405
|
+
No figure is cut by it.
|
|
2385
2406
|
|
|
2386
2407
|
### The agent's languages
|
|
2387
2408
|
|
|
@@ -2425,7 +2446,7 @@ a capability it agrees with the user's capabilities: a lead's snapshot carries `
|
|
|
2425
2446
|
| `nextCall` | The agent's standing ask for the next call, while it stands: `since`. It needs an assignment at work to be next after (`snapshot.nextCall.idle`) and the provider clears it when that assignment ends, when a call is lined up, and when the agent withdraws it. Replaced whole by `next-call`. See **The agent's own queue** in `guide/queue.md`. |
|
|
2426
2447
|
| `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`. |
|
|
2427
2448
|
| `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**. |
|
|
2428
|
-
| `shift` | The agent's own day so far, as the provider counts it -- the same
|
|
2449
|
+
| `shift` | The agent's own day so far, as the provider counts it, cut in this session's zone -- the same instants and count their lead sees on the team member list, cut there by the lead's day. Replaced whole by `shift-updated`. Omitted only where the provider cannot say. See **The agent's day is on the wire** in `guide/lead.md`. |
|
|
2429
2450
|
| `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. |
|
|
2430
2451
|
|
|
2431
2452
|
## Live connection
|
|
@@ -2443,7 +2464,7 @@ surface in one place, and what obliges an adapter to implement each one.
|
|
|
2443
2464
|
| `refused(report)` | Always. The agent application tells the adapter what it would not take -- a snapshot it did not replace its state with, an event it dropped -- with every rule broken, so a refusal is visible on both sides. See **What the agent application does with what it refuses**. |
|
|
2444
2465
|
| `setCapacity(capacity)` | Always. Nothing may be assigned until a capacity is stated, so there is no connection that does not receive it. |
|
|
2445
2466
|
| `execute(request)` | Always. Every channel has commands no capability gates — see **Which commands need a capability** in `guide/agent.md`. |
|
|
2446
|
-
| `getUserDetails(ids)` | The adapter publishes any `UserId`: on `ForcedBreak.by` where a person forced it, a team member list, or `history[].by`.
|
|
2467
|
+
| `getUserDetails(ids)` | The adapter publishes any `UserId`: on `ForcedBreak.by` where a person forced it, a team member list, or `history[].by`. A `User` carries `timeZone` where the provider knows where that person last signed in from, and omits it where it does not. |
|
|
2447
2468
|
| `dial(request)` | The manifest declares `idleCapabilities.dial`, and with it `dialOutcomes`. |
|
|
2448
2469
|
| `requestBreak(request)` | The user's capabilities include `breaks`. |
|
|
2449
2470
|
| `commitBreak()` | The user's capabilities include `breaks`. Commit and cancel are not optional halves of it. |
|
|
@@ -2593,7 +2614,7 @@ and no count. A provider that publishes any of these instants therefore declares
|
|
|
2593
2614
|
(`snapshot.providerTime`). Two screens then differ by their delay and nothing else.
|
|
2594
2615
|
|
|
2595
2616
|
**Seconds left are worked out at each publication.** `expiresInSeconds`, `previewEndsInSeconds`,
|
|
2596
|
-
`wrapEndsInSeconds` and `
|
|
2617
|
+
`wrapEndsInSeconds` and `endsInSeconds` are each the provider's arithmetic at the instant
|
|
2597
2618
|
of the publication that carries them, never a value copied from an earlier one. A provider that
|
|
2598
2619
|
builds the next publication by spreading the last one forward hands a reloaded agent computer a countdown
|
|
2599
2620
|
already spent -- sixty seconds shown beside a lead's screen showing twenty -- and the stream
|
|
@@ -2631,7 +2652,7 @@ Validate requests and responses with `validateProviderTimeCheckRequest` and
|
|
|
2631
2652
|
`validateProviderTimeCheckResult`. The agent application also checks the outstanding request, provider/connection
|
|
2632
2653
|
and session, monotonic elapsed time and cancellation after the await: a late successful response is
|
|
2633
2654
|
still rejected. Reject samples at or beyond `timeoutMs`, or above `maxRoundTripMs`. Cancel local
|
|
2634
|
-
tracking and invalidate estimates on disconnect,
|
|
2655
|
+
tracking and invalidate estimates on disconnect, sign-out, policy disable, clock change or clock
|
|
2635
2656
|
jump; late results cannot restore them. Resume with a fresh check after reconnection. Expire a
|
|
2636
2657
|
sample at `maxSampleAgeMs` using monotonic elapsed time. Failure is visible through the agent application's
|
|
2637
2658
|
existing diagnostic path, with the estimate unavailable; the next scheduled check can recover.
|
|
@@ -2743,7 +2764,7 @@ died; the agent application knows how to run a sign-in. `recovery` joins the two
|
|
|
2743
2764
|
re-establishes state exactly as a reconnect snapshot does. `connect()` is once per
|
|
2744
2765
|
`Connection`, not once per session.
|
|
2745
2766
|
- **`reauthenticate`** — the provider's authorization lapsed and the same session can be restored: a
|
|
2746
|
-
token rejected, published as `expired`. A session ended from outside -- a remote
|
|
2767
|
+
token rejected, published as `expired`. A session ended from outside -- a remote sign-out, a
|
|
2747
2768
|
permission withdrawn -- is `terminated`, which is the whole message and gets no transport `error`
|
|
2748
2769
|
beside it (see **Authentication state**). Omni
|
|
2749
2770
|
runs the authentication flow first, on the same session and `sessionId`, never through
|
|
@@ -2838,7 +2859,7 @@ Normal order is `not-requested` → `awaiting-approval` → `granted` →
|
|
|
2838
2859
|
`starting-after-task` → `on-break` → `not-requested`. Auto-approval may go directly to
|
|
2839
2860
|
`granted`; a commit with no outstanding work may go directly to `on-break`. Denial/cancel
|
|
2840
2861
|
returns a precommit request to `not-requested`; an explicit agent end returns a committed
|
|
2841
|
-
break there
|
|
2862
|
+
break there, once it is not `forced`. Same-state restatements are allowed. An evidenced forced break is the explicit
|
|
2842
2863
|
exception to requesting/granting, and must carry its forced actor/state. Neither skipped
|
|
2843
2864
|
publication nor an agent application-local guess creates another exception. A later normal attempt starts
|
|
2844
2865
|
from `not-requested`, never by regressing an active break into a request.
|
|
@@ -3051,7 +3072,7 @@ member. See **The phone's own view** in `guide/phone.md`.
|
|
|
3051
3072
|
The agent's own day, whole, replacing `Snapshot.shift`: emitted whenever a total moves -- a task
|
|
3052
3073
|
ended, a break ended, a sign-out -- and never to say nothing changed. It carries the same `Shift`
|
|
3053
3074
|
the agent's lead sees for them on the team member list, so the two screens show one day. See
|
|
3054
|
-
**The agent's day is on the wire
|
|
3075
|
+
**The agent's day is on the wire** in `guide/lead.md`.
|
|
3055
3076
|
|
|
3056
3077
|
### `labels-updated`
|
|
3057
3078
|
|
|
@@ -3079,7 +3100,7 @@ wider goes through this key.
|
|
|
3079
3100
|
### `sameCapabilities(a, b)`
|
|
3080
3101
|
|
|
3081
3102
|
Whether two sessions declare the same capabilities, field by field — key order aside, and with
|
|
3082
|
-
`
|
|
3103
|
+
`lead: {}` distinct from `lead` absent. It is the comparison an adapter makes before republishing
|
|
3083
3104
|
`authenticated`, and the one `testAdapter` holds `refreshing` to.
|
|
3084
3105
|
|
|
3085
3106
|
### `historySpans(steps)`
|
|
@@ -3118,7 +3139,7 @@ same exported checks are used by Omni and adapter tests so their interpretations
|
|
|
3118
3139
|
| `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. |
|
|
3119
3140
|
| `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. |
|
|
3120
3141
|
| `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. |
|
|
3121
|
-
| `validateCapacity(capacity)` | What the agent application states as capacity: a whole number of zero or more (`capacity.count`), zero being agent application
|
|
3142
|
+
| `validateCapacity(capacity)` | What the agent application states as capacity: a whole number of zero or more (`capacity.count`), zero being stopped by the agent application. 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`). |
|
|
3122
3143
|
| `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. |
|
|
3123
3144
|
| `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.*`). |
|
|
3124
3145
|
| `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. |
|
|
@@ -3215,7 +3236,7 @@ outcome -- stays in `notTested` for every adapter, and a rule about a live call
|
|
|
3215
3236
|
in each adopter's own tests. `{ withCall: true }` closes that: the test takes the first task the
|
|
3216
3237
|
provider offers through one ordinary lifecycle -- accept it, wait for its audio and open it on a
|
|
3217
3238
|
softphone, hold and resume where the task offers `hold`, end the call where it offers `endCall`,
|
|
3218
|
-
complete it with an outcome where the agent completes -- and holds every step to the rules
|
|
3239
|
+
complete it with an outcome where the agent completes -- and holds every step to the rules an
|
|
3219
3240
|
agent application holds a provider to. Each command is validated against the task as published
|
|
3220
3241
|
(`test.command.*`), each answer for its method, a refusal of a control the task offered is a
|
|
3221
3242
|
violation (`test.command.failed`), and an event the provider owes and never sends is one too
|