@xema/omni-protocol 0.1.74 → 0.1.76

package/dist/index.d.ts

@@ -904,11 +904,14 @@ export type TaskOutcome = {
 } | {
     type: "transferred";
     destinationId?: string;
-} | {
+}
+/** Who called the work off: the agent declining, the provider withdrawing or re-routing, the party abandoning. */
+ | {
     type: "cancelled";
+    by: "agent" | "provider" | "party";
     reason?: string;
 }
-/** Only the phases in which somebody is still being waited on can expire. */
+/** Only the phases in which somebody is still being waited on can expire; an offer that lapses at `allocationExpiresAt` names `pending`. */
  | {
     type: "expired";
     phase: "pending" | "confirmed" | "preview";

package/dist/testing.d.ts

@@ -57,6 +57,13 @@ export interface ExerciseAdapterOptions {
      * memory has nothing, and is named. Without it the store is required and never read.
      */
     rebuild?: () => Adapter<Channel>;
+    /**
+     * The values the queue locks on this login's tasks -- a party's number or email -- as the run's
+     * author knows them. A task whose party stands locked may carry none of them anywhere else
+     * (`task.locked.leak`). Required once any task locks a party field: a run that cannot ask the
+     * question is not a pass, and says so by throwing rather than passing.
+     */
+    lockedValues?: readonly string[];
 }
 /**
  * Adapter conformance exercise: validates the manifest, opens an authenticated session,

package/dist/testing.js

@@ -163,6 +163,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
     const breaks = new BreakStream();
     let seeded = false;
     const duringRead = [];
+    let lockedPartySeen = false;
     const storedSecrets = new Map();
     const authenticationSecrets = {
         get: async (key) => storedSecrets.get(key),
@@ -204,6 +205,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             capabilities: current().capabilities,
             loginId: context.loginId,
             autoAcceptTasks: context.autoAcceptTasks,
+            locked: options.lockedValues,
         });
         // The optional methods are optional only until something declares a need for them. Each
         // check pairs a method with the declaration that requires it, as the guide's Live-connection
@@ -341,6 +343,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                     message: `the provider reported a diagnostic: expected ${String(envelope.event.expected)}; observed ${String(envelope.event.observed)}` });
             }
             violations.push(...undeterminedTasks(eventTasks(envelope), "event"));
+            lockedPartySeen ||= eventTasks(envelope).some(locksParty);
             if (eventNamesUsers(envelope))
                 requireMethod(live, "describeUsers", "an event publishes a UserId");
             // Work is pulled, never pushed: an offer before the host stated capacity is an allocation
@@ -427,6 +430,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                 tellRefused({ artefact: "snapshot", violations: broken });
         }
         violations.push(...undeterminedTasks(Array.isArray(snapshot?.tasks) ? snapshot.tasks : [], "snapshot.tasks"));
+        lockedPartySeen ||= (Array.isArray(snapshot?.tasks) ? snapshot.tasks : []).some(locksParty);
         stream.seed(snapshot);
         breaks.seed(snapshot);
         seeded = true;
@@ -587,6 +591,12 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             message: "an unsubscribe, disconnect(), or close() threw during shutdown",
         });
     }
+    // A task locked a party field and the run was not told the value: task.locked.leak was never
+    // asked, and a result that cannot say is not returned as one that passed.
+    if (lockedPartySeen && options.lockedValues === undefined) {
+        stopObserving();
+        throw new TypeError("a task locks its party's number or email and the run states no lockedValues: task.locked.leak cannot be evaluated; pass the values the queue locked in options.lockedValues");
+    }
     if (!options.collectOnly)
         assertNoViolations(violations);
     stopObserving();
@@ -727,6 +737,13 @@ export function assertAuthenticationRestoreAndExpiry(states) {
     }
 }
 /** The tasks an envelope carries: the one a task event names, or a snapshot event's list. */
+/** Whether a task's party stands locked on its number or email, which is what obliges a run to state the locked values. */
+function locksParty(task) {
+    if (!isRecord(task) || !isRecord(task.party))
+        return false;
+    const locked = (value) => isRecord(value) && value.lockedBy !== undefined;
+    return locked(task.party.number) || locked(task.party.email);
+}
 function eventTasks(envelope) {
     if (!isRecord(envelope) || !isRecord(envelope.event))
         return [];
@@ -1026,7 +1043,9 @@ export class TaskStream {
                     stages.set(entry.dialId, entry.stage);
             }
         }
-        return { phase: String(isRecord(task) ? task.phase : undefined), media, source: String(isRecord(task) ? task.capabilitySource : undefined), stages, record: TaskStream.record(task), allocation: String(isRecord(task) ? task.allocationId : undefined) };
+        return { channel: String(isRecord(task) ? task.channel : undefined), completionMode: String(isRecord(task) ? task.completionMode : undefined),
+            wrapAllowance: isRecord(task) && typeof task.wrapAllowance === "number" ? task.wrapAllowance : undefined,
+            phase: String(isRecord(task) ? task.phase : undefined), media, source: String(isRecord(task) ? task.capabilitySource : undefined), stages, record: TaskStream.record(task), allocation: String(isRecord(task) ? task.allocationId : undefined) };
     }
     /** Replaces what is known with a snapshot's tasks, as a snapshot replaces Omni's state. */
     seed(snapshot) {
@@ -1214,6 +1233,15 @@ export class TaskStream {
                 // A late ending for a life that is over must not end the life that is open under the same id.
                 if (!this.namesTheOpenLife(event, known, at, refuse))
                     break;
+                // Off voice there is no media event, so the update that moves a task to completing is the
+                // provider's word that handling ended and the moment the wrap allowance starts. A provider
+                // that completes the task itself with an allowance to run has to have started the clock:
+                // completed from in-progress, the allowance it stated was never given.
+                ruleEvaluated("stream.taskEnded.unwrapped");
+                if (known.channel !== "voice" && known.completionMode === "provider-automatic" && known.wrapAllowance !== undefined && known.wrapAllowance > 0
+                    && known.phase !== "completing" && isRecord(event.outcome) && event.outcome.type === "completed") {
+                    refuse("stream.taskEnded.unwrapped", `${at}.outcome`, `${id} was completed from ${known.phase} with a wrap allowance of ${known.wrapAllowance}s under provider-automatic: off voice, completing is the provider's word that handling ended and the allowance's start, and it was never published`);
+                }
                 this.endedAllocations.add(known.allocation);
                 this.tasks.delete(id);
                 break;

package/dist/validation.d.ts

@@ -32,6 +32,12 @@ 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;
+    /**
+     * 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
+     * carry one of these. Unknown to a host, which never sees the value, and then unchecked.
+     */
+    locked?: readonly string[];
 }
 export declare function validateTask(task: unknown, context: TaskValidationContext, path?: string): ProtocolViolation[];
 /**
@@ -53,6 +59,12 @@ export interface ReaderContext {
     levels?: readonly string[];
     /** The login's `loginId`. A snapshot or event naming another belongs to a login that is gone. */
     loginId?: string;
+    /**
+     * The values the queue locked on this login's tasks, as whoever runs the validator knows them:
+     * a conformance run states them, a host never has them. Where a task's party stands locked, no
+     * other field of it may carry one (`task.locked.leak`). Absent, unchecked.
+     */
+    locked?: readonly string[];
     /** `ConnectContext.autoAcceptTasks` as sent: whether a pending task states its `acceptance`. Unknown to a caller without the context, and then unchecked. */
     autoAcceptTasks?: boolean;
 }

