@xema/omni-protocol 0.1.116 → 0.1.118

package/dist/validation.js

@@ -9,7 +9,7 @@
 // Each list is pinned to its type both ways -- a member the type lacks, or a member the list
 // lacks, fails to compile -- so what the validators accept cannot drift from what the
 // declarations say.
-import { RECORDING_ACTIONS, SHIFT_EVENT_KINDS, ALLOWED_BROWSER_URL_SCHEMES, BREAK_KINDS, BROWSER_ISOLATION_SCHEMES, HISTORY_STEPS_THAT_DIAL, IDLE_CAPABILITIES, OMNI_FAILURE_CODES, OMNI_SUPPORTED_PROTOCOL_VERSIONS, TASK_COMMAND_NAMES, negotiateProtocolVersion, DEFAULT_LEVELS, effectiveLevels, } from "./index.js";
+import { RECORDING_ACTIONS, SHIFT_EVENT_KINDS, RECORDING_SIDES, RECORDING_STATUSES, RECORDING_PAUSED_REASONS, RECORDING_UNKNOWN_REASONS, ALLOWED_BROWSER_URL_SCHEMES, BREAK_KINDS, BROWSER_ISOLATION_SCHEMES, HISTORY_STEPS_THAT_DIAL, IDLE_CAPABILITIES, OMNI_FAILURE_CODES, OMNI_SUPPORTED_PROTOCOL_VERSIONS, TASK_COMMAND_NAMES, negotiateProtocolVersion, DEFAULT_LEVELS, effectiveLevels, } from "./index.js";
 export class ProtocolConformanceError extends Error {
     violations;
     constructor(violations, summary = "Adapter violates the Omni protocol") {
@@ -49,7 +49,7 @@ const TRANSPORT_STATUSES = membersOf({ connecting: true, active: true, error: tr
 const AUTHENTICATION_METHODS = membersOf({ "browser-sso": true, credentials: true });
 const AUTHENTICATION_BROWSERS = membersOf({ system: true, omni: true });
 const AUTHENTICATION_STATUSES = membersOf({
-    "signed-out": true, authenticating: true, authenticated: true, refreshing: true, expired: true,
+    "signed-out": true, authenticating: true, authenticated: true, refreshing: true, expired: true, terminated: true,
 });
 const BREAK_APPROVALS = membersOf({
     "not-requested": true, "awaiting-approval": true, granted: true, "starting-after-task": true, "on-break": true,
@@ -59,6 +59,7 @@ const TEAM_AVAILABILITIES = membersOf({
 });
 const HISTORY_STEPS = membersOf({
     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 });
 const CUSTOM_UI_PLACEMENTS = membersOf({ primary: true, secondary: true, overflow: true });
@@ -1214,16 +1215,11 @@ function validateTaskInto(task, context, path, into) {
     if (context.locked !== undefined && isPlainObject(task.party) && (isLocked(task.party.number) || isLocked(task.party.email))) {
         validateNothingLeaksInto(task, context.locked, path, into);
     }
-    if (task.recording !== undefined) {
-        into.require(context.channel === "voice", "recording.task.channel", `${path}.recording`, "recording is voice-only");
-        if (!isPlainObject(task.recording))
-            into.add("recording.task.shape", `${path}.recording`, "expected provider recording state");
-        else {
-            for (const key of Object.keys(task.recording))
-                into.require(key === "provider", "recording.task.owner", `${path}.recording.${key}`, "host state belongs in HostReport, never provider task updates");
-            if (task.recording.provider !== undefined)
-                into.violations.push(...validateRecordingState(task.recording.provider, `${path}.recording.provider`));
-        }
+    // The provider's own recordings, a list; the host's are on its report, never on a provider's task.
+    into.require(task.recording === undefined, "recording.task.renamed", `${path}.recording`, "a task carries the provider's recordings as recordings, a list with the side each follows; the former recording state is not accepted");
+    if (task.recordings !== undefined) {
+        into.require(context.channel === "voice", "recording.task.channel", `${path}.recordings`, "recording is voice-only");
+        into.violations.push(...validateRecordings(task.recordings, `${path}.recordings`));
     }
     if (context.member !== true)
         validateBrowsers(task.browsers, `${path}.browsers`, into);
@@ -2786,7 +2782,7 @@ export function validateTaskCommand(command, task, path = "command", taskContext
             if (!offered("recording"))
                 break;
             const policy = isPlainObject(capabilities.recording) ? capabilities.recording.provider : undefined;
-            const state = isPlainObject(task.recording) ? task.recording.provider : undefined;
+            const state = task.recordings ?? [];
             into.violations.push(...validateRecordingCommandState(command, policy, state, path));
             if (command.action === "start" || command.action === "resume") {
                 interaction();
@@ -3131,18 +3127,28 @@ export function validateAuthenticationState(state, path = "authentication", cont
         validateUser(state.identity, "authentication.identity", `${path}.identity`, into);
         validateUserCapabilitiesInto(state.capabilities, `${path}.capabilities`, into, context.levels);
     }
-    else if (state.status === "expired") {
+    else if (state.status === "expired" || state.status === "terminated") {
         if (state.identity !== undefined)
             validateUser(state.identity, "authentication.identity", `${path}.identity`, into);
         if (state.failure !== undefined) {
             validateAuthenticationFailureInto(state.failure, `${path}.failure`, into);
         }
+        if (state.status === "terminated") {
+            // Ended from outside this agent computer: who did it, and why, and nothing to retry.
+            into.require(isUserId(state.by) || state.by === "provider", "authentication.terminated.by", `${path}.by`, "a terminated session says who ended it: the person by user id, or provider where the platform did");
+            if (into.require(isPlainObject(state.failure), "authentication.terminated.failure", `${path}.failure`, "a terminated session carries the reason it was ended")) {
+                into.require(state.failure.retryable === false, "authentication.terminated.retryable", `${path}.failure.retryable`, "a session ended from outside is over: its failure is not retryable");
+            }
+        }
     }
     else {
         into.require(state.identity === undefined, "authentication.identity.unexpected", `${path}.identity`, `${state.status} must not carry an identity`);
     }
     if (state.failure !== undefined) {
-        into.require(state.status === "expired", "authentication.failure.unexpected", `${path}.failure`, "only an expired state may carry a failure");
+        into.require(state.status === "expired" || state.status === "terminated", "authentication.failure.unexpected", `${path}.failure`, "only an expired or terminated state may carry a failure");
+    }
+    if (state.by !== undefined) {
+        into.require(state.status === "terminated", "authentication.by.unexpected", `${path}.by`, "only a terminated session says who ended it; the agent's own sign-out is signed-out");
     }
     if (state.expiresAt !== undefined) {
         into.require(state.status === "authenticated", "authentication.expiresAt.unexpected", `${path}.expiresAt`, "only an authenticated state may carry an expiry");
@@ -3153,7 +3159,7 @@ export function validateAuthenticationState(state, path = "authentication", cont
     }
     return into.violations;
 }
-// Independent current recording evidence and dispatch validation.
+// Recordings: published on change, restated whole, never expiring; and dispatch validation.
 const object = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 const filled = (v) => typeof v === "string" && v.trim().length > 0;
 function collector() {
@@ -3170,40 +3176,49 @@ function collector() {
     };
     return { violations, check, keys };
 }
-/** Recording observations use canonical UTC millisecond instants, never native capture boundaries. */
-function instant(v) {
-    if (typeof v !== "string" || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(v))
-        return false;
-    const n = Date.parse(v);
-    return Number.isFinite(n) && new Date(n).toISOString() === v;
-}
-export function validateRecordingState(value, path = "recording") {
+/** A recording that is, or may be, capturing: its side has no room for a second start. */
+const LIVE_RECORDING = ["starting", "recording", "paused", "unknown"];
+/**
+ * One recorder's recordings for one task, as published: each with its id, the side it follows,
+ * its status, and a reason where it is paused or unknown; ids unique, and at most one recording
+ * live on each side at once.
+ */
+export function validateRecordings(value, path = "recordings") {
     const { violations, check, keys } = collector();
-    if (!object(value)) {
-        check(false, "state.shape", path, "expected recording state");
-        return violations;
-    }
-    if (value.status === "unknown") {
-        keys(value, ["status"], path);
+    if (!Array.isArray(value)) {
+        check(false, "list.shape", path, "recordings are a list, empty when nothing has been recorded");
         return violations;
     }
-    check(["inactive", "active", "paused"].includes(value.status), "state.status", `${path}.status`, "expected unknown, inactive, active or paused");
-    keys(value, ["status", "observationId", "observedAt", "validUntil", ...(value.status === "inactive" ? [] : ["recordingId"])], path);
-    check(filled(value.observationId), "observationId", `${path}.observationId`, "a confirming observation has an opaque identity");
-    check(instant(value.observedAt), "observedAt", `${path}.observedAt`, "expected canonical UTC millisecond observation instant");
-    check(instant(value.validUntil), "validUntil", `${path}.validUntil`, "expected canonical UTC millisecond expiry instant");
-    if (instant(value.observedAt) && instant(value.validUntil))
-        check(value.observedAt < value.validUntil, "expiry", path, "expiry must be strictly after observation");
-    if (value.status !== "inactive")
-        check(filled(value.recordingId), "recordingId", `${path}.recordingId`, "active and paused states identify the actual recording");
+    const ids = new Set();
+    const live = new Set();
+    value.forEach((entry, index) => {
+        const at = `${path}[${index}]`;
+        if (!object(entry)) {
+            check(false, "shape", at, "a recording is an object");
+            return;
+        }
+        keys(entry, ["id", "follows", "status", "reason"], at);
+        check(filled(entry.id), "id", `${at}.id`, "a recording names itself by its recorder's id");
+        check(!ids.has(entry.id), "id.unique", `${at}.id`, "two recordings share an id");
+        ids.add(entry.id);
+        check(RECORDING_SIDES.includes(entry.follows), "follows", `${at}.follows`, "a recording follows the party's side or the agent's");
+        if (!check(RECORDING_STATUSES.includes(entry.status), "status", `${at}.status`, "a recording is starting, recording, paused, not-recording or unknown"))
+            return;
+        const reasons = entry.status === "paused" ? RECORDING_PAUSED_REASONS
+            : entry.status === "unknown" ? RECORDING_UNKNOWN_REASONS : undefined;
+        if (reasons !== undefined) {
+            check(reasons.includes(entry.reason), "reason", `${at}.reason`, `a ${String(entry.status)} recording says why: ${reasons.join(", ")}`);
+        }
+        else {
+            check(entry.reason === undefined, "reason.unexpected", `${at}.reason`, "only a paused or unknown recording carries a reason");
+        }
+        if (LIVE_RECORDING.includes(entry.status)) {
+            check(!live.has(entry.follows), "follows.live", `${at}.follows`, `the ${String(entry.follows)} side already has a recording that is, or may be, capturing`);
+            live.add(entry.follows);
+        }
+    });
     return violations;
 }
-/** Supply a trusted current instant in the observer's clock domain. Undefined means clock unknown. */
-export function effectiveRecordingState(state, now) {
-    if (state === undefined || validateRecordingState(state).length || state.status === "unknown" || now === undefined || !Number.isFinite(now))
-        return { status: "unknown" };
-    return Date.parse(state.observedAt) <= now && now < Date.parse(state.validUntil) ? state : { status: "unknown" };
-}
 export function validateRecordingPolicy(value, path = "capabilities.recording") {
     const { violations, check, keys } = collector();
     if (!object(value)) {
@@ -3276,12 +3291,12 @@ export function validateHostRecordings(value, path = "host.recordings") {
             check(false, "report.shape", at, "expected scoped report");
             return;
         }
-        keys(report, ["assignmentId", "state"], at);
+        keys(report, ["assignmentId", "recordings"], at);
         check(filled(report.assignmentId), "report.scope", at, "report identifies the assignment");
         const key = JSON.stringify([report.assignmentId]);
-        check(!seen.has(key), "report.duplicate", at, "one host state per assignment");
+        check(!seen.has(key), "report.duplicate", at, "one host report per assignment");
         seen.add(key);
-        violations.push(...validateRecordingState(report.state, `${at}.state`));
+        violations.push(...validateRecordings(report.recordings, `${at}.recordings`));
     });
     return violations;
 }
@@ -3291,50 +3306,62 @@ export function validateRecordingCommandShape(value, source, path = "command") {
         check(false, "command.shape", path, "expected recording command");
         return violations;
     }
-    keys(value, ["type", "source", "observationId", "action", ...(value.action === "start" ? [] : ["recordingId"])], path);
+    const starting = value.action === "start";
+    keys(value, ["type", "source", "action", starting ? "follows" : "recordingId"], path);
     check(value.type === "recording" && value.source === source, "command.source", path, `this executor accepts only ${source} recording commands`);
     check(RECORDING_ACTIONS.includes(value.action), "command.action", `${path}.action`, "unsupported recording action");
-    for (const key of ["observationId", ...(value.action === "start" ? [] : ["recordingId"])])
-        check(filled(value[key]), "command.identity", `${path}.${key}`, "expected nonempty scoped identity");
+    if (starting)
+        check(RECORDING_SIDES.includes(value.follows), "command.follows", `${path}.follows`, "a start names the side to record: party or agent");
+    else
+        check(filled(value.recordingId), "command.identity", `${path}.recordingId`, "every action but start names the recording by its id");
     return violations;
 }
 /** One transition table shared by dispatch checks and outcome checks. */
 const RECORDING_TRANSITIONS = {
-    start: { from: ["inactive"], to: "active" },
-    pause: { from: ["active"], to: "paused" },
-    resume: { from: ["paused"], to: "active" },
-    stop: { from: ["active", "paused"], to: "inactive" },
-    cancel: { from: ["active", "paused"], to: "inactive" },
+    pause: { from: ["recording"], to: "paused" },
+    resume: { from: ["paused"], to: "recording" },
+    stop: { from: ["recording", "paused"], to: "not-recording" },
+    cancel: { from: ["recording", "paused"], to: "not-recording" },
 };
 function recordingTransition(action) {
     return typeof action === "string" && Object.hasOwn(RECORDING_TRANSITIONS, action)
         ? RECORDING_TRANSITIONS[action] : undefined;
 }
-/** Structural/state permission check. Dispatch MUST also call validateRecordingRequest for scope and freshness. */
-export function validateRecordingCommandState(command, policy, state, path = "command") {
+const entries = (value) => Array.isArray(value) ? value.filter(object) : [];
+/**
+ * Whether the action is permitted on this recorder, and whether the recordings as last published
+ * let it act: a start on a side with nothing capturing, every other action on the recording it
+ * names, standing where the action needs it. Dispatch MUST also call validateRecordingRequest.
+ */
+export function validateRecordingCommandState(command, policy, recordings, path = "command") {
     const { violations, check } = collector();
     if (!object(command)) {
         check(false, "command.shape", path, "expected recording command");
         return violations;
     }
-    const transition = recordingTransition(command.action);
-    if (transition === undefined) {
+    if (!RECORDING_ACTIONS.includes(command.action)) {
         check(false, "command.action", `${path}.action`, "unsupported recording action");
         return violations;
     }
     const permitted = object(policy) && policy[command.action] === true;
     check(permitted, "command.permission", path, "task does not permit this action on this recorder");
-    if (!object(state) || validateRecordingState(state).length) {
-        check(false, "command.state", path, "no validated current recorder observation");
+    if (recordings !== undefined && validateRecordings(recordings).length) {
+        check(false, "command.state", path, "the recordings as published are malformed");
         return violations;
     }
-    check(transition.from.includes(state.status), "command.state", path, "action is invalid in the observed recorder state");
-    check(command.observationId === state.observationId, "command.stale", path, "observation changed; reconcile before acting");
-    if (command.action !== "start")
-        check(command.recordingId === state.recordingId, "command.recordingId", path, "command targets another recording");
+    const list = entries(recordings);
+    if (command.action === "start") {
+        check(!list.some(entry => entry.follows === command.follows && LIVE_RECORDING.includes(entry.status)), "command.state", path, `the ${String(command.follows)} side already has a recording that is, or may be, capturing`);
+        return violations;
+    }
+    const target = list.find(entry => entry.id === command.recordingId);
+    if (!check(target !== undefined, "command.recordingId", path, "no recording on this task has that id"))
+        return violations;
+    const transition = recordingTransition(command.action);
+    check(transition.from.includes(target.status), "command.state", path, `${String(command.action)} needs the recording ${transition.from.join(" or ")}, and it is ${String(target.status)}`);
     return violations;
 }
-/** Validate immediately before dispatch using current task, host report and trusted observer-domain time. */
+/** Validate immediately before dispatch, against the current task and, for the host's recorder, its declaration and report. */
 export function validateRecordingRequest(request, task, context, path = "request") {
     const { violations, check, keys } = collector();
     if (!object(request) || !object(task)) {
@@ -3352,58 +3379,69 @@ export function validateRecordingRequest(request, task, context, path = "request
     const caps = object(task.capabilities) ? task.capabilities.recording : undefined;
     violations.push(...validateRecordingPolicy(caps)); // a locked or missing capability cannot dispatch
     const policy = object(caps) ? caps[context.source] : undefined;
-    let state = object(task.recording) ? task.recording.provider : undefined;
+    let recordings = task.recordings ?? [];
     if (context.source === "host") {
         violations.push(...validateHostRecording(context.host, context.softphone === true));
         check(object(context.host), "host.required", path, "host did not declare recording support");
         const reports = object(context.hostReport) ? context.hostReport.recordings : undefined;
         violations.push(...validateHostRecordings(reports));
-        state = Array.isArray(reports) ? reports.find(r => object(r) && r.assignmentId === task.assignmentId)?.state : undefined;
+        const report = Array.isArray(reports) ? reports.find(r => object(r) && r.assignmentId === task.assignmentId) : undefined;
+        recordings = object(report) ? report.recordings : [];
         if (object(context.host)) {
             check(Array.isArray(context.host.actions) && context.host.actions.includes(command.action), "host.action", path, "host does not support action");
             check(object(policy) && Array.isArray(context.host.storageIds) && context.host.storageIds.includes(policy.storageId), "host.storage", path, "task storage is not one this host provisions");
         }
     }
-    const fresh = effectiveRecordingState(state, context.now);
-    check(fresh.status !== "unknown", "request.freshness", path, "current state or trusted observer time unavailable/expired");
-    violations.push(...validateRecordingCommandState(command, policy, fresh, `${path}.command`));
+    violations.push(...validateRecordingCommandState(command, policy, recordings, `${path}.command`));
     const opening = command.action === "start" || command.action === "resume";
     check(opening ? ["in-progress", "paused"].includes(task.phase) && task.audio === "started" : ["in-progress", "paused", "completing"].includes(task.phase), "request.phase", path, "capture needs live task audio; terminal controls may finish recordings during wrap-up");
     return violations;
 }
-/** Check recording-specific result semantics against the owner's confirming observations. */
+/**
+ * A recording command's answer against the recordings published before and after it: applied
+ * means the recorder confirmed what was asked -- a new recording on the side for a start, the
+ * same recording in its new status for anything else -- and failed means nothing changed there.
+ */
 export function validateRecordingOutcome(command, before, after, result, path = "recordingOutcome") {
     const { violations, check } = collector();
-    violations.push(...validateRecordingState(before, `${path}.before`), ...validateRecordingState(after, `${path}.after`));
-    if (!object(command) || !object(before) || !object(after)) {
-        check(false, "outcome.shape", path, "command and both observations required");
+    violations.push(...validateRecordings(before, `${path}.before`), ...validateRecordings(after, `${path}.after`));
+    if (!object(command) || !Array.isArray(before) || !Array.isArray(after)) {
+        check(false, "outcome.shape", path, "command and both lists of recordings required");
         return violations;
     }
     violations.push(...validateRecordingCommandShape(command, command.source === "host" ? "host" : "provider", `${path}.command`));
-    // A rejected promise has no result: any independently evidenced state may follow it.
+    // A rejected promise has no result: any state its recorder publishes may follow it.
     if (result === undefined)
         return violations;
     violations.push(...validateResult(result, "execute", `${path}.result`));
     if (!object(result))
         return violations;
     check(result.status === "applied" || result.status === "failed", "outcome.result", path, "recording never returns a dialling result");
+    const prior = entries(before);
+    const next = entries(after);
+    if (command.action === "start") {
+        const fresh = next.filter(entry => entry.follows === command.follows && !prior.some(old => old.id === entry.id));
+        if (result.status === "applied") {
+            check(fresh.some(entry => entry.status === "recording"), "outcome.state", path, "an applied start shows a new recording on that side, recording");
+            check(!prior.some(entry => entry.follows === command.follows && LIVE_RECORDING.includes(entry.status)), "outcome.origin", path, "applied cannot claim a start on a side already capturing");
+        }
+        else if (result.status === "failed") {
+            check(!fresh.some(entry => LIVE_RECORDING.includes(entry.status)), "outcome.noEffect", path, "a failed start leaves nothing capturing on that side");
+        }
+        return violations;
+    }
+    const was = prior.find(entry => entry.id === command.recordingId);
+    const now = next.find(entry => entry.id === command.recordingId);
     if (result.status === "failed") {
-        check(before.status !== "unknown" && after.status === before.status && after.recordingId === before.recordingId, "outcome.noEffect", path, "failed promises confirmed no effect; ambiguous or partial effects have no result");
+        check(was !== undefined && now !== undefined && now.status === was.status, "outcome.noEffect", path, "failed confirms no effect: the recording stands as it was; a partial effect is unknown, unsettled");
     }
     else if (result.status === "applied") {
         const transition = recordingTransition(command.action);
         if (transition === undefined)
             return violations; // shape validation already reported the unknown action
-        check(after.status === transition.to, "outcome.state", path, "applied requires the confirming requested state");
-        check(after.observationId !== before.observationId, "outcome.observation", path, "an applied transition needs new confirming evidence");
-        check(before.observationId === command.observationId, "outcome.stale", path, "command must act against its named observation");
-        check(transition.from.includes(before.status), "outcome.origin", path, "applied cannot claim an impossible transition");
-        if (command.action !== "start")
-            check(command.recordingId === before.recordingId, "outcome.recordingId", path, "command must target the prior recording");
-        if (command.action === "pause" || command.action === "resume")
-            check(after.recordingId === before.recordingId, "outcome.continuity", path, "pause/resume preserves recording identity");
-        if (instant(before.observedAt) && instant(after.observedAt))
-            check(after.observedAt >= before.observedAt, "outcome.order", path, "clock discontinuity requires reconciliation, not a reversed confirmation");
+        check(now !== undefined, "outcome.continuity", path, "the recording keeps its id through the action");
+        check(now?.status === transition.to, "outcome.state", path, `applied requires the recording ${transition.to}`);
+        check(was !== undefined && transition.from.includes(was.status), "outcome.origin", path, "applied cannot claim an impossible transition");
     }
     return violations;
 }

package/guide/agent.md

@@ -384,10 +384,14 @@ Migration from the earlier spellings:
 | the phone unspoken | `PhoneState` -- the device, its mute, its channels -- on `Snapshot.phone`, `phone-updated` and `TeamMember.phone`, from a manifest declaring `phoneStatus` (`snapshot.phone.required`, `.unexpected`, `phone.*`, `phone.channel.*`, `event.phone.capability`) |
 | the agent's readiness for the next call read into setCapacity | the agent's own queue: `capabilities.nextCall`, `requestNextCall`/`cancelNextCall`/`releaseLinedUp`, `Snapshot.nextCall` and `linedUp`, the `next-call` and `lined-up` events (`snapshot.nextCall.idle`, `nextCall.*`, `linedUp.*`) |
 | a harness that exercised an adapter, drove a call and evaluated rules | the harness reads as a test: `testAdapter`, `withCall`, `timeoutMs`, `notTested`, `rulesTested`, rules `test.*` (`test.timeout`, `test.offer.expired`, `test.preview.deadline`, ...) |
+| a `callback-requested` step, and a callback task starting its history afresh | a `callback-requested` step (`by` when an agent arranged it); a callback's task carries the earlier call's steps, oldest first |
+| a recording state with an observation id, an observation instant and a validity window, and the helpers that aged it | `recordings` on the task and on `HostRecordingReport`: a list, each recording with `id`, `follows` (`party` or `agent`), `status` (`starting`, `recording`, `paused`, `not-recording`, `unknown`) and a `reason` where paused or unknown; nothing expires; commands name `follows` for a start and `recordingId` otherwise; `validateRecordings` (`recording.task.renamed` refuses the former field) |
+| a refusal on hold under `omni.command-not-permitted` | `omni.on-hold` |
 | an `end-call` while the caller was on hold | refused: a `paused` task is resumed first (`command.endCall.held`), the agent computer shows End call disabled on hold, the provider answers `failed`, and the test names an adapter that ends from hold (`test.command.held`); `terminate-call` is not gated, it ends the caller's channel too |
 | the handset spelled by its place on a desk | `hardphone`, on the manifest's `phones` and the login's `phone`; the former spelling is refused |
 | the desk | the agent computer, in the guide's prose |
 | the agent application's Mute on hold | unavailable while the task is `paused`, promised at login by a softphone login's agent application (`host.guarantees.muteUnavailableOnHold`, required there and refused of a hardphone login); a host mute beginning on a paused task is refused (`historyReport.muted.held`) and the test names an adapter that records one (`test.recordStep.held`) |
+| a session ended from outside the agent computer, reported as `expired` | `terminated`, with `by` (a person or `provider`) and a reason never retryable; `signed-out` is only the agent's own Sign out here; an ended session's secrets are deleted before the ending is published (`authentication.secrets.retained`), kept only for an `expired` whose failure is retryable; the agent application clears the store after, and resumes no stored token |
 
 Update producers, consumers, saved task snapshots, and validation-rule assertions together.
 History and report rule names use `history` and `historyReport`; assignment rules use
@@ -425,7 +429,20 @@ 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`,
-`unanswered`, and each is defined on `TaskHistoryStep`.
+`unanswered`, `callback-requested`, and each is defined on `TaskHistoryStep`.
+
+**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
+task's history carries the earlier call's steps, oldest first, the `callback-requested` step among them,
+then the callback's own -- as a hand-over carries the steps before it. The agent opening a callback
+sees that the caller waited and asked, or whose promise they are keeping, and a second try reads as
+one, the way contact-centre platforms keep a callback with its original contact.
+
+**One call has one history.** Every task the call reaches restates the earlier steps exactly as they
+stood: the same step, instant, person, dial and destination, and a duration once stated never
+changes. `assertHistoryAgreesAcrossTasks(earlier, later)` holds two tasks of one call to that, for an
+adopter's own test that drives a hand-over, take-over or callback.
 
 **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
@@ -1098,6 +1115,7 @@ react rather than only display the message:
 | `omni.unavailable` | The provider is temporarily unable to serve the action, including any command sent while `transport-status` is not `active`. |
 | `omni.break-already-committed` | Cancellation lost the commit/cancel race; Omni must finish commit recovery. |
 | `omni.recording-unsettled` | A recording command the provider could not settle either way: a settled `failed`, never a promise left unresolved. See **Independent task recording** in `guide/voice.md`. |
+| `omni.on-hold` | Refused because the caller is on hold: the agent application's own Mute begun on a `paused` task, or `end-call` there. The agent application says resume first. The test expects this code on both (`test.recordStep.held`, `test.command.held`). |
 | `omni.break-forced-by-provider` | A lead asked to lift a break the platform imposed; the platform lifts its own. See **Forced breaks** in `guide/breaks.md`. |
 
 They are published as `OMNI_FAILURE_CODES`.

package/guide/phone.md

@@ -238,7 +238,7 @@ softphone the agent application's own Mute is unavailable while the task is `pau
 promised at login (`muteUnavailableOnHold`): mute then hold is ordinary, and the muted leg runs on
 across the held one; hold then mute is not, and a `muted` leg with `mutedBy: "host"` beginning on a
 paused task is held back by the agent application (`historyReport.muted.held`) and refused by a
-provider that receives one anyway. The test sends one past the validator while the task is held
+provider that receives one anyway, `failed` with `omni.on-hold`. The test sends one past the validator while the task is held
 and names an adapter that records it (`test.recordStep.held`). A station mute the agent
 application observes on hold -- the headset's slider, the operating system -- is a fact, reported
 with `mutedBy: "station"`, and stands. The agent application reports every such period