@xema/omni-protocol 0.1.134 → 0.1.135

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/GLOSSARY.md CHANGED
@@ -45,6 +45,7 @@ for orientation only: each platform's own documentation is the authority on its
45
45
  | **Paused** | The work is on hold: the caller hears hold music, or the chat waits. | *Hold* on a call; *paused* or *parked* on a chat. |
46
46
  | **Completing** | The customer has gone and the agent is finishing their notes. | *After-call work* or *ACW* (Amazon Connect, Genesys Cloud, NICE), *wrap-up* (Twilio, Five9), *after conversation work* (Salesforce). |
47
47
  | **Wrap allowance** | How long the agent has for that finishing work. | *ACW timeout*, *wrap-up time limit*. |
48
+ | **Wrap overrun** | How far past the wrap allowance the agent is, when the provider waits for them to finish: `wrapOverSeconds` on the wire. | *ACW overrun*, *wrap-up overtime*. |
48
49
  | **Outcome** | What the agent records about how the task went. | *Wrap-up code* (Genesys Cloud), *disposition* (Five9, NICE, Twilio), *contact disposition*. |
49
50
  | **Task ended** | The task is gone from the agent's screen. | *Contact ended*, *disconnected*, *completed*. |
50
51
 
package/dist/index.d.ts CHANGED
@@ -219,7 +219,8 @@ export interface Manifest<C extends Channel = Channel> {
219
219
  /**
220
220
  * Implements `checkTime`, and states `providerTime` on every snapshot. Required of a provider
221
221
  * that publishes an instant the agent computer renders as a running duration -- a member's `since`, a
222
- * lead's `listening.since`, an `onCall.since`, a shift's `signedInAt` -- so every screen counts
222
+ * lead's `listening.since`, an `onCall.since`, a shift's `signedInAt`, the `answered` step of a
223
+ * call under way, or a hold or mute still running -- so every screen counts
223
224
  * from the provider's clock and two screens differ by their delay alone.
224
225
  */
225
226
  timeCheck?: true;
@@ -1159,6 +1160,12 @@ export type Task<C extends Channel = Channel> = {
1159
1160
  * once overrun, and nothing acts on it.
1160
1161
  */
1161
1162
  wrapEndsInSeconds?: DurationSeconds;
1163
+ /**
1164
+ * Under `agent-command`, once `wrapEndsInSeconds` is `0`: how far past the expected wrap the task
1165
+ * is, in whole seconds at this publication, restated on every publication that carries it, so a
1166
+ * reloaded agent computer and a lead's screen count on from the same number.
1167
+ */
1168
+ wrapOverSeconds?: DurationSeconds;
1162
1169
  /** The identifier an agent reads back to a customer, where the provider has one. */
1163
1170
  reference?: string;
1164
1171
  attributes?: TaskAttribute[];
@@ -1566,6 +1573,8 @@ export type MemberTask<C extends Channel = Channel> = {
1566
1573
  completionMode?: CompletionMode;
1567
1574
  wrapAllowance?: DurationSeconds;
1568
1575
  wrapEndsInSeconds?: DurationSeconds;
1576
+ /** How far past the expected wrap, as on the member's own task. */
1577
+ wrapOverSeconds?: DurationSeconds;
1569
1578
  } & (C extends "voice" ? {
1570
1579
  onCall?: OnCall[];
1571
1580
  leadAssist?: TaskLeadAssist;
@@ -1858,7 +1867,7 @@ export interface Snapshot<C extends Channel = Channel> {
1858
1867
  sessionId: string;
1859
1868
  /**
1860
1869
  * The provider's own instant of this read, required of a provider that declares `timeCheck`:
1861
- * every duration the agent computer renders off the active call is counted from the provider's clock, and
1870
+ * every running duration the agent computer renders, the call under way included, is counted from the provider's clock, and
1862
1871
  * this sample saves a `checkTime` for it. Every envelope's `occurredAt` is a sample too.
1863
1872
  */
1864
1873
  providerTime?: IsoTimestamp;
@@ -2202,13 +2211,12 @@ export declare const historyStepDials: (step: HistoryStep) => boolean;
2202
2211
  /**
2203
2212
  * Consecutive entries of one step, shown as one span. The record keeps an entry per occurrence --
2204
2213
  * two holds are counted as two -- and this is how the agent sees them: once, from the first
2205
- * entry's `at`, lasting the sum of their `seconds` when every entry states one, and with no
2206
- * duration when any does not, never a sum that silently leaves a running leg out.
2214
+ * entry's `at`, with each entry's own `seconds`. A span states no total: summing durations the
2215
+ * provider rounded one by one could show a number its own record never would.
2207
2216
  */
2208
2217
  export interface HistorySpan {
2209
2218
  step: HistoryStep;
2210
2219
  at: IsoTimestamp;
2211
- seconds?: DurationSeconds;
2212
2220
  entries: TaskHistoryStep[];
2213
2221
  }
2214
2222
  /** Groups a record's consecutive same-step entries into spans, oldest first. */
package/dist/index.js CHANGED
@@ -224,11 +224,6 @@ export function historySpans(steps) {
224
224
  else
225
225
  spans.push({ step: entry.step, at: entry.at, entries: [entry] });
226
226
  }
227
- for (const span of spans) {
228
- if (span.entries.every(entry => entry.seconds !== undefined)) {
229
- span.seconds = span.entries.reduce((total, entry) => total + entry.seconds, 0);
230
- }
231
- }
232
227
  return spans;
233
228
  }
234
229
  /** Whether an absent `by` means "could not attribute" rather than "nobody was involved". */
package/dist/testing.js CHANGED
@@ -1352,12 +1352,28 @@ export class TaskStream {
1352
1352
  if (before !== undefined) {
1353
1353
  ruleTested("stream.countdown.copied");
1354
1354
  const elapsed = Math.floor((atMs - before.atMs) / 1000);
1355
- if (elapsed > 0 && value > before.value - elapsed + 1) {
1355
+ // A countdown stops at nought: an agent-command wrap that runs over restates `0`, the true value.
1356
+ if (elapsed > 0 && value > Math.max(0, before.value - elapsed) + 1) {
1356
1357
  refuse("stream.countdown.copied", `${at}.${field}`, `${id} said ${field} ${before.value} at ${new Date(before.atMs).toISOString()} and ${value} at ${new Date(atMs).toISOString()}: ${elapsed}s passed on the provider's clock and the countdown lost fewer; seconds left are worked out at each publication, never copied from the one before`);
1357
1358
  }
1358
1359
  }
1359
1360
  known.set(field, { value, atMs });
1360
1361
  }
1362
+ // How far over the expected wrap counts the other way: it gains at least the seconds that passed.
1363
+ const over = task.wrapOverSeconds;
1364
+ if (typeof over !== "number")
1365
+ known.delete("wrapOverSeconds");
1366
+ else {
1367
+ const before = known.get("wrapOverSeconds");
1368
+ if (before !== undefined) {
1369
+ ruleTested("stream.overrun.copied");
1370
+ const elapsed = Math.floor((atMs - before.atMs) / 1000);
1371
+ if (elapsed > 0 && over < before.value + elapsed - 1) {
1372
+ refuse("stream.overrun.copied", `${at}.wrapOverSeconds`, `${id} said wrapOverSeconds ${before.value} at ${new Date(before.atMs).toISOString()} and ${over} at ${new Date(atMs).toISOString()}: ${elapsed}s passed on the provider's clock and the overrun gained fewer; it is worked out at each publication, never copied from the one before`);
1373
+ }
1374
+ }
1375
+ known.set("wrapOverSeconds", { value: over, atMs });
1376
+ }
1361
1377
  this.countdowns.set(id, known);
1362
1378
  }
1363
1379
  // Every dial the stream can place an outcome against: one the host said it placed, or one a
@@ -1291,6 +1291,23 @@ function validateTaskInto(task, context, path, into) {
1291
1291
  else if (task.wrapEndsInSeconds !== undefined) {
1292
1292
  into.add("task.completing.wrapEndsInSeconds.unexpected", `${path}.wrapEndsInSeconds`, task.phase === "completing" ? "no wrap allowance was stated, so there is nothing to count down" : "wrapEndsInSeconds belongs to a completing task; before the wrap there is nothing to count");
1293
1293
  }
1294
+ // Past the expected wrap, how far over travels too: a screen that reloads mid-overrun reads 0 left
1295
+ // and could not otherwise say by how much.
1296
+ const overrun = task.phase === "completing" && task.completionMode !== "provider-automatic" && task.wrapEndsInSeconds === 0;
1297
+ if (overrun) {
1298
+ if (task.wrapOverSeconds === undefined) {
1299
+ // A lead's copy may leave the mode out; the member's own task states it, and is held to it.
1300
+ if (task.completionMode === "agent-command") {
1301
+ into.add("task.completing.wrapOverSeconds.required", `${path}.wrapOverSeconds`, "the expected wrap has run out, so the task says how far over it is: a reloaded agent computer and a lead's screen count on from the same number");
1302
+ }
1303
+ }
1304
+ else {
1305
+ into.require(isDurationSeconds(task.wrapOverSeconds), "task.completing.wrapOverSeconds", `${path}.wrapOverSeconds`, "wrapOverSeconds is how far past the expected wrap the task is: a whole number of seconds, zero or more, counted at this publication");
1306
+ }
1307
+ }
1308
+ else if (task.wrapOverSeconds !== undefined) {
1309
+ into.add("task.completing.wrapOverSeconds.unexpected", `${path}.wrapOverSeconds`, "wrapOverSeconds belongs to a completing agent-command task whose wrapEndsInSeconds is 0; before the wrap runs out there is nothing over");
1310
+ }
1294
1311
  // The channel is fixed per provider by its manifest, so a task claiming another one is a
1295
1312
  // task Omni would render with the wrong controls.
1296
1313
  into.require(task.channel === context.channel, "task.channel", `${path}.channel`, `a ${context.channel} provider may not publish a ${describeValue(task.channel)} task`);
@@ -1312,6 +1329,12 @@ function validateTaskInto(task, context, path, into) {
1312
1329
  validateBrowsers(task.browsers, `${path}.browsers`, into);
1313
1330
  validateTaskAttributes(task.attributes, `${path}.attributes`, into, context.levels);
1314
1331
  validateHistory(task.history, `${path}.history`, into, { phase: task.phase, audio: task.audio });
1332
+ // The call timer starts from the provider's answer, never from when a screen saw the call: a call
1333
+ // under way says when it was answered, so every screen shows the same time on it.
1334
+ if (context.channel === "voice" && (task.phase === "in-progress" || task.phase === "paused")) {
1335
+ into.require(isPlainObject(task.history) && Array.isArray(task.history.steps)
1336
+ && task.history.steps.some((entry) => isPlainObject(entry) && entry.step === "answered"), "task.history.answered.required", `${path}.history`, "a call under way carries its answered step: the call timer counts from the provider's answer on the provider's clock, and no screen times the call itself");
1337
+ }
1315
1338
  validateOnCall(task.onCall, context.channel, `${path}.onCall`, into);
1316
1339
  // Audio and onCall describe this agent's interaction, not the continuing caller journey.
1317
1340
  // Once the interaction's audio ends or it enters wrap, its live room is cleared. Other
@@ -2329,7 +2352,7 @@ function carriesRunningInstant(value) {
2329
2352
  ...(Array.isArray(value.tasks) ? value.tasks : []),
2330
2353
  ...(isPlainObject(value.task) ? [value.task] : []),
2331
2354
  ];
2332
- if (tasks.some(task => isPlainObject(task) && Array.isArray(task.onCall) && task.onCall.some((who) => isPlainObject(who) && who.since !== undefined)))
2355
+ if (tasks.some(taskCarriesRunningInstant))
2333
2356
  return true;
2334
2357
  const members = [
2335
2358
  ...(isPlainObject(value.team) && Array.isArray(value.team.members) ? value.team.members : []),
@@ -2338,13 +2361,26 @@ function carriesRunningInstant(value) {
2338
2361
  return members.some(member => isPlainObject(member) && (member.since !== undefined
2339
2362
  || (Array.isArray(member.listening) && member.listening.some((entry) => isPlainObject(entry) && entry.since !== undefined))
2340
2363
  || (isPlainObject(member.shift) && member.shift.signedInAt !== undefined)
2341
- || (Array.isArray(member.tasks) && member.tasks.some((task) => isPlainObject(task) && Array.isArray(task.onCall) && task.onCall.some((who) => isPlainObject(who) && who.since !== undefined)))));
2364
+ || (Array.isArray(member.tasks) && member.tasks.some(taskCarriesRunningInstant))));
2365
+ }
2366
+ /**
2367
+ * A task a screen times from a provider instant: someone's `since` on the call, its answer while the
2368
+ * call is under way, or a hold or mute still running. An answer in the record of a task in wrap, or
2369
+ * one offered on, is an instant shown, not a timer.
2370
+ */
2371
+ function taskCarriesRunningInstant(task) {
2372
+ if (!isPlainObject(task))
2373
+ return false;
2374
+ if (Array.isArray(task.onCall) && task.onCall.some((who) => isPlainObject(who) && who.since !== undefined))
2375
+ return true;
2376
+ const underWay = task.phase === "in-progress" || task.phase === "paused";
2377
+ return isPlainObject(task.history) && Array.isArray(task.history.steps) && task.history.steps.some((entry) => isPlainObject(entry) && ((underWay && entry.step === "answered") || ((entry.step === "held" || entry.step === "muted") && entry.seconds === undefined)));
2342
2378
  }
2343
2379
  /** A running duration is counted from the provider's clock: a provider that publishes one declares timeCheck. */
2344
2380
  function requireClockInto(value, manifest, path, into) {
2345
2381
  if (!isPlainObject(manifest) || manifest.timeCheck === true || !carriesRunningInstant(value))
2346
2382
  return;
2347
- into.add("manifest.timeCheck.required", path, "this publishes an instant the agent computer renders as a running duration -- a since, a signedInAt -- and the manifest declares no timeCheck: every screen counts such a duration from the provider's clock, so the provider states one");
2383
+ into.add("manifest.timeCheck.required", path, "this publishes an instant the agent computer renders as a running duration -- a since, a signedInAt, a call's answer -- and the manifest declares no timeCheck: every screen counts such a duration from the provider's clock, so the provider states one");
2348
2384
  }
2349
2385
  /** The agent's standing ask for the next call: since when. */
2350
2386
  export function validateNextCall(value, path = "nextCall") {
package/guide/agent.md CHANGED
@@ -263,8 +263,8 @@ so a `provider-automatic` task with `wrapAllowance: 0` publishes no `outcomes` a
263
263
 
264
264
  **The allowance means one thing per mode.** Under `provider-automatic` it is what the provider
265
265
  acts on: the task ends when it runs out. Under `agent-command` it is the expected wrap, stated so
266
- the agent can see it: the agent computer counts it down and, past zero, shows how far over they are, and
267
- nothing acts on it -- the task waits for `complete` however long that takes, with its outcomes
266
+ the agent can see it: the agent computer counts it down and, past zero, shows how far over they are,
267
+ counting on from the task's `wrapOverSeconds`, and nothing acts on it -- the task waits for `complete` however long that takes, with its outcomes
268
268
  collected whenever the agent gives them. A provider that would end the task at a time is
269
269
  `provider-automatic`.
270
270
 
@@ -274,7 +274,9 @@ carries it, as `previewEndsInSeconds` is on a preview. An agent computer that re
274
274
  number on the snapshot; a lead's screen finds it on the member; neither starts a clock of its own,
275
275
  and both count down from receipt. Under `provider-automatic` the provider ends the task when it
276
276
  reaches zero; under `agent-command` it is the expected wrap left, `0` once overrun, and nothing
277
- acts on it. Off voice, where `completing` is the provider's word that interaction ended, the field
277
+ acts on it. Once it is `0` under `agent-command`, the task also carries `wrapOverSeconds`: how far
278
+ past the expected wrap it is, restated on every publication the same way, so a reloaded screen
279
+ does not start the overrun from nought (`task.completing.wrapOverSeconds.required`, `.unexpected`). Off voice, where `completing` is the provider's word that interaction ended, the field
278
280
  arrives with that word, so the clock starts nowhere else.
279
281
 
280
282
  `wrapAllowance` is fixed, and when it starts depends on whether the channel carries real-time
@@ -309,7 +311,7 @@ outcome, and complete the task.
309
311
 
310
312
  `0` means no wrap under `provider-automatic`: the provider completes the task at the end of the
311
313
  interaction, and `complete` has nothing to cut short. Under `agent-command` it is an expected wrap
312
- of nothing -- the agent computer shows the overrun from the start -- and the task still waits for `complete`.
314
+ of nothing -- the agent computer shows the overrun from the start, from `wrapOverSeconds` -- and the task still waits for `complete`.
313
315
 
314
316
  There is no value meaning "unlimited", because a number that is not a duration would be read as
315
317
  one. A provider that imposes no deadline says so by **omitting** `wrapAllowance`, which
@@ -501,11 +503,12 @@ entries, one per join. Order is enforced: an entry earlier than the one before i
501
503
  are two holds, the way Amazon Connect counts holds per contact, and two queues say which queue the
502
504
  call waited in. The agent sees consecutive entries of one step as one span: `historySpans(steps)`
503
505
  groups them, as Genesys Cloud keeps segments apart in its record and joins them in the agent's
504
- timeline. A provider never merges entries to get that look. **Intervals between steps are the agent application's to subtract**, never a
505
- total the provider adds: *time to offer*, from the call joining its queue to the agent's screen lighting
506
- up, is the `offered` entry's `at` minus the last `queued` entry's, and the ring is outside it.
507
- `queueSeconds` keeps the industry's meaning -- the whole wait until somebody answered -- and is not
508
- that interval. **The second is the record's grain.** A duration is a positive whole number of
506
+ timeline. A provider never merges entries to get that look. **A screen shows the instants and the
507
+ provider's own figures, and works out no interval between steps**: a wait such as *time to offer*,
508
+ from the call joining its queue to the agent's screen lighting up, is a figure the provider's
509
+ reports may count from a different step, so a screen that subtracted one `at` from another could
510
+ show a number the provider never would. A desk that wants such a wait shown needs the provider to
511
+ state it. `queueSeconds` keeps the industry's meaning -- the whole wait until somebody answered. **The second is the record's grain.** A duration is a positive whole number of
509
512
  seconds, and nought is refused because it claims no time; a leg that happened is stated at the
510
513
  grain: rounded to the nearest second, and a leg that rounds to nought is stated as `1`, the error
511
514
  being under the contract's resolution, where dropping the entry would say the leg never happened.
@@ -541,10 +544,14 @@ If two distinct entries would collide under the history's `(step, at)` key, do n
541
544
  or combine them: report the representation conflict. No ambiguous event is silently accepted.
542
545
 
543
546
  **Interaction time is anchored, not restarted.** It runs from the
544
- `answered` step's `at` — from the task's first `in-progress` where the provider reports no
545
- history — until the task's audio ends, and a hold neither pauses nor resets it: the hold's own
547
+ `answered` step's `at` until the task's audio ends, and a hold neither pauses nor resets it: the hold's own
546
548
  duration is the `held` entry's `seconds`, and an agent computer that restarts its counter on resume is
547
- counting the wrong thing.
549
+ counting the wrong thing. There is no fallback to the moment a screen first saw the task in
550
+ progress: that moment is the screen's, and a screen that reloads twenty minutes in would show a
551
+ call five seconds old. So a voice call under way -- `in-progress` or `paused` -- carries its
552
+ `answered` step (`task.history.answered.required`), and the provider that publishes it declares
553
+ `timeCheck`, as any provider publishing a running instant does. See **Every screen counts from the
554
+ provider's clock** in `guide.md`.
548
555
 
549
556
  `muted` is there because the mute is the agent application's and never the provider's — see **The station is
550
557
  the agent application's** — so without a step the provider, which alone keeps the task's record, would have no
package/guide/lead.md CHANGED
@@ -29,7 +29,7 @@ computes nothing. See **`team-updated`** in `guide.md` and its companions.
29
29
  | `availability` | Required. What the member is doing now. |
30
30
  | `since` | Optional. When the current `availability` began — not when they signed in, and not when the team member list was read. |
31
31
  | `break` | Present only while the member has an outstanding break request. See **A member waiting for a break**. |
32
- | `tasks` | The member's open tasks as `MemberTask`s: the same task the member's computer holds, less the workspace. The assignment, title, task type, phase, party, room, audio and completion terms -- `completionMode`, `wrapAllowance`, `wrapEndsInSeconds` -- are what the lead reads, and the task's record -- `history`, steps and totals -- travels whole, exactly as the member's computer holds it, so the lead's screen and the member's show the same record. The workspace -- `capabilities`, `capabilitySource`, `browsers` and their URLs -- is the member's computer's alone and never travels (`team.member.task.workspace`). The party's number and email are shown to leads or locked as the provider decides for leads, apart from what it decides for the member -- see **What the queue locks is locked on the whole task**. `[]` when the member holds none; omitted only where the provider cannot see them. |
32
+ | `tasks` | The member's open tasks as `MemberTask`s: the same task the member's computer holds, less the workspace. The assignment, title, task type, phase, party, room, audio and completion terms -- `completionMode`, `wrapAllowance`, `wrapEndsInSeconds`, `wrapOverSeconds` -- are what the lead reads, and the task's record -- `history`, steps and totals -- travels whole, exactly as the member's computer holds it, so the lead's screen and the member's show the same record. A member's voice call under way carries its `answered` step here too (`task.history.answered.required`): the lead's screen times the call from it, as the member's does. The workspace -- `capabilities`, `capabilitySource`, `browsers` and their URLs -- is the member's computer's alone and never travels (`team.member.task.workspace`). The party's number and email are shown to leads or locked as the provider decides for leads, apart from what it decides for the member -- see **What the queue locks is locked on the whole task**. `[]` when the member holds none; omitted only where the provider cannot see them. |
33
33
  | `listening` | Every lead on this member's call — listening, coaching or joined — published to every lead alike: each entry names the lead by `leadId`, which of the member's calls by `assignmentId`, the `mode` they are heard in, and since when. The entry naming the signed-in lead is what their own audio opens on. Absent while nobody is on the call, never `[]` (`team.member.listening.*`); a lead is on one member's call at a time (`team.listening.single`), and a lead who is heard is also in the task's `onCall`: marked `coaching` where the member alone hears them (`team.member.listening.coaching`), unmarked once heard by everyone (`team.member.listening.heard`), and absent while listening in silence (`team.member.listening.silent`). |
34
34
  | `request` | Present while the member is asking a lead to join one of their calls: which assignment, the note they wrote, since when. The call named is one their `tasks` carry (`team.member.request.assignment`). Absent when they are not asking. See **Lead assist**. |
35
35
  | `nextCall`, `linedUp` | The member's own queue as their own snapshot carries it: their standing ask for the next call, and the call lined up for them. See **The agent's own queue** in `guide/queue.md`. |
package/guide/phone.md CHANGED
@@ -321,7 +321,7 @@ the other three are the states in which nothing can land, each wanting a differe
321
321
  connect, from the manifest's phones, as the way the agent hears this provider's calls. A state
322
322
  naming the other is the wrong phone (`phone.phone.mismatch`). The phone is the agent's; the session
323
323
  is the agent's session with the provider, and what belongs to the session is that choice. `since` is when the status began, counted from the
324
- provider's clock like every duration off the active call, and omitted rather than invented.
324
+ provider's clock like every running duration, and omitted rather than invented.
325
325
 
326
326
  **The channels.** The phone has one active audio channel and any number held
327
327
  (`phone.channel.active.single`), and a bridge is one channel: a call with people added is one entry, and its
package/guide.md CHANGED
@@ -749,7 +749,6 @@ type TaskHistoryStep = {
749
749
  type HistorySpan = {
750
750
  step: HistoryStep;
751
751
  at: IsoTimestamp;
752
- seconds?: DurationSeconds;
753
752
  entries: TaskHistoryStep[];
754
753
  };
755
754
 
@@ -811,6 +810,7 @@ type Task<C extends Channel = Channel> = {
811
810
  previewEndsInSeconds?: DurationSeconds;
812
811
  atDeadline?: PreviewDeadline;
813
812
  wrapEndsInSeconds?: DurationSeconds;
813
+ wrapOverSeconds?: DurationSeconds;
814
814
  reference?: string;
815
815
  attributes?: TaskAttribute[];
816
816
  history?: TaskHistory;
@@ -1124,6 +1124,7 @@ type MemberTask<C extends Channel = Channel> = {
1124
1124
  completionMode?: CompletionMode;
1125
1125
  wrapAllowance?: DurationSeconds;
1126
1126
  wrapEndsInSeconds?: DurationSeconds;
1127
+ wrapOverSeconds?: DurationSeconds;
1127
1128
  } & (C extends "voice"
1128
1129
  ? { onCall?: OnCall[]; leadAssist?: TaskLeadAssist; takenOver?: TaskTakenOver; audio?: TaskAudioState }
1129
1130
  : { onCall?: never; leadAssist?: never; takenOver?: never; audio?: never });
@@ -1829,7 +1830,7 @@ compile time.
1829
1830
  | `phones` | Voice only, and required there: the phones this platform can put an agent on, `softphone` (the call's audio lands in the agent application) and/or `hardphone` (a handset the platform rings; the agent application shows the call and opens nothing). The agent application picks one per session. See **How the agent hears the call** in `guide/phone.md`. |
1830
1831
  | `phoneStatus` | Voice only, declared by presence as `true`: the platform sees the phone itself -- its registration, its do-not-disturb, its hook, its calls -- and publishes it as `Snapshot.phone` and `phone-updated`. A platform that cannot see the phone omits it, and then publishes no phone (`manifest.phoneStatus`). See **The phone's own view** in `guide/phone.md`. |
1831
1832
  | `dialOutcomes` | Voice only. How a dial can end on this platform, as it distinguishes them: `answered` and at least one way of not reaching the destination. Required of a provider that dials at all — an idle dialpad, or tasks that add to the call or call back — and a `dial-outcome` carries only a declared member. See **Every dial has an outcome** in `guide/voice.md`. |
1832
- | `timeCheck` | `true`: implements `checkTime` and states `providerTime` on every snapshot. Required of a provider that publishes an instant the agent computer renders as a running duration -- a member's `since`, a `listening[].since`, an `onCall.since`, a shift's `signedInAt` -- so every screen counts from the provider's clock (`manifest.timeCheck.required`); agent application polling is independently opt-in. See **Every screen counts from the provider's clock**. |
1833
+ | `timeCheck` | `true`: implements `checkTime` and states `providerTime` on every snapshot. Required of a provider that publishes an instant the agent computer renders as a running duration -- a member's `since`, a `listening[].since`, an `onCall.since`, a shift's `signedInAt`, the `answered` step of a call under way, or a hold or mute still running -- so every screen counts from the provider's clock (`manifest.timeCheck.required`); agent application polling is independently opt-in. See **Every screen counts from the provider's clock**. |
1833
1834
  | `timestampAuthority` | Optional `"provider"`: provider timestamps are final; agent application instants are advisory. Omission makes no trust promise. |
1834
1835
  | `runningStepReports` | The provider takes running reports of an agent application-performed step — `recordStep` with `seconds` so far and no `ended`. Omitted, the agent application sends exactly two reports per leg, when it began and when it ended, and a running one is refused. See **The agent application records what it performs** in `guide/agent.md`. |
1835
1836
  | `settleMs` | Required. How long after `applied` the wire shows what the provider did: the `task-ended` after a `complete`, the `calendar-updated` after a `schedule`. A positive whole number of milliseconds (`manifest.settleMs`). Stated per provider, since platforms settle at different speeds. See **`task-ended`**. |
@@ -2577,7 +2578,7 @@ The current exceptions and their reasons are:
2577
2578
 
2578
2579
  | Case | Exception and reason |
2579
2580
  | --- | --- |
2580
- | Agent application display of provider deadlines (`expiresInSeconds`, `previewEndsInSeconds`, `wrapEndsInSeconds`) | Each is seconds from the publication that carried it, counted down on the agent computer from receipt: the provider's own arithmetic, so no clock is compared and the transport delay is the only error. The countdown estimates the display only; it does not establish that the provider acted. Without usable time, show timing uncertainty. |
2581
+ | Agent application display of provider deadlines (`expiresInSeconds`, `previewEndsInSeconds`, `wrapEndsInSeconds`, and `wrapOverSeconds` past the wrap) | Each is seconds from the publication that carried it, counted down -- or, for the overrun, on -- on the agent computer from receipt: the provider's own arithmetic, so no clock is compared and the transport delay is the only error. The countdown estimates the display only; it does not establish that the provider acted. Without usable time, show timing uncertainty. |
2581
2582
  | Agent application-triggered preview end | The agent computer counts `previewEndsInSeconds` down from receipt and issues `dial` when it reaches zero: the provider owns the deadline and the agent computer owns the trigger. It does not dial before the countdown has run out, and a reload restarts it from the next publication. |
2582
2583
  | Direct snapshot reads and method requests/results | These are reads/operations, not event envelopes, and their current types have no general event timestamp. A snapshot event still carries `occurredAt`; embedded source instants remain unchanged. Do not treat a method result or read completion time as an occurrence boundary. |
2583
2584
  | Agent application-provided provider-clock estimate | Best-effort ISO time may be supplied by the agent application for optional comparisons; it is not a source observation or accuracy guarantee. The reason is that the agent application does not own the provider clock. |
@@ -2593,25 +2594,30 @@ source-measured durations where required; timestamp subtraction is not a substit
2593
2594
 
2594
2595
  Two screens watching the same agent -- their own computer, their lead's, a manager's on another floor
2595
2596
  -- must show the same numbers. Delay between them is fine; arithmetic that differs is not. So
2596
- nothing the agent computer shows is its own count, with one exception: the running duration of the active
2597
- task or call, which a screen times itself from the moment it saw the call begin -- the
2598
- `task-audio-started` on a softphone, the answer it sent on a hardphone -- and which two such
2599
- screens may therefore disagree on, since their clocks differ. That is the whole exception. A call
2600
- a screen found already up -- on a connect or reconnect snapshot, on a lead's list, after a reload
2601
- -- is counted from the provider's `answered` step's `at` against the provider's clock, like every
2602
- other duration, so a reloaded agent computer shows 12:40 beside the lead's 12:40 and not 0:05. And a leg
2603
- that has closed shows the provider's `seconds` on every screen, never the count a screen kept.
2604
- Everything else comes from the wire.
2605
-
2606
- Durations off the active call -- how long a member has been `on-break` from their `since`, how
2607
- long a lead has been listening, how long since `signedInAt` -- are counted from the provider's
2597
+ nothing the agent computer shows is its own count. **The one sum a screen does is the tick**: it
2598
+ adds the seconds that have passed to a figure the provider stated, so a running duration moves
2599
+ without a trip to the provider every second. The figure and the clock it ticks on are both the
2600
+ provider's. The call under way is no exception: its timer counts from the provider's `answered`
2601
+ step's `at` against the provider's clock, never from the moment a screen saw the call begin, so the
2602
+ agent's own screen, a reloaded one and a lead's all show 12:40 together and none shows 0:05. A voice call
2603
+ under way -- `in-progress` or `paused` -- therefore carries its `answered` step (`task.history.answered.required`), and a screen
2604
+ with no answered step shows no timer rather than one of its own. A leg that has closed shows the
2605
+ provider's `seconds` on every screen, never a count a screen kept. Everything else comes from the
2606
+ wire.
2607
+
2608
+ Every running duration -- the call under way from its answer, a hold or mute still running from its
2609
+ `at`, how long a member has been `on-break` from their `since`, how long a lead has been
2610
+ listening, how long since `signedInAt` -- is counted from the provider's
2608
2611
  clock, never the screen's. The agent computer keeps the latest provider instant it has received -- a
2609
2612
  snapshot's `providerTime`, an envelope's `occurredAt`, a `checkTime` result -- with the monotonic
2610
2613
  elapsed time since receipt, and renders every such duration from that; a sample older than
2611
2614
  `maxSampleAgeMs` is refreshed with `checkTime`. Without a usable sample the agent computer shows the instant
2612
2615
  and no count. A provider that publishes any of these instants therefore declares `timeCheck`
2613
2616
  (`manifest.timeCheck.required`) and states `providerTime` on every snapshot
2614
- (`snapshot.providerTime`). Two screens then differ by their delay and nothing else.
2617
+ (`snapshot.providerTime`). Two screens then differ by their delay and nothing else. Nothing
2618
+ assumes the screen's clock is set right, by NTP or otherwise: the screen's wall clock is never
2619
+ read for a duration, only its monotonic timer since a provider sample, so a computer whose clock
2620
+ is minutes out still shows the provider's numbers.
2615
2621
 
2616
2622
  **Seconds left are worked out at each publication.** `expiresInSeconds`, `previewEndsInSeconds`,
2617
2623
  `wrapEndsInSeconds` and `endsInSeconds` are each the provider's arithmetic at the instant
@@ -2622,7 +2628,11 @@ names it: between two publications of one countdown the value loses at least the
2622
2628
  provider's own clock says passed, within a second of rounding (`stream.countdown.copied`, on an
2623
2629
  update against the last publication, and on a snapshot from a provider with a clock against its
2624
2630
  `providerTime`). Under `agent-command` the wrap's value reaches `0` and stays there while the agent
2625
- overruns; that is the true value, not a copy.
2631
+ overruns; that is the true value, not a copy. From then on the task carries `wrapOverSeconds`, how
2632
+ far past the expected wrap it is at that publication (`task.completing.wrapOverSeconds.required`),
2633
+ so a screen that reloads mid-overrun shows the same overrun as one that watched it happen. It
2634
+ counts the other way and is held the other way: between two publications it gains at least the
2635
+ seconds that passed, within a second of rounding (`stream.overrun.copied`).
2626
2636
 
2627
2637
  **A deadline stated is a deadline kept.** The provider that says how long an offer has ends it
2628
2638
  `expired` when it runs out, and the test holds it to that: where the first offer carries
@@ -3106,10 +3116,14 @@ Whether two sessions declare the same capabilities, field by field — key order
3106
3116
  ### `historySpans(steps)`
3107
3117
 
3108
3118
  Groups a record's consecutive entries of one step into a `HistorySpan` each — `step`, the first
3109
- entry's `at`, `seconds` summed when every entry states one and absent when any does not, and the
3110
- `entries` themselves — so every agent application shows *Self-service · 30s* once where the
3111
- record has two self-service entries in a row. Only neighbours are grouped: a hold, an answer and
3112
- another hold are three spans. See **Shown as spans** in `guide/agent.md`.
3119
+ entry's `at`, and the `entries` themselves — so every agent application shows *Self-service*
3120
+ once where the record has two self-service entries in a row, with each entry's own `seconds`.
3121
+ A span states no total: the provider rounds each entry to the second, so a sum of them could
3122
+ differ from the provider's own. Only neighbours are grouped: a hold, an answer and another hold
3123
+ are three spans. See **Shown as spans** in `guide/agent.md`.
3124
+
3125
+ Migration: a span no longer carries a `seconds` total. Show each entry's `seconds`, or a total
3126
+ the provider states.
3113
3127
 
3114
3128
  ## Runtime validation
3115
3129
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xema/omni-protocol",
3
- "version": "0.1.134",
3
+ "version": "0.1.135",
4
4
  "description": "The Omni protocol: the contract every provider adapter implements",
5
5
  "type": "module",
6
6
  "license": "MIT",