@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 +3 -1
- package/dist/index.d.ts +49 -18
- package/dist/index.js +5 -5
- package/dist/testing.d.ts +9 -1
- package/dist/testing.js +150 -3
- package/dist/validation.js +63 -14
- package/guide/agent.md +23 -13
- package/guide/breaks.md +68 -22
- package/guide/lead.md +5 -3
- package/guide/phone.md +1 -1
- package/guide.md +46 -26
- package/package.json +1 -1
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
|
|
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
|
-
*
|
|
1400
|
-
*
|
|
1401
|
-
|
|
1402
|
-
|
|
1403
|
-
|
|
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
|
|
1409
|
-
*
|
|
1410
|
-
*
|
|
1411
|
-
*
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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`,
|
|
2183
|
-
*
|
|
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
|
-
|
|
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
|
-
//
|
|
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();
|
package/dist/validation.js
CHANGED
|
@@ -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}`, "
|
|
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.
|
|
1423
|
-
|
|
1424
|
-
|
|
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", "
|
|
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
|
-
|
|
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(
|
|
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(
|
|
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,
|
|
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.
|
|
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
|
-
|
|
|
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. **
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
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`
|
|
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
|
|
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
|
-
|
|
105
|
-
|
|
106
|
-
`
|
|
107
|
-
`
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
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
|
-
|
|
143
|
+
scope: "agent",
|
|
144
|
+
endsInSeconds: 600
|
|
129
145
|
}
|
|
130
146
|
```
|
|
131
147
|
|
|
132
|
-
The agent
|
|
133
|
-
|
|
134
|
-
|
|
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
|
|
156
|
-
command, timer, late snapshot or reconnect is never a substitute for that choice.
|
|
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 `
|
|
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
|
|
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
|
|
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?,
|
|
133
|
-
| `{ type: "
|
|
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
|
|
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
|
-
|
|
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;
|
|
1197
|
-
| { type: "
|
|
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
|
|
2591
|
-
|
|
2592
|
-
|
|
2593
|
-
|
|
2594
|
-
|
|
2595
|
-
|
|
2596
|
-
|
|
2597
|
-
|
|
2598
|
-
Everything else comes from the
|
|
2599
|
-
|
|
2600
|
-
|
|
2601
|
-
|
|
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 `
|
|
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
|
|
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`, `
|
|
3104
|
-
|
|
3105
|
-
|
|
3106
|
-
|
|
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
|
|