@xema/omni-protocol 0.1.133 → 0.1.134
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 +2 -1
- package/dist/index.d.ts +36 -13
- package/dist/index.js +5 -0
- package/dist/testing.d.ts +9 -1
- package/dist/testing.js +133 -2
- package/dist/validation.js +24 -11
- package/guide/agent.md +4 -1
- package/guide/breaks.md +68 -22
- package/guide/lead.md +4 -2
- package/guide.md +11 -5
- package/package.json +1 -1
package/GLOSSARY.md
CHANGED
|
@@ -83,7 +83,8 @@ hands only through routing or a lead's take-over.
|
|
|
83
83
|
| --- | --- | --- |
|
|
84
84
|
| **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
85
|
| **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*. |
|
|
86
|
+
| **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*. |
|
|
87
|
+
| **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
88
|
| **Next call** | The agent says they are ready for another call before this one ends. | *Request next*, *ready for next*. |
|
|
88
89
|
| **Lined up** | A call waiting in this agent's own queue, held for them. | *Agent queue* or *personal queue* (Amazon Connect), *direct routing*. |
|
|
89
90
|
| **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
|
@@ -380,7 +380,9 @@ export declare const LEAD_COMMAND_CAPABILITY: {
|
|
|
380
380
|
readonly "decide-break-request": "decideBreakRequest";
|
|
381
381
|
readonly "set-break-policy": "setBreakPolicy";
|
|
382
382
|
readonly "force-break": "forceBreak";
|
|
383
|
+
readonly "force-team-break": "forceBreak";
|
|
383
384
|
readonly "end-forced-break": "endForcedBreak";
|
|
385
|
+
readonly "end-team-break": "endForcedBreak";
|
|
384
386
|
readonly "set-policy": "setPolicy";
|
|
385
387
|
};
|
|
386
388
|
/**
|
|
@@ -1396,21 +1398,31 @@ export interface BreakRequest {
|
|
|
1396
1398
|
reasonId?: string;
|
|
1397
1399
|
}
|
|
1398
1400
|
/**
|
|
1399
|
-
*
|
|
1400
|
-
*
|
|
1401
|
-
|
|
1402
|
-
|
|
1403
|
-
|
|
1401
|
+
* Whom a forced break covers. `team`: the whole team, to one end for everyone, its clock running
|
|
1402
|
+
* while a member is signed out. `agent`: one agent, its clock counting only while they are signed in.
|
|
1403
|
+
*/
|
|
1404
|
+
export type ForcedBreakScope = "team" | "agent";
|
|
1405
|
+
export declare const FORCED_BREAK_SCOPES: readonly ["team", "agent"];
|
|
1406
|
+
/**
|
|
1407
|
+
* A break forced on the agent, which the agent cannot end. Signing out ends the session, not the
|
|
1408
|
+
* break: the next session's snapshot carries it again while it stands. It is lifted by a lead, by
|
|
1409
|
+
* the platform, or by its time running out; lifting clears `forced` and leaves an ordinary break
|
|
1410
|
+
* the agent ends when ready. A lead's `force-break` or `force-team-break` is a command to the
|
|
1411
|
+
* provider, which forces the break: `by` names the lead who asked it to, or `provider` where the
|
|
1412
|
+
* platform itself did, on its own rule or a schedule. The agent sees who, a person is named only
|
|
1413
|
+
* when there is one, and a break the platform imposed is the platform's to lift: a lead's
|
|
1414
|
+
* `end-forced-break` on it fails with `omni.break-forced-by-provider`.
|
|
1404
1415
|
*/
|
|
1405
1416
|
export type ForcedBreak = {
|
|
1406
1417
|
by: UserId | "provider";
|
|
1418
|
+
scope: ForcedBreakScope;
|
|
1407
1419
|
/**
|
|
1408
|
-
* How long the break
|
|
1409
|
-
*
|
|
1410
|
-
*
|
|
1411
|
-
*
|
|
1420
|
+
* How long the break has left, in whole seconds from this publication, restated on every
|
|
1421
|
+
* publication that carries it so every screen counts down the same number from receipt. When it
|
|
1422
|
+
* runs out the provider lifts the break. Required on a `team` break; absent on an `agent` break
|
|
1423
|
+
* that stands until a lead lifts it.
|
|
1412
1424
|
*/
|
|
1413
|
-
|
|
1425
|
+
endsInSeconds?: DurationSeconds;
|
|
1414
1426
|
};
|
|
1415
1427
|
export interface BreakState {
|
|
1416
1428
|
status: BreakStatus;
|
|
@@ -1699,18 +1711,29 @@ export type TeamBreakCommand = {
|
|
|
1699
1711
|
type: "set-break-policy";
|
|
1700
1712
|
policy: "approval-required" | "automatically-approved" | "requests-suspended";
|
|
1701
1713
|
}
|
|
1702
|
-
/** `reason` text is optional. `reasonId` selects a published `BreakReason.id`, required when reasons are published; the forced break carries it as `activeReasonId`. */
|
|
1714
|
+
/** `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
1715
|
| {
|
|
1704
1716
|
type: "force-break";
|
|
1705
1717
|
memberId: UserId;
|
|
1706
1718
|
reasonId?: string;
|
|
1707
1719
|
reason?: string;
|
|
1708
|
-
|
|
1720
|
+
durationSeconds?: DurationSeconds;
|
|
1721
|
+
}
|
|
1722
|
+
/** The whole team, members who sign in while it runs included, to one end `durationSeconds` from now. */
|
|
1723
|
+
| {
|
|
1724
|
+
type: "force-team-break";
|
|
1725
|
+
reasonId?: string;
|
|
1726
|
+
reason?: string;
|
|
1727
|
+
durationSeconds: DurationSeconds;
|
|
1709
1728
|
}
|
|
1710
1729
|
/** Clears forced metadata only; preserves the committed break until the agent explicitly resumes. */
|
|
1711
1730
|
| {
|
|
1712
1731
|
type: "end-forced-break";
|
|
1713
1732
|
memberId: UserId;
|
|
1733
|
+
}
|
|
1734
|
+
/** Lifts the team break for every member, as `end-forced-break` does for one. */
|
|
1735
|
+
| {
|
|
1736
|
+
type: "end-team-break";
|
|
1714
1737
|
};
|
|
1715
1738
|
/** Every lead act, as `execute` takes a `TaskCommand`: discriminated by `type`. */
|
|
1716
1739
|
export type TeamCommand = TeamFeatureCommand | TeamBreakCommand | TeamCallCommand | TeamPolicyCommand;
|
|
@@ -2005,7 +2028,7 @@ export interface ProviderEventEnvelope<C extends Channel = Channel> {
|
|
|
2005
2028
|
occurredAt: IsoTimestamp;
|
|
2006
2029
|
event: ProviderEvent<C>;
|
|
2007
2030
|
}
|
|
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"];
|
|
2031
|
+
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
2032
|
export type OmniFailureCode = (typeof OMNI_FAILURE_CODES)[number];
|
|
2010
2033
|
/**
|
|
2011
2034
|
* What the host refused, told to the adapter that published it: a snapshot the host would not
|
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`.
|
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;
|
|
@@ -2293,8 +2388,8 @@ async function testOneCall(call) {
|
|
|
2293
2388
|
// A request goes not-requested -> awaiting-approval | granted; a commit goes granted ->
|
|
2294
2389
|
// starting-after-task | on-break; work ending goes starting-after-task -> on-break; a denial,
|
|
2295
2390
|
// 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
|
-
//
|
|
2391
|
+
// preserves the committed break. A forced break arrives on-break with `forced`, and never goes
|
|
2392
|
+
// back to not-requested while it is forced. Nothing else is a move the guide describes.
|
|
2298
2393
|
/** What a stream has said about the agent's break, and the moves it may not make. */
|
|
2299
2394
|
/**
|
|
2300
2395
|
* The team as the events left it: whole on `team-updated` and on any snapshot carrying one, then
|
|
@@ -2417,6 +2512,42 @@ export function assertAudioFollowsTheTask(envelopes, snapshot) {
|
|
|
2417
2512
|
envelopes.forEach((envelope, index) => found.push(...stream.apply(envelope, `envelopes[${index}]`)));
|
|
2418
2513
|
assertNoViolations(found, "The audio follows the task");
|
|
2419
2514
|
}
|
|
2515
|
+
/**
|
|
2516
|
+
* The break the agent signed out on, held to the one the next session carries: the same forced
|
|
2517
|
+
* break, from the same person, on the same reason, with what is left of its time by its kind's
|
|
2518
|
+
* clock -- a team break's ran on while the agent was away, an agent's own stood still. Each bound
|
|
2519
|
+
* allows a second of rounding at either end.
|
|
2520
|
+
*/
|
|
2521
|
+
function forcedBreakCarried(before, forced, after, at) {
|
|
2522
|
+
const found = [];
|
|
2523
|
+
const left = typeof forced.endsInSeconds === "number" ? forced.endsInSeconds : undefined;
|
|
2524
|
+
const whole = Math.floor((at.gotAt - at.readAt) / 1000);
|
|
2525
|
+
// A team break that could have run out while the agent was away may rightly be gone.
|
|
2526
|
+
if (forced.scope === "team" && left !== undefined && left - whole <= 1)
|
|
2527
|
+
return found;
|
|
2528
|
+
ruleTested("test.signIn.forcedBreak");
|
|
2529
|
+
const now = isRecord(after) && isRecord(after.break) ? after.break : undefined;
|
|
2530
|
+
const carried = now !== undefined && isRecord(now.forced) ? now.forced : undefined;
|
|
2531
|
+
if (carried === undefined || !(now.status === "on-break" || now.status === "starting-after-task")
|
|
2532
|
+
|| carried.by !== forced.by || carried.scope !== forced.scope || now.activeReasonId !== before.activeReasonId) {
|
|
2533
|
+
found.push({ rule: "test.signIn.forcedBreak", path: "test.signIn.snapshot.break",
|
|
2534
|
+
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` });
|
|
2535
|
+
return found;
|
|
2536
|
+
}
|
|
2537
|
+
ruleTested("test.signIn.endsInSeconds");
|
|
2538
|
+
const leftNow = typeof carried.endsInSeconds === "number" ? carried.endsInSeconds : undefined;
|
|
2539
|
+
const signedIn = Math.ceil(((at.outAt - at.readAt) + (at.gotAt - at.inAt)) / 1000);
|
|
2540
|
+
const fault = left === undefined
|
|
2541
|
+
? (leftNow === undefined ? undefined : `it had no end and now ends in ${leftNow}s`)
|
|
2542
|
+
: leftNow === undefined ? `it had ${left}s left and now states none`
|
|
2543
|
+
: leftNow > left ? `it had ${left}s left and now has ${leftNow}s: time left never grows`
|
|
2544
|
+
: 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`
|
|
2545
|
+
: 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`
|
|
2546
|
+
: undefined;
|
|
2547
|
+
if (fault !== undefined)
|
|
2548
|
+
found.push({ rule: "test.signIn.endsInSeconds", path: "test.signIn.snapshot.break.forced.endsInSeconds", message: fault });
|
|
2549
|
+
return found;
|
|
2550
|
+
}
|
|
2420
2551
|
/** The store as handed to the adapter, and the keys it holds at any moment, seen rather than reported. */
|
|
2421
2552
|
function watchStore(store) {
|
|
2422
2553
|
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") {
|
|
@@ -1417,11 +1417,14 @@ function validateForcedBreak(value, path, into) {
|
|
|
1417
1417
|
}
|
|
1418
1418
|
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
1419
|
for (const field of ["endsAutomatically", "endsAt"]) {
|
|
1420
|
-
into.require(!Object.hasOwn(value, field), "break.forced.manualResume", `${path}.${field}`, "
|
|
1420
|
+
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
1421
|
}
|
|
1422
|
-
into.
|
|
1423
|
-
|
|
1424
|
-
|
|
1422
|
+
into.oneOf(value.scope, FORCED_BREAK_SCOPES, "break.forced.scope", `${path}.scope`);
|
|
1423
|
+
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");
|
|
1424
|
+
into.require(!Object.hasOwn(value, "expectedEndsInSeconds"), "break.forced.expectedEndsInSeconds.renamed", `${path}.expectedEndsInSeconds`, "expectedEndsInSeconds is now endsInSeconds: the break is lifted when it runs out");
|
|
1425
|
+
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");
|
|
1426
|
+
if (value.endsInSeconds !== undefined)
|
|
1427
|
+
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
1428
|
}
|
|
1426
1429
|
/** Checks break status against the full currently retained task set, after a transaction. */
|
|
1427
1430
|
export function validateBreakStatus(state, tasks, path = "snapshot") {
|
|
@@ -1475,7 +1478,8 @@ export function validateTeamCommand(request, context, path = "teamCommand") {
|
|
|
1475
1478
|
const allowed = {
|
|
1476
1479
|
"lead-features": ["type", "enabled"],
|
|
1477
1480
|
"decide-break-request": ["type", "memberId", "decision", "reason"], "set-break-policy": ["type", "policy"],
|
|
1478
|
-
"force-break": ["type", "memberId", "reasonId", "reason", "
|
|
1481
|
+
"force-break": ["type", "memberId", "reasonId", "reason", "durationSeconds"], "end-forced-break": ["type", "memberId"],
|
|
1482
|
+
"force-team-break": ["type", "reasonId", "reason", "durationSeconds"], "end-team-break": ["type"],
|
|
1479
1483
|
join: member, decline: [...member, "reason"], listen: member, coach: member, "join-call": member, leave: member, "take-over-call": member,
|
|
1480
1484
|
"set-policy": ["type", "capability", "setting"],
|
|
1481
1485
|
};
|
|
@@ -1494,6 +1498,16 @@ export function validateTeamCommand(request, context, path = "teamCommand") {
|
|
|
1494
1498
|
into.require(key === "command", "team.request.field", `${path}.${key}`, "only command is supported");
|
|
1495
1499
|
for (const key of Object.keys(command))
|
|
1496
1500
|
into.require(fields.includes(key), "team.command.field", `${path}.${key}`, "field is not supported for this command");
|
|
1501
|
+
if (command.type === "force-break" || command.type === "force-team-break") {
|
|
1502
|
+
into.require(!Object.hasOwn(command, "expectedDurationSeconds"), "team.command.expectedDurationSeconds.renamed", `${path}.expectedDurationSeconds`, "expectedDurationSeconds is now durationSeconds: the break is lifted when it runs out");
|
|
1503
|
+
if (command.durationSeconds !== undefined || command.type === "force-team-break")
|
|
1504
|
+
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");
|
|
1505
|
+
if (command.reasonId !== undefined)
|
|
1506
|
+
into.filled(command.reasonId, "team.command.reasonId", path, "reasonId must not be empty");
|
|
1507
|
+
}
|
|
1508
|
+
// A team break names no member: the provider rechecks its reason codes and whether one is running.
|
|
1509
|
+
if (command.type === "force-team-break" || command.type === "end-team-break")
|
|
1510
|
+
return into.violations;
|
|
1497
1511
|
if (command.reason !== undefined)
|
|
1498
1512
|
into.filled(command.reason, "team.command.reason", path, "reason must not be empty");
|
|
1499
1513
|
if (command.type === "lead-features") {
|
|
@@ -1536,10 +1550,6 @@ export function validateTeamCommand(request, context, path = "teamCommand") {
|
|
|
1536
1550
|
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
1551
|
}
|
|
1538
1552
|
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
1553
|
const reasons = Array.isArray(state.reasons) ? state.reasons : [];
|
|
1544
1554
|
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
1555
|
}
|
|
@@ -1605,7 +1615,7 @@ export function validateBreakCommand(method, request, state, context, path = "br
|
|
|
1605
1615
|
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
1616
|
if (method === "endBreak") {
|
|
1607
1617
|
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
|
-
|
|
1618
|
+
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
1619
|
}
|
|
1610
1620
|
}
|
|
1611
1621
|
return into.violations;
|
|
@@ -1629,6 +1639,9 @@ export function validateBreakTransition(before, after, path = "break") {
|
|
|
1629
1639
|
if (committed && (from === "not-requested" || from === "awaiting-approval") && after.forced === undefined) {
|
|
1630
1640
|
into.add("stream.breakState.commitBeforeGrant", `${path}.after.status`, `${to} follows a commit, and a commit follows granted; the break stood at ${from}`);
|
|
1631
1641
|
}
|
|
1642
|
+
if (before.forced !== undefined && from !== "not-requested" && to === "not-requested") {
|
|
1643
|
+
into.add("stream.breakState.forcedEnded", `${path}.after.status`, "a forced break is lifted first, clearing forced, before the break can end");
|
|
1644
|
+
}
|
|
1632
1645
|
const backwards = (from === "on-break" && (to === "awaiting-approval" || to === "granted" || to === "starting-after-task")) ||
|
|
1633
1646
|
(from === "starting-after-task" && (to === "awaiting-approval" || to === "granted")) ||
|
|
1634
1647
|
(from === "granted" && to === "awaiting-approval");
|
package/guide/agent.md
CHANGED
|
@@ -372,7 +372,9 @@ Migration from the earlier spellings:
|
|
|
372
372
|
| 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
373
|
| a forced break requesting breaks on the other providers | `setCapacity({ count: 0 })` on every other usable provider (`assertForcedBreakStopsTheRest`) |
|
|
374
374
|
| end-forced-break on a break the platform imposed | refused: `team.command.endForcedBreak.provider`, `omni.break-forced-by-provider` |
|
|
375
|
-
|
|
|
375
|
+
| 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 |
|
|
376
|
+
| 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`) |
|
|
377
|
+
| 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
378
|
| 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
379
|
| TeamMember.listening as this lead's one entry | `MemberListening[]`, every lead's, each with `leadId` (`team.member.listening.leadId`, `.unique`, `.empty`, `.entry`, `.heard`) |
|
|
378
380
|
| a member's history trimmed on the lead's list | the record whole, as the member's computer holds it |
|
|
@@ -1152,5 +1154,6 @@ react rather than only display the message:
|
|
|
1152
1154
|
| `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
1155
|
| `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
1156
|
| `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`. |
|
|
1157
|
+
| `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
1158
|
|
|
1156
1159
|
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
|
@@ -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.md
CHANGED
|
@@ -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 = {
|
|
@@ -1193,8 +1196,10 @@ type TeamCallCommand =
|
|
|
1193
1196
|
type TeamBreakCommand =
|
|
1194
1197
|
| { type: "decide-break-request"; memberId: UserId; decision: "granted" | "denied"; reason?: string }
|
|
1195
1198
|
| { type: "set-break-policy"; policy: "approval-required" | "automatically-approved" | "requests-suspended" }
|
|
1196
|
-
| { type: "force-break"; memberId: UserId; reasonId?: string; reason?: string;
|
|
1197
|
-
| { type: "
|
|
1199
|
+
| { type: "force-break"; memberId: UserId; reasonId?: string; reason?: string; durationSeconds?: DurationSeconds }
|
|
1200
|
+
| { type: "force-team-break"; reasonId?: string; reason?: string; durationSeconds: DurationSeconds }
|
|
1201
|
+
| { type: "end-forced-break"; memberId: UserId }
|
|
1202
|
+
| { type: "end-team-break" };
|
|
1198
1203
|
|
|
1199
1204
|
type TeamCommand = TeamFeatureCommand | TeamBreakCommand | TeamCallCommand | TeamPolicyCommand;
|
|
1200
1205
|
|
|
@@ -1390,6 +1395,7 @@ const OMNI_FAILURE_CODES = [
|
|
|
1390
1395
|
"omni.recording-unsettled",
|
|
1391
1396
|
"omni.on-hold",
|
|
1392
1397
|
"omni.break-forced-by-provider",
|
|
1398
|
+
"omni.break-forced",
|
|
1393
1399
|
] as const;
|
|
1394
1400
|
type OmniFailureCode = (typeof OMNI_FAILURE_CODES)[number];
|
|
1395
1401
|
```
|
|
@@ -2608,7 +2614,7 @@ and no count. A provider that publishes any of these instants therefore declares
|
|
|
2608
2614
|
(`snapshot.providerTime`). Two screens then differ by their delay and nothing else.
|
|
2609
2615
|
|
|
2610
2616
|
**Seconds left are worked out at each publication.** `expiresInSeconds`, `previewEndsInSeconds`,
|
|
2611
|
-
`wrapEndsInSeconds` and `
|
|
2617
|
+
`wrapEndsInSeconds` and `endsInSeconds` are each the provider's arithmetic at the instant
|
|
2612
2618
|
of the publication that carries them, never a value copied from an earlier one. A provider that
|
|
2613
2619
|
builds the next publication by spreading the last one forward hands a reloaded agent computer a countdown
|
|
2614
2620
|
already spent -- sixty seconds shown beside a lead's screen showing twenty -- and the stream
|
|
@@ -2853,7 +2859,7 @@ Normal order is `not-requested` → `awaiting-approval` → `granted` →
|
|
|
2853
2859
|
`starting-after-task` → `on-break` → `not-requested`. Auto-approval may go directly to
|
|
2854
2860
|
`granted`; a commit with no outstanding work may go directly to `on-break`. Denial/cancel
|
|
2855
2861
|
returns a precommit request to `not-requested`; an explicit agent end returns a committed
|
|
2856
|
-
break there
|
|
2862
|
+
break there, once it is not `forced`. Same-state restatements are allowed. An evidenced forced break is the explicit
|
|
2857
2863
|
exception to requesting/granting, and must carry its forced actor/state. Neither skipped
|
|
2858
2864
|
publication nor an agent application-local guess creates another exception. A later normal attempt starts
|
|
2859
2865
|
from `not-requested`, never by regressing an active break into a request.
|