@xema/omni-protocol 0.1.26 → 0.1.27

package/dist/index.d.ts

@@ -342,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 {
@@ -443,10 +444,10 @@ export type TaskBrowser = Browser & {
     /** 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;
 } & ({
-    reuse: false;
+    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. */
@@ -473,7 +474,7 @@ export type TaskAttribute = TaskAttributeBase & ({
     value: string;
 } | {
     type: "contact";
-    contact: Contact;
+    party: Contact;
 } | {
     type: "timestamp";
     at: IsoTimestamp;
@@ -590,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;
@@ -1031,7 +1033,7 @@ export interface SummaryMetric {
     label: string;
     value: string;
 }
-export interface ProviderSummary {
+export interface QueueSummary {
     title: string;
     subtitle?: string;
     waitingCount: number;
@@ -1080,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;
@@ -1229,7 +1231,7 @@ export declare function sameCapabilities(a: UserCapabilities, b: UserCapabilitie
 /**
  * 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

@@ -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

@@ -166,7 +166,7 @@ export declare function assertWrapTimeout(task: Pick<TaskCompletion, "completion
 /** 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

package/dist/testing.js

@@ -32,7 +32,7 @@ const STATE_SUBJECTS = [
 // `ProviderEvent` without a row here, or a row it lacks, is a compile error.
 const EVENT_TYPES = {
     snapshot: true, "transport-status": true, "break-state": true, "task-offered": true, "task-updated": true,
-    "task-media-started": true, "task-media-ended": true, "task-ended": true, announcement: true, "provider-summary": true,
+    "task-media-started": true, "task-media-ended": true, "task-ended": true, announcement: true, "queue-summary": true,
     "team-updated": true, "contacts-updated": true, "calendar-updated": true,
 };
 const CONTRACT_SUBJECTS = [
@@ -854,14 +854,14 @@ export function assertWrapTimeout(task, mediaEndedAt, observedDeadline, toleranc
 /** The session key one scenario derives, or `undefined` where the browser shares nothing. */
 const sessionKeyFor = (scenario) => browserSessionKey(scenario);
 /** Validates whether two task-browser definitions should share one browser session. */
-export function assertBrowserIsolationAndReuse(left, right, expectedReuse) {
+export function assertBrowserSessionIsolation(left, right, expectedReuse) {
     const leftKey = sessionKeyFor(left);
     const rightKey = sessionKeyFor(right);
-    // A browser that does not reuse has no session key at all, so two of them never share one.
-    // Treating "no key" as a match would report reuse nobody asked for.
+    // A browser that does not share its session has no session key at all, so two of them never share one.
+    // Treating "no key" as a match would report sharing nobody asked for.
     const actualReuse = leftKey !== undefined && leftKey === rightKey;
     if (actualReuse !== expectedReuse) {
-        throw new Error(`Browser reuse mismatch: expected ${expectedReuse}, received ${actualReuse} (${String(leftKey)} vs ${String(rightKey)})`);
+        throw new Error(`Browser session sharing mismatch: expected ${expectedReuse}, received ${actualReuse} (${String(leftKey)} vs ${String(rightKey)})`);
     }
 }
 /**

package/dist/validation.js

@@ -200,8 +200,8 @@ function validateScheduledActivityInto(activity, path, into) {
             into.require(Date.parse(activity.endsAt) >= Date.parse(activity.startsAt), "activity.endsAt.order", `${path}.endsAt`, "endsAt must not precede startsAt");
         }
     }
-    if (activity.contact !== undefined)
-        validateContactInto(activity.contact, `${path}.contact`, into);
+    if (activity.party !== undefined)
+        validateContactInto(activity.party, `${path}.party`, into);
     validateAttributes(activity.attributes, `${path}.attributes`, into);
 }
 // ---------------------------------------------------------------------------
@@ -572,7 +572,7 @@ function validateBrowsers(value, path, into) {
         // Reuse and its scheme travel together. A reusing browser with no scheme would otherwise
         // inherit whatever a host happened to default to, which is how two tasks end up sharing a
         // session nobody intended. The guide names the rule for the missing case.
-        if (browser.reuse === true) {
+        if (browser.sharedSession === true) {
             if (browser.isolationScheme === undefined) {
                 into.add("task.browser.isolationScheme.required", `${at}.isolationScheme`, `a reusing browser must declare one of: ${ISOLATION_SCHEME_VALUES.join(", ")}`);
             }
@@ -580,11 +580,11 @@ function validateBrowsers(value, path, into) {
                 into.require(ISOLATION_SCHEME_VALUES.includes(browser.isolationScheme), "task.browser.isolationScheme", `${at}.isolationScheme`, `an isolation scheme must be one of: ${ISOLATION_SCHEME_VALUES.join(", ")}`);
             }
         }
-        else if (browser.reuse === false) {
-            into.require(browser.isolationScheme === undefined, "task.browser.isolationScheme.unexpected", `${at}.isolationScheme`, "a browser that does not reuse must not declare an isolation scheme");
+        else if (browser.sharedSession === false) {
+            into.require(browser.isolationScheme === undefined, "task.browser.isolationScheme.unexpected", `${at}.isolationScheme`, "a browser that does not share its session must not declare an isolation scheme");
         }
         else {
-            into.add("task.browser.reuse", `${at}.reuse`, "a browser must say whether it reuses a session");
+            into.add("task.browser.sharedSession", `${at}.sharedSession`, "a browser must say whether its session is shared across tasks");
         }
     });
 }
@@ -745,8 +745,8 @@ function validateTaskInto(task, context, path, into) {
     if (task.reference !== undefined) {
         into.filled(task.reference, "task.reference", `${path}.reference`, "a reference must not be empty when present");
     }
-    if (task.contact !== undefined)
-        validateContactInto(task.contact, `${path}.contact`, into, context.levels);
+    if (task.party !== undefined)
+        validateContactInto(task.party, `${path}.party`, into, context.levels);
     validateBrowsers(task.browsers, `${path}.browsers`, into);
     validateTaskAttributes(task.attributes, `${path}.attributes`, into);
     validateHandlingHistory(task.handlingHistory, `${path}.handlingHistory`, into);
@@ -1117,7 +1117,7 @@ function validateTaskOutcome(value, path, into) {
             into.add("event.taskEnded.outcome.type", `${path}.type`, `unsupported outcome: ${String(value.type)}`);
     }
 }
-function validateProviderSummary(value, path, into) {
+function validateQueueSummary(value, path, into) {
     if (!isPlainObject(value)) {
         into.add("event.summary.shape", path, "a provider summary must be an object");
         return;
@@ -1238,8 +1238,8 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
                 into.require(typeof event.html === "string", "event.announcement.html", `${at}.html`, "html must be a string when present");
             }
             break;
-        case "provider-summary":
-            validateProviderSummary(event.summary, `${at}.summary`, into);
+        case "queue-summary":
+            validateQueueSummary(event.summary, `${at}.summary`, into);
             break;
         case "team-updated":
             validateTeamRosterInto(event.team, `${at}.team`, { ...context, levels }, into);

package/guide.md

@@ -393,7 +393,7 @@ type ScheduledActivity = {
   title: string;
   startsAt: IsoTimestamp;
   endsAt?: IsoTimestamp;
-  contact?: Contact;
+  party?: Contact;
   attributes?: Attribute[];
 };
 
@@ -492,8 +492,8 @@ type TaskBrowser = Browser & {
   purpose: string;
   urlVisibility?: UrlVisibility;
 } & (
-  | { reuse: false; isolationScheme?: never }
-  | { reuse: true; isolationScheme: BrowserIsolationScheme }
+  | { sharedSession: false; isolationScheme?: never }
+  | { sharedSession: true; isolationScheme: BrowserIsolationScheme }
 );
 
 type PersonalBrowser = Browser;
@@ -507,7 +507,7 @@ type BrowserSessionKeyInput = {
 ```
 
 That union is what makes a reusing browser with no scheme fail to compile rather than inherit a
-default — see **Choosing a reuse scheme**.
+default — see **Choosing an isolation scheme**.
 
 ### Task
 
@@ -529,7 +529,7 @@ type TaskAttributeBase = {
 
 type TaskAttribute = TaskAttributeBase & (
   | { type: "text"; value: string }
-  | { type: "contact"; contact: Contact }
+  | { type: "contact"; party: Contact }
   | { type: "timestamp"; at: IsoTimestamp }
 );
 
@@ -596,7 +596,7 @@ type Task<C extends Channel = Channel> = {
   taskType: string;
   capabilities: TaskCapabilities<C>;
   browsers: TaskBrowser[];
-  contact?: Contact;
+  party?: Contact;
   phase: TaskPhase;
   reference?: string;
   attributes?: TaskAttribute[];
@@ -917,7 +917,7 @@ type OpenMediaRequest = {
 ```ts
 type SummaryMetric = { id: string; label: string; value: string };
 
-type ProviderSummary = {
+type QueueSummary = {
   title: string;
   subtitle?: string;
   waitingCount: number;
@@ -944,7 +944,7 @@ type ProviderEvent =
   | { type: "task-media-ended"; taskId: TaskId }
   | { type: "task-ended"; taskId: TaskId; outcome: TaskOutcome }
   | { type: "announcement"; text: string; html?: string; announcedAt: IsoTimestamp; expiresAt?: IsoTimestamp }
-  | { type: "provider-summary"; summary: ProviderSummary }
+  | { type: "queue-summary"; summary: QueueSummary }
   | { type: "team-updated"; team: TeamRoster }
   | { type: "contacts-updated"; contacts: Contact[] }
   | { type: "calendar-updated"; scheduledActivities: ScheduledActivity[] };
@@ -1526,7 +1526,7 @@ changes.
 | `title` | Required agent-facing activity title. |
 | `startsAt` | Required RFC-3339 start time with an explicit timezone. |
 | `endsAt` | Optional RFC-3339 end time with an explicit timezone. |
-| `contact` | Optional related `Contact`. |
+| `party` | The person the activity reaches — a callback's customer — as a `Contact`. Optional. |
 | `attributes` | Optional ordered `Attribute` entries. Keys must be non-empty. |
 
 **There is no `type` field**, for the reason there is none on `Contact`: an open category is
@@ -2071,7 +2071,7 @@ time. Runtime conformance checks also require the task channel to match its prov
 | `taskType` | Required provider-defined source or category of work, such as a voice `Queue Name`, `Mailbox Folder`, `Chat Source`, `Support`, `Billing`, or `Returns`. |
 | `capabilities` | Controls and workspace features available for this specific task. |
 | `browsers` | Named browser definitions for the task workspace: at least one when the task declares the `browsers` capability, empty when it does not. |
-| `contact` | Optional `Contact` for the person or entity on this task. Often a name and one address; a withheld caller ID may leave nothing to send at all. |
+| `party` | The person or entity on the other end of this task, as a `Contact`: often a name and one address; a withheld caller ID may leave nothing to send at all. Optional. The party is who the task is *with*; `contacts` is the directory. |
 | `phase` | Current canonical task phase: `pending`, `confirmed`, `preparing`, `in-progress`, `paused`, or `completing`. |
 | `media` | Voice only. The task's real-time audio as the provider holds it: `started` while audio is attached, `ended` once it ended, omitted while none is. The provider's word — see **`task-media-started`**. |
 | `reference` | Optional agent-facing reference such as a case, call, conversation, ticket, or message number. It is distinct from the protocol `id`. |
@@ -2091,7 +2091,7 @@ const attributes: TaskAttribute[] = [
     key: "related-contact",
     label: "Related contact",
     type: "contact",
-    contact: { name: "Asha Rao", number: "+919876543210" },
+    party: { name: "Asha Rao", number: "+919876543210" },
   },
   {
     key: "answered",
@@ -2329,14 +2329,14 @@ Each `TaskBrowser` defines one named browser in the task workspace.
 | `name` | Agent-facing tab label, unique within the task, and an input to schemes containing `TAB_NAME`. |
 | `purpose` | Human-readable explanation of the browser's role. |
 | `url` | Initial URL. Must use `http:` or `https:`; see below. Later navigation comes from Chromium. |
-| `reuse` | Required. `false` creates a task-specific browser session. |
-| `isolationScheme` | **Required when `reuse` is `true`**, and rejected when it is `false`. There is no default: see below. |
+| `sharedSession` | Required. `false` creates a task-specific browser session. |
+| `isolationScheme` | **Required when `sharedSession` is `true`**, and rejected when it is `false`. There is no default: see below. |
 | `urlVisibility` | What the agent sees of this tab's URL in Omni's chrome: `hidden`, `domain`, or `full`. Omitted, the URL shows as any browser's does; a provider says `hidden` where the URL carries what the agent may not read — a caller's number, a CRM token. Per browser, on the provider's word; Omni honours it tab by tab. |
 
-##### Choosing a reuse scheme
+##### Choosing an isolation scheme
 
 Every scheme is supported and the provider picks the one its deployment needs. There is no
-default, and a `reuse: true` browser that declares none is invalid — the type will not compile
+default, and a `sharedSession: true` browser that declares none is invalid — the type will not compile
 it and `validateSnapshot` reports `task.browser.isolationScheme.required`.
 
 That is deliberate. Sharing a signed-in session decides **who else may see those credentials**,
@@ -2358,7 +2358,7 @@ page rather than following a disallowed URL, and `isAllowedBrowserUrl()` is the
 
 ##### Reuse and isolation
 
-With `reuse: true`, definitions producing the same isolation key share one **storage profile**:
+With `sharedSession: true`, definitions producing the same isolation key share one **storage profile**:
 cookies, local storage, session storage, permissions, and cached credentials. Different keys are
 isolated from one another.
 
@@ -2382,7 +2382,7 @@ browsers: [
     name: "CRM",
     purpose: "Contact record",
     url: "https://crm.example.com/contact/42",
-    reuse: true,
+    sharedSession: true,
     isolationScheme: BROWSER_ISOLATION_SCHEMES.PROVIDER_NAME__TASK_TYPE_NAME__TAB_NAME,
   }
 ]
@@ -3580,7 +3580,7 @@ Publishes an agent-facing message. `text` is always required and is the accessib
 Optional HTML is sanitized by Omni. `announcedAt` and optional `expiresAt` are RFC-3339 times with
 explicit timezones.
 
-### `provider-summary`
+### `queue-summary`
 
 Publishes the provider's current dashboard contribution. Omni combines only the latest summary from
 each connected provider.
@@ -3742,7 +3742,7 @@ cannot be established from TypeScript structure alone.
 | `assertBreakBeginsAfterTask(steps)` | A break asked for on a task is committed as `starting-after-task` while work remains and reaches `in-effect` only once nothing is outstanding — never beside a task, never later than the step that has none. |
 | `assertDeniedAndRetriedBreak(states)` | A denial transitions directly to `not-requested`; a later request can still be granted. |
 | `assertWrapTimeout(task, mediaEndedAt, deadline, toleranceMs?)` | The wrap deadline equals media end plus the task allowance, within a tolerance that defaults to 1000ms; a task with no allowance has no deadline, and one observed is the violation. |
-| `assertBrowserIsolationAndReuse(left, right, expected)` | Browser reuse follows only the declared isolation scheme. |
+| `assertBrowserSessionIsolation(left, right, expected)` | Browser reuse follows only the declared isolation scheme. |
 | `assertNoBrowserSessionKeyCollisions(scenarios)` | No two distinct scenarios derive the same session key. Feed it adversarial names. |
 
 Adapters should run the relevant scenarios against deterministic test state before publishing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xema/omni-protocol",
-  "version": "0.1.26",
+  "version": "0.1.27",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",