@xema/omni-protocol 0.1.27 → 0.1.28

package/dist/index.d.ts

@@ -62,7 +62,7 @@ export interface BrowserAccess {
 }
 export interface PersonalBrowserCapability {
     access: BrowserAccess;
-    accessPolicyScope?: "initial-url" | "all-navigation";
+    accessAppliesTo?: "initial-url" | "all-navigation";
 }
 export type DialDestinations = "contacts-only" | "any-number";
 export interface DialCapability {
@@ -237,7 +237,7 @@ export type CompleteAuthenticationResult = {
     failure: AuthenticationFailure;
 };
 export type AuthenticationActionResult = {
-    status: "accepted";
+    status: "applied";
 } | {
     status: "failed";
     failure: AuthenticationFailure;
@@ -262,7 +262,7 @@ export interface AuthenticationSession {
 export type HostAudioInput = 
 /** Omni has the microphone. `flowing` is false while the hardware or OS says no audio moves through it. */
 {
-    status: "ready";
+    status: "available";
     localAudio: MediaStream;
     flowing: boolean;
 }
@@ -281,7 +281,7 @@ export type HostAudioUnavailableReason = "no-device" | "denied" | "not-asked" |
 /** Why the host has no speaker: no device, or one that was removed. */
 export type HostOutputUnavailableReason = "no-device" | "lost";
 export type HostAudioOutput = {
-    status: "ready";
+    status: "available";
 } | {
     status: "unavailable";
     reason: HostOutputUnavailableReason;
@@ -303,7 +303,20 @@ export interface HostReport {
     };
 }
 /** The host, as an adapter may ask it: a report now, and every change for the life of the connection. */
+/**
+ * What the host promises the provider, declared once per connection. Presence is the guarantee:
+ * an absent key is a host that makes no such promise, and a provider that needs one checks before
+ * it acts -- tokenising a URL it would otherwise send in the clear, or declining to offer work
+ * that only a person may accept.
+ */
+export interface HostGuarantees {
+    /** Every task browser's `urlVisibility` is honoured in this host's chrome, tab by tab. */
+    browserUrlVisibility?: true;
+    /** A `consent` offer is accepted only by the person's own explicit act, never on their behalf. */
+    personConsent?: true;
+}
 export interface Host {
+    guarantees: HostGuarantees;
     report(): HostReport;
     subscribe(listener: (report: HostReport) => void): Unsubscribe;
 }
@@ -353,7 +366,7 @@ export interface DispositionCode {
 }
 export interface DispositionRules {
     required?: boolean;
-    notes?: "required" | "optional" | "hidden";
+    notes?: "required" | "optional" | "none";
     codes?: DispositionCode[];
 }
 export interface Destination {
@@ -609,8 +622,13 @@ export type Task<C extends Channel = Channel> = {
     assisting?: never;
     media?: never;
 });
-/** What the provider wants of Omni's acceptance policy for one offer. */
-export type AcceptanceMode = "no-preference" | "require-agent-acceptance" | "require-automatic-acceptance";
+/**
+ * What the provider wants of Omni's acceptance policy for one offer. Present only where Omni was
+ * willing to accept for the agent (`autoAcceptTasks: true`): `consent` is therefore always the
+ * provider's requirement of an explicit acceptance, never Omni's own policy, which travels as an
+ * absent field.
+ */
+export type AcceptanceMode = "no-preference" | "consent" | "automatic";
 export type TaskOutcome = {
     type: "completed";
     by: "agent" | "provider";
@@ -827,7 +845,7 @@ export interface BreakState {
     imposed?: ImposedBreak;
 }
 export type CapacityResult = {
-    status: "accepted";
+    status: "applied";
 } | {
     status: "failed";
     failure: ProtocolFailure;
@@ -888,7 +906,7 @@ export interface TeamRoster {
 /** A capability a team policy can name: any task control, new call, or a skill by its provider id. */
 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";
+export type TeamPolicySetting = "on" | "off" | "person";
 /** 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;

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Snapshot, type TaskCompletion, type BreakApproval, type BrowserSessionKeyInput, type Channel, type ConnectContext, type Host, type HostReport, type Manifest, type ProviderEvent } from "./index.js";
+import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Snapshot, type TaskCompletion, type BreakApproval, type BrowserSessionKeyInput, type Channel, type ConnectContext, type Host, type HostGuarantees, type HostReport, type Manifest, type ProviderEvent } from "./index.js";
 import { type ProtocolViolation } from "./validation.js";
 export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation } from "./validation.js";
 /**
@@ -126,7 +126,7 @@ export declare function assertBreakFollowsItsRequests(envelopes: readonly Provid
  */
 export declare function assertMediaFollowsTheTask(envelopes: readonly ProviderEventEnvelope[], snapshot?: Snapshot): void;
 /** A host that reports one thing and never changes: what most adapter tests hand `exerciseAdapter`. */
-export declare function stillHost(report?: HostReport): Host;
+export declare function stillHost(report?: HostReport, guarantees?: HostGuarantees): Host;
 /** One provider as the host sees it when freezing a break attempt's participant set. */
 export interface BreakCandidate {
     id: string;

package/dist/testing.js

@@ -1,5 +1,5 @@
 import { browserSessionKey, effectiveLevels, sameCapabilities, } from "./index.js";
-import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateHostReport, validateManifest, validateResult, validateSnapshot, } from "./validation.js";
+import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateManifest, validateResult, validateSnapshot, } from "./validation.js";
 export { ProtocolConformanceError, assertNoViolations } from "./validation.js";
 /**
  * A part of the contract a run may never reach: state nothing obliges an adapter to publish, so
@@ -246,6 +246,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         // testing a host that cannot exist. Its first report and every later one are validated, a
         // voice connection's host reports its audio and no other does, and the host the adapter
         // receives is wrapped so the harness can tell whether the adapter ever asked.
+        violations.push(...validateHostGuarantees(context.host.guarantees, "context.host.guarantees"));
         const first = context.host.report();
         violations.push(...validateHostReport(first, "context.host"));
         const hasAudio = isRecord(first) && first.audio !== undefined;
@@ -260,6 +261,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         });
         let consulted = false;
         const host = {
+            guarantees: context.host.guarantees,
             report: () => { consulted = true; return context.host.report(); },
             subscribe: listener => { consulted = true; return context.host.subscribe(listener); },
         };
@@ -769,8 +771,8 @@ export function assertMediaFollowsTheTask(envelopes, snapshot) {
     assertNoViolations(found, "The media follows the task");
 }
 /** A host that reports one thing and never changes: what most adapter tests hand `exerciseAdapter`. */
-export function stillHost(report = { online: true }) {
-    return { report: () => report, subscribe: () => () => undefined };
+export function stillHost(report = { online: true }, guarantees = {}) {
+    return { guarantees, report: () => report, subscribe: () => () => undefined };
 }
 const usableLogin = (status) => status === "authenticated" || status === "refreshing";
 /**

package/dist/validation.d.ts

@@ -43,10 +43,10 @@ export declare function validateTeamRoster(roster: unknown, path?: string, conte
 export declare function validateSnapshot(snapshot: unknown, manifest: unknown, path?: string, context?: ReaderContext): ProtocolViolation[];
 export declare function validateEventEnvelope(envelope: unknown, manifest: unknown, path?: string, context?: ReaderContext): ProtocolViolation[];
 /**
- * Validates the host's report as Omni publishes it to an adapter. This is Omni's output, so the
- * check belongs to the host's own tests and to the harness, which validates whatever host a test
- * hands the adapter.
+ * What a host promises. Presence is the guarantee, so a key declared `false` is refused: a
+ * promise withheld is an absent key, never a false one, exactly as a capability is.
  */
+export declare function validateHostGuarantees(guarantees: unknown, path?: string): ProtocolViolation[];
 export declare function validateHostReport(report: unknown, path?: string): ProtocolViolation[];
 /** The connection methods whose results `validateResult` knows. */
 export type ResultMethod = "execute" | "dial" | "setCapacity" | "requestBreak" | "commitBreak" | "cancelBreak" | "endBreak" | "executeTeamBreak" | "executeTeamConsult" | "openMedia" | "setPreference" | "executeTeamPolicy";

package/dist/validation.js

@@ -42,7 +42,7 @@ const TASK_PHASES = membersOf({
 });
 const COMPLETION_MODES = membersOf({ "agent-command": true, "provider-automatic": true });
 const ACCEPTANCE_MODES = membersOf({
-    "no-preference": true, "require-agent-acceptance": true, "require-automatic-acceptance": true,
+    "no-preference": true, "consent": true, "automatic": true,
 });
 const TRANSPORT_STATUSES = membersOf({ connecting: true, active: true, error: true });
 const AUTHENTICATION_METHODS = membersOf({ "browser-sso": true, credentials: true });
@@ -61,9 +61,9 @@ const HANDLING_STEPS = membersOf({
 const DESTINATION_KINDS = membersOf({ queue: true, agent: true, external: true });
 const CUSTOM_UI_CONTROLS = membersOf({ button: true, toggle: true, "menu-item": true });
 const CUSTOM_UI_PLACEMENTS = membersOf({ primary: true, secondary: true, overflow: true });
-const NOTES_POLICIES = membersOf({ required: true, optional: true, hidden: true });
+const NOTES_RULES = membersOf({ required: true, optional: true, none: true });
 const ACCESS_MODES = membersOf({ "allow-all": true, "block-all": true });
-const ACCESS_POLICY_SCOPES = membersOf({
+const ACCESS_APPLIES_TO = membersOf({
     "initial-url": true, "all-navigation": true,
 });
 const DIAL_DESTINATION_POLICIES = membersOf({ "contacts-only": true, "any-number": true });
@@ -247,8 +247,8 @@ function validateIdleCapabilities(value, channel, path, into) {
         }
         else {
             validateBrowserAccess(browser.access, `${path}.personalBrowser.access`, into);
-            if (browser.accessPolicyScope !== undefined) {
-                into.oneOf(browser.accessPolicyScope, ACCESS_POLICY_SCOPES, "manifest.personalBrowser.accessPolicyScope", `${path}.personalBrowser.accessPolicyScope`);
+            if (browser.accessAppliesTo !== undefined) {
+                into.oneOf(browser.accessAppliesTo, ACCESS_APPLIES_TO, "manifest.personalBrowser.accessAppliesTo", `${path}.personalBrowser.accessAppliesTo`);
             }
         }
     }
@@ -417,7 +417,7 @@ function validateDispositions(value, path, into) {
         into.add("task.dispositions.required.codes", `${path}.codes`, "a required disposition policy must publish at least one code");
     }
     if (value.notes !== undefined)
-        into.oneOf(value.notes, NOTES_POLICIES, "task.dispositions.notes", `${path}.notes`);
+        into.oneOf(value.notes, NOTES_RULES, "task.dispositions.notes", `${path}.notes`);
     if (value.codes === undefined)
         return;
     if (!Array.isArray(value.codes)) {
@@ -486,11 +486,11 @@ function validateCustomCapabilities(value, path, into) {
     });
 }
 const DEFAULT_LEVEL_IDS = DEFAULT_LEVELS.map(level => level.id);
-const POLICY_SETTINGS = membersOf({ on: true, off: true, agent: true });
+const POLICY_SETTINGS = membersOf({ on: true, off: true, person: true });
 const POLICY_KEYS = new Set([
     ...TASK_CAPABILITIES.voice, ...TASK_CAPABILITIES.chat, ...TASK_CAPABILITIES.email, "dial",
 ].filter(name => name !== "browsers" && name !== "dispositions" && name !== "custom"));
-const AGENT_SETTABLE = /^(hold|mute|skill:.+)$/;
+const PERSON_SETTABLE = /^(hold|mute|skill:.+)$/;
 const isLocked = (value) => isPlainObject(value) && value.lockedBy !== undefined;
 /** The level ids in force: the manifest's, or the defaults when the caller holds no manifest. */
 const levelIds = (levels) => levels ?? DEFAULT_LEVEL_IDS;
@@ -1320,7 +1320,7 @@ function validateTeamPoliciesInto(value, path, into, levels) {
             continue;
         }
         if (into.oneOf(policy.setting, POLICY_SETTINGS, "team.policy.setting", `${at}.setting`)) {
-            into.require(policy.setting !== "agent" || AGENT_SETTABLE.test(key), "team.policy.agent", `${at}.setting`, `${key} is the team's, on or off; only hold, mute and skills may be left to the person`);
+            into.require(policy.setting !== "person" || PERSON_SETTABLE.test(key), "team.policy.person", `${at}.setting`, `${key} is the team's, on or off; only hold, mute and skills may be left to the person`);
         }
         validateResolvedInto(policy, "team.policy", at, levels, into);
         into.require(policy.setBy !== "person", "team.policy.setBy", `${at}.setBy`, "a team policy is not set by a person");
@@ -1361,6 +1361,26 @@ function validateUnavailable(value, rule, path, into) {
  * check belongs to the host's own tests and to the harness, which validates whatever host a test
  * hands the adapter.
  */
+const HOST_GUARANTEES = membersOf({ browserUrlVisibility: true, personConsent: true });
+/**
+ * What a host promises. Presence is the guarantee, so a key declared `false` is refused: a
+ * promise withheld is an absent key, never a false one, exactly as a capability is.
+ */
+export function validateHostGuarantees(guarantees, path = "host.guarantees") {
+    const into = new Collector();
+    if (!isPlainObject(guarantees)) {
+        into.add("host.guarantees.shape", path, "a host declares its guarantees as an object, empty when it makes none");
+        return into.violations;
+    }
+    for (const [name, declared] of Object.entries(guarantees)) {
+        if (declared === undefined)
+            continue;
+        if (!into.require(HOST_GUARANTEES.includes(name), "host.guarantee.unknown", `${path}.${name}`, `${name} is not a guarantee this contract names: ${HOST_GUARANTEES.join(", ")}`))
+            continue;
+        into.require(declared === true, "host.guarantee.value", `${path}.${name}`, "a guarantee is declared by presence; one the host does not make is omitted, never false");
+    }
+    return into.violations;
+}
 export function validateHostReport(report, path = "host") {
     const into = new Collector();
     if (!isPlainObject(report)) {
@@ -1379,7 +1399,7 @@ export function validateHostReport(report, path = "host") {
     if (!isPlainObject(input)) {
         into.add("host.audio.input.shape", at, "audio carries its input");
     }
-    else if (input.status === "ready") {
+    else if (input.status === "available") {
         into.require(typeof input.localAudio === "object" && input.localAudio !== null, "host.audio.input.localAudio", `${at}.localAudio`, "a ready input carries the captured microphone");
         into.require(typeof input.flowing === "boolean", "host.audio.input.flowing", `${at}.flowing`, "a ready input says whether audio is flowing through it");
         into.require(input.failure === undefined, "host.audio.input.failure.unexpected", `${at}.failure`, "a ready input carries no failure");
@@ -1392,14 +1412,14 @@ export function validateHostReport(report, path = "host") {
         into.require(input.flowing === undefined, "host.audio.input.flowing.unexpected", `${at}.flowing`, "an unavailable input has nothing to flow");
     }
     else {
-        into.add("host.audio.input.status", `${at}.status`, `an input is ready or unavailable, not ${String(input.status)}`);
+        into.add("host.audio.input.status", `${at}.status`, `an input is available or unavailable, not ${String(input.status)}`);
     }
     const output = report.audio.output;
     const out = `${path}.audio.output`;
     if (!isPlainObject(output)) {
         into.add("host.audio.output.shape", out, "audio carries its output");
     }
-    else if (output.status === "ready") {
+    else if (output.status === "available") {
         into.require(output.failure === undefined, "host.audio.output.failure.unexpected", `${out}.failure`, "a ready output carries no failure");
         into.require(output.reason === undefined, "host.audio.output.reason.unexpected", `${out}.reason`, "a ready output has no reason to be unavailable");
     }
@@ -1408,7 +1428,7 @@ export function validateHostReport(report, path = "host") {
         validateUnavailable(output, "host.audio.output", out, into);
     }
     else {
-        into.add("host.audio.output.status", `${out}.status`, `an output is ready or unavailable, not ${String(output.status)}`);
+        into.add("host.audio.output.status", `${out}.status`, `an output is available or unavailable, not ${String(output.status)}`);
     }
     return into.violations;
 }
@@ -1417,7 +1437,7 @@ export function validateHostReport(report, path = "host") {
 const RESULT_STATUSES = {
     execute: { success: "applied", failure: "failed" },
     dial: { success: "dialled", failure: "failed" },
-    setCapacity: { success: "accepted", failure: "failed" },
+    setCapacity: { success: "applied", failure: "failed" },
     requestBreak: { success: "requested", failure: "failed" },
     commitBreak: { success: "committed", failure: "failed" },
     cancelBreak: { success: "cancelled", failure: "failed" },

package/guide.md

@@ -155,7 +155,7 @@ type BrowserAccess = {
 
 type PersonalBrowserCapability = {
   access: BrowserAccess;
-  accessPolicyScope?: "initial-url" | "all-navigation";
+  accessAppliesTo?: "initial-url" | "all-navigation";
 };
 
 type DialDestinations = "contacts-only" | "any-number";
@@ -253,11 +253,11 @@ type HostAudioUnavailableReason = "no-device" | "denied" | "not-asked" | "in-use
 type HostOutputUnavailableReason = "no-device" | "lost";
 
 type HostAudioInput =
-  | { status: "ready"; localAudio: MediaStream; flowing: boolean }
+  | { status: "available"; localAudio: MediaStream; flowing: boolean }
   | { status: "unavailable"; reason: HostAudioUnavailableReason; failure: ProtocolFailure };
 
 type HostAudioOutput =
-  | { status: "ready" }
+  | { status: "available" }
   | { status: "unavailable"; reason: HostOutputUnavailableReason; failure: ProtocolFailure };
 
 type UrlVisibility = "full" | "domain" | "hidden";
@@ -270,7 +270,13 @@ type HostReport = {
   };
 };
 
+type HostGuarantees = {
+  browserUrlVisibility?: true;
+  personConsent?: true;
+};
+
 type Host = {
+  guarantees: HostGuarantees;
   report(): HostReport;
   subscribe(listener: (report: HostReport) => void): Unsubscribe;
 };
@@ -315,7 +321,7 @@ type CompleteAuthenticationResult =
   | { status: "rejected"; failure: AuthenticationFailure };
 
 type AuthenticationActionResult =
-  | { status: "accepted" }
+  | { status: "applied" }
   | { status: "failed"; failure: AuthenticationFailure };
 
 type Unsubscribe = () => void;
@@ -374,7 +380,7 @@ type AgentCapacity = {
 };
 
 type CapacityResult =
-  | { status: "accepted" }
+  | { status: "applied" }
   | { status: "failed"; failure: ProtocolFailure };
 ```
 
@@ -413,7 +419,7 @@ type DispositionCode = { id: string; label: string; group?: string };
 
 type DispositionRules = {
   required?: boolean;
-  notes?: "required" | "optional" | "hidden";
+  notes?: "required" | "optional" | "none";
   codes?: DispositionCode[];
 };
 
@@ -609,8 +615,8 @@ type Task<C extends Channel = Channel> = {
 
 type AcceptanceMode =
   | "no-preference"
-  | "require-agent-acceptance"
-  | "require-automatic-acceptance";
+  | "consent"
+  | "automatic";
 
 type TaskOutcome =
   | { type: "completed"; by: "agent" | "provider" }
@@ -747,8 +753,8 @@ controls — is content, and is never locked.
 
 **A lead sets the team's policy from their roster.** A login that declares
 `capabilities.team.policyControl` may `executeTeamPolicy({ type: "set", capability, setting })`
-with `on`, `off`, or `agent`, for any task control, `dial`, or a skill — and only `hold`, `mute`
-and skills may be `agent`; callback and new call are the team's, on or off, within what the queue
+with `on`, `off`, or `person`, for any task control, `dial`, or a skill — and only `hold`, `mute`
+and skills may be `person`; callback and new call are the team's, on or off, within what the queue
 allows. The roster carries `policies` for such a login: every policy as it stands, who set it, and
 `lockedBy` where a level above the team made it theirs to keep, which the lead sees and cannot
 change — `executeTeamPolicy` on it answers `failed` with `omni.capability-not-enabled`.
@@ -856,7 +862,7 @@ type PolicyKey =
   | "dial"
   | `skill:${string}`;
 
-type TeamPolicySetting = "on" | "off" | "agent";
+type TeamPolicySetting = "on" | "off" | "person";
 
 type TeamPolicy = Resolved & {
   setting: TeamPolicySetting;
@@ -1474,12 +1480,12 @@ idleCapabilities: {
 | `access.mode` | `allow-all` permits unmatched URLs; `block-all` denies unmatched URLs. |
 | `access.allowList` | URL-pattern exceptions permitted when the mode is `block-all`. |
 | `access.blockList` | Explicit denials. A match takes precedence over the same policy's allow list and mode. |
-| `accessPolicyScope` | `all-navigation` by default: every redirect and navigation is checked. `initial-url` checks the starting URL alone. |
+| `accessAppliesTo` | `all-navigation` by default: every redirect and navigation is checked. `initial-url` checks the starting URL alone. |
 
 Patterns use the standard `URLPattern` syntax. Omni owns browser navigation, and the browser is
 hidden when no active provider contributes one.
 
-`accessPolicyScope` defaults to `all-navigation`: every redirect and subsequent navigation is
+`accessAppliesTo` defaults to `all-navigation`: every redirect and subsequent navigation is
 validated against the current combined policy, not only the starting URL. A provider may set
 `initial-url` to check the first hop alone, but that has to be asked for. A `block-all` policy
 enforced only on the initial URL stops nothing — one redirect leaves it — so the permissive
@@ -1682,7 +1688,7 @@ them from what arrives later.
 | `team` | This login leads a team. The provider publishes a `TeamRoster` to it on every snapshot — `[]` when nobody is in it — and to nobody else. |
 | `team.breakControl` | This lead may act on their team's breaks through `executeTeamBreak` — place, release, decide, set policy — as far as the provider supports; a command it lacks answers `omni.capability-not-enabled`. Omni asks for a decision only against a member whose `break` is `awaiting-decision`, so a provider that grants on request is never asked to decide. Requires `executeTeamBreak`. |
 | `team.consultControl` | This lead may join a member's call on request. Requires `executeTeamConsult`. |
-| `team.policyControl` | This lead sets the team's policy per capability — on, off, or the agent's — within what the queue allows. Requires `executeTeamPolicy`; the roster carries `policies`. |
+| `team.policyControl` | This lead sets the team's policy per capability — on, off, or the person's — within what the queue allows. Requires `executeTeamPolicy`; the roster carries `policies`. |
 | `preferences` | What the team left to this person, with where each stands and who set it. Omitted when nothing was. Requires `setPreference`. See **Who decides what an agent may do**. |
 
 A session action is available only when both the capability and Omni provisioning permit it.
@@ -1765,7 +1771,7 @@ settles. The adapter must not persist raw credentials. Field-specific failures m
 
 `cancelAuthentication(flowId)` cancels an abandoned Browser SSO window or credentials form and
 releases its temporary state. It does not sign out an already authenticated session. It answers
-`accepted`; a repeat, or a flow that already ended, is nothing to act on and answers `accepted`
+`applied`; a repeat, or a flow that already ended, is nothing to act on and answers `applied`
 too, by the rule that a command asking for a state answers success when that state holds.
 
 ### Completion and failures
@@ -1979,24 +1985,27 @@ provider includes an acceptance directive with each allocation:
 | Directive | Contract |
 | --- | --- |
 | `no-preference` | The provider leaves acceptance to Omni; with `autoAcceptTasks: true`, Omni accepts automatically. |
-| `require-agent-acceptance` | Omni presents **Accept** and waits for the agent. |
-| `require-automatic-acceptance` | Omni accepts immediately without agent interaction. |
+| `consent` | The provider requires the person's explicit consent: Omni presents **Accept** and waits, whatever its own policy would have done. A host that declares `guarantees.personConsent` promises exactly this; a provider checks it before offering work only a person may take. |
+| `automatic` | Omni accepts immediately without agent interaction. |
 
 When Omni sent `autoAcceptTasks: false`, the provider omits `acceptanceMode` and every task
-requires agent acceptance.
+requires agent acceptance. The two are never confused on the wire: `consent` is always the
+provider's requirement, stated on a wire where Omni was willing to accept for the agent; Omni's own
+no-auto-accept policy puts no word on the wire at all — the field is absent, and the **Accept**
+press is Omni's doing, not the provider's.
 
 **An absent value means `true`**, as `readyOnLogin` does, because an agent who has signed in and
 gone ready is telling the deployment they are working. Requiring a press before every contact is
 the exception a provisioning file asks for, not the state it falls into when a flag is missing.
 
 Nothing is given away by that default. `acceptanceMode` is the provider's own control and outranks
-it: `require-agent-acceptance` puts the decision back in the agent's hands for any task where it
+it: `consent` puts the decision back in the agent's hands for any task where it
 belongs, whatever the host was configured with.
 
 An automatically accepted task still arrives through `task-offered`.
 
 Agent-initiated work arrives through `task-offered` with
-`acceptanceMode: "require-automatic-acceptance"`.
+`acceptanceMode: "automatic"`.
 
 ### Pending
 
@@ -2011,7 +2020,7 @@ declare const task: Task;
 const allocation = {
   type: "task-offered",
   task,
-  acceptanceMode: "require-agent-acceptance",
+  acceptanceMode: "consent",
   allocationExpiresAt: "2026-08-25T10:41:07.000Z",
   preparationEndsAt: "2026-08-25T10:40:37.000Z",
 } satisfies Extract<ProviderEvent, { type: "task-offered" }>;
@@ -2021,7 +2030,7 @@ The rule the phase exists to express: **nothing is acquired on the agent's behal
 is pending.** A host that carries media must not open the microphone until the task is
 accepted. Omni does not open the task's browsers either — a task that rings out costs nothing.
 
-When manual acceptance is required, Omni offers the agent an **Accept** control. The call is the
+When consent is required, Omni offers the agent an **Accept** control. The call is the
 medium the task arrives on, not a separate decision.
 
 **Once a task is accepted, the call that comes with it is answered.** Omni has no discretion
@@ -2331,7 +2340,7 @@ Each `TaskBrowser` defines one named browser in the task workspace.
 | `url` | Initial URL. Must use `http:` or `https:`; see below. Later navigation comes from Chromium. |
 | `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. |
+| `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; a host that declares `guarantees.browserUrlVisibility` honours it tab by tab, and a provider checks that guarantee before it sends such a URL at all. |
 
 ##### Choosing an isolation scheme
 
@@ -2464,7 +2473,7 @@ capabilities: {
 | Field | Contract |
 | --- | --- |
 | `required` | When `true`, Omni must collect a code before issuing `complete`. A required policy must publish at least one code. |
-| `notes` | `required`, `optional`, or `hidden`; controls the free-text field beside the code. |
+| `notes` | `required`, `optional`, or `none`; controls the free-text field beside the code. |
 | `codes` | Codes Omni offers. `id` values are non-empty and unique; Omni sends the chosen `id` as `TaskCommand.complete.disposition`. |
 
 With `dispositions: true` Omni shows a Complete control and sends `complete` with no code, because
@@ -2693,7 +2702,7 @@ everywhere; success is not.
 
 | Method | Succeeded |
 | --- | --- |
-| `setCapacity` | `accepted` |
+| `setCapacity` | `applied` |
 | `requestBreak` | `requested` |
 | `commitBreak` | `committed` |
 | `cancelBreak` | `cancelled` |
@@ -3080,7 +3089,7 @@ executeTeamConsult({ command: { type: "decline", requestId: "req-7", reason: "In
 ```
 
 **On `join` the provider bridges three parties and the lead is on a task of their own**, on the
-same task id, arriving on the lead's connection as `task-offered` with `require-automatic-acceptance`
+same task id, arriving on the lead's connection as `task-offered` with `automatic`
 -- the way a call an agent placed themselves arrives -- and carrying `assisting`. The agent's task
 moves to `lead: { stage: "joined", leadId }`. A join is the lead's own act, so capacity does not
 trigger it; but from then on it is an outstanding task the provider counts against the lead's
@@ -3190,12 +3199,27 @@ the microphone once as the voice connection opens, so the permission prompt land
 is signing in rather than over a contact, prompts, retries on the agent's request, tells the agent
 what failed, and reports. It never decides for the adapter what a missing microphone means.
 
+**The host also guarantees, and a promise the provider cannot see is not one it can rely on.**
+Two of this contract's obligations fall on the host rather than the provider — honouring a task
+browser's `urlVisibility`, and taking a `consent` offer only on the person's own press — and more
+than one desk speaks this contract. So `ConnectContext.host.guarantees` says which promises the
+connected host makes, declared once per connection, presence being the guarantee exactly as it is
+the permission everywhere else:
+
+| Guarantee | Contract |
+| --- | --- |
+| `browserUrlVisibility` | Every task browser's `urlVisibility` is honoured in this host's chrome, tab by tab. A provider that would send a caller's number in a URL checks this first and tokenises where the promise is absent. |
+| `personConsent` | A `consent` offer is accepted only by the person's own explicit act, never on their behalf. A provider whose work may only be taken by a human checks this first and does not offer it where the promise is absent. |
+
+A guarantee the host does not make is an absent key, never `false` — `validateHostGuarantees`
+refuses a false one, as it refuses a name this contract does not list.
+
 | Field | Contract |
 | --- | --- |
 | `online` | Whether the host has a network interface up. Not a claim that anything is reachable — the adapter knows whether it can reach its own platform far better than the host does — so `false` is a reason not to go ready and `true` is not a reason to. |
 | `audio` | Present on a voice connection, absent where there is no audio. |
-| `audio.input` | `ready` with `localAudio` — the microphone as captured, the same stream `openMedia` receives — and `flowing`, false while the hardware or OS says no audio moves through it (a headset's own mute switch, which Omni's Mute control never touches). `unavailable` with `reason`, since each wants a different fix from the agent: `no-device`; `denied`; `not-asked`, which a host that asks at connect never publishes; `in-use`, a device present and permitted that another application holds — on an agent desktop the commonest of all; `lost`, a capture that ended. A host decides the reason from the devices before the error name: a browser can report a permission error on a machine with no microphone at all, and "grant permission" is the wrong instruction for an agent who needs to plug one in. `failure` carries the words Omni showed them. |
-| `audio.output` | `ready`, or `unavailable` with `reason` — `no-device`, or `lost` for one removed — and `failure`: an agent who cannot hear is as unable to take a call as one who cannot speak. |
+| `audio.input` | `available` with `localAudio` — the microphone as captured, the same stream `openMedia` receives — and `flowing`, false while the hardware or OS says no audio moves through it (a headset's own mute switch, which Omni's Mute control never touches). `unavailable` with `reason`, since each wants a different fix from the agent: `no-device`; `denied`; `not-asked`, which a host that asks at connect never publishes; `in-use`, a device present and permitted that another application holds — on an agent desktop the commonest of all; `lost`, a capture that ended. A host decides the reason from the devices before the error name: a browser can report a permission error on a machine with no microphone at all, and "grant permission" is the wrong instruction for an agent who needs to plug one in. `failure` carries the words Omni showed them. |
+| `audio.output` | `available`, or `unavailable` with `reason` — `no-device`, or `lost` for one removed — and `failure`: an agent who cannot hear is as unable to take a call as one who cannot speak. |
 
 Omni republishes the report whenever it changes — a permission granted late, a headset unplugged,
 a network gone — and it publishes a state, not a flicker: a change that resolves within moments is
@@ -3647,7 +3671,8 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | `validateEventEnvelope(envelope, manifest)` | Envelope identity, timestamp, and the payload for each event type. |
 | `validateContact(contact)` | Contact field shapes and attribute keys. Every field is optional, so this checks what is present rather than what is missing. |
 | `validateScheduledActivity(activity)` | Required activity fields and start/end ordering. |
-| `validateHostReport(report)` | The host's own report as published to an adapter: `online`, and where there is audio, an input that is `ready` with the microphone and `flowing`, or `unavailable` with a reason and the failure that says why, and an output that is `ready` or `unavailable` with its failure. The harness validates whatever host a test hands the adapter; `stillHost(report)` builds one that never changes. |
+| `validateHostGuarantees(guarantees)` | What a host promises: only the guarantees this contract names, each declared by presence and never `false`. The harness validates the guarantees of whatever host a test hands the adapter. |
+| `validateHostReport(report)` | The host's own report as published to an adapter: `online`, and where there is audio, an input that is `available` with the microphone and `flowing`, or `unavailable` with a reason and the failure that says why, and an output that is `available` or `unavailable` with its failure. The harness validates whatever host a test hands the adapter; `stillHost(report)` builds one that never changes. |
 | `validateResult(result, method)` | What a connection method answered: the status it gives, a failure where the status says so and nowhere else, the failure's shape, and that an `omni.` code is one this contract names. |
 | `validateAuthenticationState(state)` | The identity each state must carry, the capabilities a usable login declares, and the expiry that only `authenticated` may. Omni applies it to every state a session publishes — the republished as much as the first. |
 

package/package.json

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