@xema/omni-protocol 0.1.19 → 0.1.21

package/dist/index.d.ts

@@ -111,6 +111,8 @@ export interface Manifest<C extends Channel = Channel> {
     phaseLabels?: TaskPhaseLabels;
     /** Keyed by `taskType`. An entry replaces the channel default outright rather than merging. */
     taskTypePresentation?: Record<string, TaskTypePresentation>;
+    /** The organisation's whole ladder, stated outright, `person` included. Omitted for the typical four, `DEFAULT_TIERS`. */
+    orgTiers?: TierDeclaration[];
 }
 export interface SecretStore {
     get(key: string): Promise<string | undefined>;
@@ -145,6 +147,8 @@ export interface TeamCapabilities {
     breakControl?: true;
     /** This lead may join a member's call on request. Requires `executeTeamConsult`. */
     consultControl?: true;
+    /** This lead sets the team's policy per capability -- on, off, or the agent's -- within what the queue allows. Requires `executeTeamPolicy`. */
+    policyControl?: true;
 }
 /**
  * What this login may do, beyond any one task. It travels with the identity because it is part
@@ -154,6 +158,8 @@ export interface TeamCapabilities {
 export interface SessionCapabilities {
     /** This login may request a break. Requires the four break methods. */
     breaks?: true;
+    /** The choices the team left to this person, with where each stands. Omitted when there are none. Requires `setPreference`. */
+    preferences?: AgentPreference[];
     /** This login leads a team: a `TeamRoster` is published to it on every snapshot, `[]` included. */
     team?: TeamCapabilities;
 }
