@xema/omni-protocol 0.1.121 → 0.1.123

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: 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

@@ -177,11 +177,31 @@ export type IdleCapabilities<C extends Channel = Channel> = {
 } : {
     dial?: never;
 });
-export type TaskPhaseLabels = Readonly<Partial<Record<TaskPhase, string>>>;
+/** A BCP 47 language tag: `en`, `hi`, `en-IN`. */
+export type LanguageTag = string;
+/**
+ * One display text per language the provider words it in, keyed by language tag. The agent
+ * application shows the one for the agent's language, found with `localizedText()`, and its own
+ * word when the provider gave none in that language.
+ */
+export type LocalizedText = Readonly<Record<LanguageTag, string>>;
+export type TaskPhaseLabels = Readonly<Partial<Record<TaskPhase, LocalizedText>>>;
+export type HistoryStepLabels = Readonly<Partial<Record<HistoryStep, LocalizedText>>>;
 export interface TaskTypePresentation {
-    singular: string;
-    plural: string;
-    referenceLabel?: string;
+    singular: LocalizedText;
+    plural: LocalizedText;
+    referenceLabel?: LocalizedText;
+}
+/**
+ * What the signed-in customer calls things, as its own admin set them in the provider: one
+ * customer's agents read "New call" where another's read "Entered". Each part is partial and
+ * renames only; the values underneath stay the protocol's, so counts by phase or step add up.
+ */
+export interface Labels {
+    phases?: TaskPhaseLabels;
+    historySteps?: HistoryStepLabels;
+    /** Keyed by `taskType`. An entry replaces the channel default outright rather than merging. */
+    taskTypes?: Readonly<Record<string, TaskTypePresentation>>;
 }
 export interface Manifest<C extends Channel = Channel> {
     /** Stable, installation-wide unique, and unchanged between launches. */
@@ -202,9 +222,6 @@ export interface Manifest<C extends Channel = Channel> {
     timeCheck?: true;
     /** Provider uses its own timestamps for final records; host timestamps are advisory. Omission makes no trust promise. */
     timestampAuthority?: "provider";
-    phaseLabels?: TaskPhaseLabels;
-    /** Keyed by `taskType`. An entry replaces the channel default outright rather than merging. */
-    taskTypePresentation?: Record<string, TaskTypePresentation>;
     /** The organisation's whole ladder, stated outright, `person` included. Omitted for the typical four, `DEFAULT_LEVELS`. */
     orgLevels?: LevelDeclaration[];
     /**
@@ -855,7 +872,7 @@ export type TaskAttribute = TaskAttributeBase & ({
     type: "timestamp";
     at: IsoTimestamp;
 });
-export type HistoryStep = "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,
@@ -890,7 +907,7 @@ export interface TaskHistoryStep {
      */
     seconds?: DurationSeconds;
     /**
-     * Who took part. Absent on `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.
      */
@@ -1756,6 +1773,8 @@ export interface Snapshot<C extends Channel = Channel> {
     /** The call waiting in the agent's own queue, while one is; replaced whole by `lined-up`. */
     linedUp?: LinedUpCall;
     team?: TeamMembers;
+    /** The signed-in customer's own words, from its admin's settings; replaced whole by `labels-updated`. Omitted where it set none. */
+    labels?: Labels;
 }
 /**
  * How many tasks this provider may have assigned to the agent at once.
@@ -1886,6 +1905,11 @@ export type ProviderEvent<C extends Channel = Channel> = {
  | {
     type: "lined-up";
     linedUp?: LinedUpCall;
+}
+/** The customer's words as its admin now has them, whole: present with what it set, empty when it set nothing. */
+ | {
+    type: "labels-updated";
+    labels: Labels;
 };
 /**
  * The `Provider` prefix survives here for a mechanical reason rather than a naming one: `Event`
@@ -2027,6 +2051,25 @@ export declare const DEFAULT_TASK_TYPE_PRESENTATION: {
         readonly referenceLabel: "Email ID";
     };
 };
+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";
+    readonly held: "On hold";
+    readonly muted: "Muted";
+    readonly transferred: "Transferred";
+    readonly conferenced: "Conferenced";
+    readonly unanswered: "Unanswered";
+    readonly "callback-requested": "Callback requested";
+};
+/**
+ * The provider's text for the first of `languages` it has, matched as BCP 47 lookup does: the tag
+ * whole, then with its last subtag dropped, so `hi-IN` finds `hi`. Undefined when it has none of
+ * them, and the agent application shows its own word; never another language in their place.
+ */
+export declare function localizedText(text: LocalizedText | undefined, languages: readonly LanguageTag[]): string | undefined;
 /**
  * A collision-safe global task key.
  *
@@ -2044,8 +2087,9 @@ 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. `queued` is the one nobody does, and
- * `callback-requested` is the caller's choice unless an agent arranged it, so neither is here.
+ * 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`. */

package/dist/index.js

@@ -145,6 +145,29 @@ export const DEFAULT_TASK_TYPE_PRESENTATION = {
     chat: { singular: "Chat", plural: "Chats", referenceLabel: "Chat ID" },
     email: { singular: "Email", plural: "Emails", referenceLabel: "Email ID" },
 };
+export const DEFAULT_HISTORY_STEP_LABELS = {
+    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",
+};
+/**
+ * The provider's text for the first of `languages` it has, matched as BCP 47 lookup does: the tag
+ * whole, then with its last subtag dropped, so `hi-IN` finds `hi`. Undefined when it has none of
+ * them, and the agent application shows its own word; never another language in their place.
+ */
+export function localizedText(text, languages) {
+    if (text === undefined)
+        return undefined;
+    const byTag = new Map(Object.entries(text).map(([tag, value]) => [tag.toLowerCase(), value]));
+    for (const language of languages) {
+        for (let tag = language.toLowerCase(); tag !== ""; tag = tag.includes("-") ? tag.slice(0, tag.lastIndexOf("-")) : "") {
+            const found = byTag.get(tag);
+            if (found !== undefined)
+                return found;
+        }
+    }
+    return undefined;
+}
 // ---------------------------------------------------------------------------
 // Utilities.
 // ---------------------------------------------------------------------------
@@ -165,8 +188,9 @@ 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. `queued` is the one nobody does, and
- * `callback-requested` is the caller's choice unless an agent arranged it, so neither is here.
+ * 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 = [
     "offered", "answered", "held", "muted", "transferred", "conferenced", "unanswered",

package/dist/testing.d.ts

@@ -7,7 +7,7 @@ export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation }
  * rules -- each optional part of a task, each optional part of the break state and team member list, each
  * declared contribution, and each event type.
  */
-declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.history", "task.onCall", "task.leadAssist", "task.takenOver", "task.audio", "task.acceptance", "task.outcomes", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.forced", "team.members", "team.request", "team.tasks", "team.listening", "team.shift", "team.phone", "team.nextCall", "team.linedUp", "shift", "phone", "nextCall", "linedUp", "contacts", "calendar", "team.policies"];
+declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.history", "task.onCall", "task.leadAssist", "task.takenOver", "task.audio", "task.acceptance", "task.outcomes", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.forced", "team.members", "team.request", "team.tasks", "team.listening", "team.shift", "team.phone", "team.nextCall", "team.linedUp", "shift", "phone", "nextCall", "linedUp", "labels", "contacts", "calendar", "team.policies"];
 export type ContractSubject = (typeof STATE_SUBJECTS)[number] | `event.${ProviderEvent["type"]}`;
 export interface AdapterContractResult {
     events: ProviderEventEnvelope[];

package/dist/testing.js

@@ -35,6 +35,7 @@ const STATE_SUBJECTS = [
     "phone",
     "nextCall",
     "linedUp",
+    "labels",
     "contacts",
     "calendar",
     "team.policies",
@@ -46,6 +47,7 @@ const EVENT_TYPES = {
     "task-audio-started": true, "task-audio-ended": true, "task-ended": true, "dial-outcome": true, announcement: true, "queue-summary": true, diagnostic: true,
     "team-updated": true, "team-member-updated": true, "team-member-removed": true, "team-policies-updated": true,
     "contacts-updated": true, "calendar-updated": true, "shift-updated": true, "phone-updated": true, "next-call": true, "lined-up": true,
+    "labels-updated": true,
 };
 const CONTRACT_SUBJECTS = [
     ...STATE_SUBJECTS,
@@ -147,6 +149,8 @@ function observeSnapshot(value, seen) {
         seen.add("nextCall");
     if (value.linedUp !== undefined)
         seen.add("linedUp");
+    if (value.labels !== undefined)
+        seen.add("labels");
 }
 function observeEvent(envelope, seen) {
     const event = isRecord(envelope) ? envelope.event : undefined;
@@ -197,6 +201,9 @@ function observeEvent(envelope, seen) {
             if (event.linedUp !== undefined)
                 seen.add("linedUp");
             break;
+        case "labels-updated":
+            seen.add("labels");
+            break;
         default: break;
     }
 }
@@ -1154,7 +1161,7 @@ const REACHABLE_PHASES = {
 export const SUPERSEDED_BY_A_SNAPSHOT = new Set([
     "snapshot", "transport-status", "break-state", "task-offered", "task-updated", "task-ended",
     "task-audio-started", "task-audio-ended", "team-updated", "team-member-updated", "team-member-removed", "team-policies-updated",
-    "contacts-updated", "calendar-updated", "shift-updated", "phone-updated", "next-call", "lined-up",
+    "contacts-updated", "calendar-updated", "shift-updated", "phone-updated", "next-call", "lined-up", "labels-updated",
 ]);
 export class TaskStream {
     tasks = new Map();

package/dist/validation.d.ts

@@ -30,6 +30,8 @@ export declare function validateProviderTimeCheckRequest(value: unknown, path?:
 /** Checks response shape/correlation, not source-clock accuracy, round-trip delay or freshness. */
 export declare function validateProviderTimeCheckResult(value: unknown, request: unknown, loginId: string, path?: string): ProtocolViolation[];
 export declare function validateManifest(manifest: unknown, path?: string): ProtocolViolation[];
+/** The customer's own words, as `Snapshot.labels` and `labels-updated` carry them. */
+export declare function validateLabels(value: unknown, path?: string): ProtocolViolation[];
 export interface TaskValidationContext {
     /** The provider's channel, from its manifest. A task must agree with it. */
     channel: string;

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({
-    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 });
@@ -517,16 +517,9 @@ export function validateManifest(manifest, path = "manifest") {
         into.require(manifest.timeCheck === true, "manifest.timeCheck", `${path}.timeCheck`, "declare true or omit unsupported clock checks");
     validateDialOutcomes(manifest, `${path}.dialOutcomes`, into);
     validatePhones(manifest, `${path}.phones`, into);
-    if (manifest.phaseLabels !== undefined) {
-        if (!isPlainObject(manifest.phaseLabels)) {
-            into.add("manifest.phaseLabels.shape", `${path}.phaseLabels`, "phaseLabels must be an object when present");
-        }
-        else {
-            for (const [phase, label] of Object.entries(manifest.phaseLabels)) {
-                into.oneOf(phase, TASK_PHASES, "manifest.phaseLabels.phase", `${path}.phaseLabels.${phase}`);
-                into.filled(label, "manifest.phaseLabels.label", `${path}.phaseLabels.${phase}`, "a phase label must not be empty");
-            }
-        }
+    // Labels are the signed-in customer's, set by its own admin: a manifest is fixed when the adapter ships.
+    for (const former of ["phaseLabels", "historyStepLabels", "taskTypePresentation"]) {
+        into.require(!Object.hasOwn(manifest, former), "manifest.labels.moved", `${path}.${former}`, "labels are the signed-in customer's own words and travel as Snapshot.labels and labels-updated; the manifest carries none");
     }
     if (manifest.runningStepReports !== undefined) {
         into.require(manifest.runningStepReports === true, "manifest.runningStepReports", `${path}.runningStepReports`, "runningStepReports is declared by presence, as true; a provider that takes begin and end only omits it");
@@ -566,26 +559,67 @@ export function validateManifest(manifest, path = "manifest") {
             }
         }
     }
-    if (manifest.taskTypePresentation !== undefined) {
-        if (!isPlainObject(manifest.taskTypePresentation)) {
-            into.add("manifest.taskTypePresentation.shape", `${path}.taskTypePresentation`, "taskTypePresentation must be an object when present");
+    return into.violations;
+}
+/** Language tags as BCP 47 writes them: a language, then subtags of up to eight letters or digits. */
+const LANGUAGE_TAG = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8})*$/;
+/** The customer's own words, as `Snapshot.labels` and `labels-updated` carry them. */
+export function validateLabels(value, path = "labels") {
+    const into = new Collector();
+    validateLabelsInto(value, path, into);
+    return into.violations;
+}
+function validateLabelsInto(value, path, into) {
+    if (!isPlainObject(value)) {
+        into.add("labels.shape", path, "labels are an object, empty when the customer set none");
+        return;
+    }
+    for (const [field, rule, allowed] of [["phases", "phase", TASK_PHASES], ["historySteps", "step", HISTORY_STEPS]]) {
+        if (value[field] === undefined)
+            continue;
+        if (!isPlainObject(value[field])) {
+            into.add(`labels.${field}.shape`, `${path}.${field}`, `${field} must be an object when present`);
+            continue;
         }
-        else {
-            for (const [taskType, presentation] of Object.entries(manifest.taskTypePresentation)) {
-                const at = `${path}.taskTypePresentation.${taskType}`;
-                if (!isPlainObject(presentation)) {
-                    into.add("manifest.taskTypePresentation.entry", at, "each presentation must be an object");
-                    continue;
-                }
-                into.filled(presentation.singular, "manifest.taskTypePresentation.singular", `${at}.singular`, "a presentation needs a singular name");
-                into.filled(presentation.plural, "manifest.taskTypePresentation.plural", `${at}.plural`, "a presentation needs a plural name");
-                if (presentation.referenceLabel !== undefined) {
-                    into.filled(presentation.referenceLabel, "manifest.taskTypePresentation.referenceLabel", `${at}.referenceLabel`, "referenceLabel must not be empty when present");
-                }
+        for (const [key, label] of Object.entries(value[field])) {
+            // Renames only: a label never adds a phase or a step the protocol does not have.
+            into.oneOf(key, allowed, `labels.${field}.${rule}`, `${path}.${field}.${key}`);
+            validateLocalizedText(label, `labels.${field}.label`, `${path}.${field}.${key}`, into);
+        }
+    }
+    if (value.taskTypes !== undefined) {
+        if (!isPlainObject(value.taskTypes)) {
+            into.add("labels.taskTypes.shape", `${path}.taskTypes`, "taskTypes must be an object when present");
+            return;
+        }
+        for (const [taskType, presentation] of Object.entries(value.taskTypes)) {
+            const at = `${path}.taskTypes.${taskType}`;
+            if (!isPlainObject(presentation)) {
+                into.add("labels.taskTypes.entry", at, "each task type's names must be an object");
+                continue;
+            }
+            validateLocalizedText(presentation.singular, "labels.taskTypes.singular", `${at}.singular`, into);
+            validateLocalizedText(presentation.plural, "labels.taskTypes.plural", `${at}.plural`, into);
+            if (presentation.referenceLabel !== undefined) {
+                validateLocalizedText(presentation.referenceLabel, "labels.taskTypes.referenceLabel", `${at}.referenceLabel`, into);
             }
         }
     }
-    return into.violations;
+}
+/** One text per language: at least one, each tag well-formed and stated once, each text filled. */
+function validateLocalizedText(value, rule, path, into) {
+    if (!isPlainObject(value) || Object.keys(value).length === 0) {
+        into.add(rule, path, `a label is one text per language, keyed by language tag, as { en: "On Call" }; received ${describeValue(value)}`);
+        return;
+    }
+    const seen = new Set();
+    for (const [tag, text] of Object.entries(value)) {
+        if (!into.require(LANGUAGE_TAG.test(tag), `${rule}.language`, `${path}.${tag}`, `${describeValue(tag)} is not a language tag such as en, hi or en-IN`))
+            continue;
+        into.require(!seen.has(tag.toLowerCase()), `${rule}.language.unique`, `${path}.${tag}`, "language tags are case-insensitive, and each language is stated once");
+        seen.add(tag.toLowerCase());
+        into.filled(text, `${rule}.text`, `${path}.${tag}`, "a label must not be empty in any language it is given in");
+    }
 }
 // ---------------------------------------------------------------------------
 // Task.
@@ -921,6 +955,10 @@ function validateHistory(value, path, into, task = {}) {
             return;
         }
         into.oneOf(entry.step, HISTORY_STEPS, "task.history.step", `${at}.step`);
+        // A call arrives once, before anything else happens to it.
+        if (entry.step === "arrived") {
+            into.require(index === 0, "task.history.arrived.first", `${at}.step`, "arrived is when the call reached the provider: the first step, and only once");
+        }
         if (into.timestamp(entry.at, "task.history.at", `${at}.at`)) {
             // The record is one entry per occurrence, oldest first: a second hold is a second entry
             // after the first, never a revision of it or an entry filed out of its turn.
@@ -957,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 `queued` nobody takes part, so there is nothing to name.
-            into.require(entry.step !== "queued", "task.history.by.unexpected", `${at}.by`, "a queued 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);
@@ -1789,6 +1827,8 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
     // The agent's own day, as the provider counts it: the same numbers their lead sees.
     if (snapshot.shift !== undefined)
         validateShiftInto(snapshot.shift, `${path}.shift`, into, "shift");
+    if (snapshot.labels !== undefined)
+        validateLabelsInto(snapshot.labels, `${path}.labels`, into);
     // The phone as the platform sees it: owed by a provider that declares it can, and by nobody else.
     const seesPhone = isPlainObject(manifest) && manifest.phoneStatus === true;
     // The agent's own queue: the ask and the lined-up call need an assignment at work to be next
@@ -2138,6 +2178,9 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
         case "shift-updated":
             validateShiftInto(event.shift, `${at}.shift`, into, "shift");
             break;
+        case "labels-updated":
+            validateLabelsInto(event.labels, `${at}.labels`, into);
+            break;
         case "calendar-updated":
             into.require(idle.calendar === true, "event.calendar.capability", `${at}.calendar`, "calendar-updated requires the calendar idle capability");
             if (!Array.isArray(event.calendar)) {

package/guide/agent.md

@@ -409,6 +409,8 @@ first, and what they add up to before this agent:
 ```ts
 history: {
   steps: [
+    { 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" },
@@ -429,9 +431,26 @@ 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 `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
+provider, before any menu or queue, and its `seconds`, when the provider measured them, are how
+long it took to move on to the next step. Nobody takes part in it, so it never has `by`. It is the
+first step and appears once (`task.history.arrived.first`); a provider that did not see the call
+arrive omits it rather than guessing an instant. Omni shows it as *Incoming call* unless the customer words it in
+`labels.historySteps`, the way
+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`.
+
 **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
@@ -465,7 +484,7 @@ hold, at the entry's `at` plus its `seconds`, and nothing is lost by not naming
 `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
-total the provider adds: *time to offer*, from the call's arrival to the agent's screen lighting
+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
 that interval. **The second is the record's grain.** A duration is a positive whole number of
@@ -541,7 +560,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
-`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
@@ -554,7 +573,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` 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

@@ -233,8 +233,6 @@ type Manifest<C extends Channel = Channel> = {
   idleCapabilities?: IdleCapabilities<C>;
   timeCheck?: true;
   timestampAuthority?: "provider";
-  phaseLabels?: TaskPhaseLabels;
-  taskTypePresentation?: Record<string, TaskTypePresentation>;
   orgLevels?: LevelDeclaration[];
   dialOutcomes?: C extends "voice" ? DialOutcome[] : never;
   phones?: C extends "voice" ? Phone[] : never;
@@ -259,12 +257,22 @@ These serialized strings are stable protocol values and must not be renamed or r
 ### Presentation
 
 ```ts
-type TaskPhaseLabels = Readonly<Partial<Record<TaskPhase, string>>>;
+type LanguageTag = string; // BCP 47: "en", "hi", "en-IN"
+type LocalizedText = Readonly<Record<LanguageTag, string>>;
+
+type TaskPhaseLabels = Readonly<Partial<Record<TaskPhase, LocalizedText>>>;
+type HistoryStepLabels = Readonly<Partial<Record<HistoryStep, LocalizedText>>>;
 
 type TaskTypePresentation = {
-  singular: string;
-  plural: string;
-  referenceLabel?: string;
+  singular: LocalizedText;
+  plural: LocalizedText;
+  referenceLabel?: LocalizedText;
+};
+
+type Labels = {
+  phases?: TaskPhaseLabels;
+  historySteps?: HistoryStepLabels;
+  taskTypes?: Readonly<Record<string, TaskTypePresentation>>;
 };
 ```
 
@@ -524,6 +532,7 @@ type Snapshot = {
   nextCall?: NextCallRequest;
   linedUp?: LinedUpCall;
   team?: TeamMembers;
+  labels?: Labels;
 };
 
 type AgentCapacity = {
@@ -686,6 +695,8 @@ type TaskAttribute = TaskAttributeBase & (
 );
 
 type HistoryStep =
+  | "arrived"
+  | "self-service"
   | "queued"
   | "offered"
   | "answered"
@@ -1218,7 +1229,8 @@ type ProviderEvent =
   | { type: "shift-updated"; shift: Shift }
   | { type: "phone-updated"; phone: PhoneState }
   | { type: "next-call"; nextCall?: NextCallRequest }
-  | { type: "lined-up"; linedUp?: LinedUpCall };
+  | { type: "lined-up"; linedUp?: LinedUpCall }
+  | { type: "labels-updated"; labels: Labels };
 
 type ProviderEventEnvelope = {
   id: string;
@@ -1351,8 +1363,8 @@ const OMNI_FAILURE_CODES = [
 type OmniFailureCode = (typeof OMNI_FAILURE_CODES)[number];
 ```
 
-`HISTORY_STEPS_WITH_A_PERSON` is every `HistoryStep` except `queued`, which is the one nobody
-takes part in. `historyStepExpectsAPerson()` tests membership.
+`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
 
@@ -1373,25 +1385,83 @@ interface ProtocolViolation {
 
 ## Presentation labels
 
-Adapters may supply static display labels for canonical protocol values. Labels affect presentation
-only and cannot vary by connection, task, snapshot, or event.
+**Each customer's admin chooses the words its agents see, in each language it serves**, in the
+provider, and the provider publishes them for the signed-in customer as `Snapshot.labels`,
+replaced whole by `labels-updated` when the admin changes them. Customer A's agents read *New call*
+where customer B's read *Entered*, on the same adapter, and a change reaches agents without an
+adapter release. That is how Genesys Cloud loads an organisation's presence names at sign-in and
+pushes the change when an admin edits one, and how Amazon Connect and NICE CXone keep agent state
+names per instance or business unit. A manifest is fixed when the adapter ships, so it carries no
+labels (`manifest.labels.moved`). `labels` is omitted, or `labels-updated` carries `{}`, when the
+customer set nothing, and the agent application shows its own words throughout.
+
+```ts
+labels: {
+  phases: { "in-progress": { en: "On Call", hi: "कॉल पर" } },
+  historySteps: { arrived: { en: "New call", hi: "नई कॉल" }, queued: { en: "Waiting" } },
+  taskTypes: { Support: { singular: { en: "Support call" }, plural: { en: "Support calls" }, referenceLabel: { en: "Case" } } },
+}
+```
+
+`validateLabels(value, path?)` checks one on its own.
+
+**Every word is per language.** Every label is a
+`LocalizedText`: one text per BCP 47 language tag, as `{ en: "On Call", hi: "कॉल पर" }`. The agent
+application finds the agent's language with `localizedText(text, languages)`, which tries each of
+the agent's languages in order, the tag whole and then without its last subtag, so `hi-IN` finds
+`hi`. When the provider wrote none of them, it returns nothing and the agent application shows its
+own word; it never shows another language in their place. A single string is the former shape and
+is refused (`labels.phases.label`, `labels.historySteps.label`,
+`labels.taskTypes.singular`), as are an empty text (`….text`), a key that is not a language tag
+(`….language`) and one language given twice in different case (`….language.unique`). This is how
+Genesys Cloud words its presence definitions and NICE CXone its agent states: the value is the
+platform's, and the words are per language.
+
+The values underneath never change: a customer renames what its agents see, so a lead's counts by
+phase or by step still add up.
 
 ### Renaming a phase
 
-`manifest.phaseLabels` renames the canonical `TaskPhase` values for the agent. It never adds a
-phase or removes one.
+`labels.phases` renames the canonical `TaskPhase` values for the agent. It never adds a
+phase or removes one (`labels.phases.phase`).
 
 `TaskPhaseLabels` is `Partial` so that renaming one phase keeps the default wording for the rest —
-an adapter changing "On Call" does not restate the other five.
+a customer changing "On Call" does not restate the other five.
 
-**A task is labelled by the provider that owns it**, from that provider's manifest merged over its
+**A task is labelled by the provider that owns it**, from that provider's `labels` merged over its
 channel defaults. Two adapters may word the same phase differently and each is right about its own
 tasks: a call reads as the voice platform names it while a chat beside it reads as its own does.
 How Omni words a view spanning several providers is its own presentation problem, not a provider's.
 
+### Naming the history steps
+
+`labels.historySteps` words the `HistoryStep` values the way `labels.phases` words phases: per
+step, per language, and partial, so a customer that calls `arrived` *Entered* restates nothing
+else. It never adds a step; a provider's own stages that the protocol has no step for are not
+labelled into existence (`labels.historySteps.step`).
+
+`DEFAULT_HISTORY_STEP_LABELS` is what Omni shows when the customer words a step in none of the
+agent's languages:
+
+```ts
+const DEFAULT_HISTORY_STEP_LABELS = {
+  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",
+} as const satisfies Readonly<Record<HistoryStep, string>>;
+```
+
 ### `DEFAULT_TASK_PHASE_LABELS`
 
-What Omni shows when an adapter overrides nothing.
+What Omni shows when the customer renames nothing.
 
 ```ts
 const DEFAULT_TASK_PHASE_LABELS = {
@@ -1426,14 +1496,14 @@ const DEFAULT_TASK_PHASE_LABELS = {
 
 ### Naming a kind of work
 
-`TaskTypePresentation` says what one kind of work is called. Unlike `phaseLabels`, an entry
-**replaces the channel default outright** rather than merging.
+`TaskTypePresentation` says what one kind of work is called, in `labels.taskTypes`. Unlike
+`labels.phases`, an entry **replaces the channel default outright** rather than merging.
 `singular` and `plural` are required together because pluralisation is not mechanical, and a
 half-supplied entry would leave Omni pairing one provider's noun with another's plural.
 
 ### `DEFAULT_TASK_TYPE_PRESENTATION`
 
-The per-channel fallback, used for any `taskType` the adapter does not name.
+The per-channel fallback, used for any `taskType` the customer does not name.
 
 ```ts
 const DEFAULT_TASK_TYPE_PRESENTATION = {
@@ -1453,21 +1523,21 @@ const DEFAULT_TASK_TYPE_PRESENTATION = {
     referenceLabel: "Email ID",
   },
 } as const satisfies Readonly<
-  Record<"voice" | "chat" | "email", TaskTypePresentation>
+  Record<"voice" | "chat" | "email", { singular: string; plural: string; referenceLabel: string }>
 >;
 ```
 
 ### Naming task types
 
 `channel` is too coarse for agent-facing names. A WhatsApp call and a PSTN call are both `voice`,
-but the provider may name them differently through static manifest metadata:
+but the customer may name them differently:
 
 ```ts
-const taskTypePresentation = {
+const taskTypes = {
   WhatsApp: {
-    singular: "Conversation",
-    plural: "Conversations",
-    referenceLabel: "Conversation ID",
+    singular: { en: "Conversation", hi: "बातचीत" },
+    plural: { en: "Conversations", hi: "बातचीतें" },
+    referenceLabel: { en: "Conversation ID" },
   },
 } satisfies Record<string, TaskTypePresentation>;
 ```
@@ -1710,8 +1780,6 @@ compile time.
 | `supportedProtocolVersions` | Required non-empty list of versions this adapter can speak. Must share at least one with Omni. |
 | `authenticationMethods` | Required non-empty list of supported login methods. |
 | `idleCapabilities` | Declares actions Omni may offer while the agent has no active task, such as voice dialing. Task controls do not belong here. |
-| `phaseLabels` | Optional static adapter-defined display names for canonical `TaskPhase` values. They cannot vary at runtime. |
-| `taskTypePresentation` | Optional static adapter-defined presentation keyed by exact `taskType`. It names the item and its optional agent-facing reference. |
 | `orgLevels` | The organisation's whole ladder as the provider calls it, each level with the label an agent computer shows for "who decided". Stated outright, `person` included: what it leaves out does not exist. Omitted for the typical four, `DEFAULT_LEVELS`. See **Who decides what an agent may do**. |
 | `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 login. See **How the agent hears the call** in `guide/phone.md`. |
 | `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`. |
@@ -2283,6 +2351,7 @@ a capability it agrees with the login: a lead's snapshot carries `team`, nobody
 | `phone` | The phone as the platform sees it -- the device, whether it can take a call, its own mute where observed -- from a provider whose manifest declares `phoneStatus`; required there (`snapshot.phone.required`) and forbidden otherwise (`snapshot.phone.unexpected`). Replaced whole by `phone-updated`. See **The phone's own view** in `guide/phone.md`. |
 | `nextCall` | The agent's standing ask for the next call, while it stands: `since`. It needs an assignment at work to be next after (`snapshot.nextCall.idle`) and the provider clears it when that assignment ends, when a call is lined up, and when the agent withdraws it. Replaced whole by `next-call`. See **The agent's own queue** in `guide/queue.md`. |
 | `linedUp` | The call waiting in the agent's own queue, while one is: the caller as shown to this audience, the queue, the caller's wait, when it was lined up, and `release` where the provider lets the agent let it go. Not a task yet. Replaced whole by `lined-up`. See **The agent's own queue** in `guide/queue.md`. |
+| `labels` | The signed-in customer's own words for phases, history steps and kinds of work, per language, as its admin set them in the provider. Replaced whole by `labels-updated`. Omitted where the customer set none. See **Presentation labels**. |
 | `shift` | The agent's own day so far, as the provider counts it -- the same `Shift` their lead sees on the team member list, the same numbers from the same count. Replaced whole by `shift-updated`. Omitted only where the provider cannot say. See **The agent's day is on the wire**. |
 | `team` | Required `TeamMembers` when the login declares `capabilities.lead` and the lead has the team feature on, `members: []` when nobody is in it. Forbidden otherwise — the login is the permission, and a lead who turned the feature off gets nothing of the team. |
 
@@ -2326,7 +2395,7 @@ Returns the provider's complete authoritative state at one point in time.
   snapshot is read is held until it lands, and what happens to it then depends on what it is. A
   snapshot restates state, so an event of a state-replacing kind -- `task-offered`, `task-updated`,
   `task-ended`, `task-audio-started`, `task-audio-ended`, `break-state`, `team-updated`,
-  `team-member-updated`, `team-member-removed`, `team-policies-updated`, `shift-updated`,
+  `team-member-updated`, `team-member-removed`, `team-policies-updated`, `shift-updated`, `labels-updated`,
   `contacts-updated`, `calendar-updated`, `transport-status`, `snapshot` -- is dropped, because the
   snapshot accounts for it. An event that reports a transaction no snapshot carries --
   `dial-outcome`, `diagnostic`, `announcement`, `queue-summary` -- is applied after the snapshot,
@@ -2892,6 +2961,11 @@ ended, a break ended, a sign-out -- and never to say nothing changed. It carries
 the agent's lead sees for them on the team member list, so the two screens show one day. See
 **The agent's day is on the wire**.
 
+### `labels-updated`
+
+The customer's words, whole, replacing `Snapshot.labels`: emitted when its admin changes them, and
+carrying `{}` when the admin has cleared them all. See **Presentation labels**.
+
 ## Utilities
 
 ### `assignmentKey(providerId, assignmentId)`
@@ -2939,6 +3013,7 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | `validateHostReport(report)` | The agent application's own report as published to an adapter: `online`, and where there is audio, an input that is `available` with the microphone and `flowing`, or `unavailable` with a reason and the failure that says why, and an output that is `available` or `unavailable` with its failure. The harness validates whatever agent application a test hands the adapter; `stillHost(report)` builds one that never changes. |
 | `validateNextCall(value)` | The agent's standing ask for the next call, on its own as `next-call` and `Snapshot.nextCall` carry it: since when, and nothing else (`nextCall.since`, `nextCall.field`). |
 | `validateLinedUp(value, path?, levels?)` | A call lined up in the agent's own queue, on its own as `lined-up` and `Snapshot.linedUp` carry it: the caller under the same contact rules as a task's party, the queue's label, the waits, and `release` by presence (`linedUp.*`). |
+| `validateLabels(value, path?)` | The customer's words on their own, as `labels-updated` and `Snapshot.labels` carry them: renames of the protocol's phases and steps only, and every word one text per well-formed language tag (`labels.*`). |
 | `validatePhoneState(value, path?, context?)` | The phone as the platform sees it, on its own as `phone-updated` and `Snapshot.phone` carry it: its status, its one active channel, its mute where a hardphone's is observed (`phone.*`). |
 | `validateHostMute(mute, softphone)` | What the agent application's Mute does, stated on a softphone login and nowhere else: `stream` or `station` (`host.mute`), required where the agent application holds a microphone (`host.mute.required`) and refused where it does not (`host.mute.unexpected`). The harness holds `ConnectContext.host.mute` to it. |
 | `validateLoginStore(store)` | The login's store the agent application hands every connection: an object with `get`, `set` and `delete` (`store.shape`, `store.get`, `.set`, `.delete`). The harness holds `ConnectContext.store` to it. |
@@ -3167,6 +3242,6 @@ Adapters should run the relevant scenarios against deterministic test state befo
 
 How a deployment themes Omni is the agent application's concern and is specified with the agent application, not here. What
 belongs in this contract is the boundary. A provider says what a control **is** through its
-capabilities and what its work is **called** through `phaseLabels` and `taskTypePresentation`; how
+capabilities and what its work is **called** through the customer's `labels`; how
 any of it is drawn is Omni's. A task cannot select a design language, inject a component, or
 override the agent's theme and font preferences.

package/package.json

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