@xema/omni-protocol 0.1.78 → 0.1.79

package/README.md

@@ -126,11 +126,18 @@ const request = { reasonId, requestedAt } satisfies BreakRequest; // error: requ
 ## Building
 
 ```
-pnpm install
+pnpm install --frozen-lockfile
+pnpm check        # clean build, type checks, tests, and packed-package checks
 pnpm build        # emits dist/
 pnpm test         # type-checks the tests, then runs them
+pnpm check:package # verifies the current dist/ as a consumer would
 ```
 
+CI runs the complete check on Node 20, 22, and 24 for pull requests (including drafts)
+and pushes to main. Package checks create a temporary npm tarball, verify its contents,
+and check JavaScript imports and TypeScript declarations for every exported entry point
+from an isolated consumer. Publishing also runs `pnpm check` through `prepublishOnly`.
+
 ## The guide is authoritative
 
 Where `guide.md` and any code here disagree, the guide is right and the code is a defect. It has

package/dist/testing.js

@@ -1251,7 +1251,7 @@ export class TaskStream {
                 this.noteDials(event.task);
                 break;
             case "task-media-started":
-                ruleEvaluated("stream.taskMediaStarted.unknown", "stream.taskMediaStarted.beforeWork", "stream.taskMediaStarted.duplicate", "stream.allocation.ended", "stream.allocation.unknown");
+                ruleEvaluated("stream.taskMediaStarted.unknown", "stream.taskMediaStarted.beforeWork", "stream.taskMediaStarted.duplicate", "stream.taskMedia.channel", "stream.allocation.ended", "stream.allocation.unknown");
                 if (id === undefined)
                     break;
                 if (known === undefined) {
@@ -1262,6 +1262,10 @@ export class TaskStream {
                     break;
                 // Ring-back is audio: a task whose party the host is dialling has media from dialling on,
                 // whatever its phase; every other task not at work has none.
+                if (known.channel !== "voice") {
+                    refuse("stream.taskMedia.channel", `${at}.type`, "only a voice task has media transitions");
+                    break;
+                }
                 if (!AT_WORK.has(known.phase) && !known.partyRingingByHost) {
                     refuse("stream.taskMediaStarted.beforeWork", `${at}.taskId`, `media cannot arrive on ${id} while it is ${known.phase}: a task is never its audio, and its work has not begun`);
                 }
@@ -1271,7 +1275,7 @@ export class TaskStream {
                 known.media = "started";
                 break;
             case "task-media-ended":
-                ruleEvaluated("stream.taskMediaEnded.unknown", "stream.taskMediaEnded.beforeWork", "stream.taskMediaEnded.silent", "stream.allocation.ended", "stream.allocation.unknown");
+                ruleEvaluated("stream.taskMediaEnded.unknown", "stream.taskMediaEnded.beforeWork", "stream.taskMediaEnded.silent", "stream.taskMedia.channel", "stream.allocation.ended", "stream.allocation.unknown");
                 if (id === undefined)
                     break;
                 if (known === undefined) {
@@ -1280,6 +1284,10 @@ export class TaskStream {
                 }
                 if (!this.namesTheOpenLife(event, known, at, refuse))
                     break;
+                if (known.channel !== "voice") {
+                    refuse("stream.taskMedia.channel", `${at}.type`, "only a voice task has media transitions");
+                    break;
+                }
                 if (!WORK_BEGUN.has(known.phase)) {
                     refuse("stream.taskMediaEnded.beforeWork", `${at}.taskId`, `media cannot end on ${id} while it is ${known.phase}: a task is never its audio, and its work has not begun`);
                 }
@@ -1477,10 +1485,11 @@ async function driveOneCall(drive) {
                 session = undefined;
                 ruleEvaluated("drive.reload.openMedia");
                 const reopened = await second.openMedia?.({ taskId, allocationId: allocationOf(), localAudio: drive.localAudio });
-                found.push(...validateResult(reopened, "openMedia", "drive.reload.openMedia"));
-                if (isRecord(reopened) && reopened.status === "opened")
+                const malformed = validateResult(reopened, "openMedia", "drive.reload.openMedia");
+                found.push(...malformed);
+                if (malformed.length === 0 && isRecord(reopened) && reopened.status === "opened")
                     session = reopened.session;
-                else
+                else if (malformed.length === 0)
                     refuse("drive.reload.openMedia", "drive.reload.openMedia", `a second adapter built from the same login could not open the audio of ${taskId}, which its own snapshot carries with media started`);
             }
         }
@@ -1630,10 +1639,11 @@ async function driveOneCall(drive) {
             cursor = Math.max(cursor, started.at);
         }
         const opened = await drive.connection.openMedia?.({ taskId, allocationId: allocationOf(), localAudio: drive.localAudio });
-        found.push(...validateResult(opened, "openMedia", "drive.openMedia"));
-        if (isRecord(opened) && opened.status === "opened")
+        const malformed = validateResult(opened, "openMedia", "drive.openMedia");
+        found.push(...malformed);
+        if (malformed.length === 0 && isRecord(opened) && opened.status === "opened")
             session = opened.session;
-        else if (isRecord(opened))
+        else if (malformed.length === 0 && isRecord(opened))
             refuse("drive.openMedia.unavailable", "drive.openMedia", "a softphone login's adapter could not open the call's audio");
     }
     // 3b. The microphone is the host's. With the audio open, the drive mutes it for a moment and

package/dist/validation.js

@@ -47,6 +47,7 @@ const ACCEPTANCE_MODES = membersOf({
 });
 const TRANSPORT_STATUSES = membersOf({ connecting: true, active: true, error: true });
 const AUTHENTICATION_METHODS = membersOf({ "browser-sso": true, credentials: true });
+const AUTHENTICATION_BROWSERS = membersOf({ system: true, omni: true });
 const AUTHENTICATION_STATUSES = membersOf({
     "signed-out": true, authenticating: true, authenticated: true, refreshing: true, expired: true,
 });
@@ -117,6 +118,16 @@ const isChannel = (value) => CHANNELS.includes(value);
 // ---------------------------------------------------------------------------
 const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const isFilled = (value) => typeof value === "string" && value.trim().length > 0;
+/** Error text must not invoke conversion methods supplied by an untrusted object or array. */
+function describeValue(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "object")
+        return Array.isArray(value) ? "an array" : "an object";
+    if (typeof value === "function")
+        return "a function";
+    return String(value);
+}
 /**
  * An RFC-3339 timestamp carrying a zone.
  *
@@ -124,9 +135,22 @@ const isFilled = (value) => typeof value === "string" && value.trim().length > 0
  * happens to be in, so two hosts would read the same wire value as two different instants. The
  * contract calls those invalid, and this is where that is enforced rather than assumed.
  */
-const isIsoTimestamp = (value) => typeof value === "string"
-    && /^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/.test(value)
-    && !Number.isNaN(Date.parse(value));
+const isIsoTimestamp = (value) => {
+    if (typeof value !== "string")
+        return false;
+    const match = /^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):\d{2}:\d{2}(?:\.\d+)?(?:[Zz]|[+-]\d{2}:\d{2})$/.exec(value);
+    if (match === null)
+        return false;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    // RFC 3339 sections 5.6–5.7: days depend on the month/year and hours are 00–23.
+    // Date.parse alone normalizes February 30 and 24:00 into different instants.
+    const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const daysInMonth = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1];
+    return daysInMonth !== undefined && day >= 1 && day <= daysInMonth
+        && Number(match[4]) < 24 && !Number.isNaN(Date.parse(value));
+};
 /** A non-negative integer count of seconds. */
 const isDurationSeconds = (value) => typeof value === "number" && Number.isInteger(value) && value >= 0;
 /** Opaque, non-empty, provider-issued. Never parsed and never compared across providers. */
