@xema/omni-protocol 0.1.123 → 0.1.124

package/dist/index.d.ts

@@ -2095,6 +2095,20 @@ export declare const HISTORY_STEPS_WITH_A_PERSON: readonly ["offered", "answered
 /** 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

@@ -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/guide/agent.md

@@ -443,13 +443,16 @@ 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 with the IVR or a bot is `self-service`.** The caller pressing through a menu, talking to a
-voice bot, or a chat customer with a bot before a person takes over: one step for all of them, on
-every channel, the way Genesys Cloud and NICE CXone report IVR and bot time together as
-self-service. Nobody from the provider takes part, so it has no `by`. `at` is when the customer
-entered it and `seconds`, once it ended, how long they spent there; a customer sent back to a menu
-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`.
+**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
@@ -483,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

package/guide.md

@@ -725,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 };
@@ -2990,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.123",
+  "version": "0.1.124",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",