@xema/omni-protocol 0.1.133 → 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
 
@@ -83,7 +84,8 @@ hands only through routing or a lead's take-over.
83
84
  | --- | --- | --- |
84
85
  | **Capacity** | How many tasks the agent can take at once on this provider. Zero means none. | *Concurrency* (Amazon Connect routing profiles), *capacity* (Twilio, Salesforce), *utilization* (Genesys Cloud). |
85
86
  | **Break** | Time away: lunch, training, a personal break. The agent asks, the provider decides. | *Aux* or *auxiliary code* (Avaya and many floors), *presence* such as Break or Meal (Genesys Cloud), *agent status* (Amazon Connect), *unavailable code* (NICE). |
86
- | **Forced break** | A break a lead or the provider puts the agent on. | *Forced aux*, *supervisor-set status*. |
87
+ | **Forced break** | A break a lead or the provider puts the agent on. The agent cannot end it, and signing out does not clear it. | *Forced aux*, *supervisor-set status*. |
88
+ | **Team break** | A forced break on the whole team, to one end for everyone. Time signed out counts towards it. | *Scheduled break*, *team aux*. |
87
89
  | **Next call** | The agent says they are ready for another call before this one ends. | *Request next*, *ready for next*. |
88
90
  | **Lined up** | A call waiting in this agent's own queue, held for them. | *Agent queue* or *personal queue* (Amazon Connect), *direct routing*. |
89
91
  | **Shift** | The agent's day: when they signed in, their breaks, their totals. | *Schedule adherence* data, *agent state history*. |
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;
@@ -380,7 +381,9 @@ export declare const LEAD_COMMAND_CAPABILITY: {
380
381
  readonly "decide-break-request": "decideBreakRequest";
381
382
  readonly "set-break-policy": "setBreakPolicy";
382
383
  readonly "force-break": "forceBreak";
384
+ readonly "force-team-break": "forceBreak";
383
385
  readonly "end-forced-break": "endForcedBreak";
386
+ readonly "end-team-break": "endForcedBreak";
384
387
  readonly "set-policy": "setPolicy";
385
388
  };
386
389
  /**
@@ -1157,6 +1160,12 @@ export type Task<C extends Channel = Channel> = {
1157
1160
  * once overrun, and nothing acts on it.
1158
1161
  */
1159
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;
1160
1169
  /** The identifier an agent reads back to a customer, where the provider has one. */
1161
1170
  reference?: string;
1162
1171
  attributes?: TaskAttribute[];
@@ -1396,21 +1405,31 @@ export interface BreakRequest {
1396
1405
  reasonId?: string;
1397
1406
  }
1398
1407
  /**
1399
- * A break forced on the agent; the agent must explicitly resume when ready. A lead's `force-break`
1400
- * is a command to the provider, which forces the break: `by` names the lead who asked it to, or
1401
- * `provider` where the platform itself did, on its own rule or a schedule. The agent sees who, a
1402
- * person is named only when there is one, and a break the platform imposed is the platform's to
1403
- * lift: a lead's `end-forced-break` on it fails with `omni.break-forced-by-provider`.
1408
+ * Whom a forced break covers. `team`: the whole team, to one end for everyone, its clock running
1409
+ * while a member is signed out. `agent`: one agent, its clock counting only while they are signed in.
1410
+ */
1411
+ export type ForcedBreakScope = "team" | "agent";
1412
+ export declare const FORCED_BREAK_SCOPES: readonly ["team", "agent"];
1413
+ /**
1414
+ * A break forced on the agent, which the agent cannot end. Signing out ends the session, not the
1415
+ * break: the next session's snapshot carries it again while it stands. It is lifted by a lead, by
1416
+ * the platform, or by its time running out; lifting clears `forced` and leaves an ordinary break
1417
+ * the agent ends when ready. A lead's `force-break` or `force-team-break` is a command to the
1418
+ * provider, which forces the break: `by` names the lead who asked it to, or `provider` where the
1419
+ * platform itself did, on its own rule or a schedule. The agent sees who, a person is named only
1420
+ * when there is one, and a break the platform imposed is the platform's to lift: a lead's
1421
+ * `end-forced-break` on it fails with `omni.break-forced-by-provider`.
1404
1422
  */
1405
1423
  export type ForcedBreak = {
1406
1424
  by: UserId | "provider";
1425
+ scope: ForcedBreakScope;
1407
1426
  /**
1408
- * How long the break is expected to run yet, in whole seconds from this publication, restated
1409
- * on every publication that carries it so every screen counts down the same number from
1410
- * receipt. Advisory only: nothing ends the break but the agent. Absent once it has run out, or
1411
- * where none was expected.
1427
+ * How long the break has left, in whole seconds from this publication, restated on every
1428
+ * publication that carries it so every screen counts down the same number from receipt. When it
1429
+ * runs out the provider lifts the break. Required on a `team` break; absent on an `agent` break
1430
+ * that stands until a lead lifts it.
1412
1431
  */
1413
- expectedEndsInSeconds?: DurationSeconds;
1432
+ endsInSeconds?: DurationSeconds;
1414
1433
  };
