@xema/omni-protocol 0.1.122 → 0.1.124

package/GLOSSARY.md

@@ -100,7 +100,7 @@ hands only through routing or a lead's take-over.
 
 | Term | In plain words | What others call it |
 | --- | --- | --- |
-| **History** | The steps a call went through before and with this agent: arrived, queued, answered, held, handed over. | *Contact trace record* (Amazon Connect), *conversation details* or *segments* (Genesys Cloud), *call detail record*. |
+| **History** | The steps a call went through before and with this agent: arrived, self-service, queued, answered, held, handed over. | *Contact trace record* (Amazon Connect), *conversation details* or *segments* (Genesys Cloud), *call detail record*. |
 | **Recording** | A recording of one side of the call, the customer's or the agent's. | *Call recording*, *screen and voice recording*. |
 | **Paused for sensitive details** | Recording stops while card or account details are given. | *Secure pause* (Genesys Cloud), *PCI pause*. |
 

package/dist/index.d.ts

@@ -872,7 +872,7 @@ export type TaskAttribute = TaskAttributeBase & ({
     type: "timestamp";
     at: IsoTimestamp;
 });
-export type HistoryStep = "arrived" | "queued" | "offered" | "answered" | "held" | "muted" | "transferred" | "conferenced" | "unanswered" | "callback-requested";
+export type HistoryStep = "arrived" | "self-service" | "queued" | "offered" | "answered" | "held" | "muted" | "transferred" | "conferenced" | "unanswered" | "callback-requested";
 /**
  * The call record: the steps that brought the task here, one entry per occurrence and oldest
  * first, and what they add up to before this agent -- stated by the provider from its own record,
@@ -907,7 +907,7 @@ export interface TaskHistoryStep {
      */
     seconds?: DurationSeconds;
     /**
-     * Who took part. Absent on `arrived` and `queued`, where nobody does; absent on `callback-requested`, where the
+     * Who took part. Absent on `arrived`, `self-service` and `queued`, where nobody does; absent on `callback-requested`, where the
      * caller chose it in the queue, and present there when an agent arranged it; absent on any other
      * step means the provider could not attribute it, which is a different claim and a legitimate one.
      */
