@xema/omni-protocol 0.1.93 → 0.1.94

package/dist/index.d.ts

@@ -237,7 +237,7 @@ export interface AuthenticationFailure {
 export interface TeamCapabilities {
     /**
      * This lead may act on their team's breaks through `executeTeamBreak` -- force-break, end-forced-break, decide-break-request,
-     * set policy -- as far as the provider supports; a command it lacks answers
+     * set-break-policy -- as far as the provider supports; a command it lacks answers
      * `omni.capability-not-enabled`. Requires `executeTeamBreak`.
      */
     breakControl?: true;
@@ -1223,7 +1223,7 @@ export type BreakApproval = "not-requested"
 /** Granted, and a promise to honour a later commit. */
  | "granted"
 /** Granted and begins when the current task ends. Nobody needs to act. */
- | "starting-after-task" | "in-effect";
+ | "starting-after-task" | "on-break";
 export declare const BREAK_KINDS: readonly ["short-break", "meal", "rest", "training", "coaching", "meeting", "administrative", "technical", "personal", "other"];
 /**
  * The breaks a contact centre runs, named once so providers can agree.
@@ -1245,7 +1245,7 @@ export interface BreakReason {
     label: string;
     group?: string;
     kind?: BreakKind;
-    /** Survives `mayAsk: false`: a mandatory rest is not something a busy hour can cancel. */
+    /** Survives `canRequestBreak: false`: a mandatory rest is not something a busy hour can cancel. */
     alwaysAvailable?: true;
 }
 export interface BreakRequest {
@@ -1272,11 +1272,11 @@ export type ForcedBreak = {
 export interface BreakState {
     approval: BreakApproval;
     /** Whether the agent may ask at all. Distinct from the fate of a request already made. */
-    mayAsk: boolean;
-    /** Shown when `mayAsk` is false, such as "Busy hours". */
-    refusedReason?: string;
+    canRequestBreak: boolean;
+    /** Shown when `canRequestBreak` is false, such as "Busy hours". */
+    requestUnavailableReason?: string;
     decisionReason?: string;
-    retryAfterMs?: number;
+    retryRequestAfterMs?: number;
     /** Not-ready codes this provider offers. Omitted when it defines none. */
     reasons?: BreakReason[];
     /** Which reason the current break is on, a published `BreakReason.id`. Omitted when there is no break; required on a break in effect or starting after the task where the provider publishes `reasons`, a forced one included. */
@@ -1320,7 +1320,7 @@ export interface TeamMember {
     availability: TeamMemberAvailability;
     /** Omitted rather than invented: Omni renders it as a duration. */
     since?: IsoTimestamp;
-    /** A request in flight or a grant not yet in effect. `not-requested` is absence, and `in-effect` is `availability: "on-break"`. */
+    /** A request in flight or a grant not yet in effect. `not-requested` is absence, and `on-break` is `availability: "on-break"`. */
     break?: Extract<BreakApproval, "awaiting-decision" | "granted" | "starting-after-task">;
 }
 /** A member asking this lead to join their call. */
@@ -1395,8 +1395,8 @@ export type TeamBreakCommand = {
     decision: "granted" | "denied";
     reason?: string;
 } | {
-    type: "policy";
-    policy: "ask" | "auto-approve" | "suspended";
+    type: "set-break-policy";
+    policy: "approval-required" | "automatically-approved" | "requests-suspended";
 }
 /** `reasonId` names a published `BreakReason.id`, required whenever the provider publishes reasons: the member's forced break carries it as `activeReasonId`. */
  | {

package/dist/testing.d.ts

@@ -248,7 +248,7 @@ export interface BreakOnTaskStep {
 /**
  * A break asked for on a task begins when the work ends. `steps` is the sequence the provider
  * published, first to last: the request is made while work is outstanding, the commit is reported
- * as `starting-after-task` while it remains, and `in-effect` arrives only once nothing is
+ * as `starting-after-task` while it remains, and `on-break` arrives only once nothing is
  * outstanding -- never beside a task, and never later than the step that has none.
  */
 export declare function assertBreakBeginsAfterTask(steps: readonly BreakOnTaskStep[]): void;

package/dist/testing.js

@@ -949,11 +949,11 @@ export function assertDeniedAndRetriedBreak(approvals) {
     const refused = approvals.indexOf("not-requested", asked + 1);
     if (refused < 0)
         throw new Error("A refused break must return to not-requested, leaving nothing pending");
-    const granted = approvals.findIndex((approval, index) => index > refused && (approval === "granted" || approval === "in-effect"));
+    const granted = approvals.findIndex((approval, index) => index > refused && (approval === "granted" || approval === "on-break"));
     if (granted < 0)
         throw new Error("Break retry scenario must grant a later request");
     const last = approvals.at(-1);
-    if (last !== "granted" && last !== "in-effect") {
+    if (last !== "granted" && last !== "on-break") {
         throw new Error(`Break retry scenario must end granted or in effect, ended ${String(last)}`);
     }
 }
@@ -1866,8 +1866,8 @@ async function driveOneCall(drive) {
     return found;
 }
 // A request goes not-requested -> awaiting-decision | granted; a commit goes granted ->
-// starting-after-task | in-effect; work ending goes starting-after-task -> in-effect; a denial,
-// a cancel, an agent end or a lead end goes back to not-requested; a forced break arrives in-effect
+// starting-after-task | on-break; work ending goes starting-after-task -> on-break; a denial,
+// a cancel, an agent end or a lead end goes back to not-requested; a forced break arrives on-break
 // with `forced`. Nothing else is a move the guide describes.
 /** What a stream has said about the agent's break, and the moves it may not make. */
 export class BreakStream {
@@ -1990,7 +1990,7 @@ export function assertBreakAttemptProviders(candidates, asked) {
 /**
  * A break asked for on a task begins when the work ends. `steps` is the sequence the provider
  * published, first to last: the request is made while work is outstanding, the commit is reported
- * as `starting-after-task` while it remains, and `in-effect` arrives only once nothing is
+ * as `starting-after-task` while it remains, and `on-break` arrives only once nothing is
  * outstanding -- never beside a task, and never later than the step that has none.
  */
 export function assertBreakBeginsAfterTask(steps) {
@@ -2003,14 +2003,14 @@ export function assertBreakBeginsAfterTask(steps) {
     if (committed < 0)
         throw new Error("A break committed on a task is reported as starting-after-task while the work remains");
     steps.forEach((step, index) => {
-        if (step.approval === "in-effect" && step.outstanding > 0) {
-            throw new Error(`steps[${index}] reports in-effect with ${step.outstanding} task(s) outstanding: a break begins when the work ends`);
+        if (step.approval === "on-break" && step.outstanding > 0) {
+            throw new Error(`steps[${index}] reports on-break with ${step.outstanding} task(s) outstanding: a break begins when the work ends`);
         }
         if (step.approval === "starting-after-task" && step.outstanding < 1) {
             throw new Error(`steps[${index}] reports starting-after-task with nothing outstanding: the break should have begun`);
         }
     });
-    if (steps.at(-1)?.approval !== "in-effect") {
+    if (steps.at(-1)?.approval !== "on-break") {
         throw new Error(`Break-on-task scenario must end in effect, ended ${String(steps.at(-1)?.approval)}`);
     }
 }

package/dist/validation.js

@@ -52,7 +52,7 @@ const AUTHENTICATION_STATUSES = membersOf({
     "signed-out": true, authenticating: true, authenticated: true, refreshing: true, expired: true,
 });
 const BREAK_APPROVALS = membersOf({
-    "not-requested": true, "awaiting-decision": true, granted: true, "starting-after-task": true, "in-effect": true,
+    "not-requested": true, "awaiting-decision": true, granted: true, "starting-after-task": true, "on-break": true,
 });
 const TEAM_AVAILABILITIES = membersOf({
     ready: true, "on-task": true, "on-break": true, reserved: true, "signed-out": true,
@@ -1331,13 +1331,13 @@ export function validateBreakStatus(state, tasks, path = "snapshot") {
     ruleEvaluated("break.starting-after-task.tasks");
     if (isPlainObject(state) && state.approval === "starting-after-task"
         && Array.isArray(tasks) && tasks.length === 0) {
-        into.add("break.starting-after-task.tasks", `${path}.break.approval`, "a break starting after the task waits on a task, and the snapshot carries none: with nothing outstanding the break is in-effect");
+        into.add("break.starting-after-task.tasks", `${path}.break.approval`, "a break starting after the task waits on a task, and the snapshot carries none: with nothing outstanding the break is on-break");
     }
-    if (isPlainObject(state) && state.approval === "in-effect"
+    if (isPlainObject(state) && state.approval === "on-break"
         && Array.isArray(tasks) && tasks.length > 0) {
         const listening = tasks.every((task) => isPlainObject(task) && task.listening !== undefined);
         if (!listening) {
-            into.add("break.in-effect.tasks", `${path}.tasks`, "a break in effect holds no task: it begins when the work ends, and until then the state is starting-after-task");
+            into.add("break.on-break.tasks", `${path}.tasks`, "a break in effect holds no task: it begins when the work ends, and until then the state is starting-after-task");
         }
         else {
             const reasons = Array.isArray(state.reasons) ? state.reasons : [];
@@ -1366,7 +1366,7 @@ export function validateTeamBreakCommand(request, context, path = "teamBreakComm
     into.require(isPlainObject(caps.team) && caps.team.breakControl === true, "team.break.command.capability", path, "the login must declare team.breakControl");
     const command = request.command;
     const allowed = {
-        "decide-break-request": ["type", "memberId", "decision", "reason"], policy: ["type", "policy"],
+        "decide-break-request": ["type", "memberId", "decision", "reason"], "set-break-policy": ["type", "policy"],
         "force-break": ["type", "memberId", "reasonId", "reason"], "end-forced-break": ["type", "memberId"],
     };
     const fields = typeof command.type === "string" && Object.hasOwn(allowed, command.type) ? allowed[command.type] : undefined;
@@ -1380,8 +1380,8 @@ export function validateTeamBreakCommand(request, context, path = "teamBreakComm
         into.require(fields.includes(key), "team.break.command.field", `${path}.${key}`, "field is not supported for this command");
     if (command.reason !== undefined)
         into.filled(command.reason, "team.break.command.reason", path, "reason must not be empty");
-    if (command.type === "policy") {
-        into.require(["ask", "auto-approve", "suspended"].includes(command.policy), "team.break.command.policy", path, "unknown break policy");
+    if (command.type === "set-break-policy") {
+        into.require(["approval-required", "automatically-approved", "requests-suspended"].includes(command.policy), "team.break.command.policy", path, "unknown break policy");
         return into.violations;
     }
     into.filled(command.memberId, "team.break.command.member", path, "name the target member");
@@ -1398,7 +1398,7 @@ export function validateTeamBreakCommand(request, context, path = "teamBreakComm
         validateBreakState(context.memberBreak, `${path}.memberBreak`, into);
         const state = isPlainObject(context.memberBreak) ? context.memberBreak : {};
         if (command.type === "end-forced-break")
-            into.require(state.forced !== undefined && (state.approval === "in-effect" || state.approval === "starting-after-task"), "team.break.command.endForcedBreak", path, "end a currently forced break");
+            into.require(state.forced !== undefined && (state.approval === "on-break" || state.approval === "starting-after-task"), "team.break.command.endForcedBreak", path, "end a currently forced break");
         if (command.type === "force-break") {
             if (command.reasonId !== undefined)
                 into.filled(command.reasonId, "team.break.command.reasonId", path, "reasonId must not be empty");
@@ -1449,16 +1449,16 @@ export function validateBreakCommand(method, request, state, context, path = "br
             into.require(selected !== undefined, "break.request.reasonId", path, "choose a currently published reasonId; free text is not a substitute");
         else
             into.require(request.reasonId === undefined, "break.request.reasonId.unexpected", path, "no reason codes were published");
-        into.require(state.mayAsk === true || (isPlainObject(selected) && selected.alwaysAvailable === true), "break.request.mayAsk", path, "asking is disabled except for the selected alwaysAvailable reason");
+        into.require(state.canRequestBreak === true || (isPlainObject(selected) && selected.alwaysAvailable === true), "break.request.canRequestBreak", path, "asking is disabled except for the selected alwaysAvailable reason");
     }
     else {
         into.require(request === undefined, "break.command.arguments", path, "this break method takes no arguments");
         if (method === "commitBreak")
-            into.require(approval === "granted" || approval === "starting-after-task" || approval === "in-effect", "break.command.commit.grant", path, "commit requires a grant; repeated committed state is idempotent");
+            into.require(approval === "granted" || approval === "starting-after-task" || approval === "on-break", "break.command.commit.grant", path, "commit requires a grant; repeated committed state is idempotent");
         if (method === "cancelBreak")
             into.require(approval === "awaiting-decision" || approval === "granted", "break.command.cancel.precommit", path, "cancel only a pre-commit request; a raced commit requires commit recovery");
         if (method === "endBreak") {
-            into.require(approval === "starting-after-task" || approval === "in-effect", "break.command.end.started", path, "end a committed break, including a returning provider still finishing work");
+            into.require(approval === "starting-after-task" || approval === "on-break", "break.command.end.started", path, "end a committed break, including a returning provider still finishing work");
             into.require(state.forced === undefined, "break.command.end.forced", path, "an agent cannot end a forced break; an authorized lead ends it");
         }
     }
@@ -1479,11 +1479,11 @@ export function validateBreakTransition(before, after, path = "break") {
         return into.violations;
     const from = before.approval;
     const to = after.approval;
-    const committed = to === "starting-after-task" || to === "in-effect";
+    const committed = to === "starting-after-task" || to === "on-break";
     if (committed && (from === "not-requested" || from === "awaiting-decision") && after.forced === undefined) {
         into.add("stream.breakState.commitBeforeGrant", `${path}.after.approval`, `${to} follows a commit, and a commit follows granted; the break stood at ${from}`);
     }
-    const backwards = (from === "in-effect" && (to === "awaiting-decision" || to === "granted" || to === "starting-after-task")) ||
+    const backwards = (from === "on-break" && (to === "awaiting-decision" || to === "granted" || to === "starting-after-task")) ||
         (from === "starting-after-task" && (to === "awaiting-decision" || to === "granted")) ||
         (from === "granted" && to === "awaiting-decision");
     if (backwards)
@@ -1497,18 +1497,21 @@ function validateBreakState(value, path, into) {
     }
     into.require(!Object.hasOwn(value, "imposed"), "break.forced.renamed", `${path}.imposed`, "imposed was renamed to forced; use only forced");
     into.oneOf(value.approval, BREAK_APPROVALS, "break.approval", `${path}.approval`);
-    into.require(typeof value.mayAsk === "boolean", "break.mayAsk", `${path}.mayAsk`, "mayAsk says whether the agent may ask for a break: a boolean");
-    for (const field of ["refusedReason", "decisionReason"]) {
+    into.require(!Object.hasOwn(value, "mayAsk"), "break.canRequestBreak.renamed", `${path}.mayAsk`, "mayAsk was renamed to canRequestBreak; use only canRequestBreak");
+    into.require(typeof value.canRequestBreak === "boolean", "break.canRequestBreak", `${path}.canRequestBreak`, "canRequestBreak says whether the agent may ask for a break: a boolean");
+    into.require(!Object.hasOwn(value, "refusedReason"), "break.requestUnavailableReason.renamed", `${path}.refusedReason`, "refusedReason was renamed to requestUnavailableReason; use only requestUnavailableReason");
+    for (const field of ["requestUnavailableReason", "decisionReason"]) {
         if (value[field] !== undefined) {
             into.filled(value[field], `break.${field}`, `${path}.${field}`, `${field} must not be empty when present`);
         }
     }
-    // The refusal is the reason the control is withdrawn; beside `mayAsk: true` it explains nothing.
-    if (value.refusedReason !== undefined) {
-        into.require(value.mayAsk !== true, "break.refusedReason.mayAsk", `${path}.refusedReason`, "refusedReason is shown when mayAsk is false; omit it while the agent may ask");
+    // The refusal is the reason the control is withdrawn; beside `canRequestBreak: true` it explains nothing.
+    if (value.requestUnavailableReason !== undefined) {
+        into.require(value.canRequestBreak !== true, "break.requestUnavailableReason.canRequestBreak", `${path}.requestUnavailableReason`, "requestUnavailableReason is shown when canRequestBreak is false; omit it while the agent may ask");
     }
-    if (value.retryAfterMs !== undefined) {
-        into.require(typeof value.retryAfterMs === "number" && Number.isFinite(value.retryAfterMs) && value.retryAfterMs >= 0, "break.retryAfterMs", `${path}.retryAfterMs`, "retryAfterMs must be a non-negative number when present");
+    into.require(!Object.hasOwn(value, "retryAfterMs"), "break.retryRequestAfterMs.renamed", `${path}.retryAfterMs`, "retryAfterMs was renamed to retryRequestAfterMs on BreakState");
+    if (value.retryRequestAfterMs !== undefined) {
+        into.require(typeof value.retryRequestAfterMs === "number" && Number.isFinite(value.retryRequestAfterMs) && value.retryRequestAfterMs >= 0, "break.retryRequestAfterMs", `${path}.retryRequestAfterMs`, "retryRequestAfterMs must be a non-negative number when present");
     }
     if (value.activeReasonId !== undefined) {
         into.filled(value.activeReasonId, "break.activeReasonId", `${path}.activeReasonId`, "activeReasonId must not be empty when present");
@@ -1519,9 +1522,9 @@ function validateBreakState(value, path, into) {
     if (value.forced !== undefined) {
         validateForcedBreak(value.forced, `${path}.forced`, into);
         // A forced break is a break somebody forced; beside `not-requested` there is no break.
-        // A forced break is a break in progress or about to be: it travels with in-effect or
+        // A forced break is a break in progress or about to be: it travels with on-break or
         // starting-after-task and nothing else. Beside granted, the host would commit a break nobody asked for.
-        into.require(value.approval === "in-effect" || value.approval === "starting-after-task", "break.forced.approval", `${path}.forced`, `a forced break is in effect or starting after the task; ${describeValue(value.approval)} says the agent asked, or that there is none`);
+        into.require(value.approval === "on-break" || value.approval === "starting-after-task", "break.forced.approval", `${path}.forced`, `a forced break is in effect or starting after the task; ${describeValue(value.approval)} says the agent asked, or that there is none`);
     }
     if (value.reasons === undefined)
         return;
@@ -1560,7 +1563,7 @@ function validateBreakState(value, path, into) {
     // forced one included, since the lead's force-break command named it. A break of no kind is a break whose
     // rules -- who may listen through it, whether it counts -- nobody can apply.
     ruleEvaluated("break.activeReasonId.required");
-    if (seen.size > 0 && (value.approval === "in-effect" || value.approval === "starting-after-task")) {
+    if (seen.size > 0 && (value.approval === "on-break" || value.approval === "starting-after-task")) {
         into.require(typeof value.activeReasonId === "string" && value.activeReasonId.length > 0, "break.activeReasonId.required", `${path}.activeReasonId`, `a break ${describeValue(value.approval)} on a provider that publishes reasons names the one it is on`);
     }
 }
@@ -1652,7 +1655,7 @@ function validateTeamMembersInto(teamMembers, path, context, into) {
         if (member.since !== undefined)
             into.timestamp(member.since, "team.member.since", `${at}.since`);
         if (member.break !== undefined) {
-            // Only an outstanding request appears here: `not-requested` is absence, `in-effect` is
+            // Only an outstanding request appears here: `not-requested` is absence, `on-break` is
             // `availability: "on-break"`, and a denial never survives to be reported.
             if (into.oneOf(member.break, MEMBER_BREAKS, "team.member.break", `${at}.break`)) {
                 into.require(member.availability !== "signed-out" && member.availability !== "on-break", "team.member.break.availability", `${at}.break`, "a member on a break or signed out has no request outstanding");

package/guide.md

@@ -53,7 +53,7 @@ transport, a task, a break and a call each have a word of their own:
 | `media` | A task's audio | `started`, `ended` |
 | `transport` | A connection | `connecting`, `active`, `error` |
 | `status` | An authentication session | `signed-out`, `authenticating`, `authenticated`, `refreshing`, `expired` |
-| `approval` | A break request | `not-requested`, `awaiting-decision`, `granted`, `starting-after-task`, `in-effect` |
+| `approval` | A break request | `not-requested`, `awaiting-decision`, `granted`, `starting-after-task`, `on-break` |
 | `availability` | A team member | `ready`, `on-task`, `on-break`, `signed-out` |
 
 ## Versioning
@@ -934,7 +934,7 @@ type BreakApproval =
   | "awaiting-decision"
   | "granted"
   | "starting-after-task"
-  | "in-effect";
+  | "on-break";
 
 type BreakReason = {
   id: string;
@@ -955,10 +955,10 @@ type ForcedBreak =
 
 type BreakState = {
   approval: BreakApproval;
-  mayAsk: boolean;
-  refusedReason?: string;
+  canRequestBreak: boolean;
+  requestUnavailableReason?: string;
   decisionReason?: string;
-  retryAfterMs?: number;
+  retryRequestAfterMs?: number;
   reasons?: BreakReason[];
   activeReasonId?: string;
   forced?: ForcedBreak;
@@ -1035,7 +1035,7 @@ type TeamLeadAssistCommand =
 
 type TeamBreakCommand =
   | { type: "decide-break-request"; memberId: UserId; decision: "granted" | "denied"; reason?: string }
-  | { type: "policy"; policy: "ask" | "auto-approve" | "suspended" }
+  | { type: "set-break-policy"; policy: "approval-required" | "automatically-approved" | "requests-suspended" }
   | { type: "force-break"; memberId: UserId; reasonId?: string; reason?: string }
   | { type: "end-forced-break"; memberId: UserId };
 
@@ -1924,7 +1924,7 @@ them from what arrives later.
 | --- | --- |
 | `breaks` | This login may request a break. Requires the four break methods on the connection. |
 | `team` | This login leads a team. The provider publishes a `TeamMembers` object to it on every snapshot — `members: []` when nobody is in it — and to nobody else. |
-| `team.breakControl` | This lead may act on their team's breaks through `executeTeamBreak` — force-break, end-forced-break, decide-break-request, 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.breakControl` | This lead may act on their team's breaks through `executeTeamBreak` — force-break, end-forced-break, decide-break-request, set-break-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.leadAssistControl` | This lead may join a member's call on request. Requires `executeTeamLeadAssist`. |
 | `team.listeningControl` | This lead may listen to a member's call unasked, in the listed modes and no others: `listen`, `coach`, `join-call`. The list always includes `listen`, since the other two begin from one. Requires `executeTeamListen`. See **Listening to a call**. |
 | `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 team member list carries `policies`. |
@@ -3608,12 +3608,12 @@ nothing while none are being accepted — so they are not published separately.
 | Field | Contract |
 | --- | --- |
 | `approval` | Where the agent's current request stands. See the states below. |
-| `mayAsk` | Whether the agent may ask at all. Distinct from `approval`. |
-| `refusedReason` | Display-ready reason shown when `mayAsk` is false — a standing gate that applies to everyone. |
+| `canRequestBreak` | Whether the agent may ask at all. Distinct from `approval`. |
+| `requestUnavailableReason` | Display-ready reason shown when `canRequestBreak` is false — a standing gate that applies to everyone. |
 | `decisionReason` | The words whoever decided attached, from `decide.reason`. About one request and one decision, not a standing gate. |
-| `retryAfterMs` | How long until the agent may retry, when the provider can say. |
+| `retryRequestAfterMs` | Milliseconds until the agent may retry a break request, when the provider can say. |
 | `reasons` | Not-ready codes this provider offers. Omitted when it defines none; an empty list is refused, being a second spelling of the same fact. |
-| `activeReasonId` | The `BreakReason.id` the current break is on. Omitted when there is no break. Required on a break `in-effect` or `starting-after-task` where the provider publishes `reasons`, a forced break included (`break.activeReasonId.required`): a break with a kind the provider cannot name is a break whose rules nobody can apply. |
+| `activeReasonId` | The `BreakReason.id` the current break is on. Omitted when there is no break. Required on a break `on-break` or `starting-after-task` where the provider publishes `reasons`, a forced break included (`break.activeReasonId.required`): a break with a kind the provider cannot name is a break whose rules nobody can apply. |
 | `forced` | Set when the break was forced on the agent rather than requested. |
 
 A request can be waiting for two unrelated things, and they are separate values because
@@ -3624,8 +3624,8 @@ rendering one as the other tells an agent to wait for somebody who is never comi
 | `not-requested` | No request outstanding. |
 | `awaiting-decision` | A person has to decide. The agent is waiting on somebody. |
 | `granted` | A person decided yes. Omni may now tell this provider to stop the agent; until it does, work continues normally, and this says nothing about why Omni has not. |
-| `starting-after-task` | Omni has told the provider to stop; the break begins when the current task ends. No new work arrives meanwhile, and nobody needs to act. It waits on a task, so beside no task it is refused (`break.starting-after-task.tasks`): a committed break with nothing outstanding is `in-effect`. |
-| `in-effect` | The agent is on the break now. It holds no task: a break begins when the work ends, so a snapshot reporting `in-effect` beside a task is refused as `break.in-effect.tasks`. The one exception is a lead's listening task during a `coaching`, `administrative` or `training` break -- see **Listening to a call**. |
+| `starting-after-task` | Omni has told the provider to stop; the break begins when the current task ends. No new work arrives meanwhile, and nobody needs to act. It waits on a task, so beside no task it is refused (`break.starting-after-task.tasks`): a committed break with nothing outstanding is `on-break`. |
+| `on-break` | The agent is on the break now. It holds no task: a break begins when the work ends, so a snapshot reporting `on-break` beside a task is refused as `break.on-break.tasks`. The one exception is a lead's listening task during a `coaching`, `administrative` or `training` break -- see **Listening to a call**. |
 
 A denial is a decision, not a standing approval state. The provider transitions the request directly
 to `not-requested`; Omni returns the agent to idle and never asks again on their behalf. They saw the
@@ -3636,16 +3636,47 @@ A provider reports `starting-after-task` only after Omni commits a `granted` req
 work is still active. Omni does not send the request again, because asking again would not move
 it; it sends the commit again only from a reconnect snapshot that shows the grant still standing.
 
-`mayAsk: false` is what lets Omni withdraw the control rather than let an agent ask and be
+`canRequestBreak: false` is what lets Omni withdraw the control rather than let an agent ask and be
 refused. A `BreakReason` marked `alwaysAvailable` survives it: a mandatory rest period is not
 something a busy hour can cancel, and Omni keeps offering those while the rest are withdrawn.
 
 ### Forced breaks
 
+Migration: the break-state field formerly named retryAfterMs is now `BreakState.retryRequestAfterMs`,
+with diagnostic `break.retryRequestAfterMs`. It remains an optional non-negative finite number
+of milliseconds; the former break field is rejected even alongside the new field.
+The separate authentication and general failure retryAfterMs fields are unchanged.
+
+Migration: the former in-effect break approval value is now `on-break`. It means the
+agent is on the break, not merely granted permission. The old value is rejected without an
+alias. The task prerequisite, supported listening exceptions and ordering rules are unchanged;
+the task-conflict diagnostic is `break.on-break.tasks`. Team member availability already uses
+`on-break` and is unchanged.
+
+Migration: the former refusedReason field is now `BreakState.requestUnavailableReason`.
+It explains why requests are unavailable when `canRequestBreak` is false; `decisionReason`
+continues to explain a particular approval or denial. The old field is rejected even alongside
+the new one, and related diagnostics use requestUnavailableReason.
+
+Migration: the former mayAsk field is now `BreakState.canRequestBreak`. The old field is
+rejected even beside the new field. Validation diagnostics use canRequestBreak in place of
+mayAsk. Request eligibility remains distinct from approval; existing alwaysAvailable reason
+exceptions are unchanged. Hosts and providers must update together.
+
 Migration: ImposedBreak is now `ForcedBreak`, and the former imposed field is now
 `BreakState.forced`. Diagnostic and harness coverage names use `break.forced`; the agent-end
 diagnostic is `break.command.end.forced`. Update hosts and providers together. The old field
 is rejected, including when both spellings are sent; no compatibility alias is provided.
+The break policy value formerly named auto-approve is now `automatically-approved`.
+Requests are approved automatically; approval does not skip commitment or the prerequisites
+for starting a break. The former value is rejected without an alias.
+The break policy value formerly named suspended is now `requests-suspended`. The former
+value is rejected without an alias. It suspends new requests, not breaks already underway.
+The break policy value formerly named ask is now `approval-required`: requests require
+approval. The former value is rejected without an alias; automatically-approved and requests-suspended retain
+their existing behavior.
+The team break command formerly named policy is now `set-break-policy`. The former
+command is rejected without an alias; its policy field is unchanged. Hosts and providers must adopt the new name together.
 The team break command formerly named decide is now `decide-break-request`. The former
 spelling is rejected without an alias; the granted/denied decisions and pending-request
 prerequisite are unchanged.
@@ -3667,7 +3698,7 @@ them, not the machinery that carried it out.
 Omni resolves the name to show with `describeUsers()`, so a provider sends the identifier and never
 a display name.
 
-**A forced break travels with `in-effect` or `starting-after-task`, and nothing else.** It is a
+**A forced break travels with `on-break` or `starting-after-task`, and nothing else.** It is a
 break in progress or about to be; beside `granted` or `awaiting-decision` the host would read a
 request the agent never made and commit it (`break.forced.approval`). Where the provider publishes
 `reasons`, the lead's `force-break` named one, and the member's state carries it as `activeReasonId`.
@@ -3771,10 +3802,10 @@ request object only to the request method, and undefined to the other three.
 
 | Method | Required current state |
 | --- | --- |
-| `requestBreak` | `not-requested`; selected current reason code when codes exist; `mayAsk` or the selected reason's `alwaysAvailable` exception. Free text does not replace a code. |
-| `commitBreak` | `granted`, or already committed for an idempotent repeat. A later change to `mayAsk` does not revoke the grant. |
+| `requestBreak` | `not-requested`; selected current reason code when codes exist; `canRequestBreak` or the selected reason's `alwaysAvailable` exception. Free text does not replace a code. |
+| `commitBreak` | `granted`, or already committed for an idempotent repeat. A later change to `canRequestBreak` does not revoke the grant. |
 | `cancelBreak` | `awaiting-decision` or `granted`. A concurrent commit winning still answers `omni.break-already-committed` and requires recovery. |
-| `endBreak` | `in-effect` or `starting-after-task` during reconciliation; an agent cannot end a forced break. |
+| `endBreak` | `on-break` or `starting-after-task` during reconciliation; an agent cannot end a forced break. |
 
 Use `validateTeamBreakCommand(request, context)` for lead decisions, forcing a break, ending a forced break and
 policy commands. It requires the live lead capability and active transport, a current target
@@ -3933,11 +3964,11 @@ Omni coordinates one break attempt as follows:
    causes Omni to take the cancel path.
 4. If every asked provider reports `granted`, durably choose commit, enter `committing-break`,
    and send `commitBreak()` to each of them. A provider then stops offering new work
-   and reports `starting-after-task` or `in-effect`. The **commit bound** — ten seconds from the
+   and reports `starting-after-task` or `on-break`. The **commit bound** — ten seconds from the
    decision, tunable per deployment — decides who is kept: a provider that has not applied the
    commit by then, still `granted` or unreachable, is set aside as unreconciled and the break
-   begins without it. `in-effect` decides `on-break`: Omni enters it once every kept provider
-   reports `in-effect`. A kept provider reporting `starting-after-task` has applied the commit
+   begins without it. `on-break` decides `on-break`: Omni enters it once every kept provider
+   reports `on-break`. A kept provider reporting `starting-after-task` has applied the commit
    and is finishing a task; the bound is on delivery, not on that task. Omni shows the break as
    settled and beginning when the task ends, and offers no cancel, because the commit is durable.
 5. If any asked provider fails or denies the request, cannot be reconciled within the bounded
@@ -3970,7 +4001,7 @@ Setting a provider aside is not a rollback and not a cancel. The commit stands a
 obligation stands: until that provider is stopped it has not stopped. When it returns it emits a
 snapshot before anything else, and the snapshot decides:
 
-- `in-effect` or `starting-after-task` — the commit arrived after all. Nothing to send.
+- `on-break` or `starting-after-task` — the commit arrived after all. Nothing to send.
 - still `granted` — the commit was lost. Omni sends `commitBreak()` now. If the original turns up
   late behind it, the provider stops an agent who is already stopped; nothing happens, because a
   commit is a state to be in, not an act to be done.
@@ -3983,7 +4014,7 @@ no capacity until it is reconciled.
 
 **If the agent has already ended the break elsewhere, the break attempt is over** and the returning
 provider is reconciled to that instead: still `granted` gets `cancelBreak()`, because committing
-would stop an agent who is working again; `starting-after-task` or `in-effect` gets `endBreak()`.
+would stop an agent who is working again; `starting-after-task` or `on-break` gets `endBreak()`.
 Never rolling back is about a break that is still on, not one the agent has finished.
 
 Omni may tell the agent which platforms the break has not yet reached, as it already does when a
@@ -4026,7 +4057,7 @@ reported through `break-state`.
 
 Commits the `granted` request. Once the provider has reported `granted`, it cannot fail for a
 business reason. On commit the provider stops offering new work and reports
-`starting-after-task` while existing work finishes, or `in-effect` when the break is in effect.
+`starting-after-task` while existing work finishes, or `on-break` when the break is in effect.
 Committing a break that is already in effect changes nothing and answers `committed`.
 
 ### `endBreak()`
@@ -4107,7 +4138,7 @@ One method, `executeTeamBreak`, taking a discriminated command exactly as `execu
 | Command | Effect |
 | --- | --- |
 | `{ type: "decide-break-request", memberId: UserId, decision, reason? }` | Settles one pending request. `decision` is `granted` or `denied`. A grant moves the member to `granted`; a denial ends the request and moves it directly to `not-requested`. |
-| `{ type: "policy", policy }` | `ask`, `auto-approve`, or `suspended`. |
+| `{ type: "set-break-policy", policy }` | `approval-required`, `automatically-approved`, or `requests-suspended`. |
 | `{ type: "force-break", memberId: UserId, reasonId?, reason? }` | Puts a member on a break they did not ask for. `reasonId` names a published `BreakReason.id` and is required whenever the provider publishes `reasons`; the member's forced break carries it as `activeReasonId`, so its kind is known. |
 | `{ type: "end-forced-break", memberId: UserId }` | Ends a forced break on that member, whoever forced it. |
 
@@ -4115,8 +4146,8 @@ One method, `executeTeamBreak`, taking a discriminated command exactly as `execu
 never an identifier from another provider, and Omni does not translate between them; names come
 from `describeUsers()`.
 
-`suspended` means requests are **rejected outright** rather than left pending — nobody is coming to
-approve them. A provider that suspends breaks must also publish `mayAsk: false` to the team's
+`requests-suspended` means requests are **rejected outright** rather than left pending — nobody is coming to
+approve them. A provider that suspends break requests must also publish `canRequestBreak: false` to the team's
 agents so they see it before asking. A `force-break` must likewise reach that member as a `forced` break
 on their own `BreakState`, or they are stopped from working with no way to see why.
 
@@ -4164,7 +4195,7 @@ or until it is withdrawn or declined.
 
 **A lead on a break does not join.** A break is a reported state in which the agent is not working,
 and a join is work. Omni offers Join to a lead only while their own `BreakState.approval` is neither
-`starting-after-task` nor `in-effect` -- a committed break waiting for the lead's current work to
+`starting-after-task` nor `on-break` -- a committed break waiting for the lead's current work to
 finish is not given more -- and a provider answers a `join` from a lead on such a break `failed`.
 The request stands for another lead, as it does when this one is already on a call.
 
@@ -4319,7 +4350,7 @@ about whether anybody has to act on it, and the difference is a lead's entire ac
 | `starting-after-task` | Already granted; it begins when their current task ends. Nobody needs to act. |
 
 Those three are the only values that appear here. `not-requested` is absence — omit `break`
-instead. `in-effect` is `availability: "on-break"`, and a denial transitions to `not-requested`,
+instead. `on-break` is `availability: "on-break"`, and a denial transitions to `not-requested`,
 so neither survives to be reported. It is otherwise the same `BreakApproval` the member's own
 break state uses, rather than a parallel vocabulary for the lead's view, so the two cannot drift
 apart.
@@ -4951,14 +4982,14 @@ covers a `diagnostic`: shown where the agent works, and counted.
 
 Replaces this provider's complete `break` object. Its `approval` uses the canonical
 `not-requested`, `awaiting-decision`, `granted`, `starting-after-task` and
-`in-effect` states defined under Breaks; the event also carries the corresponding may-ask state,
+`on-break` states defined under Breaks; the event also carries the corresponding may-ask state,
 reasons, retry details, and any forced break.
 
 Each state is also held to the one before it. A commit's states, `starting-after-task` and
-`in-effect`, follow a grant — the one arrival in a committed state nobody asked for is a forced
+`on-break`, follow a grant — the one arrival in a committed state nobody asked for is a forced
 break, which says so with `forced`: in effect at once, or `starting-after-task` while the member
 finishes the call they are on (`stream.breakState.commitBeforeGrant`); and a break never moves backwards —
-from `in-effect` or `starting-after-task` to a grant or a request, or from `granted` to
+from `on-break` or `starting-after-task` to a grant or a request, or from `granted` to
 `awaiting-decision` — a new request passes through `not-requested` (`stream.breakState.backwards`).
 `exerciseAdapter` holds the stream to that from the connect snapshot on;
 `assertBreakFollowsItsRequests` holds any sequence.
@@ -4986,8 +5017,8 @@ unresolved operation per provider/attempt; recovery must resolve uncertainty bef
 operation is dispatched. The source must fence delayed operations against its own attempt state.
 
 Normal order is `not-requested` → `awaiting-decision` → `granted` →
-`starting-after-task` → `in-effect` → `not-requested`. Auto-approval may go directly to
-`granted`; a commit with no outstanding work may go directly to `in-effect`. Denial/cancel
+`starting-after-task` → `on-break` → `not-requested`. Auto-approval may go directly to
+`granted`; a commit with no outstanding work may go directly to `on-break`. Denial/cancel
 returns a precommit request to `not-requested`; an authorized agent or lead end returns a committed
 break there. Same-state restatements are allowed. An evidenced forced break is the explicit
 exception to requesting/granting, and must carry its forced actor/state. Neither skipped
@@ -5008,7 +5039,7 @@ not implement or assume invocation of Protocol's two-phase request/commit coordi
 For a multi-provider break attempt, "every provider" is the set of providers frozen when the
 attempt entered `requesting-break`. Omni commits only after every asked provider reports `granted` —
 that one is unconditional, because nothing has stopped yet and waiting costs only time. It enters
-`on-break` once every kept provider reports `in-effect`; the commit bound decides who is kept,
+`on-break` once every kept provider reports `on-break`; the commit bound decides who is kept,
 setting aside a provider that has not applied the commit rather than holding a break that has
 already begun elsewhere. Otherwise it follows the two-phase rules under **Coordinating a
 multi-provider break**.
@@ -5391,7 +5422,7 @@ cannot be established from TypeScript structure alone.
 | `assertBreakFollowsItsRequests(envelopes, snapshot?)` | A break follows its requests: a commit's states only after a grant, never backwards, and a forced break arriving in effect with `forced`. The harness applies the same rules after the connect snapshot. |
 | `assertMediaFollowsTheTask(envelopes, snapshot?)` | The media follows the task and never decides it: every task is introduced once, `task-media-started` and `task-media-ended` alternate on work that has begun, media ends only where it arrived, and what follows the media ending is `completing` or `task-ended`. The harness applies the same rules to every event after the connect snapshot (`stream.*`). A sequence with no media satisfies it by never testing it — pair it with the assertion that the media end is present. |
 | `assertBreakAttemptProviders(candidates, asked)` | A break attempt asks every usable provider holding capacity, `refreshing` included, and nothing of a provider whose login is `expired`. |
-| `assertBreakBeginsAfterTask(steps)` | A break asked for on a task is committed as `starting-after-task` while work remains and reaches `in-effect` only once nothing is outstanding — never beside a task, never later than the step that has none. |
+| `assertBreakBeginsAfterTask(steps)` | A break asked for on a task is committed as `starting-after-task` while work remains and reaches `on-break` only once nothing is outstanding — never beside a task, never later than the step that has none. |
 | `assertDeniedAndRetriedBreak(states)` | A denial transitions directly to `not-requested`; a later request can still be granted. |
 | `assertWrapTimeout(task, mediaEndedAt, deadline, toleranceMs?)` | The wrap deadline equals media end plus the task allowance, within a tolerance that defaults to 1000ms; a task with no allowance has no deadline, and one observed is the violation. |
 | `assertBrowserSessionIsolation(left, right, expected)` | Browser reuse follows only the declared isolation scheme. |

package/package.json

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