@xema/omni-protocol 0.1.101 → 0.1.103

package/dist/index.d.ts

@@ -164,7 +164,7 @@ export interface Manifest<C extends Channel = Channel> {
     /**
      * The outcomes this platform distinguishes when a dial ends, `answered` and at least one way of
      * not reaching the destination. Required of a provider that dials at all -- an idle dialpad, or
-     * a task that may transfer, conference, or call back -- and forbidden off voice, where nothing dials.
+     * a task that may conference or call back -- and forbidden off voice, where nothing dials.
      */
     dialOutcomes?: C extends "voice" ? DialOutcome[] : never;
     /**
@@ -179,13 +179,12 @@ export interface Manifest<C extends Channel = Channel> {
      */
     runningStepReports?: true;
     /**
-     * How long after an applied completion -- `complete`, or a lead's `take-over-call` -- 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 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.
+     * How long after `applied` the wire shows what the provider did, in milliseconds: the
+     * `task-ended` after a `complete` or a lead's `take-over-call`, the `calendar-updated` after a
+     * `schedule`. Past it the host resyncs and shows the thing as unsettled. Stated per provider,
+     * since platforms settle at different speeds.
      */
-    completionSettleMs: number;
+    settleMs: number;
 }
 export interface SecretStore {
     get(key: string): Promise<string | undefined>;
@@ -251,9 +250,10 @@ export interface UserCapabilities {
     /**
      * This login leads a team. The flag alone turns on the team feature in the agent application:
      * the lead sees their members with their tasks and stats, and acts on them through `executeTeam`
-     * with the authority the flag carries. No per-action permission rides beside it. While the lead
-     * has the feature on, a `TeamMembers` object is published to them on every snapshot, `members: []`
-     * included; to nobody else, ever.
+     * with the authority the flag carries. No per-action permission rides beside it. The provider
+     * assumes nothing of the switch: the application sends `lead-features` on every connect, and
+     * only while it is on does the team reach the lead -- `team-updated` whole after the switch and
+     * on any snapshot, then one member at a time as members change; to nobody else, ever.
      */
     lead?: true;
 }
@@ -458,7 +458,6 @@ export type RecordingState = {
 export type RecordingCommand = {
     type: "recording";
     source: RecordingSource;
-    requestId: string;
     /** Compare-and-set against current evidence; never act on a replacement recording. */
     observationId: string;
 } & ({
@@ -622,7 +621,7 @@ export interface Destination {
     id: string;
     label: string;
 }
-/** The items a transfer or conference control offers. Nothing is typed; the agent picks one. */
+/** The items a conference control offers. Nothing is typed; the agent picks one. */
 export interface DestinationDirectory {
     destinations: Destination[];
 }
@@ -653,14 +652,13 @@ export interface SharedTaskCapabilities {
 export type TaskCapabilities<C extends Channel = Channel> = C extends "voice" ? SharedTaskCapabilities & {
     decline?: Lockable<true>;
     hold?: Lockable<true>;
-    /** The provider ends the caller connection and agent-added channels owned by this interaction, including inherited channels after transfer/takeover. Interaction completion remains separate. */
+    /** The provider ends the caller connection and agent-added channels owned by this interaction, including inherited channels after a take-over. Interaction completion remains separate. */
     endCall?: Lockable<true>;
     terminateCall?: Lockable<true>;
     /** Connect back to the party while `completing`, whoever placed the call; the task returns to `in-progress`. */
     connectBack?: Lockable<true>;
-    coldTransfer?: Lockable<DestinationDirectory>;
-    /** Park the customer and call a destination first; then `complete` or `cancel`. */
-    warmTransfer?: Lockable<DestinationDirectory>;
+    /** Put a time on the calendar for this party, from the call: a follow-up the agent promised. */
+    schedule?: Lockable<true>;
     /** Ask a lead to join this call, with a note. The lead's decision arrives on `Task.leadAssist`. */
     leadAssist?: Lockable<true>;
     conference?: Lockable<DestinationDirectory>;
@@ -668,8 +666,10 @@ export type TaskCapabilities<C extends Channel = Channel> = C extends "voice" ?
 } : C extends "chat" ? SharedTaskCapabilities & {
     decline?: Lockable<true>;
     hold?: Lockable<true>;
+    schedule?: Lockable<true>;
 } : SharedTaskCapabilities & {
     decline?: Lockable<true>;
+    schedule?: Lockable<true>;
 };
 /**
  * How a reusing browser's session is keyed.
@@ -721,7 +721,7 @@ export type TaskPhase =
  | "confirmed"
 /**
  * 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.
+ * presses Call, or `previewEndsInSeconds` runs out and `atDeadline` says what the system does instead.
  */
  | "preview" | "in-progress" | "paused"
 /** The work is over and the agent is finishing up. */
@@ -807,19 +807,18 @@ export type TaskCompletion = {
     completionMode: "provider-automatic";
     wrapAllowance: DurationSeconds;
 };
-export type OnCallRole = "party" | "agent" | "consulted" | "conferenced";
+export type OnCallRole = "party" | "agent" | "conferenced";
 /** Where a dialled entry stands: `ringing` until its dial is answered, `joined` after. */
 export type OnCallStage = "ringing" | "joined";
-export declare const ON_CALL_ROLES: readonly ["party", "agent", "consulted", "conferenced"];
+export declare const ON_CALL_ROLES: readonly ["party", "agent", "conferenced"];
 /**
  * Somebody on the call, or being brought onto it, as the provider states it: who, since when, and
- * whether they are held aside. `party` is the customer; `agent` a person, by user id; `consulted`
- * and `conferenced` someone a dial is bringing in -- listed from the moment the dial is placed, so
- * the agent can call it off while it rings -- carrying the dial when a host placed it, the address
- * 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. The `party`
+ * whether they are held aside. `party` is the customer; `agent` a person, by user id; `conferenced`
+ * someone a dial is bringing in -- listed from the moment the dial is placed, so the agent can call
+ * it off while it rings -- carrying the dial when a host placed it, the address 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`. The `party`
  * carries a `stage` while being dialled -- by any host dial, a dialpad call, a preview Call or a
  * connect-back, carrying its `dialId`, or by a callback the platform places itself, carrying none --
  * `ringing` from the moment the dial is placed, `joined` on the publication that follows its
@@ -842,7 +841,7 @@ export type OnCall = {
     role: "agent";
     userId: UserId;
 } | {
-    role: "consulted" | "conferenced";
+    role: "conferenced";
     destinationId: string;
     stage: OnCallStage;
     dialId?: DialId;
@@ -952,12 +951,21 @@ 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 -- `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.
+     * In `pending` only: how long the offer has left, in whole seconds from this publication,
+     * restated on every publication that carries it so a reconnect snapshot says what is actually
+     * left. Absent, the offer stands until the provider says otherwise. Runs out: the provider ends
+     * the offer `expired` naming `pending`.
+     */
+    expiresInSeconds?: DurationSeconds;
+    /**
+     * In `preview` only, and together: how long the preparation has left, in whole seconds from
+     * this publication -- restated on every publication that carries it, so a resync starts the
+     * countdown afresh and no clock is compared -- and behavior when it runs out, 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.
      */
-    previewEndsAt?: IsoTimestamp;
+    previewEndsInSeconds?: DurationSeconds;
     atDeadline?: PreviewDeadline;
     /** The identifier an agent reads back to a customer, where the provider has one. */
     reference?: string;
@@ -989,11 +997,6 @@ export type TaskOutcome = {
     type: "completed";
     by: "agent" | "provider";
 }
-/** A cold transfer to a destination the agent chose: a directory item's id. */
- | {
-    type: "transferred";
-    destinationId?: string;
-}
 /** A lead took the call over and the agent has wrapped it: the outcome at the agent's own completion. Named by the lead, since a lead is not a directory item. */
  | {
     type: "taken-over";
@@ -1005,18 +1008,18 @@ export type TaskOutcome = {
     by: "agent" | "provider" | "party";
     reason?: string;
 }
-/** Only the phases in which somebody is still being waited on can expire; an offer that lapses at `assignmentExpiresAt` names `pending`. */
+/** Only the phases in which somebody is still being waited on can expire: an offer whose `expiresInSeconds` runs out names `pending`, accepted work the platform gave up on names `confirmed`. A preview never lapses: withdrawn, it is `cancelled` by the provider. */
  | {
     type: "expired";
-    phase: "pending" | "confirmed" | "preview";
+    phase: "pending" | "confirmed";
 } | {
     type: "failed";
     failure: ProtocolFailure;
 };
 export declare const TASK_COMMAND_NAMES: {
-    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"];
+    readonly voice: readonly ["answer", "decline", "dial", "hold", "resume", "end-call", "terminate-call", "connect-back", "lead-assist", "conference", "recording", "schedule", "complete"];
+    readonly chat: readonly ["accept", "decline", "pause", "resume", "schedule", "complete"];
+    readonly email: readonly ["accept", "decline", "schedule", "complete"];
 };
 export type TaskCommandName<C extends keyof typeof TASK_COMMAND_NAMES> = (typeof TASK_COMMAND_NAMES)[C][number];
 export interface OutcomePayload {
@@ -1049,31 +1052,7 @@ export type VoiceTaskCommand = {
  | {
     type: "connect-back";
     dialId: DialId;
-}
-/** Cold: hand the customer to the directory item `destinationId` with nobody spoken to first. Gated by `coldTransfer`. */
- | {
-    type: "transfer";
-    action: "cold";
-    dialId: DialId;
-    destinationId: string;
-}
-/** Warm: park the customer and call the directory item `destinationId` first. Gated by `warmTransfer`. */
- | {
-    type: "transfer";
-    action: "warm";
-    dialId: DialId;
-    destinationId: string;
-}
-/** Hand the customer to the consulted destination and leave. Needs a `consulted` entry on `Task.onCall`. */
- | {
-    type: "transfer";
-    action: "complete";
-}
-/** Drop the consulted destination and return to the customer. Needs a `consulted` entry on `Task.onCall`. */
- | {
-    type: "transfer";
-    action: "cancel";
-}
+} | ScheduleCommand
 /** Ask a lead to join, with a note. Gated by `leadAssist`. */
  | {
     type: "lead-assist";
@@ -1113,6 +1092,18 @@ export type VoiceTaskCommand = {
 }) | ({
     type: "complete";
 } & OutcomePayload);
+/**
+ * Put a time on the calendar for this party: a follow-up promised on the call or in the
+ * conversation, or written up in wrap. Gated by `schedule` on any channel, issuable in
+ * `in-progress`, `paused` or `completing`, under a manifest that declares `calendar` for it to
+ * land on; `applied` says it is on the calendar, and the `calendar-updated` that shows it follows
+ * within the manifest's `settleMs`.
+ */
+export type ScheduleCommand = {
+    type: "schedule";
+    at: IsoTimestamp;
+    note?: string;
+};
 export type ChatTaskCommand = {
     type: "accept";
 } | {
@@ -1121,14 +1112,14 @@ export type ChatTaskCommand = {
     type: "pause";
 } | {
     type: "resume";
-} | ({
+} | ScheduleCommand | ({
     type: "complete";
 } & OutcomePayload);
 export type EmailTaskCommand = {
     type: "accept";
 } | {
     type: "decline";
-} | ({
+} | ScheduleCommand | ({
     type: "complete";
 } & OutcomePayload);
 export interface CustomTaskCommand {
@@ -1206,9 +1197,15 @@ export interface BreakRequest {
     /** The chosen `BreakReason.id`, where the provider publishes codes. */
     reasonId?: string;
 }
-/** A break forced on the agent; the agent must explicitly resume when ready. */
+/**
+ * A break forced on the agent; the agent must explicitly resume when ready. A lead's `force-break`
+ * is a command to the provider, which forces the break: `by` names the lead who asked it to, or
+ * `provider` where the platform itself did, on its own rule or a schedule. The agent sees who, a
+ * person is named only when there is one, and a break the platform imposed is the platform's to
+ * lift: a lead's `end-forced-break` on it fails with `omni.break-forced-by-provider`.
+ */
 export type ForcedBreak = {
-    by: UserId;
+    by: UserId | "provider";
     /** Optional expected time on break, in milliseconds from actual start. Advisory only. */
     expectedDurationMs?: number;
 };
@@ -1271,10 +1268,11 @@ export interface TeamMember {
     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;
+    /** The member's standing ask for a lead on one of their calls; absent when they are not asking. */
+    request?: MemberRequest;
 }
-/** A member asking this lead to join their call, named by the member and the assignment. */
-export interface LeadRequest {
-    memberId: UserId;
+/** This member asking their lead to join a call: which assignment, the note they wrote, since when. */
+export interface MemberRequest {
     assignmentId: AssignmentId;
     note?: string;
     since: IsoTimestamp;
@@ -1337,19 +1335,20 @@ export interface MemberShift {
     signedOutAt?: IsoTimestamp;
     talkSeconds?: DurationSeconds;
     holdSeconds?: DurationSeconds;
+    /** Every break the member was on today, including time held elsewhere for a break another provider forced: the provider counts it under a break kind of its own. */
     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
- * current: when a member holds, mutes or is transferred, the list is republished whole.
+ * lead has the team feature on, and to nobody else. Whole on `team-updated` -- after the switch,
+ * and on any snapshot -- and from then on one member at a time: `team-member-updated` carries the
+ * member whole, so applying it twice changes nothing, and `team-member-removed` takes one off.
+ * A team of two hundred is never resent because one of them held.
  */
 export interface TeamMembers {
     members: TeamMember[];
-    /** Members asking a lead to join their call; `[]` when nobody is asking. */
-    requests: LeadRequest[];
     /** The team's policy per capability, as it stands. Present where the provider offers policy control; absent where it does not. */
     policies?: TeamPolicies;
 }
@@ -1605,7 +1604,6 @@ export type ProviderEvent<C extends Channel = Channel> = {
 } | {
     type: "task-offered";
     task: Task<C>;
-    assignmentExpiresAt?: IsoTimestamp;
 } | {
     type: "task-updated";
     task: Task<C>;
@@ -1648,9 +1646,22 @@ export type ProviderEvent<C extends Channel = Channel> = {
     expected: string;
     observed: string;
     assignmentId?: AssignmentId;
-} | {
+}
+/** The whole team, once: after `lead-features` comes on, and on every snapshot while it is. */
+ | {
     type: "team-updated";
     team: TeamMembers;
+}
+/** One member, whole, as they now stand: replaces the member of that id, or adds them. */
+ | {
+    type: "team-member-updated";
+    member: TeamMember;
+} | {
+    type: "team-member-removed";
+    memberId: UserId;
+} | {
+    type: "team-policies-updated";
+    policies: TeamPolicies;
 } | {
     type: "contacts-updated";
     contacts: Contact[];
@@ -1670,7 +1681,7 @@ export interface ProviderEventEnvelope<C extends Channel = Channel> {
     occurredAt: IsoTimestamp;
     event: ProviderEvent<C>;
 }
-export declare const OMNI_FAILURE_CODES: readonly ["omni.not-authenticated", "omni.capability-not-enabled", "omni.assignment-not-found", "omni.destination-not-permitted", "omni.phone-not-permitted", "omni.rate-limited", "omni.unavailable", "omni.break-already-committed"];
+export declare const OMNI_FAILURE_CODES: readonly ["omni.not-authenticated", "omni.capability-not-enabled", "omni.assignment-not-found", "omni.destination-not-permitted", "omni.phone-not-permitted", "omni.rate-limited", "omni.unavailable", "omni.break-already-committed", "omni.recording-unsettled", "omni.break-forced-by-provider"];
 export type OmniFailureCode = (typeof OMNI_FAILURE_CODES)[number];
 /**
  * What the host refused, told to the adapter that published it: a snapshot the host would not

package/dist/index.js

@@ -56,7 +56,7 @@ export function isAllowedBrowserUrl(url) {
         return false;
     }
 }
-export const ON_CALL_ROLES = ["party", "agent", "consulted", "conferenced"];
+export const ON_CALL_ROLES = ["party", "agent", "conferenced"];
 /**
  * The levels a typical organisation has: the ladder in force when a manifest declares no
  * `orgLevels`. A manifest that declares any states its whole ladder outright.
@@ -77,16 +77,14 @@ export const CAPABILITY_SOURCES = ["queue", "nobody", "not-yet-read"];
 // ---------------------------------------------------------------------------
 export const TASK_COMMAND_NAMES = {
     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"],
+        "connect-back", "lead-assist", "conference", "recording", "schedule", "complete"],
+    chat: ["accept", "decline", "pause", "resume", "schedule", "complete"],
+    email: ["accept", "decline", "schedule", "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 === "dial")
         return command.dialId;
-    if (command.type === "transfer" && (command.action === "cold" || command.action === "warm"))
-        return command.dialId;
     if (command.type === "conference" && command.action === "add")
         return command.dialId;
     return undefined;
@@ -105,6 +103,10 @@ export const OMNI_FAILURE_CODES = [
     "omni.rate-limited",
     "omni.unavailable",
     "omni.break-already-committed",
+    /** A recording command the provider could not settle either way: no start, stop, pause or resume it can vouch for. */
+    "omni.recording-unsettled",
+    /** A lead asked to lift a break the platform itself imposed; the platform lifts its own. */
+    "omni.break-forced-by-provider",
 ];
 /**
  * Preserves the adapter's inferred concrete type while checking it implements `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 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.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"];
+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.request", "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[];
@@ -149,6 +149,8 @@ export declare class TaskStream {
     private readonly tasks;
     private readonly assignments;
     private readonly endedAssignments;
+    /** Every assignment a `task-offered` introduced, as against one a snapshot carried: each is owed its ending. */
+    private readonly offered;
     private readonly dials;
     /** The host placed a dial: its outcome, whenever it arrives, is one the stream expects. */
     dialled(dialId: string): void;
@@ -160,6 +162,8 @@ export declare class TaskStream {
     private notOpen;
     /** How many tasks the stream currently holds open. */
     openCount(): number;
+    /** The assignments an offer introduced that are still open: each was owed a `task-ended` that has not come. */
+    unended(): string[];
     /** 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;
     /**
@@ -188,6 +192,20 @@ export declare class TaskStream {
     apply(envelope: unknown, path?: string): ProtocolViolation[];
 }
 /** What a stream has said about the agent's break, and the moves it may not make. */
+/**
+ * The team as the events left it: whole on `team-updated` and on any snapshot carrying one, then
+ * one member at a time. A member event before the whole team, or a removal of a member the team
+ * never carried, is a change to a team the lead was never given.
+ */
+export declare class TeamStream {
+    private members;
+    private static ids;
+    /** A snapshot carrying a team is the team whole; one carrying none leaves the lead with none. */
+    seed(snapshot: unknown): void;
+    /** Whether the team currently carries this member, as the events left it. */
+    has(id: string): boolean;
+    apply(envelope: unknown, path?: string): ProtocolViolation[];
+}
 export declare class BreakStream {
     private state;
     private recovery;
@@ -231,6 +249,13 @@ export interface BreakCandidate {
     /** Whether the agent can currently receive work from it: connected, with a capacity stated. */
     holdsCapacity: boolean;
 }
+/**
+ * A break one provider forces stops the agent everywhere: the host states a capacity of zero on
+ * every other usable provider holding capacity -- taken, never refused, and nothing the agent can
+ * cancel -- and on the forcing provider states nothing, since the break itself holds the agent
+ * there. A provider whose login is not usable is left alone, as a break attempt leaves it.
+ */
+export declare function assertForcedBreakStopsTheRest(forcedOn: string, candidates: readonly BreakCandidate[], stopped: readonly string[]): void;
 /**
  * A break attempt asks every connected provider from which the agent can currently receive work.
  * A provider whose login is not usable -- `expired` above all -- is not asked, whatever else is