@xema/omni-protocol 0.1.130 → 0.1.131
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/dist/index.d.ts +7 -7
- package/dist/index.js +3 -3
- package/dist/testing.d.ts +5 -5
- package/dist/testing.js +10 -10
- package/dist/validation.js +4 -4
- package/guide/agent.md +11 -11
- package/guide.md +5 -5
- package/package.json +1 -1
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
|
|
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
|
|
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
|
-
|
|
900
|
+
sharedProfile: false;
|
|
901
901
|
isolationScheme?: never;
|
|
902
902
|
} | {
|
|
903
|
-
|
|
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
|
|
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 `
|
|
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
|
|
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 `
|
|
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
|
|
258
|
+
export function browserProfileKey(input) {
|
|
259
259
|
const { providerId, assignmentId, taskType, browser } = input;
|
|
260
|
-
if (browser.
|
|
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
|
|
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 =
|
|
301
|
-
/** Validates whether two task-browser definitions should share one browser
|
|
302
|
-
export declare function
|
|
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
|
|
309
|
+
export declare function assertNoBrowserProfileKeyCollisions(scenarios: readonly BrowserIsolationScenario[]): void;
|
package/dist/testing.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
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
|
|
2562
|
-
/** Validates whether two task-browser definitions should share one browser
|
|
2563
|
-
export function
|
|
2564
|
-
const leftKey =
|
|
2565
|
-
const rightKey =
|
|
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
|
|
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
|
|
2579
|
+
export function assertNoBrowserProfileKeyCollisions(scenarios) {
|
|
2580
2580
|
const byKey = new Map();
|
|
2581
2581
|
for (const scenario of scenarios) {
|
|
2582
|
-
const key =
|
|
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
|
|
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
|
}
|
package/dist/validation.js
CHANGED
|
@@ -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
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
|
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
|
-
| `
|
|
693
|
-
| `isolationScheme` | **Required when `
|
|
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 `
|
|
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
|
|
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
|
|
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
|
-
`
|
|
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 `
|
|
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
|
-
`
|
|
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
|
-
|
|
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
|
|
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
|
-
| {
|
|
675
|
-
| {
|
|
674
|
+
| { sharedProfile: false; isolationScheme?: never }
|
|
675
|
+
| { sharedProfile: true; isolationScheme: BrowserIsolationScheme }
|
|
676
676
|
);
|
|
677
677
|
|
|
678
678
|
type PersonalBrowser = Browser;
|
|
679
679
|
|
|
680
|
-
type
|
|
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
|
-
| `
|
|
3340
|
-
| `
|
|
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
|
|