@xema/omni-protocol 0.1.82 → 0.1.84

package/dist/index.d.ts

@@ -29,7 +29,7 @@ export type TaskId = string;
 /**
  * One life of a task on the wire. A platform retires a task id minutes after closing it and a
  * requeue takes seconds, so the same `TaskId` comes back for another customer while a late dial
- * outcome or a late handling report for the first is still in flight. The allocation id is minted
+ * outcome or a late interaction report for the first is still in flight. The allocation id is minted
  * once per offer and never reused for the life of the login, and every event, command and report
  * that names a task names its allocation too, so nothing lands on the next life of the id.
  */
@@ -153,6 +153,10 @@ export interface Manifest<C extends Channel = Channel> {
     supportedProtocolVersions: number[];
     authenticationMethods: AuthenticationMethod[];
     idleCapabilities?: IdleCapabilities<C>;
+    /** Optional provider-clock sampling through Connection.checkTime; absent means unsupported. */
+    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>;
@@ -176,13 +180,13 @@ export interface Manifest<C extends Channel = Channel> {
      */
     runningStepReports?: true;
     /**
-     * How long after an applied disposal -- `complete`, or a lead's `take-over` -- the provider's
+     * How long after an applied completion -- `complete`, or a lead's `take-over` -- the provider's
      * `task-ended` is owed, in milliseconds. A warm transfer's `complete` is not one: the agent's
      * wrap runs after it as after any call. `applied` says the provider
-     * has disposed of the task; the ending follows within this, or the host resyncs and shows the
+     * has completed the task; the ending follows within this, or the host resyncs and shows the
      * task as unsettled. Stated per provider, since platforms settle at different speeds.
      */
-    disposalSettleMs: number;
+    completionSettleMs: number;
 }
 export interface SecretStore {
     get(key: string): Promise<string | undefined>;
@@ -191,7 +195,7 @@ export interface SecretStore {
 }
 /**
  * A small store for one login's operational state -- what an adapter holds about open work that
- * its platform cannot hold for it, such as the handling legs a host reported. Kept by the host for
+ * its platform cannot hold for it, such as the interaction legs a host reported. Kept by the host for
  * the life of the login, across a reload of the host, and cleared at sign-out. Never for anything
  * sensitive: that is `SecretStore`, whose contract is that a host may clear it aggressively.
  */
@@ -366,7 +370,7 @@ export interface AuthenticationSession {
 /**
  * Who silenced a device that is present and permitted: the host, by its own Mute, or the station --
  * a slider on the headset, the operating system -- which the host observes and, on a browser,
- * cannot touch. The same word on a `muted` handling leg says whose the silence was.
+ * cannot touch. The same word on a `muted` interaction leg says whose the silence was.
  */
 export type MutedBy = "host" | "station";
 export declare const MUTED_BY: readonly ["host", "station"];
@@ -526,7 +530,20 @@ export interface HostGuarantees {
     /** A `consent` offer is accepted only by the person's own explicit act, never on their behalf. */
     personConsent?: true;
 }
+export interface ProviderTimeScope {
+    providerId: string;
+    loginId: string;
+}
+/** Best-effort host estimate, never a provider observation or accuracy guarantee. The provider may ignore it and timestamp receipt itself. */
+export interface ProviderTimeEstimate extends ProviderTimeScope {
+    at: IsoTimestamp;
+    clockId: string;
+    /** Estimated uncertainty only; not a guaranteed error bound. */
+    uncertaintyMs?: number;
+}
 export interface Host {
+    /** Optional current provider-clock estimate; undefined when no usable estimate exists. */
+    estimateProviderTime?(scope: ProviderTimeScope): ProviderTimeEstimate | undefined;
     /** Voice softphone recording support; policy and destination remain per task. */
     recording?: HostRecording;
     guarantees: HostGuarantees;
@@ -615,7 +632,7 @@ export interface DispositionRules {
 /**
  * One item the queue configured for the agent to send a contact to: a button or a menu item. The
  * protocol does not say what it does -- a queue, a menu, a line -- the provider executes it when a
- * command names its `id`. Never a named agent: who takes a contact next is the queue's decision.
+ * command names its `id`. The provider may publish a queue, IVR, named agent or other supported destination; the host does not invent one.
  */
 export interface Destination {
     id: string;
@@ -652,7 +669,7 @@ export interface SharedTaskCapabilities {
 export type TaskCapabilities<C extends Channel = Channel> = C extends "voice" ? SharedTaskCapabilities & {
     decline?: Lockable<true>;
     hold?: Lockable<true>;
-    /** The agent may end the whole call: everyone leaves and the media ends, the task stays for its wrap-up. */
+    /** The provider ends the caller connection and agent-added channels owned by this interaction, including inherited channels after transfer/takeover. Interaction completion remains separate. */
     endCall?: Lockable<true>;
     /** Connect back to the party while `completing`, whoever placed the call; the task returns to `in-progress`. */
     connectBack?: Lockable<true>;
@@ -718,14 +735,20 @@ export type TaskPhase =
 /** Accepted, and not yet started. */
  | "confirmed"
 /**
- * Voice only: the customer's record is on the agent's screen and no call has gone out. The agent
+ * Voice only: the customer's record is available for preparation, then dialing before answer. The agent
  * presses Call, or `previewEndsAt` arrives and `atDeadline` says what the system does instead.
  */
  | "preview" | "in-progress" | "paused"
 /** The work is over and the agent is finishing up. */
  | "completing";
 /** What the system does when a preview's deadline passes with no Call pressed. */
-export type PreviewDeadline = "calls" | "expires";
+export type PreviewDeadline = 
+/** Provider initiates dialing when preparation ends; never a host timer command. */
+"calls"
+/** Host initiates the ordinary call command when preparation ends. */
+ | "host-calls"
+/** Preparation target has elapsed; remain in preview until the agent presses Call. */
+ | "waits";
 /** Who ends the task: the agent issuing `complete`, or the provider deciding it is over. */
 export type CompletionMode = "agent-command" | "provider-automatic";
 export interface TaskAttributeBase {
@@ -742,7 +765,7 @@ export type TaskAttribute = TaskAttributeBase & ({
     type: "timestamp";
     at: IsoTimestamp;
 });
-export type HandlingStep = "queued" | "offered" | "answered" | "held" | "muted" | "transferred" | "conferenced" | "unanswered";
+export type InteractionStep = "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,
@@ -750,10 +773,10 @@ export type HandlingStep = "queued" | "offered" | "answered" | "held" | "muted"
  * 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;
+export interface TaskInteractionHistory {
+    steps: TaskInteractionStep[];
+    /** Seconds others spent working on it before this agent. */
+    interactionSeconds?: DurationSeconds;
     /** Seconds the caller spent on hold at others' hands. */
     holdSeconds?: DurationSeconds;
     /** Seconds waiting before anyone answered. */
@@ -761,8 +784,8 @@ export interface TaskHandlingHistory {
     /** How many times the task changed hands. */
     transfers?: number;
 }
-export interface TaskHandlingStep {
-    step: HandlingStep;
+export interface TaskInteractionStep {
+    step: InteractionStep;
     at: IsoTimestamp;
     /**
      * On a step that dialled -- `transferred`, `conferenced`, `unanswered` -- the host's identity for
@@ -785,7 +808,7 @@ export interface TaskHandlingStep {
     mutedBy?: MutedBy;
 }
 /**
- * How the task ends, and how long after handling the provider allows for it.
+ * How the task ends, and how long after interaction the provider allows for it.
  *
  * The allowance is coupled to the mode. Under `provider-automatic` the provider acts on it, so it
  * is required. Under `agent-command` the provider will not complete the task itself, so it may
@@ -958,16 +981,17 @@ export type Task<C extends Channel = Channel> = {
      */
     acceptance?: AcceptanceMode;
     /**
-     * In `preview` only, and together: when the system stops waiting for the agent to press Call,
-     * and what it does then -- `calls` places the call itself, `expires` takes the record back and
-     * the task ends `expired`. Absent, the agent has as long as they need.
+     * In `preview` only, and together: the preparation target and behavior when it elapses,
+     * and who acts then -- `calls` makes the provider initiate dialing, `host-calls` makes the
+     * host issue Call, and `waits` keeps waiting for the agent without dialing or ending the task.
+     * Absent, the agent has as long as they need, without a preparation countdown.
      */
     previewEndsAt?: IsoTimestamp;
     atDeadline?: PreviewDeadline;
     /** The identifier an agent reads back to a customer, where the provider has one. */
     reference?: string;
     attributes?: TaskAttribute[];
-    handlingHistory?: TaskHandlingHistory;
+    interactionHistory?: TaskInteractionHistory;
 } & TaskCompletion & (C extends "voice" ? {
     recording?: {
         provider?: RecordingState;
@@ -1048,7 +1072,7 @@ export type VoiceTaskCommand = {
 } | {
     type: "resume";
 }
-/** End the whole call: everyone leaves and the task's media ends; the task stays for its wrap-up. Gated by `endCall`. */
+/** End the caller connection and all agent-added channels owned or inherited by this interaction. Wrap/completion remain separate. Gated by `endCall`. */
  | {
     type: "end-call";
 }
@@ -1395,7 +1419,7 @@ export interface TeamBreakCommandRequest {
 }
 /**
  * The task's real-time audio as the provider holds it: `started` while audio should be attached,
- * `ended` once primary handling's audio ended, and the field omitted while none should be. The
+ * `ended` once primary interaction's audio ended, and the field omitted while none should be. The
  * provider's word -- a desk attaches and renders audio from it, never from its own senses.
  */
 export type TaskMediaState = "started" | "ended";
@@ -1457,14 +1481,14 @@ export type SetPreferenceRequest = {
     inherit: true;
 };
 /**
- * The host's report of a handling leg it performed itself -- a mute, which is the host's and
+ * The host's report of an interaction leg it performed itself -- a mute, which is the host's and
  * never the provider's -- 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 = {
+export type InteractionReport = {
     taskId: TaskId;
     allocationId: AllocationId;
     at: IsoTimestamp;
@@ -1474,7 +1498,7 @@ export type HandlingReport = {
     step: "muted";
     mutedBy: MutedBy;
 } | {
-    step: Exclude<HandlingStep, "muted">;
+    step: Exclude<InteractionStep, "muted">;
     mutedBy?: never;
 }) & ({
     ended: true;
@@ -1483,8 +1507,9 @@ export type HandlingReport = {
     ended?: never;
     seconds?: DurationSeconds;
 });
-export type HandlingReportResult = {
+export type InteractionReportResult = {
     status: "recorded";
+    at: IsoTimestamp;
 } | {
     status: "failed";
     failure: ProtocolFailure;
@@ -1636,7 +1661,28 @@ export interface Refusal {
     envelopeId?: string;
     violations: ProtocolViolation[];
 }
+/** Host-local opt-in configuration; no implicit interval or timeout. */
+export interface ProviderTimeCheckPolicy {
+    intervalMs: number;
+    timeoutMs: number;
+    maxRoundTripMs: number;
+    maxSampleAgeMs: number;
+}
+export interface ProviderTimeCheckRequest {
+    /** Fresh opaque correlation ID for one outstanding check, never reused on retry. */
+    requestId: string;
+}
+export interface ProviderTimeCheckResult {
+    requestId: string;
+    loginId: string;
+    /** Provider clock domain/incarnation; changes on clock discontinuity or authority replacement. */
+    clockId: string;
+    /** Provider-domain ISO instant sampled after this request arrived, before its response leaves. */
+    providerTime: IsoTimestamp;
+}
 export interface Connection<C extends Channel = Channel> {
+    /** Required only when Manifest.timeCheck is true. A read-only clock sample, never cached/replayed. */
+    checkTime?(request: ProviderTimeCheckRequest): Promise<ProviderTimeCheckResult>;
     snapshot(): Snapshot<C> | Promise<Snapshot<C>>;
     /** Delivery order must match the order the provider observes changes. Never replay. */
     subscribe(listener: (envelope: ProviderEventEnvelope<C>) => void): Unsubscribe;
@@ -1671,8 +1717,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 softphone login's connection: the host mutes its microphone on any call, and the record is the provider's. */
-    recordStep?(report: HandlingReport): Promise<HandlingReportResult>;
+    /** Records an interaction leg the host performed. Required of a softphone login's connection: the host mutes its microphone on any call, and the record is the provider's. */
+    recordStep?(report: InteractionReport): Promise<InteractionReportResult>;
 }
 export interface Adapter<C extends Channel = Channel> {
     manifest: Manifest<C>;
@@ -1743,13 +1789,13 @@ export declare const taskKey: (providerId: string, taskId: TaskId) => string;
  * same provider; anything wider goes through this.
  */
 export declare const userKey: (providerId: string, userId: UserId) => string;
-/** Every handling step somebody takes part in. `queued` is the one nobody does. */
-export declare const HANDLING_STEPS_WITH_A_PERSON: readonly ["offered", "answered", "held", "muted", "transferred", "conferenced", "unanswered"];
+/** Every interaction step somebody takes part in. `queued` is the one nobody does. */
+export declare const INTERACTION_STEPS_WITH_A_PERSON: readonly ["offered", "answered", "held", "muted", "transferred", "conferenced", "unanswered"];
 /** The steps a dial writes, and so the only ones that carry a `dialId` and a `destinationId`. */
-export declare const HANDLING_STEPS_THAT_DIAL: readonly ["transferred", "conferenced", "unanswered"];
-export declare const handlingStepDials: (step: HandlingStep) => boolean;
+export declare const INTERACTION_STEPS_THAT_DIAL: readonly ["transferred", "conferenced", "unanswered"];
+export declare const interactionStepDials: (step: InteractionStep) => boolean;
 /** Whether an absent `by` means "could not attribute" rather than "nobody was involved". */
-export declare function handlingStepExpectsAPerson(step: HandlingStep): boolean;
+export declare function interactionStepExpectsAPerson(step: InteractionStep): boolean;
 export interface BrowserSessionKeyInput {
     /** `Manifest.id`, never `displayName`: only the id is unique across an installation and stable. */
     providerId: string;

package/dist/index.js

@@ -159,19 +159,19 @@ export const taskKey = (providerId, taskId) => `${encodeURIComponent(providerId)
  * same provider; anything wider goes through this.
  */
 export const userKey = (providerId, userId) => `${encodeURIComponent(providerId)}:${encodeURIComponent(userId)}`;
-/** Every handling step somebody takes part in. `queued` is the one nobody does. */
-export const HANDLING_STEPS_WITH_A_PERSON = [
+/** Every interaction step somebody takes part in. `queued` is the one nobody does. */
+export const INTERACTION_STEPS_WITH_A_PERSON = [
     "offered", "answered", "held", "muted", "transferred", "conferenced", "unanswered",
 ];
 /** The steps a dial writes, and so the only ones that carry a `dialId` and a `destinationId`. */
-export const HANDLING_STEPS_THAT_DIAL = ["transferred", "conferenced", "unanswered"];
-export const handlingStepDials = (step) => HANDLING_STEPS_THAT_DIAL.includes(step);
-// Pinned both ways: a step added to `HandlingStep` has to be placed here, and a step listed here
+export const INTERACTION_STEPS_THAT_DIAL = ["transferred", "conferenced", "unanswered"];
+export const interactionStepDials = (step) => INTERACTION_STEPS_THAT_DIAL.includes(step);
+// Pinned both ways: a step added to `InteractionStep` has to be placed here, and a step listed here
 // has to exist there. `satisfies` on the list covers the second; this statement covers the first.
 true;
 /** Whether an absent `by` means "could not attribute" rather than "nobody was involved". */
-export function handlingStepExpectsAPerson(step) {
-    return HANDLING_STEPS_WITH_A_PERSON.includes(step);
+export function interactionStepExpectsAPerson(step) {
+    return INTERACTION_STEPS_WITH_A_PERSON.includes(step);
 }
 /**
  * Whether two logins declare the same capabilities, field by field. The comparison an adapter

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 roster, each
  * declared contribution, and each event type.
  */
-declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.handlingHistory", "task.onCall", "task.leadAssist", "task.assisting", "task.monitoring", "task.media", "task.acceptance", "task.dispositions", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.imposed", "team.members", "team.requests", "contacts", "scheduledActivities", "team.policies"];
+declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.interactionHistory", "task.onCall", "task.leadAssist", "task.assisting", "task.monitoring", "task.media", "task.acceptance", "task.dispositions", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.imposed", "team.members", "team.requests", "contacts", "scheduledActivities", "team.policies"];
 export type ContractSubject = (typeof STATE_SUBJECTS)[number] | `event.${ProviderEvent["type"]}`;
 export interface AdapterContractResult {
     events: ProviderEventEnvelope[];
@@ -190,15 +190,18 @@ export declare class TaskStream {
 }
 /** What a stream has said about the agent's break, and the moves it may not make. */
 export declare class BreakStream {
-    private approval;
-    /** Takes the break state a snapshot carries as the point the stream continues from. */
-    seed(snapshot: unknown): void;
-    /** Applies one envelope and returns the moves it may not make given where the break stood. */
+    private state;
+    private recovery;
+    /** True until a validated authoritative snapshot establishes a usable baseline. */
+    get needsRecovery(): boolean;
+    /** Caller establishes snapshot freshness/login scope separately; malformed state never replaces the baseline. */
+    seed(snapshot: unknown): ProtocolViolation[];
+    /** Rejected transitions keep accepted state and require snapshot recovery before further deltas. */
     apply(envelope: unknown, path?: string): ProtocolViolation[];
 }
 /**
- * A break follows its requests. Given a provider's stream -- optionally seeded with the snapshot
- * it began from -- every `break-state` moves the way the guide describes: a commit's states only
+ * A break follows its requests. Given a provider's stream -- seeded with its initial snapshot,
+ * either supplied separately or carried by a snapshot event -- every `break-state` moves the way the guide describes: a commit's states only
  * after a grant, never backwards, and a break placed on the agent arriving in effect with `imposed`.
  */
 export declare function assertBreakFollowsItsRequests(envelopes: readonly ProviderEventEnvelope[], snapshot?: Snapshot): void;