@@ -286,7 +292,13 @@ export type HostAudioOutput = {
  * network. Omni reports it; the adapter decides what any of it means for its platform and what
  * to relay. `audio` is present on a voice connection.
  */
+/** What Omni's own chrome shows of a task browser's URL: nothing, the domain, or all of it. */
+export type UrlVisibility = "full" | "domain" | "hidden";
 export interface HostReport {
+    /** What the agent can see of a task browser's URL in Omni's chrome. Task browsers only; the personal browser is the agent's. */
+    browsers: {
+        urlVisibility: UrlVisibility;
+    };
     /** Whether the host has a network interface up. Not a claim that anything is reachable: the adapter knows its own platform's reachability better than the host does. */
     online: boolean;
     audio?: {
@@ -317,8 +329,10 @@ export type ConnectionStatus = "connecting" | "active" | "error";
 /** Every field is optional: a provider sends what it knows and omits what it does not. */
 export interface Contact {
     name?: string;
-    number?: string;
-    email?: string;
+    /** The number, or `{ lockedBy }` where the queue says the agent may not see it: the last digits or nothing are sent, never a flag to honour. */
+    number?: Lockable<string>;
+    /** The email, or `{ lockedBy }` where the agent may not see it; it identifies a person as a number does. */
+    email?: Lockable<string>;
     attributes?: Attribute[];
 }
 export interface ScheduledActivity {
@@ -356,6 +370,12 @@ export interface CustomCapability {
         kind: "button" | "toggle" | "menu-item";
         label: string;
         placement: "primary" | "secondary" | "overflow";
+        /** Where the control's work renders: inline in the workspace, or as a page of its own. Inline when absent. */
+        render?: "inline" | "page";
+    };
+    /** What the agent supplies before the action runs; the values travel on the custom command. */
+    prompt?: {
+        fields: CredentialField[];
     };
 }
 export interface SharedTaskCapabilities {
@@ -369,24 +389,24 @@ export interface SharedTaskCapabilities {
  * The channel arms are why `Task<"email">` rejects `hold` at compile time rather than at runtime.
  */
 export type TaskCapabilities<C extends Channel = Channel> = C extends "voice" ? SharedTaskCapabilities & {
-    decline?: true;
-    mute?: true;
-    hold?: true;
-    agentDisconnect?: true;
+    decline?: Lockable<true>;
+    mute?: Lockable<true>;
+    hold?: Lockable<true>;
+    agentDisconnect?: Lockable<true>;
     /** Reach the party again while `completing`; the task returns to `in-progress`. */
-    callback?: true;
-    blindTransfer?: true | DestinationDirectory;
+    callback?: Lockable<true>;
+    blindTransfer?: Lockable<true | DestinationDirectory>;
     /** Park the customer and call a destination first; then `complete` or `cancel`. */
-    consultTransfer?: true | DestinationDirectory;
+    consultTransfer?: Lockable<true | DestinationDirectory>;
     /** Ask a lead to join this call, with a note. The lead's decision arrives on `Task.lead`. */
-    consultLead?: true;
-    conference?: true | DestinationDirectory;
-    recording?: true;
+    consultLead?: Lockable<true>;
+    conference?: Lockable<true | DestinationDirectory>;
+    recording?: Lockable<true>;
 } : C extends "chat" ? SharedTaskCapabilities & {
-    reject?: true;
-    hold?: true;
+    reject?: Lockable<true>;
+    hold?: Lockable<true>;
 } : SharedTaskCapabilities & {
-    reject?: true;
+    reject?: Lockable<true>;
 };
 /**
  * How a reusing browser's session is keyed.
@@ -508,6 +528,50 @@ export interface TaskAssisting {
     note?: string;
     since: IsoTimestamp;
 }
+/**
+ * A tier of the organisation's structure, by the id its manifest declares -- or one of the four
+ * a typical organisation has, `DEFAULT_TIERS`, when the manifest declares no ladder. The protocol
+ * never describes the chain: which tiers a person passes through is the structure's to know.
+ */
+export type Tier = string;
+/** A tier the structure has, with the label a desk shows for "who decided". */
+export interface TierDeclaration {
+    id: Tier;
+    label: string;
+}
+/**
+ * The tiers a typical organisation has: the ladder in force when a manifest declares no
+ * `orgTiers`. A manifest that declares any states its whole ladder outright.
+ */
+export declare const DEFAULT_TIERS: readonly [{
+    readonly id: "org";
+    readonly label: "Your organisation";
+}, {
+    readonly id: "site";
+    readonly label: "Your site";
+}, {
+    readonly id: "team";
+    readonly label: "Your team";
+}, {
+    readonly id: "person";
+    readonly label: "You";
+}];
+/** The ladder in force for a manifest: exactly what it declares, or the defaults when it declares none. */
+export declare function effectiveTiers(declared: readonly TierDeclaration[] | undefined): TierDeclaration[];
+/**
+ * Something the queue could allow, locked above the person: the tier that made it unchangeable,
+ * and why if they said. `person` never locks their own value, and the queue is not a tier --
+ * what the queue does not allow at all is simply absent.
+ */
+export interface Locked {
+    lockedBy: Tier;
+    reason?: string;
+}
+/**
+ * A value, or `{ lockedBy }` in its place: present without permission, saying whose. `lockedBy`
+ * is the discriminant: a value that carries it is the lock, so no `T` may carry that key.
+ */
+export type Lockable<T> = T | Locked;
 export type Task<C extends Channel = Channel> = {
     id: TaskId;
     title: string;
@@ -804,6 +868,25 @@ export interface TeamRoster {
     members: TeamMember[];
     /** Omitted when the login lacks `team.consultControl`; `[]` when nobody is asking. */
     requests?: LeadRequest[];
+    /** The team's policy per capability, as it stands. Present exactly when the login declares `team.policyControl`. */
+    policies?: TeamPolicies;
+}
+/** 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";
+/** One policy as the lead sees it: the setting, who set it, and `lockedBy` when a tier above the team made it theirs to keep. */
+export interface TeamPolicy extends Resolved {
+    setting: TeamPolicySetting;
+}
+export type TeamPolicies = Partial<Record<PolicyKey, TeamPolicy>>;
+export type TeamPolicyCommand = {
+    type: "set";
+    capability: PolicyKey;
+    setting: TeamPolicySetting;
+};
+export interface TeamPolicyCommandRequest {
+    command: TeamPolicyCommand;
 }
 export type TeamConsultCommand = {
     type: "join";
@@ -859,6 +942,50 @@ export type OpenMediaResult = {
     failure: ProtocolFailure;
 };
 /** The provider's complete state at one moment. It replaces what Omni holds; never a patch. */
+/**
+ * What the team may leave to the person: a capability by its own name -- `hold`, `mute` -- or a
+ * skill by its provider id. The same key as in `Task.capabilities`, because it is the same
+ * capability seen at another tier. Callback and new call are never the person's; they are the
+ * team's, on or off, within what the queue allows.
+ */
+export type PreferenceId = "hold" | "mute" | `skill:${string}`;
+/**
+ * Who stated a value as it stands: a tier -- `person` among them -- or `provisioning`, the
+ * protocol's own word for "no tier has said anything and the provider's default applies".
+ * Nothing is hidden for want of a row.
+ */
+export type SetBy = Tier | "provisioning";
+/** What every resolved value carries: who set it, and who locked it if anyone did. */
+export interface Resolved {
+    setBy: SetBy;
+    lockedBy?: Tier;
+    /** Given with `lockedBy`, where whoever locked it said why. */
+    reason?: string;
+}
+/**
+ * One choice the team may leave to the person, with where it stands and who set it. The provider
+ * keeps it: it is the person's across sessions, written through `setPreference`. Listed whether
+ * or not anyone has stated it, and even when a tier above has since locked it.
+ */
+export interface AgentPreference extends Resolved {
+    id: PreferenceId;
+    label: string;
+    enabled: boolean;
+}
+/** The person's act: set their own value, or give it up and inherit again. */
+export type SetPreferenceRequest = {
+    id: PreferenceId;
+    enabled: boolean;
+} | {
+    id: PreferenceId;
+    inherit: true;
+};
+export type PreferenceResult = {
+    status: "applied";
+} | {
+    status: "failed";
+    failure: ProtocolFailure;
+};
 export interface Snapshot<C extends Channel = Channel> {
     status: ConnectionStatus;
     sessionId: string;
@@ -976,8 +1103,12 @@ export interface Connection<C extends Channel = Channel> {
     executeTeamBreak?(request: TeamBreakCommandRequest): Promise<TeamCommandResult>;
     /** Required when the login declares `capabilities.team.consultControl`. */
     executeTeamConsult?(request: TeamConsultCommandRequest): Promise<TeamCommandResult>;
+    /** Required when the login declares `capabilities.team.policyControl`. */
+    executeTeamPolicy?(request: TeamPolicyCommandRequest): Promise<TeamCommandResult>;
     /** Required of every voice adapter: all voice audio lands in Omni. */
     openMedia?(request: OpenMediaRequest): Promise<OpenMediaResult>;
+    /** Required when the login declares `capabilities.preferences`: the person's own choice, kept by the provider and republished as `authenticated`. */
+    setPreference?(request: SetPreferenceRequest): Promise<PreferenceResult>;
 }
 export interface Adapter<C extends Channel = Channel> {
     manifest: Manifest<C>;

package/dist/index.js

@@ -50,6 +50,20 @@ export function isAllowedBrowserUrl(url) {
         return false;
     }
 }
+/**
+ * The tiers a typical organisation has: the ladder in force when a manifest declares no
+ * `orgTiers`. A manifest that declares any states its whole ladder outright.
+ */
+export const DEFAULT_TIERS = [
+    { id: "org", label: "Your organisation" },
+    { id: "site", label: "Your site" },
+    { id: "team", label: "Your team" },
+    { id: "person", label: "You" },
+];
+/** The ladder in force for a manifest: exactly what it declares, or the defaults when it declares none. */
+export function effectiveTiers(declared) {
+    return [...(declared ?? DEFAULT_TIERS)];
+}
 // ---------------------------------------------------------------------------
 // Task commands.
 // ---------------------------------------------------------------------------

package/dist/testing.d.ts

@@ -7,7 +7,7 @@ export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation }
  * rules -- each optional part of a task, each optional part of the break state and roster, each
  * declared contribution, and each event type.
  */
-declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.handlingHistory", "task.consultation", "task.lead", "task.assisting", "task.dispositions", "task.destinations", "task.custom", "break.reasons", "break.imposed", "team.members", "team.requests", "contacts", "scheduledActivities"];
+declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.handlingHistory", "task.consultation", "task.lead", "task.assisting", "task.dispositions", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.imposed", "team.members", "team.requests", "contacts", "scheduledActivities", "team.policies"];
 export type ContractSubject = (typeof STATE_SUBJECTS)[number] | `event.${ProviderEvent["type"]}`;
 export interface AdapterContractResult {
     events: ProviderEventEnvelope[];

package/dist/testing.js

@@ -1,4 +1,4 @@
-import { browserSessionKey, sameCapabilities, } from "./index.js";
+import { browserSessionKey, effectiveTiers, sameCapabilities, } from "./index.js";
 import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateHostReport, validateManifest, validateResult, validateSnapshot, } from "./validation.js";
 export { ProtocolConformanceError, assertNoViolations } from "./validation.js";
 /**
@@ -18,12 +18,14 @@ const STATE_SUBJECTS = [
     "task.dispositions",
     "task.destinations",
     "task.custom",
+    "task.locked",
     "break.reasons",
     "break.imposed",
     "team.members",
     "team.requests",
     "contacts",
     "scheduledActivities",
+    "team.policies",
 ];
 // Pinned to the event union the way validation pins its closed sets: a type added to
 // `ProviderEvent` without a row here, or a row it lacks, is a compile error.
@@ -66,6 +68,8 @@ function observeTask(value, seen) {
     }
     if (some(capabilities.custom))
         seen.add("task.custom");
+    if (Object.values(capabilities).some(declared => isRecord(declared) && declared.lockedBy !== undefined))
+        seen.add("task.locked");
 }
 function observeBreak(value, seen) {
     if (!isRecord(value))
@@ -82,6 +86,8 @@ function observeTeam(value, seen) {
         seen.add("team.members");
     if (some(value.requests))
         seen.add("team.requests");
+    if (isRecord(value.policies) && Object.keys(value.policies).length > 0)
+        seen.add("team.policies");
 }
 function observeSnapshot(value, seen) {
     if (!isRecord(value))
@@ -163,7 +169,8 @@ export async function exerciseAdapter(adapter, context, options = {}) {
     let disconnectWasClean = false;
     try {
         authenticationState = await authentication.state();
-        violations.push(...validateAuthenticationState(authenticationState));
+        const tiers = effectiveTiers(adapter.manifest.orgTiers).map(tier => tier.id);
+        violations.push(...validateAuthenticationState(authenticationState, "authentication", { tiers }));
         if (authenticationState.status !== "authenticated") {
             throw new Error(`Adapter contract exercise requires authenticated test state, received ${authenticationState.status}`);
         }
@@ -212,9 +219,13 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                 requireMethod(on, "executeTeamBreak", "the login declares capabilities.team.breakControl");
             if (capabilities.team?.consultControl === true)
                 requireMethod(on, "executeTeamConsult", "the login declares capabilities.team.consultControl");
+            if (capabilities.team?.policyControl === true)
+                requireMethod(on, "executeTeamPolicy", "the login declares capabilities.team.policyControl");
+            if (some(capabilities.preferences))
+                requireMethod(on, "setPreference", "the login declares capabilities.preferences");
         };
         unsubscribeAuthentication = authentication.subscribe(state => {
-            const own = validateAuthenticationState(state);
+            const own = validateAuthenticationState(state, "authentication", { tiers });
             violations.push(...own);
             if (own.length > 0)
                 return;
@@ -723,7 +734,7 @@ 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 }) {
+export function stillHost(report = { online: true, browsers: { urlVisibility: "hidden" } }) {
     return { report: () => report, subscribe: () => () => undefined };
 }
 const usableLogin = (status) => status === "authenticated" || status === "refreshing";

package/dist/validation.d.ts

@@ -13,6 +13,8 @@ export declare function validateManifest(manifest: unknown, path?: string): Prot
 export interface TaskValidationContext {
     /** The provider's channel, from its manifest. A task must agree with it. */
     channel: string;
+    /** The tier ids in force, from the manifest. The defaults when absent. */
+    tiers?: readonly string[];
 }
 export declare function validateTask(task: unknown, context: TaskValidationContext, path?: string): ProtocolViolation[];
 /**
@@ -30,6 +32,8 @@ export interface ReaderContext {
      * snapshot carries a roster, nobody else's does, and `requests` need `team.consultControl`.
      */
     capabilities?: SessionCapabilities;
+    /** The tier ids in force. Filled from the manifest by `validateSnapshot` and `validateEventEnvelope`; the defaults otherwise. */
+    tiers?: readonly string[];
     /** The login's `sessionId`. A snapshot or event naming another belongs to a login that is gone. */
     sessionId?: string;
     /** `ConnectContext.autoAcceptTasks` as sent, absent meaning `true`: whether `task-offered` carries an `acceptanceMode`. */
@@ -45,7 +49,7 @@ export declare function validateEventEnvelope(envelope: unknown, manifest: unkno
  */
 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";
+export type ResultMethod = "execute" | "dial" | "setCapacity" | "requestBreak" | "commitBreak" | "cancelBreak" | "endBreak" | "executeTeamBreak" | "executeTeamConsult" | "openMedia" | "setPreference" | "executeTeamPolicy";
 /**
  * Validates what a connection method answered. A result is untrusted for the same reason a
  * snapshot is: it comes from an adapter that may be compiled against another version, and Omni
@@ -53,4 +57,9 @@ export type ResultMethod = "execute" | "dial" | "setCapacity" | "requestBreak" |
  * failure, a success carrying one, or an `omni.` code the contract lacks are each refused.
  */
 export declare function validateResult(result: unknown, method: ResultMethod, path?: string): ProtocolViolation[];
-export declare function validateAuthenticationState(state: unknown, path?: string): ProtocolViolation[];
+/** What a login is validated against beyond its own shape. */
+export interface LoginValidationContext {
+    /** The tier ids in force, from the manifest. The defaults when absent. */
+    tiers?: readonly string[];
+}
+export declare function validateAuthenticationState(state: unknown, path?: string, context?: LoginValidationContext): ProtocolViolation[];

package/dist/validation.js

@@ -9,7 +9,7 @@
 // Each list is pinned to its type both ways -- a member the type lacks, or a member the list
 // lacks, fails to compile -- so what the validators accept cannot drift from what the
 // declarations say.
-import { ALLOWED_BROWSER_URL_SCHEMES, BREAK_KINDS, BROWSER_ISOLATION_SCHEMES, IDLE_CAPABILITIES, OMNI_FAILURE_CODES, OMNI_SUPPORTED_PROTOCOL_VERSIONS, negotiateProtocolVersion, } from "./index.js";
+import { ALLOWED_BROWSER_URL_SCHEMES, BREAK_KINDS, BROWSER_ISOLATION_SCHEMES, IDLE_CAPABILITIES, OMNI_FAILURE_CODES, OMNI_SUPPORTED_PROTOCOL_VERSIONS, negotiateProtocolVersion, DEFAULT_TIERS, effectiveTiers, } from "./index.js";
 export class ProtocolConformanceError extends Error {
     violations;
     constructor(violations, summary = "Adapter violates the Omni protocol") {
@@ -69,14 +69,14 @@ const DIAL_DESTINATION_POLICIES = membersOf({ "contacts-only": true, "any-number
 const SNAPSHOT_REASONS = membersOf({
     reconnected: true, "provider-requested": true,
 });
-const SESSION_CAPABILITIES = membersOf({ breaks: true, team: true });
+const SESSION_CAPABILITIES = membersOf({ breaks: true, team: true, preferences: true });
 const MEMBER_BREAKS = membersOf({
     "awaiting-decision": true, granted: true, "starting-after-task": true,
 });
 const OFFERABLE_PHASES = membersOf({
     pending: true, confirmed: true, preparing: true,
 });
-const TEAM_CAPABILITIES = membersOf({ breakControl: true, consultControl: true });
+const TEAM_CAPABILITIES = membersOf({ breakControl: true, consultControl: true, policyControl: true });
 const COMPLETED_BY = membersOf({ agent: true, provider: true });
 const EXPIRABLE_PHASES = membersOf({
     pending: true, confirmed: true, preparing: true,
@@ -164,15 +164,19 @@ export function validateContact(contact, path = "contact") {
     validateContactInto(contact, path, into);
     return into.violations;
 }
-function validateContactInto(contact, path, into) {
+function validateContactInto(contact, path, into, tiers) {
     if (!isPlainObject(contact)) {
         into.add("contact.shape", path, "a contact must be an object");
         return;
     }
     for (const field of ["name", "number", "email"]) {
-        if (contact[field] !== undefined) {
-            into.filled(contact[field], `contact.${field}`, `${path}.${field}`, `${field} must not be empty when present`);
+        if (contact[field] === undefined)
+            continue;
+        if ((field === "number" || field === "email") && isLocked(contact[field])) {
+            validateLockedInto(contact[field], `contact.${field}.locked`, `${path}.${field}`, tiers, into);
+            continue;
         }
+        into.filled(contact[field], `contact.${field}`, `${path}.${field}`, `${field} must not be empty when present`);
     }
     validateAttributes(contact.attributes, `${path}.attributes`, into);
 }
@@ -307,6 +311,37 @@ export function validateManifest(manifest, path = "manifest") {
             }
         }
     }
+    if (manifest.orgTiers !== undefined) {
+        if (!Array.isArray(manifest.orgTiers)) {
+            into.add("manifest.orgTiers.shape", `${path}.orgTiers`, "orgTiers must be an array when present");
+        }
+        else {
+            const ids = new Set();
+            let wellFormed = true;
+            manifest.orgTiers.forEach((tier, index) => {
+                const at = `${path}.orgTiers[${index}]`;
+                if (!isPlainObject(tier)) {
+                    into.add("manifest.orgTier.shape", at, "each tier must be an object with an id and a label");
+                    wellFormed = false;
+                    return;
+                }
+                if (into.filled(tier.id, "manifest.orgTier.id", `${at}.id`, "a tier needs an id")) {
+                    if (ids.has(tier.id)) {
+                        into.add("manifest.orgTier.unique", `${at}.id`, `duplicate tier: ${tier.id}`);
+                        wellFormed = false;
+                    }
+                    ids.add(tier.id);
+                }
+                else
+                    wellFormed = false;
+                if (!into.filled(tier.label, "manifest.orgTier.label", `${at}.label`, "a tier needs the label a desk shows for it"))
+                    wellFormed = false;
+            });
+            if (wellFormed && !ids.has("person")) {
+                into.add("manifest.orgTiers.person", `${path}.orgTiers`, "a declared ladder states the whole ladder and must include person, the subject of every resolution");
+            }
+        }
+    }
     if (manifest.taskTypePresentation !== undefined) {
         if (!isPlainObject(manifest.taskTypePresentation)) {
             into.add("manifest.taskTypePresentation.shape", `${path}.taskTypePresentation`, "taskTypePresentation must be an object when present");
@@ -427,8 +462,73 @@ function validateCustomCapabilities(value, path, into) {
         into.oneOf(custom.ui.kind, CUSTOM_UI_KINDS, "task.custom.ui.kind", `${at}.ui.kind`);
         into.filled(custom.ui.label, "task.custom.ui.label", `${at}.ui.label`, "a custom control needs a label");
         into.oneOf(custom.ui.placement, CUSTOM_UI_PLACEMENTS, "task.custom.ui.placement", `${at}.ui.placement`);
+        if (custom.ui.render !== undefined)
+            into.oneOf(custom.ui.render, CUSTOM_RENDERS, "task.custom.ui.render", `${at}.ui.render`);
+        if (custom.prompt !== undefined) {
+            if (!isPlainObject(custom.prompt) || !Array.isArray(custom.prompt.fields)) {
+                into.add("task.custom.prompt.shape", `${at}.prompt`, "a prompt is an object with the fields the agent fills");
+            }
+            else {
+                into.require(custom.prompt.fields.length > 0, "task.custom.prompt.fields", `${at}.prompt.fields`, "a prompt with no fields asks for nothing; omit it");
+                custom.prompt.fields.forEach((field, fieldIndex) => {
+                    const where = `${at}.prompt.fields[${fieldIndex}]`;
+                    if (!isPlainObject(field)) {
+                        into.add("task.custom.prompt.field.shape", where, "each prompt field must be an object");
+                        return;
+                    }
+                    into.filled(field.name, "task.custom.prompt.field.name", `${where}.name`, "a prompt field needs a name");
+                    into.filled(field.label, "task.custom.prompt.field.label", `${where}.label`, "a prompt field needs a label");
+                    into.oneOf(field.type, CREDENTIAL_FIELD_TYPES, "task.custom.prompt.field.type", `${where}.type`);
+                });
+            }
+        }
     });
 }
+const DEFAULT_TIER_IDS = DEFAULT_TIERS.map(tier => tier.id);
+const POLICY_SETTINGS = membersOf({ on: true, off: true, agent: 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 isLocked = (value) => isPlainObject(value) && value.lockedBy !== undefined;
+/** The tier ids in force: the manifest's, or the defaults when the caller holds no manifest. */
+const tierIds = (tiers) => tiers ?? DEFAULT_TIER_IDS;
+/** `lockedBy`: a declared tier other than `person`, who never locks their own value. */
+function validateLockedByInto(value, rule, path, tiers, into) {
+    if (!into.filled(value, rule, path, "lockedBy names the tier that locked it"))
+        return;
+    into.require(value !== "person", `${rule}.person`, path, "a person never locks their own value");
+    into.require(tierIds(tiers).includes(value), `${rule}.unknown`, path, `${String(value)} is not a tier this manifest declares: in force are ${tierIds(tiers).join(", ")}`);
+}
+/** `{ lockedBy, reason? }` standing in for a value: who locked it, and a reason if given. */
+function validateLockedInto(value, rule, path, tiers, into) {
+    validateLockedByInto(value.lockedBy, `${rule}.lockedBy`, `${path}.lockedBy`, tiers, into);
+    if (value.reason !== undefined)
+        into.filled(value.reason, `${rule}.reason`, `${path}.reason`, "a reason must not be empty when present");
+}
+/** What every resolved value carries: who set it, and who locked it if anyone. */
+function validateResolvedInto(value, rule, path, tiers, into) {
+    if (into.filled(value.setBy, `${rule}.setBy`, `${path}.setBy`, "setBy names who stated the value: a tier, or provisioning")) {
+        into.require(value.setBy === "provisioning" || tierIds(tiers).includes(value.setBy), `${rule}.setBy.unknown`, `${path}.setBy`, `${String(value.setBy)} is neither provisioning nor a tier this manifest declares`);
+    }
+    if (value.lockedBy !== undefined)
+        validateLockedByInto(value.lockedBy, `${rule}.lockedBy`, `${path}.lockedBy`, tiers, into);
+    if (value.reason !== undefined) {
+        into.filled(value.reason, `${rule}.reason`, `${path}.reason`, "a reason must not be empty when present");
+        into.require(value.lockedBy !== undefined, `${rule}.reason.unexpected`, `${path}.reason`, "a reason goes with lockedBy: it says why it was locked");
+    }
+}
+/** The tier ids a manifest puts in force, for validators that receive one. */
+function manifestTiers(manifest) {
+    if (!isPlainObject(manifest))
+        return undefined;
+    const declared = Array.isArray(manifest.orgTiers)
+        ? manifest.orgTiers.filter((tier) => isPlainObject(tier) && typeof tier.id === "string")
+        : undefined;
+    return effectiveTiers(declared).map(tier => tier.id);
+}
+const CUSTOM_RENDERS = membersOf({ inline: true, page: true });
+const CREDENTIAL_FIELD_TYPES = membersOf({ text: true, password: true });
 function validateBrowsers(value, path, into) {
     if (!Array.isArray(value)) {
         into.add("task.browsers.shape", path, "browsers must be an array");
@@ -633,7 +733,7 @@ function validateTaskInto(task, context, path, into) {
         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);
+        validateContactInto(task.contact, `${path}.contact`, into, context.tiers);
     validateBrowsers(task.browsers, `${path}.browsers`, into);
     validateTaskAttributes(task.attributes, `${path}.attributes`, into);
     validateHandlingHistory(task.handlingHistory, `${path}.handlingHistory`, into);
@@ -660,6 +760,14 @@ function validateTaskInto(task, context, path, into) {
             continue;
         if (!into.require(allowed.includes(name), "task.capability.channel", `${path}.capabilities.${name}`, `a ${context.channel} task may not declare ${name}`))
             continue;
+        // A control the queue could allow may stand locked in its place, saying whose. What the
+        // queue provides -- browsers, dispositions, custom controls -- is content, not a control.
+        if (isLocked(declared)) {
+            if (into.require(name !== "browsers" && name !== "dispositions" && name !== "custom", "task.capability.locked.unexpected", `${path}.capabilities.${name}`, `${name} is what the queue provides, not a control anyone locks`)) {
+                validateLockedInto(declared, "task.capability.locked", `${path}.capabilities.${name}`, context.tiers, into);
+            }
+            continue;
+        }
         switch (name) {
             case "dispositions":
                 validateDispositions(declared, `${path}.capabilities.dispositions`, into);
@@ -780,6 +888,18 @@ function validateTeamRosterInto(roster, path, context, into) {
     if (context.capabilities !== undefined && context.capabilities.team === undefined) {
         into.add("team.unentitled", path, "a roster published to a login that does not declare capabilities.team: the login is the permission");
     }
+    // The team's policies travel with the roster exactly when the login may set them.
+    if (context.capabilities !== undefined) {
+        const may = context.capabilities.team?.policyControl === true;
+        if (may && roster.policies === undefined) {
+            into.add("team.policies.required", `${path}.policies`, "the login declares team.policyControl, so the roster carries the team's policies");
+        }
+        if (!may && roster.policies !== undefined) {
+            into.add("team.policies.capability", `${path}.policies`, "policies require team.policyControl on the login: a lead who may not set them has nothing to see");
+        }
+    }
+    if (roster.policies !== undefined)
+        validateTeamPoliciesInto(roster.policies, `${path}.policies`, into, context.tiers);
     if (roster.requests === undefined) {
         // `[]` says nobody is asking; omission says the lead may not be asked. A login that may be
         // asked therefore always carries the list.
@@ -855,6 +975,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
         return into.violations;
     }
     const channel = isPlainObject(manifest) && typeof manifest.channel === "string" ? manifest.channel : "voice";
+    const tiers = context.tiers ?? manifestTiers(manifest);
     into.oneOf(snapshot.status, CONNECTION_STATUSES, "snapshot.status", `${path}.status`);
     if (into.filled(snapshot.sessionId, "snapshot.sessionId", `${path}.sessionId`, "a snapshot needs the session id it belongs to")
         && context.sessionId !== undefined) {
@@ -868,7 +989,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
         const seen = new Set();
         let assisting;
         snapshot.tasks.forEach((task, index) => {
-            validateTaskInto(task, { channel }, `${path}.tasks[${index}]`, into);
+            validateTaskInto(task, { channel, tiers }, `${path}.tasks[${index}]`, into);
             // A lead assists one call at a time.
             if (isPlainObject(task) && task.assisting !== undefined) {
                 if (assisting !== undefined)
@@ -933,7 +1054,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
         into.add("team.required", `${path}.team`, "the login declares capabilities.team, so every snapshot carries a roster: [] when nobody is in it");
     }
     if (snapshot.team !== undefined)
-        validateTeamRosterInto(snapshot.team, `${path}.team`, context, into);
+        validateTeamRosterInto(snapshot.team, `${path}.team`, { ...context, tiers }, into);
     return into.violations;
 }
 // ---------------------------------------------------------------------------
@@ -1017,6 +1138,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
         return into.violations;
     }
     const channel = isPlainObject(manifest) && typeof manifest.channel === "string" ? manifest.channel : "voice";
+    const tiers = context.tiers ?? manifestTiers(manifest);
     into.filled(envelope.id, "event.id", `${path}.id`, "an event needs an id");
     if (into.filled(envelope.sessionId, "event.sessionId", `${path}.sessionId`, "an event needs the session id it belongs to")
         && context.sessionId !== undefined) {
@@ -1033,7 +1155,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
     switch (event.type) {
         case "snapshot":
             into.oneOf(event.reason, SNAPSHOT_REASONS, "event.snapshot.reason", `${at}.reason`);
-            into.violations.push(...validateSnapshot(event.snapshot, manifest, `${at}.snapshot`, context));
+            into.violations.push(...validateSnapshot(event.snapshot, manifest, `${at}.snapshot`, { ...context, tiers }));
             break;
         case "provider-status":
             into.oneOf(event.status, CONNECTION_STATUSES, "event.providerStatus.status", `${at}.status`);
@@ -1045,7 +1167,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             validateBreakState(event.break, `${at}.break`, into);
             break;
         case "task-offered":
-            validateTaskInto(event.task, { channel }, `${at}.task`, into);
+            validateTaskInto(event.task, { channel, tiers }, `${at}.task`, into);
             // An offer introduces work that is not yet under way; work in progress arrives only on a snapshot.
             if (isPlainObject(event.task) && typeof event.task.phase === "string") {
                 into.require(OFFERABLE_PHASES.includes(event.task.phase), "event.taskOffered.phase", `${at}.task.phase`, `task-offered introduces a task as ${OFFERABLE_PHASES.join(", ")}, never as ${event.task.phase}`);
@@ -1066,7 +1188,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             }
             break;
         case "task-updated":
-            validateTaskInto(event.task, { channel }, `${at}.task`, into);
+            validateTaskInto(event.task, { channel, tiers }, `${at}.task`, into);
             break;
         case "task-media-ended":
             into.require(isTaskId(event.taskId), "event.taskMediaEnded.taskId", `${at}.taskId`, "a task id is required");
@@ -1088,7 +1210,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             validateProviderSummary(event.summary, `${at}.summary`, into);
             break;
         case "team-updated":
-            validateTeamRosterInto(event.team, `${at}.team`, context, into);
+            validateTeamRosterInto(event.team, `${at}.team`, { ...context, tiers }, into);
             break;
         case "contacts-updated":
             into.require(idle.contacts === true, "event.contacts.capability", `${at}.contacts`, "contacts-updated requires the contacts idle capability");
@@ -1125,6 +1247,53 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
 // Results. A result crosses the same boundary a snapshot does, from an adapter that may be
 // compiled against another version, and Omni shows the agent what it says.
 // ---------------------------------------------------------------------------
+const PREFERENCE_ID = /^(hold|mute|skill:.+)$/;
+/** The choices left to the person, each with where it stands. */
+function validatePreferencesInto(value, path, into, tiers) {
+    if (!Array.isArray(value)) {
+        into.add("preferences.shape", path, "preferences must be an array");
+        return;
+    }
+    const seen = new Set();
+    value.forEach((preference, index) => {
+        const at = `${path}[${index}]`;
+        if (!isPlainObject(preference)) {
+            into.add("preference.shape", at, "each preference must be an object");
+            return;
+        }
+        if (into.require(typeof preference.id === "string" && PREFERENCE_ID.test(preference.id), "preference.id", `${at}.id`, "a preference is hold, mute, or skill:<id>: nothing else is the person's to set")) {
+            if (seen.has(preference.id))
+                into.add("preference.unique", `${at}.id`, `duplicate preference: ${preference.id}`);
+            seen.add(preference.id);
+        }
+        into.filled(preference.label, "preference.label", `${at}.label`, "a preference needs a label");
+        into.require(typeof preference.enabled === "boolean", "preference.enabled", `${at}.enabled`, "a preference says where it stands");
+        validateResolvedInto(preference, "preference", at, tiers, into);
+    });
+}
+/** The team's policy per capability as the lead sees it: the setting, who set it, who locked it. */
+function validateTeamPoliciesInto(value, path, into, tiers) {
+    if (!isPlainObject(value)) {
+        into.add("team.policies.shape", path, "policies must be an object keyed by capability");
+        return;
+    }
+    for (const [key, policy] of Object.entries(value)) {
+        if (policy === undefined)
+            continue;
+        const at = `${path}.${key}`;
+        if (!into.require(POLICY_KEYS.has(key) || /^skill:.+$/.test(key), "team.policy.key", at, `${key} is not a control a policy can name: a task control, dial, or skill:<id>`))
+            continue;
+        if (!isPlainObject(policy)) {
+            into.add("team.policy.shape", at, "each policy carries its setting, who set it, and who locked it if anyone");
+            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`);
+        }
+        validateResolvedInto(policy, "team.policy", at, tiers, into);
+        into.require(policy.setBy !== "person", "team.policy.setBy", `${at}.setBy`, "a team policy is not set by a person");
+    }
+}
 /** A `ProtocolFailure`, wherever one appears: on a result, or on a task's failed outcome. */
 function validateFailureInto(value, path, into) {
     if (!isPlainObject(value)) {
@@ -1144,6 +1313,7 @@ function validateFailureInto(value, path, into) {
         into.require(typeof value.retryAfterMs === "number" && Number.isFinite(value.retryAfterMs) && value.retryAfterMs >= 0, "failure.retryAfterMs", `${path}.retryAfterMs`, "retryAfterMs must be a non-negative number when present");
     }
 }
+const URL_VISIBILITIES = membersOf({ full: true, domain: true, hidden: true });
 const HOST_AUDIO_REASONS = membersOf({ "no-device": true, denied: true, "not-asked": true, "in-use": true, lost: true });
 const HOST_OUTPUT_REASONS = membersOf({ "no-device": true, lost: true });
 function validateUnavailable(value, rule, path, into) {
@@ -1166,6 +1336,12 @@ export function validateHostReport(report, path = "host") {
         return into.violations;
     }
     into.require(typeof report.online === "boolean", "host.online", `${path}.online`, "a host report says whether it has a network");
+    if (!isPlainObject(report.browsers)) {
+        into.add("host.browsers.shape", `${path}.browsers`, "a host report says what its chrome shows of a task browser's URL");
+    }
+    else {
+        into.oneOf(report.browsers.urlVisibility, URL_VISIBILITIES, "host.browsers.urlVisibility", `${path}.browsers.urlVisibility`);
+    }
     if (report.audio === undefined)
         return into.violations;
     if (!isPlainObject(report.audio)) {
@@ -1223,6 +1399,8 @@ const RESULT_STATUSES = {
     executeTeamBreak: { success: "applied", failure: "failed" },
     executeTeamConsult: { success: "applied", failure: "failed" },
     openMedia: { success: "opened", failure: "unavailable" },
+    setPreference: { success: "applied", failure: "failed" },
+    executeTeamPolicy: { success: "applied", failure: "failed" },
 };
 /**
  * Validates what a connection method answered. A result is untrusted for the same reason a
@@ -1267,7 +1445,7 @@ function validateUser(value, rule, path, into) {
     into.require(isUserId(value.id), `${rule}.id`, `${path}.id`, "an identity needs a provider-issued user id");
     into.filled(value.displayName, `${rule}.displayName`, `${path}.displayName`, "an identity needs a display name");
 }
-function validateSessionCapabilitiesInto(value, path, into) {
+function validateSessionCapabilitiesInto(value, path, into, tiers) {
     if (!isPlainObject(value)) {
         into.add("authentication.capabilities.shape", path, "a usable login declares its capabilities: an object, {} when it has none");
         return;
@@ -1277,6 +1455,13 @@ function validateSessionCapabilitiesInto(value, path, into) {
             continue;
         if (!into.require(SESSION_CAPABILITIES.includes(name), "authentication.capability.unknown", `${path}.${name}`, `unsupported session capability: ${name}`))
             continue;
+        if (name === "preferences") {
+            if (Array.isArray(declared) && declared.length === 0) {
+                into.add("authentication.capability.preferences.empty", `${path}.preferences`, "a login with nothing left to the person omits preferences rather than declaring an empty list");
+            }
+            validatePreferencesInto(declared, `${path}.preferences`, into, tiers);
+            continue;
+        }
         if (name === "team") {
             if (!isPlainObject(declared)) {
                 into.add("authentication.capability.team.shape", `${path}.team`, "team names what the lead may do: an object, {} for a lead with no controls");
@@ -1294,7 +1479,7 @@ function validateSessionCapabilitiesInto(value, path, into) {
         into.require(declared === true, "authentication.capability.value", `${path}.${name}`, `${name} is declared by presence: send true or omit it`);
     }
 }
-export function validateAuthenticationState(state, path = "authentication") {
+export function validateAuthenticationState(state, path = "authentication", context = {}) {
     const into = new Collector();
     if (!isPlainObject(state)) {
         into.add("authentication.shape", path, "an authentication state must be an object");
@@ -1307,7 +1492,7 @@ export function validateAuthenticationState(state, path = "authentication") {
     // may carry an identity. Anything else is a state claiming knowledge it does not have.
     if (state.status === "authenticated" || state.status === "refreshing") {
         validateUser(state.identity, "authentication.identity", `${path}.identity`, into);
-        validateSessionCapabilitiesInto(state.capabilities, `${path}.capabilities`, into);
+        validateSessionCapabilitiesInto(state.capabilities, `${path}.capabilities`, into, context.tiers);
     }
     else if (state.status === "expired") {
         if (state.identity !== undefined)

package/guide.md

@@ -176,6 +176,7 @@ type Manifest<C extends Channel = Channel> = {
   idleCapabilities?: IdleCapabilities<C>;
   phaseLabels?: TaskPhaseLabels;
   taskTypePresentation?: Record<string, TaskTypePresentation>;
+  orgTiers?: TierDeclaration[];
 };
 ```
 
@@ -223,10 +224,12 @@ type AuthenticationContext = {
 type TeamCapabilities = {
   breakControl?: true;
   consultControl?: true;
+  policyControl?: true;
 };
 
 type SessionCapabilities = {
   breaks?: true;
+  preferences?: AgentPreference[];
   team?: TeamCapabilities;
 };
 
@@ -256,7 +259,10 @@ type HostAudioOutput =
   | { status: "ready" }
   | { status: "unavailable"; reason: HostOutputUnavailableReason; failure: ProtocolFailure };
 
+type UrlVisibility = "full" | "domain" | "hidden";
+
 type HostReport = {
+  browsers: { urlVisibility: UrlVisibility };
   online: boolean;
   audio?: {
     input: HostAudioInput;
@@ -328,6 +334,30 @@ type AuthenticationSession = {
 ### Provider state
 
 ```ts
+type PreferenceId = "hold" | "mute" | `skill:${string}`;
+
+type SetBy = Tier | "provisioning";
+
+type Resolved = {
+  setBy: SetBy;
+  lockedBy?: Tier;
+  reason?: string;
+};
+
+type AgentPreference = Resolved & {
+  id: PreferenceId;
+  label: string;
+  enabled: boolean;
+};
+
+type SetPreferenceRequest =
+  | { id: PreferenceId; enabled: boolean }
+  | { id: PreferenceId; inherit: true };
+
+type PreferenceResult =
+  | { status: "applied" }
+  | { status: "failed"; failure: ProtocolFailure };
+
 type Snapshot = {
   status: ConnectionStatus;
   sessionId: string;
@@ -352,8 +382,8 @@ type CapacityResult =
 ```ts
 type Contact = {
   name?: string;
-  number?: string;
-  email?: string;
+  number?: Lockable<string>;
+  email?: Lockable<string>;
   attributes?: Attribute[];
 };
 
@@ -404,7 +434,9 @@ type CustomCapability = {
     kind: "button" | "toggle" | "menu-item";
     label: string;
     placement: "primary" | "secondary" | "overflow";
+    render?: "inline" | "page";
   };
+  prompt?: { fields: CredentialField[] };
 };
 
 type SharedTaskCapabilities = {
@@ -416,20 +448,20 @@ type SharedTaskCapabilities = {
 type TaskCapabilities<C extends Channel = Channel> =
   C extends "voice"
     ? SharedTaskCapabilities & {
-        decline?: true;
-        mute?: true;
-        hold?: true;
-        agentDisconnect?: true;
-        callback?: true;
-        blindTransfer?: true | DestinationDirectory;
-        consultTransfer?: true | DestinationDirectory;
-        consultLead?: true;
-        conference?: true | DestinationDirectory;
-        recording?: true;
+        decline?: Lockable<true>;
+        mute?: Lockable<true>;
+        hold?: Lockable<true>;
+        agentDisconnect?: Lockable<true>;
+        callback?: Lockable<true>;
+        blindTransfer?: Lockable<true | DestinationDirectory>;
+        consultTransfer?: Lockable<true | DestinationDirectory>;
+        consultLead?: Lockable<true>;
+        conference?: Lockable<true | DestinationDirectory>;
+        recording?: Lockable<true>;
       }
     : C extends "chat"
-      ? SharedTaskCapabilities & { reject?: true; hold?: true }
-      : SharedTaskCapabilities & { reject?: true };
+      ? SharedTaskCapabilities & { reject?: Lockable<true>; hold?: Lockable<true> }
+      : SharedTaskCapabilities & { reject?: Lockable<true> };
 ```
 
 The channel arms are why `Task<"email">` rejects `hold` at compile time rather than at runtime.
@@ -536,6 +568,20 @@ type TaskAssisting = {
   since: IsoTimestamp;
 };
 
+type Tier = string;
+
+type TierDeclaration = {
+  id: Tier;
+  label: string;
+};
+
+type Locked = {
+  lockedBy: Tier;
+  reason?: string;
+};
+
+type Lockable<T> = T | Locked;
+
 type Task<C extends Channel = Channel> = {
   id: TaskId;
   title: string;
@@ -645,7 +691,78 @@ type TaskCommandResult =
   | { status: "failed"; failure: ProtocolFailure };
 ```
 
-### Breaks
+### Who decides what an agent may do
+
+An agent desk has two managers, not one. **The queue** — a process, a work type — is owned by a
+process manager and **allows** a set of capabilities: hold, mute, callback, new call, conference,
+whether the number is visible, the actions it offers, the skills it needs. **The people** are
+managed through the organisation's structure — a team, a location, the organisation itself, in
+whatever combination the structure defines for a person — and **decide** per capability within
+what the queue allows: on for everyone, off for everyone, or left to the person. What you do to
+your team is a **policy**; what you do to yourself is a **preference**. A person belongs to one
+team and many queues, so a policy applies across every queue the person works.
+
+**The provider resolves; the protocol carries the result and who decided.** The structure's tiers
+are the provider's ladder: each tier states only what it sets, an enforcing policy at a tier above
+the person settles the value for everyone below it, and where nothing enforces the most specific
+tier that says anything wins. The protocol names a tier by the id the manifest declares for it and
+never describes the chain between them: which tiers a person passes through is the structure's to
+know. A typical organisation has four, and they are the defaults — `DEFAULT_TIERS`: `org`, `site`,
+`team`, `person`, each with the label a desk shows. A structure that differs states its whole
+ladder in `Manifest.orgTiers`, `person` included: what the list carries is in force, and what it
+leaves out does not exist — a structure with no site tier declares `org`, `team`, `person`, and
+`site` is refused on its wire. A declared tier is one the provider's own store actually resolves
+at: a label with no policy behind it decides nothing. A manifest that declares none has exactly
+the four. `lockedBy` is any tier in force except `person`, who never locks their own value;
+`setBy` is any tier in force, or `provisioning`, the protocol's word for "no tier has said
+anything and the provider's own configuration supplied the value" — the provider speaking, never
+Omni's provisioning file, which does not reach the wire. A host renders "who decided" from the
+declared labels and needs no others, and validates every republished `authenticated` state
+against them, not only the sign-in. What the wire carries is the resolution:
+
+- **`lockedBy`** — a tier above the person made this value theirs to keep. A person never locks
+  their own value, and the queue is not a tier: what the queue does not allow at all is absent.
+- **`setBy`** — who stated the value as it stands: a tier, the `person` themself, or
+  `provisioning` where no tier has said anything. Provenance, not a lock: a value that came from a
+  broad tier as a default is still the person's to change.
+
+**On a task, a control the queue could allow may stand locked in its place.** `Task.capabilities`
+is the effective set. What the queue does not allow is absent and nothing is shown. What the queue
+allows and a tier above the person locked is present as `{ lockedBy, reason? }` where the control's
+value would be — `mute: { lockedBy: "team", reason: "Nobody on this team mutes" }` — and Omni
+renders that control disabled, saying who decided, so an agent who cannot press Mute knows whether
+to ask their lead or their site. `lockedBy` is the discriminant: a value that carries it is the
+lock, so nothing that can be locked — a directory, a number — may carry that key itself. A
+contact's number and email are the same, since each identifies a person: where the queue says
+the agent may not see it, the provider sends `{ lockedBy }` in its place — the last digits or
+nothing — and a CRM link carries a token, never the value with a flag the desk is asked to honour.
+A name is not locked. What the queue provides rather than permits — browsers, dispositions, custom
+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
+allows. The roster carries `policies` for such a login: every policy as it stands, who set it, and
+`lockedBy` where a tier 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`.
+
+**What the team left to the person is the person's, and the provider keeps it.** The login's
+`capabilities.preferences` lists every preference the person may hold — `hold`, `mute`, a skill —
+with where it stands and who set it: `setBy: "team"` while they inherit the team's default,
+`"person"` once they have set their own, `"provisioning"` where no tier has said anything. Nothing
+is hidden for want of a row, and a preference a tier above has since locked is listed with
+`lockedBy`. `setPreference` is the person's act — `{ id, enabled }` to set their own, `{ id,
+inherit: true }` to give it up and inherit again — answered `applied` and republished as a new
+`authenticated` state when something changed, a state and not a flicker, as every republish of
+`authenticated` is; and it is durable: the person's across sessions. A lead may also set a
+person's preference from their own screen, which arrives the same way. A preference is keyed by
+the capability's own name because it is the same capability at another tier: effective in
+`Task.capabilities`, set for the team in `policies`, left to the person in `preferences`. The
+command `mute` acts on one call; the preference `mute` says whether the person wants the control
+at all, and a host renders it in its settings, never as the button on a call.
+
+## Breaks
 
 ```ts
 type BreakApproval =
@@ -723,6 +840,28 @@ type LeadRequest = {
 type TeamRoster = {
   members: TeamMember[];
   requests?: LeadRequest[];
+  policies?: TeamPolicies;
+};
+
+type PolicyKey =
+  | Exclude<keyof TaskCapabilities<"voice">, keyof SharedTaskCapabilities>
+  | Exclude<keyof TaskCapabilities<"chat">, keyof SharedTaskCapabilities>
+  | Exclude<keyof TaskCapabilities<"email">, keyof SharedTaskCapabilities>
+  | "dial"
+  | `skill:${string}`;
+
+type TeamPolicySetting = "on" | "off" | "agent";
+
+type TeamPolicy = Resolved & {
+  setting: TeamPolicySetting;
+};
+
+type TeamPolicies = Partial<Record<PolicyKey, TeamPolicy>>;
+
+type TeamPolicyCommand = { type: "set"; capability: PolicyKey; setting: TeamPolicySetting };
+
+type TeamPolicyCommandRequest = {
+  command: TeamPolicyCommand;
 };
 
 type TeamConsultCommand =
@@ -833,6 +972,8 @@ type Connection<C extends Channel = Channel> = {
   executeTeamBreak?(request: TeamBreakCommandRequest): Promise<TeamCommandResult>;
   executeTeamConsult?(request: TeamConsultCommandRequest): Promise<TeamCommandResult>;
   openMedia?(request: OpenMediaRequest): Promise<OpenMediaResult>;
+  setPreference?(request: SetPreferenceRequest): Promise<PreferenceResult>;
+  executeTeamPolicy?(request: TeamPolicyCommandRequest): Promise<TeamCommandResult>;
 };
 
 type Adapter<C extends Channel = Channel> = {
@@ -850,6 +991,13 @@ const ALLOWED_BROWSER_URL_SCHEMES = ["http:", "https:"] as const;
 const IDLE_CAPABILITIES = ["dial", "personalBrowser", "calendar", "contacts"] as const;
 type IdleCapability = (typeof IDLE_CAPABILITIES)[number];
 
+const DEFAULT_TIERS = [
+  { id: "org", label: "Your organisation" },
+  { id: "site", label: "Your site" },
+  { id: "team", label: "Your team" },
+  { id: "person", label: "You" },
+] as const satisfies readonly TierDeclaration[];
+
 const IDLE_CAPABILITY_UI = {
   dial: "Dialpad",
   personalBrowser: "Browser",
@@ -1205,6 +1353,7 @@ compile time.
 | `idleCapabilities` | Declares actions Omni may offer while the agent has no active task, such as voice dialing. Task controls do not belong here. |
 | `phaseLabels` | Optional static adapter-defined display names for canonical `TaskPhase` values. They cannot vary at runtime. |
 | `taskTypePresentation` | Optional static adapter-defined presentation keyed by exact `taskType`. It names the item and its optional agent-facing reference. |
+| `orgTiers` | The organisation's whole ladder as the provider calls it, each tier with the label a desk shows for "who decided". Stated outright, `person` included: what it leaves out does not exist. Omitted for the typical four, `DEFAULT_TIERS`. See **Who decides what an agent may do**. |
 
 ### Authentication methods
 
@@ -1512,6 +1661,8 @@ 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`. |
+| `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.
 
@@ -1702,6 +1853,8 @@ surface in one place, and what obliges an adapter to implement each one.
 | `endBreak()` | The login declares `capabilities.breaks`. |
 | `executeTeamBreak(command)` | The login declares `capabilities.team.breakControl`. |
 | `executeTeamConsult(command)` | The login declares `capabilities.team.consultControl`. |
+| `setPreference(request)` | The login declares `capabilities.preferences`: the person's choice has to have somewhere to go. |
+| `executeTeamPolicy(command)` | The login declares `capabilities.team.policyControl`. |
 | `openMedia(request)` | The manifest channel is `voice`. Every voice task's audio lands in Omni, so there is no voice adapter that does not implement it. |
 
 **The four break methods stand or fall together.** Declaring `capabilities.breaks` at login and then
@@ -2379,8 +2532,15 @@ capabilities: {
 ```
 
 Custom capability IDs must be non-empty and unique within the task. `ui.kind` is `button`, `toggle`,
-or `menu-item`; `ui.placement` is `primary`, `secondary`, or `overflow`. Omni renders the control
-and invokes it with the shared custom task command:
+or `menu-item`; `ui.placement` is `primary`, `secondary`, or `overflow`. `ui.render` says where the
+control's work appears: `inline`, in the workspace beside the task, or `page`, as a page of its own
+— a tab in the same work area as the task's browsers, beside them, and alone on a task that has
+none; inline when absent. `prompt.fields` are what the agent supplies before the action runs — a
+destination number, a reference — as `CredentialField`s Omni renders as a form; the values travel
+on the custom command under the fields' names, as strings, and Omni sends the command only once
+every `required` field has a value. The provider validates what arrives as it validates any
+command; a form is a declaration, not a contract for what the agent typed. Omni renders the
+control and invokes it with the shared custom task command:
 
 ```ts
 {
@@ -2788,6 +2948,7 @@ A lead who also takes calls sees their team on the idle dashboard. `Snapshot.tea
 | --- | --- |
 | `members` | Every member of this lead's team, whatever their state. `[]` says the lead has a team with nobody in it; omitting the roster says something else entirely — see **The login is the permission** below. |
 | `requests` | The members currently asking this lead to join a call, each with the task and the note. Required when the login declares `team.consultControl`, `[]` when nobody is asking; omitted when it does not. See **Consulting a lead**. |
+| `policies` | The team's policy per capability as it stands — the setting, who set it, and `lockedBy` where a tier above the team made it theirs to keep. Required when the login declares `team.policyControl`; omitted when it does not. See **Who decides what an agent may do**. |
 
 | `TeamMember` field | Contract |
 | --- | --- |
@@ -2998,6 +3159,7 @@ what failed, and reports. It never decides for the adapter what a missing microp
 | `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. |
+| `browsers.urlVisibility` | What Omni's own chrome shows of a task browser's URL: `hidden`, `domain`, or `full`. A statement about the chrome, not about what the page renders or a screenshot captures; task browsers only — the personal browser is the agent's own and nothing a provider sends appears in it. A provider reads it before deciding what URL it is willing to send: one that carries confidential data goes out under `hidden` and not under `full`. |
 | `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. |
 
 Omni republishes the report whenever it changes — a permission granted late, a headset unplugged,
@@ -3410,7 +3572,7 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | `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. |
 | `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. |
+| `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. |
 
 Each returns `ProtocolViolation[]` rather than throwing, so a caller can report every problem at
 once. A violation carries a stable `rule` id such as `task.browser.url.scheme`, the `path` it was

package/package.json

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