@xema/omni-protocol 0.1.12 → 0.1.14

package/README.md

@@ -70,7 +70,8 @@ expect(result.disconnectWasClean).toBe(true);
 ```
 
 Run the contract scenarios beside it — authentication restore and expiry, capability withdrawal,
-reconnect with missed assignments, break denial and retry, wrap timeout, browser isolation.
+reconnect with missed assignments, break denial and retry, a break asked for on a task, who a
+break asks, wrap timeout, browser isolation.
 
 > **Assert both directions.** Every helper rejects a violating input as well as accepting a
 > conforming one. A suite that only asserts "this conforming case does not throw" passes unchanged

package/dist/index.d.ts

@@ -137,7 +137,11 @@ export interface AuthenticationFailure {
 }
 /** What a lead may do with their team. Declared by presence. */
 export interface TeamCapabilities {
-    /** This lead decides their team's breaks. Requires `executeTeamBreak`. */
+    /**
+     * 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`. Requires `executeTeamBreak`.
+     */
     breakControl?: true;
     /** This lead may join a member's call on request. Requires `executeTeamConsult`. */
     consultControl?: true;
@@ -998,6 +1002,13 @@ export interface BrowserSessionKeyInput {
     taskType: string;
     browser: TaskBrowser;
 }
+/**
+ * Whether two logins declare the same capabilities, field by field. The comparison an adapter
+ * makes before republishing `authenticated`: capabilities are current, not fixed, and the natural
+ * guard -- comparing the identity -- never fires on a demotion, because the thing that changed is
+ * not the thing being compared. Key order does not matter, and `team: {}` is not `team` absent.
+ */
+export declare function sameCapabilities(a: SessionCapabilities, b: SessionCapabilities): boolean;
 /**
  * The storage-profile key a reusing browser shares, or `undefined` where it shares nothing.
  *

package/dist/index.js

@@ -128,6 +128,18 @@ export const HANDLING_STEPS_WITH_A_PERSON = [
 export function handlingStepExpectsAPerson(step) {
     return HANDLING_STEPS_WITH_A_PERSON.includes(step);
 }
+/**
+ * Whether two logins declare the same capabilities, field by field. The comparison an adapter
+ * makes before republishing `authenticated`: capabilities are current, not fixed, and the natural
+ * guard -- comparing the identity -- never fires on a demotion, because the thing that changed is
+ * not the thing being compared. Key order does not matter, and `team: {}` is not `team` absent.
+ */
+export function sameCapabilities(a, b) {
+    return a.breaks === b.breaks &&
+        (a.team === undefined) === (b.team === undefined) &&
+        a.team?.breakControl === b.team?.breakControl &&
+        a.team?.consultControl === b.team?.consultControl;
+}
 /**
  * The storage-profile key a reusing browser shares, or `undefined` where it shares nothing.
  *

package/dist/testing.d.ts

@@ -95,6 +95,33 @@ export declare function assertReconnectWithMissedAssignments<C extends Channel>(
  * both.
  */
 export declare function assertDeniedAndRetriedBreak(approvals: readonly BreakApproval[]): void;