@@ -168,7 +192,7 @@ class Collector {
         return this.require(isIsoTimestamp(value), rule, path, "must be an RFC-3339 timestamp carrying a zone, such as 2026-08-21T09:00:00Z");
     }
     oneOf(value, allowed, rule, path) {
-        return this.require(typeof value === "string" && allowed.includes(value), rule, path, `must be one of ${allowed.join(", ")}; received ${String(value)}`);
+        return this.require(typeof value === "string" && allowed.includes(value), rule, path, `must be one of ${allowed.join(", ")}; received ${describeValue(value)}`);
     }
 }
 // ---------------------------------------------------------------------------
@@ -309,7 +333,7 @@ function validateDialOutcomes(manifest, path, into) {
         into.require(!dials, "manifest.dialOutcomes.required", path, "a manifest that declares dial says how a dial ends: dialOutcomes with answered and at least one way of not reaching");
         return;
     }
-    if (!into.require(manifest.channel === "voice", "manifest.dialOutcomes.channel", path, `a ${String(manifest.channel)} provider dials nothing and declares no dial outcomes`))
+    if (!into.require(manifest.channel === "voice", "manifest.dialOutcomes.channel", path, `a ${describeValue(manifest.channel)} provider dials nothing and declares no dial outcomes`))
         return;
     if (!Array.isArray(declared) || declared.length === 0) {
         into.add("manifest.dialOutcomes.shape", path, "dialOutcomes is a non-empty array of the outcomes the platform distinguishes");
@@ -317,7 +341,7 @@ function validateDialOutcomes(manifest, path, into) {
     }
     declared.forEach((outcome, index) => {
         if (into.oneOf(outcome, DIAL_OUTCOMES, "manifest.dialOutcome", `${path}[${index}]`) && declared.indexOf(outcome) !== index) {
-            into.add("manifest.dialOutcome.unique", `${path}[${index}]`, `duplicate dial outcome: ${String(outcome)}`);
+            into.add("manifest.dialOutcome.unique", `${path}[${index}]`, `duplicate dial outcome: ${describeValue(outcome)}`);
         }
     });
     into.require(declared.includes("answered"), "manifest.dialOutcomes.answered", path, "a dial that reached its destination is stated, never inferred: dialOutcomes includes answered");
@@ -335,7 +359,7 @@ function validateDialOutcomes(manifest, path, into) {
 function validatePhones(manifest, path, into) {
     const declared = manifest.phones;
     if (manifest.channel !== "voice") {
-        into.require(declared === undefined, "manifest.phones.channel", path, `a ${String(manifest.channel)} provider has no call to hear and declares no phones`);
+        into.require(declared === undefined, "manifest.phones.channel", path, `a ${describeValue(manifest.channel)} provider has no call to hear and declares no phones`);
         return;
     }
     if (!Array.isArray(declared) || declared.length === 0) {
@@ -344,7 +368,7 @@ function validatePhones(manifest, path, into) {
     }
     declared.forEach((phone, index) => {
         if (into.oneOf(phone, PHONES, "manifest.phone", `${path}[${index}]`) && declared.indexOf(phone) !== index) {
-            into.add("manifest.phone.unique", `${path}[${index}]`, `duplicate phone: ${String(phone)}`);
+            into.add("manifest.phone.unique", `${path}[${index}]`, `duplicate phone: ${describeValue(phone)}`);
         }
     });
 }
@@ -357,13 +381,13 @@ export function validatePhone(value, manifest, path = "context.phone") {
     const channel = isPlainObject(manifest) ? manifest.channel : undefined;
     const phones = isPlainObject(manifest) && Array.isArray(manifest.phones) ? manifest.phones : [];
     if (channel !== "voice") {
-        into.require(value === undefined, "context.phone.unexpected", path, `a ${String(channel)} login has no call to hear and chooses no phone`);
+        into.require(value === undefined, "context.phone.unexpected", path, `a ${describeValue(channel)} login has no call to hear and chooses no phone`);
         return into.violations;
     }
     if (!into.require(value !== undefined, "context.phone.required", path, "a voice login says how the agent hears the call: one of the manifest's phones"))
         return into.violations;
     if (into.oneOf(value, PHONES, "context.phone", path)) {
-        into.require(phones.includes(value), "context.phone.unsupported", path, `the host chose ${String(value)} and the manifest lists ${phones.length === 0 ? "no phones" : phones.join(", ")}`);
+        into.require(phones.includes(value), "context.phone.unsupported", path, `the host chose ${describeValue(value)} and the manifest lists ${phones.length === 0 ? "no phones" : phones.map(describeValue).join(", ")}`);
     }
     return into.violations;
 }
@@ -400,7 +424,7 @@ export function validateManifest(manifest, path = "manifest") {
     else {
         methods.forEach((method, index) => {
             if (into.oneOf(method, AUTHENTICATION_METHODS, "manifest.authenticationMethod", `${path}.authenticationMethods[${index}]`) && methods.indexOf(method) !== index) {
-                into.add("manifest.authenticationMethod.unique", `${path}.authenticationMethods[${index}]`, `duplicate authentication method: ${String(method)}`);
+                into.add("manifest.authenticationMethod.unique", `${path}.authenticationMethods[${index}]`, `duplicate authentication method: ${describeValue(method)}`);
             }
         });
     }
@@ -583,6 +607,10 @@ function validateCustomCapabilities(value, path, into) {
                     into.filled(field.name, "task.custom.prompt.field.name", `${where}.name`, "a prompt field needs a name");
                     into.filled(field.label, "task.custom.prompt.field.label", `${where}.label`, "a prompt field needs a label");
                     into.oneOf(field.type, CREDENTIAL_FIELD_TYPES, "task.custom.prompt.field.type", `${where}.type`);
+                    if (field.required !== undefined)
+                        into.require(typeof field.required === "boolean", "task.custom.prompt.field.required", `${where}.required`, "required must be a boolean when present");
+                    if (field.autocomplete !== undefined)
+                        into.require(typeof field.autocomplete === "string", "task.custom.prompt.field.autocomplete", `${where}.autocomplete`, "autocomplete must be a string when present");
                 });
             }
         }
@@ -649,7 +677,7 @@ function validateLockedByInto(value, rule, path, levels, into) {
     if (!into.filled(value, rule, path, "lockedBy names the level that locked it"))
         return;
     into.require(value !== "person", `${rule}.person`, path, "a person never locks their own value");
-    into.require(levelIds(levels).includes(value), `${rule}.unknown`, path, `${String(value)} is not a level this manifest declares: in force are ${levelIds(levels).join(", ")}`);
+    into.require(levelIds(levels).includes(value), `${rule}.unknown`, path, `${describeValue(value)} is not a level this manifest declares: in force are ${levelIds(levels).join(", ")}`);
 }
 /** `{ lockedBy, reason? }` standing in for a value: who locked it, and a reason if given. */
 function validateLockedInto(value, rule, path, levels, into) {
@@ -660,7 +688,7 @@ function validateLockedInto(value, rule, path, levels, into) {
 /** What every resolved value carries: who set it, and who locked it if anyone. */
 function validateResolvedInto(value, rule, path, levels, into) {
     if (into.filled(value.setBy, `${rule}.setBy`, `${path}.setBy`, "setBy names who stated the value: a level, or provider")) {
-        into.require(value.setBy === "provider" || levelIds(levels).includes(value.setBy), `${rule}.setBy.unknown`, `${path}.setBy`, `${String(value.setBy)} is neither provider nor a level this manifest declares`);
+        into.require(value.setBy === "provider" || levelIds(levels).includes(value.setBy), `${rule}.setBy.unknown`, `${path}.setBy`, `${describeValue(value.setBy)} is neither provider nor a level this manifest declares`);
     }
     if (value.lockedBy !== undefined)
         validateLockedByInto(value.lockedBy, `${rule}.lockedBy`, `${path}.lockedBy`, levels, into);
@@ -771,7 +799,7 @@ function validateTaskAttributes(value, path, into, levels) {
                 into.timestamp(attribute.at, "task.attribute.timestamp", `${at}.at`);
                 break;
             default:
-                into.add("task.attribute.type", `${at}.type`, `unsupported attribute type: ${String(attribute.type)}`);
+                into.add("task.attribute.type", `${at}.type`, `unsupported attribute type: ${describeValue(attribute.type)}`);
         }
     });
 }
@@ -822,7 +850,7 @@ function validateHandlingHistory(value, path, into, task = {}) {
             // the task is paused, and a mute only while its media is up. An open entry after that is a leg
             // nobody closed, which reads exactly like a leg running now.
             if (entry.step === "held") {
-                into.require(task.phase === "paused", "task.handlingHistory.held.open", `${at}.seconds`, `a held entry without seconds is a hold still running, and the task is ${String(task.phase)}: the hold has ended, and its duration is stated`);
+                into.require(task.phase === "paused", "task.handlingHistory.held.open", `${at}.seconds`, `a held entry without seconds is a hold still running, and the task is ${describeValue(task.phase)}: the hold has ended, and its duration is stated`);
             }
             if (entry.step === "muted") {
                 into.require(task.media !== "ended" && task.phase !== "completing", "task.handlingHistory.muted.open", `${at}.seconds`, "a muted entry without seconds is a mute still running, and the call is over: the provider closes every open leg at the instant the media ends, and the duration is stated");
@@ -849,7 +877,7 @@ function validateHandlingHistory(value, path, into, task = {}) {
             if (entry[field] === undefined)
                 continue;
             if (into.filled(entry[field], `task.handlingHistory.${field}`, `${at}.${field}`, `${field} must not be empty when present`)) {
-                into.require(dialled, `task.handlingHistory.${field}.unexpected`, `${at}.${field}`, `${String(entry.step)} dialled nothing; ${field} belongs on transferred, conferenced, or unanswered`);
+                into.require(dialled, `task.handlingHistory.${field}.unexpected`, `${at}.${field}`, `${describeValue(entry.step)} dialled nothing; ${field} belongs on transferred, conferenced, or unanswered`);
             }
         }
     });
@@ -871,7 +899,7 @@ function validateTaskMedia(task, value, channel, phase, path, into) {
         // work has begun, on a snapshot as on the event, or a host would open the microphone on an offer.
         // The one task not yet at work that has audio is one whose party the host is dialling: ring-back
         // is audio, and every host-placed dial's media starts on dialling.
-        into.require(!WORK_NOT_BEGUN.includes(phase) || partyRingingByHost(task), "task.media.beforeWork", path, `a ${String(phase)} task has no media: audio arrives once its work has begun, or once the host is dialling its party`);
+        into.require(!WORK_NOT_BEGUN.includes(phase) || partyRingingByHost(task), "task.media.beforeWork", path, `a ${describeValue(phase)} task has no media: audio arrives once its work has begun, or once the host is dialling its party`);
     }
 }
 const WORK_NOT_BEGUN = ["pending", "confirmed", "preview"];