package/dist/validation.js

@@ -89,6 +89,7 @@ const PHONES = membersOf({ softphone: true, deskPhone: true });
 const TEAM_CAPABILITIES = membersOf({ breakControl: true, leadAssistControl: true, policyControl: true, monitorControl: true });
 const MONITOR_MODES = membersOf({ monitor: true, whisper: true, barge: true });
 const COMPLETED_BY = membersOf({ agent: true, provider: true });
+const CANCELLED_BY = membersOf({ agent: true, provider: true, party: true });
 const EXPIRABLE_PHASES = membersOf({
     pending: true, confirmed: true, preview: true,
 });
@@ -598,6 +599,53 @@ const PERSON_SETTABLE = /^(hold|skill:.+)$/;
 const isLocked = (value) => isPlainObject(value) && value.lockedBy !== undefined;
 /** The level ids in force: the manifest's, or the defaults when the caller holds no manifest. */
 const levelIds = (levels) => levels ?? DEFAULT_LEVEL_IDS;
+/**
+ * What the queue locks is locked on the whole task. Given the locked values, every other field an
+ * agent reads -- the title, the reference, an attribute, a custom control's label, a browser URL the
+ * desk shows -- is held to carrying none of them. A number is compared by its digits, so no
+ * formatting hides it; anything else by its text, case aside.
+ */
+function validateNothingLeaksInto(task, locked, path, into) {
+    ruleEvaluated("task.locked.leak");
+    const carries = (text, value) => {
+        if (typeof text !== "string")
+            return false;
+        const digits = value.replace(/[\s+().-]/g, "");
+        if (/^\d+$/.test(digits))
+            return text.replace(/\D/g, "").includes(digits);
+        return text.toLowerCase().includes(value.trim().toLowerCase());
+    };
+    const hold = (text, at) => {
+        for (const value of locked) {
+            if (carries(text, value))
+                into.add("task.locked.leak", at, "carries a value the queue locked: what the queue locks is locked on the whole task, and appears nowhere the agent reads");
+        }
+    };
+    hold(task.title, `${path}.title`);
+    hold(task.reference, `${path}.reference`);
+    if (Array.isArray(task.attributes)) {
+        task.attributes.forEach((attribute, index) => {
+            if (!isPlainObject(attribute))
+                return;
+            hold(attribute.label, `${path}.attributes[${index}].label`);
+            hold(attribute.value, `${path}.attributes[${index}].value`);
+            if (isPlainObject(attribute.party)) {
+                hold(attribute.party.number, `${path}.attributes[${index}].party.number`);
+                hold(attribute.party.email, `${path}.attributes[${index}].party.email`);
+            }
+        });
+    }
+    const custom = isPlainObject(task.capabilities) ? task.capabilities.custom : undefined;
+    if (Array.isArray(custom))
+        custom.forEach((control, index) => { if (isPlainObject(control))
+            hold(control.label, `${path}.capabilities.custom[${index}].label`); });
+    if (Array.isArray(task.browsers)) {
+        task.browsers.forEach((browser, index) => {
+            if (isPlainObject(browser) && browser.urlVisibility !== "hidden")
+                hold(browser.url, `${path}.browsers[${index}].url`);
+        });
+    }
+}
 /** `lockedBy`: a declared level other than `person`, who never locks their own value. */
 function validateLockedByInto(value, rule, path, levels, into) {
     if (!into.filled(value, rule, path, "lockedBy names the level that locked it"))
@@ -947,6 +995,12 @@ function validateMonitoring(value, channel, path, into) {
     into.oneOf(value.mode, MONITOR_MODES, "task.monitoring.mode", `${path}.mode`);
     into.timestamp(value.since, "task.monitoring.since", `${path}.since`);
 }
+/** Whether a task is the agent's own doing: a dial the host placed on its onCall, a lead's join, a lead's monitor. */
+function originatedByTheAgent(task) {
+    if (Array.isArray(task.onCall) && task.onCall.some(entry => isPlainObject(entry) && typeof entry.dialId === "string"))
+        return true;
+    return task.assisting !== undefined || task.monitoring !== undefined;
+}
 export function validateTask(task, context, path = "task") {
     const into = new Collector();
     validateTaskInto(task, context, path, into);
@@ -985,15 +1039,27 @@ function validateTaskInto(task, context, path, into) {
     }
     // Acceptance is the offer's word, carried on the pending task so a snapshot can say it: it
     // travels exactly when Omni said tasks may be auto-accepted, and only while the task is pending.
+    // Work the agent originated -- a dial or connect-back, carrying the host's dialId on onCall; a
+    // lead's join, carrying assisting; a monitor, carrying monitoring -- was accepted by the command
+    // that created it, and says so whatever the provisioning: the desk shows no Accept for a call
+    // the agent placed. The provisioning governs work the queue routes, and nothing else.
+    const originated = task.phase === "pending" && originatedByTheAgent(task);
+    ruleEvaluated("task.acceptance.originated");
     if (task.acceptance !== undefined) {
         into.oneOf(task.acceptance, ACCEPTANCE_MODES, "task.acceptance", `${path}.acceptance`);
         if (task.phase !== "pending") {
             into.add("task.acceptance.unexpected", `${path}.acceptance`, "acceptance is an offer's word; a task past pending has been accepted");
         }
+        else if (originated) {
+            into.require(task.acceptance === "automatic", "task.acceptance.originated", `${path}.acceptance`, "work the agent originated -- a dial, a connect-back, a join, a monitor -- was accepted by the command that created it, and says automatic whatever the provisioning");
+        }
         else if (context.autoAcceptTasks === false) {
-            into.add("task.acceptance.unexpected", `${path}.acceptance`, "autoAcceptTasks is off, so every task requires agent acceptance and a pending task carries no acceptance");
+            into.add("task.acceptance.unexpected", `${path}.acceptance`, "autoAcceptTasks is off, so every task the queue routes requires agent acceptance and a pending task carries no acceptance");
         }
     }
+    else if (originated) {
+        into.add("task.acceptance.originated", `${path}.acceptance`, "work the agent originated -- a dial, a connect-back, a join, a monitor -- says acceptance: automatic whatever the provisioning: the command that created it accepted it");
+    }
     else if (task.phase === "pending" && context.autoAcceptTasks === true) {
         into.add("task.acceptance.required", `${path}.acceptance`, "autoAcceptTasks is on, so a pending task states how it is accepted");
     }
@@ -1015,6 +1081,9 @@ function validateTaskInto(task, context, path, into) {
     }
     if (task.party !== undefined)
         validateContactInto(task.party, `${path}.party`, into, context.levels);
+    if (context.locked !== undefined && isPlainObject(task.party) && (isLocked(task.party.number) || isLocked(task.party.email))) {
+        validateNothingLeaksInto(task, context.locked, path, into);
+    }
     validateBrowsers(task.browsers, `${path}.browsers`, into);
     validateTaskAttributes(task.attributes, `${path}.attributes`, into, context.levels);
     validateHandlingHistory(task.handlingHistory, `${path}.handlingHistory`, into, { phase: task.phase, media: task.media });
@@ -1308,7 +1377,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
         let assisting;
         let monitoring;
         snapshot.tasks.forEach((task, index) => {
-            validateTaskInto(task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest) }, `${path}.tasks[${index}]`, into);
+            validateTaskInto(task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest), locked: context.locked }, `${path}.tasks[${index}]`, into);
             // A lead assists one call at a time, and listens to one at a time.
             if (isPlainObject(task) && task.assisting !== undefined) {
                 if (assisting !== undefined)
@@ -1419,6 +1488,9 @@ function validateTaskOutcome(value, path, into) {
             }
             break;
         case "cancelled":
+            // One word covered the agent declining, the provider withdrawing and the party abandoning the
+            // ring; a record that cannot tell them apart is not a record. by says who, as completed does.
+            into.oneOf(value.by, CANCELLED_BY, "event.taskEnded.outcome.cancelled.by", `${path}.by`);
             if (value.reason !== undefined) {
                 into.filled(value.reason, "event.taskEnded.outcome.cancelled", `${path}.reason`, "a reason must not be empty when present");
             }
@@ -1520,7 +1592,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             validateBreakState(event.break, `${at}.break`, into);
             break;
         case "task-offered":
-            validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest) }, `${at}.task`, into);
+            validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest), locked: context.locked }, `${at}.task`, into);
             // An offer introduces work that is not yet under way; work in progress arrives only on a snapshot.
             if (isPlainObject(event.task) && typeof event.task.phase === "string") {
                 into.require(OFFERABLE_PHASES.includes(event.task.phase), "event.taskOffered.phase", `${at}.task.phase`, `task-offered introduces a task as ${OFFERABLE_PHASES.join(", ")}, never as ${event.task.phase}`);
@@ -1529,7 +1601,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
                 into.timestamp(event.allocationExpiresAt, "event.taskOffered.allocationExpiresAt", `${at}.allocationExpiresAt`);
             break;
         case "task-updated":
-            validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest) }, `${at}.task`, into);
+            validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest), locked: context.locked }, `${at}.task`, into);
             break;
         case "task-media-started":
             into.require(isTaskId(event.taskId), "event.taskMediaStarted.taskId", `${at}.taskId`, "a task id is required");

