@xema/omni-protocol 0.1.25 → 0.1.27

package/README.md

@@ -65,7 +65,7 @@ clean result is read for what it covers and not for the whole contract; `assertR
 subjects)` is the paired assertion.
 
 ```ts
-const context = { protocolVersion: OMNI_PROTOCOL_VERSION, sessionId: "session-1", host: stillHost(report) };
+const context = { protocolVersion: OMNI_PROTOCOL_VERSION, loginId: "session-1", host: stillHost(report) };
 const result = await exerciseAdapter(adapter, context, { collectOnly: true });
 expect(result.violations).toEqual([]);
 expect(result.disconnectWasClean).toBe(true);

package/dist/index.d.ts

@@ -54,19 +54,19 @@ export interface ProtocolViolation {
     message: string;
 }
 export type AuthenticationMethod = "browser-sso" | "credentials";
-export interface BrowserAccessPolicy {
+export interface BrowserAccess {
     /** The decision when no list entry matches. */
     mode: "allow-all" | "block-all";
     allowList?: string[];
     blockList?: string[];
 }
 export interface PersonalBrowserCapability {
-    access: BrowserAccessPolicy;
+    access: BrowserAccess;
     accessPolicyScope?: "initial-url" | "all-navigation";
 }
-export type DialDestinationPolicy = "contacts-only" | "any-number";
+export type DialDestinations = "contacts-only" | "any-number";
 export interface DialCapability {
-    destinationPolicy: DialDestinationPolicy;
+    destinations: DialDestinations;
 }
 /** Every idle capability a provider may declare. Only voice may `dial`; the channel arm says so. */
 export declare const IDLE_CAPABILITIES: readonly ["dial", "personalBrowser", "calendar", "contacts"];
@@ -111,8 +111,8 @@ export interface Manifest<C extends Channel = Channel> {
     phaseLabels?: TaskPhaseLabels;
     /** Keyed by `taskType`. An entry replaces the channel default outright rather than merging. */
     taskTypePresentation?: Record<string, TaskTypePresentation>;
-    /** The organisation's whole ladder, stated outright, `person` included. Omitted for the typical four, `DEFAULT_TIERS`. */
-    orgTiers?: TierDeclaration[];
+    /** The organisation's whole ladder, stated outright, `person` included. Omitted for the typical four, `DEFAULT_LEVELS`. */
+    orgLevels?: LevelDeclaration[];
 }
 export interface SecretStore {
     get(key: string): Promise<string | undefined>;
@@ -121,8 +121,8 @@ export interface SecretStore {
 }
 export interface AuthenticationContext {
     protocolVersion: number;
-    /** Omni's identity for this login. The same value arrives later as `ConnectContext.sessionId`. */
-    sessionId: string;
+    /** Omni's identity for this login. The same value arrives later as `ConnectContext.loginId`. */
+    loginId: string;
     /** Scoped to this provider's manifest id. */
     secrets: SecretStore;
     signal?: AbortSignal;
@@ -155,7 +155,7 @@ export interface TeamCapabilities {
  * of who the agent is on this provider: the provider knows the roles and says so at sign-in.
  * Current as of the latest `authenticated` state, never fixed for the login.
  */
-export interface SessionCapabilities {
+export interface UserCapabilities {
     /** This login may request a break. Requires the four break methods. */
     breaks?: true;
     /** The choices the team left to this person, with where each stands. Omitted when there are none. Requires `setPreference`. */
@@ -175,12 +175,12 @@ export type AuthenticationState = {
 } | {
     status: "authenticated";
     identity: User;
-    capabilities: SessionCapabilities;
+    capabilities: UserCapabilities;
     expiresAt?: IsoTimestamp;
 } | {
     status: "refreshing";
     identity: User;
-    capabilities: SessionCapabilities;
+    capabilities: UserCapabilities;
 } | {
     status: "expired";
     identity?: User;
@@ -230,7 +230,7 @@ export type CompleteAuthenticationRequest = {
 export type CompleteAuthenticationResult = {
     status: "authenticated";
     identity: User;
-    capabilities: SessionCapabilities;
+    capabilities: UserCapabilities;
     expiresAt?: IsoTimestamp;
 } | {
     status: "rejected";
@@ -295,10 +295,6 @@ export type HostAudioOutput = {
 /** What Omni's own chrome shows of a task browser's URL: nothing, the domain, or all of it. */
 export type UrlVisibility = "full" | "domain" | "hidden";
 export interface HostReport {
-    /** What the agent can see of a task browser's URL in Omni's chrome. Task browsers only; the personal browser is the agent's. */
-    browsers: {
-        urlVisibility: UrlVisibility;
-    };
     /** Whether the host has a network interface up. Not a claim that anything is reachable: the adapter knows its own platform's reachability better than the host does. */
     online: boolean;
     audio?: {
@@ -314,7 +310,7 @@ export interface Host {
 export interface ConnectContext {
     protocolVersion: number;
     /** The session that authenticated this connection. */
-    sessionId: string;
+    loginId: string;
     /** Omni-side policy: whether the agent's tasks are accepted without asking them. */
     autoAcceptTasks?: boolean;
     /**
@@ -325,13 +321,13 @@ export interface ConnectContext {
     signal?: AbortSignal;
     log?: (entry: unknown) => void;
 }
-export type ConnectionStatus = "connecting" | "active" | "error";
+export type TransportStatus = "connecting" | "active" | "error";
 /**
  * What revives a connection that reported `error`: `reconnect` -- the login is good, dispose this
  * connection and call `connect()` again -- or `reauthenticate` -- run the authentication flow
  * first. The adapter knows which; the host acts on its word.
  */
-export type ConnectionRecovery = "reconnect" | "reauthenticate";
+export type TransportRecovery = "reconnect" | "reauthenticate";
 /** Every field is optional: a provider sends what it knows and omits what it does not. */
 export interface Contact {
     name?: string;
@@ -346,7 +342,8 @@ export interface ScheduledActivity {
     title: string;
     startsAt: IsoTimestamp;
     endsAt?: IsoTimestamp;
-    contact?: Contact;
+    /** The person the activity reaches -- a callback's customer. */
+    party?: Contact;
     attributes?: Attribute[];
 }
 export interface DispositionCode {
@@ -354,7 +351,7 @@ export interface DispositionCode {
     label: string;
     group?: string;
 }
-export interface DispositionPolicy {
+export interface DispositionRules {
     required?: boolean;
     notes?: "required" | "optional" | "hidden";
     codes?: DispositionCode[];
@@ -373,7 +370,7 @@ export interface DestinationDirectory {
 export interface CustomCapability {
     id: string;
     ui: {
-        kind: "button" | "toggle" | "menu-item";
+        control: "button" | "toggle" | "menu-item";
         label: string;
         placement: "primary" | "secondary" | "overflow";
         /** Where the control's work renders: inline in the workspace, or as a page of its own. Inline when absent. */
@@ -386,7 +383,7 @@ export interface CustomCapability {
 }
 export interface SharedTaskCapabilities {
     browsers?: true;
-    dispositions?: true | DispositionPolicy;
+    dispositions?: true | DispositionRules;
     custom?: CustomCapability[];
 }
 /**
@@ -429,24 +426,32 @@ export declare const BROWSER_ISOLATION_SCHEMES: {
     readonly TASK_TYPE_NAME__TAB_NAME: "TaskTypeName.TabName";
 };
 export type BrowserIsolationScheme = (typeof BROWSER_ISOLATION_SCHEMES)[keyof typeof BROWSER_ISOLATION_SCHEMES];
-export interface TaskBrowserBase {
+/** One tab, in either workspace. */
+export interface Browser {
     id: string;
     name: string;
-    purpose: string;
     /** `http:` or `https:` only. */
     url: string;
 }
 /**
- * The union is what makes a reusing browser with no scheme fail to compile rather than inherit
- * a default -- which is how two tasks end up sharing a session nobody intended.
+ * A tab the task brought: fixed at the task's definition -- count and details -- with why it is
+ * there, whether its session is shared across tasks, and whether the agent may read its URL. The
+ * union is what makes a reusing browser with no scheme fail to compile rather than inherit a
+ * default -- which is how two tasks end up sharing a session nobody intended.
  */
-export type TaskBrowser = TaskBrowserBase & ({
-    reuse: false;
+export type TaskBrowser = Browser & {
+    purpose: string;
+    /** Hide this tab's URL from the agent in Omni's chrome. Omitted, the URL shows as any browser's does; a provider says `hidden` where the URL carries what the agent may not read. */
+    urlVisibility?: UrlVisibility;
+} & ({
+    sharedSession: false;
     isolationScheme?: never;
 } | {
-    reuse: true;
+    sharedSession: true;
     isolationScheme: BrowserIsolationScheme;
 });
+/** A tab the agent opened in the personal workspace: theirs, as many as they like, and never on the wire. */
+export type PersonalBrowser = Browser;
 export declare const ALLOWED_BROWSER_URL_SCHEMES: readonly ["http:", "https:"];
 export declare function isAllowedBrowserUrl(url: string): boolean;
 export type TaskPhase = 
@@ -469,7 +474,7 @@ export type TaskAttribute = TaskAttributeBase & ({
     value: string;
 } | {
     type: "contact";
-    contact: Contact;
+    party: Contact;
 } | {
     type: "timestamp";
     at: IsoTimestamp;
@@ -500,10 +505,10 @@ export interface TaskHandlingStep {
  */
 export type TaskCompletion = {
     completionMode: "agent-command";
-    completionAllowance?: DurationSeconds;
+    wrapAllowance?: DurationSeconds;
 } | {
     completionMode: "provider-automatic";
-    completionAllowance: DurationSeconds;
+    wrapAllowance: DurationSeconds;
 };
 /**
  * A consultation in progress on a task: who is being consulted, and since when where the provider
@@ -520,7 +525,7 @@ export interface TaskConsultation {
  * `requested` while nobody has joined; `joined`, with `leadId`, once somebody has.
  */
 export interface TaskLead {
-    status: "requested" | "joined";
+    stage: "requested" | "joined";
     leadId?: UserId;
     note?: string;
     since: IsoTimestamp;
@@ -535,21 +540,21 @@ export interface TaskAssisting {
     since: IsoTimestamp;
 }
 /**
- * A tier of the organisation's structure, by the id its manifest declares -- or one of the four
- * a typical organisation has, `DEFAULT_TIERS`, when the manifest declares no ladder. The protocol
- * never describes the chain: which tiers a person passes through is the structure's to know.
+ * A level of the organisation's structure, by the id its manifest declares -- or one of the four
+ * a typical organisation has, `DEFAULT_LEVELS`, when the manifest declares no ladder. The protocol
+ * never describes the chain: which levels a person passes through is the structure's to know.
  */
-export type Tier = string;
-/** A tier the structure has, with the label a desk shows for "who decided". */
-export interface TierDeclaration {
-    id: Tier;
+export type Level = string;
+/** A level the structure has, with the label a desk shows for "who decided". */
+export interface LevelDeclaration {
+    id: Level;
     label: string;
 }
 /**
- * The tiers a typical organisation has: the ladder in force when a manifest declares no
- * `orgTiers`. A manifest that declares any states its whole ladder outright.
+ * 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.
  */
-export declare const DEFAULT_TIERS: readonly [{
+export declare const DEFAULT_LEVELS: readonly [{
     readonly id: "org";
     readonly label: "Your organisation";
 }, {
@@ -563,14 +568,14 @@ export declare const DEFAULT_TIERS: readonly [{
     readonly label: "You";
 }];
 /** The ladder in force for a manifest: exactly what it declares, or the defaults when it declares none. */
-export declare function effectiveTiers(declared: readonly TierDeclaration[] | undefined): TierDeclaration[];
+export declare function effectiveLevels(declared: readonly LevelDeclaration[] | undefined): LevelDeclaration[];
 /**
- * Something the queue could allow, locked above the person: the tier that made it unchangeable,
- * and why if they said. `person` never locks their own value, and the queue is not a tier --
+ * Something the queue could allow, locked above the person: the level that made it unchangeable,
+ * and why if they said. `person` never locks their own value, and the queue is not a level --
  * what the queue does not allow at all is simply absent.
  */
 export interface Locked {
-    lockedBy: Tier;
+    lockedBy: Level;
     reason?: string;
 }
 /**
@@ -586,7 +591,8 @@ export type Task<C extends Channel = Channel> = {
     taskType: string;
     capabilities: TaskCapabilities<C>;
     browsers: TaskBrowser[];
-    contact?: Contact;
+    /** The person or entity on the other end of this task. Who the task is with; `contacts` on the snapshot is the directory. */
+    party?: Contact;
     phase: TaskPhase;
     /** The identifier an agent reads back to a customer, where the provider has one. */
     reference?: string;
@@ -782,7 +788,7 @@ export interface BreakReason {
     label: string;
     group?: string;
     kind?: BreakKind;
-    /** Survives `accepting: false`: a mandatory rest is not something a busy hour can cancel. */
+    /** Survives `mayAsk: false`: a mandatory rest is not something a busy hour can cancel. */
     alwaysAvailable?: true;
 }
 export interface BreakRequest {
@@ -809,8 +815,8 @@ export type ImposedBreak = {
 export interface BreakState {
     approval: BreakApproval;
     /** Whether the agent may ask at all. Distinct from the fate of a request already made. */
-    accepting: boolean;
-    /** Shown when `accepting` is false, such as "Busy hours". */
+    mayAsk: boolean;
+    /** Shown when `mayAsk` is false, such as "Busy hours". */
     refusedReason?: string;
     decisionReason?: string;
     retryAfterMs?: number;
@@ -883,7 +889,7 @@ export interface TeamRoster {
 export type PolicyKey = Exclude<keyof TaskCapabilities<"voice">, keyof SharedTaskCapabilities> | Exclude<keyof TaskCapabilities<"chat">, keyof SharedTaskCapabilities> | Exclude<keyof TaskCapabilities<"email">, keyof SharedTaskCapabilities> | "dial" | `skill:${string}`;
 /** On for everyone, off for everyone, or the agent's own choice. Only `hold`, `mute` and skills may be `agent`. */
 export type TeamPolicySetting = "on" | "off" | "agent";
-/** One policy as the lead sees it: the setting, who set it, and `lockedBy` when a tier above the team made it theirs to keep. */
+/** One policy as the lead sees it: the setting, who set it, and `lockedBy` when a level above the team made it theirs to keep. */
 export interface TeamPolicy extends Resolved {
     setting: TeamPolicySetting;
 }
@@ -937,7 +943,7 @@ export interface TeamBreakCommandRequest {
  * `ended` once primary handling'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 = "ready" | "ended";
+export type TaskMediaState = "started" | "ended";
 export interface VoiceMediaSession {
     remoteAudio: MediaStream;
     setMuted(muted: boolean): void;
@@ -959,27 +965,27 @@ export type OpenMediaResult = {
 /**
  * What the team may leave to the person: a capability by its own name -- `hold`, `mute` -- or a
  * skill by its provider id. The same key as in `Task.capabilities`, because it is the same
- * capability seen at another tier. Callback and new call are never the person's; they are the
+ * capability seen at another level. Callback and new call are never the person's; they are the
  * team's, on or off, within what the queue allows.
  */
 export type PreferenceId = "hold" | "mute" | `skill:${string}`;
 /**
- * Who stated a value as it stands: a tier -- `person` among them -- or `provisioning`, the
- * protocol's own word for "no tier has said anything and the provider's default applies".
+ * Who stated a value as it stands: a level -- `person` among them -- or `provisioning`, the
+ * protocol's own word for "no level has said anything and the provider's default applies".
  * Nothing is hidden for want of a row.
  */
-export type SetBy = Tier | "provisioning";
+export type SetBy = Level | "provider";
 /** What every resolved value carries: who set it, and who locked it if anyone did. */
 export interface Resolved {
     setBy: SetBy;
-    lockedBy?: Tier;
+    lockedBy?: Level;
     /** Given with `lockedBy`, where whoever locked it said why. */
     reason?: string;
 }
 /**
  * One choice the team may leave to the person, with where it stands and who set it. The provider
  * keeps it: it is the person's across sessions, written through `setPreference`. Listed whether
- * or not anyone has stated it, and even when a tier above has since locked it.
+ * or not anyone has stated it, and even when a level above has since locked it.
  */
 export interface AgentPreference extends Resolved {
     id: PreferenceId;
@@ -1001,8 +1007,8 @@ export type PreferenceResult = {
     failure: ProtocolFailure;
 };
 export interface Snapshot<C extends Channel = Channel> {
-    status: ConnectionStatus;
-    sessionId: string;
+    transport: TransportStatus;
+    loginId: string;
     break: BreakState;
     /** Every task currently owned by this agent for this provider. */
     tasks: Task<C>[];
@@ -1027,7 +1033,7 @@ export interface SummaryMetric {
     label: string;
     value: string;
 }
-export interface ProviderSummary {
+export interface QueueSummary {
     title: string;
     subtitle?: string;
     waitingCount: number;
@@ -1039,13 +1045,13 @@ export type ProviderEvent<C extends Channel = Channel> = {
     reason: "reconnected" | "provider-requested";
     snapshot: Snapshot<C>;
 } | {
-    type: "provider-status";
+    type: "transport-status";
     status: "connecting" | "active";
     message?: string;
 } | {
-    type: "provider-status";
+    type: "transport-status";
     status: "error";
-    recovery: ConnectionRecovery;
+    recovery: TransportRecovery;
     message?: string;
 } | {
     type: "break-state";
@@ -1060,7 +1066,7 @@ export type ProviderEvent<C extends Channel = Channel> = {
     type: "task-updated";
     task: Task<C>;
 } | {
-    type: "task-media-ready";
+    type: "task-media-started";
     taskId: TaskId;
 } | {
     type: "task-media-ended";
@@ -1076,8 +1082,8 @@ export type ProviderEvent<C extends Channel = Channel> = {
     announcedAt: IsoTimestamp;
     expiresAt?: IsoTimestamp;
 } | {
-    type: "provider-summary";
-    summary: ProviderSummary;
+    type: "queue-summary";
+    summary: QueueSummary;
 } | {
     type: "team-updated";
     team: TeamRoster;
@@ -1096,7 +1102,7 @@ export type ProviderEvent<C extends Channel = Channel> = {
 export interface ProviderEventEnvelope<C extends Channel = Channel> {
     id: string;
     /** The login this belongs to. */
-    sessionId: string;
+    loginId: string;
     occurredAt: IsoTimestamp;
     event: ProviderEvent<C>;
 }
@@ -1221,11 +1227,11 @@ export interface BrowserSessionKeyInput {
  * guard -- comparing the identity -- never fires on a demotion, because the thing that changed is
  * not the thing being compared. Key order does not matter, and `team: {}` is not `team` absent.
  */
-export declare function sameCapabilities(a: SessionCapabilities, b: SessionCapabilities): boolean;
+export declare function sameCapabilities(a: UserCapabilities, b: UserCapabilities): boolean;
 /**
  * The storage-profile key a reusing browser shares, or `undefined` where it shares nothing.
  *
- * Fails closed. A browser with `reuse: false` has no key; nor does a reusing one whose scheme is
+ * Fails closed. A browser with `sharedSession: false` has no key; nor does a reusing one whose scheme is
  * missing or unknown -- the type forbids that, but an adapter compiled against another version can
  * still send it, and the safe reading is "do not share", never "share with everyone named the
  * same". Every part is encoded, separator included, before joining, so a tab called `a.b`

package/dist/index.js

@@ -51,18 +51,18 @@ export function isAllowedBrowserUrl(url) {
     }
 }
 /**
- * The tiers a typical organisation has: the ladder in force when a manifest declares no
- * `orgTiers`. A manifest that declares any states its whole ladder outright.
+ * 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.
  */
-export const DEFAULT_TIERS = [
+export const DEFAULT_LEVELS = [
     { id: "org", label: "Your organisation" },
     { id: "site", label: "Your site" },
     { id: "team", label: "Your team" },
     { id: "person", label: "You" },
 ];
 /** The ladder in force for a manifest: exactly what it declares, or the defaults when it declares none. */
-export function effectiveTiers(declared) {
-    return [...(declared ?? DEFAULT_TIERS)];
+export function effectiveLevels(declared) {
+    return [...(declared ?? DEFAULT_LEVELS)];
 }
 // ---------------------------------------------------------------------------
 // Task commands.
@@ -157,7 +157,7 @@ export function sameCapabilities(a, b) {
 /**
  * The storage-profile key a reusing browser shares, or `undefined` where it shares nothing.
  *
- * Fails closed. A browser with `reuse: false` has no key; nor does a reusing one whose scheme is
+ * Fails closed. A browser with `sharedSession: false` has no key; nor does a reusing one whose scheme is
  * missing or unknown -- the type forbids that, but an adapter compiled against another version can
  * still send it, and the safe reading is "do not share", never "share with everyone named the
  * same". Every part is encoded, separator included, before joining, so a tab called `a.b`
@@ -165,7 +165,7 @@ export function sameCapabilities(a, b) {
  */
 export function browserSessionKey(input) {
     const { providerId, taskId, taskType, browser } = input;
-    if (browser.reuse !== true)
+    if (browser.sharedSession !== true)
         return undefined;
     // `encodeURIComponent` leaves `.` untouched, and `.` is the separator: a raw join would let
     // provider `Acme.Voice` with type `Support` forge the key of `Acme` with `Voice.Support`.

package/dist/testing.d.ts

@@ -120,7 +120,7 @@ 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-ready` and
+ * 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`.
  */
@@ -162,11 +162,11 @@ export declare function assertBreakBeginsAfterTask(steps: readonly BreakOnTaskSt
  * 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" | "completionAllowance">, mediaEndedAt: string, observedDeadline: string | undefined, toleranceMs?: number): void;
+export declare function assertWrapTimeout(task: Pick<TaskCompletion, "completionMode" | "wrapAllowance">, mediaEndedAt: 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. */
-export declare function assertBrowserIsolationAndReuse(left: BrowserIsolationScenario, right: BrowserIsolationScenario, expectedReuse: boolean): void;
+export declare function assertBrowserSessionIsolation(left: BrowserIsolationScenario, right: BrowserIsolationScenario, expectedReuse: boolean): void;
 /**
  * Asserts that no two distinct scenarios in `scenarios` derive the same session key.
  * Feed it adversarial names — a provider called `A.B` against a task type called