1415
1434
  export interface BreakState {
1416
1435
  status: BreakStatus;
@@ -1554,6 +1573,8 @@ export type MemberTask<C extends Channel = Channel> = {
1554
1573
  completionMode?: CompletionMode;
1555
1574
  wrapAllowance?: DurationSeconds;
1556
1575
  wrapEndsInSeconds?: DurationSeconds;
1576
+ /** How far past the expected wrap, as on the member's own task. */
1577
+ wrapOverSeconds?: DurationSeconds;
1557
1578
  } & (C extends "voice" ? {
1558
1579
  onCall?: OnCall[];
1559
1580
  leadAssist?: TaskLeadAssist;
@@ -1699,18 +1720,29 @@ export type TeamBreakCommand = {
1699
1720
  type: "set-break-policy";
1700
1721
  policy: "approval-required" | "automatically-approved" | "requests-suspended";
1701
1722
  }
1702
- /** `reason` text is optional. `reasonId` selects a published `BreakReason.id`, required when reasons are published; the forced break carries it as `activeReasonId`. */
1723
+ /** `reason` text is optional. `reasonId` selects a published `BreakReason.id`, required when reasons are published; the forced break carries it as `activeReasonId`. Without `durationSeconds` it stands until lifted. */
1703
1724
  | {
1704
1725
  type: "force-break";
1705
1726
  memberId: UserId;
1706
1727
  reasonId?: string;
1707
1728
  reason?: string;
1708
- expectedDurationSeconds?: DurationSeconds;
1729
+ durationSeconds?: DurationSeconds;
1730
+ }
1731
+ /** The whole team, members who sign in while it runs included, to one end `durationSeconds` from now. */
1732
+ | {
1733
+ type: "force-team-break";
1734
+ reasonId?: string;
1735
+ reason?: string;
1736
+ durationSeconds: DurationSeconds;
1709
1737
  }
1710
1738
  /** Clears forced metadata only; preserves the committed break until the agent explicitly resumes. */
1711
1739
  | {
1712
1740
  type: "end-forced-break";
1713
1741
  memberId: UserId;
1742
+ }
1743
+ /** Lifts the team break for every member, as `end-forced-break` does for one. */
1744
+ | {
1745
+ type: "end-team-break";
1714
1746
  };
1715
1747
  /** Every lead act, as `execute` takes a `TaskCommand`: discriminated by `type`. */
1716
1748
  export type TeamCommand = TeamFeatureCommand | TeamBreakCommand | TeamCallCommand | TeamPolicyCommand;
@@ -1835,7 +1867,7 @@ export interface Snapshot<C extends Channel = Channel> {
1835
1867
  sessionId: string;
1836
1868
  /**
1837
1869
  * The provider's own instant of this read, required of a provider that declares `timeCheck`:
1838
- * 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
1839
1871
  * this sample saves a `checkTime` for it. Every envelope's `occurredAt` is a sample too.
1840
1872
  */
1841
1873
  providerTime?: IsoTimestamp;
@@ -2005,7 +2037,7 @@ export interface ProviderEventEnvelope<C extends Channel = Channel> {
2005
2037
  occurredAt: IsoTimestamp;
2006
2038
  event: ProviderEvent<C>;
2007
2039
  }
2008
- export declare const OMNI_FAILURE_CODES: readonly ["omni.not-authenticated", "omni.capability-not-enabled", "omni.assignment-not-found", "omni.destination-not-permitted", "omni.phone-not-permitted", "omni.rate-limited", "omni.unavailable", "omni.break-already-committed", "omni.recording-unsettled", "omni.on-hold", "omni.break-forced-by-provider"];
2040
+ export declare const OMNI_FAILURE_CODES: readonly ["omni.not-authenticated", "omni.capability-not-enabled", "omni.assignment-not-found", "omni.destination-not-permitted", "omni.phone-not-permitted", "omni.rate-limited", "omni.unavailable", "omni.break-already-committed", "omni.recording-unsettled", "omni.on-hold", "omni.break-forced-by-provider", "omni.break-forced"];
2009
2041
  export type OmniFailureCode = (typeof OMNI_FAILURE_CODES)[number];
2010
2042
  /**
2011
2043
  * What the host refused, told to the adapter that published it: a snapshot the host would not
@@ -2179,13 +2211,12 @@ export declare const historyStepDials: (step: HistoryStep) => boolean;
2179
2211
  /**
2180
2212
  * Consecutive entries of one step, shown as one span. The record keeps an entry per occurrence --
2181
2213
  * two holds are counted as two -- and this is how the agent sees them: once, from the first
2182
- * entry's `at`, lasting the sum of their `seconds` when every entry states one, and with no
2183
- * 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.
2184
2216
  */
2185
2217
  export interface HistorySpan {
2186
2218
  step: HistoryStep;
2187
2219
  at: IsoTimestamp;
2188
- seconds?: DurationSeconds;
2189
2220
  entries: TaskHistoryStep[];
2190
2221
  }
2191
2222
  /** Groups a record's consecutive same-step entries into spans, oldest first. */
package/dist/index.js CHANGED
@@ -40,7 +40,9 @@ export const LEAD_COMMAND_CAPABILITY = {
40
40
  "decide-break-request": "decideBreakRequest",
41
41
  "set-break-policy": "setBreakPolicy",
42
42
  "force-break": "forceBreak",
43
+ "force-team-break": "forceBreak",
43
44
  "end-forced-break": "endForcedBreak",
45
+ "end-team-break": "endForcedBreak",
44
46
  "set-policy": "setPolicy",
45
47
  };
46
48
  export const MUTED_BY = ["host", "station"];
@@ -99,6 +101,7 @@ export const BREAK_KINDS = [
99
101
  "short-break", "meal", "rest", "training", "coaching",
100
102
  "meeting", "administrative", "technical", "personal", "other",
101
103
  ];
104
+ export const FORCED_BREAK_SCOPES = ["team", "agent"];
102
105
  export const SHIFT_EVENT_KINDS = ["signed-in", "signed-out", "break-started", "break-ended"];
103
106
  export const SHIFT_FIGURES = ["talk", "hold", "break"];
104
107
  export const OMNI_FAILURE_CODES = [
@@ -116,6 +119,8 @@ export const OMNI_FAILURE_CODES = [
116
119
  "omni.on-hold",
117
120
  /** A lead asked to lift a break the platform itself imposed; the platform lifts its own. */
118
121
  "omni.break-forced-by-provider",
122
+ /** The agent asked to end a break that is still forced; only its lifting does. */
123
+ "omni.break-forced",
119
124
  ];
120
125
  /**
121
126
  * Preserves the adapter's inferred concrete type while checking it implements `Adapter`.
@@ -219,11 +224,6 @@ export function historySpans(steps) {
219
224
  else
220
225
  spans.push({ step: entry.step, at: entry.at, entries: [entry] });
221
226
  }
222
- for (const span of spans) {
223
- if (span.entries.every(entry => entry.seconds !== undefined)) {
224
- span.seconds = span.entries.reduce((total, entry) => total + entry.seconds, 0);
225
- }
226
- }
227
227
  return spans;
228
228
  }
229
229
  /** Whether an absent `by` means "could not attribute" rather than "nobody was involved". */
package/dist/testing.d.ts CHANGED
@@ -7,7 +7,7 @@ export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation }
7
7
  * rules -- each optional part of a task, each optional part of the break state and team member list, each
8
8
  * declared contribution, and each event type.
9
9
  */
10
- declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.history", "task.onCall", "task.leadAssist", "task.takenOver", "task.audio", "task.acceptance", "task.outcomes", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.forced", "team.members", "team.request", "team.tasks", "team.listening", "team.shift", "team.phone", "team.nextCall", "team.linedUp", "shift", "phone", "nextCall", "linedUp", "labels", "contacts", "calendar", "team.policies"];
10
+ declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.history", "task.onCall", "task.leadAssist", "task.takenOver", "task.audio", "task.acceptance", "task.outcomes", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.forced", "break.forced.signIn", "team.members", "team.request", "team.tasks", "team.listening", "team.shift", "team.phone", "team.nextCall", "team.linedUp", "shift", "phone", "nextCall", "linedUp", "labels", "contacts", "calendar", "team.policies"];
11
11
  export type ContractSubject = (typeof STATE_SUBJECTS)[number] | `event.${ProviderEvent["type"]}`;
12
12
  export interface AdapterContractResult {
13
13
  events: ProviderEventEnvelope[];
@@ -57,6 +57,14 @@ export interface TestAdapterOptions {
57
57
  * memory has nothing, and is named. Without it the store is required and never read.
58
58
  */
59
59
  rebuild?: () => Adapter<Channel>;
60
+ /**
61
+ * Builds the adapter again after the agent signed out, for a backend that signs the same agent
62
+ * in again, as a sign-in screen would. Given it, a run whose agent is on a forced break at the end
63
+ * signs out, signs in, and expects the new session's snapshot to carry the same break, its time
64
+ * left counted by its kind's clock. Without it, or with no forced break to carry, the run lists
65
+ * `break.forced.signIn` under `notTested`.
66
+ */
67
+ signInAgain?: () => Adapter<Channel>;
60
68
  /**
61
69
  * The values the queue locks on this session's tasks -- a party's number or email -- as the run's
62
70
  * author knows them. A task whose party stands locked may carry none of them anywhere else
package/dist/testing.js CHANGED
@@ -23,6 +23,7 @@ const STATE_SUBJECTS = [
23
23
  "task.locked",
24
24
  "break.reasons",
25
25
  "break.forced",
26
+ "break.forced.signIn",
26
27
  "team.members",
27
28
  "team.request",
28
29
  "team.tasks",
@@ -729,6 +730,100 @@ export async function testAdapter(adapter, context, options = {}) {
729
730
  const restated = await connection.setCapacity({ count });
730
731
  violations.push(...validateResult(restated, "setCapacity", "connection.setCapacity"));
731
732
  }
733
+ // A forced break outlives the session: the agent signs out and in again and finds it waiting,
734
+ // or signing out would undo any forced break. Its time left runs on while a team break's
735
+ // members are away, and stands still for an agent's own.
736
+ if (options.signInAgain !== undefined && clientLive) {
737
+ const refuse = (rule, path, message) => violations.push({ rule, path, message });
738
+ const fresh = await connection.snapshot();
739
+ const readAt = Date.now();
740
+ const before = isRecord(fresh) && isRecord(fresh.break) ? fresh.break : undefined;
741
+ const forced = before !== undefined && isRecord(before.forced) ? before.forced : undefined;
742
+ if (before !== undefined && forced !== undefined) {
743
+ seen.add("break.forced.signIn");
744
+ ruleTested("test.signIn.rejected");
745
+ let clean = true;
746
+ try {
747
+ unsubscribe?.();
748
+ }
749
+ catch {
750
+ clean = false;
751
+ }
752
+ unsubscribe = undefined;
753
+ try {
754
+ await connection.disconnect();
755
+ }
756
+ catch {
757
+ clean = false;
758
+ }
759
+ try {
760
+ const out = await authentication.signOut();
761
+ ruleTested("test.signIn.signOut");
762
+ if (!isRecord(out) || out.status !== "applied")
763
+ refuse("test.signIn.signOut", "test.signIn.signOut", `the agent's Sign out on a forced break answered ${JSON.stringify(out)}: the run cannot sign in again from a session that would not end`);
764
+ }
765
+ catch {
766
+ clean = false;
767
+ }
768
+ try {
769
+ await authentication.close();
770
+ }
771
+ catch {
772
+ clean = false;
773
+ }
774
+ clientLive = false;
775
+ if (!clean)
776
+ refuse("test.signIn.rejected", "test.signIn", "signing out on a forced break threw: an unsubscribe, disconnect(), signOut() or close() failed");
777
+ const outAt = Date.now();
778
+ try {
779
+ const again = options.signInAgain();
780
+ const session = await again.createAuthenticationSession({ ...context, secrets: authenticationSecrets });
781
+ try {
782
+ const state = await session.state();
783
+ ruleTested("test.signIn.session");
784
+ if (!(isRecord(state) && state.status === "authenticated" && isRecord(state.identity) && state.identity.id === current().identity.id)) {
785
+ refuse("test.signIn.session", "test.signIn.session", `signed in again, the session says ${String(isRecord(state) ? state.status : state)}; the run needs ${String(current().identity.id)} authenticated to see the break`);
786
+ }
787
+ else {
788
+ const inAt = Date.now();
789
+ const reconnecting = connectingReports(connected, violations);
790
+ let second;
791
+ try {
792
+ second = await again.connect(reconnecting.context);
793
+ }
794
+ finally {
795
+ reconnecting.settled();
796
+ }
797
+ try {
798
+ const after = await second.snapshot();
799
+ const gotAt = Date.now();
800
+ await snapshotRead(second, after, "test.signIn.snapshot");
801
+ violations.push(...forcedBreakCarried(before, forced, after, { readAt, outAt, inAt, gotAt }));
802
+ }
803
+ finally {
804
+ try {
805
+ await second.disconnect();
806
+ }
807
+ catch {
808
+ refuse("test.signIn.rejected", "test.signIn", "disconnecting the signed-in-again client threw");
809
+ }
810
+ }
811
+ }
812
+ }
813
+ finally {
814
+ try {
815
+ await session.close();
816
+ }
817
+ catch {
818
+ refuse("test.signIn.rejected", "test.signIn", "closing the signed-in-again session threw");
819
+ }
820
+ }
821
+ }
822
+ catch (error) {
823
+ refuse("test.signIn.rejected", "test.signIn", `signing in again rejected rather than answered: ${String(error)}`);
824
+ }
825
+ }
826
+ }
732
827
  }
733
828
  finally {
734
829
  let clean = true;
@@ -1257,12 +1352,28 @@ export class TaskStream {
1257
1352
  if (before !== undefined) {
1258
1353
  ruleTested("stream.countdown.copied");
1259
1354
  const elapsed = Math.floor((atMs - before.atMs) / 1000);
1260
- 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) {
1261
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`);
1262
1358
  }
1263
1359
  }
1264
1360
  known.set(field, { value, atMs });
1265
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
+ }
1266
1377
  this.countdowns.set(id, known);
1267
1378
  }
1268
1379
  // Every dial the stream can place an outcome against: one the host said it placed, or one a
@@ -2293,8 +2404,8 @@ async function testOneCall(call) {
2293
2404
  // A request goes not-requested -> awaiting-approval | granted; a commit goes granted ->
2294
2405
  // starting-after-task | on-break; work ending goes starting-after-task -> on-break; a denial,
2295
2406
  // a cancel or an explicit agent end goes back to not-requested; a lead lifting forced status
2296
- // preserves the committed break. A forced break arrives on-break
2297
- // with `forced`. Nothing else is a move the guide describes.
2407
+ // preserves the committed break. A forced break arrives on-break with `forced`, and never goes
2408
+ // back to not-requested while it is forced. Nothing else is a move the guide describes.
2298
2409
  /** What a stream has said about the agent's break, and the moves it may not make. */
2299
2410
  /**
2300
2411
  * The team as the events left it: whole on `team-updated` and on any snapshot carrying one, then
@@ -2417,6 +2528,42 @@ export function assertAudioFollowsTheTask(envelopes, snapshot) {
2417
2528
  envelopes.forEach((envelope, index) => found.push(...stream.apply(envelope, `envelopes[${index}]`)));
2418
2529
  assertNoViolations(found, "The audio follows the task");
2419
2530
  }
2531
+ /**
2532
+ * The break the agent signed out on, held to the one the next session carries: the same forced
2533
+ * break, from the same person, on the same reason, with what is left of its time by its kind's
2534
+ * clock -- a team break's ran on while the agent was away, an agent's own stood still. Each bound
2535
+ * allows a second of rounding at either end.
2536
+ */
2537
+ function forcedBreakCarried(before, forced, after, at) {
2538
+ const found = [];
2539
+ const left = typeof forced.endsInSeconds === "number" ? forced.endsInSeconds : undefined;
2540
+ const whole = Math.floor((at.gotAt - at.readAt) / 1000);
2541
+ // A team break that could have run out while the agent was away may rightly be gone.
2542
+ if (forced.scope === "team" && left !== undefined && left - whole <= 1)
2543
+ return found;
2544
+ ruleTested("test.signIn.forcedBreak");
2545
+ const now = isRecord(after) && isRecord(after.break) ? after.break : undefined;
2546
+ const carried = now !== undefined && isRecord(now.forced) ? now.forced : undefined;
2547
+ if (carried === undefined || !(now.status === "on-break" || now.status === "starting-after-task")
2548
+ || carried.by !== forced.by || carried.scope !== forced.scope || now.activeReasonId !== before.activeReasonId) {
2549
+ found.push({ rule: "test.signIn.forcedBreak", path: "test.signIn.snapshot.break",
2550
+ message: `the agent signed out on a ${String(forced.scope)} break forced by ${String(forced.by)}, and the next session's snapshot carries ${carried === undefined ? "no forced break" : `a break forced by ${String(carried.by)}, ${String(carried.scope)}, on ${String(now.activeReasonId)}`}: signing out ends the session, not the break` });
2551
+ return found;
2552
+ }
2553
+ ruleTested("test.signIn.endsInSeconds");
2554
+ const leftNow = typeof carried.endsInSeconds === "number" ? carried.endsInSeconds : undefined;
2555
+ const signedIn = Math.ceil(((at.outAt - at.readAt) + (at.gotAt - at.inAt)) / 1000);
2556
+ const fault = left === undefined
2557
+ ? (leftNow === undefined ? undefined : `it had no end and now ends in ${leftNow}s`)
2558
+ : leftNow === undefined ? `it had ${left}s left and now states none`
2559
+ : leftNow > left ? `it had ${left}s left and now has ${leftNow}s: time left never grows`
2560
+ : forced.scope === "team" && leftNow > left - whole + 1 ? `it had ${left}s left, ${whole}s passed, and it has ${leftNow}s: a team break's time runs on while the agent is away`
2561
+ : forced.scope === "agent" && leftNow < left - signedIn - 1 ? `it had ${left}s left, the agent was signed in for ${signedIn}s of it, and it has ${leftNow}s: an agent's own break counts only while they are signed in`
2562
+ : undefined;
2563
+ if (fault !== undefined)
2564
+ found.push({ rule: "test.signIn.endsInSeconds", path: "test.signIn.snapshot.break.forced.endsInSeconds", message: fault });
2565
+ return found;
2566
+ }
2420
2567
  /** The store as handed to the adapter, and the keys it holds at any moment, seen rather than reported. */
2421
2568
  function watchStore(store) {
2422
2569
  const held = new Set();
@@ -9,7 +9,7 @@
9
9
  // Each list is pinned to its type both ways -- a member the type lacks, or a member the list
10
10
  // lacks, fails to compile -- so what the validators accept cannot drift from what the
11
11
  // declarations say.
12
- import { RECORDING_ACTIONS, LEAD_COMMAND_CAPABILITY, SHIFT_EVENT_KINDS, SHIFT_FIGURES, RECORDING_SIDES, RECORDING_STATUSES, RECORDING_PAUSED_REASONS, RECORDING_UNKNOWN_REASONS, ALLOWED_BROWSER_URL_SCHEMES, BREAK_KINDS, BROWSER_ISOLATION_SCHEMES, HISTORY_STEPS_THAT_DIAL, IDLE_CAPABILITIES, OMNI_FAILURE_CODES, OMNI_SUPPORTED_PROTOCOL_VERSIONS, TASK_COMMAND_NAMES, negotiateProtocolVersion, } from "./index.js";
12
+ import { RECORDING_ACTIONS, LEAD_COMMAND_CAPABILITY, SHIFT_EVENT_KINDS, SHIFT_FIGURES, FORCED_BREAK_SCOPES, RECORDING_SIDES, RECORDING_STATUSES, RECORDING_PAUSED_REASONS, RECORDING_UNKNOWN_REASONS, ALLOWED_BROWSER_URL_SCHEMES, BREAK_KINDS, BROWSER_ISOLATION_SCHEMES, HISTORY_STEPS_THAT_DIAL, IDLE_CAPABILITIES, OMNI_FAILURE_CODES, OMNI_SUPPORTED_PROTOCOL_VERSIONS, TASK_COMMAND_NAMES, negotiateProtocolVersion, } from "./index.js";
13
13
  export class ProtocolConformanceError extends Error {
14
14
  violations;
15
15
  constructor(violations, summary = "Adapter violates the Omni protocol") {
@@ -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
@@ -1417,11 +1440,14 @@ function validateForcedBreak(value, path, into) {
1417
1440
  }
1418
1441
  into.require(isUserId(value.by) || value.by === "provider", "break.forced.by", `${path}.by`, "a forced break says who forced it: the lead by user id, or provider where the platform did");
1419
1442
  for (const field of ["endsAutomatically", "endsAt"]) {
1420
- into.require(!Object.hasOwn(value, field), "break.forced.manualResume", `${path}.${field}`, "automatic ending fields are unsupported; the agent must resume manually");
1443
+ into.require(!Object.hasOwn(value, field), "break.forced.manualResume", `${path}.${field}`, "the end is endsInSeconds, counted from each publication; after it the agent resumes by their own choice");
1421
1444
  }
1422
- into.require(!Object.hasOwn(value, "expectedDurationMs"), "break.forced.expectedDurationMs.renamed", `${path}.expectedDurationMs`, "the state says how long is left, as expectedEndsInSeconds; the duration asked for travels on the lead's command alone");
1423
- if (value.expectedEndsInSeconds !== undefined)
1424
- into.require(isDurationSeconds(value.expectedEndsInSeconds), "break.forced.expectedEndsInSeconds", `${path}.expectedEndsInSeconds`, "expectedEndsInSeconds is how long the break is expected to run yet: a whole number of seconds, zero or more, counted from this publication");
1445
+ into.oneOf(value.scope, FORCED_BREAK_SCOPES, "break.forced.scope", `${path}.scope`);
1446
+ into.require(value.scope !== "team" || value.endsInSeconds !== undefined, "break.forced.team.endsInSeconds", `${path}.endsInSeconds`, "a team break always has an end: state endsInSeconds on every publication, and lift the break when it runs out");
1447
+ into.require(!Object.hasOwn(value, "expectedEndsInSeconds"), "break.forced.expectedEndsInSeconds.renamed", `${path}.expectedEndsInSeconds`, "expectedEndsInSeconds is now endsInSeconds: the break is lifted when it runs out");
1448
+ into.require(!Object.hasOwn(value, "expectedDurationMs"), "break.forced.expectedDurationMs.renamed", `${path}.expectedDurationMs`, "the state says how long is left, as endsInSeconds; the duration asked for travels on the lead's command alone");
1449
+ if (value.endsInSeconds !== undefined)
1450
+ into.require(isDurationSeconds(value.endsInSeconds), "break.forced.endsInSeconds", `${path}.endsInSeconds`, "endsInSeconds is how long the break has left: a whole number of seconds, zero or more, counted from this publication");
1425
1451
  }
1426
1452
  /** Checks break status against the full currently retained task set, after a transaction. */
1427
1453
  export function validateBreakStatus(state, tasks, path = "snapshot") {
@@ -1475,7 +1501,8 @@ export function validateTeamCommand(request, context, path = "teamCommand") {
1475
1501
  const allowed = {
1476
1502
  "lead-features": ["type", "enabled"],
1477
1503
  "decide-break-request": ["type", "memberId", "decision", "reason"], "set-break-policy": ["type", "policy"],
1478
- "force-break": ["type", "memberId", "reasonId", "reason", "expectedDurationSeconds"], "end-forced-break": ["type", "memberId"],
1504
+ "force-break": ["type", "memberId", "reasonId", "reason", "durationSeconds"], "end-forced-break": ["type", "memberId"],
1505
+ "force-team-break": ["type", "reasonId", "reason", "durationSeconds"], "end-team-break": ["type"],
1479
1506
  join: member, decline: [...member, "reason"], listen: member, coach: member, "join-call": member, leave: member, "take-over-call": member,
1480
1507
  "set-policy": ["type", "capability", "setting"],
1481
1508
  };
@@ -1494,6 +1521,16 @@ export function validateTeamCommand(request, context, path = "teamCommand") {
1494
1521
  into.require(key === "command", "team.request.field", `${path}.${key}`, "only command is supported");
1495
1522
  for (const key of Object.keys(command))
1496
1523
  into.require(fields.includes(key), "team.command.field", `${path}.${key}`, "field is not supported for this command");
1524
+ if (command.type === "force-break" || command.type === "force-team-break") {
1525
+ into.require(!Object.hasOwn(command, "expectedDurationSeconds"), "team.command.expectedDurationSeconds.renamed", `${path}.expectedDurationSeconds`, "expectedDurationSeconds is now durationSeconds: the break is lifted when it runs out");
1526
+ if (command.durationSeconds !== undefined || command.type === "force-team-break")
1527
+ into.require(isDurationSeconds(command.durationSeconds) && command.durationSeconds > 0, "team.command.durationSeconds", `${path}.durationSeconds`, "durationSeconds must be a whole number of seconds, more than zero; a team break always states one");
1528
+ if (command.reasonId !== undefined)
1529
+ into.filled(command.reasonId, "team.command.reasonId", path, "reasonId must not be empty");
1530
+ }
1531
+ // A team break names no member: the provider rechecks its reason codes and whether one is running.
1532
+ if (command.type === "force-team-break" || command.type === "end-team-break")
1533
+ return into.violations;
1497
1534
  if (command.reason !== undefined)
1498
1535
  into.filled(command.reason, "team.command.reason", path, "reason must not be empty");
1499
1536
  if (command.type === "lead-features") {
@@ -1536,10 +1573,6 @@ export function validateTeamCommand(request, context, path = "teamCommand") {
1536
1573
  into.require(!(isPlainObject(state.forced) && state.forced.by === "provider"), "team.command.endForcedBreak.provider", path, "the platform put this member on the break, and it lifts it: a lead ends a break a lead forced");
1537
1574
  }
1538
1575
  if (command.type === "force-break") {
1539
- if (command.expectedDurationSeconds !== undefined)
1540
- into.require(isDurationSeconds(command.expectedDurationSeconds) && command.expectedDurationSeconds > 0, "team.command.expectedDurationSeconds", `${path}.expectedDurationSeconds`, "expectedDurationSeconds must be a whole number of seconds, more than zero; it never resumes the agent");
1541
- if (command.reasonId !== undefined)
1542
- into.filled(command.reasonId, "team.command.reasonId", path, "reasonId must not be empty");
1543
1576
  const reasons = Array.isArray(state.reasons) ? state.reasons : [];
1544
1577
  into.require(state.reasons === undefined ? command.reasonId === undefined : reasons.some((r) => isPlainObject(r) && r.id === command.reasonId), "team.command.reasonId", path, "force-break uses the target's currently published reason codes");
1545
1578
  }
@@ -1605,7 +1638,7 @@ export function validateBreakCommand(method, request, state, context, path = "br
1605
1638
  into.require(status === "awaiting-approval" || status === "granted", "break.command.cancel.precommit", path, "cancel only a pre-commit request; a raced commit requires commit recovery");
1606
1639
  if (method === "endBreak") {
1607
1640
  into.require(status === "starting-after-task" || status === "on-break", "break.command.end.started", path, "end a committed break, including a returning provider still finishing work");
1608
- // A forced break also ends only when the agent explicitly resumes.
1641
+ into.require(state.forced === undefined, "break.command.end.forced", path, "a forced break is not the agent's to end: it ends only when it is lifted");
1609
1642
  }
1610
1643
  }
1611
1644
  return into.violations;
@@ -1629,6 +1662,9 @@ export function validateBreakTransition(before, after, path = "break") {
1629
1662
  if (committed && (from === "not-requested" || from === "awaiting-approval") && after.forced === undefined) {
1630
1663
  into.add("stream.breakState.commitBeforeGrant", `${path}.after.status`, `${to} follows a commit, and a commit follows granted; the break stood at ${from}`);
1631
1664
  }
1665
+ if (before.forced !== undefined && from !== "not-requested" && to === "not-requested") {
1666
+ into.add("stream.breakState.forcedEnded", `${path}.after.status`, "a forced break is lifted first, clearing forced, before the break can end");
1667
+ }
1632
1668
  const backwards = (from === "on-break" && (to === "awaiting-approval" || to === "granted" || to === "starting-after-task")) ||
1633
1669
  (from === "starting-after-task" && (to === "awaiting-approval" || to === "granted")) ||
1634
1670
  (from === "granted" && to === "awaiting-approval");
@@ -2316,7 +2352,7 @@ function carriesRunningInstant(value) {
2316
2352
  ...(Array.isArray(value.tasks) ? value.tasks : []),
2317
2353
  ...(isPlainObject(value.task) ? [value.task] : []),
2318
2354
  ];
2319
- if (tasks.some(task => isPlainObject(task) && Array.isArray(task.onCall) && task.onCall.some((who) => isPlainObject(who) && who.since !== undefined)))
2355
+ if (tasks.some(taskCarriesRunningInstant))
2320
2356
  return true;
2321
2357
  const members = [
2322
2358
  ...(isPlainObject(value.team) && Array.isArray(value.team.members) ? value.team.members : []),
@@ -2325,13 +2361,26 @@ function carriesRunningInstant(value) {
2325
2361
  return members.some(member => isPlainObject(member) && (member.since !== undefined
2326
2362
  || (Array.isArray(member.listening) && member.listening.some((entry) => isPlainObject(entry) && entry.since !== undefined))
2327
2363
  || (isPlainObject(member.shift) && member.shift.signedInAt !== undefined)
2328
- || (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)));
2329
2378
  }
2330
2379
  /** A running duration is counted from the provider's clock: a provider that publishes one declares timeCheck. */
2331
2380
  function requireClockInto(value, manifest, path, into) {
2332
2381
  if (!isPlainObject(manifest) || manifest.timeCheck === true || !carriesRunningInstant(value))
2333
2382
  return;
2334
- 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");
2335
2384
  }
2336
2385
  /** The agent's standing ask for the next call: since when. */
2337
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
@@ -372,7 +374,9 @@ Migration from the earlier spellings:
372
374
  | schedule on voice alone | `schedule` on every channel, under a manifest that declares `calendar` (`task.capability.calendar.required`), bounded by `settleMs` (`test.schedule.unsettled`) |
373
375
  | a forced break requesting breaks on the other providers | `setCapacity({ count: 0 })` on every other usable provider (`assertForcedBreakStopsTheRest`) |
374
376
  | end-forced-break on a break the platform imposed | refused: `team.command.endForcedBreak.provider`, `omni.break-forced-by-provider` |
375
- | ForcedBreak.expectedDurationMs | `expectedEndsInSeconds`: seconds left, restated (`break.forced.expectedEndsInSeconds`, `.expectedDurationMs.renamed`); the command's is `expectedDurationSeconds`, in the same unit |
377
+ | endBreak on a forced break, Resume offered on one | refused: `break.command.end.forced`, `omni.break-forced`; no Resume while `forced` stands; a sign-out keeps it, and the next session's snapshot carries it again |
378
+ | ForcedBreak.expectedDurationMs, then expectedEndsInSeconds | `endsInSeconds`: seconds left, restated, and the break is lifted when it runs out (`break.forced.endsInSeconds`, `.expectedDurationMs.renamed`, `.expectedEndsInSeconds.renamed`); the command's is `durationSeconds` (`team.command.expectedDurationSeconds.renamed`) |
379
+ | a forced break with no scope | `scope`: `team` to one end for all, or `agent`, counted while signed in (`break.forced.scope`, `break.forced.team.endsInSeconds`); `force-team-break` and `end-team-break` for the team |
376
380
  | MemberShift; the day on the lead's list alone | `Shift`, on `Snapshot.shift` and `shift-updated` for the agent, on `TeamMember.shift` for the lead |
377
381
  | TeamMember.listening as this lead's one entry | `MemberListening[]`, every lead's, each with `leadId` (`team.member.listening.leadId`, `.unique`, `.empty`, `.entry`, `.heard`) |
378
382
  | a member's history trimmed on the lead's list | the record whole, as the member's computer holds it |
@@ -499,11 +503,12 @@ entries, one per join. Order is enforced: an entry earlier than the one before i
499
503
  are two holds, the way Amazon Connect counts holds per contact, and two queues say which queue the
500
504
  call waited in. The agent sees consecutive entries of one step as one span: `historySpans(steps)`
501
505
  groups them, as Genesys Cloud keeps segments apart in its record and joins them in the agent's
502
- timeline. A provider never merges entries to get that look. **Intervals between steps are the agent application's to subtract**, never a
503
- total the provider adds: *time to offer*, from the call joining its queue to the agent's screen lighting
504
- up, is the `offered` entry's `at` minus the last `queued` entry's, and the ring is outside it.
505
- `queueSeconds` keeps the industry's meaning -- the whole wait until somebody answered -- and is not
506
- 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
507
512
  seconds, and nought is refused because it claims no time; a leg that happened is stated at the
508
513
  grain: rounded to the nearest second, and a leg that rounds to nought is stated as `1`, the error
509
514
  being under the contract's resolution, where dropping the entry would say the leg never happened.
@@ -539,10 +544,14 @@ If two distinct entries would collide under the history's `(step, at)` key, do n
539
544
  or combine them: report the representation conflict. No ambiguous event is silently accepted.
540
545
 
541
546
  **Interaction time is anchored, not restarted.** It runs from the
542
- `answered` step's `at` — from the task's first `in-progress` where the provider reports no
543
- 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
544
548
  duration is the `held` entry's `seconds`, and an agent computer that restarts its counter on resume is
545
- 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`.
546
555
 
547
556
  `muted` is there because the mute is the agent application's and never the provider's — see **The station is
548
557
  the agent application's** — so without a step the provider, which alone keeps the task's record, would have no
@@ -1152,5 +1161,6 @@ react rather than only display the message:
1152
1161
  | `omni.recording-unsettled` | A recording command the provider could not settle either way: a settled `failed`, never a promise left unresolved. See **Independent task recording** in `guide/voice.md`. |
1153
1162
  | `omni.on-hold` | Refused because the caller is on hold: the agent application's own Mute begun on a `paused` task, or `end-call` there. The agent application says resume first. The test expects this code on both (`test.recordStep.held`, `test.command.held`). |
1154
1163
  | `omni.break-forced-by-provider` | A lead asked to lift a break the platform imposed; the platform lifts its own. See **Forced breaks** in `guide/breaks.md`. |
1164
+ | `omni.break-forced` | The agent asked to end a break that is still forced. Only lifting it ends it, and signing out does not. See **Forced breaks** in `guide/breaks.md`. |
1155
1165
 
1156
1166
  They are published as `OMNI_FAILURE_CODES`.
package/guide/breaks.md CHANGED
@@ -81,8 +81,7 @@ mayAsk. Request eligibility remains distinct from approval; existing alwaysAvail
81
81
  exceptions are unchanged. Hosts and providers must update together.
82
82
 
83
83
  Migration: ImposedBreak is now `ForcedBreak`, and the former imposed field is now
84
- `BreakState.forced`. Diagnostic and harness coverage names use `break.forced`. The former agent-end prohibition
85
- has been removed: forced breaks also permit explicit agent resumption. Update hosts and providers together. The old field
84
+ `BreakState.forced`. Diagnostic and harness coverage names use `break.forced`. Update hosts and providers together. The old field
86
85
  is rejected, including when both spellings are sent; no compatibility alias is provided.
87
86
  The break policy value formerly named auto-approve is now `automatically-approved`.
88
87
  Requests are approved automatically; approval does not skip commitment or the prerequisites
@@ -101,16 +100,32 @@ The team break command formerly named place is now `force-break`. Hosts and prov
101
100
  adopt the new command together; place and the interim force spelling are rejected without aliases.
102
101
  The team break command formerly named release is now `end-forced-break`, and its diagnostic is
103
102
  `team.command.endForcedBreak`. The former release command and the interim end spelling are rejected without aliases.
104
- The agent’s `endBreak` now applies to forced breaks as well as requested breaks.
105
-
106
- `ForcedBreak` names who forced the break and may say how long it is expected to run yet, as
107
- `expectedEndsInSeconds`: whole seconds from the publication that carries it, restated on every
108
- publication, so every screen -- the agent's, reloaded or not, and every lead's -- counts down the
109
- same number from receipt (`break.forced.expectedEndsInSeconds`). The duration the lead asked for
110
- travels on the `force-break` command alone; the state says what is left, and drops the field once
111
- it has run out. The agent must explicitly resume when ready. The retired endsAutomatically and
112
- endsAt fields are rejected, including when an expectation is also provided. Who forced it is
113
- `by`, as **A forced break is the provider's act** below sets out.
103
+ Migration: the agent's `endBreak` no longer ends a forced break. It is refused before it is sent
104
+ (`break.command.end.forced`), and a provider that receives one answers `failed` with
105
+ `omni.break-forced`. The agent application no longer offers Resume on a forced break.
106
+ Migration: `ForcedBreak` now says whom it covers, as `scope` (`break.forced.scope`), and its
107
+ `expectedEndsInSeconds` is now `endsInSeconds`, since the break is lifted when it runs out
108
+ (`break.forced.expectedEndsInSeconds.renamed`). The `force-break` command's
109
+ `expectedDurationSeconds` is now `durationSeconds` (`team.command.expectedDurationSeconds.renamed`).
110
+
111
+ `ForcedBreak` names who forced the break, whom it covers, and how long it has left.
112
+
113
+ **There are two kinds, by `scope`.**
114
+
115
+ | `scope` | Covers | Its end | Signed-out time |
116
+ | --- | --- | --- | --- |
117
+ | `team` | The whole team, members who sign in while it runs included. A lead's `force-team-break`, or a break the platform schedules. | One end for everyone, always stated (`break.forced.team.endsInSeconds`). | Counts. A member who signs back in after the end finds no break. |
118
+ | `agent` | One agent. A lead's `force-break`, or a hold the platform puts on one agent. | A length, where one was given; without one it stands until lifted. | Does not count. The clock stops at sign-out and goes on at the next sign-in, so thirty minutes means thirty minutes signed in. |
119
+
120
+ `endsInSeconds` is how long the break has left: whole seconds from the publication that carries
121
+ it, restated on every publication, so every screen -- the agent's, reloaded or not, and every
122
+ lead's -- counts down the same number from receipt (`break.forced.endsInSeconds`). The length the
123
+ lead asked for travels on the command alone, as `durationSeconds`; the state says what is left.
124
+ **When it runs out, the provider lifts the break**, as a lead's `end-forced-break` would: it clears
125
+ `forced` and leaves an ordinary break, and the agent resumes when ready. The agent application
126
+ counts down but never acts on zero; the provider's publication lifts it. The retired
127
+ endsAutomatically and endsAt fields are rejected. Who forced it is `by`, as **A forced break is
128
+ the provider's act** below sets out.
114
129
 
115
130
  Omni resolves the name to show with `getUserDetails()`, so a provider sends the identifier and never
116
131
  a display name.
@@ -125,13 +140,40 @@ For example:
125
140
  ```ts
126
141
  forced: {
127
142
  by: "manager-1042",
128
- expectedEndsInSeconds: 600
143
+ scope: "agent",
144
+ endsInSeconds: 600
129
145
  }
130
146
  ```
131
147
 
132
- The agent application keeps **Resume** available for an agent on a forced break. The agent explicitly chooses
133
- Resume; the agent application sends `endBreak()` and follows the provider-confirmed state before resuming
134
- work. The expectation is whole seconds still to run, restated on every publication; omission
148
+ **The agent cannot end a forced break.** Forcing a break is how a lead or the platform takes the
149
+ agent off work, and a break the agent could end at will would take nobody off anything. So the
150
+ agent application offers no Resume while `forced` is present, and `endBreak()` on it is refused
151
+ before it is sent (`break.command.end.forced`). A provider that receives one answers `failed`
152
+ with `omni.break-forced` and leaves the break as it was.
153
+
154
+ **Only lifting ends it.** A lead's `end-forced-break` or `end-team-break`, the platform lifting
155
+ its own, or `endsInSeconds` running out clears `forced` and leaves an ordinary break. The agent
156
+ then resumes when ready, as from any break.
157
+
158
+ **Signing out does not end it.** The agent may sign out on a forced break, as at any time, but
159
+ that ends the session and not the break. The provider keeps the break, and the first snapshot of
160
+ the agent's next session carries it again while it stands, `on-break` with the same `forced`,
161
+ `activeReasonId` and what is left of `endsInSeconds` by its kind's clock. Without that, signing
162
+ out and straight back in would undo any forced break. While the agent is away, the lead's team
163
+ list shows them `signed-out`, not `on-break`: someone who has gone home is not on a break. The
164
+ break is held for their return, not shown.
165
+
166
+ `testAdapter` holds a provider to this when given `signInAgain`, a way to build the adapter again
167
+ that signs the same agent in, as a sign-in screen would. A run that ends with the agent on a
168
+ forced break signs out, signs in again, and reads the new session's snapshot. That snapshot
169
+ carries the same break, from the same person, on the same reason, or the run names it
170
+ (`test.signIn.forcedBreak`). Its time left is held to its kind's clock: a team break's ran on
171
+ while the agent was away, an agent's own stood still, and neither grows
172
+ (`test.signIn.endsInSeconds`). A sign-in that does not come back as the same agent is named too
173
+ (`test.signIn.session`). A run without `signInAgain`, or with no forced break to carry, lists
174
+ `break.forced.signIn` under `notTested`: the rule was not checked, and the result says so.
175
+
176
+ The expectation is whole seconds still to run, restated on every publication; omission
135
177
  means none was stated, or it has run out. Neither its reaching zero nor an overdue indication
136
178
  authorizes the agent application or provider to end the break, restore availability, or route
137
179
  work to the agent.
@@ -152,15 +194,19 @@ to lift: a lead's `end-forced-break` on it is refused before it is sent
152
194
  published state and waits for the agent's explicit Resume, even after reconnect. Historical
153
195
  attribution is not rewritten by clearing the current forced marker.
154
196
 
155
- The agent may explicitly resume either before or after the lead lifts the restriction. A lead
156
- command, timer, late snapshot or reconnect is never a substitute for that choice. Providers
197
+ The agent resumes only after the restriction is lifted, and only by their own choice. A lead
198
+ command, timer, late snapshot or reconnect is never a substitute for that choice. A stream that
199
+ takes a forced break straight back to `not-requested`, without clearing `forced` first, is
200
+ refused (`stream.breakState.forcedEnded`). Providers
157
201
  must correlate resumption to the authenticated agent's action; a state-only ordering validator
158
202
  cannot establish the cause of a transition. The usual multi-provider end/reconciliation flow
159
203
  still applies, and work resumes only on confirmed provider state.
160
204
 
161
- An agent application counts `expectedEndsInSeconds` down from receipt, on every publication that
205
+ An agent application counts `endsInSeconds` down from receipt, on every publication that
162
206
  carries it, and shows nothing of it where the provider sends none. It invents no start and no
163
- return time, and nothing acts on the number reaching zero.
207
+ return time, and the agent application does not act on the number reaching zero: the provider's
208
+ publication lifting the break does. It shows a `team` break as the team's and an `agent` break as
209
+ the agent's own.
164
210
 
165
211
  A break applies to the **agent**, not to one provider. When a provider forces one, Omni stops the
166
212
  agent everywhere else at once, and not by asking: it states `setCapacity({ count: 0 })` on every
@@ -271,10 +317,10 @@ request object only to the request method, and undefined to the other three.
271
317
  | `requestBreak` | `not-requested`; selected current reason code when codes exist; `canRequestBreak` or the selected reason's `alwaysAvailable` exception. Free text does not replace a code. |
272
318
  | `commitBreak` | `granted`, or already committed for an idempotent repeat. A later change to `canRequestBreak` does not revoke the grant. |
273
319
  | `cancelBreak` | `awaiting-approval` or `granted`. A concurrent commit winning still answers `omni.break-already-committed` and requires recovery. |
274
- | `endBreak` | `on-break` or `starting-after-task` during reconciliation; the agent may explicitly end a requested or forced break. |
320
+ | `endBreak` | `on-break` or `starting-after-task` during reconciliation, and not `forced` (`break.command.end.forced`): the agent ends a break they asked for, or one whose restriction was lifted. |
275
321
 
276
322
  Use `validateTeamCommand(request, context)` before every lead act, its context carrying the manifest's `levels` as the break check's does: the team feature switch, break
277
- decisions, forcing and ending a forced break, policy, and every act on a member's call. It requires
323
+ decisions, forcing and ending a forced break, for a member or the team, policy, and every act on a member's call. It requires
278
324
  the live `lead` capability the command needs and active transport, a current team member list for any command naming a
279
325
  member, and the target's complete break state for forcing/ending a break. Approve/deny requires an
280
326
  awaiting decision; forcing a break uses the target's reason codes; ending a forced break requires a
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`. |
@@ -129,8 +129,10 @@ assignment from the member alone.
129
129
  | `{ type: "lead-features", enabled }` | The team feature on or off. See **The lead switches the feature on and off** above. |
130
130
  | `{ type: "decide-break-request", memberId, decision, reason? }` | Settles one pending request. `decision` is `granted` or `denied`. A grant moves the member to `granted`; a denial ends the request and moves it directly to `not-requested`. |
131
131
  | `{ type: "set-break-policy", policy }` | `approval-required`, `automatically-approved`, or `requests-suspended`. |
132
- | `{ type: "force-break", memberId, reasonId?, reason?, expectedDurationSeconds? }` | Puts a member on a break they did not ask for. `reasonId` names a published `BreakReason.id` and is required whenever the provider publishes `reasons`; the member's forced break carries it as `activeReasonId`, so its kind is known. Optional `expectedDurationSeconds` is advisory; the resulting forced break publishes what is left of it as `expectedEndsInSeconds`, restated on every publication. |
133
- | `{ type: "end-forced-break", memberId }` | Asks the provider to lift a forced-break restriction a lead asked for, by clearing `BreakState.forced`; one the platform imposed is its own to lift (`team.command.endForcedBreak.provider`, `omni.break-forced-by-provider`). The committed break continues; only the agent resumes work. |
132
+ | `{ type: "force-break", memberId, reasonId?, reason?, durationSeconds? }` | Puts one member on a break they did not ask for, `scope: "agent"`. `reasonId` names a published `BreakReason.id` and is required whenever the provider publishes `reasons`; the member's forced break carries it as `activeReasonId`, so its kind is known. With `durationSeconds`, the break publishes what is left as `endsInSeconds`, counted only while the member is signed in, and is lifted when it runs out; without it, it stands until a lead lifts it. |
133
+ | `{ type: "force-team-break", reasonId?, reason?, durationSeconds }` | Puts the whole team on a break, `scope: "team"`, members who sign in while it runs included. `durationSeconds` is required (`team.command.durationSeconds`): one end for everyone, which runs on while a member is signed out. The provider lifts it for all when it runs out. |
134
+ | `{ type: "end-forced-break", memberId }` | Asks the provider to lift a forced-break restriction a lead asked for, by clearing `BreakState.forced`; one the platform imposed is its own to lift (`team.command.endForcedBreak.provider`, `omni.break-forced-by-provider`). The committed break continues; only the agent resumes work. It lifts a team break for this member alone. |
135
+ | `{ type: "end-team-break" }` | Lifts the team break for every member, as `end-forced-break` does for one. With no team break running it changes nothing. |
134
136
  | `{ type: "join", memberId, assignmentId? }` | Answers the member's request: the provider bridges the lead's channel into the call. See **Lead assist**. |
135
137
  | `{ type: "decline", memberId, assignmentId?, reason? }` | Refuses the member's request. |
136
138
  | `{ type: "listen", memberId, assignmentId? }` | The lead's channel joins the member's call unasked, in silence. See **Listening to a call**. |
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;
@@ -1026,9 +1026,12 @@ type BreakRequest = {
1026
1026
  reasonId?: string;
1027
1027
  };
1028
1028
 
1029
+ type ForcedBreakScope = "team" | "agent";
1030
+
1029
1031
  type ForcedBreak = {
1030
1032
  by: UserId | "provider";
1031
- expectedEndsInSeconds?: DurationSeconds;
1033
+ scope: ForcedBreakScope;
1034
+ endsInSeconds?: DurationSeconds;
1032
1035
  };
1033
1036
 
1034
1037
  type BreakState = {
@@ -1121,6 +1124,7 @@ type MemberTask<C extends Channel = Channel> = {
1121
1124
  completionMode?: CompletionMode;
1122
1125
  wrapAllowance?: DurationSeconds;
1123
1126
  wrapEndsInSeconds?: DurationSeconds;
1127
+ wrapOverSeconds?: DurationSeconds;
1124
1128
  } & (C extends "voice"
1125
1129
  ? { onCall?: OnCall[]; leadAssist?: TaskLeadAssist; takenOver?: TaskTakenOver; audio?: TaskAudioState }
1126
1130
  : { onCall?: never; leadAssist?: never; takenOver?: never; audio?: never });
@@ -1193,8 +1197,10 @@ type TeamCallCommand =
1193
1197
  type TeamBreakCommand =
1194
1198
  | { type: "decide-break-request"; memberId: UserId; decision: "granted" | "denied"; reason?: string }
1195
1199
  | { type: "set-break-policy"; policy: "approval-required" | "automatically-approved" | "requests-suspended" }
1196
- | { type: "force-break"; memberId: UserId; reasonId?: string; reason?: string; expectedDurationSeconds?: DurationSeconds }
1197
- | { type: "end-forced-break"; memberId: UserId };
1200
+ | { type: "force-break"; memberId: UserId; reasonId?: string; reason?: string; durationSeconds?: DurationSeconds }
1201
+ | { type: "force-team-break"; reasonId?: string; reason?: string; durationSeconds: DurationSeconds }
1202
+ | { type: "end-forced-break"; memberId: UserId }
1203
+ | { type: "end-team-break" };
1198
1204
 
1199
1205
  type TeamCommand = TeamFeatureCommand | TeamBreakCommand | TeamCallCommand | TeamPolicyCommand;
1200
1206
 
@@ -1390,6 +1396,7 @@ const OMNI_FAILURE_CODES = [
1390
1396
  "omni.recording-unsettled",
1391
1397
  "omni.on-hold",
1392
1398
  "omni.break-forced-by-provider",
1399
+ "omni.break-forced",
1393
1400
  ] as const;
1394
1401
  type OmniFailureCode = (typeof OMNI_FAILURE_CODES)[number];
1395
1402
  ```
@@ -1823,7 +1830,7 @@ compile time.
1823
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`. |
1824
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`. |
1825
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`. |
1826
- | `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**. |
1827
1834
  | `timestampAuthority` | Optional `"provider"`: provider timestamps are final; agent application instants are advisory. Omission makes no trust promise. |
1828
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`. |
1829
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`**. |
@@ -2571,7 +2578,7 @@ The current exceptions and their reasons are:
2571
2578
 
2572
2579
  | Case | Exception and reason |
2573
2580
  | --- | --- |
2574
- | 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. |
2575
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. |
2576
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. |
2577
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. |
@@ -2587,28 +2594,33 @@ source-measured durations where required; timestamp subtraction is not a substit
2587
2594
 
2588
2595
  Two screens watching the same agent -- their own computer, their lead's, a manager's on another floor
2589
2596
  -- must show the same numbers. Delay between them is fine; arithmetic that differs is not. So
2590
- nothing the agent computer shows is its own count, with one exception: the running duration of the active
2591
- task or call, which a screen times itself from the moment it saw the call begin -- the
2592
- `task-audio-started` on a softphone, the answer it sent on a hardphone -- and which two such
2593
- screens may therefore disagree on, since their clocks differ. That is the whole exception. A call
2594
- a screen found already up -- on a connect or reconnect snapshot, on a lead's list, after a reload
2595
- -- is counted from the provider's `answered` step's `at` against the provider's clock, like every
2596
- other duration, so a reloaded agent computer shows 12:40 beside the lead's 12:40 and not 0:05. And a leg
2597
- that has closed shows the provider's `seconds` on every screen, never the count a screen kept.
2598
- Everything else comes from the wire.
2599
-
2600
- Durations off the active call -- how long a member has been `on-break` from their `since`, how
2601
- 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
2602
2611
  clock, never the screen's. The agent computer keeps the latest provider instant it has received -- a
2603
2612
  snapshot's `providerTime`, an envelope's `occurredAt`, a `checkTime` result -- with the monotonic
2604
2613
  elapsed time since receipt, and renders every such duration from that; a sample older than
2605
2614
  `maxSampleAgeMs` is refreshed with `checkTime`. Without a usable sample the agent computer shows the instant
2606
2615
  and no count. A provider that publishes any of these instants therefore declares `timeCheck`
2607
2616
  (`manifest.timeCheck.required`) and states `providerTime` on every snapshot
2608
- (`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.
2609
2621
 
2610
2622
  **Seconds left are worked out at each publication.** `expiresInSeconds`, `previewEndsInSeconds`,
2611
- `wrapEndsInSeconds` and `expectedEndsInSeconds` are each the provider's arithmetic at the instant
2623
+ `wrapEndsInSeconds` and `endsInSeconds` are each the provider's arithmetic at the instant
2612
2624
  of the publication that carries them, never a value copied from an earlier one. A provider that
2613
2625
  builds the next publication by spreading the last one forward hands a reloaded agent computer a countdown
2614
2626
  already spent -- sixty seconds shown beside a lead's screen showing twenty -- and the stream
@@ -2616,7 +2628,11 @@ names it: between two publications of one countdown the value loses at least the
2616
2628
  provider's own clock says passed, within a second of rounding (`stream.countdown.copied`, on an
2617
2629
  update against the last publication, and on a snapshot from a provider with a clock against its
2618
2630
  `providerTime`). Under `agent-command` the wrap's value reaches `0` and stays there while the agent
2619
- 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`).
2620
2636
 
2621
2637
  **A deadline stated is a deadline kept.** The provider that says how long an offer has ends it
2622
2638
  `expired` when it runs out, and the test holds it to that: where the first offer carries
@@ -2853,7 +2869,7 @@ Normal order is `not-requested` → `awaiting-approval` → `granted` →
2853
2869
  `starting-after-task` → `on-break` → `not-requested`. Auto-approval may go directly to
2854
2870
  `granted`; a commit with no outstanding work may go directly to `on-break`. Denial/cancel
2855
2871
  returns a precommit request to `not-requested`; an explicit agent end returns a committed
2856
- break there. Same-state restatements are allowed. An evidenced forced break is the explicit
2872
+ break there, once it is not `forced`. Same-state restatements are allowed. An evidenced forced break is the explicit
2857
2873
  exception to requesting/granting, and must carry its forced actor/state. Neither skipped
2858
2874
  publication nor an agent application-local guess creates another exception. A later normal attempt starts
2859
2875
  from `not-requested`, never by regressing an active break into a request.
@@ -3100,10 +3116,14 @@ Whether two sessions declare the same capabilities, field by field — key order
3100
3116
  ### `historySpans(steps)`
3101
3117
 
3102
3118
  Groups a record's consecutive entries of one step into a `HistorySpan` each — `step`, the first
3103
- entry's `at`, `seconds` summed when every entry states one and absent when any does not, and the
3104
- `entries` themselves — so every agent application shows *Self-service · 30s* once where the
3105
- record has two self-service entries in a row. Only neighbours are grouped: a hold, an answer and
3106
- 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.
3107
3127
 
3108
3128
  ## Runtime validation
3109
3129
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xema/omni-protocol",
3
- "version": "0.1.133",
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",