package/guide.md

@@ -702,7 +702,7 @@ type AcceptanceMode =
 type TaskOutcome =
   | { type: "completed"; by: "agent" | "provider" }
   | { type: "transferred"; destinationId?: string }
-  | { type: "cancelled"; reason?: string }
+  | { type: "cancelled"; by: "agent" | "provider" | "party"; reason?: string }
   | { type: "expired"; phase: "pending" | "confirmed" | "preview" }
   | { type: "left" }
   | { type: "failed"; failure: ProtocolFailure };
@@ -831,7 +831,14 @@ lock, so nothing that can be locked — a directory, a number — may carry that
 contact's number and email are the same, since each identifies a person: where the queue says
 the agent may not see it, the provider sends `{ lockedBy }` in its place — the last digits or
 nothing — and a CRM link carries a token, never the value with a flag the desk is asked to honour.
-A name is not locked. What the queue provides rather than permits — browsers, dispositions, custom
+**What the queue locks is locked on the whole task.** A number the agent may not see appears
+nowhere else they read — not in the title, the reference, an attribute, a custom control's label,
+or a browser URL the desk shows; a browser whose URL must carry it says `urlVisibility: "hidden"`.
+The adapter is the one that knows the value, so it is the one held to it: given the values the
+queue locked, the validator refuses any other field carrying one, digits compared as digits so no
+formatting hides them (`task.locked.leak`), and a conformance run whose tasks lock a party's number
+or email states those values in `lockedValues`, since a run that cannot ask the question is not a
+pass. A host never has the value and never asks. A name is not locked. What the queue provides rather than permits — browsers, dispositions, custom
 controls — is content, and is never locked.
 
 **A lead sets the team's policy from their roster.** A login that declares
