@xema/omni-protocol 0.1.109 → 0.1.111

package/dist/testing.js

@@ -434,6 +434,16 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                         message: `a task was offered with ${stream.openCount()} already open against a stated capacity of ${capacityStated}` });
                 }
             }
+            // The agent's own queue lives within capacity: told count 0, the provider clears the ask and
+            // lets the lined-up call go, so an entry published after that is a promise it cannot keep.
+            if (capacityStated === 0 && isRecord(envelope?.event)) {
+                if (envelope.event.type === "next-call" && envelope.event.nextCall !== undefined) {
+                    violations.push({ rule: "stream.nextCall.stopped", path: "event.nextCall", message: "an ask for the next call was published after the host stated count 0: the agent's capacity is elsewhere, and the ask is cleared with it" });
+                }
+                if (envelope.event.type === "lined-up" && envelope.event.linedUp !== undefined) {
+                    violations.push({ rule: "stream.linedUp.stopped", path: "event.linedUp", message: "a call was lined up after the host stated count 0: the agent's capacity is elsewhere, and the call goes back to the queue for anyone" });
+                }
+            }
             // A re-delivered envelope is harmless and applied once; the same id carrying a different
             // payload is a reused id, which no dedupe can make harmless, and is named.
             if (typeof envelope?.id === "string") {
@@ -505,8 +515,12 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                 unsubscribeAuthentication = session.subscribe(onAuthenticationState);
                 unsubscribe = second.subscribe(onEnvelope);
                 clientLive = true;
+                // The second client has been told nothing: the switch is per connection, and the reader
+                // holds its connect snapshot to no team until it is sent again, after its capacity.
+                leadFeaturesOn = false;
                 const restated = await second.setCapacity({ count: capacityStated ?? 1 });
                 violations.push(...validateResult(restated, "setCapacity", "drive.reload.setCapacity"));
+                await switchOnLeadFeatures(second, "drive.reload");
             },
         };
         // Every snapshot the run reads, the connect snapshot and a reloaded client's, is read the same
@@ -609,40 +623,44 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         }
         // The provider assumes nothing of the team feature: the application says on every connect,
         // and once it has said on, the whole team is owed, once. Before that nothing of the team
