@xema/omni-protocol 0.1.66 → 0.1.68

package/dist/index.d.ts

@@ -26,6 +26,14 @@ export type IsoTimestamp = string;
 export type UserId = string;
 /** A non-empty, opaque task identifier unique within one provider. Scope it with `taskKey()`. */
 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
+ * 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.
+ */
+export type AllocationId = string;
 /**
  * The host's identity for one dial, minted before the command leaves and unique across the
  * installation. A dial is the one command whose outcome arrives later and apart, so the provider
@@ -442,8 +450,8 @@ export type ConnectContext = {
     protocolVersion: number;
     /** The session that authenticated this connection. */
     loginId: string;
-    /** Omni-side policy: whether the agent's tasks are accepted without asking them. */
-    autoAcceptTasks?: boolean;
+    /** Omni-side policy: whether the agent's tasks are accepted without asking them. Stated, never assumed: a host says which. */
+    autoAcceptTasks: boolean;
     /**
      * The zone the agent's day is reckoned in, the same value passed as
      * `AuthenticationContext.timeZone`. The provider stores it on the agent and carries it on the
@@ -713,13 +721,24 @@ export declare const ON_CALL_ROLES: readonly ["party", "agent", "consulted", "co
  * either way, and the `stage` it has reached: `ringing` until the dial is answered, `joined` after,
  * stated so a snapshot says who is present without anyone having seen the outcome. Nobody ringing is
  * held. `label` names a destination -- a person, a queue -- not a phrase. At most one `party` and
- * one `consulted`: the consult commands name neither because there is exactly one.
+ * one `consulted`: the consult commands name neither because there is exactly one. The `party`
+ * carries a `stage` only while being dialled again on the same task -- a connect-back the host
+ * placed, carrying its `dialId`, or a callback the platform places itself, carrying none --
+ * `ringing` from the moment the dial is placed and `joined` on its answered outcome, so a host can
+ * show a call being placed rather than assert one that is still ringing. A party with no stage is
+ * on the call.
  */
 export type OnCall = {
     since: IsoTimestamp;
     held?: true;
 } & ({
     role: "party";
+    dialId?: never;
+    stage?: never;
+} | {
+    role: "party";
+    stage: OnCallStage;
+    dialId?: DialId;
 } | {
     role: "agent";
     userId: UserId;
@@ -759,6 +778,7 @@ export interface TaskAssisting {
 export interface TaskMonitoring {
     memberId: UserId;
     taskId: TaskId;
+    allocationId: AllocationId;
     mode: MonitorMode;
     since: IsoTimestamp;
 }
@@ -815,6 +835,8 @@ export type CapabilitySource = "queue" | "ungoverned" | "undetermined";
 export declare const CAPABILITY_SOURCES: readonly ["queue", "ungoverned", "undetermined"];
 export type Task<C extends Channel = Channel> = {
     id: TaskId;
+    /** This life of the task: minted once per offer, never reused for the life of the login. See `AllocationId`. */
+    allocationId: AllocationId;
     title: string;
     channel: C;
     /** The provider's own name for a category of work. Finer-grained than a channel. */
@@ -1024,6 +1046,7 @@ export interface CustomTaskCommand {
 export type TaskCommand<C extends Channel = Channel> = (C extends "voice" ? VoiceTaskCommand : C extends "chat" ? ChatTaskCommand : EmailTaskCommand) | CustomTaskCommand;
 export interface TaskCommandRequest<C extends Channel = Channel> {
     taskId: TaskId;
+    allocationId: AllocationId;
     command: TaskCommand<C>;
 }
 /**
@@ -1171,6 +1194,7 @@ export interface LeadRequest {
     id: string;
     memberId: UserId;
     taskId: TaskId;
+    allocationId: AllocationId;
     note?: string;
     since: IsoTimestamp;
 }
@@ -1269,6 +1293,7 @@ export interface VoiceMediaSession {
 }
 export interface OpenMediaRequest {
     taskId: TaskId;
+    allocationId: AllocationId;
     /** The agent's microphone as Omni captured it, `HostReport.audio.input.localAudio`; absent while that input is `unavailable`. */
     localAudio?: MediaStream;
 }
@@ -1328,6 +1353,7 @@ export type SetPreferenceRequest = {
  */
 export type HandlingReport = {
     taskId: TaskId;
+    allocationId: AllocationId;
     at: IsoTimestamp;
 } & (
 /** A muted leg says whose the silence was: the host's own Mute, or the station's slider or system. */
@@ -1416,12 +1442,15 @@ export type ProviderEvent<C extends Channel = Channel> = {
 } | {
     type: "task-media-started";
     taskId: TaskId;
+    allocationId: AllocationId;
 } | {
     type: "task-media-ended";
     taskId: TaskId;
+    allocationId: AllocationId;
 } | {
     type: "task-ended";
     taskId: TaskId;
+    allocationId: AllocationId;
     outcome: TaskOutcome;
 }
 /**
@@ -1436,6 +1465,7 @@ export type ProviderEvent<C extends Channel = Channel> = {
     dialId: DialId;
     outcome: DialOutcome;
     taskId?: TaskId;
+    allocationId?: AllocationId;
     destinationId?: string;
     reason?: string;
 } | {
@@ -1452,6 +1482,7 @@ export type ProviderEvent<C extends Channel = Channel> = {
     expected: string;
     observed: string;
     taskId?: TaskId;
+    allocationId?: AllocationId;
 } | {
     type: "team-updated";
     team: TeamRoster;
@@ -1592,6 +1623,8 @@ export interface BrowserSessionKeyInput {
     /** `Manifest.id`, never `displayName`: only the id is unique across an installation and stable. */
     providerId: string;
     taskId: TaskId;
+    /** The task's allocation: a task-scoped session lives one life of the task, never the next customer's under a reused id. */
+    allocationId: AllocationId;
     /** `Task.taskType`. */
     taskType: string;
     browser: TaskBrowser;

package/dist/index.js

@@ -196,7 +196,7 @@ export function sameCapabilities(a, b) {
  * cannot collide with a provider called `a` and a tab called `b`.
  */
 export function browserSessionKey(input) {
-    const { providerId, taskId, taskType, browser } = input;
+    const { providerId, allocationId, taskType, browser } = input;
     if (browser.sharedSession !== true)
         return undefined;
     // `encodeURIComponent` leaves `.` untouched, and `.` is the separator: a raw join would let
@@ -204,7 +204,7 @@ export function browserSessionKey(input) {
     const part = (value) => encodeURIComponent(value).replaceAll(".", "%2E");
     switch (browser.isolationScheme) {
         case BROWSER_ISOLATION_SCHEMES.PROVIDER_NAME__TASK_ID__TAB_NAME:
-            return `${part(providerId)}.${part(taskId)}.${part(browser.name)}`;
+            return `${part(providerId)}.${part(allocationId)}.${part(browser.name)}`;
         case BROWSER_ISOLATION_SCHEMES.TAB_NAME:
             return part(browser.name);
         case BROWSER_ISOLATION_SCHEMES.PROVIDER_NAME__TASK_TYPE_NAME__TAB_NAME:

package/dist/testing.d.ts

@@ -29,6 +29,12 @@ export interface AdapterContractResult {
     notExercised: readonly ContractSubject[];
     /** Every violation observed. Non-empty only when `collectOnly` suppressed the throw. */
     violations: readonly ProtocolViolation[];
+    /**
+     * Every rule the run evaluated, pass or fail: the validators' as each was applied, the stream's
+     * and the drive's as each case was considered. A rule absent here was never looked at, which a
+     * clean `violations` says nothing about; a test that needs a rule to have run asserts it here.
+     */
+    rulesEvaluated: ReadonlySet<string>;
 }
 export interface ExerciseAdapterOptions {
     /** Return violations in the result instead of throwing. Defaults to `false`. */
@@ -127,13 +133,26 @@ export declare function assertReconnectWithMissedAssignments<C extends Channel>(
  * both.
  */
 export declare function assertDeniedAndRetriedBreak(approvals: readonly BreakApproval[]): void;
-/** What a stream has said about the tasks it carries, and the rules across events. */
 export declare class TaskStream {
     private readonly tasks;
+    private readonly allocations;
+    private readonly endedAllocations;
     private readonly dials;
     /** The host placed a dial: its outcome, whenever it arrives, is one the stream expects. */
     dialled(dialId: string): void;
     private noteDials;
+    /**
+     * Whether an event about a task names the life that is open under its id. One naming a life that
+     * has ended is the late event the allocation exists to catch; one naming a life nobody has seen is
+     * a different fault. Either way it is not applied to the open task.
+     */
+    private namesTheOpenLife;
+    /** How many tasks the stream currently holds open. */
+    openCount(): number;
+    /** Whether an offered task is a dial arriving -- the host's own call, a connect-back -- which counts against no capacity: an entry on its call carrying a dial. */
+    static carriesDial(task: unknown): boolean;
+    /** Whether the update shows the party being dialled again -- a connect-back, a platform's callback -- the one thing that brings a completing task back. */
+    private static partyDialled;
     /** The entries of a task's record, each by step and instant, or undefined where the task carries no record. */
     private static record;
     /** What a restated record lost of the one read before it: nothing, or the entries by step and instant. */