@@ -1079,7 +1107,7 @@ function validateTaskInto(task, context, path, into) {
     }
     // The channel is fixed per provider by its manifest, so a task claiming another one is a
     // task Omni would render with the wrong controls.
-    into.require(task.channel === context.channel, "task.channel", `${path}.channel`, `a ${context.channel} provider may not publish a ${String(task.channel)} task`);
+    into.require(task.channel === context.channel, "task.channel", `${path}.channel`, `a ${context.channel} provider may not publish a ${describeValue(task.channel)} task`);
     if (task.reference !== undefined) {
         into.filled(task.reference, "task.reference", `${path}.reference`, "a reference must not be empty when present");
     }
@@ -1223,7 +1251,7 @@ function validateBreakState(value, path, into) {
         // An imposed break is a break somebody placed; beside `not-requested` there is no break.
         // An imposed break is a break in progress or about to be: it travels with in-effect or
         // starting-after-task and nothing else. Beside granted, the host would commit a break nobody asked for.
-        into.require(value.approval === "in-effect" || value.approval === "starting-after-task", "break.imposed.approval", `${path}.imposed`, `an imposed break is in effect or starting after the task; ${String(value.approval)} says the agent asked, or that there is none`);
+        into.require(value.approval === "in-effect" || value.approval === "starting-after-task", "break.imposed.approval", `${path}.imposed`, `an imposed break is in effect or starting after the task; ${describeValue(value.approval)} says the agent asked, or that there is none`);
     }
     if (value.reasons === undefined)
         return;
