@xema/omni-protocol 0.1.130 → 0.1.132

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -11,6 +11,7 @@ system.
11
11
 
12
12
  | Path | |
13
13
  | --- | --- |
14
+ | `PURPOSE.md` | **Why.** What the protocol is trying to achieve, and how choices in it are made. |
14
15
  | `guide.md` | **The protocol.** The terms, the shapes, the rules, and how an adapter is declared, connected and held to them. |
15
16
  | `guide/` | One file per role and channel: `agent.md`, `lead.md`, `queue.md`, `breaks.md`, `phone.md`, `voice.md`, `chat.md`, `email.md`. Each points back into `guide.md` for what it relies on. |
16
17
  | `src/index.ts` | The TypeScript declarations. |
package/dist/index.d.ts CHANGED
@@ -888,19 +888,19 @@ export interface Browser {
888
888
  }
889
889
  /**
890
890
  * A tab the task brought: fixed at the task's definition -- count and details -- with why it is
891
- * there, whether its session is shared across tasks, and whether the agent may read its URL. The
891
+ * there, whether its profile is shared across tasks, and whether the agent may read its URL. The
892
892
  * union is what makes a reusing browser with no scheme fail to compile rather than inherit a
893
- * default -- which is how two tasks end up sharing a session nobody intended.
893
+ * default -- which is how two tasks end up sharing a profile nobody intended.
894
894
  */
895
895
  export type TaskBrowser = Browser & {
896
896
  purpose: string;
897
897
  /** 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. */
898
898
  urlVisibility?: UrlVisibility;
899
899
  } & ({
900
- sharedSession: false;
900
+ sharedProfile: false;
901
901
  isolationScheme?: never;
902
902
  } | {
903
- sharedSession: true;
903
+ sharedProfile: true;
904
904
  isolationScheme: BrowserIsolationScheme;
905
905
  });
906
906
  /** A tab the agent opened in the personal workspace: theirs, as many as they like, and never on the wire. */
