@xema/omni-protocol 0.1.132 → 0.1.133
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 +3 -3
- package/README.md +4 -4
- package/dist/index.d.ts +65 -46
- package/dist/index.js +7 -6
- package/dist/validation.js +43 -17
- package/guide/agent.md +25 -19
- package/guide/breaks.md +296 -5
- package/guide/chat.md +1 -1
- package/guide/lead.md +16 -14
- package/guide/phone.md +8 -7
- package/guide/queue.md +2 -292
- package/guide/voice.md +6 -6
- package/guide.md +80 -65
- 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
|
|
@@ -1033,7 +1036,7 @@ type BreakState = {
|
|
|
1033
1036
|
canRequestBreak: boolean;
|
|
1034
1037
|
requestUnavailableReason?: string;
|
|
1035
1038
|
decisionReason?: string;
|
|
1036
|
-
|
|
1039
|
+
retryRequestInSeconds?: DurationSeconds;
|
|
1037
1040
|
reasons?: BreakReason[];
|
|
1038
1041
|
activeReasonId?: string;
|
|
1039
1042
|
forced?: ForcedBreak;
|
|
@@ -1136,6 +1139,13 @@ type ShiftEvent = {
|
|
|
1136
1139
|
kind: ShiftEventKind;
|
|
1137
1140
|
};
|
|
1138
1141
|
|
|
1142
|
+
type ShiftFigure = "talk" | "hold" | "break";
|
|
1143
|
+
|
|
1144
|
+
type ShiftRunning = {
|
|
1145
|
+
figure: ShiftFigure;
|
|
1146
|
+
since: IsoTimestamp;
|
|
1147
|
+
};
|
|
1148
|
+
|
|
1139
1149
|
type Shift = {
|
|
1140
1150
|
signedInAt: IsoTimestamp;
|
|
1141
1151
|
signedOutAt?: IsoTimestamp;
|
|
@@ -1143,6 +1153,7 @@ type Shift = {
|
|
|
1143
1153
|
holdSeconds?: DurationSeconds;
|
|
1144
1154
|
breakSeconds?: DurationSeconds;
|
|
1145
1155
|
tasksHandled?: number;
|
|
1156
|
+
running?: ShiftRunning[];
|
|
1146
1157
|
events?: ShiftEvent[];
|
|
1147
1158
|
};
|
|
1148
1159
|
|
|
@@ -1182,7 +1193,7 @@ type TeamCallCommand =
|
|
|
1182
1193
|
type TeamBreakCommand =
|
|
1183
1194
|
| { type: "decide-break-request"; memberId: UserId; decision: "granted" | "denied"; reason?: string }
|
|
1184
1195
|
| { type: "set-break-policy"; policy: "approval-required" | "automatically-approved" | "requests-suspended" }
|
|
1185
|
-
| { type: "force-break"; memberId: UserId; reasonId?: string; reason?: string;
|
|
1196
|
+
| { type: "force-break"; memberId: UserId; reasonId?: string; reason?: string; expectedDurationSeconds?: DurationSeconds }
|
|
1186
1197
|
| { type: "end-forced-break"; memberId: UserId };
|
|
1187
1198
|
|
|
1188
1199
|
type TeamCommand = TeamFeatureCommand | TeamBreakCommand | TeamCallCommand | TeamPolicyCommand;
|
|
@@ -1230,16 +1241,16 @@ type QueueSummary = {
|
|
|
1230
1241
|
|
|
1231
1242
|
type TransportRecovery = "reconnect" | "reauthenticate" | "displaced";
|
|
1232
1243
|
|
|
1233
|
-
type ProviderEvent =
|
|
1234
|
-
| { type: "snapshot"; reason: "reconnected" | "provider-requested"; snapshot: Snapshot }
|
|
1244
|
+
type ProviderEvent<C extends Channel = Channel> =
|
|
1245
|
+
| { type: "snapshot"; reason: "reconnected" | "provider-requested"; snapshot: Snapshot<C> }
|
|
1235
1246
|
| { type: "transport-status"; status: "connecting" | "active"; message?: string }
|
|
1236
1247
|
| { type: "transport-status"; status: "error"; recovery: TransportRecovery; message: string }
|
|
1237
1248
|
| { type: "break-state"; break: BreakState }
|
|
1238
1249
|
| {
|
|
1239
1250
|
type: "task-offered";
|
|
1240
|
-
task: Task
|
|
1251
|
+
task: Task<C>;
|
|
1241
1252
|
}
|
|
1242
|
-
| { type: "task-updated"; task: Task }
|
|
1253
|
+
| { type: "task-updated"; task: Task<C> }
|
|
1243
1254
|
| { type: "task-audio-started"; assignmentId: AssignmentId }
|
|
1244
1255
|
| { type: "task-audio-ended"; assignmentId: AssignmentId }
|
|
1245
1256
|
| { type: "task-ended"; assignmentId: AssignmentId; outcome: TaskOutcome }
|
|
@@ -1259,11 +1270,11 @@ type ProviderEvent =
|
|
|
1259
1270
|
| { type: "lined-up"; linedUp?: LinedUpCall }
|
|
1260
1271
|
| { type: "labels-updated"; labels: Labels };
|
|
1261
1272
|
|
|
1262
|
-
type ProviderEventEnvelope = {
|
|
1273
|
+
type ProviderEventEnvelope<C extends Channel = Channel> = {
|
|
1263
1274
|
id: string;
|
|
1264
1275
|
sessionId: string;
|
|
1265
1276
|
occurredAt: IsoTimestamp;
|
|
1266
|
-
event: ProviderEvent
|
|
1277
|
+
event: ProviderEvent<C>;
|
|
1267
1278
|
};
|
|
1268
1279
|
```
|
|
1269
1280
|
|
|
@@ -1384,7 +1395,7 @@ type OmniFailureCode = (typeof OMNI_FAILURE_CODES)[number];
|
|
|
1384
1395
|
```
|
|
1385
1396
|
|
|
1386
1397
|
`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
|
|
1398
|
+
takes part in, and `callback-requested`, which is the caller's own choice in the queue. `historyStepExpectsAPerson()` tests membership.
|
|
1388
1399
|
|
|
1389
1400
|
### Failure and validation
|
|
1390
1401
|
|
|
@@ -1475,6 +1486,7 @@ const DEFAULT_HISTORY_STEP_LABELS = {
|
|
|
1475
1486
|
transferred: "Transferred",
|
|
1476
1487
|
added: "Added",
|
|
1477
1488
|
unanswered: "Unanswered",
|
|
1489
|
+
"connected-back": "Reconnected",
|
|
1478
1490
|
"callback-requested": "Callback requested",
|
|
1479
1491
|
} as const satisfies Readonly<Record<HistoryStep, string>>;
|
|
1480
1492
|
```
|
|
@@ -1496,7 +1508,6 @@ const DEFAULT_TASK_PHASE_LABELS = {
|
|
|
1496
1508
|
chat: {
|
|
1497
1509
|
pending: "Incoming Chat",
|
|
1498
1510
|
confirmed: "Accepted",
|
|
1499
|
-
preview: "Preview",
|
|
1500
1511
|
"in-progress": "In Chat",
|
|
1501
1512
|
paused: "Paused",
|
|
1502
1513
|
completing: "Wrap-up",
|
|
@@ -1504,14 +1515,16 @@ const DEFAULT_TASK_PHASE_LABELS = {
|
|
|
1504
1515
|
email: {
|
|
1505
1516
|
pending: "Assigned",
|
|
1506
1517
|
confirmed: "Accepted",
|
|
1507
|
-
preview: "Preview",
|
|
1508
1518
|
"in-progress": "Working",
|
|
1509
1519
|
paused: "Paused",
|
|
1510
1520
|
completing: "Completing",
|
|
1511
1521
|
},
|
|
1512
|
-
} as const satisfies
|
|
1513
|
-
|
|
1514
|
-
|
|
1522
|
+
} as const satisfies {
|
|
1523
|
+
// Preview is voice only: a chat or an email has no record put in front of the agent to call.
|
|
1524
|
+
voice: Readonly<Record<TaskPhase, string>>;
|
|
1525
|
+
chat: Readonly<Record<Exclude<TaskPhase, "preview">, string>>;
|
|
1526
|
+
email: Readonly<Record<Exclude<TaskPhase, "preview">, string>>;
|
|
1527
|
+
};
|
|
1515
1528
|
```
|
|
1516
1529
|
|
|
1517
1530
|
### Naming a kind of work
|
|
@@ -1903,7 +1916,8 @@ idleCapabilities: {
|
|
|
1903
1916
|
"https://*.microsoft.com/*"
|
|
1904
1917
|
],
|
|
1905
1918
|
blockList: ["https://help.example.com/private/*"]
|
|
1906
|
-
}
|
|
1919
|
+
},
|
|
1920
|
+
accessAppliesTo: "all-navigation"
|
|
1907
1921
|
}
|
|
1908
1922
|
}
|
|
1909
1923
|
```
|
|
@@ -2071,7 +2085,7 @@ Creates the provider-scoped authentication session.
|
|
|
2071
2085
|
| --- | --- |
|
|
2072
2086
|
| `protocolVersion` | The negotiated version, fixed for this session. |
|
|
2073
2087
|
| `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
|
|
2088
|
+
| `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
2089
|
| `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
2090
|
| `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
2091
|
| `secrets` | Omni-provided `SecretStore`, scoped to this provider's manifest id. |
|
|
@@ -2097,7 +2111,7 @@ reports later changes.
|
|
|
2097
2111
|
| `authenticated` | A usable session exists. Includes the provider identity, the user's `capabilities` for the session, and optional token expiry time. |
|
|
2098
2112
|
| `refreshing` | The adapter is refreshing its session. Existing provider identity and capabilities remain available, unchanged: a change to either is published as `authenticated`. |
|
|
2099
2113
|
| `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
|
|
2114
|
+
| `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
2115
|
|
|
2102
2116
|
Omni calls `connect()` only after authentication reaches `authenticated`. Token refresh remains
|
|
2103
2117
|
adapter-owned; the adapter publishes `refreshing`, followed by `authenticated` or `expired`.
|
|
@@ -2118,7 +2132,7 @@ replaces the session" describes is a new `AuthenticationSession` under a new `se
|
|
|
2118
2132
|
`signed-out`.
|
|
2119
2133
|
|
|
2120
2134
|
**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
|
|
2135
|
+
take away what the session was built on -- an agent made a lead may no longer have a phone, and
|
|
2122
2136
|
the platform refuses to renew the softphone. Retrying cannot help and the same session cannot carry
|
|
2123
2137
|
on, so the adapter deletes the secrets and publishes `terminated`, `by: "provider"`, with a failure
|
|
2124
2138
|
in the agent's words: `{ code: "phone-not-allowed", message: "Your sign-in no longer allows a phone.
|
|
@@ -2343,8 +2357,8 @@ Creates one live provider connection for the signed-in agent.
|
|
|
2343
2357
|
| --- | --- |
|
|
2344
2358
|
| `protocolVersion` | Version negotiated before authentication. Fixed for this session. |
|
|
2345
2359
|
| `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
|
|
2360
|
+
| `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()`. |
|
|
2361
|
+
| `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
2362
|
| `languages` | The same value passed as `AuthenticationContext.languages`. See **The agent's languages**. |
|
|
2349
2363
|
| `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
2364
|
| `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 +2372,31 @@ Creates one live provider connection for the signed-in agent.
|
|
|
2358
2372
|
Every instant on this wire carries an explicit offset, so a moment is unambiguous everywhere and
|
|
2359
2373
|
an agent computer renders it in the viewer's clock without help. A **day** is different: hours toward
|
|
2360
2374
|
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
|
-
|
|
2375
|
+
by somebody's day, and a platform that was never told whose uses its own.
|
|
2376
|
+
|
|
2377
|
+
**Every day is the viewer's.** Each person sees every figure cut in their own zone: an agent their
|
|
2378
|
+
own day, and a lead a member's day cut by the lead's midnight, not the member's. The instants and
|
|
2379
|
+
the count are the same for both; only the day they fall in follows whoever is looking.
|
|
2380
|
+
|
|
2381
|
+
So the agent application says which zone the session sees days in, and it says so first.
|
|
2382
|
+
`AuthenticationContext.timeZone` is that zone as an IANA name -- `Asia/Kolkata`, `America/Chicago` --
|
|
2383
|
+
never an offset, since an offset cannot survive a daylight-saving boundary and a day boundary is
|
|
2384
|
+
exactly where that bites (`context.timeZone`). It is stated before any identity exists, and
|
|
2385
|
+
`ConnectContext.timeZone` is the same value again. The provider carries it as `identity.timeZone`
|
|
2386
|
+
on every `authenticated` state, and cuts every day-scoped figure this session reads by it: the
|
|
2387
|
+
agent's own `shift`, and every member's `shift` on a lead's team list.
|
|
2388
|
+
|
|
2389
|
+
**The zone is never absent from the signed-in identity.** An identity without one is refused
|
|
2390
|
+
(`authentication.identity.timeZone`), and so is a zone that is not an IANA name, wherever it
|
|
2391
|
+
appears. Nothing is ever assumed in its place -- not the viewer's browser, and not the provider's
|
|
2392
|
+
clock. The harness holds a provider to the round trip: the identity carries the zone the agent
|
|
2393
|
+
application stated (`authentication.identity.timeZone.republished`), judged by what the name
|
|
2394
|
+
denotes: `Asia/Kolkata` and `Asia/Calcutta` are one zone, and a provider that keeps the canonical
|
|
2395
|
+
name has kept the zone.
|
|
2396
|
+
|
|
2397
|
+
**A colleague's zone is information only.** On a `User` from `getUserDetails()`, `timeZone` is the
|
|
2398
|
+
zone that person last signed in from, where the provider knows it, and absent where it does not.
|
|
2399
|
+
No figure is cut by it.
|
|
2385
2400
|
|
|
2386
2401
|
### The agent's languages
|
|
2387
2402
|
|
|
@@ -2425,7 +2440,7 @@ a capability it agrees with the user's capabilities: a lead's snapshot carries `
|
|
|
2425
2440
|
| `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
2441
|
| `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
2442
|
| `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
|
|
2443
|
+
| `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
2444
|
| `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
2445
|
|
|
2431
2446
|
## Live connection
|
|
@@ -2443,7 +2458,7 @@ surface in one place, and what obliges an adapter to implement each one.
|
|
|
2443
2458
|
| `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
2459
|
| `setCapacity(capacity)` | Always. Nothing may be assigned until a capacity is stated, so there is no connection that does not receive it. |
|
|
2445
2460
|
| `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`.
|
|
2461
|
+
| `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
2462
|
| `dial(request)` | The manifest declares `idleCapabilities.dial`, and with it `dialOutcomes`. |
|
|
2448
2463
|
| `requestBreak(request)` | The user's capabilities include `breaks`. |
|
|
2449
2464
|
| `commitBreak()` | The user's capabilities include `breaks`. Commit and cancel are not optional halves of it. |
|
|
@@ -2631,7 +2646,7 @@ Validate requests and responses with `validateProviderTimeCheckRequest` and
|
|
|
2631
2646
|
`validateProviderTimeCheckResult`. The agent application also checks the outstanding request, provider/connection
|
|
2632
2647
|
and session, monotonic elapsed time and cancellation after the await: a late successful response is
|
|
2633
2648
|
still rejected. Reject samples at or beyond `timeoutMs`, or above `maxRoundTripMs`. Cancel local
|
|
2634
|
-
tracking and invalidate estimates on disconnect,
|
|
2649
|
+
tracking and invalidate estimates on disconnect, sign-out, policy disable, clock change or clock
|
|
2635
2650
|
jump; late results cannot restore them. Resume with a fresh check after reconnection. Expire a
|
|
2636
2651
|
sample at `maxSampleAgeMs` using monotonic elapsed time. Failure is visible through the agent application's
|
|
2637
2652
|
existing diagnostic path, with the estimate unavailable; the next scheduled check can recover.
|
|
@@ -2743,7 +2758,7 @@ died; the agent application knows how to run a sign-in. `recovery` joins the two
|
|
|
2743
2758
|
re-establishes state exactly as a reconnect snapshot does. `connect()` is once per
|
|
2744
2759
|
`Connection`, not once per session.
|
|
2745
2760
|
- **`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
|
|
2761
|
+
token rejected, published as `expired`. A session ended from outside -- a remote sign-out, a
|
|
2747
2762
|
permission withdrawn -- is `terminated`, which is the whole message and gets no transport `error`
|
|
2748
2763
|
beside it (see **Authentication state**). Omni
|
|
2749
2764
|
runs the authentication flow first, on the same session and `sessionId`, never through
|
|
@@ -3051,7 +3066,7 @@ member. See **The phone's own view** in `guide/phone.md`.
|
|
|
3051
3066
|
The agent's own day, whole, replacing `Snapshot.shift`: emitted whenever a total moves -- a task
|
|
3052
3067
|
ended, a break ended, a sign-out -- and never to say nothing changed. It carries the same `Shift`
|
|
3053
3068
|
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
|
|
3069
|
+
**The agent's day is on the wire** in `guide/lead.md`.
|
|
3055
3070
|
|
|
3056
3071
|
### `labels-updated`
|
|
3057
3072
|
|
|
@@ -3079,7 +3094,7 @@ wider goes through this key.
|
|
|
3079
3094
|
### `sameCapabilities(a, b)`
|
|
3080
3095
|
|
|
3081
3096
|
Whether two sessions declare the same capabilities, field by field — key order aside, and with
|
|
3082
|
-
`
|
|
3097
|
+
`lead: {}` distinct from `lead` absent. It is the comparison an adapter makes before republishing
|
|
3083
3098
|
`authenticated`, and the one `testAdapter` holds `refreshing` to.
|
|
3084
3099
|
|
|
3085
3100
|
### `historySpans(steps)`
|
|
@@ -3118,7 +3133,7 @@ same exported checks are used by Omni and adapter tests so their interpretations
|
|
|
3118
3133
|
| `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
3134
|
| `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
3135
|
| `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
|
|
3136
|
+
| `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
3137
|
| `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
3138
|
| `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
3139
|
| `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 +3230,7 @@ outcome -- stays in `notTested` for every adapter, and a rule about a live call
|
|
|
3215
3230
|
in each adopter's own tests. `{ withCall: true }` closes that: the test takes the first task the
|
|
3216
3231
|
provider offers through one ordinary lifecycle -- accept it, wait for its audio and open it on a
|
|
3217
3232
|
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
|
|
3233
|
+
complete it with an outcome where the agent completes -- and holds every step to the rules an
|
|
3219
3234
|
agent application holds a provider to. Each command is validated against the task as published
|
|
3220
3235
|
(`test.command.*`), each answer for its method, a refusal of a control the task offered is a
|
|
3221
3236
|
violation (`test.command.failed`), and an event the provider owes and never sends is one too
|