@@ -1263,7 +1291,7 @@ function validateBreakState(value, path, into) {
     // rules -- who may monitor through it, whether it counts -- nobody can apply.
     ruleEvaluated("break.activeReasonId.required");
     if (seen.size > 0 && (value.approval === "in-effect" || value.approval === "starting-after-task")) {
-        into.require(typeof value.activeReasonId === "string" && value.activeReasonId.length > 0, "break.activeReasonId.required", `${path}.activeReasonId`, `a break ${String(value.approval)} on a provider that publishes reasons names the one it is on`);
+        into.require(typeof value.activeReasonId === "string" && value.activeReasonId.length > 0, "break.activeReasonId.required", `${path}.activeReasonId`, `a break ${describeValue(value.approval)} on a provider that publishes reasons names the one it is on`);
     }
 }
 export function validateTeamRoster(roster, path = "team", context = {}) {
@@ -1370,10 +1398,10 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
     }
     const channel = isPlainObject(manifest) && typeof manifest.channel === "string" ? manifest.channel : "voice";
     const levels = context.levels ?? manifestLevels(manifest);
-    into.oneOf(snapshot.transport, TRANSPORT_STATUSES, "snapshot.transport", `${path}.status`);
+    into.oneOf(snapshot.transport, TRANSPORT_STATUSES, "snapshot.transport", `${path}.transport`);
     if (into.filled(snapshot.loginId, "snapshot.loginId", `${path}.loginId`, "a snapshot needs the login id it belongs to")
         && context.loginId !== undefined) {
-        into.require(snapshot.loginId === context.loginId, "snapshot.loginId.mismatch", `${path}.loginId`, `a snapshot for session ${String(snapshot.loginId)} on a login whose session is ${context.loginId}`);
+        into.require(snapshot.loginId === context.loginId, "snapshot.loginId.mismatch", `${path}.loginId`, `a snapshot for session ${describeValue(snapshot.loginId)} on a login whose session is ${context.loginId}`);
     }
     validateBreakState(snapshot.break, `${path}.break`, into);
     // The count is the provider's confirmation of how much work it answered with. Stated, never
@@ -1440,7 +1468,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
             const reasons = Array.isArray(state.reasons) ? state.reasons : [];
             const active = reasons.find((reason) => isPlainObject(reason) && reason.id === state.activeReasonId);
             const kind = isPlainObject(active) ? active.kind : undefined;
-            into.require(typeof kind === "string" && MONITORING_BREAK_KINDS.includes(kind), "snapshot.monitoring.break", `${path}.tasks`, `a lead listens during a ${MONITORING_BREAK_KINDS.join(", ")} break and no other; the active reason is ${kind === undefined ? "unstated" : String(kind)}`);
+            into.require(typeof kind === "string" && MONITORING_BREAK_KINDS.includes(kind), "snapshot.monitoring.break", `${path}.tasks`, `a lead listens during a ${MONITORING_BREAK_KINDS.join(", ")} break and no other; the active reason is ${kind === undefined ? "unstated" : describeValue(kind)}`);
         }
     }
     // Presence is the permission, and it cuts both ways: data a provider never declared a
@@ -1535,7 +1563,7 @@ function validateTaskOutcome(value, path, into) {
             }
             break;
         default:
-            into.add("event.taskEnded.outcome.type", `${path}.type`, `unsupported outcome: ${String(value.type)}`);
+            into.add("event.taskEnded.outcome.type", `${path}.type`, `unsupported outcome: ${describeValue(value.type)}`);
     }
 }
 function validateQueueSummary(value, path, into) {
@@ -1583,7 +1611,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
     into.filled(envelope.id, "event.id", `${path}.id`, "an event needs an id");
     if (into.filled(envelope.loginId, "event.loginId", `${path}.loginId`, "an event needs the login id it belongs to")
         && context.loginId !== undefined) {
-        into.require(envelope.loginId === context.loginId, "event.loginId.mismatch", `${path}.loginId`, `an event for session ${String(envelope.loginId)} on a login whose session is ${context.loginId}`);
+        into.require(envelope.loginId === context.loginId, "event.loginId.mismatch", `${path}.loginId`, `an event for session ${describeValue(envelope.loginId)} on a login whose session is ${context.loginId}`);
     }
     const idle = isPlainObject(manifest) && isPlainObject(manifest.idleCapabilities) ? manifest.idleCapabilities : {};
     into.timestamp(envelope.occurredAt, "event.occurredAt", `${path}.occurredAt`);
@@ -1629,10 +1657,12 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest), locked: context.locked }, `${at}.task`, into);
             break;
         case "task-media-started":
+            into.require(channel === "voice", "event.media.channel", `${at}.type`, "only a voice provider publishes media transitions");
             into.require(isTaskId(event.taskId), "event.taskMediaStarted.taskId", `${at}.taskId`, "a task id is required");
             into.require(isAllocationId(event.allocationId), "event.taskMediaStarted.allocationId", `${at}.allocationId`, "an event about a task names its allocation");
             break;
         case "task-media-ended":
+            into.require(channel === "voice", "event.media.channel", `${at}.type`, "only a voice provider publishes media transitions");
             into.require(isTaskId(event.taskId), "event.taskMediaEnded.taskId", `${at}.taskId`, "a task id is required");
             into.require(isAllocationId(event.allocationId), "event.taskMediaEnded.allocationId", `${at}.allocationId`, "an event about a task names its allocation");
             break;
@@ -1646,7 +1676,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             // Only a distinction the manifest declared: an undeclared word is a guess dressed as a code.
             const declared = isPlainObject(manifest) && Array.isArray(manifest.dialOutcomes) ? manifest.dialOutcomes : undefined;
             if (into.oneOf(event.outcome, DIAL_OUTCOMES, "event.dialOutcome.outcome", `${at}.outcome`)) {
-                into.require(declared !== undefined && declared.includes(event.outcome), "event.dialOutcome.undeclared", `${at}.outcome`, `the manifest does not declare ${String(event.outcome)} among its dialOutcomes`);
+                into.require(declared !== undefined && declared.includes(event.outcome), "event.dialOutcome.undeclared", `${at}.outcome`, `the manifest does not declare ${describeValue(event.outcome)} among its dialOutcomes`);
             }
             if (event.taskId !== undefined)
                 into.require(isTaskId(event.taskId), "event.dialOutcome.taskId", `${at}.taskId`, "taskId must be a task id when present");