+/** One provider as the host sees it when freezing a break attempt's participant set. */
+export interface BreakCandidate {
+    id: string;
+    authentication: AuthenticationState["status"];
+    /** Whether the agent can currently receive work from it: connected, with a capacity stated. */
+    holdsCapacity: boolean;
+}
+/**
+ * The participant set of a break attempt is every connected provider from which the agent can
+ * currently receive work. A provider whose login is not usable -- `expired` above all -- is not
+ * one, whatever else is true of it: nothing can be asked of it, and a host that waits on it
+ * stalls the break for everyone. A usable provider holding capacity is one, and cannot be left
+ * out. `refreshing` is usable: identity and capabilities remain available and work continues.
+ */
+export declare function assertBreakParticipants(candidates: readonly BreakCandidate[], participants: readonly string[]): void;
+/** One published moment of a break asked for on a task: the approval, and how many tasks were outstanding. */
+export interface BreakOnTaskStep {
+    approval: BreakApproval;
+    outstanding: number;
+}
+/**
+ * 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
+ * outstanding -- never beside a task, and never later than the step that has none.
+ */
+export declare function assertBreakBeginsAfterTask(steps: readonly BreakOnTaskStep[]): void;
 /**
  * Validates the deadline derived from media end and the task's fixed wrap allowance.
  *

package/dist/testing.js

@@ -1,4 +1,4 @@
-import { browserSessionKey, } from "./index.js";
+import { browserSessionKey, sameCapabilities, } from "./index.js";
 import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateManifest, validateSnapshot, } from "./validation.js";
 export { ProtocolConformanceError, assertNoViolations } from "./validation.js";
 /**
@@ -313,10 +313,6 @@ function publishesUserIds(snapshot) {
         return false;
     return snapshot.tasks.some(task => Array.isArray(task?.handlingHistory) && task.handlingHistory.some(step => step?.by !== undefined));
 }
-const sameCapabilities = (a, b) => a.breaks === b.breaks &&
-    (a.team === undefined) === (b.team === undefined) &&
-    a.team?.breakControl === b.team?.breakControl &&
-    a.team?.consultControl === b.team?.consultControl;
 /**
  * `refreshing` carries the identity and capabilities of the login it refreshes. A change to
  * either is published as `authenticated`; a different identity is a new login.
@@ -491,6 +487,58 @@ export function assertDeniedAndRetriedBreak(approvals) {
         throw new Error(`Break retry scenario must end granted or in effect, ended ${String(last)}`);
     }
 }
+const usableLogin = (status) => status === "authenticated" || status === "refreshing";
+/**
+ * The participant set of a break attempt is every connected provider from which the agent can
+ * currently receive work. A provider whose login is not usable -- `expired` above all -- is not
+ * one, whatever else is true of it: nothing can be asked of it, and a host that waits on it
+ * stalls the break for everyone. A usable provider holding capacity is one, and cannot be left
+ * out. `refreshing` is usable: identity and capabilities remain available and work continues.
+ */
+export function assertBreakParticipants(candidates, participants) {
+    const chosen = new Set(participants);
+    for (const id of participants) {
+        if (!candidates.some(candidate => candidate.id === id))
+            throw new Error(`${id} is not a provider the host knows`);
+    }
+    for (const candidate of candidates) {
+        const expected = usableLogin(candidate.authentication) && candidate.holdsCapacity;
+        if (expected && !chosen.has(candidate.id)) {
+            throw new Error(`${candidate.id} can give the agent work and must be a participant`);
+        }
+        if (!expected && chosen.has(candidate.id)) {
+            const why = usableLogin(candidate.authentication) ? "holds no capacity" : `is ${candidate.authentication}`;
+            throw new Error(`${candidate.id} ${why} and is not a participant: nothing can be asked of it`);
+        }
+    }
+}
+/**
+ * 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
+ * outstanding -- never beside a task, and never later than the step that has none.
+ */
+export function assertBreakBeginsAfterTask(steps) {
+    const asked = steps.findIndex(step => step.approval === "awaiting-decision" || step.approval === "granted");
+    if (asked < 0)
+        throw new Error("Break-on-task scenario requires a request");
+    if ((steps[asked]?.outstanding ?? 0) < 1)
+        throw new Error("Break-on-task scenario requires the request to be made while a task is outstanding");
+    const committed = steps.findIndex((step, index) => index > asked && step.approval === "starting-after-task");
+    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 === "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") {
+        throw new Error(`Break-on-task scenario must end in effect, ended ${String(steps.at(-1)?.approval)}`);
+    }
+}
 /**
  * Validates the deadline derived from media end and the task's fixed wrap allowance.
  *

package/dist/validation.js

@@ -808,6 +808,12 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
             }
         });
     }
+    // A break in effect begins when the work ends, so it holds no task. A snapshot reporting both
+    // describes a state the agent cannot be in, whichever half is stale.
+    if (isPlainObject(snapshot.break) && snapshot.break.approval === "in-effect"
+        && Array.isArray(snapshot.tasks) && snapshot.tasks.length > 0) {
+        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");
+    }
     // Presence is the permission, and it cuts both ways: data a provider never declared a
     // capability for is data Omni would show against a control the agent does not have.
     const idle = isPlainObject(manifest) && isPlainObject(manifest.idleCapabilities) ? manifest.idleCapabilities : {};

package/guide.md

@@ -1002,7 +1002,6 @@ Request/response polling does not have those properties and is not a transport f
 | `@xema/omni-protocol` | Provider adapter contract and shared domain types |
 | `@xema/omni-protocol/testing` | Adapter conformance helpers |
 | `@xema/omni-protocol/validation` | Runtime validators Omni and adapters both use to reject malformed data |
-| `@xema/omni-protocol/design` | Host design-language integration. Specified separately; no part of it is a provider surface. |
 
 ## Declaring an adapter
 
@@ -1352,7 +1351,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 `TeamRoster` to it on every snapshot — `[]` when nobody is in it — and to nobody else. |
-| `team.breakControl` | This lead decides their team's breaks. Requires `executeTeamBreak`. |
+| `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`. |
 
 A session action is available only when both the capability and Omni provisioning permit it.
@@ -1366,7 +1365,10 @@ roster arrives, and nothing for anybody else — and withdraws it on the next re
 capability goes. A command that arrives after its capability was withdrawn is answered `failed`
 with `omni.capability-not-enabled`: the provider names it, so Omni never has to infer from a
 capability change it may not have rendered yet that "you are no longer a lead" is the message
-rather than "that did not work".
+rather than "that did not work". One trap for adapter authors: the natural guard on a republish
+compares the identity, and a demotion does not touch it — compare the capabilities, field by
+field, which is what `sameCapabilities()` does. The thing that changed is not the thing you are
+comparing, and `assertCapabilityWithdrawal` is the test that catches a guard which never fires.
 
 ### Starting authentication
 
@@ -2257,7 +2259,7 @@ rendering one as the other tells an agent to wait for somebody who is never comi
 | `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. |
-| `in-effect` | The agent is on the break now. |
+| `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`. |
 
 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
@@ -2362,6 +2364,11 @@ Requests permission to stop the agent later; it does not itself stop work. The p
 offering work and reports `awaiting-decision` or `granted` through `break-state` events. If the request is denied, the
 provider reports `not-requested` directly, with `decisionReason` when one was supplied.
 
+**An agent asks from anywhere — idle or on a task** — and Omni offers the request in the task
+workspace as it does on the idle dashboard. Asked on a task, the break is decided and committed like
+any other and begins when the work ends: that is `starting-after-task`, and
+`assertBreakBeginsAfterTask` is the scenario that holds a provider to it.
+
 #### Break reasons
 
 A provider that defines not-ready reason codes publishes them on `Snapshot.break.reasons`,
@@ -2477,6 +2484,11 @@ Omni coordinates one attempt as follows:
 
 1. Freeze the participant set to every connected provider from which the agent can currently
    receive work. A provider joining during the attempt is given no capacity until it finishes.
+   A provider whose authentication is `expired` is not one the agent can receive work from and is
+   not a participant: nothing is asked of it, the break proceeds without it, and when the login
+   is restored it is reconciled from its snapshot as a set-aside provider is, with no capacity
+   until then. `refreshing` keeps a provider in — its identity and capabilities remain available
+   and work continues. `assertBreakParticipants` holds a host to this set.
 2. Enter `requesting-break`. Keep the agent's normal capacity in place throughout this phase.
 3. Send one `requestBreak` to every participant. A provider reports `awaiting-decision` or
    `granted`; neither state stops work. A denial transitions directly to `not-requested` and
@@ -2702,6 +2714,12 @@ provider whose lead is already at the ceiling answers the join `failed`.
 they joined -- is answered `failed`, whatever their ceiling; the request stands for another lead,
 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
+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.
+
 **On `decline`, or a request the agent withdraws with `{ type: "lead", action: "cancel" }`, the
 provider clears `lead` from the agent's task** and drops the request from every roster. Nothing
 else changes; the agent is still on the call.
@@ -3138,6 +3156,12 @@ Use it for every `UserId` — `handlingHistory[].by`, roster members, `memberId`
 lead command, `ImposedBreak.by`. A bare one is only ever compared against another from the **same** provider; anything
 wider goes through this key.
 
+### `sameCapabilities(a, b)`
+
+Whether two logins declare the same capabilities, field by field — key order aside, and with
+`team: {}` distinct from `team` absent. It is the comparison an adapter makes before republishing
+`authenticated`, and the one `exerciseAdapter` holds `refreshing` to.
+
 ## Runtime validation
 
 Structural rules in this document are executable through the runtime validators Omni applies to
@@ -3233,10 +3257,12 @@ cannot be established from TypeScript structure alone.
 | Helper | Contract checked |
 | --- | --- |
 | `assertCapabilityWithdrawal(states, snapshot, manifest)` | A capability withdrawn by a later `authenticated` state is gone from the next snapshot: no roster for a login that no longer leads, no requests for one that may no longer join. Every state is validated on the way, `refreshing` must carry the login over, and the sequence passes only through usable states. |
-| `assertCommandRefusedAfterWithdrawal(result)` | A command that arrives after its capability was withdrawn fails with `omni.capability-not-enabled`, named by the provider. |
+| `assertCommandRefusedAfterWithdrawal(result)` | A command that arrives after its capability was withdrawn fails with `omni.capability-not-enabled`, named by the provider. The same assertion serves a command the provider never supported under a capability it declares. |
 | `assertReached(result, subjects)` | The exercise met every subject named; throws listing those it did not. Pair it with a clean `exerciseAdapter` result. |
 | `assertAuthenticationRestoreAndExpiry(states)` | A restored authenticated session can refresh and ends in expiry. Every state is validated. |
 | `assertReconnectWithMissedAssignments(before, reconnect, ids)` | A reconnect snapshot restores assignments received while offline. |
+| `assertBreakParticipants(candidates, participants)` | 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. |
 | `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. |
 | `assertBrowserIsolationAndReuse(left, right, expected)` | Browser reuse follows only the declared isolation scheme. |
@@ -3250,11 +3276,8 @@ Adapters should run the relevant scenarios against deterministic test state befo
 
 ## A provider does not style the workspace
 
-The package ships a `design` entry point, and none of it is for adapters. It is host UI
-extensibility — how a deployment themes Omni — and it is specified with the host, not here, which
-is why no part of it is declared under **Shapes**.
-
-What belongs in this contract is the boundary. A provider says what a control **is** through its
+How a deployment themes Omni is the host's concern and is specified with the host, not here. What
+belongs in this contract is the boundary. A provider says what a control **is** through its
 capabilities and what its work is **called** through `phaseLabels` and `taskTypePresentation`; how
 any of it is drawn is Omni's. A task cannot select a design language, inject a component, or
 override the agent's theme and font preferences.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xema/omni-protocol",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",
@@ -18,10 +18,6 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./design": {
-      "types": "./dist/design.d.ts",
-      "import": "./dist/design.js"
-    },
     "./testing": {
       "types": "./dist/testing.d.ts",
       "import": "./dist/testing.js"

package/dist/design.d.ts

@@ -1,49 +0,0 @@
-export type ThemePreference = "system" | "light" | "dark";
-export type ResolvedTheme = Exclude<ThemePreference, "system">;
-export type Density = "compact" | "comfortable" | "spacious";
-/** Semantic values consumed by Omni's layout, independent of a CSS framework. */
-export interface DesignTokens {
-    accent: string;
-    accentText: string;
-    surface: string;
-    surfaceMuted: string;
-    selected: string;
-    text: string;
-    mutedText: string;
-    border: string;
-    info: string;
-    success: string;
-    warning: string;
-    danger: string;
-    radius: string;
-    radiusLarge: string;
-    shadow: string;
-    controlFont: string;
-    controlWeight: string;
-    controlTracking: string;
-    controlHeight: string;
-}
-export type ControlKind = "button" | "icon-button" | "checkbox" | "input" | "textarea" | "select" | "tabs" | "menu" | "badge" | "card" | "progress";
-export interface DesignLanguageManifest {
-    id: string;
-    displayName: string;
-    supportedThemes: ReadonlyArray<ResolvedTheme>;
-    supportedControls: ReadonlyArray<ControlKind>;
-    defaultDensity: Density;
-}
-export interface DesignLanguage {
-    manifest: DesignLanguageManifest;
-    tokens: Record<ResolvedTheme, DesignTokens>;
-}
-/**
- * A framework bridge can use any native control representation: an Angular
- * component type, a React component, or an Omni DOM renderer. The protocol
- * deliberately does not make one UI framework part of the ABI.
- */
-export interface DesignLanguageAdapter<TControl = unknown> {
-    readonly language: DesignLanguage;
-    resolveControl(kind: ControlKind): TControl | Promise<TControl>;
-}
-export declare function defineDesignLanguage<TControl, T extends DesignLanguageAdapter<TControl>>(adapter: T): T;
-/** Maps semantic tokens to the stable CSS custom properties understood by Omni. */
-export declare function designTokenProperties(tokens: DesignTokens): Record<string, string>;

package/dist/design.js

@@ -1,27 +0,0 @@
-export function defineDesignLanguage(adapter) {
-    return adapter;
-}
-/** Maps semantic tokens to the stable CSS custom properties understood by Omni. */
-export function designTokenProperties(tokens) {
-    return {
-        "--omni-accent": tokens.accent,
-        "--omni-accent-text": tokens.accentText,
-        "--omni-surface": tokens.surface,
-        "--omni-surface-muted": tokens.surfaceMuted,
-        "--omni-selected": tokens.selected,
-        "--omni-text": tokens.text,
-        "--omni-muted-text": tokens.mutedText,
-        "--omni-border": tokens.border,
-        "--omni-info": tokens.info,
-        "--omni-success": tokens.success,
-        "--omni-warning": tokens.warning,
-        "--omni-danger": tokens.danger,
-        "--omni-radius": tokens.radius,
-        "--omni-radius-large": tokens.radiusLarge,
-        "--omni-shadow": tokens.shadow,
-        "--omni-control-font": tokens.controlFont,
-        "--omni-control-weight": tokens.controlWeight,
-        "--omni-control-tracking": tokens.controlTracking,
-        "--omni-control-height": tokens.controlHeight,
-    };
-}