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