@@ -1706,7 +1736,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             }
             break;
         default:
-            into.add("event.type", `${at}.type`, `unsupported event type: ${String(event.type)}`);
+            into.add("event.type", `${at}.type`, `unsupported event type: ${describeValue(event.type)}`);
     }
     return into.violations;
 }
@@ -1942,7 +1972,7 @@ export function validateHostReport(report, path = "host") {
         into.require(input.mutedBy === undefined, "host.audio.input.mutedBy.unexpected", `${at}.mutedBy`, "an unavailable input was not silenced; it is absent");
     }
     else {
-        into.add("host.audio.input.status", `${at}.status`, `an input is available or unavailable, not ${String(input.status)}`);
+        into.add("host.audio.input.status", `${at}.status`, `an input is available or unavailable, not ${describeValue(input.status)}`);
     }
     const output = report.audio.output;
     const out = `${path}.audio.output`;
@@ -1965,7 +1995,7 @@ export function validateHostReport(report, path = "host") {
         into.require(output.mutedBy === undefined, "host.audio.output.mutedBy.unexpected", `${out}.mutedBy`, "an unavailable output was not silenced; it is absent");
     }
     else {
-        into.add("host.audio.output.status", `${out}.status`, `an output is available or unavailable, not ${String(output.status)}`);
+        into.add("host.audio.output.status", `${out}.status`, `an output is available or unavailable, not ${describeValue(output.status)}`);
     }
     return into.violations;
 }
