@xema/omni-protocol 0.1.30 → 0.1.32

package/dist/index.d.ts

@@ -113,6 +113,12 @@ export interface Manifest<C extends Channel = Channel> {
     taskTypePresentation?: Record<string, TaskTypePresentation>;
     /** The organisation's whole ladder, stated outright, `person` included. Omitted for the typical four, `DEFAULT_LEVELS`. */
     orgLevels?: LevelDeclaration[];
+    /**
+     * The provider takes running reports of a host-performed step -- `recordStep` with `seconds`
+     * so far and no `ended`. Absent, the host sends exactly two reports per leg, when it began and
+     * when it ended, and a running report is refused: what a provider never asked for never crosses.
+     */
+    runningStepReports?: true;
 }
 export interface SecretStore {
     get(key: string): Promise<string | undefined>;
@@ -493,6 +499,24 @@ export type TaskAttribute = TaskAttributeBase & ({
     at: IsoTimestamp;
 });
 export type HandlingStep = "queued" | "offered" | "answered" | "held" | "muted" | "transferred" | "conferenced" | "unanswered";
+/**
+ * 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,
+ * never summed by a desk from instants. Each total is present when the provider knows it and
+ * absent when it does not; a plausible nought is the fallback the no-fallbacks rule forbids. The
+ * record rides on the task and is replaced with it, so a late entry corrects the sums.
+ */
+export interface TaskHandlingHistory {
+    steps: TaskHandlingStep[];
+    /** Seconds others spent handling it before this agent. */
+    handleSeconds?: DurationSeconds;
+    /** Seconds the caller spent on hold at others' hands. */
+    holdSeconds?: DurationSeconds;
+    /** Seconds waiting before anyone answered. */
+    queueSeconds?: DurationSeconds;
+    /** How many times the task changed hands. */
+    transfers?: number;
+}
 export interface TaskHandlingStep {
     step: HandlingStep;
     at: IsoTimestamp;
@@ -617,7 +641,7 @@ export type Task<C extends Channel = Channel> = {
     /** The identifier an agent reads back to a customer, where the provider has one. */
     reference?: string;
     attributes?: TaskAttribute[];
-    handlingHistory?: TaskHandlingStep[];
+    handlingHistory?: TaskHandlingHistory;
 } & TaskCompletion & (C extends "voice" ? {
     consultation?: TaskConsultation;
     lead?: TaskLead;
@@ -1025,6 +1049,31 @@ export type SetPreferenceRequest = {
     id: PreferenceId;
     inherit: true;
 };
+/**
+ * The host's report of a handling leg it performed itself -- a mute, which Omni does rather than
+ * the provider -- so the provider's record has an account of it. Keyed by `step` and `at`: the
+ * same entry is reported when it begins, as often as the host cares to while it runs, and once
+ * more with `ended`, when `seconds` is the final duration. The host is the authority for the
+ * legs it performs, so `seconds` may say how long so far at any time; the end is stated, never
+ * inferred from a number's presence. What the adapter forwards upstream, and how often, is its own.
+ */
+export type HandlingReport = {
+    taskId: TaskId;
+    step: HandlingStep;
+    at: IsoTimestamp;
+} & ({
+    ended: true;
+    seconds: DurationSeconds;
+} | {
+    ended?: never;
+    seconds?: DurationSeconds;
+});
+export type HandlingReportResult = {
+    status: "recorded";
+} | {
+    status: "failed";
+    failure: ProtocolFailure;
+};
 export type PreferenceResult = {
     status: "applied";
 } | {
@@ -1168,6 +1217,8 @@ export interface Connection<C extends Channel = Channel> {
     openMedia?(request: OpenMediaRequest): Promise<OpenMediaResult>;
     /** Required when the login declares `capabilities.preferences`: the person's own choice, kept by the provider and republished as `authenticated`. */
     setPreference?(request: SetPreferenceRequest): Promise<PreferenceResult>;
+    /** Records a handling leg the host performed. Required of a connection whose tasks may declare `mute`. */
+    recordStep?(report: HandlingReport): Promise<HandlingReportResult>;
 }
 export interface Adapter<C extends Channel = Channel> {
     manifest: Manifest<C>;

package/dist/testing.js

@@ -52,7 +52,7 @@ function observeTask(value, seen) {
         seen.add("task.browsers");
     if (some(value.attributes))
         seen.add("task.attributes");
-    if (some(value.handlingHistory))
+    if (isRecord(value.handlingHistory) && some(value.handlingHistory.steps))
         seen.add("task.handlingHistory");
     if (value.consultation !== undefined)
         seen.add("task.consultation");
@@ -289,6 +289,8 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             }
             if (eventNamesUsers(envelope))
                 requireMethod(live, "describeUsers", "an event publishes a UserId");
+            if (eventDeclaresMute(envelope))
+                requireMethod(live, "recordStep", "a task declares mute, which the host performs and must have somewhere to record");
             // Cross-event rules apply once the stream has a beginning: the connect snapshot.
             if (seeded)
                 violations.push(...stream.apply(envelope), ...breaks.apply(envelope));
@@ -308,6 +310,9 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         requireCapabilityMethods(live, current().capabilities);
         if (publishesUserIds(snapshot))
             requireMethod(live, "describeUsers", "the snapshot publishes a UserId");
+        if (isRecord(snapshot) && Array.isArray(snapshot.tasks) && snapshot.tasks.some(taskDeclaresMute)) {
+            requireMethod(live, "recordStep", "a task declares mute, which the host performs and must have somewhere to record");
+        }
         // Capacity is stated, not requested: nothing may be allocated until it is, so a connection
         // that will not accept one is a connection nothing can be given to.
         // The guide's obligation on a voice adapter: consult the host before declaring the agent
@@ -398,9 +403,21 @@ function publishesUserIds(snapshot) {
     return snapshot.tasks.some(taskNamesUsers);
 }
 const teamNamesUsers = (team) => isRecord(team) && (some(team.members) || some(team.requests));
-const taskNamesUsers = (task) => isRecord(task) && ((Array.isArray(task.handlingHistory) && task.handlingHistory.some(step => isRecord(step) && step.by !== undefined)) ||
+const taskNamesUsers = (task) => isRecord(task) && ((isRecord(task.handlingHistory) && Array.isArray(task.handlingHistory.steps) && task.handlingHistory.steps.some(step => isRecord(step) && step.by !== undefined)) ||
     (isRecord(task.lead) && task.lead.leadId !== undefined) ||
     isRecord(task.assisting));
+/** Mute is the leg the host performs, so a task that allows it obliges the provider to take the record. */
+const taskDeclaresMute = (task) => isRecord(task) && isRecord(task.capabilities) && task.capabilities.mute !== undefined;
+function eventDeclaresMute(envelope) {
+    const event = isRecord(envelope) ? envelope.event : undefined;
+    if (!isRecord(event))
+        return false;
+    if (event.type === "task-offered" || event.type === "task-updated")
+        return taskDeclaresMute(event.task);
+    if (event.type === "snapshot" && isRecord(event.snapshot) && Array.isArray(event.snapshot.tasks))
+        return event.snapshot.tasks.some(taskDeclaresMute);
+    return false;
+}
 /** Whether an event publishes a `UserId`, on a roster, a task, or the snapshot a reconnect carries. */
 function eventNamesUsers(envelope) {
     const event = isRecord(envelope) ? envelope.event : undefined;

package/dist/validation.d.ts

@@ -49,9 +49,15 @@ export declare function validateEventEnvelope(envelope: unknown, manifest: unkno
  * promise withheld is an absent key, never a false one, exactly as a capability is.
  */
 export declare function validateHostGuarantees(guarantees: unknown, path?: string): ProtocolViolation[];
+/**
+ * What the host reports of a leg it performed, as an adapter may validate it before forwarding:
+ * a task, a step, when it began, how long so far if the host says, and an explicit end that
+ * carries the final duration.
+ */
+export declare function validateHandlingReport(report: unknown, path?: string, manifest?: unknown): ProtocolViolation[];
 export declare function validateHostReport(report: unknown, path?: string): ProtocolViolation[];
 /** The connection methods whose results `validateResult` knows. */
-export type ResultMethod = "execute" | "dial" | "setCapacity" | "requestBreak" | "commitBreak" | "cancelBreak" | "endBreak" | "executeTeamBreak" | "executeTeamConsult" | "openMedia" | "setPreference" | "executeTeamPolicy";
+export type ResultMethod = "execute" | "dial" | "setCapacity" | "requestBreak" | "commitBreak" | "cancelBreak" | "endBreak" | "executeTeamBreak" | "executeTeamConsult" | "openMedia" | "setPreference" | "recordStep" | "executeTeamPolicy";
 /**
  * Validates what a connection method answered. A result is untrusted for the same reason a
  * snapshot is: it comes from an adapter that may be compiled against another version, and Omni

package/dist/validation.js

@@ -312,6 +312,9 @@ export function validateManifest(manifest, path = "manifest") {
             }
         }
     }
+    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");
+    }
     if (manifest.orgLevels !== undefined) {
         if (!Array.isArray(manifest.orgLevels)) {
             into.add("manifest.orgLevels.shape", `${path}.orgLevels`, "orgLevels must be an array when present");
@@ -628,18 +631,41 @@ function validateTaskAttributes(value, path, into) {
 function validateHandlingHistory(value, path, into) {
     if (value === undefined)
         return;
-    if (!Array.isArray(value)) {
-        into.add("task.handlingHistory.shape", path, "handlingHistory must be an array when present");
+    if (!isPlainObject(value)) {
+        into.add("task.handlingHistory.shape", path, "handlingHistory must be an object with its steps when present");
         return;
     }
-    value.forEach((entry, index) => {
-        const at = `${path}[${index}]`;
+    // What the record adds up to before this agent: each total present when the provider knows it
+    // and absent when it does not, never a plausible nought.
+    for (const field of ["handleSeconds", "holdSeconds", "queueSeconds"]) {
+        if (value[field] !== undefined) {
+            into.require(isDurationSeconds(value[field]), `task.handlingHistory.${field}`, `${path}.${field}`, `${field} must be a whole number of seconds, zero or more, or omitted when unknown`);
+        }
+    }
+    if (value.transfers !== undefined) {
+        into.require(typeof value.transfers === "number" && Number.isInteger(value.transfers) && value.transfers >= 0, "task.handlingHistory.transfers", `${path}.transfers`, "transfers must be a whole number, zero or more, or omitted when unknown");
+    }
+    if (!Array.isArray(value.steps)) {
+        into.add("task.handlingHistory.steps.shape", `${path}.steps`, "handlingHistory carries its steps as an array, empty when the task has had none");
+        return;
+    }
+    let previous;
+    value.steps.forEach((entry, index) => {
+        const at = `${path}.steps[${index}]`;
         if (!isPlainObject(entry)) {
             into.add("task.handlingHistory.entry", at, "each handling step must be an object");
             return;
         }
         into.oneOf(entry.step, HANDLING_STEPS, "task.handlingHistory.step", `${at}.step`);
-        into.timestamp(entry.at, "task.handlingHistory.at", `${at}.at`);
+        if (into.timestamp(entry.at, "task.handlingHistory.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.
+            const instant = Date.parse(entry.at);
+            if (previous !== undefined && instant < previous) {
+                into.add("task.handlingHistory.order", `${at}.at`, "handling steps are oldest first; this entry is earlier than the one before it");
+            }
+            previous = instant;
+        }
         if (entry.seconds !== undefined) {
             // Omitted while a leg is still running. Nought is a claim that it took no time.
             into.require(isDurationSeconds(entry.seconds) && entry.seconds > 0, "task.handlingHistory.seconds", `${at}.seconds`, "seconds must be a positive whole number; omit it while the step is still running");
@@ -1391,6 +1417,35 @@ export function validateHostGuarantees(guarantees, path = "host.guarantees") {
     }
     return into.violations;
 }
+/**
+ * What the host reports of a leg it performed, as an adapter may validate it before forwarding:
+ * a task, a step, when it began, how long so far if the host says, and an explicit end that
+ * carries the final duration.
+ */
+export function validateHandlingReport(report, path = "handlingReport", manifest) {
+    const into = new Collector();
+    if (!isPlainObject(report)) {
+        into.add("handlingReport.shape", path, "a handling report must be an object");
+        return into.violations;
+    }
+    into.require(isTaskId(report.taskId), "handlingReport.taskId", `${path}.taskId`, "a report names the task");
+    into.oneOf(report.step, HANDLING_STEPS, "handlingReport.step", `${path}.step`);
+    into.timestamp(report.at, "handlingReport.at", `${path}.at`);
+    if (report.seconds !== undefined) {
+        into.require(isDurationSeconds(report.seconds) && report.seconds > 0, "handlingReport.seconds", `${path}.seconds`, "seconds must be a positive whole number; omit it rather than report nought");
+    }
+    if (report.ended !== undefined) {
+        if (into.require(report.ended === true, "handlingReport.ended", `${path}.ended`, "ended is declared by presence, as true; a running leg omits it")) {
+            into.require(report.seconds !== undefined, "handlingReport.ended.seconds", `${path}.seconds`, "an ended leg states its final duration");
+        }
+    }
+    else if (report.seconds !== undefined && manifest !== undefined) {
+        // A running report crosses only to a provider that asked for one: begin and end are the whole
+        // of what the rest receive.
+        into.require(isPlainObject(manifest) && manifest.runningStepReports === true, "handlingReport.running.unexpected", `${path}.seconds`, "this provider takes begin and end only; a running report was never asked for");
+    }
+    return into.violations;
+}
 export function validateHostReport(report, path = "host") {
     const into = new Collector();
     if (!isPlainObject(report)) {
@@ -1456,6 +1511,7 @@ const RESULT_STATUSES = {
     executeTeamConsult: { success: "applied", failure: "failed" },
     openMedia: { success: "opened", failure: "unavailable" },
     setPreference: { success: "applied", failure: "failed" },
+    recordStep: { success: "recorded", failure: "failed" },
     executeTeamPolicy: { success: "applied", failure: "failed" },
 };
 /**

package/guide.md

@@ -178,6 +178,7 @@ type Manifest<C extends Channel = Channel> = {
   phaseLabels?: TaskPhaseLabels;
   taskTypePresentation?: Record<string, TaskTypePresentation>;
   orgLevels?: LevelDeclaration[];
+  runningStepReports?: true;
 };
 ```
 
@@ -360,6 +361,15 @@ type SetPreferenceRequest =
   | { id: PreferenceId; enabled: boolean }
   | { id: PreferenceId; inherit: true };
 
+type HandlingReport = { taskId: TaskId; step: HandlingStep; at: IsoTimestamp } & (
+  | { ended: true; seconds: DurationSeconds }
+  | { ended?: never; seconds?: DurationSeconds }
+);
+
+type HandlingReportResult =
+  | { status: "recorded" }
+  | { status: "failed"; failure: ProtocolFailure };
+
 type PreferenceResult =
   | { status: "applied" }
   | { status: "failed"; failure: ProtocolFailure };
@@ -549,6 +559,14 @@ type HandlingStep =
   | "conferenced"
   | "unanswered";
 
+type TaskHandlingHistory = {
+  steps: TaskHandlingStep[];
+  handleSeconds?: DurationSeconds;
+  holdSeconds?: DurationSeconds;
+  queueSeconds?: DurationSeconds;
+  transfers?: number;
+};
+
 type TaskHandlingStep = {
   step: HandlingStep;
   at: IsoTimestamp;
@@ -607,7 +625,7 @@ type Task<C extends Channel = Channel> = {
   acceptance?: AcceptanceMode;
   reference?: string;
   attributes?: TaskAttribute[];
-  handlingHistory?: TaskHandlingStep[];
+  handlingHistory?: TaskHandlingHistory;
 } & TaskCompletion & (
   C extends "voice"
     ? { consultation?: TaskConsultation; lead?: TaskLead; assisting?: TaskAssisting; media?: TaskMediaState }
@@ -990,6 +1008,7 @@ type Connection<C extends Channel = Channel> = {
   executeTeamConsult?(request: TeamConsultCommandRequest): Promise<TeamCommandResult>;
   openMedia?(request: OpenMediaRequest): Promise<OpenMediaResult>;
   setPreference?(request: SetPreferenceRequest): Promise<PreferenceResult>;
+  recordStep?(report: HandlingReport): Promise<HandlingReportResult>;
   executeTeamPolicy?(request: TeamPolicyCommandRequest): Promise<TeamCommandResult>;
 };
 
@@ -1382,6 +1401,7 @@ compile time.
 | `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 a desk 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**. |
+| `runningStepReports` | The provider takes running reports of a host-performed step — `recordStep` with `seconds` so far and no `ended`. Omitted, the host sends exactly two reports per leg, when it began and when it ended, and a running one is refused. See **The host records what it performs**. |
 
 ### Authentication methods
 
@@ -1886,6 +1906,7 @@ surface in one place, and what obliges an adapter to implement each one.
 | `executeTeamBreak(command)` | The login declares `capabilities.team.breakControl`. |
 | `executeTeamConsult(command)` | The login declares `capabilities.team.consultControl`. |
 | `setPreference(request)` | The login declares `capabilities.preferences`: the person's choice has to have somewhere to go. |
+| `recordStep(report)` | A task declares `mute`: the host performs that leg, and the provider's record has to have somewhere to take it. See **The host records what it performs**. |
 | `executeTeamPolicy(command)` | The login declares `capabilities.team.policyControl`. |
 | `openMedia(request)` | The manifest channel is `voice`. Every voice task's audio lands in Omni, so there is no voice adapter that does not implement it. |
 
@@ -2090,7 +2111,7 @@ time. Runtime conformance checks also require the task channel to match its prov
 | `completionMode` | `agent-command` waits for the channel's `complete` command; `provider-automatic` completes without one. |
 | `wrapAllowance` | Fixed time allowed to complete the task after primary handling ends. For real-time media, it begins after `task-media-ended`. Required under `provider-automatic`, where the provider acts on it. Optional under `agent-command`: omitted says the provider imposes no deadline, and Omni counts nothing down. |
 | `attributes` | Optional ordered, typed `TaskAttribute` entries with keys unique within the task. Each contact or timestamp is a separate array item; new attribute shapes require new union members. |
-| `handlingHistory` | Optional ordered handling history for this currently open task. It is live task data, not a permanent archive. |
+| `handlingHistory` | The call record: `steps` — the ordered handling history of this open task, one entry per occurrence, oldest first — and what they add up to before this agent, `handleSeconds`, `holdSeconds`, `queueSeconds`, `transfers`, each present when the provider knows it. Live task data restated with the task, not a permanent archive. See **How a task has been handled**. |
 | `consultation` | Voice only. Present while the agent is consulting a transfer destination: who is being consulted, and since when where the provider records it. Its presence is what makes `transfer` `complete` and `cancel` issuable. `label` is a name for the destination -- a person, a queue -- not a phrase; the host supplies the verb. See **Consult transfer**. |
 | `lead` | Voice only. Present from the agent's request for a lead until the lead leaves or the request ends: `requested` while nobody has joined, `joined` with the lead's `leadId` once somebody has. See **Consulting a lead**. |
 | `assisting` | Voice only, on the lead's own task for a call they joined: which member asked, with their note. Its presence is what makes `lead` `take-over` and `leave` issuable. See **Consulting a lead**. |
@@ -2254,13 +2275,23 @@ const immediateProviderCompletion = {
 
 ### How a task has been handled
 
-`Task.handlingHistory` is the sequence of steps that brought the task to the agent, oldest first:
+`Task.handlingHistory` is the call record: the steps that brought the task to the agent, oldest
+first, and what they add up to before this agent:
 
 ```ts
-handlingHistory: [
-  { step: "queued",   at: "2026-08-21T00:59:00Z", seconds: 41 },
-  { step: "answered", at: "2026-08-21T00:59:41Z", by: "a-17" },
-]
+handlingHistory: {
+  steps: [
+    { 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" },
+    { step: "transferred", at: "2026-08-21T01:04:53Z", by: "a-17" },
+    { step: "answered",    at: "2026-08-21T01:05:02Z", by: "a-23" },
+  ],
+  handleSeconds: 312,   // handled by others before this agent
+  holdSeconds: 35,      // holds others put the caller on
+  queueSeconds: 41,     // waiting before anyone answered
+  transfers: 1,         // hands the call has changed
+}
 ```
 
 **This is not an archive.** It is live data about a task that is still open: it travels with the task
@@ -2273,6 +2304,16 @@ It rides in the snapshot and is replaced whole like everything else there.
 Steps are `queued`, `offered`, `answered`, `held`, `muted`, `transferred`, `conferenced`,
 `unanswered`, and each is defined on `TaskHandlingStep`.
 
+**The record is one entry per occurrence, oldest first.** Each hold is its own `held` entry — `at`
+when it began, `seconds` once it ended and omitted while it runs — and a second hold is a second
+entry after the first, never a revision of it. The same goes for every step: two mutes are two
+`muted` entries. Order is enforced: an entry earlier than the one before it is refused
+(`task.handlingHistory.order`). **Handle time is anchored, not restarted.** It runs from the
+`answered` step's `at` — from the task's first `in-progress` where the provider reports no
+history — until the task's media ends, and a hold neither pauses nor resets it: the hold's own
+duration is the `held` entry's `seconds`, and a desk that restarts its counter on resume is
+counting the wrong thing.
+
 `muted` is there because Omni performs the mute rather than the provider — see **Where a command
 executes** — so without a step the one participant that keeps the task's record would have no
 account of a period the agent could not be heard.
@@ -2309,8 +2350,46 @@ A host must render the two differently. Showing an unattributed `answered` the s
 `queued` 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 `handlingHistory` entirely when the provider cannot observe the steps. An empty array is a different
-claim — it says the task has had none.
+Omit `handlingHistory` entirely when the provider cannot observe the steps. Empty `steps` is a
+different claim — it says the task has had none.
+
+**What the record adds up to is stated, not summed.** A call that has changed hands arrives
+carrying what others already used of it, and the agent reads that before they say hello: the
+totals are the provider's own — never a desk summing instants that may be rounded or skewed, for
+the same reason `seconds` is reported and not derived — and each is present when the provider
+knows it and absent when it does not, never a plausible nought. A fresh call from the queue has
+`steps` with no prior `answered` and no totals to state, and a desk shows nothing rather than
+zeros. The record is restated with the task on every `task-updated` and snapshot, so an entry
+that arrives late corrects the sums. These four are what every platform reports; more will be
+added here as a need is shown, not invented ahead of one.
+
+#### The host records what it performs
+
+`muted` is the one leg Omni performs rather than the provider, and a record kept by the provider
+would have a hole exactly there. So the host reports it, through `recordStep`, and the provider
+writes it into its record as it writes every other leg:
+
+```ts
+declare const connection: Connection<"voice">;
+declare const taskId: TaskId;
+declare const at: IsoTimestamp;
+
+void connection.recordStep?.({ taskId, step: "muted", at });                          // the moment the agent mutes
+void connection.recordStep?.({ taskId, step: "muted", at, seconds: 15 });             // still running, if the host chooses to say
+void connection.recordStep?.({ taskId, step: "muted", at, seconds: 42, ended: true }); // the moment they unmute
+```
+
+The entry is keyed by `step` and `at`, so every report about one leg names the same instant. The
+host is the authority for the legs it performs, so it may say how long so far — `seconds` is
+elapsed while the leg runs and final once it has ended — and **the end is stated, never
+inferred**: `ended: true` marks the last report, and it carries the final duration. **What a
+provider never asked for never crosses.** The running report is sent only to a provider whose
+manifest declares `runningStepReports`; every other provider receives exactly two reports per
+leg, when it began and when it ended, and `validateHandlingReport(report, path, manifest)` refuses
+a running one it was never asked for (`handlingReport.running.unexpected`). What a provider that
+did ask for them forwards upstream, and how often, is its own business. The step appears in
+`handlingHistory` when the *provider* publishes it: Omni never writes the record itself.
+`recordStep` is required of a connection whose tasks declare `mute`, and answers `recorded`.
 
 ### Browser capability
 
@@ -2706,6 +2785,7 @@ everywhere; success is not.
 | Method | Succeeded |
 | --- | --- |
 | `setCapacity` | `applied` |
+| `recordStep` | `recorded` |
 | `requestBreak` | `requested` |
 | `commitBreak` | `committed` |
 | `cancelBreak` | `cancelled` |
@@ -3702,6 +3782,7 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | `validateContact(contact)` | Contact field shapes and attribute keys. Every field is optional, so this checks what is present rather than what is missing. |
 | `validateScheduledActivity(activity)` | Required activity fields and start/end ordering. |
 | `validateHostGuarantees(guarantees)` | What a host promises: only the guarantees this contract names, each declared by presence and never `false`. The harness validates the guarantees of whatever host a test hands the adapter. |
+| `validateHandlingReport(report, path?, manifest?)` | What the host reports of a leg it performed, for an adapter to check before forwarding: a task, a step, when it began, a positive `seconds` where stated, and an explicit `ended` that carries the final duration. Given the manifest, a running report is refused unless it declares `runningStepReports`. |
 | `validateHostReport(report)` | The host'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 host a test hands the adapter; `stillHost(report)` builds one that never changes. |
 | `validateResult(result, method)` | What a connection method answered: the status it gives, a failure where the status says so and nowhere else, the failure's shape, and that an `omni.` code is one this contract names. |
 | `validateAuthenticationState(state)` | The identity each state must carry, the capabilities a usable login declares, and the expiry that only `authenticated` may. Omni applies it to every state a session publishes — the republished as much as the first. |

package/package.json

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