@xema/omni-protocol 0.1.102 → 0.1.104

package/dist/index.d.ts

@@ -153,6 +153,12 @@ export interface Manifest<C extends Channel = Channel> {
     authenticationMethods: AuthenticationMethod[];
     idleCapabilities?: IdleCapabilities<C>;
     /** Optional provider-clock sampling through Connection.checkTime; absent means unsupported. */
+    /**
+     * Implements `checkTime`, and states `providerTime` on every snapshot. Required of a provider
+     * that publishes an instant the desk renders as a running duration -- a member's `since`, a
+     * lead's `listening.since`, an `onCall.since`, a shift's `signedInAt` -- so every screen counts
+     * from the provider's clock and two screens differ by their delay alone.
+     */
     timeCheck?: true;
     /** Provider uses its own timestamps for final records; host timestamps are advisory. Omission makes no trust promise. */
     timestampAuthority?: "provider";
@@ -179,12 +185,12 @@ export interface Manifest<C extends Channel = Channel> {
      */
     runningStepReports?: true;
     /**
-     * How long after an applied completion -- `complete`, or a lead's `take-over-call` -- the provider's
-     * `task-ended` is owed, in milliseconds. `applied` says the provider has completed the task;
-     * the ending follows within this, or the host resyncs and shows the task as unsettled. Stated
-     * per provider, since platforms settle at different speeds.
+     * How long after `applied` the wire shows what the provider did, in milliseconds: the
+     * `task-ended` after a `complete` or a lead's `take-over-call`, the `calendar-updated` after a
+     * `schedule`. Past it the host resyncs and shows the thing as unsettled. Stated per provider,
+     * since platforms settle at different speeds.
      */
-    completionSettleMs: number;
+    settleMs: number;
 }
 export interface SecretStore {
     get(key: string): Promise<string | undefined>;
@@ -666,8 +672,10 @@ export type TaskCapabilities<C extends Channel = Channel> = C extends "voice" ?
 } : C extends "chat" ? SharedTaskCapabilities & {
     decline?: Lockable<true>;
     hold?: Lockable<true>;
+    schedule?: Lockable<true>;
 } : SharedTaskCapabilities & {
     decline?: Lockable<true>;
+    schedule?: Lockable<true>;
 };
 /**
  * How a reusing browser's session is keyed.
@@ -948,6 +956,13 @@ export type Task<C extends Channel = Channel> = {
      * Omni said not, and absent past `pending`.
      */
     acceptance?: AcceptanceMode;
+    /**
+     * In `pending` only: how long the offer has left, in whole seconds from this publication,
+     * restated on every publication that carries it so a reconnect snapshot says what is actually
+     * left. Absent, the offer stands until the provider says otherwise. Runs out: the provider ends
+     * the offer `expired` naming `pending`.
+     */
+    expiresInSeconds?: DurationSeconds;
     /**
      * In `preview` only, and together: how long the preparation has left, in whole seconds from
      * this publication -- restated on every publication that carries it, so a resync starts the
@@ -999,18 +1014,18 @@ export type TaskOutcome = {
     by: "agent" | "provider" | "party";
     reason?: string;
 }
-/** Only the phases in which somebody is still being waited on can expire; an offer whose `expiresInSeconds` runs out names `pending`. */
+/** Only the phases in which somebody is still being waited on can expire: an offer whose `expiresInSeconds` runs out names `pending`, accepted work the platform gave up on names `confirmed`. A preview never lapses: withdrawn, it is `cancelled` by the provider. */
  | {
     type: "expired";
-    phase: "pending" | "confirmed" | "preview";
+    phase: "pending" | "confirmed";
 } | {
     type: "failed";
     failure: ProtocolFailure;
 };
 export declare const TASK_COMMAND_NAMES: {
     readonly voice: readonly ["answer", "decline", "dial", "hold", "resume", "end-call", "terminate-call", "connect-back", "lead-assist", "conference", "recording", "schedule", "complete"];
-    readonly chat: readonly ["accept", "decline", "pause", "resume", "complete"];
-    readonly email: readonly ["accept", "decline", "complete"];
+    readonly chat: readonly ["accept", "decline", "pause", "resume", "schedule", "complete"];
+    readonly email: readonly ["accept", "decline", "schedule", "complete"];
 };
 export type TaskCommandName<C extends keyof typeof TASK_COMMAND_NAMES> = (typeof TASK_COMMAND_NAMES)[C][number];
 export interface OutcomePayload {
@@ -1043,17 +1058,7 @@ export type VoiceTaskCommand = {
  | {
     type: "connect-back";
     dialId: DialId;
-}
-/**
- * Put a time on the calendar for this party: a follow-up promised on the call. Gated by
- * `schedule`, issuable in `in-progress`, `paused` or `completing`; the activity arrives on
- * `calendar-updated`, which is the provider's word that it stands.
- */
- | {
-    type: "schedule";
-    at: IsoTimestamp;
-    note?: string;
-}
+} | ScheduleCommand
 /** Ask a lead to join, with a note. Gated by `leadAssist`. */
  | {
     type: "lead-assist";
@@ -1093,6 +1098,18 @@ export type VoiceTaskCommand = {
 }) | ({
     type: "complete";
 } & OutcomePayload);
+/**
+ * Put a time on the calendar for this party: a follow-up promised on the call or in the
+ * conversation, or written up in wrap. Gated by `schedule` on any channel, issuable in
+ * `in-progress`, `paused` or `completing`, under a manifest that declares `calendar` for it to
+ * land on; `applied` says it is on the calendar, and the `calendar-updated` that shows it follows
+ * within the manifest's `settleMs`.
+ */
+export type ScheduleCommand = {
+    type: "schedule";
+    at: IsoTimestamp;
+    note?: string;
+};
 export type ChatTaskCommand = {
     type: "accept";
 } | {
@@ -1101,14 +1118,14 @@ export type ChatTaskCommand = {
     type: "pause";
 } | {
     type: "resume";
-} | ({
+} | ScheduleCommand | ({
     type: "complete";
 } & OutcomePayload);
 export type EmailTaskCommand = {
     type: "accept";
 } | {
     type: "decline";
-} | ({
+} | ScheduleCommand | ({
     type: "complete";
 } & OutcomePayload);
 export interface CustomTaskCommand {
@@ -1187,14 +1204,21 @@ export interface BreakRequest {
     reasonId?: string;
 }
 /**
- * A break forced on the agent; the agent must explicitly resume when ready. `by` is the lead who
- * forced it, or `provider` where the platform itself did, on its own rule or a schedule: the agent
- * sees who, and a person is named only when there is one.
+ * A break forced on the agent; the agent must explicitly resume when ready. A lead's `force-break`
+ * is a command to the provider, which forces the break: `by` names the lead who asked it to, or
+ * `provider` where the platform itself did, on its own rule or a schedule. The agent sees who, a
+ * person is named only when there is one, and a break the platform imposed is the platform's to
+ * lift: a lead's `end-forced-break` on it fails with `omni.break-forced-by-provider`.
  */
 export type ForcedBreak = {
     by: UserId | "provider";
-    /** Optional expected time on break, in milliseconds from actual start. Advisory only. */
-    expectedDurationMs?: number;
+    /**
+     * How long the break is expected to run yet, in whole seconds from this publication, restated
+     * on every publication that carries it so every screen counts down the same number from
+     * receipt. Advisory only: nothing ends the break but the agent. Absent once it has run out, or
+     * where none was expected.
+     */
+    expectedEndsInSeconds?: DurationSeconds;
 };
 export interface BreakState {
     status: BreakStatus;
@@ -1251,10 +1275,10 @@ export interface TeamMember {
     break?: Extract<BreakStatus, "awaiting-approval" | "granted" | "starting-after-task">;
     /** The member's open tasks, trimmed, kept current by the provider; `[]` when they hold none, omitted only where the provider cannot see them. */
     tasks?: MemberTask[];
-    /** Present while this lead is on the member's call, listening, coaching or joined; absent otherwise. */
-    listening?: MemberListening;
-    /** The member's own history for the day: sign-in, sign-out, breaks and productivity. Omitted where the provider cannot say. */
-    shift?: MemberShift;
+    /** Every lead on this member's call, listening, coaching or joined, published to every lead alike; absent while none is. */
+    listening?: MemberListening[];
+    /** The member's own history for the day: sign-in, sign-out, breaks and productivity, the same numbers the member's own snapshot carries. Omitted where the provider cannot say. */
+    shift?: Shift;
     /** The member's standing ask for a lead on one of their calls; absent when they are not asking. */
     request?: MemberRequest;
 }
@@ -1297,11 +1321,14 @@ export type MemberTask<C extends Channel = Channel> = {
     audio?: never;
 });
 /**
- * The lead on this member's call: which of the member's calls, in the mode they are heard, since
- * when. Its appearance on the team member list is the provider's word that the lead's audio is up,
- * and the application opens `openAudio` on the assignment named; its disappearance closes it.
+ * A lead on this member's call: who, which of the member's calls, in the mode they are heard,
+ * since when. Every lead sees every entry; the application opens `openAudio` on the entry whose
+ * `leadId` is the signed-in lead, and closes it when that entry goes. A lead who is heard --
+ * `join-call` -- is also on the task's `onCall` as an `agent`; `listen` and `coach` leave no trace
+ * on the member's task.
  */
 export interface MemberListening {
+    leadId: UserId;
     assignmentId: AssignmentId;
     mode: ListeningMode;
     since: IsoTimestamp;
@@ -1313,15 +1340,18 @@ export interface ShiftEvent {
     kind: ShiftEventKind;
 }
 /**
- * The member's own history for the day, about the person rather than any one call: when they
+ * An agent's own history for the day, about the person rather than any one call: when they
  * signed in and out, today's totals as the provider counts them, each present only when the
- * provider knows it, and the day's sign-in, sign-out and break events, oldest first.
+ * provider knows it, and the day's sign-in, sign-out and break events, oldest first. Published
+ * to the agent on their snapshot and on `shift-updated`, and to their lead on the team member
+ * list: the same numbers from the same count.
  */
-export interface MemberShift {
+export interface Shift {
     signedInAt: IsoTimestamp;
     signedOutAt?: IsoTimestamp;
     talkSeconds?: DurationSeconds;
     holdSeconds?: DurationSeconds;
+    /** Every break the member was on today, including time held elsewhere for a break another provider forced: the provider counts it under a break kind of its own. */
     breakSeconds?: DurationSeconds;
     tasksHandled?: number;
     events?: ShiftEvent[];
@@ -1536,6 +1566,12 @@ export type PreferenceResult = {
 export interface Snapshot<C extends Channel = Channel> {
     transport: TransportStatus;
     loginId: string;
+    /**
+     * The provider's own instant of this read, required of a provider that declares `timeCheck`:
+     * every duration the desk renders off the active call is counted from the provider's clock, and
+     * this sample saves a `checkTime` for it. Every envelope's `occurredAt` is a sample too.
+     */
+    providerTime?: IsoTimestamp;
     break: BreakState;
     /** Every task currently owned by this agent for this provider. */
     tasks: Task<C>[];
@@ -1543,6 +1579,8 @@ export interface Snapshot<C extends Channel = Channel> {
     taskCount: number;
     contacts?: Contact[];
     calendar?: ScheduledActivity[];
+    /** The agent's own day so far, as the provider counts it; replaced whole by `shift-updated`. Omitted where the provider cannot say. */
+    shift?: Shift;
     team?: TeamMembers;
 }
 /**
@@ -1590,8 +1628,6 @@ export type ProviderEvent<C extends Channel = Channel> = {
 } | {
     type: "task-offered";
     task: Task<C>;
-    /** How long the agent has to answer, in whole seconds from this event; the offer expires when it runs out. Absent, it stands until the provider says otherwise. */
-    expiresInSeconds?: DurationSeconds;
 } | {
     type: "task-updated";
     task: Task<C>;
@@ -1656,6 +1692,11 @@ export type ProviderEvent<C extends Channel = Channel> = {
 } | {
     type: "calendar-updated";
     calendar: ScheduledActivity[];
+}
+/** The agent's own day, whole, whenever a total moves: a task ended, a break ended. */
+ | {
+    type: "shift-updated";
+    shift: Shift;
 };
 /**
  * The `Provider` prefix survives here for a mechanical reason rather than a naming one: `Event`
@@ -1669,7 +1710,7 @@ export interface ProviderEventEnvelope<C extends Channel = Channel> {
     occurredAt: IsoTimestamp;
     event: ProviderEvent<C>;
 }
-export declare const OMNI_FAILURE_CODES: readonly ["omni.not-authenticated", "omni.capability-not-enabled", "omni.assignment-not-found", "omni.destination-not-permitted", "omni.phone-not-permitted", "omni.rate-limited", "omni.unavailable", "omni.break-already-committed", "omni.recording-unsettled"];
+export declare const OMNI_FAILURE_CODES: readonly ["omni.not-authenticated", "omni.capability-not-enabled", "omni.assignment-not-found", "omni.destination-not-permitted", "omni.phone-not-permitted", "omni.rate-limited", "omni.unavailable", "omni.break-already-committed", "omni.recording-unsettled", "omni.break-forced-by-provider"];
 export type OmniFailureCode = (typeof OMNI_FAILURE_CODES)[number];
 /**
  * What the host refused, told to the adapter that published it: a snapshot the host would not

package/dist/index.js

@@ -78,8 +78,8 @@ export const CAPABILITY_SOURCES = ["queue", "nobody", "not-yet-read"];
 export const TASK_COMMAND_NAMES = {
     voice: ["answer", "decline", "dial", "hold", "resume", "end-call", "terminate-call",
         "connect-back", "lead-assist", "conference", "recording", "schedule", "complete"],
-    chat: ["accept", "decline", "pause", "resume", "complete"],
-    email: ["accept", "decline", "complete"],
+    chat: ["accept", "decline", "pause", "resume", "schedule", "complete"],
+    email: ["accept", "decline", "schedule", "complete"],
 };
 /** The dial a command places, by the host's identity for it; `undefined` for a command that dials nothing. */
 export function commandDialId(command) {
@@ -105,6 +105,8 @@ export const OMNI_FAILURE_CODES = [
     "omni.break-already-committed",
     /** A recording command the provider could not settle either way: no start, stop, pause or resume it can vouch for. */
     "omni.recording-unsettled",
+    /** A lead asked to lift a break the platform itself imposed; the platform lifts its own. */
+    "omni.break-forced-by-provider",
 ];
 /**
  * Preserves the adapter's inferred concrete type while checking it implements `Adapter`.

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 team member list, each
  * declared contribution, and each event type.
  */
-declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.history", "task.onCall", "task.leadAssist", "task.takenOver", "task.audio", "task.acceptance", "task.outcomes", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.forced", "team.members", "team.request", "team.tasks", "team.listening", "team.shift", "contacts", "calendar", "team.policies"];
+declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.history", "task.onCall", "task.leadAssist", "task.takenOver", "task.audio", "task.acceptance", "task.outcomes", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.forced", "team.members", "team.request", "team.tasks", "team.listening", "team.shift", "shift", "contacts", "calendar", "team.policies"];
 export type ContractSubject = (typeof STATE_SUBJECTS)[number] | `event.${ProviderEvent["type"]}`;
 export interface AdapterContractResult {
     events: ProviderEventEnvelope[];
@@ -249,6 +249,13 @@ export interface BreakCandidate {
     /** Whether the agent can currently receive work from it: connected, with a capacity stated. */
     holdsCapacity: boolean;
 }
+/**
+ * A break one provider forces stops the agent everywhere: the host states a capacity of zero on
+ * every other usable provider holding capacity -- taken, never refused, and nothing the agent can
+ * cancel -- and on the forcing provider states nothing, since the break itself holds the agent
+ * there. A provider whose login is not usable is left alone, as a break attempt leaves it.
+ */
+export declare function assertForcedBreakStopsTheRest(forcedOn: string, candidates: readonly BreakCandidate[], stopped: readonly string[]): void;
 /**
  * A break attempt asks every connected provider from which the agent can currently receive work.
  * A provider whose login is not usable -- `expired` above all -- is not asked, whatever else is

package/dist/testing.js

@@ -28,6 +28,7 @@ const STATE_SUBJECTS = [
     "team.tasks",
     "team.listening",
     "team.shift",
+    "shift",
     "contacts",
     "calendar",
     "team.policies",
@@ -38,7 +39,7 @@ const EVENT_TYPES = {
     snapshot: true, "transport-status": true, "break-state": true, "task-offered": true, "task-updated": true,
     "task-audio-started": true, "task-audio-ended": true, "task-ended": true, "dial-outcome": true, announcement: true, "queue-summary": true, diagnostic: true,
     "team-updated": true, "team-member-updated": true, "team-member-removed": true, "team-policies-updated": true,
-    "contacts-updated": true, "calendar-updated": true,
+    "contacts-updated": true, "calendar-updated": true, "shift-updated": true,
 };
 const CONTRACT_SUBJECTS = [
     ...STATE_SUBJECTS,
@@ -94,7 +95,7 @@ function observeMember(member, seen) {
         return;
     if (some(member.tasks))
         seen.add("team.tasks");
-    if (member.listening !== undefined)
+    if (some(member.listening))
         seen.add("team.listening");
     if (member.shift !== undefined)
         seen.add("team.shift");
@@ -126,6 +127,8 @@ function observeSnapshot(value, seen) {
         seen.add("contacts");
     if (some(value.calendar))
         seen.add("calendar");
+    if (value.shift !== undefined)
+        seen.add("shift");
 }
 function observeEvent(envelope, seen) {
     const event = isRecord(envelope) ? envelope.event : undefined;
@@ -162,6 +165,9 @@ function observeEvent(envelope, seen) {
             if (some(event.calendar))
                 seen.add("calendar");
             break;
+        case "shift-updated":
+            seen.add("shift");
+            break;
         default: break;
     }
 }
@@ -719,9 +725,14 @@ function userIdsIn(snapshot) {
         add(snapshot?.break?.forced?.by);
     const team = snapshot?.team;
     if (isRecord(team)) {
-        for (const member of Array.isArray(team.members) ? team.members : [])
-            if (isRecord(member))
-                add(member.id);
+        for (const member of Array.isArray(team.members) ? team.members : []) {
+            if (!isRecord(member))
+                continue;
+            add(member.id);
+            for (const entry of Array.isArray(member.listening) ? member.listening : [])
+                if (isRecord(entry))
+                    add(entry.leadId);
+        }
     }
     for (const task of Array.isArray(snapshot?.tasks) ? snapshot.tasks : []) {
         const t = task;
@@ -1063,7 +1074,7 @@ const REACHABLE_PHASES = {
 export const SUPERSEDED_BY_A_SNAPSHOT = new Set([
     "snapshot", "transport-status", "break-state", "task-offered", "task-updated", "task-ended",
     "task-audio-started", "task-audio-ended", "team-updated", "team-member-updated", "team-member-removed", "team-policies-updated",
-    "contacts-updated", "calendar-updated",
+    "contacts-updated", "calendar-updated", "shift-updated",
 ]);
 export class TaskStream {
     tasks = new Map();
@@ -1626,6 +1637,7 @@ async function driveOneCall(drive) {
         const own = validateTaskCommand(command, latestTask(), `drive.command.${String(command.type)}`, {
             levels: effectiveLevels(drive.manifest.orgLevels).map(level => level.id),
             dialOutcomesDeclared: drive.manifest.dialOutcomes !== undefined,
+            calendarDeclared: drive.manifest.idleCapabilities?.calendar === true,
             autoAcceptTasks: drive.context.autoAcceptTasks,
         });
         found.push(...own);
@@ -1798,6 +1810,38 @@ async function driveOneCall(drive) {
             }
         }
     }
+    // 4a. Schedule a follow-up, where the task offers it: applied says it is on the calendar, and the
+    // calendar-updated that shows it is owed within the manifest's bound. The time is the provider's
+    // own: a day after the instant it published the offer, so no clock of the runner's is read.
+    if (latestTask().phase === "in-progress" && offers("schedule")) {
+        const publishedAt = drive.events.slice(0, cursor).reverse().find(envelope => {
+            const event = envelope.event;
+            return (event.type === "task-offered" || event.type === "task-updated") && isTask(event.task) && event.task.assignmentId === taskId;
+        })?.occurredAt;
+        const at = new Date(Date.parse(String(publishedAt ?? "2026-01-01T00:00:00Z")) + 24 * 60 * 60 * 1000).toISOString();
+        if (await send({ type: "schedule", at, note: "Follow-up promised on the call" }) !== undefined) {
+            ruleEvaluated("drive.schedule.unsettled");
+            const settle = Number(drive.manifest.settleMs);
+            const carries = (calendar) => Array.isArray(calendar) && calendar.some(activity => isRecord(activity) && activity.startsAt === at);
+            let unsettled = false;
+            const shown = await waitFor("a calendar-updated carrying the follow-up", envelope => {
+                const event = envelope.event;
+                return event.type === "calendar-updated" && carries(event.calendar) ? event : undefined;
+            }, cursor, { ms: settle, onExpiry: () => { unsettled = true; } });
+            if (shown === undefined && unsettled) {
+                let resync;
+                try {
+                    resync = await drive.connection.snapshot();
+                }
+                catch (error) {
+                    refuse("drive.command.rejected", "drive.schedule", `snapshot() after an unsettled schedule rejected: ${String(error)}`);
+                }
+                if (!(isRecord(resync) && carries(resync.calendar))) {
+                    refuse("drive.schedule.unsettled", "drive.schedule", `schedule was applied and ${settle}ms later no calendar-updated carries a follow-up at ${at}, and a snapshot does not either: applied says the follow-up is on the calendar, and it is not`);
+                }
+            }
+        }
+    }
     // 5. End the call, where the agent may -- with the microphone muted, as agents do. The leg left
     // open at audio end is the provider's to close, since the provider knows the instant the audio
     // ended; the host's own closing report can only follow what it hears, is answered recorded, and
@@ -1853,7 +1897,7 @@ async function driveOneCall(drive) {
     // provider. A conversation has no audio to end and no completing phase to wait for: a chat or an
     // email, and a voice task offering no end-call, is completed from where it stands.
     const completable = latestTask().phase === "completing" || latestTask().phase === "in-progress" || latestTask().phase === "paused";
-    if (latestTask().wrapAllowance !== 0 && completable) {
+    if (!(latestTask().completionMode === "provider-automatic" && latestTask().wrapAllowance === 0) && completable) {
         const command = { type: "complete" };
         const outcomes = isRecord(latestTask().capabilities) ? latestTask().capabilities.outcomes : undefined;
         if (isRecord(outcomes) && outcomes.required === true && Array.isArray(outcomes.codes) && isRecord(outcomes.codes[0])) {
@@ -1864,7 +1908,7 @@ async function driveOneCall(drive) {
             // the manifest stated. Past it the host resyncs: a snapshot still carrying the task is a task
             // held open by a provider that said it was done, and the desk shows it as unsettled.
             ruleEvaluated("drive.completion.unsettled");
-            const settle = Number(drive.manifest.completionSettleMs);
+            const settle = Number(drive.manifest.settleMs);
             let unsettled = false;
             const end = await ended({ ms: settle, onExpiry: () => { unsettled = true; } });
             if (end !== undefined)
@@ -2083,6 +2127,35 @@ export function stillHost(report = { online: true }, guarantees = {}, mute) {
     return { guarantees, ...(mute === undefined ? {} : { mute }), report: () => report, subscribe: () => () => undefined };
 }
 const usableLogin = (status) => status === "authenticated" || status === "refreshing";
+/**
+ * A break one provider forces stops the agent everywhere: the host states a capacity of zero on
+ * every other usable provider holding capacity -- taken, never refused, and nothing the agent can
+ * cancel -- and on the forcing provider states nothing, since the break itself holds the agent
+ * there. A provider whose login is not usable is left alone, as a break attempt leaves it.
+ */
+export function assertForcedBreakStopsTheRest(forcedOn, candidates, stopped) {
+    if (!candidates.some(candidate => candidate.id === forcedOn))
+        throw new Error(`${forcedOn} is not a provider the host knows`);
+    const chosen = new Set(stopped);
+    for (const id of stopped) {
+        if (!candidates.some(candidate => candidate.id === id))
+            throw new Error(`${id} is not a provider the host knows`);
+    }
+    if (chosen.has(forcedOn))
+        throw new Error(`${forcedOn} forced the break and holds the agent itself: its capacity is not restated`);
+    for (const candidate of candidates) {
+        if (candidate.id === forcedOn)
+            continue;
+        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 stopped: capacity 0 stated`);
+        }
+        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 stopped: there is nothing to stop`);
+        }
+    }
+}
 /**
  * A break attempt asks every connected provider from which the agent can currently receive work.
  * A provider whose login is not usable -- `expired` above all -- is not asked, whatever else is

package/dist/validation.d.ts

@@ -39,6 +39,8 @@ export interface TaskValidationContext {
     autoAcceptTasks?: boolean;
     /** Whether the manifest declares `dialOutcomes`. A task that may dial needs it to; absent, the question is not asked. */
     dialOutcomesDeclared?: boolean;
+    /** Whether the manifest declares the `calendar` idle capability. A task that may schedule needs it to; absent, the question is not asked. */
+    calendarDeclared?: boolean;
     /**
      * The values the queue locked on this login's tasks -- a party's number or email -- as whoever
      * runs the validator knows them. Where a task's party stands locked, no other field of it may