@@ -1996,25 +2026,8 @@ export function validateTaskCommand(command, task, path = "command") {
         : [...new Set([...TASK_COMMAND_NAMES.voice, ...TASK_COMMAND_NAMES.chat, ...TASK_COMMAND_NAMES.email])];
     if (type === "custom") {
         into.filled(command.name, "command.custom.name", `${path}.name`, "a custom command names the control it presses");
-        if (task === undefined)
-            return into.violations;
-        // Held to the task: the control it presses is one the task published, and what the control asked for travels with it.
-        const custom = isPlainObject(task) && isPlainObject(task.capabilities) ? task.capabilities.custom : undefined;
-        const control = Array.isArray(custom) ? custom.filter(isPlainObject).find(entry => entry.id === command.name) : undefined;
-        if (control === undefined) {
-            into.add("command.capability.custom", path, `custom ${String(command.name)} presses a control the task never published`);
-            return into.violations;
-        }
-        if (isPlainObject(control.prompt) && Array.isArray(control.prompt.fields)) {
-            for (const field of control.prompt.fields.filter(isPlainObject)) {
-                if (typeof field.name === "string") {
-                    into.require(typeof command[field.name] === "string" && command[field.name].length > 0, "command.custom.prompt", `${path}.${field.name}`, `the control asked for ${field.name} and the command does not carry it`);
-                }
-            }
-        }
-        return into.violations;
     }
-    if (!into.require(typeof type === "string" && names.includes(type), "command.type", `${path}.type`, channel === undefined ? `unsupported command: ${String(type)}` : `a ${channel} task has no ${String(type)} command`)) {
+    if (type !== "custom" && !into.require(typeof type === "string" && names.includes(type), "command.type", `${path}.type`, channel === undefined ? `unsupported command: ${describeValue(type)}` : `a ${channel} task has no ${describeValue(type)} command`)) {
         return into.violations;
     }
     const dial = (rule) => into.filled(command.dialId, rule, `${path}.dialId`, "a command that dials carries the host's dialId");
@@ -2032,7 +2045,7 @@ export function validateTaskCommand(command, task, path = "command") {
                     into.filled(command.destinationId, "command.transfer.destinationId", `${path}.destinationId`, "a transfer names the directory item it goes to");
                 }
                 else {
-                    into.require(command.dialId === undefined && command.destinationId === undefined, "command.transfer.unexpected", path, `${String(command.action)} names no destination: there is exactly one it could mean`);
+                    into.require(command.dialId === undefined && command.destinationId === undefined, "command.transfer.unexpected", path, `${describeValue(command.action)} names no destination: there is exactly one it could mean`);
                 }
             }
             break;
@@ -2066,7 +2079,7 @@ export function validateTaskCommand(command, task, path = "command") {
         default:
             break;
     }
-    if (!isPlainObject(task))
+    if (task === undefined)
         return into.violations;
     // The task the command is held to has to be one the wire published. A host's own mapping of it,
     // handed in for want of the original, is not, and checking a command against it would be
@@ -2074,25 +2087,45 @@ export function validateTaskCommand(command, task, path = "command") {
     // only to a task that stands.
     const published = new Collector();
     validateTaskInto(task, { channel: channel ?? "voice" }, `${path}.task`, published);
-    if (published.violations.length > 0) {
+    if (published.violations.length > 0 || !isPlainObject(task)) {
         into.add("command.task", `${path}.task`, `the task the command is held to is not one the wire published (${published.violations.map(v => v.rule).join(", ")}): pass the task as the provider sent it, or validate the command's shape alone`);
         return into.violations;
     }
+    if (type === "custom") {
+        // Held to the task: the control it presses is one the task published, and what the control asked for travels with it.
+        const custom = isPlainObject(task) && isPlainObject(task.capabilities) ? task.capabilities.custom : undefined;
+        const control = Array.isArray(custom) ? custom.filter(isPlainObject).find(entry => entry.id === command.name) : undefined;
+        if (control === undefined) {
+            into.add("command.capability.custom", path, `custom ${describeValue(command.name)} presses a control the task never published`);
+            return into.violations;
+        }
+        if (isPlainObject(control.ui) && control.ui.control === "toggle") {
+            into.require(typeof command.on === "boolean", "command.custom.on", `${path}.on`, "a custom toggle carries the state it wants as a boolean");
+        }
+        if (isPlainObject(control.prompt) && Array.isArray(control.prompt.fields)) {
+            for (const field of control.prompt.fields.filter(isPlainObject)) {
+                if (typeof field.name === "string" && (field.required === true || command[field.name] !== undefined)) {
+                    into.require(typeof command[field.name] === "string" && (field.required !== true || command[field.name].length > 0), "command.custom.prompt", `${path}.${field.name}`, `${field.name} must be a string when supplied, and a required field must have a value`);
+                }
+            }
+        }
+        return into.violations;
+    }
     // What the task has to offer or be in for the command to be issuable.
     const capabilities = isPlainObject(task.capabilities) ? task.capabilities : {};
     const offered = (name) => {
         const declared = capabilities[name];
         if (declared === undefined) {
-            into.add(`command.capability.${name}`, path, `${String(type)} needs the ${name} capability, and the task does not offer it`);
+            into.add(`command.capability.${name}`, path, `${describeValue(type)} needs the ${name} capability, and the task does not offer it`);
             return false;
         }
         if (isLocked(declared)) {
-            into.add("command.capability.locked", path, `${name} stands locked by ${String(declared.lockedBy)}: the control is present without permission`);
+            into.add("command.capability.locked", path, `${name} stands locked by ${describeValue(declared.lockedBy)}: the control is present without permission`);
             return false;
         }
         return true;
     };
-    const inPhase = (rule, ...phases) => into.require(phases.includes(String(task.phase)), rule, path, `${String(type)} belongs to ${phases.join(" or ")}, and the task is ${String(task.phase)}`);
+    const inPhase = (rule, ...phases) => into.require(typeof task.phase === "string" && phases.includes(task.phase), rule, path, `${describeValue(type)} belongs to ${phases.join(" or ")}, and the task is ${describeValue(task.phase)}`);
     // A control on the contact acts on a contact being handled. Before in-progress there is nothing
     // to act on yet, and in completing the handling has ended: a call with nobody on it, a
     // conversation closed. What a capability offers, the phase decides whether there is anything to use it on.
@@ -2101,7 +2134,7 @@ export function validateTaskCommand(command, task, path = "command") {
     const listed = (name) => {
         const declared = capabilities[name];
         const directory = isPlainObject(declared) && Array.isArray(declared.destinations) ? declared.destinations.filter(isPlainObject) : [];
-        into.require(directory.some(item => item.id === command.destinationId), "command.destination.unknown", `${path}.destinationId`, `${String(command.destinationId)} is not a destination the task's ${name} directory offered`);
+        into.require(directory.some(item => item.id === command.destinationId), "command.destination.unknown", `${path}.destinationId`, `${describeValue(command.destinationId)} is not a destination the task's ${name} directory offered`);
     };
     const onCall = Array.isArray(task.onCall) ? task.onCall.filter(isPlainObject) : [];
     switch (type) {
@@ -2144,7 +2177,7 @@ export function validateTaskCommand(command, task, path = "command") {
                     listed("warmTransfer");
             }
             else if (command.action === "complete" || command.action === "cancel") {
-                into.require(onCall.some(entry => entry.role === "consulted"), "command.transfer.consulted", path, `${String(command.action)} needs a consulted entry on onCall: without one there is nothing to complete or cancel`);
+                into.require(onCall.some(entry => entry.role === "consulted"), "command.transfer.consulted", path, `${describeValue(command.action)} needs a consulted entry on onCall: without one there is nothing to complete or cancel`);
             }
             break;
         case "lead-assist":
@@ -2156,7 +2189,7 @@ export function validateTaskCommand(command, task, path = "command") {
                 }
             }
             else {
-                into.require(task.assisting !== undefined, "command.leadAssist.assisting", path, `${String(command.action)} is the lead's own act on a call they joined: the task carries assisting`);
+                into.require(task.assisting !== undefined, "command.leadAssist.assisting", path, `${describeValue(command.action)} is the lead's own act on a call they joined: the task carries assisting`);
             }
             break;
         case "conference": {
@@ -2170,7 +2203,7 @@ export function validateTaskCommand(command, task, path = "command") {
                     into.require(others.some(entry => entry.role !== "party"), "command.conference.remove.alone", path, "removing the party would leave the agent alone: that is end-call");
                 }
                 else if (isFilled(command.destinationId)) {
-                    into.require(onCall.some(entry => entry.role === "conferenced" && entry.destinationId === command.destinationId), "command.conference.remove.unknown", path, `no conferenced entry on onCall has destinationId ${String(command.destinationId)}`);
+                    into.require(onCall.some(entry => entry.role === "conferenced" && entry.destinationId === command.destinationId), "command.conference.remove.unknown", path, `no conferenced entry on onCall has destinationId ${describeValue(command.destinationId)}`);
                     into.require(others.length > 1, "command.conference.remove.alone", path, "removing the last other person would leave the agent alone: that is end-call");
                 }
             }
@@ -2185,9 +2218,12 @@ export function validateTaskCommand(command, task, path = "command") {
                 into.require(command.disposition === undefined, "command.complete.disposition.unexpected", `${path}.disposition`, "the task declares no dispositions; complete travels with no code");
                 into.require(command.notes === undefined, "command.complete.notes.unexpected", `${path}.notes`, "the task declares no dispositions; complete travels with no notes");
             }
+            else if (dispositions === true) {
+                into.require(command.disposition === undefined, "command.complete.disposition.unexpected", `${path}.disposition`, "a bare dispositions control publishes no code, so complete carries none");
+            }
             else if (isPlainObject(dispositions)) {
                 if (Array.isArray(dispositions.codes) && command.disposition !== undefined) {
-                    into.require(dispositions.codes.some(code => isPlainObject(code) && code.id === command.disposition), "command.complete.disposition.unknown", `${path}.disposition`, `${String(command.disposition)} is not a code the task published`);
+                    into.require(dispositions.codes.some(code => isPlainObject(code) && code.id === command.disposition), "command.complete.disposition.unknown", `${path}.disposition`, `${describeValue(command.disposition)} is not a code the task published`);
                 }
                 if (dispositions.required === true) {
                     into.require(command.disposition !== undefined, "command.complete.disposition.required", `${path}.disposition`, "the task requires a disposition and complete carries none");
@@ -2241,14 +2277,27 @@ export function validateResult(result, method, path = "result", dialId) {
         into.add("result.shape", path, `${method} must answer an object`);
         return into.violations;
     }
+    if (method === "openMedia" && result.status !== "opened") {
+        into.require(result.session === undefined, "result.session.unexpected", `${path}.session`, "only opened carries a media session");
+    }
     if (result.status === statuses.success) {
         into.require(result.failure === undefined, "result.failure.unexpected", `${path}.failure`, `${statuses.success} carries no failure`);
         if (method === "openMedia") {
-            into.require(isPlainObject(result.session), "result.session", `${path}.session`, "opened carries the media session");
+            if (isPlainObject(result.session)) {
+                // Streams may come from another realm, and Node conformance runs have no MediaStream
+                // constructor. Check the boundary shape without claiming to verify live audio.
+                into.require(isPlainObject(result.session.remoteAudio), "result.session.remoteAudio", `${path}.session.remoteAudio`, "an opened session carries its remote audio stream");
+                for (const method of ["setMuted", "close"]) {
+                    into.require(typeof result.session[method] === "function", `result.session.${method}`, `${path}.session.${method}`, `a media session implements ${method}`);
+                }
+            }
+            else {
+                into.add("result.session", `${path}.session`, "opened carries the media session");
+            }
         }
         if (dials) {
             if (into.filled(result.dialId, "result.dialId", `${path}.dialId`, "dialling restates the dialId the host sent") && dialId !== undefined) {
-                into.require(result.dialId === dialId, "result.dialId.mismatch", `${path}.dialId`, `the host dialled ${dialId} and the provider answered for ${String(result.dialId)}`);
+                into.require(result.dialId === dialId, "result.dialId.mismatch", `${path}.dialId`, `the host dialled ${dialId} and the provider answered for ${describeValue(result.dialId)}`);
             }
         }
         else {
@@ -2264,7 +2313,7 @@ export function validateResult(result, method, path = "result", dialId) {
         }
     }
     else {
-        into.add("result.status", `${path}.status`, `${method} answers ${statuses.success} or ${statuses.failure}, not ${String(result.status)}`);
+        into.add("result.status", `${path}.status`, `${method} answers ${statuses.success} or ${statuses.failure}, not ${describeValue(result.status)}`);
     }
     return into.violations;
 }
@@ -2377,7 +2426,7 @@ function validateMonitorControl(value, path, into) {
     }
     value.forEach((mode, index) => {
         if (into.oneOf(mode, MONITOR_MODES, "authentication.capability.team.monitorControl.mode", `${path}[${index}]`) && value.indexOf(mode) !== index) {
-            into.add("authentication.capability.team.monitorControl.unique", `${path}[${index}]`, `duplicate monitor mode: ${String(mode)}`);
+            into.add("authentication.capability.team.monitorControl.unique", `${path}[${index}]`, `duplicate monitor mode: ${describeValue(mode)}`);
         }
     });
     into.require(value.includes("monitor"), "authentication.capability.team.monitorControl.monitor", path, "whisper and barge begin from a monitor: a lead who may listen in any mode may monitor");
@@ -2394,7 +2443,7 @@ function validateAuthenticationFailureInto(value, path, into) {
         return;
     }
     if (into.filled(value.code, "authentication.failure.code", `${path}.code`, "a failure needs a code") && value.code.startsWith("omni.")) {
-        into.require(OMNI_FAILURE_CODES.includes(value.code), "failure.code.unknown", `${path}.code`, `${String(value.code)} is not a failure code this contract defines`);
+        into.require(OMNI_FAILURE_CODES.includes(value.code), "failure.code.unknown", `${path}.code`, `${describeValue(value.code)} is not a failure code this contract defines`);
     }
     into.filled(value.message, "authentication.failure.message", `${path}.message`, "a failure needs a message");
     into.require(typeof value.retryable === "boolean", "authentication.failure.retryable", `${path}.retryable`, "a failure must say whether it is retryable");
@@ -2402,7 +2451,7 @@ function validateAuthenticationFailureInto(value, path, into) {
         into.require(value.retryable === false, "authentication.failure.phone.retryable", `${path}.retryable`, "a phone the platform does not permit for this agent is configuration: trying again does not change it, so the refusal is not retryable");
     }
     if (value.retryAfterMs !== undefined) {
-        into.require(typeof value.retryAfterMs === "number" && value.retryAfterMs >= 0, "authentication.failure.retryAfterMs", `${path}.retryAfterMs`, "retryAfterMs must be a non-negative number when present");
+        into.require(typeof value.retryAfterMs === "number" && Number.isFinite(value.retryAfterMs) && value.retryAfterMs >= 0, "authentication.failure.retryAfterMs", `${path}.retryAfterMs`, "retryAfterMs must be a non-negative number when present");
     }
     if (value.field !== undefined)
         into.filled(value.field, "authentication.failure.field", `${path}.field`, "field names a declared credentials field when present");
@@ -2412,6 +2461,42 @@ export function validateAuthenticationFailure(failure, path = "failure") {
     validateAuthenticationFailureInto(failure, path, into);
     return into.violations;
 }
+function validateAuthenticationChallenge(value, path, into) {
+    if (!isPlainObject(value)) {
+        into.add("authentication.result.challenge", path, "interaction-required carries the challenge to put to the person");
+        return;
+    }
+    into.filled(value.flowId, "authentication.challenge.flowId", `${path}.flowId`, "a challenge names the flow to complete or cancel");
+    if (!into.oneOf(value.method, AUTHENTICATION_METHODS, "authentication.challenge.method", `${path}.method`))
+        return;
+    if (value.method === "browser-sso") {
+        into.filled(value.authorizationUrl, "authentication.challenge.authorizationUrl", `${path}.authorizationUrl`, "browser SSO carries the authorization URL to open");
+        into.oneOf(value.browser, AUTHENTICATION_BROWSERS, "authentication.challenge.browser", `${path}.browser`);
+    }
+    else if (!Array.isArray(value.fields)) {
+        into.add("authentication.challenge.fields", `${path}.fields`, "credentials carries the fields to render");
+    }
+    else {
+        const seen = new Set();
+        value.fields.forEach((field, index) => {
+            const at = `${path}.fields[${index}]`;
+            if (!isPlainObject(field)) {
+                into.add("authentication.challenge.field.shape", at, "a credentials field must be an object");
+                return;
+            }
+            if (into.filled(field.name, "authentication.challenge.field.name", `${at}.name`, "a credentials field needs a name")) {
+                into.require(!seen.has(field.name), "authentication.challenge.field.unique", `${at}.name`, "each credentials field has its own key in the submitted values");
+                seen.add(field.name);
+            }
+            into.filled(field.label, "authentication.challenge.field.label", `${at}.label`, "a credentials field needs a label");
+            into.oneOf(field.type, CREDENTIAL_FIELD_TYPES, "authentication.challenge.field.type", `${at}.type`);
+            if (field.required !== undefined)
+                into.require(typeof field.required === "boolean", "authentication.challenge.field.required", `${at}.required`, "required must be a boolean when present");
+            if (field.autocomplete !== undefined)
+                into.require(typeof field.autocomplete === "string", "authentication.challenge.field.autocomplete", `${at}.autocomplete`, "autocomplete must be a string when present");
+        });
+    }
+}
 /**
  * What `start()` or `complete()` answered: a challenge or a rejection from `start`, a login or a
  * rejection from `complete`. A rejection carries a failure the host can show, and a login is held
@@ -2427,13 +2512,17 @@ export function validateAuthenticationResult(result, method, path = "result", co
         validateAuthenticationFailureInto(result.failure, `${path}.failure`, into);
     }
     else if (method === "start" && result.status === "interaction-required") {
-        into.require(isPlainObject(result.challenge), "authentication.result.challenge", `${path}.challenge`, "interaction-required carries the challenge to put to the person");
+        validateAuthenticationChallenge(result.challenge, `${path}.challenge`, into);
+        into.require(result.failure === undefined, "authentication.failure.unexpected", `${path}.failure`, "an authentication challenge carries no failure");
     }
     else if (method === "complete" && result.status === "authenticated") {
         into.violations.push(...validateAuthenticationState(result, path, context));
     }
     else {
-        into.add("authentication.result.status", `${path}.status`, `${method} answers ${method === "start" ? "interaction-required" : "authenticated"} or rejected, not ${String(result.status)}`);
+        into.add("authentication.result.status", `${path}.status`, `${method} answers ${method === "start" ? "interaction-required" : "authenticated"} or rejected, not ${describeValue(result.status)}`);
+    }
+    if (result.status !== "interaction-required") {
+        into.require(result.challenge === undefined, "authentication.challenge.unexpected", `${path}.challenge`, "only interaction-required carries a challenge");
     }
     return into.violations;
 }

package/guide.md

@@ -1306,7 +1306,7 @@ dropped. An adapter that wanted only a better noun loses a field it never meant
 
 ## Protocol contract rules
 
-Nine rules govern protocol data and behavior.
+Ten rules govern protocol data and behavior.
 
 ### 1. The protocol is authoritative
 
@@ -3181,7 +3181,7 @@ inside Omni.
 
 ## Every dial has an outcome
 
-Four commands place a call: `dial` from the idle dialpad, a blind or consult `transfer`, a
+Five commands place a call: `dial` from the idle dialpad, `call` from preview, a cold or warm `transfer`, a
 `conference` `add`, and `connect-back`. Each is accepted or refused at once, and each then ends later
 and apart from its answer -- the destination picks up, is busy, or never does -- and a dial placed
 late in a call routinely outlives the call. Nothing in between is reported: the wire says
@@ -3979,18 +3979,17 @@ decision or it is not.
 
 ## Real-time media
 
-Every voice provider has media. There is nothing to announce, no capability to declare and no
-endpoint to choose: `channel: "voice"` says audio exists, and **Omni is the device it lands on**.
+Every voice provider has media: `channel: "voice"` says audio exists. Where the agent hears it
+depends on the `phone` the host selected at authentication and connect from the manifest's
+`phones`. On a softphone, audio lands in Omni; on a desk phone, it lands on the handset and Omni
+opens no audio. See **How the agent hears the call**. Media transitions are voice-only;
+chat and email publish none (`event.media.channel`, `stream.taskMedia.channel`).
 
-Other endpoints exist in a deployment — desk phones, the provider's own hardware, whatever the
-platform already rings — and none of them is the agent's. Omni does not enumerate them, map the
-agent onto one, or follow a change made to one. There is no device list, no device selection and
-no device on the snapshot, because there is no choice to record: audio for this agent arrives in
-Omni, and Omni registers the endpoint for it.
+The provider owns signalling and the platform's endpoint configuration. The host selects the
+declared phone mode; it does not enumerate or reconfigure the platform's devices. The selected
+mode stays with the login rather than being inferred from a snapshot or a device failure.
 
-That removes a whole class of state the provider would otherwise own and Omni would have to track,
-and it removes the branch that came with it: no command has to ask where the audio went before
-deciding who performs it. Nor does the audio ever stand in for the task: a task's presence and
+Nor does the audio ever stand in for the task: a task's presence and
 phase follow the provider's reports about the work, and the media — attaching, moving through a
 hold, a consult, a conference or a transfer, and ending — is transient beside it. See **A task is
 never its audio** under **Task allocation lifecycle**.
@@ -4165,7 +4164,7 @@ carries as `audio.input.localAudio`, and absent while that input is `unavailable
 bridges audio without a host-side input may ignore it; one that needs it and finds it absent
 answers `unavailable` with a failure Omni shows the agent.
 
-**When to ask is the provider's word, not Omni's guess.** Omni opens media on `task-media-started`,
+**When to ask is the provider's word, not Omni's guess.** On a softphone login, Omni opens media on `task-media-started`,
 and on a task arriving with `media: "started"` on a snapshot; it closes on `task-media-ended` and
 when the task ends. Between those words, nothing Omni's own senses report — a stream that drops, a
 track that ends — moves the task or its audio.
@@ -4302,7 +4301,7 @@ declared:
 | `lead-assist` with `action: "request"` or `"cancel"` | The `leadAssist` capability. `cancel` needs a request standing -- `Task.leadAssist` with status `requested`. |
 | `lead-assist` with `action: "take-over"` or `"leave"` | The lead's own task, on a call they joined -- `Task.assisting` present. An agent's task never has it, and a provider that receives either without it answers `failed`. |
 | `transfer` with a destination, `conference` with `action: "add"` | Its capability, and a `destinationId` the directory offered: the id Omni sends is the id the provider published (`command.destination.unknown`). |
-| `custom` | A control the task published under `capabilities.custom`, by its `id` (`command.capability.custom`), carrying every field the control's `prompt` asked for (`command.custom.prompt`). |
+| `custom` | A control the task published under `capabilities.custom`, by its `id` (`command.capability.custom`), carrying a non-empty string for each `required` prompt field and strings for any optional fields supplied (`command.custom.prompt`). A toggle carries its target `on` boolean (`command.custom.on`). |
 | Everything else | Its own named capability. |
 
 **A control on the contact belongs to the handling phases**, `in-progress` and `paused`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xema/omni-protocol",
-  "version": "0.1.78",
+  "version": "0.1.79",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,11 @@
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "pnpm run clean && tsc -p tsconfig.json",
-    "test": "tsc -p tsconfig.test.json && vitest run"
+    "typecheck": "tsc -p tsconfig.test.json",
+    "test": "pnpm run typecheck && vitest run",
+    "check:package": "node scripts/check-package.mjs",
+    "check": "pnpm run build && pnpm run test && pnpm run check:package",
+    "prepublishOnly": "pnpm run check"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",