-        // reaches the lead, which the reader held the connect snapshot to.
-        if (current().capabilities.lead === true && typeof live.executeTeam === "function") {
+        // reaches the lead, which the reader held the connect snapshot to. A reloaded client is a
+        // connect too: it is told again, after its capacity, and held the same way.
+        const switchOnLeadFeatures = async (on, at) => {
+            if (current().capabilities.lead !== true || typeof on.executeTeam !== "function")
+                return;
             const from = events.length;
             let switched;
             // On from the moment the application says so: the provider may answer with the team at once.
             leadFeaturesOn = true;
             try {
-                switched = await live.executeTeam({ command: { type: "lead-features", enabled: true } });
+                switched = await on.executeTeam({ command: { type: "lead-features", enabled: true } });
             }
             catch (error) {
                 leadFeaturesOn = false;
-                violations.push({ rule: "team.switch.rejected", path: "connection.executeTeam", message: `lead-features on was rejected: ${String(error)}` });
+                violations.push({ rule: "team.switch.rejected", path: `${at}.executeTeam`, message: `lead-features on was rejected: ${String(error)}` });
             }
-            if (switched !== undefined) {
-                violations.push(...validateResult(switched, "executeTeam", "connection.executeTeam"));
-                ruleEvaluated("team.required");
-                const ms = options.driveTimeoutMs ?? 5000;
-                const isBaseline = (envelope) => isRecord(envelope?.event) && envelope.event.type === "team-updated";
-                const baseline = events.slice(from).some(isBaseline) || await new Promise(resolve => {
-                    const timer = setTimeout(() => { waiters.delete(waiter); resolve(false); }, ms);
-                    const waiter = (envelope) => {
-                        if (!isBaseline(envelope))
-                            return;
-                        clearTimeout(timer);
-                        waiters.delete(waiter);
-                        resolve(true);
-                    };
-                    waiters.add(waiter);
-                });
-                if (!baseline)
-                    violations.push({ rule: "team.required", path: "event.team",
-                        message: `the application switched the team feature on and no team-updated followed within ${ms}ms: the whole team is owed once it is on, members: [] when nobody is in it` });
-            }
-        }
+            if (switched === undefined)
+                return;
+            violations.push(...validateResult(switched, "executeTeam", `${at}.executeTeam`));
+            ruleEvaluated("team.required");
+            const ms = options.driveTimeoutMs ?? 5000;
+            const isBaseline = (envelope) => isRecord(envelope?.event) && envelope.event.type === "team-updated";
+            const baseline = events.slice(from).some(isBaseline) || await new Promise(resolve => {
+                const timer = setTimeout(() => { waiters.delete(waiter); resolve(false); }, ms);
+                const waiter = (envelope) => {
+                    if (!isBaseline(envelope))
+                        return;
+                    clearTimeout(timer);
+                    waiters.delete(waiter);
+                    resolve(true);
+                };
+                waiters.add(waiter);
+            });
+            if (!baseline)
+                violations.push({ rule: "team.required", path: "event.team",
+                    message: `the application switched the team feature on and no team-updated followed within ${ms}ms: the whole team is owed once it is on, members: [] when nobody is in it` });
+        };
+        await switchOnLeadFeatures(live, "connection");
         if (options.drive) {
             const localAudio = isRecord(first) && isRecord(first.audio) && isRecord(first.audio.input) && first.audio.input.status === "available"
                 ? first.audio.input.localAudio : undefined;

package/dist/validation.js

@@ -1795,14 +1795,21 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
         validateShiftInto(snapshot.shift, `${path}.shift`, into, "shift");
     // The phone as the platform sees it: owed by a provider that declares it can, and by nobody else.
     const seesPhone = isPlainObject(manifest) && manifest.phoneStatus === true;
-    // The agent's own queue: an ask needs an assignment at work to be next after, and one call at most waits.
+    // The agent's own queue: the ask and the lined-up call need an assignment at work to be next
+    // after, and neither stands beside a break the agent asked for or was put on -- the break wins.
+    const atWork = Array.isArray(snapshot.tasks) && snapshot.tasks.some((task) => isPlainObject(task) && (task.phase === "in-progress" || task.phase === "paused" || task.phase === "completing"));
+    const breakStatus = isPlainObject(snapshot.break) ? snapshot.break.status : undefined;
+    const breakStands = typeof breakStatus === "string" && breakStatus !== "not-requested";
     if (snapshot.nextCall !== undefined) {
         validateNextCallInto(snapshot.nextCall, `${path}.nextCall`, into);
-        const atWork = Array.isArray(snapshot.tasks) && snapshot.tasks.some((task) => isPlainObject(task) && (task.phase === "in-progress" || task.phase === "paused" || task.phase === "completing"));
         into.require(atWork, "snapshot.nextCall.idle", `${path}.nextCall`, "an ask for the next call stands only while an assignment is at work to be next after: the provider clears it when that assignment ends");
+        into.require(!breakStands, "snapshot.nextCall.break", `${path}.nextCall`, `an ask for the next call does not stand beside a break that is ${String(breakStatus)}: the break wins, and the provider clears the ask`);
     }
-    if (snapshot.linedUp !== undefined)
+    if (snapshot.linedUp !== undefined) {
         validateLinedUpInto(snapshot.linedUp, `${path}.linedUp`, into, levels);
+        into.require(atWork, "snapshot.linedUp.idle", `${path}.linedUp`, "a call is lined up for an agent with an assignment at work; with nothing at work it is an offer, and travels as task-offered");
+        into.require(!breakStands, "snapshot.linedUp.break", `${path}.linedUp`, `a lined-up call does not stand beside a break that is ${String(breakStatus)}: the break wins, and the call goes back to the queue for anyone`);
+    }
     if (seesPhone && snapshot.phone === undefined) {
         into.add("snapshot.phone.required", `${path}.phone`, "the manifest declares phoneStatus, so every snapshot carries the phone as the platform sees it");
     }

package/guide/breaks.md

@@ -253,4 +253,6 @@ it: the ceiling binds assignment, not the agent's own hand.
 **Capacity is not the agent's readiness.** It is the desk's division of one person across
 providers, a ceiling on assignments at once, and it says nothing about the moment. An agent who
 is about to finish a call and wants the next one lined up has a different thing to say, and says
-it as **The agent's own queue** in `guide/queue.md` sets out; the ceiling stands unchanged while they do.
+it as **The agent's own queue** in `guide/queue.md` sets out; the ceiling stands unchanged while they do,
+and the queue lives within it: `count: 0` clears the ask and lets a lined-up call go, and a break
+in flight or in effect does the same, since the break wins.

package/guide/queue.md

@@ -44,6 +44,24 @@ its own when that assignment ends, when a call is lined up to meet it, and when
 withdraws it with `cancelNextCall()`. The desk never keeps it past any of those. `requested` says
 the provider holds the ask, not that a call will come: a queue may be empty.
 
+**The queue lives within capacity, and never beside a break.** The ask and the lined-up call are
+promises to assign, and a promise the provider can no longer keep goes:
+
+- **Told `count: 0`**, host-stopped, the provider assigns nothing, so it clears the ask and lets the
+  lined-up call go back to the queue for anyone; an entry published after that is refused
+  (`stream.nextCall.stopped`, `stream.linedUp.stopped`). The queue is per provider, as the ask
+  was made on that provider's call, and the desk's division of capacity is what it was.
+- **A break wins.** An agent who has asked for a break, been granted one starting after this
+  task, or been put on one has said the opposite of "line up my next call", and the two never
+  stand together: while a break is in flight or in effect -- any status but `not-requested` --
+  `requestNextCall()` is refused with `omni.unavailable`, and a break arriving after a
+  call was lined up drops the call, the caller going back to the queue for anyone
+  (`snapshot.nextCall.break`, `snapshot.linedUp.break`). The desk shows Next call or the break
+  controls, never both.
+- **A lined-up call needs an agent at work** as the ask does: a call lined up for an agent with
+  nothing at work is an offer that has not been made, and travels as `task-offered`
+  (`snapshot.linedUp.idle`). The repeat caller for an idle agent is an ordinary offer.
+
 **The lined-up call is not a task, and rides no task event.** Until the offer there is no
 assignment and nothing to accept, so it has no phase, no capabilities and no history, and it
 rings nothing: the caller is still in the platform's queue, the phone has no channel for it, and

package/package.json

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