@@ -2053,6 +2053,7 @@ export declare const DEFAULT_TASK_TYPE_PRESENTATION: {
 };
 export declare const DEFAULT_HISTORY_STEP_LABELS: {
     readonly arrived: "Incoming call";
+    readonly "self-service": "Self-service";
     readonly queued: "Queued";
     readonly offered: "Offered";
     readonly answered: "Answered";
@@ -2086,14 +2087,28 @@ export declare const assignmentKey: (providerId: string, assignmentId: Assignmen
  */
 export declare const userKey: (providerId: string, userId: UserId) => string;
 /**
- * Every history step somebody from the provider takes part in. `arrived` and `queued` are the ones
- * nobody does, and `callback-requested` is the caller's choice unless an agent arranged it, so none
+ * Every history step somebody from the provider takes part in. `arrived`, `self-service` and
+ * `queued` are the ones nobody does, and `callback-requested` is the caller's choice unless an agent arranged it, so none
  * of them is here.
  */
 export declare const HISTORY_STEPS_WITH_A_PERSON: readonly ["offered", "answered", "held", "muted", "transferred", "conferenced", "unanswered"];
 /** The steps a dial writes, and so the only ones that carry a `dialId` and a `destinationId`. */
 export declare const HISTORY_STEPS_THAT_DIAL: readonly ["transferred", "conferenced", "unanswered"];
 export declare const historyStepDials: (step: HistoryStep) => boolean;
+/**
+ * Consecutive entries of one step, shown as one span. The record keeps an entry per occurrence --
+ * two holds are counted as two -- and this is how the agent sees them: once, from the first
+ * entry's `at`, lasting the sum of their `seconds` when every entry states one, and with no
+ * duration when any does not, never a sum that silently leaves a running leg out.
+ */
+export interface HistorySpan {
+    step: HistoryStep;
+    at: IsoTimestamp;
+    seconds?: DurationSeconds;
+    entries: TaskHistoryStep[];
+}
+/** Groups a record's consecutive same-step entries into spans, oldest first. */
+export declare function historySpans(steps: readonly TaskHistoryStep[]): HistorySpan[];
 /** Whether an absent `by` means "could not attribute" rather than "nobody was involved". */
 export declare function historyStepExpectsAPerson(step: HistoryStep): boolean;
 export interface BrowserSessionKeyInput {

package/dist/index.js

@@ -146,7 +146,7 @@ export const DEFAULT_TASK_TYPE_PRESENTATION = {
     email: { singular: "Email", plural: "Emails", referenceLabel: "Email ID" },
 };
 export const DEFAULT_HISTORY_STEP_LABELS = {
-    arrived: "Incoming call", queued: "Queued", offered: "Offered", answered: "Answered", held: "On hold",
+    arrived: "Incoming call", "self-service": "Self-service", queued: "Queued", offered: "Offered", answered: "Answered", held: "On hold",
     muted: "Muted", transferred: "Transferred", conferenced: "Conferenced", unanswered: "Unanswered",
     "callback-requested": "Callback requested",
 };
@@ -188,8 +188,8 @@ export const assignmentKey = (providerId, assignmentId) => `${encodeURIComponent
  */
 export const userKey = (providerId, userId) => `${encodeURIComponent(providerId)}:${encodeURIComponent(userId)}`;
 /**
- * Every history step somebody from the provider takes part in. `arrived` and `queued` are the ones
- * nobody does, and `callback-requested` is the caller's choice unless an agent arranged it, so none
+ * Every history step somebody from the provider takes part in. `arrived`, `self-service` and
+ * `queued` are the ones nobody does, and `callback-requested` is the caller's choice unless an agent arranged it, so none
  * of them is here.
  */
 export const HISTORY_STEPS_WITH_A_PERSON = [
@@ -201,6 +201,23 @@ export const historyStepDials = (step) => HISTORY_STEPS_THAT_DIAL.includes(step)
 // Pinned both ways: a step added to `HistoryStep` has to be placed here, and a step listed here
 // has to exist there. `satisfies` on the list covers the second; this statement covers the first.
 true;
+/** Groups a record's consecutive same-step entries into spans, oldest first. */
+export function historySpans(steps) {
+    const spans = [];
+    for (const entry of steps) {
+        const last = spans[spans.length - 1];
+        if (last !== undefined && last.step === entry.step)
+            last.entries.push(entry);
+        else
+            spans.push({ step: entry.step, at: entry.at, entries: [entry] });
+    }
+    for (const span of spans) {
+        if (span.entries.every(entry => entry.seconds !== undefined)) {
+            span.seconds = span.entries.reduce((total, entry) => total + entry.seconds, 0);
+        }
+    }
+    return spans;
+}
 /** Whether an absent `by` means "could not attribute" rather than "nobody was involved". */
 export function historyStepExpectsAPerson(step) {
     return HISTORY_STEPS_WITH_A_PERSON.includes(step);

package/dist/validation.js

@@ -58,7 +58,7 @@ const TEAM_AVAILABILITIES = membersOf({
     ready: true, "on-task": true, "on-break": true, elsewhere: true, "signed-out": true,
 });
 const HISTORY_STEPS = membersOf({
-    arrived: true, queued: true, offered: true, answered: true, held: true, muted: true, transferred: true, conferenced: true, unanswered: true,
+    arrived: true, "self-service": true, queued: true, offered: true, answered: true, held: true, muted: true, transferred: true, conferenced: true, unanswered: true,
     "callback-requested": true,
 });
 const CUSTOM_UI_CONTROLS = membersOf({ button: true, toggle: true, "menu-item": true });
@@ -995,8 +995,8 @@ function validateHistory(value, path, into, task = {}) {
         }
         if (entry.by !== undefined) {
             into.require(isUserId(entry.by), "task.history.by", `${at}.by`, "by must be a non-empty user id; omit it when the person cannot be identified");
-            // On `arrived` and `queued` nobody takes part, so there is nothing to name.
-            into.require(entry.step !== "arrived" && entry.step !== "queued", "task.history.by.unexpected", `${at}.by`, `${describeValue(entry.step)} names nobody`);
+            // On `arrived`, `self-service` and `queued` nobody takes part, so there is nothing to name.
+            into.require(entry.step !== "arrived" && entry.step !== "self-service" && entry.step !== "queued", "task.history.by.unexpected", `${at}.by`, `${describeValue(entry.step)} names nobody`);
         }
         // A step that dialled says where to and, when a host placed it, which dial; no other step dialled.
         const dialled = typeof entry.step === "string" && HISTORY_STEPS_THAT_DIAL.includes(entry.step);

package/guide/agent.md

@@ -409,7 +409,8 @@ first, and what they add up to before this agent:
 ```ts
 history: {
   steps: [
-    { step: "arrived",     at: "2026-08-21T00:58:40Z", seconds: 20 },
+    { step: "arrived",     at: "2026-08-21T00:58:40Z", seconds: 2 },
+    { step: "self-service", at: "2026-08-21T00:58:42Z", seconds: 18 },
     { step: "queued",      at: "2026-08-21T00:59:00Z", seconds: 41 },
     { step: "answered",    at: "2026-08-21T00:59:41Z", seconds: 312, by: "a-17" },
     { step: "held",        at: "2026-08-21T01:02:10Z", seconds: 35, by: "a-17" },
@@ -430,7 +431,7 @@ something else, which will arrive under its own name and must not be folded in h
 
 It rides in the snapshot and is replaced whole like everything else there.
 
-Steps are `arrived`, `queued`, `offered`, `answered`, `held`, `muted`, `transferred`, `conferenced`,
+Steps are `arrived`, `self-service`, `queued`, `offered`, `answered`, `held`, `muted`, `transferred`, `conferenced`,
 `unanswered`, `callback-requested`, and each is defined on `TaskHistoryStep`.
 
 **The record starts where the call started.** `arrived` is the instant the call reached the
@@ -442,6 +443,17 @@ arrive omits it rather than guessing an instant. Omni shows it as *Incoming call
 Amazon Connect keeps an initiation time, Genesys Cloud a conversation start and NICE CXone a contact
 start, separate from the queue.
 
+**Time the platform handles the customer before a queue is `self-service`.** The caller pressing
+through a menu, talking to a voice bot, hearing an announcement, or waiting while the platform
+looks them up; a chat customer with a bot before a person takes over: one step for all of them, on
+every channel. Genesys Cloud and NICE CXone report IVR and bot time as self-service; here it also
+takes in the routing time Genesys Cloud keeps as a separate system segment, so a provider that
+measures the gap before each queue without knowing what played in it reports it here rather than
+nowhere. It is therefore not evidence that the customer used a menu. Nobody from the provider takes
+part, so it has no `by`. `at` is when it began and `seconds`, once it ended, how long it lasted; a
+customer routed again after a transfer has a second entry, one per visit, as a second queue is a
+second `queued`. A customer that words it *IVR* for its agents does so in `labels.historySteps`.
+
 **A callback carries the call it comes back to.** When a caller asks to be called back, or an agent
 arranges it, the provider writes a `callback-requested` step: `by` names the agent who arranged it, and
 is absent when the caller chose it in the queue. The callback reaches an agent as a new task, and that
@@ -474,7 +486,13 @@ provider closed it. One publisher of the closed leg, and no order between them t
 hold, at the entry's `at` plus its `seconds`, and nothing is lost by not naming it twice. The same goes for every step: two mutes are two
 `muted` entries, and a call that joined two queues -- a menu's, then this one -- has two `queued`
 entries, one per join. Order is enforced: an entry earlier than the one before it is refused
-(`task.history.order`). **Intervals between steps are the agent application's to subtract**, never a
+(`task.history.order`).
+
+**Shown as spans.** The record keeps one entry per occurrence, because leads count them — two holds
+are two holds, the way Amazon Connect counts holds per contact, and two queues say which queue the
+call waited in. The agent sees consecutive entries of one step as one span: `historySpans(steps)`
+groups them, as Genesys Cloud keeps segments apart in its record and joins them in the agent's
+timeline. A provider never merges entries to get that look. **Intervals between steps are the agent application's to subtract**, never a
 total the provider adds: *time to offer*, from the call joining its queue to the agent's screen lighting
 up, is the `offered` entry's `at` minus the last `queued` entry's, and the ring is outside it.
 `queueSeconds` keeps the industry's meaning -- the whole wait until somebody answered -- and is not
@@ -551,7 +569,7 @@ Four rules a provider has to keep:
   wrongly; carrying the name here would also copy it into every task and leave it to go stale.
 
 **An absent `by` means different things on different steps, and both are legitimate.** On
-`arrived` and `queued` nobody takes part, so there is nothing to name. On every other step somebody did — see
+`arrived`, `self-service` and `queued` nobody takes part, so there is nothing to name. On every other step somebody did — see
 `HISTORY_STEPS_WITH_A_PERSON` and `historyStepExpectsAPerson()` — so an absent `by` there says
 *this was handled and the provider cannot say by whom*. The one step that is never unattributed is
 `muted`: the agent application has exactly one agent and the provider knows who, so `by` is required there
@@ -564,7 +582,7 @@ worse than one saying plainly it could not attribute a leg — and far better th
 nothing because a single leg could not be named.
 
 An agent application must render the two differently. Showing an unattributed `answered` the same way as
-`queued` or `arrived` tells the agent nobody was involved, which is not what was said. Omni renders it as
+`queued`, `self-service` or `arrived` tells the agent nobody was involved, which is not what was said. Omni renders it as
 *"not recorded"* in the place the name would go.
 
 Omit `history` entirely when the provider cannot observe the steps. Empty `steps` is a

package/guide.md

@@ -696,6 +696,7 @@ type TaskAttribute = TaskAttributeBase & (
 
 type HistoryStep =
   | "arrived"
+  | "self-service"
   | "queued"
   | "offered"
   | "answered"
@@ -724,6 +725,13 @@ type TaskHistoryStep = {
   mutedBy?: MutedBy;
 };
 
+type HistorySpan = {
+  step: HistoryStep;
+  at: IsoTimestamp;
+  seconds?: DurationSeconds;
+  entries: TaskHistoryStep[];
+};
+
 type TaskCompletion =
   | { completionMode: "agent-command"; wrapAllowance?: DurationSeconds }
   | { completionMode: "provider-automatic"; wrapAllowance: DurationSeconds };
@@ -1362,7 +1370,7 @@ const OMNI_FAILURE_CODES = [
 type OmniFailureCode = (typeof OMNI_FAILURE_CODES)[number];
 ```
 
-`HISTORY_STEPS_WITH_A_PERSON` is every `HistoryStep` except `arrived` and `queued`, which nobody
+`HISTORY_STEPS_WITH_A_PERSON` is every `HistoryStep` except `arrived`, `self-service` and `queued`, which nobody
 takes part in, and `callback-requested`, which the caller may choose alone. `historyStepExpectsAPerson()` tests membership.
 
 ### Failure and validation
@@ -1445,6 +1453,7 @@ agent's languages:
 ```ts
 const DEFAULT_HISTORY_STEP_LABELS = {
   arrived: "Incoming call",
+  "self-service": "Self-service",
   queued: "Queued",
   offered: "Offered",
   answered: "Answered",
@@ -2988,6 +2997,14 @@ Whether two logins declare the same capabilities, field by field — key order a
 `team: {}` distinct from `team` absent. It is the comparison an adapter makes before republishing
 `authenticated`, and the one `testAdapter` holds `refreshing` to.
 
+### `historySpans(steps)`
+
+Groups a record's consecutive entries of one step into a `HistorySpan` each — `step`, the first
+entry's `at`, `seconds` summed when every entry states one and absent when any does not, and the
+`entries` themselves — so every agent application shows *Self-service · 30s* once where the
+record has two self-service entries in a row. Only neighbours are grouped: a hold, an answer and
+another hold are three spans. See **Shown as spans** in `guide/agent.md`.
+
 ## Runtime validation
 
 Structural rules in this document are executable through the runtime validators Omni applies to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xema/omni-protocol",
-  "version": "0.1.122",
+  "version": "0.1.124",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",