@xema/omni-protocol 0.1.99 → 0.1.101

package/dist/index.d.ts

@@ -106,7 +106,7 @@ export type DialOutcome = "answered" | "busy" | "no-answer" | "unreachable" | "r
 export declare const DIAL_OUTCOMES: readonly ["answered", "busy", "no-answer", "unreachable", "rejected", "cancelled", "unexplained"];
 /**
  * How the agent hears the call: on a `softphone`, where the host owns the audio and opens it
- * through `openMedia`, or on a `deskPhone`, a handset the platform rings, where the host opens
+ * through `openAudio`, or on a `deskPhone`, a handset the platform rings, where the host opens
  * nothing and only shows the call. A voice manifest lists the phones its platform supports, and
  * the host picks one for the login at authentication.
  */
@@ -433,7 +433,7 @@ export interface RecordingActions {
 export interface TaskRecordingPolicy {
     provider?: RecordingActions;
     host?: RecordingActions & {
-        destinationId: string;
+        storageId: string;
     };
 }
 /** Current evidence only. Expiry/disconnect means unknown, never a historical stop. */
@@ -478,7 +478,7 @@ export interface HostRecording {
     announcesToCaller?: true;
     actions: RecordingAction[];
     /** Explicitly provisioned destinations. A task chooses one; no upload/storage fallback. */
-    destinationIds: string[];
+    storageIds: string[];
     execute(request: HostRecordingRequest): Promise<RecordingCommandResult>;
 }
 /** Recording applies or fails; it never dials. Rejection without result means unknown. */
@@ -729,9 +729,9 @@ export type TaskPhase =
 /** What the system does when a preview's deadline passes with no Call pressed. */
 export type PreviewDeadline = 
 /** Provider initiates dialing when preparation ends; never a host timer command. */
-"calls"
+"provider-dials"
 /** Host initiates the ordinary call command when preparation ends. */
- | "host-calls"
+ | "host-dials"
 /** 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. */
@@ -866,7 +866,7 @@ export type TaskLeadAssist = {
  * On a task that reached this agent by a lead's take-over: which member the call was taken from,
  * and when. The provider moves the call from one agent to another, and the lead is the new agent,
  * so the task is an ordinary assignment with the call's history -- offered whatever break the lead
- * is on, counted against no capacity, provided their voice channel is free.
+ * is on, counted against their capacity like any other call, provided they are under it and their voice channel is free.
  */
 export interface TaskTakenOver {
     memberId: UserId;
@@ -917,12 +917,12 @@ export interface Locked {
  */
 export type Lockable<T> = T | Locked;
 /**
- * Who chose a task's capabilities. `undetermined` is a fault the provider states on the task rather
+ * Who chose a task's capabilities. `not-yet-read` is a fault the provider states on the task rather
  * than hides: the platform's terms could not be read, and the set published is what the provider
  * will honour, not what the platform permits.
  */
-export type CapabilitySource = "queue" | "ungoverned" | "undetermined";
-export declare const CAPABILITY_SOURCES: readonly ["queue", "ungoverned", "undetermined"];
+export type CapabilitySource = "queue" | "nobody" | "not-yet-read";
+export declare const CAPABILITY_SOURCES: readonly ["queue", "nobody", "not-yet-read"];
 export type Task<C extends Channel = Channel> = {
     /** The assignment this task is the record of, and its one identity. See `AssignmentId`. */
     assignmentId: AssignmentId;
@@ -933,8 +933,8 @@ export type Task<C extends Channel = Channel> = {
     capabilities: TaskCapabilities<C>;
     /**
      * Where the capabilities came from before the provider put them on the task, so a host can tell
-     * a fact from a fault: `queue` when somebody chose these terms, `ungoverned` when nothing handed
-     * the work over, `undetermined` when a queue was named and its terms could not be read -- the
+     * a fact from a fault: `queue` when somebody chose these terms, `nobody` when nothing handed
+     * the work over, `not-yet-read` when a queue was named and its terms could not be read -- the
      * provider then publishes what it will honour and says so here, where the controls are drawn.
      */
     capabilitySource: CapabilitySource;
@@ -953,7 +953,7 @@ export type Task<C extends Channel = Channel> = {
     acceptance?: AcceptanceMode;
     /**
      * 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
+     * and who acts then -- `provider-dials` makes the provider initiate dialing, `host-dials` 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.
      */
@@ -970,13 +970,13 @@ export type Task<C extends Channel = Channel> = {
     onCall?: OnCall[];
     leadAssist?: TaskLeadAssist;
     takenOver?: TaskTakenOver;
-    media?: TaskMediaState;
+    audio?: TaskAudioState;
 } : {
     recording?: never;
     onCall?: never;
     leadAssist?: never;
     takenOver?: never;
-    media?: never;
+    audio?: never;
 });
 /**
  * What the provider wants of Omni's acceptance policy for one offer. On routed work, present only
@@ -1014,7 +1014,7 @@ export type TaskOutcome = {
     failure: ProtocolFailure;
 };
 export declare const TASK_COMMAND_NAMES: {
-    readonly voice: readonly ["answer", "decline", "call", "hold", "resume", "end-call", "terminate-call", "connect-back", "transfer", "lead-assist", "conference", "recording", "complete"];
+    readonly voice: readonly ["answer", "decline", "dial", "hold", "resume", "end-call", "terminate-call", "connect-back", "transfer", "lead-assist", "conference", "recording", "complete"];
     readonly chat: readonly ["accept", "decline", "pause", "resume", "complete"];
     readonly email: readonly ["accept", "decline", "complete"];
 };
@@ -1030,7 +1030,7 @@ export type VoiceTaskCommand = {
 }
 /** In `preview`: place the call to the party whose record the agent has read. A dial, gated by the phase alone. */
  | {
-    type: "call";
+    type: "dial";
     dialId: DialId;
 } | {
     type: "hold";
@@ -1041,7 +1041,7 @@ export type VoiceTaskCommand = {
  | {
     type: "end-call";
 }
-/** End the caller channel. Gated by `terminateCall`. */
+/** End the whole call at the provider: every channel on it, the agent's, the caller's and anyone else's. Gated by `terminateCall`. */
  | {
     type: "terminate-call";
 }
@@ -1256,8 +1256,8 @@ export type BreakEndResult = {
     status: "failed";
     failure: ProtocolFailure;
 };
-/** `reserved`: signed in here, and the host holds this agent's capacity for another provider (`count: 0`, host-stopped); not receiving this provider's work. */
-export type TeamMemberAvailability = "ready" | "on-task" | "on-break" | "reserved" | "signed-out";
+/** `elsewhere`: signed in here, and the host holds this agent's capacity for another provider (`count: 0`, host-stopped); not receiving this provider's work. */
+export type TeamMemberAvailability = "ready" | "on-task" | "on-break" | "elsewhere" | "signed-out";
 export interface TeamMember {
     id: UserId;
     availability: TeamMemberAvailability;
@@ -1269,6 +1269,8 @@ export interface TeamMember {
     tasks?: MemberTask[];
     /** Present while this lead is on the member's call, listening, coaching or joined; absent otherwise. */
     listening?: MemberListening;
+    /** The member's own history for the day: sign-in, sign-out, breaks and productivity. Omitted where the provider cannot say. */
+    shift?: MemberShift;
 }
 /** A member asking this lead to join their call, named by the member and the assignment. */
 export interface LeadRequest {
@@ -1302,18 +1304,43 @@ export type MemberTask<C extends Channel = Channel> = {
     onCall?: OnCall[];
     leadAssist?: TaskLeadAssist;
     takenOver?: TaskTakenOver;
-    media?: TaskMediaState;
+    audio?: TaskAudioState;
 } : {
     onCall?: never;
     leadAssist?: never;
     takenOver?: never;
-    media?: never;
+    audio?: never;
 });
-/** The lead on this member's call, in the mode they are heard, since when. */
+/**
+ * The lead on this member's call: which of the member's calls, in the mode they are heard, since
+ * when. Its appearance on the team member list is the provider's word that the lead's audio is up,
+ * and the application opens `openAudio` on the assignment named; its disappearance closes it.
+ */
 export interface MemberListening {
+    assignmentId: AssignmentId;
     mode: ListeningMode;
     since: IsoTimestamp;
 }
+export type ShiftEventKind = "signed-in" | "signed-out" | "break-started" | "break-ended";
+export declare const SHIFT_EVENT_KINDS: readonly ["signed-in", "signed-out", "break-started", "break-ended"];
+export interface ShiftEvent {
+    at: IsoTimestamp;
+    kind: ShiftEventKind;
+}
+/**
+ * The member's own history for the day, about the person rather than any one call: when they
+ * signed in and out, today's totals as the provider counts them, each present only when the
+ * provider knows it, and the day's sign-in, sign-out and break events, oldest first.
+ */
+export interface MemberShift {
+    signedInAt: IsoTimestamp;
+    signedOutAt?: IsoTimestamp;
+    talkSeconds?: DurationSeconds;
+    holdSeconds?: DurationSeconds;
+    breakSeconds?: DurationSeconds;
+    tasksHandled?: number;
+    events?: ShiftEvent[];
+}
 /**
  * The lead's view of their team: published to a login that declares `capabilities.lead` while the
  * lead has the team feature on, on every snapshot, and to nobody else. The provider keeps it
@@ -1425,20 +1452,20 @@ export type TeamCommandResult = {
  * `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";
-export interface VoiceMediaSession {
+export type TaskAudioState = "started" | "ended";
+export interface CallAudio {
     remoteAudio: MediaStream;
     setMuted(muted: boolean): void;
     close(): void;
 }
-export interface OpenMediaRequest {
+export interface OpenAudioRequest {
     assignmentId: AssignmentId;
     /** The agent's microphone as Omni captured it, `HostReport.audio.input.localAudio`; absent while that input is `unavailable`. */
     localAudio?: MediaStream;
 }
-export type OpenMediaResult = {
+export type OpenAudioResult = {
     status: "opened";
-    session: VoiceMediaSession;
+    audio: CallAudio;
 } | {
     status: "unavailable";
     failure: ProtocolFailure;
@@ -1530,7 +1557,7 @@ export interface Snapshot<C extends Channel = Channel> {
     /** The provider's own count of those tasks, stated rather than inferred: it must equal `tasks.length`, so a blank or unanswered state can never pass as a confirmed empty. */
     taskCount: number;
     contacts?: Contact[];
-    scheduledActivities?: ScheduledActivity[];
+    calendar?: ScheduledActivity[];
     team?: TeamMembers;
 }
 /**
@@ -1540,7 +1567,7 @@ export interface Snapshot<C extends Channel = Channel> {
  * tasks against it and needs no new signal when one ends. The agent is one person on several
  * providers, and the host divides their capacity among them: `0` is host-stopped -- the agent's
  * capacity is elsewhere for now, this provider assigns nothing and shows the member as
- * `reserved` -- and is not a break, which is the agent not working at all. The host restates a
+ * `elsewhere` -- and is not a break, which is the agent not working at all. The host restates a
  * count of one or more when this provider has the agent's capacity again.
  */
 export interface AgentCapacity {
@@ -1583,24 +1610,10 @@ export type ProviderEvent<C extends Channel = Channel> = {
     type: "task-updated";
     task: Task<C>;
 } | {
-    type: "task-media-started";
+    type: "task-audio-started";
     assignmentId: AssignmentId;
 } | {
-    type: "task-media-ended";
-    assignmentId: AssignmentId;
-}
-/**
- * The lead's channel is in a member's call -- listening, coaching or joined -- and its audio should
- * attach: on a softphone the application opens media on the member's assignment as it does for a
- * task. Voice, to a login that declares `lead`, never to the member.
- */
- | {
-    type: "team-media-started";
-    memberId: UserId;
-    assignmentId: AssignmentId;
-} | {
-    type: "team-media-ended";
-    memberId: UserId;
+    type: "task-audio-ended";
     assignmentId: AssignmentId;
 } | {
     type: "task-ended";
@@ -1643,7 +1656,7 @@ export type ProviderEvent<C extends Channel = Channel> = {
     contacts: Contact[];
 } | {
     type: "calendar-updated";
-    scheduledActivities: ScheduledActivity[];
+    calendar: ScheduledActivity[];
 };
 /**
  * The `Provider` prefix survives here for a mechanical reason rather than a naming one: `Event`
@@ -1718,7 +1731,7 @@ export interface Connection<C extends Channel = Channel> {
     /** Required when the login declares `capabilities.lead`: every lead act, on the team surface and nowhere else. */
     executeTeam?(request: TeamCommandRequest): Promise<TeamCommandResult>;
     /** Required of a voice adapter whose manifest lists `softphone`: on one, the call's audio lands in Omni. */
-    openMedia?(request: OpenMediaRequest): Promise<OpenMediaResult>;
+    openAudio?(request: OpenAudioRequest): Promise<OpenAudioResult>;
     /** 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 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. */

package/dist/index.js

@@ -71,19 +71,19 @@ export const DEFAULT_LEVELS = [
 export function effectiveLevels(declared) {
     return [...(declared ?? DEFAULT_LEVELS)];
 }
-export const CAPABILITY_SOURCES = ["queue", "ungoverned", "undetermined"];
+export const CAPABILITY_SOURCES = ["queue", "nobody", "not-yet-read"];
 // ---------------------------------------------------------------------------
 // Task commands.
 // ---------------------------------------------------------------------------
 export const TASK_COMMAND_NAMES = {
-    voice: ["answer", "decline", "call", "hold", "resume", "end-call", "terminate-call",
+    voice: ["answer", "decline", "dial", "hold", "resume", "end-call", "terminate-call",
         "connect-back", "transfer", "lead-assist", "conference", "recording", "complete"],
     chat: ["accept", "decline", "pause", "resume", "complete"],
     email: ["accept", "decline", "complete"],
 };
 /** The dial a command places, by the host's identity for it; `undefined` for a command that dials nothing. */
 export function commandDialId(command) {
-    if (command.type === "connect-back" || command.type === "call")
+    if (command.type === "connect-back" || command.type === "dial")
         return command.dialId;
     if (command.type === "transfer" && (command.action === "cold" || command.action === "warm"))
         return command.dialId;
@@ -95,6 +95,7 @@ export const BREAK_KINDS = [
     "short-break", "meal", "rest", "training", "coaching",
     "meeting", "administrative", "technical", "personal", "other",
 ];
+export const SHIFT_EVENT_KINDS = ["signed-in", "signed-out", "break-started", "break-ended"];
 export const OMNI_FAILURE_CODES = [
     "omni.not-authenticated",
     "omni.capability-not-enabled",

package/dist/testing.d.ts

@@ -7,7 +7,7 @@ export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation }
  * rules -- each optional part of a task, each optional part of the break state and team member list, each
  * declared contribution, and each event type.
  */
-declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.history", "task.onCall", "task.leadAssist", "task.takenOver", "task.media", "task.acceptance", "task.outcomes", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.forced", "team.members", "team.requests", "team.tasks", "team.listening", "contacts", "scheduledActivities", "team.policies"];
+declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.history", "task.onCall", "task.leadAssist", "task.takenOver", "task.audio", "task.acceptance", "task.outcomes", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.forced", "team.members", "team.requests", "team.tasks", "team.listening", "team.shift", "contacts", "calendar", "team.policies"];
 export type ContractSubject = (typeof STATE_SUBJECTS)[number] | `event.${ProviderEvent["type"]}`;
 export interface AdapterContractResult {
     events: ProviderEventEnvelope[];
@@ -41,7 +41,7 @@ export interface ExerciseAdapterOptions {
     collectOnly?: boolean;
     /**
      * Drive one ordinary lifecycle on the first task the provider offers -- accept it, open its
-     * media on a softphone, hold and resume where offered, end the call where offered, complete it
+     * audio on a softphone, hold and resume where offered, end the call where offered, complete it
      * where the agent completes -- so the rules about a live call are reached rather than listed
      * under `notExercised`. Off by default, since it issues commands against whatever platform the
      * adapter is connected to: turn it on against a test backend.
@@ -177,9 +177,9 @@ export declare class TaskStream {
      * Takes a resync snapshot -- a `snapshot` event, or the read a reloaded client makes -- as the
      * state now, and first holds it to what the stream knew. A snapshot replaces state; it does not
      * get to forget it. A task it carries that the stream already held may not go backwards, lose an
-     * entry of its record, return to undetermined terms, or be at work without the audio the stream
-     * held up: media ends on task-media-ended and the call moves on, so a task still in-progress or
-     * paused without its media is a snapshot that lost state, not a call that ended.
+     * entry of its record, return to not-yet-read terms, or be at work without the audio the stream
+     * held up: audio ends on task-audio-ended and the call moves on, so a task still in-progress or
+     * paused without its audio is a snapshot that lost state, not a call that ended.
      */
     resync(snapshot: unknown, at: string): ProtocolViolation[];
     /** Replaces what is known with a snapshot's tasks, as a snapshot replaces Omni's state. */
@@ -205,12 +205,12 @@ export declare class BreakStream {
  */
 export declare function assertBreakFollowsItsRequests(envelopes: readonly ProviderEventEnvelope[], snapshot?: Snapshot): void;
 /**
- * The media follows the task and never decides it. Given a provider's stream -- optionally seeded
- * with the snapshot it began from -- every task is introduced once, `task-media-started` and
- * `task-media-ended` alternate on work that has begun, media ends only where it arrived, and what
- * follows the media ending is `completing` or `task-ended`.
+ * The audio follows the task and never decides it. Given a provider's stream -- optionally seeded
+ * with the snapshot it began from -- every task is introduced once, `task-audio-started` and
+ * `task-audio-ended` alternate on work that has begun, audio ends only where it arrived, and what
+ * follows the audio ending is `completing` or `task-ended`.
  */
-export declare function assertMediaFollowsTheTask(envelopes: readonly ProviderEventEnvelope[], snapshot?: Snapshot): void;
+export declare function assertAudioFollowsTheTask(envelopes: readonly ProviderEventEnvelope[], snapshot?: Snapshot): void;
 /** A login store that lives in memory for the test: what most adapter tests hand `exerciseAdapter` as `context.store`. */
 export declare function memoryStore(): LoginStore;
 /**
@@ -252,14 +252,14 @@ export interface BreakOnTaskStep {
  */
 export declare function assertBreakBeginsAfterTask(steps: readonly BreakOnTaskStep[]): void;
 /**
- * Validates the deadline derived from media end and the task's fixed wrap allowance.
+ * Validates the deadline derived from audio end and the task's fixed wrap allowance.
  *
  * A task with no allowance has no deadline, so `observedDeadline` must then be `undefined`: a
  * host counting down what the provider left open is the violation, and so is a host counting
  * nothing down when the provider set a clock. `toleranceMs` absorbs scheduler jitter in a real
  * implementation; pass 0 to demand an exact match.
  */
-export declare function assertWrapTimeout(task: Pick<TaskCompletion, "completionMode" | "wrapAllowance">, mediaEndedAt: string, observedDeadline: string | undefined, toleranceMs?: number): void;
+export declare function assertWrapTimeout(task: Pick<TaskCompletion, "completionMode" | "wrapAllowance">, audioEndedAt: string, observedDeadline: string | undefined, toleranceMs?: number): void;
 /** One browser in one task of one provider. `providerId` is `Manifest.id`, never `displayName`. */
 export type BrowserIsolationScenario = BrowserSessionKeyInput;
 /** Validates whether two task-browser definitions should share one browser session. */