@@ -2163,8 +2170,8 @@ person's behalf for want of a word:
 | `consent` | The provider requires the person's explicit consent: Omni presents **Accept** and waits, whatever its own policy would have done. A host that declares `guarantees.personConsent` promises exactly this; a provider checks it before offering work only a person may take. |
 | `automatic` | Omni accepts immediately without agent interaction. |
 
-When Omni sent `autoAcceptTasks: false`, the provider omits `acceptance` and every task
-requires agent acceptance. The two are never confused on the wire: `consent` is always the
+When Omni sent `autoAcceptTasks: false`, the provider omits `acceptance` and every task the
+queue routes requires agent acceptance. The two are never confused on the wire: `consent` is always the
 provider's requirement, stated on a wire where Omni was willing to accept for the agent; Omni's own
 no-auto-accept policy puts no word on the wire at all — the field is absent, and the **Accept**
 press is Omni's doing, not the provider's.
@@ -2178,8 +2185,13 @@ belongs, whatever the host was configured with.
 
 An automatically accepted task still arrives through `task-offered`.
 
-Agent-initiated work arrives through `task-offered` with the task's
-`acceptance: "automatic"`.
+**Work the agent originated is accepted by the command that created it.** A task born of the
+agent's own act — a dialpad call or a connect-back, recognisable by the host's `dialId` on
+`onCall`; a lead's join, carrying `assisting`; a lead's monitor, carrying `monitoring` — arrives
+through `task-offered` with `acceptance: "automatic"` whatever `autoAcceptTasks` says, and the
+validator holds it there under either provisioning and under none (`task.acceptance.originated`):
+the desk shows no **Accept** for a call the agent placed. The provisioning governs work the queue
+routes to the agent, and nothing else.
 
 ### Pending
 