@@ -2173,7 +2173,7 @@ export interface HistorySpan {
2173
2173
  export declare function historySpans(steps: readonly TaskHistoryStep[]): HistorySpan[];
2174
2174
  /** Whether an absent `by` means "could not attribute" rather than "nobody was involved". */
2175
2175
  export declare function historyStepExpectsAPerson(step: HistoryStep): boolean;
2176
- export interface BrowserSessionKeyInput {
2176
+ export interface BrowserProfileKeyInput {
2177
2177
  /** `Manifest.id`, never `displayName`: only the id is unique across an installation and stable. */
2178
2178
  providerId: string;
2179
2179
  /** The task's assignment: a task-scoped session lives one assignment, never the next customer's. */
@@ -2192,13 +2192,13 @@ export declare function sameCapabilities(a: UserCapabilities, b: UserCapabilitie
2192
2192
  /**
2193
2193
  * The storage-profile key a reusing browser shares, or `undefined` where it shares nothing.
2194
2194
  *
2195
- * Fails closed. A browser with `sharedSession: false` has no key; nor does a reusing one whose scheme is
2195
+ * Fails closed. A browser with `sharedProfile: false` has no key; nor does a reusing one whose scheme is
2196
2196
  * missing or unknown -- the type forbids that, but an adapter compiled against another version can
2197
2197
  * still send it, and the safe reading is "do not share", never "share with everyone named the
2198
2198
  * same". Every part is encoded, separator included, before joining, so a tab called `a.b`
2199
2199
  * cannot collide with a provider called `a` and a tab called `b`.
2200
2200
  */
2201
- export declare function browserSessionKey(input: BrowserSessionKeyInput): string | undefined;
2201
+ export declare function browserProfileKey(input: BrowserProfileKeyInput): string | undefined;
2202
2202
  /**
2203
2203
  * The comparison key for a contact number. Never for display: keep the original value for that.
2204
2204
  *
package/dist/index.js CHANGED
@@ -249,15 +249,15 @@ export function sameCapabilities(a, b) {
249
249
  /**
250
250
  * The storage-profile key a reusing browser shares, or `undefined` where it shares nothing.
251
251
  *
252
- * Fails closed. A browser with `sharedSession: false` has no key; nor does a reusing one whose scheme is
252
+ * Fails closed. A browser with `sharedProfile: false` has no key; nor does a reusing one whose scheme is
253
253
  * missing or unknown -- the type forbids that, but an adapter compiled against another version can
254
254
  * still send it, and the safe reading is "do not share", never "share with everyone named the
255
255
  * same". Every part is encoded, separator included, before joining, so a tab called `a.b`
256
256
  * cannot collide with a provider called `a` and a tab called `b`.
257
257
  */
258
- export function browserSessionKey(input) {
258
+ export function browserProfileKey(input) {
259
259
  const { providerId, assignmentId, taskType, browser } = input;
260
- if (browser.sharedSession !== true)
260
+ if (browser.sharedProfile !== true)
261
261
  return undefined;
262
262
  // `encodeURIComponent` leaves `.` untouched, and `.` is the separator: a raw join would let
263
263
  // provider `Acme.Voice` with type `Support` forge the key of `Acme` with `Voice.Support`.
package/dist/testing.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Snapshot, type Task, type BreakStatus, type BrowserSessionKeyInput, type Channel, type ConnectContext, type Host, type HostGuarantees, type HostMute, type SessionStore, type HostReport, type Manifest, type ProviderEvent } from "./index.js";
1
+ import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Snapshot, type Task, type BreakStatus, type BrowserProfileKeyInput, type Channel, type ConnectContext, type Host, type HostGuarantees, type HostMute, type SessionStore, type HostReport, type Manifest, type ProviderEvent } from "./index.js";
2
2
  import { type ProtocolViolation } from "./validation.js";
3
3
  export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation } from "./validation.js";
4
4
  /**
@@ -297,13 +297,13 @@ export interface BreakOnTaskStep {
297
297
  */
298
298
  export declare function assertBreakBeginsAfterTask(steps: readonly BreakOnTaskStep[]): void;
299
299
  /** One browser in one task of one provider. `providerId` is `Manifest.id`, never `displayName`. */
300
- export type BrowserIsolationScenario = BrowserSessionKeyInput;
301
- /** Validates whether two task-browser definitions should share one browser session. */
302
- export declare function assertBrowserSessionIsolation(left: BrowserIsolationScenario, right: BrowserIsolationScenario, expectedReuse: boolean): void;
300
+ export type BrowserIsolationScenario = BrowserProfileKeyInput;
301
+ /** Validates whether two task-browser definitions should share one browser profile. */
302
+ export declare function assertBrowserProfileIsolation(left: BrowserIsolationScenario, right: BrowserIsolationScenario, expectedReuse: boolean): void;
303
303
  /**
304
304
  * Asserts that no two distinct scenarios in `scenarios` derive the same session key.
305
305
  * Feed it adversarial names — a provider called `A.B` against a task type called
306
306
  * `B`, casing variants, separators — because a collision silently shares cookies,
307
307
  * storage, and permissions between two backends.
308
308
  */
309
- export declare function assertNoBrowserSessionKeyCollisions(scenarios: readonly BrowserIsolationScenario[]): void;
309
+ export declare function assertNoBrowserProfileKeyCollisions(scenarios: readonly BrowserIsolationScenario[]): void;
package/dist/testing.js CHANGED
@@ -1,4 +1,4 @@
1
- import { browserSessionKey, sameCapabilities, } from "./index.js";
1
+ import { browserProfileKey, sameCapabilities, } from "./index.js";
2
2
  import { assertNoViolations, validateAuthenticationState, validateBreakTransition, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateUserDetails, observeRules, ruleTested, validateHostMute, validateHostRecording, validateSessionStore, validateHistoryReport, validateManifest, validateResult, validateSnapshot, validateTask, validateLanguages, validateTimeZone, validatePhone, validateTaskCommand, isTimeZone, sameTimeZone, } from "./validation.js";
3
3
  export { ProtocolConformanceError, assertNoViolations } from "./validation.js";
4
4
  /**
@@ -2558,16 +2558,16 @@ export function assertBreakBeginsAfterTask(steps) {
2558
2558
  }
2559
2559
  }
2560
2560
  /** The session key one scenario derives, or `undefined` where the browser shares nothing. */
2561
- const sessionKeyFor = (scenario) => browserSessionKey(scenario);
2562
- /** Validates whether two task-browser definitions should share one browser session. */
2563
- export function assertBrowserSessionIsolation(left, right, expectedReuse) {
2564
- const leftKey = sessionKeyFor(left);
2565
- const rightKey = sessionKeyFor(right);
2561
+ const profileKeyFor = (scenario) => browserProfileKey(scenario);
2562
+ /** Validates whether two task-browser definitions should share one browser profile. */
2563
+ export function assertBrowserProfileIsolation(left, right, expectedReuse) {
2564
+ const leftKey = profileKeyFor(left);
2565
+ const rightKey = profileKeyFor(right);
2566
2566
  // A browser that does not share its session has no session key at all, so two of them never share one.
2567
2567
  // Treating "no key" as a match would report sharing nobody asked for.
2568
2568
  const actualReuse = leftKey !== undefined && leftKey === rightKey;
2569
2569
  if (actualReuse !== expectedReuse) {
2570
- throw new Error(`Browser session sharing mismatch: expected ${expectedReuse}, received ${actualReuse} (${String(leftKey)} vs ${String(rightKey)})`);
2570
+ throw new Error(`Browser profile sharing mismatch: expected ${expectedReuse}, received ${actualReuse} (${String(leftKey)} vs ${String(rightKey)})`);
2571
2571
  }
2572
2572
  }
2573
2573
  /**
@@ -2576,15 +2576,15 @@ export function assertBrowserSessionIsolation(left, right, expectedReuse) {
2576
2576
  * `B`, casing variants, separators — because a collision silently shares cookies,
2577
2577
  * storage, and permissions between two backends.
2578
2578
  */
2579
- export function assertNoBrowserSessionKeyCollisions(scenarios) {
2579
+ export function assertNoBrowserProfileKeyCollisions(scenarios) {
2580
2580
  const byKey = new Map();
2581
2581
  for (const scenario of scenarios) {
2582
- const key = sessionKeyFor(scenario);
2582
+ const key = profileKeyFor(scenario);
2583
2583
  if (key === undefined)
2584
2584
  continue;
2585
2585
  const existing = byKey.get(key);
2586
2586
  if (existing) {
2587
- throw new Error(`Browser session key collision on '${key}': ` +
2587
+ throw new Error(`Browser profile key collision on '${key}': ` +
2588
2588
  `${JSON.stringify({ provider: existing.providerId, taskType: existing.taskType, tab: existing.browser.name })} and ` +
2589
2589
  `${JSON.stringify({ provider: scenario.providerId, taskType: scenario.taskType, tab: scenario.browser.name })}`);
2590
2590
  }
@@ -894,7 +894,7 @@ function validateBrowsers(value, path, into) {
894
894
  seen.add(browser.id);
895
895
  }
896
896
  // The name is an input to a `TAB_NAME` isolation scheme: two tabs with one name would
897
- // silently share a session.
897
+ // silently share a profile.
898
898
  if (into.filled(browser.name, "task.browser.name", `${at}.name`, "a browser needs a name")) {
899
899
  if (names.has(browser.name))
900
900
  into.add("task.browser.name.unique", `${at}.name`, `duplicate browser name: ${browser.name}`);
@@ -917,7 +917,7 @@ function validateBrowsers(value, path, into) {
917
917
  // Reuse and its scheme travel together. A reusing browser with no scheme would otherwise
918
918
  // inherit whatever a host happened to default to, which is how two tasks end up sharing a
919
919
  // session nobody intended. The guide names the rule for the missing case.
920
- if (browser.sharedSession === true) {
920
+ if (browser.sharedProfile === true) {
921
921
  if (browser.isolationScheme === undefined) {
922
922
  into.add("task.browser.isolationScheme.required", `${at}.isolationScheme`, `a reusing browser must declare one of: ${ISOLATION_SCHEME_VALUES.join(", ")}`);
923
923
  }
@@ -925,11 +925,11 @@ function validateBrowsers(value, path, into) {
925
925
  into.require(ISOLATION_SCHEME_VALUES.includes(browser.isolationScheme), "task.browser.isolationScheme", `${at}.isolationScheme`, `an isolation scheme must be one of: ${ISOLATION_SCHEME_VALUES.join(", ")}`);
926
926
  }
927
927
  }
928
- else if (browser.sharedSession === false) {
928
+ else if (browser.sharedProfile === false) {
929
929
  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");
930
930
  }
931
931
  else {
932
- into.add("task.browser.sharedSession", `${at}.sharedSession`, "a browser must say whether its session is shared across tasks");
932
+ into.add("task.browser.sharedProfile", `${at}.sharedProfile`, "a browser must say whether its profile is shared across tasks");
933
933
  }
934
934
  });
935
935
  }
package/guide/agent.md CHANGED
@@ -225,7 +225,7 @@ ending, a history report, a command -- would land on whichever assignment is ope
225
225
  So the assignment id is unique within the provider and never reused: where the platform's handle
226
226
  never comes back, the adapter passes it through; where it does, the adapter mints the assignment id
227
227
  and keeps the mapping, and the agent computer never learns which. A late event finds the assignment it
228
- belongs to or is refused, and a task-scoped browser session (`PROVIDER_NAME__ASSIGNMENT_ID__TAB_NAME`)
228
+ belongs to or is refused, and a task-scoped browser profile (`PROVIDER_NAME__ASSIGNMENT_ID__TAB_NAME`)
229
229
  lives one assignment, never the next customer's cookies. A dial the agent application placed was
230
230
  already safe, since its outcome is placed by the agent application's own `dialId`; where the
231
231
  assignment earns its place is everything the agent application does not mint --
@@ -689,23 +689,23 @@ Each `TaskBrowser` defines one named browser in the task workspace.
689
689
  | `name` | Agent-facing tab label, unique within the task, and an input to schemes containing `TAB_NAME`. |
690
690
  | `purpose` | Human-readable explanation of the browser's role. |
691
691
  | `url` | Initial URL. Must use `http:` or `https:`; see below. Later navigation comes from Chromium. |
692
- | `sharedSession` | Required. `false` creates a task-specific browser session. |
693
- | `isolationScheme` | **Required when `sharedSession` is `true`**, and rejected when it is `false`. There is no default: see below. |
692
+ | `sharedProfile` | Required. `false` creates a task-specific browser profile. |
693
+ | `isolationScheme` | **Required when `sharedProfile` is `true`**, and rejected when it is `false`. There is no default: see below. |
694
694
  | `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; an agent application that declares `guarantees.browserUrlVisibility` honours it tab by tab, and a provider checks that guarantee before it sends such a URL at all. |
695
695
 
696
696
  ##### Choosing an isolation scheme
697
697
 
698
698
  Every scheme is supported and the provider picks the one its deployment needs. There is no
699
- default, and a `sharedSession: true` browser that declares none is invalid — the type will not compile
699
+ default, and a `sharedProfile: true` browser that declares none is invalid — the type will not compile
700
700
  it and `validateSnapshot` reports `task.browser.isolationScheme.required`.
701
701
 
702
- That is deliberate. Sharing a signed-in session decides **who else may see those credentials**,
702
+ That is deliberate. Sharing a signed-in profile decides **who else may see those credentials**,
703
703
  and it is not a decision to inherit from whichever value happened to be the default. `TAB_NAME`
704
704
  keys on the tab label alone, so two providers that each publish a browser named "CRM" share one
705
- signed-in session — legitimate where a deployment wants exactly that, and a silent credential
705
+ signed-in profile — legitimate where a deployment wants exactly that, and a silent credential
706
706
  leak where it does not. It remains available; it has to be asked for.
707
707
 
708
- `browserSessionKey` fails closed: given a reusing browser with no scheme it returns `undefined`
708
+ `browserProfileKey` fails closed: given a reusing browser with no scheme it returns `undefined`
709
709
  and the browser is isolated. The safe reading of an invalid declaration is "do not share", never
710
710
  "share with everyone named the same".
711
711
 
@@ -718,7 +718,7 @@ page rather than following a disallowed URL, and `isAllowedBrowserUrl()` is the
718
718
 
719
719
  ##### Reuse and isolation
720
720
 
721
- With `sharedSession: true`, definitions producing the same isolation key share one **storage profile**:
721
+ With `sharedProfile: true`, definitions producing the same isolation key share one **storage profile**:
722
722
  cookies, local storage, session storage, permissions, and cached credentials. Different keys are
723
723
  isolated from one another.
724
724
 
@@ -727,7 +727,7 @@ own visible label, and their own navigation state and history even when their ke
727
727
  scheme that omits `TAB_NAME`, such as `PROVIDER_NAME__TASK_TYPE_NAME`, deliberately places every
728
728
  named browser of that task type in one signed-in profile without merging them into one page.
729
729
 
730
- `browserSessionKey()` derives the key. Every part is escaped before the `.` separator is applied,
730
+ `browserProfileKey()` derives the key. Every part is escaped before the `.` separator is applied,
731
731
  because `encodeURIComponent` leaves `.` untouched and a raw join would let one value forge
732
732
  another key: provider `Acme.Voice` with task type `Support` would otherwise produce the same key
733
733
  as provider `Acme` with task type `Voice.Support`, silently placing two providers in one cookie
@@ -742,7 +742,7 @@ browsers: [
742
742
  name: "CRM",
743
743
  purpose: "Contact record",
744
744
  url: "https://crm.example.com/contact/42",
745
- sharedSession: true,
745
+ sharedProfile: true,
746
746
  isolationScheme: BROWSER_ISOLATION_SCHEMES.PROVIDER_NAME__TASK_TYPE_NAME__TAB_NAME,
747
747
  }
748
748
  ]
@@ -765,7 +765,7 @@ reused.
765
765
 
766
766
  **`PROVIDER_NAME` is `manifest.id`, never `manifest.displayName`.** Only the id is required unique
767
767
  across an installation; two providers may legitimately share a display label, and keying a cookie
768
- jar on one would put them in the same signed-in session. The id is also stable across launches,
768
+ jar on one would put them in the same signed-in profile. The id is also stable across launches,
769
769
  where a display name may be re-worded — and a changed key silently signs the agent out of every
770
770
  browser that used it.
771
771
 
package/guide.md CHANGED
@@ -671,13 +671,13 @@ type TaskBrowser = Browser & {
671
671
  purpose: string;
672
672
  urlVisibility?: UrlVisibility;
673
673
  } & (
674
- | { sharedSession: false; isolationScheme?: never }
675
- | { sharedSession: true; isolationScheme: BrowserIsolationScheme }
674
+ | { sharedProfile: false; isolationScheme?: never }
675
+ | { sharedProfile: true; isolationScheme: BrowserIsolationScheme }
676
676
  );
677
677
 
678
678
  type PersonalBrowser = Browser;
679
679
 
680
- type BrowserSessionKeyInput = {
680
+ type BrowserProfileKeyInput = {
681
681
  providerId: string;
682
682
  assignmentId: AssignmentId;
683
683
  taskType: string;
@@ -3336,8 +3336,8 @@ cannot be established from TypeScript structure alone.
3336
3336
  | `assertForcedBreakStopsTheRest(forcedOn, candidates, stopped)` | A forced break on one provider stops the agent everywhere else: capacity zero stated on every other usable provider holding capacity, nothing on the forcing one, nothing on a dead session. See **Forced breaks** in `guide/breaks.md`. |
3337
3337
  | `assertBreakBeginsAfterTask(steps)` | A break asked for on a task is committed as `starting-after-task` while work remains and reaches `on-break` only once nothing is outstanding — never beside a task, never later than the step that has none. |
3338
3338
  | `assertDeniedAndRetriedBreak(states)` | A denial transitions directly to `not-requested`; a later request can still be granted. |
3339
- | `assertBrowserSessionIsolation(left, right, expected)` | Browser reuse follows only the declared isolation scheme. |
3340
- | `assertNoBrowserSessionKeyCollisions(scenarios)` | No two distinct scenarios derive the same session key. Feed it adversarial names. |
3339
+ | `assertBrowserProfileIsolation(left, right, expected)` | Browser reuse follows only the declared isolation scheme. |
3340
+ | `assertNoBrowserProfileKeyCollisions(scenarios)` | No two distinct scenarios derive the same profile key. Feed it adversarial names. |
3341
3341
 
3342
3342
  Adapters should run the relevant scenarios against deterministic test state before publishing.
3343
3343
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xema/omni-protocol",
3
- "version": "0.1.130",
3
+ "version": "0.1.132",
4
4
  "description": "The Omni protocol: the contract every provider adapter implements",
5
5
  "type": "module",
6
6
  "license": "MIT",