@xema/omni-protocol 0.1.128 → 0.1.130

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.
@@ -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, SHIFT_EVENT_KINDS, 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, DEFAULT_LEVELS, effectiveLevels, } from "./index.js";
12
+ import { RECORDING_ACTIONS, LEAD_COMMAND_CAPABILITY, SHIFT_EVENT_KINDS, 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") {
@@ -58,7 +58,7 @@ const TEAM_AVAILABILITIES = membersOf({
58
58
  ready: true, "on-task": true, "on-break": true, elsewhere: true, "signed-out": true,
59
59
  });
60
60
  const HISTORY_STEPS = membersOf({
61
- arrived: true, "self-service": true, queued: true, offered: true, answered: true, held: true, muted: true, transferred: true, conferenced: true, unanswered: true,
61
+ arrived: true, "self-service": true, queued: true, offered: true, answered: true, held: true, muted: true, transferred: true, added: true, unanswered: true,
62
62
  "callback-requested": true,
63
63
  });
64
64
  const CUSTOM_UI_CONTROLS = membersOf({ button: true, toggle: true, "menu-item": true });
@@ -72,14 +72,15 @@ const DIAL_DESTINATION_POLICIES = membersOf({ "contacts-only": true, "any-number
72
72
  const DIAL_OUTCOMES = membersOf({ answered: true, busy: true, "no-answer": true, unreachable: true, rejected: true, cancelled: true, unexplained: true });
73
73
  /** The outcomes that name a cause. `unexplained` is declarable only beside one of these. */
74
74
  const EXPLAINED_FAILURES = ["busy", "no-answer", "unreachable", "rejected", "cancelled"];
75
- const ON_CALL_ROLES = membersOf({ party: true, agent: true, conferenced: true });
75
+ const ON_CALL_ROLES = membersOf({ party: true, agent: true, added: true });
76
76
  const ON_CALL_STAGES = membersOf({ ringing: true, joined: true });
77
77
  /** The task capabilities under which a command dials, and so need the manifest to say how a dial ends. */
78
- const DIALLING_CAPABILITIES = ["connectBack", "conference"];
78
+ const DIALLING_CAPABILITIES = ["connectBack", "addToCall"];
79
79
  const SNAPSHOT_REASONS = membersOf({
80
80
  reconnected: true, "provider-requested": true,
81
81
  });
82
82
  const SESSION_CAPABILITIES = membersOf({ breaks: true, lead: true, preferences: true, nextCall: true });
83
+ const LEAD_CAPABILITY_NAMES = Object.values(LEAD_COMMAND_CAPABILITY);
83
84
  const MEMBER_BREAKS = membersOf({
84
85
  "awaiting-approval": true, granted: true, "starting-after-task": true,
85
86
  });
@@ -101,7 +102,7 @@ const ISOLATION_SCHEME_VALUES = Object.values(BROWSER_ISOLATION_SCHEMES);
101
102
  const TASK_CAPABILITIES = {
102
103
  voice: membersOf({
103
104
  browsers: true, outcomes: true, custom: true, decline: true, hold: true,
104
- endCall: true, terminateCall: true, connectBack: true, schedule: true, leadAssist: true, conference: true, recording: true,
105
+ endCall: true, terminateCall: true, connectBack: true, schedule: true, leadAssist: true, addToCall: true, recording: true,
105
106
  }),
106
107
  chat: membersOf({ browsers: true, outcomes: true, custom: true, decline: true, hold: true, schedule: true }),
107
108
  email: membersOf({ browsers: true, outcomes: true, custom: true, decline: true, schedule: true }),
@@ -217,9 +218,9 @@ function validateAttributes(value, path, into) {
217
218
  });
218
219
  }
219
220
  /** Every field is optional, so this checks what is present rather than what is missing. */
220
- export function validateContact(contact, path = "contact") {
221
+ export function validateContact(contact, levels, path = "contact") {
221
222
  const into = new Collector();
222
- validateContactInto(contact, path, into);
223
+ validateContactInto(contact, path, into, levels);
223
224
  return into.violations;
224
225
  }
225
226
  function validateContactInto(contact, path, into, levels) {
@@ -238,9 +239,9 @@ function validateContactInto(contact, path, into, levels) {
238
239
  }
239
240
  validateAttributes(contact.attributes, `${path}.attributes`, into);
240
241
  }
241
- export function validateScheduledActivity(activity, path = "scheduledActivity") {
242
+ export function validateScheduledActivity(activity, levels, path = "scheduledActivity") {
242
243
  const into = new Collector();
243
- validateScheduledActivityInto(activity, path, into);
244
+ validateScheduledActivityInto(activity, path, into, levels);
244
245
  return into.violations;
245
246
  }
246
247
  function validateScheduledActivityInto(activity, path, into, levels) {
@@ -378,7 +379,7 @@ function validatePhones(manifest, path, into) {
378
379
  }
379
380
  }
380
381
  /**
381
- * The host's choice of phone for a login, held to the manifest: one the platform listed, required
382
+ * The host's choice of phone for a session, held to the manifest: one the platform listed, required
382
383
  * on voice, absent elsewhere.
383
384
  */
384
385
  export function validatePhone(value, manifest, path = "context.phone") {
@@ -386,10 +387,10 @@ export function validatePhone(value, manifest, path = "context.phone") {
386
387
  const channel = isPlainObject(manifest) ? manifest.channel : undefined;
387
388
  const phones = isPlainObject(manifest) && Array.isArray(manifest.phones) ? manifest.phones : [];
388
389
  if (channel !== "voice") {
389
- into.require(value === undefined, "context.phone.unexpected", path, `a ${describeValue(channel)} login has no call to hear and chooses no phone`);
390
+ into.require(value === undefined, "context.phone.unexpected", path, `a ${describeValue(channel)} session has no call to hear and chooses no phone`);
390
391
  return into.violations;
391
392
  }
392
- if (!into.require(value !== undefined, "context.phone.required", path, "a voice login says how the agent hears the call: one of the manifest's phones"))
393
+ if (!into.require(value !== undefined, "context.phone.required", path, "a voice session says how the agent hears the call: one of the manifest's phones"))
393
394
  return into.violations;
394
395
  if (into.oneOf(value, PHONES, "context.phone", path)) {
395
396
  into.require(phones.includes(value), "context.phone.unsupported", path, `the host chose ${describeValue(value)} and the manifest lists ${phones.length === 0 ? "no phones" : phones.map(describeValue).join(", ")}`);
@@ -408,25 +409,25 @@ function manifestCalendar(manifest) {
408
409
  export function validateProviderTimeEstimate(value, scope, path = "estimate") {
409
410
  const into = new Collector();
410
411
  if (!isPlainObject(scope)) {
411
- into.add("timeEstimate.scope", path, "provider/login scope is required");
412
+ into.add("timeEstimate.scope", path, "provider/session scope is required");
412
413
  return into.violations;
413
414
  }
414
- for (const key of ["providerId", "loginId"])
415
- into.filled(scope[key], "timeEstimate.scope", `scope.${key}`, "explicit provider/login scope is required");
415
+ for (const key of ["providerId", "sessionId"])
416
+ into.filled(scope[key], "timeEstimate.scope", `scope.${key}`, "explicit provider/session scope is required");
416
417
  if (value === undefined)
417
418
  return into.violations;
418
419
  if (!isPlainObject(value)) {
419
420
  into.add("timeEstimate.shape", path, "expected a provider time estimate or undefined");
420
421
  return into.violations;
421
422
  }
422
- for (const key of ["providerId", "loginId"])
423
- into.require(value[key] === scope[key], "timeEstimate.scope", `${path}.${key}`, "estimate must match the requested provider/login");
423
+ for (const key of ["providerId", "sessionId"])
424
+ into.require(value[key] === scope[key], "timeEstimate.scope", `${path}.${key}`, "estimate must match the requested provider/session");
424
425
  into.timestamp(value.at, "timeEstimate.at", `${path}.at`);
425
426
  into.filled(value.clockId, "timeEstimate.clock", `${path}.clockId`, "estimate must identify its clock domain");
426
427
  if (value.uncertaintyMs !== undefined)
427
428
  into.require(typeof value.uncertaintyMs === "number" && Number.isFinite(value.uncertaintyMs) && value.uncertaintyMs >= 0, "timeEstimate.uncertainty", `${path}.uncertaintyMs`, "estimated uncertainty must be finite and nonnegative");
428
429
  for (const key of Object.keys(value))
429
- into.require(["providerId", "loginId", "at", "clockId", "uncertaintyMs"].includes(key), "timeEstimate.field", `${path}.${key}`, "unsupported estimate field");
430
+ into.require(["providerId", "sessionId", "at", "clockId", "uncertaintyMs"].includes(key), "timeEstimate.field", `${path}.${key}`, "unsupported estimate field");
430
431
  return into.violations;
431
432
  }
432
433
  /** Validate host-local periodic clock-check configuration. Omission disables checking. */
@@ -459,21 +460,21 @@ export function validateProviderTimeCheckRequest(value, path = "request") {
459
460
  return into.violations;
460
461
  }
461
462
  /** Checks response shape/correlation, not source-clock accuracy, round-trip delay or freshness. */
462
- export function validateProviderTimeCheckResult(value, request, loginId, path = "result") {
463
+ export function validateProviderTimeCheckResult(value, request, sessionId, path = "result") {
463
464
  const into = new Collector();
464
465
  into.violations.push(...validateProviderTimeCheckRequest(request));
465
- into.filled(loginId, "timeCheck.login", "loginId", "current authenticated login is required");
466
+ into.filled(sessionId, "timeCheck.session", "sessionId", "current authenticated session is required");
466
467
  if (!isPlainObject(value)) {
467
468
  into.add("timeCheck.result.shape", path, "expected a clock-check response");
468
469
  return into.violations;
469
470
  }
470
471
  into.filled(value.requestId, "timeCheck.result.id", `${path}.requestId`, "response must identify its request");
471
472
  into.require(isPlainObject(request) && value.requestId === request.requestId, "timeCheck.result.request", `${path}.requestId`, "response must match the outstanding check");
472
- into.require(value.loginId === loginId, "timeCheck.result.login", `${path}.loginId`, "response belongs to the current login");
473
+ into.require(value.sessionId === sessionId, "timeCheck.result.session", `${path}.sessionId`, "response belongs to the current session");
473
474
  into.filled(value.clockId, "timeCheck.result.clock", `${path}.clockId`, "provider clock domain/incarnation is required");
474
475
  into.timestamp(value.providerTime, "timeCheck.result.time", `${path}.providerTime`);
475
476
  for (const key of Object.keys(value))
476
- into.require(["requestId", "loginId", "clockId", "providerTime"].includes(key), "timeCheck.result.field", `${path}.${key}`, "unsupported response field");
477
+ into.require(["requestId", "sessionId", "clockId", "providerTime"].includes(key), "timeCheck.result.field", `${path}.${key}`, "unsupported response field");
477
478
  return into.violations;
478
479
  }
479
480
  export function validateManifest(manifest, path = "manifest") {
@@ -528,9 +529,12 @@ export function validateManifest(manifest, path = "manifest") {
528
529
  into.require(!Object.hasOwn(manifest, former), "manifest.settleMs.renamed", `${path}.${former}`, "use settleMs; the former field is not accepted");
529
530
  }
530
531
  into.require(typeof manifest.settleMs === "number" && Number.isInteger(manifest.settleMs) && manifest.settleMs > 0, "manifest.settleMs", `${path}.settleMs`, "settleMs is 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, stated by every provider");
531
- if (manifest.orgLevels !== undefined) {
532
+ if (manifest.orgLevels === undefined) {
533
+ into.add("manifest.orgLevels.required", `${path}.orgLevels`, "orgLevels is required: the organisation's whole ladder, person included, each level labelled in the languages its agents read");
534
+ }
535
+ else {
532
536
  if (!Array.isArray(manifest.orgLevels)) {
533
- into.add("manifest.orgLevels.shape", `${path}.orgLevels`, "orgLevels must be an array when present");
537
+ into.add("manifest.orgLevels.shape", `${path}.orgLevels`, "orgLevels must be an array");
534
538
  }
535
539
  else {
536
540
  const ids = new Set();
@@ -551,7 +555,9 @@ export function validateManifest(manifest, path = "manifest") {
551
555
  }
552
556
  else
553
557
  wellFormed = false;
554
- if (!into.filled(level.label, "manifest.orgLevel.label", `${at}.label`, "a level needs the label an agent computer shows for it"))
558
+ const before = into.violations.length;
559
+ validateLocalizedText(level.label, "manifest.orgLevel.label", `${at}.label`, into);
560
+ if (into.violations.length !== before)
555
561
  wellFormed = false;
556
562
  });
557
563
  if (wellFormed && !ids.has("person")) {
@@ -652,32 +658,38 @@ function validateLocalizedText(value, rule, path, into) {
652
658
  // ---------------------------------------------------------------------------
653
659
  // Task.
654
660
  // ---------------------------------------------------------------------------
655
- function validateDestinationDirectory(value, path, into) {
661
+ function validateAddToCallCapability(value, path, into) {
656
662
  if (!isPlainObject(value)) {
657
- into.add("task.destinations.shape", path, "a conference control carries the directory it offers: { destinations: [...] }");
663
+ into.add("task.addToCall.shape", path, "addToCall says whom the agent may add to the call, as the dialpad does: { destinations: \"contacts-only\" | \"any-number\" }");
658
664
  return;
659
665
  }
660
- if (!Array.isArray(value.destinations)) {
661
- into.add("task.destinations.list", `${path}.destinations`, "destinations must be an array");
666
+ into.oneOf(value.destinations, DIAL_DESTINATION_POLICIES, "task.addToCall.destinations", `${path}.destinations`);
667
+ if (value.contactIds === undefined)
668
+ return;
669
+ if (!Array.isArray(value.contactIds) || value.contactIds.length === 0) {
670
+ into.add("task.addToCall.contactIds", `${path}.contactIds`, "contactIds narrows the contacts offered: a non-empty list of ids, or omitted for every contact");
662
671
  return;
663
- }
664
- // Nothing is typed, so a directory with nothing in it is a control with nothing to offer.
665
- if (value.destinations.length === 0) {
666
- into.add("task.destinations.offer", path, "a directory offers at least one item; with none, omit the capability");
667
672
  }
668
673
  const seen = new Set();
669
- value.destinations.forEach((destination, index) => {
670
- const at = `${path}.destinations[${index}]`;
671
- if (!isPlainObject(destination)) {
672
- into.add("task.destination.shape", at, "each destination must be an object");
673
- return;
674
+ value.contactIds.forEach((id, index) => {
675
+ if (into.filled(id, "task.addToCall.contactIds", `${path}.contactIds[${index}]`, "each contact id is a non-empty string")) {
676
+ into.require(!seen.has(id), "task.addToCall.contactIds.unique", `${path}.contactIds[${index}]`, `${describeValue(id)} is listed twice`);
677
+ seen.add(id);
674
678
  }
675
- if (into.filled(destination.id, "task.destination.id", `${at}.id`, "a destination needs an id")) {
676
- if (seen.has(destination.id))
677
- into.add("task.destination.unique", `${at}.id`, `duplicate destination id: ${destination.id}`);
678
- seen.add(destination.id);
679
+ });
680
+ }
681
+ /** The provider's contacts, the agent computer's directory: each entry a contact with a unique id. */
682
+ function validateContactEntriesInto(value, path, into, levels) {
683
+ const seen = new Set();
684
+ value.forEach((contact, index) => {
685
+ const at = `${path}[${index}]`;
686
+ validateContactInto(contact, at, into, levels);
687
+ if (!isPlainObject(contact))
688
+ return;
689
+ if (into.filled(contact.id, "contact.id", `${at}.id`, "a contacts entry carries the unique id the wire names it by")) {
690
+ into.require(!seen.has(contact.id), "contact.id.unique", `${at}.id`, `duplicate contact id: ${contact.id}`);
691
+ seen.add(contact.id);
679
692
  }
680
- into.filled(destination.label, "task.destination.label", `${at}.label`, "a destination needs a label");
681
693
  });
682
694
  }
683
695
  function validateOutcomes(value, path, into) {
@@ -766,15 +778,12 @@ function validateCustomCapabilities(value, path, into) {
766
778
  }
767
779
  });
768
780
  }
769
- const DEFAULT_LEVEL_IDS = DEFAULT_LEVELS.map(level => level.id);
770
781
  const POLICY_SETTINGS = membersOf({ on: true, off: true, person: true });
771
782
  const POLICY_KEYS = new Set([
772
783
  ...TASK_CAPABILITIES.voice, ...TASK_CAPABILITIES.chat, ...TASK_CAPABILITIES.email, "dial",
773
784
  ].filter(name => name !== "browsers" && name !== "outcomes" && name !== "custom"));
774
785
  const PERSON_SETTABLE = /^(hold|skill:.+)$/;
775
786
  const isLocked = (value) => isPlainObject(value) && value.lockedBy !== undefined;
776
- /** The level ids in force: the manifest's, or the defaults when the caller holds no manifest. */
777
- const levelIds = (levels) => levels ?? DEFAULT_LEVEL_IDS;
778
787
  /**
779
788
  * What the queue locks is locked on the whole task. Given the locked values, every other field an
780
789
  * agent reads -- the title, the reference, an attribute, a custom control's label, a browser URL the
@@ -827,7 +836,7 @@ function validateLockedByInto(value, rule, path, levels, into) {
827
836
  if (!into.filled(value, rule, path, "lockedBy names the level that locked it"))
828
837
  return;
829
838
  into.require(value !== "person", `${rule}.person`, path, "a person never locks their own value");
830
- into.require(levelIds(levels).includes(value), `${rule}.unknown`, path, `${describeValue(value)} is not a level this manifest declares: in force are ${levelIds(levels).join(", ")}`);
839
+ into.require(levels.includes(value), `${rule}.unknown`, path, `${describeValue(value)} is not a level this manifest declares: ${inForce(levels)}`);
831
840
  }
832
841
  /** `{ lockedBy, reason? }` standing in for a value: who locked it, and a reason if given. */
833
842
  function validateLockedInto(value, rule, path, levels, into) {
@@ -838,7 +847,7 @@ function validateLockedInto(value, rule, path, levels, into) {
838
847
  /** What every resolved value carries: who set it, and who locked it if anyone. */
839
848
  function validateResolvedInto(value, rule, path, levels, into) {
840
849
  if (into.filled(value.setBy, `${rule}.setBy`, `${path}.setBy`, "setBy names who stated the value: a level, or provider")) {
841
- into.require(value.setBy === "provider" || levelIds(levels).includes(value.setBy), `${rule}.setBy.unknown`, `${path}.setBy`, `${describeValue(value.setBy)} is neither provider nor a level this manifest declares`);
850
+ into.require(value.setBy === "provider" || levels.includes(value.setBy), `${rule}.setBy.unknown`, `${path}.setBy`, `${describeValue(value.setBy)} is neither provider nor a level this manifest declares: ${inForce(levels)}`);
842
851
  }
843
852
  if (value.lockedBy !== undefined)
844
853
  validateLockedByInto(value.lockedBy, `${rule}.lockedBy`, `${path}.lockedBy`, levels, into);
@@ -847,14 +856,22 @@ function validateResolvedInto(value, rule, path, levels, into) {
847
856
  into.require(value.lockedBy !== undefined, `${rule}.reason.unexpected`, `${path}.reason`, "a reason goes with lockedBy: it says why it was locked");
848
857
  }
849
858
  }
850
- /** The level ids a manifest puts in force, for validators that receive one. */
859
+ /** A command context's `levels`, the manifest's level ids the session is validated against. */
860
+ function contextLevels(context, rule, path, into) {
861
+ const levels = context.levels;
862
+ if (Array.isArray(levels) && levels.every(level => typeof level === "string"))
863
+ return levels;
864
+ into.add(rule, `${path}.levels`, "the context carries levels, the ids of the manifest's orgLevels, to validate the session against");
865
+ return [];
866
+ }
867
+ const inForce = (levels) => levels.length === 0 ? "it declares no ladder" : `in force are ${levels.join(", ")}`;
868
+ /** The level ids a manifest declares, for validators that receive one. A manifest without a ladder declares none, and every level is refused. */
851
869
  function manifestLevels(manifest) {
852
- if (!isPlainObject(manifest))
853
- return undefined;
854
- const declared = Array.isArray(manifest.orgLevels)
855
- ? manifest.orgLevels.filter((level) => isPlainObject(level) && typeof level.id === "string")
856
- : undefined;
857
- return effectiveLevels(declared).map(level => level.id);
870
+ if (!isPlainObject(manifest) || !Array.isArray(manifest.orgLevels))
871
+ return [];
872
+ return manifest.orgLevels
873
+ .filter((level) => isPlainObject(level) && typeof level.id === "string")
874
+ .map(level => level.id);
858
875
  }
859
876
  const CUSTOM_RENDERS = membersOf({ inline: true, page: true });
860
877
  const CREDENTIAL_FIELD_TYPES = membersOf({ text: true, password: true });
@@ -1016,7 +1033,7 @@ function validateHistory(value, path, into, task = {}) {
1016
1033
  // muted leg is a record that dropped a fact it held rather than one it could not establish.
1017
1034
  if (entry.step === "muted") {
1018
1035
  into.oneOf(entry.mutedBy, MUTED_BY, "task.history.mutedBy", `${at}.mutedBy`);
1019
- into.require(entry.by !== undefined, "task.history.muted.by", `${at}.by`, "a muted leg is attributed to the login's agent: the host reported it, and the provider knows who the host's agent is");
1036
+ into.require(entry.by !== undefined, "task.history.muted.by", `${at}.by`, "a muted leg is attributed to the session's agent: the host reported it, and the provider knows who the host's agent is");
1020
1037
  }
1021
1038
  else if (HISTORY_STEPS.includes(entry.step)) {
1022
1039
  into.require(entry.mutedBy === undefined, "task.history.mutedBy.unexpected", `${at}.mutedBy`, "only a muted step says who silenced the microphone");
@@ -1028,11 +1045,11 @@ function validateHistory(value, path, into, task = {}) {
1028
1045
  }
1029
1046
  // A step that dialled says where to and, when a host placed it, which dial; no other step dialled.
1030
1047
  const dialled = typeof entry.step === "string" && HISTORY_STEPS_THAT_DIAL.includes(entry.step);
1031
- for (const field of ["dialId", "destinationId"]) {
1048
+ for (const field of ["dialId", "contactId"]) {
1032
1049
  if (entry[field] === undefined)
1033
1050
  continue;
1034
1051
  if (into.filled(entry[field], `task.history.${field}`, `${at}.${field}`, `${field} must not be empty when present`)) {
1035
- into.require(dialled, `task.history.${field}.unexpected`, `${at}.${field}`, `${describeValue(entry.step)} dialled nothing; ${field} belongs on transferred, conferenced, or unanswered`);
1052
+ into.require(dialled, `task.history.${field}.unexpected`, `${at}.${field}`, `${describeValue(entry.step)} dialled nothing; ${field} belongs on transferred, added, or unanswered`);
1036
1053
  }
1037
1054
  }
1038
1055
  });
@@ -1061,7 +1078,7 @@ const WORK_NOT_BEGUN = ["pending", "confirmed", "preview"];
1061
1078
  /**
1062
1079
  * Who is on the call, as the provider states it. Voice only. Each entry is a role with what that
1063
1080
  * role needs and nothing another role would: a party or an agent dialled nowhere, so neither
1064
- * carries a destination; somebody conferenced came from one, so they do.
1081
+ * carries a destination; somebody added came from one, so they do.
1065
1082
  */
1066
1083
  function validateOnCall(value, channel, path, into) {
1067
1084
  if (value === undefined)
@@ -1088,14 +1105,18 @@ function validateOnCall(value, channel, path, into) {
1088
1105
  }
1089
1106
  if (role === "party")
1090
1107
  parties += 1;
1108
+ if (entry.coaching !== undefined) {
1109
+ into.require(entry.coaching === true, "task.onCall.coaching", `${at}.coaching`, "coaching is stated by presence: send true or omit it");
1110
+ into.require(role === "agent", "task.onCall.coaching.unexpected", `${at}.coaching`, "only a lead, on the call as an agent, coaches");
1111
+ }
1091
1112
  if (role === "agent") {
1092
1113
  into.require(isUserId(entry.userId), "task.onCall.userId", `${at}.userId`, "an agent on the call is named by their user id");
1093
1114
  }
1094
1115
  else {
1095
1116
  into.require(entry.userId === undefined, "task.onCall.userId.unexpected", `${at}.userId`, `a ${role} is not named by a user id`);
1096
1117
  }
1097
- if (role === "conferenced") {
1098
- into.filled(entry.destinationId, "task.onCall.destinationId", `${at}.destinationId`, `a ${role} entry names the directory item that was dialled`);
1118
+ if (role === "added") {
1119
+ into.filled(entry.contactId, "task.onCall.contactId", `${at}.contactId`, `a ${role} entry names the contact that was dialled, by its id in the provider's contacts`);
1099
1120
  // Stated, so a snapshot says who is present without anyone having seen the dial's outcome.
1100
1121
  if (into.oneOf(entry.stage, ON_CALL_STAGES, "task.onCall.stage", `${at}.stage`)) {
1101
1122
  into.require(!(entry.stage === "ringing" && entry.held === true), "task.onCall.held.ringing", `${at}.held`, "nobody ringing is held; held belongs to somebody who has joined");
@@ -1115,13 +1136,13 @@ function validateOnCall(value, channel, path, into) {
1115
1136
  if (entry.stage !== undefined && into.oneOf(entry.stage, ON_CALL_STAGES, "task.onCall.stage", `${at}.stage`)) {
1116
1137
  into.require(!(entry.stage === "ringing" && entry.held === true), "task.onCall.held.ringing", `${at}.held`, "nobody ringing is held; held belongs to somebody who has joined");
1117
1138
  }
1118
- for (const field of ["destinationId", "label"]) {
1119
- into.require(entry[field] === undefined, `task.onCall.${field}.unexpected`, `${at}.${field}`, `a party is not a directory item; ${field} belongs on conferenced`);
1139
+ for (const field of ["contactId", "label"]) {
1140
+ into.require(entry[field] === undefined, `task.onCall.${field}.unexpected`, `${at}.${field}`, `a party is not a directory item; ${field} belongs on added`);
1120
1141
  }
1121
1142
  }
1122
1143
  else {
1123
- for (const field of ["destinationId", "dialId", "label", "stage"]) {
1124
- into.require(entry[field] === undefined, `task.onCall.${field}.unexpected`, `${at}.${field}`, role === "party" ? `a party carries ${field} on a connect-back alone, with its dial and stage together` : `a ${role} was dialled from nowhere; ${field} belongs on conferenced`);
1144
+ for (const field of ["contactId", "dialId", "label", "stage"]) {
1145
+ into.require(entry[field] === undefined, `task.onCall.${field}.unexpected`, `${at}.${field}`, role === "party" ? `a party carries ${field} on a connect-back alone, with its dial and stage together` : `a ${role} was dialled from nowhere; ${field} belongs on added`);
1125
1146
  }
1126
1147
  }
1127
1148
  });
@@ -1376,8 +1397,8 @@ function validateTaskInto(task, context, path, into) {
1376
1397
  case "custom":
1377
1398
  validateCustomCapabilities(declared, `${path}.capabilities.custom`, into);
1378
1399
  break;
1379
- case "conference":
1380
- validateDestinationDirectory(declared, `${path}.capabilities.${name}`, into);
1400
+ case "addToCall":
1401
+ validateAddToCallCapability(declared, `${path}.capabilities.${name}`, into);
1381
1402
  break;
1382
1403
  default:
1383
1404
  // Presence is the permission: the flag capabilities carry no payload, so anything but
@@ -1434,7 +1455,7 @@ export function validateBreakStatus(state, tasks, path = "snapshot") {
1434
1455
  /**
1435
1456
  * Checks a lead command before dispatch, against the current authentication, transport and team
1436
1457
  * member list (`team`) and, for force-break and end-forced-break, the target's full `memberBreak`.
1437
- * The authority is the login's `lead` flag; the provider rechecks the target and the state
1458
+ * The authority is the lead capability the command needs, on the session's `lead`; the provider rechecks the target and the state
1438
1459
  * atomically, since a team member list is not authority to act after it has changed.
1439
1460
  */
1440
1461
  export function validateTeamCommand(request, context, path = "teamCommand") {
@@ -1444,10 +1465,11 @@ export function validateTeamCommand(request, context, path = "teamCommand") {
1444
1465
  return into.violations;
1445
1466
  }
1446
1467
  const auth = isPlainObject(context.authentication) ? context.authentication : {};
1447
- into.violations.push(...validateAuthenticationState(auth, `${path}.authentication`));
1468
+ into.violations.push(...validateAuthenticationState(auth, `${path}.authentication`, { levels: contextLevels(context, "team.command.levels", path, into) }));
1448
1469
  const caps = isPlainObject(auth.capabilities) ? auth.capabilities : {};
1449
- into.require((auth.status === "authenticated" || auth.status === "refreshing") && context.transport === "active", "team.command.connection", path, "lead commands require a live login and active transport");
1450
- into.require(caps.lead === true, "team.command.capability", path, "the login must declare lead");
1470
+ into.require((auth.status === "authenticated" || auth.status === "refreshing") && context.transport === "active", "team.command.connection", path, "lead commands require a live session and active transport");
1471
+ const lead = isPlainObject(caps.lead) ? caps.lead : undefined;
1472
+ into.require(lead !== undefined, "team.command.capability", path, "the session must declare lead");
1451
1473
  const command = request.command;
1452
1474
  const member = ["type", "memberId", "assignmentId"];
1453
1475
  const allowed = {
@@ -1462,6 +1484,12 @@ export function validateTeamCommand(request, context, path = "teamCommand") {
1462
1484
  into.add("team.command.type", path, `unknown lead command: ${describeValue(command.type)}`);
1463
1485
  return into.violations;
1464
1486
  }
1487
+ // Every lead switches the feature and leaves a call; every other command is the lead capability it needs.
1488
+ const needs = Object.hasOwn(LEAD_COMMAND_CAPABILITY, command.type)
1489
+ ? LEAD_COMMAND_CAPABILITY[command.type] : undefined;
1490
+ if (needs !== undefined && lead !== undefined) {
1491
+ into.require(lead[needs] === true, "team.command.notGranted", path, `${describeValue(command.type)} needs the lead capability ${needs}, which this lead does not hold`);
1492
+ }
1465
1493
  for (const key of Object.keys(request))
1466
1494
  into.require(key === "command", "team.request.field", `${path}.${key}`, "only command is supported");
1467
1495
  for (const key of Object.keys(command))
@@ -1538,10 +1566,10 @@ export function validateBreakCommand(method, request, state, context, path = "br
1538
1566
  into.add("break.command.context", path, "current authentication and transport are required");
1539
1567
  return into.violations;
1540
1568
  }
1541
- into.violations.push(...validateAuthenticationState(context.authentication, `${path}.authentication`));
1569
+ into.violations.push(...validateAuthenticationState(context.authentication, `${path}.authentication`, { levels: contextLevels(context, "break.command.levels", path, into) }));
1542
1570
  const auth = isPlainObject(context.authentication) ? context.authentication : {};
1543
- into.require(auth.status === "authenticated" || auth.status === "refreshing", "break.command.authentication", path, "break commands require a live authenticated login");
1544
- into.require(isPlainObject(auth.capabilities) && auth.capabilities.breaks === true, "break.command.capability", path, "the login must declare breaks");
1571
+ into.require(auth.status === "authenticated" || auth.status === "refreshing", "break.command.authentication", path, "break commands require a live authenticated session");
1572
+ into.require(isPlainObject(auth.capabilities) && auth.capabilities.breaks === true, "break.command.capability", path, "the session must declare breaks");
1545
1573
  into.require(context.transport === "active", "break.command.transport", path, "break commands require active transport");
1546
1574
  if (!["requestBreak", "commitBreak", "cancelBreak", "endBreak"].includes(method)) {
1547
1575
  into.add("break.command.method", path, "unknown break method");
@@ -1583,7 +1611,7 @@ export function validateBreakCommand(method, request, state, context, path = "br
1583
1611
  return into.violations;
1584
1612
  }
1585
1613
  /**
1586
- * Checks two complete break states within one provider/login's ordered event stream.
1614
+ * Checks two complete break states within one provider/session's ordered event stream.
1587
1615
  * Call before replacing accepted state; report violations and reconcile on failure.
1588
1616
  * This is not a freshness check: validate a fresh authoritative snapshot separately and
1589
1617
  * use it as a new baseline, never as an event transition. Source ordering and connection
@@ -1686,7 +1714,7 @@ function validateBreakState(value, path, into) {
1686
1714
  into.require(typeof value.activeReasonId === "string" && value.activeReasonId.length > 0, "break.activeReasonId.required", `${path}.activeReasonId`, `a break ${describeValue(value.status)} on a provider that publishes reasons names the one it is on`);
1687
1715
  }
1688
1716
  }
1689
- export function validateTeamMembers(teamMembers, path = "team", context = {}) {
1717
+ export function validateTeamMembers(teamMembers, path, context) {
1690
1718
  const into = new Collector();
1691
1719
  validateTeamMembersInto(teamMembers, path, context, into);
1692
1720
  return into.violations;
@@ -1696,10 +1724,10 @@ function validateTeamMembersInto(teamMembers, path, context, into) {
1696
1724
  into.add("team.shape", path, "a team member list must be an object");
1697
1725
  return;
1698
1726
  }
1699
- // The login is the permission: a team member list reaches a login that declares `capabilities.lead`
1700
- // and nobody else. Only a caller holding the login can check it.
1701
- if (context.capabilities !== undefined && context.capabilities.lead !== true) {
1702
- into.add("team.unentitled", path, "a team member list published to a login that does not declare capabilities.lead: the login is the permission");
1727
+ // The user's capabilities are the permission: a team member list reaches a user whose capabilities include `lead`
1728
+ // and nobody else. Only a caller holding the session can check it.
1729
+ if (context.capabilities !== undefined && context.capabilities.lead === undefined) {
1730
+ into.add("team.unentitled", path, "a team member list published to a user whose capabilities do not include lead: the user's capabilities are the permission");
1703
1731
  }
1704
1732
  // Policies are present where the provider offers policy control, absent where it does not.
1705
1733
  if (teamMembers.policies !== undefined)
@@ -1733,7 +1761,7 @@ function validateTeamMembersInto(teamMembers, path, context, into) {
1733
1761
  }
1734
1762
  }
1735
1763
  /** One member as the lead sees them, whole: on the list, and on `team-member-updated` alone. */
1736
- export function validateTeamMember(member, path = "member", context = {}) {
1764
+ export function validateTeamMember(member, path, context) {
1737
1765
  const into = new Collector();
1738
1766
  validateTeamMemberInto(member, path, context, into);
1739
1767
  return into.violations;
@@ -1798,10 +1826,21 @@ function validateTeamMemberInto(member, at, context, into) {
1798
1826
  if (into.require(isAssignmentId(entry.assignmentId), "team.member.listening.assignmentId", `${here}.assignmentId`, "a listening entry names which of the member's calls the lead is on: the application opens its own audio on it") && Array.isArray(member.tasks)) {
1799
1827
  into.require(task !== undefined, "team.member.listening.assignment", `${here}.assignmentId`, "the call the lead is on is one the member's tasks carry");
1800
1828
  }
1801
- if (into.oneOf(entry.mode, LISTENING_MODES, "team.member.listening.mode", `${here}.mode`) && entry.mode === "join-call"
1829
+ if (into.oneOf(entry.mode, LISTENING_MODES, "team.member.listening.mode", `${here}.mode`)
1802
1830
  && isPlainObject(task) && Array.isArray(task.onCall) && isUserId(entry.leadId)) {
1803
- // A lead who is heard is in the room the member sees; a silent one is not.
1804
- into.require(task.onCall.some((who) => isPlainObject(who) && who.role === "agent" && who.userId === entry.leadId), "team.member.listening.heard", `${here}.mode`, `${entry.leadId} has joined the call and is heard, so the task's onCall carries them as an agent`);
1831
+ // A lead who is heard is in the room the member sees -- marked coaching where the member alone
1832
+ // hears them -- and a silent one is not.
1833
+ const inRoom = task.onCall.find((who) => isPlainObject(who) && who.role === "agent" && who.userId === entry.leadId);
1834
+ const coaching = isPlainObject(inRoom) && inRoom.coaching === true;
1835
+ if (entry.mode === "join-call") {
1836
+ into.require(inRoom !== undefined && !coaching, "team.member.listening.heard", `${here}.mode`, `${entry.leadId} has joined the call and is heard by everyone, so the task's onCall carries them as an agent, not coaching`);
1837
+ }
1838
+ else if (entry.mode === "coach") {
1839
+ into.require(coaching, "team.member.listening.coaching", `${here}.mode`, `${entry.leadId} is coaching and the member hears them, so the task's onCall carries them as an agent marked coaching`);
1840
+ }
1841
+ else {
1842
+ into.require(inRoom === undefined, "team.member.listening.silent", `${here}.mode`, `${entry.leadId} is listening in silence, so the task's onCall does not carry them`);
1843
+ }
1805
1844
  }
1806
1845
  into.timestamp(entry.since, "team.member.listening.since", `${here}.since`);
1807
1846
  });
@@ -1890,7 +1929,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
1890
1929
  return;
1891
1930
  const here = `${path}.phone.channels[${index}]`;
1892
1931
  const task = tasks.find(task => task.assignmentId === channel.assignmentId);
1893
- if (!into.require(task !== undefined, "phone.channel.assignment", `${here}.assignmentId`, `${String(channel.assignmentId)} is not a task this login holds: a channel names the task its call is, or nothing`))
1932
+ if (!into.require(task !== undefined, "phone.channel.assignment", `${here}.assignmentId`, `${String(channel.assignmentId)} is not a task this session holds: a channel names the task its call is, or nothing`))
1894
1933
  return;
1895
1934
  const agrees = channel.state === "active" ? task.phase === "in-progress" && task.audio === "started"
1896
1935
  : channel.state === "held" ? task.phase === "paused"
@@ -1905,9 +1944,9 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
1905
1944
  });
1906
1945
  }
1907
1946
  }
1908
- if (into.filled(snapshot.loginId, "snapshot.loginId", `${path}.loginId`, "a snapshot needs the login id it belongs to")
1909
- && context.loginId !== undefined) {
1910
- into.require(snapshot.loginId === context.loginId, "snapshot.loginId.mismatch", `${path}.loginId`, `a snapshot for session ${describeValue(snapshot.loginId)} on a login whose session is ${context.loginId}`);
1947
+ if (into.filled(snapshot.sessionId, "snapshot.sessionId", `${path}.sessionId`, "a snapshot needs the session id it belongs to")
1948
+ && context.sessionId !== undefined) {
1949
+ into.require(snapshot.sessionId === context.sessionId, "snapshot.sessionId.mismatch", `${path}.sessionId`, `a snapshot for session ${describeValue(snapshot.sessionId)} while the current session is ${context.sessionId}`);
1911
1950
  }
1912
1951
  // The count is the provider's confirmation of how much work it answered with. Stated, never
1913
1952
  // inferred: an unanswered or blank state lacks it, and cannot pass as a confirmed empty.
@@ -1945,7 +1984,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
1945
1984
  if (snapshot.contacts !== undefined) {
1946
1985
  into.require(idle.contacts === true, "snapshot.contacts.capability", `${path}.contacts`, "contacts require the contacts idle capability");
1947
1986
  if (Array.isArray(snapshot.contacts)) {
1948
- snapshot.contacts.forEach((contact, index) => validateContactInto(contact, `${path}.contacts[${index}]`, into, levels));
1987
+ validateContactEntriesInto(snapshot.contacts, `${path}.contacts`, into, levels);
1949
1988
  }
1950
1989
  else {
1951
1990
  into.add("snapshot.contacts.shape", `${path}.contacts`, "contacts must be an array when present");
@@ -1971,7 +2010,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
1971
2010
  }
1972
2011
  // The switch is the permission: once the application has said the team feature is on, a
1973
2012
  // snapshot carries the team, `members: []` included. Before it has said, the provider assumes
1974
- // nothing and owes nothing. The other direction -- a team member list to a login that does not
2013
+ // nothing and owes nothing. The other direction -- a team member list to a session that does not
1975
2014
  // lead, or to a lead who turned the feature off -- is the team member list's own rule.
1976
2015
  if (context.leadFeatures === true && snapshot.team === undefined) {
1977
2016
  into.add("team.required", `${path}.team`, "the team feature is on, so every snapshot carries a team member list: members: [] when nobody is in it");
@@ -2066,9 +2105,9 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
2066
2105
  const channel = isPlainObject(manifest) && typeof manifest.channel === "string" ? manifest.channel : "voice";
2067
2106
  const levels = context.levels ?? manifestLevels(manifest);
2068
2107
  into.filled(envelope.id, "event.id", `${path}.id`, "an event needs an id");
2069
- if (into.filled(envelope.loginId, "event.loginId", `${path}.loginId`, "an event needs the login id it belongs to")
2070
- && context.loginId !== undefined) {
2071
- into.require(envelope.loginId === context.loginId, "event.loginId.mismatch", `${path}.loginId`, `an event for session ${describeValue(envelope.loginId)} on a login whose session is ${context.loginId}`);
2108
+ if (into.filled(envelope.sessionId, "event.sessionId", `${path}.sessionId`, "an event needs the session id it belongs to")
2109
+ && context.sessionId !== undefined) {
2110
+ into.require(envelope.sessionId === context.sessionId, "event.sessionId.mismatch", `${path}.sessionId`, `an event for session ${describeValue(envelope.sessionId)} while the current session is ${context.sessionId}`);
2072
2111
  }
2073
2112
  const idle = isPlainObject(manifest) && isPlainObject(manifest.idleCapabilities) ? manifest.idleCapabilities : {};
2074
2113
  into.timestamp(envelope.occurredAt, "event.occurredAt", `${path}.occurredAt`);
@@ -2142,8 +2181,8 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
2142
2181
  }
2143
2182
  if (event.assignmentId !== undefined)
2144
2183
  into.require(isAssignmentId(event.assignmentId), "event.dialOutcome.assignmentId", `${at}.assignmentId`, "assignmentId must name an assignment when present");
2145
- if (event.destinationId !== undefined)
2146
- into.filled(event.destinationId, "event.dialOutcome.destinationId", `${at}.destinationId`, "a destinationId must not be empty when present");
2184
+ if (event.contactId !== undefined)
2185
+ into.filled(event.contactId, "event.dialOutcome.contactId", `${at}.contactId`, "a contactId must not be empty when present");
2147
2186
  if (event.reason !== undefined)
2148
2187
  into.filled(event.reason, "event.dialOutcome.reason", `${at}.reason`, "a reason must not be empty when present");
2149
2188
  break;
@@ -2171,7 +2210,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
2171
2210
  case "team-member-removed":
2172
2211
  case "team-policies-updated": {
2173
2212
  const field = event.type === "team-updated" ? "team" : event.type === "team-member-updated" ? "member" : event.type === "team-member-removed" ? "memberId" : "policies";
2174
- into.require(context.capabilities === undefined || context.capabilities.lead === true, "event.team.capability", `${at}.${field}`, `${event.type} reaches a login that declares lead, and nobody else`);
2213
+ into.require(context.capabilities === undefined || context.capabilities.lead !== undefined, "event.team.capability", `${at}.${field}`, `${event.type} reaches a user whose capabilities include lead, and nobody else`);
2175
2214
  into.require(context.leadFeatures !== false, "event.team.features", `${at}.${field}`, "the team feature is not on for this lead: nothing of the team reaches them until the application switches it on, and nothing after it switches it off");
2176
2215
  const teamContext = { ...context, levels, channel: isChannel(channel) ? channel : undefined };
2177
2216
  if (event.type === "team-updated")
@@ -2193,7 +2232,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
2193
2232
  into.add("event.contacts.shape", `${at}.contacts`, "contacts must be an array");
2194
2233
  }
2195
2234
  else {
2196
- event.contacts.forEach((contact, index) => validateContactInto(contact, `${at}.contacts[${index}]`, into, levels));
2235
+ validateContactEntriesInto(event.contacts, `${at}.contacts`, into, levels);
2197
2236
  }
2198
2237
  break;
2199
2238
  case "next-call":
@@ -2308,7 +2347,7 @@ function validateNextCallInto(value, path, into) {
2308
2347
  into.require(key === "since", "nextCall.field", `${path}.${key}`, "unsupported field on the ask");
2309
2348
  }
2310
2349
  /** A call waiting in the agent's own queue: the caller as shown to this audience, the queue, the waits, and whether the agent may let it go. */
2311
- export function validateLinedUp(value, path = "linedUp", levels) {
2350
+ export function validateLinedUp(value, levels, path = "linedUp") {
2312
2351
  const into = new Collector();
2313
2352
  validateLinedUpInto(value, path, into, levels);
2314
2353
  return into.violations;
@@ -2342,7 +2381,7 @@ function validatePhoneStateInto(value, path, context, into) {
2342
2381
  return;
2343
2382
  }
2344
2383
  if (into.oneOf(value.phone, PHONES, "phone.phone", `${path}.phone`) && context.phone !== undefined) {
2345
- into.require(value.phone === context.phone, "phone.phone.mismatch", `${path}.phone`, `the host chose a ${context.phone} for this login at connect and the platform reports a ${describeValue(value.phone)}: the phone state is the phone the agent hears this provider's calls on`);
2384
+ into.require(value.phone === context.phone, "phone.phone.mismatch", `${path}.phone`, `the host chose a ${context.phone} for this session at connect and the platform reports a ${describeValue(value.phone)}: the phone state is the phone the agent hears this provider's calls on`);
2346
2385
  }
2347
2386
  into.oneOf(value.status, PHONE_STATUSES, "phone.status", `${path}.status`);
2348
2387
  if (value.muted !== undefined) {
@@ -2476,7 +2515,7 @@ const HOST_GUARANTEES = membersOf({ browserUrlVisibility: true, personConsent: t
2476
2515
  const MUTED_BY = membersOf({ host: true, station: true });
2477
2516
  const HOST_MUTES = membersOf({ stream: true, station: true });
2478
2517
  /**
2479
- * What pressing Mute does on this host, stated on a softphone login and nowhere else: on an agent computer
2518
+ * What pressing Mute does on this host, stated on a softphone session and nowhere else: on an agent computer
2480
2519
  * phone the microphone is the phone's, and off voice there is none. Neither the value nor its
2481
2520
  * absence is inferred from what kind of application the host is.
2482
2521
  */
@@ -2490,24 +2529,24 @@ export function validateCapacity(capacity, path = "capacity") {
2490
2529
  into.require(typeof capacity.count === "number" && Number.isInteger(capacity.count) && capacity.count >= 0, "capacity.count", `${path}.count`, "count is a whole number, zero or more: how many tasks this provider may assign at once, zero while the agent's capacity is elsewhere");
2491
2530
  return into.violations;
2492
2531
  }
2493
- /** The login's store, which the host provides on every connection: three functions, and nothing else is a store. */
2494
- export function validateLoginStore(store, path = "store") {
2532
+ /** The session's store, which the host provides on every connection: three functions, and nothing else is a store. */
2533
+ export function validateSessionStore(store, path = "store") {
2495
2534
  const into = new Collector();
2496
2535
  if (!isPlainObject(store)) {
2497
- into.add("store.shape", path, "a connection carries the login's store: an object with get, set and delete");
2536
+ into.add("store.shape", path, "a connection carries the session's store: an object with get, set and delete");
2498
2537
  return into.violations;
2499
2538
  }
2500
2539
  for (const method of ["get", "set", "delete"]) {
2501
- into.require(typeof store[method] === "function", `store.${method}`, `${path}.${method}`, `a login store ${method}s by key`);
2540
+ into.require(typeof store[method] === "function", `store.${method}`, `${path}.${method}`, `a session store ${method}s by key`);
2502
2541
  }
2503
2542
  return into.violations;
2504
2543
  }
2505
2544
  export function validateHostMute(mute, softphone, path = "host.mute") {
2506
2545
  const into = new Collector();
2507
2546
  if (mute === undefined) {
2508
- into.require(!softphone, "host.mute.required", path, "a softphone login's host states what its Mute does: stream or station");
2547
+ into.require(!softphone, "host.mute.required", path, "a softphone session's host states what its Mute does: stream or station");
2509
2548
  }
2510
- else if (into.require(softphone, "host.mute.unexpected", path, "only a softphone login's host holds a microphone to mute; a hardphone's is the phone's, and a conversation has none")) {
2549
+ else if (into.require(softphone, "host.mute.unexpected", path, "only a softphone session's host holds a microphone to mute; a hardphone's is the phone's, and a conversation has none")) {
2511
2550
  into.oneOf(mute, HOST_MUTES, "host.mute", path);
2512
2551
  }
2513
2552
  return into.violations;
@@ -2522,14 +2561,14 @@ export function validateHostGuarantees(guarantees, path = "host.guarantees", pho
2522
2561
  into.add("host.guarantees.shape", path, "a host declares its guarantees as an object, empty when it makes none");
2523
2562
  return into.violations;
2524
2563
  }
2525
- // The login's phone decides who holds the mute: a softphone host owns it and promises to keep it
2564
+ // The session's phone decides who holds the mute: a softphone host owns it and promises to keep it
2526
2565
  // off the hold; a hardphone's is the handset's, and a host off voice has none.
2527
2566
  if (phone !== undefined) {
2528
2567
  if (phone === "softphone") {
2529
- into.require(guarantees.muteUnavailableOnHold === true, "host.guarantee.muteUnavailableOnHold.required", `${path}.muteUnavailableOnHold`, "a softphone login's host holds the mute and promises it is unavailable while the task is paused");
2568
+ into.require(guarantees.muteUnavailableOnHold === true, "host.guarantee.muteUnavailableOnHold.required", `${path}.muteUnavailableOnHold`, "a softphone session's host holds the mute and promises it is unavailable while the task is paused");
2530
2569
  }
2531
2570
  else {
2532
- into.require(guarantees.muteUnavailableOnHold === undefined, "host.guarantee.muteUnavailableOnHold.unexpected", `${path}.muteUnavailableOnHold`, `a ${describeValue(phone)} login's host holds no mute to promise anything of`);
2571
+ into.require(guarantees.muteUnavailableOnHold === undefined, "host.guarantee.muteUnavailableOnHold.unexpected", `${path}.muteUnavailableOnHold`, `a ${describeValue(phone)} session's host holds no mute to promise anything of`);
2533
2572
  }
2534
2573
  }
2535
2574
  for (const [name, declared] of Object.entries(guarantees)) {
@@ -2658,9 +2697,8 @@ export function validateHostReport(report, path = "host") {
2658
2697
  // Commands.
2659
2698
  // ---------------------------------------------------------------------------
2660
2699
  const LEAD_ASSIST_ACTIONS = ["request", "cancel"];
2661
- const CONFERENCE_ACTIONS = ["add", "remove"];
2662
2700
  /** Validate the exact interaction/assignment target before provider command dispatch. */
2663
- export function validateTaskCommandRequest(request, task, path = "request", taskContext) {
2701
+ export function validateTaskCommandRequest(request, task, path, taskContext) {
2664
2702
  const into = new Collector();
2665
2703
  if (!isPlainObject(request) || !isPlainObject(task)) {
2666
2704
  into.add("command.request.shape", path, "a request and the current published task are required");
@@ -2674,13 +2712,6 @@ export function validateTaskCommandRequest(request, task, path = "request", task
2674
2712
  into.violations.push(...validateTaskCommand(request.command, task, `${path}.command`, taskContext));
2675
2713
  return into.violations;
2676
2714
  }
2677
- /**
2678
- * What a command needs to be issuable, checked against the task it names: the capability the
2679
- * guide's table gates it on, the phase it belongs to, and the state that has to stand -- a
2680
- * lead requested, somebody else on the call. Without a task only the command's
2681
- * own shape is checked. A host validates before sending, and an adapter before acting: a command
2682
- * for a control the task never offered is the host's error, and this names it.
2683
- */
2684
2715
  export function validateTaskCommand(command, task, path = "command", taskContext) {
2685
2716
  const into = new Collector();
2686
2717
  if (!isPlainObject(command)) {
@@ -2718,9 +2749,11 @@ export function validateTaskCommand(command, task, path = "command", taskContext
2718
2749
  if (command.action === "request")
2719
2750
  fields.push("note");
2720
2751
  break;
2721
- case "conference":
2722
- fields.push("action", "destinationId");
2723
- fields.push(command.action === "add" ? "dialId" : "party");
2752
+ case "add-to-call":
2753
+ fields.push("dialId", "contactId", "number");
2754
+ break;
2755
+ case "remove-from-call":
2756
+ fields.push("contactId", "party");
2724
2757
  break;
2725
2758
  }
2726
2759
  for (const key of Object.keys(command))
@@ -2744,19 +2777,22 @@ export function validateTaskCommand(command, task, path = "command", taskContext
2744
2777
  if (command.note !== undefined)
2745
2778
  into.filled(command.note, "command.leadAssist.note", `${path}.note`, "a note must not be empty when present");
2746
2779
  break;
2747
- case "conference":
2748
- if (into.oneOf(command.action, CONFERENCE_ACTIONS, "command.conference.action", `${path}.action`)) {
2749
- if (command.action === "add") {
2750
- dial("command.conference.dialId");
2751
- into.filled(command.destinationId, "command.conference.destinationId", `${path}.destinationId`, "a conference names the directory item it dials in");
2752
- }
2753
- else {
2754
- const party = command.party === true;
2755
- const item = isFilled(command.destinationId);
2756
- into.require(party !== item, "command.conference.remove.target", path, "a remove names one person: the party, or a conferenced entry by its destinationId, never both and never neither");
2757
- }
2780
+ case "add-to-call":
2781
+ dial("command.addToCall.dialId");
2782
+ if (command.number === undefined) {
2783
+ into.filled(command.contactId, "command.addToCall.contactId", `${path}.contactId`, "an add names the contact it dials in, or the number typed");
2784
+ }
2785
+ else {
2786
+ into.filled(command.number, "command.addToCall.number", `${path}.number`, "a typed number must not be empty");
2787
+ into.require(command.contactId === undefined, "command.addToCall.number.both", path, "an add names a contact or a typed number, never both");
2758
2788
  }
2759
2789
  break;
2790
+ case "remove-from-call": {
2791
+ const party = command.party === true;
2792
+ const contact = isFilled(command.contactId);
2793
+ into.require(party !== contact, "command.removeFromCall.target", path, "a remove names one person: the party, or an added entry by its contactId, never both and never neither");
2794
+ break;
2795
+ }
2760
2796
  case "recording":
2761
2797
  into.violations.push(...validateRecordingCommandShape(command, "provider", path));
2762
2798
  break;
@@ -2771,6 +2807,8 @@ export function validateTaskCommand(command, task, path = "command", taskContext
2771
2807
  }
2772
2808
  if (task === undefined)
2773
2809
  return into.violations;
2810
+ if (taskContext === undefined)
2811
+ throw new TypeError("validateTaskCommand: a task is validated against the manifest's levels; pass taskContext with it");
2774
2812
  // The task the command is held to has to be one the wire published. A host's own mapping of it,
2775
2813
  // handed in for want of the original, is not, and checking a command against it would be
2776
2814
  // checking against a task nobody has -- so the task is validated first, and a command is held
@@ -2820,12 +2858,6 @@ export function validateTaskCommand(command, task, path = "command", taskContext
2820
2858
  // to act on yet, and in completing this agent's interaction has ended. The caller and other
2821
2859
  // channels may continue elsewhere; this task's phase no longer permits these controls.
2822
2860
  const interaction = () => inPhase("command.phase.interaction", "in-progress", "paused");
2823
- // A destination is one the directory offered: the id Omni sends is the id the provider published.
2824
- const listed = (name) => {
2825
- const declared = capabilities[name];
2826
- const directory = isPlainObject(declared) && Array.isArray(declared.destinations) ? declared.destinations.filter(isPlainObject) : [];
2827
- into.require(directory.some(item => item.id === command.destinationId), "command.destination.unknown", `${path}.destinationId`, `${describeValue(command.destinationId)} is not a destination the task's ${name} directory offered`);
2828
- };
2829
2861
  const onCall = Array.isArray(task.onCall) ? task.onCall.filter(isPlainObject) : [];
2830
2862
  switch (type) {
2831
2863
  case "answer":
@@ -2884,19 +2916,27 @@ export function validateTaskCommand(command, task, path = "command", taskContext
2884
2916
  into.require(isPlainObject(task.leadAssist) && task.leadAssist.stage === "requested", "command.leadAssist.requested", path, "cancel needs a request standing: leadAssist with stage requested");
2885
2917
  }
2886
2918
  break;
2887
- case "conference": {
2919
+ case "add-to-call":
2920
+ case "remove-from-call": {
2888
2921
  interaction();
2889
- const conferencing = offered("conference");
2890
- if (conferencing && command.action === "add")
2891
- listed("conference");
2892
- if (conferencing && command.action === "remove") {
2922
+ const adding = offered("addToCall");
2923
+ if (adding && type === "add-to-call" && command.contactId !== undefined) {
2924
+ const declared = capabilities.addToCall;
2925
+ const narrowed = isPlainObject(declared) && Array.isArray(declared.contactIds) ? declared.contactIds : undefined;
2926
+ into.require(narrowed === undefined || narrowed.includes(command.contactId), "command.addToCall.contactId.unlisted", `${path}.contactId`, `${describeValue(command.contactId)} is not among the contacts this task offers to add`);
2927
+ }
2928
+ if (adding && type === "add-to-call" && command.number !== undefined) {
2929
+ const declared = capabilities.addToCall;
2930
+ into.require(isPlainObject(declared) && declared.destinations === "any-number", "command.addToCall.number.contactsOnly", `${path}.number`, "this task adds contacts only: a typed number needs any-number");
2931
+ }
2932
+ if (adding && type === "remove-from-call") {
2893
2933
  const others = onCall.filter(entry => entry.role !== "agent");
2894
2934
  if (command.party === true) {
2895
- into.require(others.some(entry => entry.role !== "party"), "command.conference.remove.alone", path, "removing the party would leave the agent alone: that is end-call");
2935
+ into.require(others.some(entry => entry.role !== "party"), "command.removeFromCall.alone", path, "removing the party would leave the agent alone: that is end-call");
2896
2936
  }
2897
- else if (isFilled(command.destinationId)) {
2898
- into.require(onCall.some(entry => entry.role === "conferenced" && entry.destinationId === command.destinationId), "command.conference.remove.unknown", path, `no conferenced entry on onCall has destinationId ${describeValue(command.destinationId)}`);
2899
- into.require(others.length > 1, "command.conference.remove.alone", path, "removing the last other person would leave the agent alone: that is end-call");
2937
+ else if (isFilled(command.contactId)) {
2938
+ into.require(onCall.some(entry => entry.role === "added" && entry.contactId === command.contactId), "command.removeFromCall.unknown", path, `no added entry on onCall has contactId ${describeValue(command.contactId)}`);
2939
+ into.require(others.length > 1, "command.removeFromCall.alone", path, "removing the last other person would leave the agent alone: that is end-call");
2900
2940
  }
2901
2941
  }
2902
2942
  break;
@@ -3075,7 +3115,7 @@ function validateUser(value, rule, path, into) {
3075
3115
  }
3076
3116
  function validateUserCapabilitiesInto(value, path, into, levels) {
3077
3117
  if (!isPlainObject(value)) {
3078
- into.add("authentication.capabilities.shape", path, "a usable login declares its capabilities: an object, {} when it has none");
3118
+ into.add("authentication.capabilities.shape", path, "a usable state declares the user's capabilities: an object, {} when there are none");
3079
3119
  return;
3080
3120
  }
3081
3121
  for (const [name, declared] of Object.entries(value)) {
@@ -3083,9 +3123,13 @@ function validateUserCapabilitiesInto(value, path, into, levels) {
3083
3123
  continue;
3084
3124
  if (!into.require(SESSION_CAPABILITIES.includes(name), "authentication.capability.unknown", `${path}.${name}`, `unsupported session capability: ${name}`))
3085
3125
  continue;
3126
+ if (name === "lead") {
3127
+ validateLeadCapabilitiesInto(declared, `${path}.lead`, into);
3128
+ continue;
3129
+ }
3086
3130
  if (name === "preferences") {
3087
3131
  if (Array.isArray(declared) && declared.length === 0) {
3088
- into.add("authentication.capability.preferences.empty", `${path}.preferences`, "a login with nothing left to the person omits preferences rather than declaring an empty list");
3132
+ into.add("authentication.capability.preferences.empty", `${path}.preferences`, "a user with nothing left to them omits preferences rather than declaring an empty list");
3089
3133
  }
3090
3134
  validatePreferencesInto(declared, `${path}.preferences`, into, levels);
3091
3135
  continue;
@@ -3093,6 +3137,20 @@ function validateUserCapabilitiesInto(value, path, into, levels) {
3093
3137
  into.require(declared === true, "authentication.capability.value", `${path}.${name}`, `${name} is declared by presence: send true or omit it`);
3094
3138
  }
3095
3139
  }
3140
+ /** A lead's capabilities: an object of the lead commands it allows, each by presence, at least one. */
3141
+ function validateLeadCapabilitiesInto(value, path, into) {
3142
+ if (!isPlainObject(value)) {
3143
+ into.add("authentication.capability.lead.shape", path, "lead states the lead capabilities this session holds: an object such as { listen: true, coach: true }");
3144
+ return;
3145
+ }
3146
+ const granted = Object.entries(value).filter(([, declared]) => declared !== undefined);
3147
+ into.require(granted.length > 0, "authentication.capability.lead.empty", path, "a lead holds at least one lead capability; a session with none omits lead");
3148
+ for (const [name, declared] of granted) {
3149
+ if (!into.require(LEAD_CAPABILITY_NAMES.includes(name), "authentication.capability.lead.unknown", `${path}.${name}`, `unsupported lead capability: ${name}`))
3150
+ continue;
3151
+ into.require(declared === true, "authentication.capability.lead.value", `${path}.${name}`, `${name} is declared by presence: send true or omit it`);
3152
+ }
3153
+ }
3096
3154
  /**
3097
3155
  * A failure an authentication reports: on a `rejected` start or completion, or on an `expired`
3098
3156
  * state. A provider names its own codes freely; an `omni.` code is the contract's and has to be one
@@ -3187,11 +3245,11 @@ function validateAuthenticationChallenge(value, path, into) {
3187
3245
  }
3188
3246
  }
3189
3247
  /**
3190
- * What `start()` or `complete()` answered: a challenge or a rejection from `start`, a login or a
3191
- * rejection from `complete`. A rejection carries a failure the host can show, and a login is held
3248
+ * What `start()` or `complete()` answered: a challenge or a rejection from `start`, a session or a
3249
+ * rejection from `complete`. A rejection carries a failure the host can show, and a session is held
3192
3250
  * to the same rules as any `authenticated` state.
3193
3251
  */
3194
- export function validateAuthenticationResult(result, method, path = "result", context = {}) {
3252
+ export function validateAuthenticationResult(result, method, path, context) {
3195
3253
  const into = new Collector();
3196
3254
  if (!isPlainObject(result)) {
3197
3255
  into.add("authentication.result.shape", path, `${method} must answer an object`);
@@ -3215,7 +3273,7 @@ export function validateAuthenticationResult(result, method, path = "result", co
3215
3273
  }
3216
3274
  return into.violations;
3217
3275
  }
3218
- export function validateAuthenticationState(state, path = "authentication", context = {}) {
3276
+ export function validateAuthenticationState(state, path, context) {
3219
3277
  const into = new Collector();
3220
3278
  if (!isPlainObject(state)) {
3221
3279
  into.add("authentication.shape", path, "an authentication state must be an object");