@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/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 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. |
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: 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: User; capabilities: UserCapabilities; expiresAt?: IsoTimestamp }
327
- | { status: "refreshing"; identity: User; capabilities: UserCapabilities }
328
- | { status: "expired"; identity?: User; failure?: AuthenticationFailure }
329
- | { status: "terminated"; by: UserId | "provider"; identity?: User; failure: AuthenticationFailure & { retryable: false } };
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: User; capabilities: UserCapabilities; expiresAt?: IsoTimestamp }
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-stopped
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 agent computer has two managers, not one. **The queue** — a process, a work type — is owned by a
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
- retryRequestAfterMs?: number;
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; expectedDurationMs?: number }
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 may choose alone. `historyStepExpectsAPerson()` tests membership.
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 Readonly<
1513
- Record<"voice" | "chat" | "email", Readonly<Record<TaskPhase, string>>>
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 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**. |
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 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. |
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 supervisor may no longer have a phone, and
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` | 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()`. |
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**. |
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. An agent in Chennai
2362
- then finds their day rolling at 05:30, and a night shift in Chicago lands in two buckets.
2363
-
2364
- So the agent application says whose day it is, and it says so first. `AuthenticationContext.timeZone` is the
2365
- agent's zone as an IANA name -- `Asia/Kolkata`, `America/Chicago` -- never an offset, since an
2366
- offset cannot survive a daylight-saving boundary and a day boundary is exactly where that bites
2367
- (`context.timeZone`). It is stated before any identity exists, and `ConnectContext.timeZone` is the
2368
- same value again. The provider **stores it on the agent** and carries it as `identity.timeZone` on
2369
- every `authenticated` state and on every `User` it returns from `getUserDetails()`, so a lead
2370
- reading a colleague's yesterday sees the colleague's yesterday and a summary is bucketed by the
2371
- right day after a session has ended. A roaming agent corrects it by signing in from where they are.
2372
-
2373
- **The zone is never absent.** Time zone awareness is a first-party property of this wire, not a
2374
- field to fill in later: an identity without one is refused (`authentication.identity.timeZone`), and
2375
- so is a zone that is not an IANA name, wherever it appears. Nothing is ever assumed in its place --
2376
- not the viewer's browser, which gives a different answer per reader for the same record, and not the
2377
- provider's clock. The harness holds a provider to the round trip: the identity carries the zone the
2378
- agent application stated (`authentication.identity.timeZone.republished`), judged by what the name denotes:
2379
- `Asia/Kolkata` and `Asia/Calcutta` are one zone, and a provider that keeps the canonical name has
2380
- kept the zone. **The round trip is not the store.**
2381
- An adapter that echoes the stated zone back onto the identity passes that check with nothing kept,
2382
- and a lead reading a colleague's day would still get the wrong one. What proves the store is a zone
2383
- the run never sent: a colleague's `User` from `getUserDetails()` carrying theirs. A provider's own
2384
- tests are where that is shown, with a second agent whose zone arrived through another session.
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 `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**. |
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`. Each `User` carries its `timeZone`; a person whose zone the provider cannot name is omitted from the answer, as any unresolvable id is. |
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, logout, policy disable, clock change or clock
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 logout, a
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
- `team: {}` distinct from `team` absent. It is the comparison an adapter makes before republishing
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-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`). |
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 a
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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xema/omni-protocol",
3
- "version": "0.1.132",
3
+ "version": "0.1.133",
4
4
  "description": "The Omni protocol: the contract every provider adapter implements",
5
5
  "type": "module",
6
6
  "license": "MIT",