@@ -2213,14 +2225,20 @@ on a desk phone — and is not in question per call. See **How the agent hears t
 Automatic acceptance still begins with `task-offered`.
 
 `allocationExpiresAt` is the deadline after which the offer lapses. Where present, Omni counts
-down and stops offering **Accept** once it passes. **Omit it unless the provider can observe it.**
+down and stops offering **Accept** once it passes; the provider ends the lapsed offer with
+`task-ended` and an `expired` outcome naming `pending`, since nobody cancelled it. **Omit it unless the provider can observe it.**
 A provider that reports only elapsed ring time after the fact cannot say when an offer is due
 to end, and a computed value would have Omni withdraw **Accept** from a task still pending.
 
 A preview's deadline is not on the offer. It travels on the task, as `previewEndsAt` with
 `atDeadline`, so a snapshot carries it too -- see **Preview: the agent presses Call**.
 
-A provider may withdraw a pending task by emitting `task-ended` with a `cancelled` outcome.
+A provider may withdraw a pending task by emitting `task-ended` with a `cancelled` outcome, `by:
+"provider"`. **`cancelled` says who called the work off**, as `completed` says who completed it:
+`agent` for a decline, `provider` for a withdrawal or a re-route, `party` for a caller who abandoned
+the ring. One word for the three left a supervisor's record unable to tell them apart, so `by` is
+required and closed (`event.taskEnded.outcome.cancelled.by`). An offer nobody acted on before
+`allocationExpiresAt` is not cancelled by anyone: it lapses, and ends `expired` naming `pending`.
 
 ### Tasks already in progress
 
@@ -2302,7 +2320,8 @@ The canonical task transitions are:
 | `preview` | Agent presses Call (`call`) and the customer answers, or the deadline `calls` and they answer | `in-progress` |
 | `preview` | The call goes out and nobody answers | `completing` |
 | `preview` | The deadline `expires` | Removed by `task-ended` with `expired` outcome |
-| `pending` | Provider withdraws the allocation | Removed by `task-ended` with `cancelled` outcome |
+| `pending` | Provider withdraws the allocation, the agent declines, or the party abandons the ring | Removed by `task-ended` with `cancelled` outcome, `by` saying which |
+| `pending` | The offer lapses at `allocationExpiresAt` | Removed by `task-ended` with `expired` outcome naming `pending` |
 | No task | Snapshot reports work already underway | `in-progress` |
 | `in-progress` | Provider or agent pauses the task | `paused` |
 | `in-progress` | Agent starts a warm transfer (`transfer` `warm`); the customer is parked | `paused` |
@@ -2413,9 +2432,18 @@ whether the channel carries real-time media:
 | Channel | Wrap allowance starts at |
 | --- | --- |
 | Voice and any channel with real-time media | The `task-media-ended` event |
-| Chat | When the conversation ends and the task enters `completing` |
-| Email | After the message is sent and the task enters `completing` |
-| Other non-media channels | The moment the task enters `completing` |
+| Chat | The `task-updated` that moves the task to `completing`: the provider's word that the conversation is closed on its side, the allowance running from that publication's `occurredAt` |
+| Email | The `task-updated` that moves the task to `completing`: the provider's word that the platform has accepted the outgoing message, the allowance running from that publication's `occurredAt` |
+| Other non-media channels | The `task-updated` that moves the task to `completing` |
+
+**Off voice, `completing` is the provider's word that handling ended.** There is no media event to
+carry it, so the phase does; a host starts the wrap clock at that publication and nowhere else. It
+is optional: a conversation with nothing to wrap moves from `in-progress` to `task-ended` and
+`completing` is never published. Under `provider-automatic` with a non-zero `wrapAllowance` it is
+required, because the clock has to start somewhere: a chat or email task the provider completes
+from `in-progress` with an allowance to run gave the agent none of it, and the stream refuses the
+ending (`stream.taskEnded.unwrapped`). Under `agent-command` the agent's `complete` is the end,
+from `in-progress` or from `completing` alike.
 
 ```ts
 const emailCompletion = {
@@ -4261,8 +4289,8 @@ beside the mapped one is what the full check costs a host; an adapter has it for
 validator holds a command only to a task that stands: a task handed in that is not one the wire
 published is named (`command.task`) rather than checked against.
 
-Declining or rejecting a pending offer ends it without accepting or completing it. The provider
-confirms the end with `task-ended` and a `cancelled` outcome.
+Declining a pending offer ends it without accepting or completing it. The provider confirms the
+end with `task-ended` and a `cancelled` outcome, `by: "agent"`.
 
 ### `execute(request)`
 
@@ -4624,7 +4652,7 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | Function | Validates |
 | --- | --- |
 | `validateManifest(manifest)` | Identity, protocol-version interoperability, authentication methods, and idle-capability shapes. |
-| `validateTask(task, { channel })` | Identity, channel agreement, phase, wrap allowance, capability shapes, custom controls, and browsers. |
+| `validateTask(task, { channel, locked? })` | Identity, channel agreement, phase, wrap allowance, capability shapes, custom controls, and browsers. Given `locked`, the values the queue locked, a task whose party stands locked carries none of them anywhere else (`task.locked.leak`). |
 | `validateSnapshot(snapshot, manifest)` | Status, break state, break reasons, team roster, the stated `taskCount` reconciled against the tasks carried, and every task, contact, and activity, including idle-capability gating both ways: a contribution the manifest never declared is refused, and one it declares is required, `[]` included. |
 | `validateEventEnvelope(envelope, manifest)` | Envelope identity, timestamp, and the payload for each event type. |
 | `validateContact(contact)` | Contact field shapes and attribute keys. Every field is optional, so this checks what is present rather than what is missing. |

package/package.json

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