@xema/omni-protocol 0.1.15 → 0.1.17

package/dist/index.d.ts

@@ -247,12 +247,32 @@ export interface AuthenticationSession {
     signOut(): Promise<AuthenticationActionResult>;
     close(): Promise<void>;
 }
+/**
+ * How the host's own audio stands: the microphone Omni captures for the agent, and whether it has
+ * it. Omni facilitates the microphone -- captures it, prompts, retries, tells the agent -- and
+ * does not decide for the adapter what a missing one means. The adapter does what its platform
+ * needs: go not-ready, refuse calls, or carry on because audio lands elsewhere.
+ */
+export type HostMediaState = {
+    status: "ready";
+    localAudio: MediaStream;
+} | {
+    status: "unavailable";
+    failure: ProtocolFailure;
+};
+/** The host's audio, observable for the life of the connection, as authentication is. */
+export interface HostMedia {
+    state(): HostMediaState;
+    subscribe(listener: (state: HostMediaState) => void): Unsubscribe;
+}
 export interface ConnectContext {
     protocolVersion: number;
     /** The session that authenticated this connection. */
     sessionId: string;
     /** Omni-side policy: whether the agent's tasks are accepted without asking them. */
     autoAcceptTasks?: boolean;
+    /** The host's audio. Present on a voice connection; absent on a channel with no media. */
+    media?: HostMedia;
     signal?: AbortSignal;
     log?: (entry: unknown) => void;
 }
@@ -791,7 +811,8 @@ export interface VoiceMediaSession {
 }
 export interface OpenMediaRequest {
     taskId: TaskId;
-    localAudio: MediaStream;
+    /** The agent's microphone as Omni captured it; absent while `HostMediaState` is `unavailable`. */
+    localAudio?: MediaStream;
 }
 export type OpenMediaResult = {
     status: "opened";

package/dist/testing.d.ts

@@ -95,6 +95,20 @@ export declare function assertReconnectWithMissedAssignments<C extends Channel>(
  * both.
  */
 export declare function assertDeniedAndRetriedBreak(approvals: readonly BreakApproval[]): void;
+/** What a stream has said about the tasks it carries, and the rules across events. */
+export declare class TaskStream {
+    private readonly tasks;
+    /** Replaces what is known with a snapshot's tasks, as a snapshot replaces Omni's state. */
+    seed(snapshot: unknown): void;
+    /** Applies one envelope and returns what it may not say given what came before. */
+    apply(envelope: unknown, path?: string): ProtocolViolation[];
+}
+/**
+ * The media follows the task and never decides it. Given a provider's stream -- optionally seeded
+ * with the snapshot it began from -- every task is introduced once, `task-media-ended` names a
+ * task whose work has begun, and what follows it is `completing` or `task-ended`.
+ */
+export declare function assertMediaFollowsTheTask(envelopes: readonly ProviderEventEnvelope[], snapshot?: Snapshot): void;
 /** One provider as the host sees it when freezing a break attempt's participant set. */
 export interface BreakCandidate {
     id: string;

package/dist/testing.js

@@ -1,5 +1,5 @@
 import { browserSessionKey, sameCapabilities, } from "./index.js";
-import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateManifest, validateResult, validateSnapshot, } from "./validation.js";
+import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateHostMediaState, validateManifest, validateResult, validateSnapshot, } from "./validation.js";
 export { ProtocolConformanceError, assertNoViolations } from "./validation.js";
 /**
  * A part of the contract a run may never reach: state nothing obliges an adapter to publish, so
@@ -59,8 +59,11 @@ function observeTask(value, seen) {
     const capabilities = isRecord(value.capabilities) ? value.capabilities : {};
     if (isRecord(capabilities.dispositions))
         seen.add("task.dispositions");
-    if (isRecord(capabilities.blindTransfer) && some(capabilities.blindTransfer.destinations))
-        seen.add("task.destinations");
+    for (const directory of ["blindTransfer", "consultTransfer", "conference"]) {
+        const declared = capabilities[directory];
+        if (isRecord(declared) && some(declared.destinations))
+            seen.add("task.destinations");
+    }
     if (some(capabilities.custom))
         seen.add("task.custom");
 }
@@ -139,6 +142,8 @@ export async function exerciseAdapter(adapter, context, options = {}) {
     const violations = [...validateManifest(adapter.manifest)];
     const events = [];
     const seen = new Set();
+    const stream = new TaskStream();
+    let seeded = false;
     const storedSecrets = new Map();
     const authentication = await adapter.createAuthenticationSession({
         ...context,
@@ -151,6 +156,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
     let connection;
     let unsubscribe;
     let unsubscribeAuthentication;
+    let unsubscribeMedia;
     let authenticationState;
     let login;
     let disconnectWasClean = false;
@@ -173,7 +179,12 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                 throw new Error("unreachable: the exercise has an authenticated login");
             return login;
         };
-        const reader = () => ({ self: current().identity.id, capabilities: current().capabilities });
+        const reader = () => ({
+            self: current().identity.id,
+            capabilities: current().capabilities,
+            sessionId: context.sessionId,
+            autoAcceptTasks: context.autoAcceptTasks ?? true,
+        });
         // 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
         // table does; a missing one is a control the agent would be shown and could never use.
@@ -216,6 +227,14 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                     requireCapabilityMethods(connection, state.capabilities);
             }
         });
+        // The host's media is Omni's output, and a test that hands the adapter a malformed one is
+        // testing a host that cannot exist. Its first state and every later one are validated.
+        if (context.media !== undefined) {
+            violations.push(...validateHostMediaState(context.media.state(), "context.media"));
+            unsubscribeMedia = context.media.subscribe(state => {
+                violations.push(...validateHostMediaState(state, "context.media"));
+            });
+        }
         connection = await adapter.connect(context);
         const live = connection;
         // Dial is declared by presence: the capability object carries a destination policy rather
@@ -229,6 +248,11 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         unsubscribe = connection.subscribe(envelope => {
             observeEvent(envelope, seen);
             violations.push(...validateEventEnvelope(envelope, adapter.manifest, "event", reader()));
+            if (eventNamesUsers(envelope))
+                requireMethod(live, "describeUsers", "an event publishes a UserId");
+            // Cross-event rules apply once the stream has a beginning: the connect snapshot.
+            if (seeded)
+                violations.push(...stream.apply(envelope));
             if (typeof envelope?.id === "string") {
                 if (eventIds.has(envelope.id))
                     return;
@@ -239,6 +263,8 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         const snapshot = await connection.snapshot();
         observeSnapshot(snapshot, seen);
         violations.push(...validateSnapshot(snapshot, adapter.manifest, "snapshot", reader()));
+        stream.seed(snapshot);
+        seeded = true;
         requireCapabilityMethods(live, current().capabilities);
         if (publishesUserIds(snapshot))
             requireMethod(live, "describeUsers", "the snapshot publishes a UserId");
@@ -270,6 +296,12 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         catch {
             clean = false;
         }
+        try {
+            unsubscribeMedia?.();
+        }
+        catch {
+            clean = false;
+        }
         try {
             await connection?.disconnect();
         }
@@ -310,11 +342,29 @@ export async function exerciseAdapter(adapter, context, options = {}) {
 function publishesUserIds(snapshot) {
     if (snapshot?.break?.imposed?.by !== undefined)
         return true;
-    if (Array.isArray(snapshot?.team?.members) && snapshot.team.members.length > 0)
+    if (teamNamesUsers(snapshot?.team))
         return true;
     if (!Array.isArray(snapshot?.tasks))
         return false;
-    return snapshot.tasks.some(task => Array.isArray(task?.handlingHistory) && task.handlingHistory.some(step => step?.by !== undefined));
+    return snapshot.tasks.some(taskNamesUsers);
+}
+const teamNamesUsers = (team) => isRecord(team) && (some(team.members) || some(team.requests));
+const taskNamesUsers = (task) => isRecord(task) && ((Array.isArray(task.handlingHistory) && task.handlingHistory.some(step => isRecord(step) && step.by !== undefined)) ||
+    (isRecord(task.lead) && task.lead.leadId !== undefined) ||
+    isRecord(task.assisting));
+/** Whether an event publishes a `UserId`, on a roster, a task, or the snapshot a reconnect carries. */
+function eventNamesUsers(envelope) {
+    const event = isRecord(envelope) ? envelope.event : undefined;
+    if (!isRecord(event))
+        return false;
+    switch (event.type) {
+        case "snapshot": return publishesUserIds(event.snapshot);
+        case "break-state": return isRecord(event.break) && isRecord(event.break.imposed) && event.break.imposed.by !== undefined;
+        case "task-offered":
+        case "task-updated": return taskNamesUsers(event.task);
+        case "team-updated": return teamNamesUsers(event.team);
+        default: return false;
+    }
 }
 /**
  * `refreshing` carries the identity and capabilities of the login it refreshes. A change to
@@ -490,6 +540,101 @@ export function assertDeniedAndRetriedBreak(approvals) {
         throw new Error(`Break retry scenario must end granted or in effect, ended ${String(last)}`);
     }
 }
+// ---------------------------------------------------------------------------
+// The task stream. Each event is validated on its own; what one event may say about a task
+// depends on what was said before, and only something that watched the whole stream can hold a
+// provider to it. A task is never its audio: media ends only on work that has begun, and what
+// follows the media ending is the work completing or ending, never a phase the audio decided.
+// ---------------------------------------------------------------------------
+const WORK_BEGUN = new Set(["in-progress", "paused", "completing"]);
+/** What a stream has said about the tasks it carries, and the rules across events. */
+export class TaskStream {
+    tasks = new Map();
+    /** Replaces what is known with a snapshot's tasks, as a snapshot replaces Omni's state. */
+    seed(snapshot) {
+        this.tasks.clear();
+        if (!isRecord(snapshot) || !Array.isArray(snapshot.tasks))
+            return;
+        for (const task of snapshot.tasks) {
+            if (isRecord(task) && typeof task.id === "string")
+                this.tasks.set(task.id, { phase: String(task.phase), mediaEnded: false });
+        }
+    }
+    /** Applies one envelope and returns what it may not say given what came before. */
+    apply(envelope, path = "event") {
+        const found = [];
+        const event = isRecord(envelope) ? envelope.event : undefined;
+        if (!isRecord(event))
+            return found;
+        const at = `${path}.event`;
+        const refuse = (rule, where, message) => found.push({ rule, path: where, message });
+        const id = typeof event.taskId === "string" ? event.taskId : isRecord(event.task) && typeof event.task.id === "string" ? event.task.id : undefined;
+        const known = id === undefined ? undefined : this.tasks.get(id);
+        switch (event.type) {
+            case "snapshot":
+                this.seed(event.snapshot);
+                break;
+            case "task-offered":
+                if (id === undefined)
+                    break;
+                if (known !== undefined)
+                    refuse("stream.taskOffered.duplicate", `${at}.task.id`, `${id} is already on the stream; an offer introduces a task once`);
+                this.tasks.set(id, { phase: String(isRecord(event.task) ? event.task.phase : undefined), mediaEnded: false });
+                break;
+            case "task-updated":
+                if (id === undefined)
+                    break;
+                if (known === undefined) {
+                    refuse("stream.taskUpdated.unknown", `${at}.task.id`, `${id} was never offered or carried on a snapshot`);
+                    break;
+                }
+                if (known.mediaEnded) {
+                    const phase = isRecord(event.task) ? String(event.task.phase) : "";
+                    if (phase !== "completing") {
+                        refuse("stream.taskMediaEnded.follow", `${at}.task.phase`, `after its media ended, ${id} completes or ends; ${phase} is a phase the audio does not decide`);
+                    }
+                    known.mediaEnded = phase === "completing" ? false : known.mediaEnded;
+                }
+                known.phase = isRecord(event.task) ? String(event.task.phase) : known.phase;
+                break;
+            case "task-media-ended":
+                if (id === undefined)
+                    break;
+                if (known === undefined) {
+                    refuse("stream.taskMediaEnded.unknown", `${at}.taskId`, `${id} was never offered or carried on a snapshot`);
+                    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`);
+                }
+                known.mediaEnded = true;
+                break;
+            case "task-ended":
+                if (id === undefined)
+                    break;
+                if (known === undefined)
+                    refuse("stream.taskEnded.unknown", `${at}.taskId`, `${id} was never offered or carried on a snapshot`);
+                this.tasks.delete(id);
+                break;
+            default:
+                break;
+        }
+        return found;
+    }
+}
+/**
+ * The media follows the task and never decides it. Given a provider's stream -- optionally seeded
+ * with the snapshot it began from -- every task is introduced once, `task-media-ended` names a
+ * task whose work has begun, and what follows it is `completing` or `task-ended`.
+ */
+export function assertMediaFollowsTheTask(envelopes, snapshot) {
+    const stream = new TaskStream();
+    if (snapshot !== undefined)
+        stream.seed(snapshot);
+    const found = [];
+    envelopes.forEach((envelope, index) => found.push(...stream.apply(envelope, `envelopes[${index}]`)));
+    assertNoViolations(found, "The media follows the task");
+}
 const usableLogin = (status) => status === "authenticated" || status === "refreshing";
 /**
  * The participant set of a break attempt is every connected provider from which the agent can

package/dist/validation.d.ts

@@ -30,10 +30,20 @@ export interface ReaderContext {
      * snapshot carries a roster, nobody else's does, and `requests` need `team.consultControl`.
      */
     capabilities?: SessionCapabilities;
+    /** The login's `sessionId`. A snapshot or event naming another belongs to a login that is gone. */
+    sessionId?: string;
+    /** `ConnectContext.autoAcceptTasks` as sent, absent meaning `true`: whether `task-offered` carries an `acceptanceMode`. */
+    autoAcceptTasks?: boolean;
 }
 export declare function validateTeamRoster(roster: unknown, path?: string, context?: ReaderContext): ProtocolViolation[];
 export declare function validateSnapshot(snapshot: unknown, manifest: unknown, path?: string, context?: ReaderContext): ProtocolViolation[];
 export declare function validateEventEnvelope(envelope: unknown, manifest: unknown, path?: string, context?: ReaderContext): ProtocolViolation[];
+/**
+ * Validates the host's media state as Omni publishes it to an adapter. This is Omni's output, so
+ * the check belongs to the host's own tests and to the harness, which validates whatever media a
+ * test hands the adapter.
+ */
+export declare function validateHostMediaState(state: unknown, path?: string): ProtocolViolation[];
 /** The connection methods whose results `validateResult` knows. */
 export type ResultMethod = "execute" | "dial" | "setCapacity" | "requestBreak" | "commitBreak" | "cancelBreak" | "endBreak" | "executeTeamBreak" | "executeTeamConsult" | "openMedia";
 /**

package/dist/validation.js

@@ -70,6 +70,12 @@ const SNAPSHOT_REASONS = membersOf({
     reconnected: true, "provider-requested": true,
 });
 const SESSION_CAPABILITIES = membersOf({ breaks: true, team: true });
+const MEMBER_BREAKS = membersOf({
+    "awaiting-decision": true, granted: true, "starting-after-task": true,
+});
+const OFFERABLE_PHASES = membersOf({
+    pending: true, confirmed: true, preparing: true,
+});
 const TEAM_CAPABILITIES = membersOf({ breakControl: true, consultControl: true });
 const COMPLETED_BY = membersOf({ agent: true, provider: true });
 const EXPIRABLE_PHASES = membersOf({
@@ -283,7 +289,9 @@ export function validateManifest(manifest, path = "manifest") {
     }
     else {
         methods.forEach((method, index) => {
-            into.oneOf(method, AUTHENTICATION_METHODS, "manifest.authenticationMethod", `${path}.authenticationMethods[${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)}`);
+            }
         });
     }
     if (channelValid)
@@ -331,19 +339,28 @@ function validateDestinationDirectory(value, path, into) {
         return;
     }
     into.require(typeof value.allowManualEntry === "boolean", "task.destinations.allowManualEntry", `${path}.allowManualEntry`, "a directory must say whether manual entry is allowed");
+    // A directory with nothing in it and no typing is a control with nothing to offer.
+    if (value.allowManualEntry === false && !(Array.isArray(value.destinations) && value.destinations.length > 0)) {
+        into.add("task.destinations.offer", path, "a directory with no destinations must allow manual entry, or the control has nothing to offer");
+    }
     if (value.destinations === undefined)
         return;
     if (!Array.isArray(value.destinations)) {
         into.add("task.destinations.list", `${path}.destinations`, "destinations must be an array when present");
         return;
     }
+    const seen = new Set();
     value.destinations.forEach((destination, index) => {
         const at = `${path}.destinations[${index}]`;
         if (!isPlainObject(destination)) {
             into.add("task.destination.shape", at, "each destination must be an object");
             return;
         }
-        into.filled(destination.id, "task.destination.id", `${at}.id`, "a destination needs an id");
+        if (into.filled(destination.id, "task.destination.id", `${at}.id`, "a destination needs an id")) {
+            if (seen.has(destination.id))
+                into.add("task.destination.unique", `${at}.id`, `duplicate destination id: ${destination.id}`);
+            seen.add(destination.id);
+        }
         into.filled(destination.label, "task.destination.label", `${at}.label`, "a destination needs a label");
         into.filled(destination.address, "task.destination.address", `${at}.address`, "a destination needs an address");
         into.oneOf(destination.kind, DESTINATION_KINDS, "task.destination.kind", `${at}.kind`);
@@ -359,6 +376,10 @@ function validateDispositions(value, path, into) {
     if (value.required !== undefined) {
         into.require(typeof value.required === "boolean", "task.dispositions.required", `${path}.required`, "required must be a boolean when present");
     }
+    // A code must be collected before completion, so there must be one to collect.
+    if (value.required === true && !(Array.isArray(value.codes) && value.codes.length > 0)) {
+        into.add("task.dispositions.required.codes", `${path}.codes`, "a required disposition policy must publish at least one code");
+    }
     if (value.notes !== undefined)
         into.oneOf(value.notes, NOTES_POLICIES, "task.dispositions.notes", `${path}.notes`);
     if (value.codes === undefined)
@@ -414,6 +435,7 @@ function validateBrowsers(value, path, into) {
         return;
     }
     const seen = new Set();
+    const names = new Set();
     value.forEach((browser, index) => {
         const at = `${path}[${index}]`;
         if (!isPlainObject(browser)) {
@@ -425,7 +447,13 @@ function validateBrowsers(value, path, into) {
                 into.add("task.browser.unique", `${at}.id`, `duplicate browser id: ${browser.id}`);
             seen.add(browser.id);
         }
-        into.filled(browser.name, "task.browser.name", `${at}.name`, "a browser needs a name");
+        // The name is an input to a `TAB_NAME` isolation scheme: two tabs with one name would
+        // silently share a session.
+        if (into.filled(browser.name, "task.browser.name", `${at}.name`, "a browser needs a name")) {
+            if (names.has(browser.name))
+                into.add("task.browser.name.unique", `${at}.name`, `duplicate browser name: ${browser.name}`);
+            names.add(browser.name);
+        }
         into.filled(browser.purpose, "task.browser.purpose", `${at}.purpose`, "a browser needs a purpose");
         if (into.filled(browser.url, "task.browser.url", `${at}.url`, "a browser needs a url")) {
             let scheme;
@@ -463,13 +491,18 @@ function validateTaskAttributes(value, path, into) {
         into.add("task.attributes.shape", path, "attributes must be an array when present");
         return;
     }
+    const keys = new Set();
     value.forEach((attribute, index) => {
         const at = `${path}[${index}]`;
         if (!isPlainObject(attribute)) {
             into.add("task.attribute.shape", at, "each task attribute must be an object");
             return;
         }
-        into.filled(attribute.key, "task.attribute.key", `${at}.key`, "a task attribute needs a key");
+        if (into.filled(attribute.key, "task.attribute.key", `${at}.key`, "a task attribute needs a key")) {
+            if (keys.has(attribute.key))
+                into.add("task.attribute.unique", `${at}.key`, `duplicate attribute key: ${attribute.key}`);
+            keys.add(attribute.key);
+        }
         if (attribute.label !== undefined) {
             into.filled(attribute.label, "task.attribute.label", `${at}.label`, "a label must not be empty when present");
         }
@@ -509,6 +542,8 @@ function validateHandlingHistory(value, path, into) {
         }
         if (entry.by !== undefined) {
             into.require(isUserId(entry.by), "task.handlingHistory.by", `${at}.by`, "by must be a non-empty user id; omit it when the person cannot be identified");
+            // On `queued` nobody takes part, so there is nothing to name.
+            into.require(entry.step !== "queued", "task.handlingHistory.by.unexpected", `${at}.by`, "a queued step names nobody");
         }
     });
 }
@@ -611,6 +646,15 @@ function validateTaskInto(task, context, path, into) {
         return;
     }
     const allowed = isChannel(context.channel) ? TASK_CAPABILITIES[context.channel] : TASK_CAPABILITIES.voice;
+    // A task that supplies browser definitions declares the capability that shows them, and one
+    // that declares it supplies at least one: the capability puts a panel in the workspace, and a
+    // panel with nothing in it is a control with nothing to offer.
+    if (Array.isArray(task.browsers) && task.browsers.length > 0 && capabilities.browsers !== true) {
+        into.add("task.browsers.capability", `${path}.browsers`, "a task that supplies browsers declares capabilities.browsers");
+    }
+    if (capabilities.browsers === true && Array.isArray(task.browsers) && task.browsers.length === 0) {
+        into.add("task.browsers.required", `${path}.browsers`, "a task that declares capabilities.browsers supplies at least one; with none, omit the capability");
+    }
     for (const [name, declared] of Object.entries(capabilities)) {
         if (declared === undefined)
             continue;
@@ -669,6 +713,10 @@ function validateBreakState(value, path, into) {
             into.filled(value[field], `break.${field}`, `${path}.${field}`, `${field} must not be empty when present`);
         }
     }
+    // The refusal is the reason the control is withdrawn; beside `accepting: true` it explains nothing.
+    if (value.refusedReason !== undefined) {
+        into.require(value.accepting !== true, "break.refusedReason.accepting", `${path}.refusedReason`, "refusedReason is shown when accepting is false; omit it while the agent may ask");
+    }
     if (value.retryAfterMs !== undefined) {
         into.require(typeof value.retryAfterMs === "number" && Number.isFinite(value.retryAfterMs) && value.retryAfterMs >= 0, "break.retryAfterMs", `${path}.retryAfterMs`, "retryAfterMs must be a non-negative number when present");
     }
@@ -678,14 +726,21 @@ function validateBreakState(value, path, into) {
         // break that is not happening.
         into.require(value.approval !== "not-requested", "break.activeReasonId.approval", `${path}.activeReasonId`, "activeReasonId must be omitted when no break is requested or in effect");
     }
-    if (value.imposed !== undefined)
+    if (value.imposed !== undefined) {
         validateImposedBreak(value.imposed, `${path}.imposed`, into);
+        // An imposed break is a break somebody placed; beside `not-requested` there is no break.
+        into.require(value.approval !== "not-requested", "break.imposed.approval", `${path}.imposed`, "an imposed break is a break in progress; not-requested says there is none");
+    }
     if (value.reasons === undefined)
         return;
     if (!Array.isArray(value.reasons)) {
         into.add("break.reasons.shape", `${path}.reasons`, "break reasons must be an array when present");
         return;
     }
+    // A provider that defines no codes omits the field: an empty list is a second spelling of that.
+    if (value.reasons.length === 0) {
+        into.add("break.reasons.empty", `${path}.reasons`, "a provider that defines no reasons omits the field rather than publishing an empty list");
+    }
     const seen = new Set();
     value.reasons.forEach((reason, index) => {
         const at = `${path}.reasons[${index}]`;
@@ -705,6 +760,10 @@ function validateBreakState(value, path, into) {
             into.require(reason.alwaysAvailable === true, "break.reason.alwaysAvailable", `${at}.alwaysAvailable`, "alwaysAvailable is declared by presence: send true or omit it");
         }
     });
+    // The active reason is one of the published ones, or it is a reason Omni cannot name.
+    if (typeof value.activeReasonId === "string" && value.activeReasonId.length > 0) {
+        into.require(seen.has(value.activeReasonId), "break.activeReasonId.known", `${path}.activeReasonId`, `activeReasonId names a reason the provider did not publish: ${value.activeReasonId}`);
+    }
 }
 export function validateTeamRoster(roster, path = "team", context = {}) {
     const into = new Collector();
@@ -780,8 +839,13 @@ function validateTeamRosterInto(roster, path, context, into) {
         into.oneOf(member.availability, TEAM_AVAILABILITIES, "team.member.availability", `${at}.availability`);
         if (member.since !== undefined)
             into.timestamp(member.since, "team.member.since", `${at}.since`);
-        if (member.break !== undefined)
-            into.oneOf(member.break, BREAK_APPROVALS, "team.member.break", `${at}.break`);
+        if (member.break !== undefined) {
+            // Only an outstanding request appears here: `not-requested` is absence, `in-effect` is
+            // `availability: "on-break"`, and a denial never survives to be reported.
+            if (into.oneOf(member.break, MEMBER_BREAKS, "team.member.break", `${at}.break`)) {
+                into.require(member.availability !== "signed-out" && member.availability !== "on-break", "team.member.break.availability", `${at}.break`, "a member on a break or signed out has no request outstanding");
+            }
+        }
     });
 }
 export function validateSnapshot(snapshot, manifest, path = "snapshot", context = {}) {
@@ -792,15 +856,25 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
     }
     const channel = isPlainObject(manifest) && typeof manifest.channel === "string" ? manifest.channel : "voice";
     into.oneOf(snapshot.status, CONNECTION_STATUSES, "snapshot.status", `${path}.status`);
-    into.filled(snapshot.sessionId, "snapshot.sessionId", `${path}.sessionId`, "a snapshot needs the session id it belongs to");
+    if (into.filled(snapshot.sessionId, "snapshot.sessionId", `${path}.sessionId`, "a snapshot needs the session id it belongs to")
+        && context.sessionId !== undefined) {
+        into.require(snapshot.sessionId === context.sessionId, "snapshot.sessionId.mismatch", `${path}.sessionId`, `a snapshot for session ${String(snapshot.sessionId)} on a login whose session is ${context.sessionId}`);
+    }
     validateBreakState(snapshot.break, `${path}.break`, into);
     if (!Array.isArray(snapshot.tasks)) {
         into.add("snapshot.tasks.shape", `${path}.tasks`, "a snapshot must carry a tasks array");
     }
     else {
         const seen = new Set();
+        let assisting;
         snapshot.tasks.forEach((task, index) => {
             validateTaskInto(task, { channel }, `${path}.tasks[${index}]`, into);
+            // A lead assists one call at a time.
+            if (isPlainObject(task) && task.assisting !== undefined) {
+                if (assisting !== undefined)
+                    into.add("snapshot.assisting.single", `${path}.tasks[${index}].assisting`, "a lead assists one call at a time");
+                assisting = index;
+            }
             if (isPlainObject(task) && isTaskId(task.id)) {
                 if (seen.has(task.id))
                     into.add("task.id.unique", `${path}.tasks[${index}].id`, `duplicate task id: ${task.id}`);
@@ -919,7 +993,13 @@ function validateProviderSummary(value, path, into) {
         into.add("event.summary.metrics.shape", `${path}.metrics`, "metrics must be an array when present");
         return;
     }
+    const ids = new Set();
     value.metrics.forEach((metric, index) => {
+        if (isPlainObject(metric) && isFilled(metric.id)) {
+            if (ids.has(metric.id))
+                into.add("event.summary.metric.unique", `${path}.metrics[${index}].id`, `duplicate metric id: ${metric.id}`);
+            ids.add(metric.id);
+        }
         const at = `${path}.metrics[${index}]`;
         if (!isPlainObject(metric)) {
             into.add("event.summary.metric.shape", at, "each metric must be an object");
@@ -938,7 +1018,11 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
     }
     const channel = isPlainObject(manifest) && typeof manifest.channel === "string" ? manifest.channel : "voice";
     into.filled(envelope.id, "event.id", `${path}.id`, "an event needs an id");
-    into.filled(envelope.sessionId, "event.sessionId", `${path}.sessionId`, "an event needs the session id it belongs to");
+    if (into.filled(envelope.sessionId, "event.sessionId", `${path}.sessionId`, "an event needs the session id it belongs to")
+        && context.sessionId !== undefined) {
+        into.require(envelope.sessionId === context.sessionId, "event.sessionId.mismatch", `${path}.sessionId`, `an event for session ${String(envelope.sessionId)} on a login whose session is ${context.sessionId}`);
+    }
+    const idle = isPlainObject(manifest) && isPlainObject(manifest.idleCapabilities) ? manifest.idleCapabilities : {};
     into.timestamp(envelope.occurredAt, "event.occurredAt", `${path}.occurredAt`);
     const event = envelope.event;
     if (!isPlainObject(event)) {
@@ -962,9 +1046,20 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             break;
         case "task-offered":
             validateTaskInto(event.task, { channel }, `${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}`);
+            }
             if (event.acceptanceMode !== undefined) {
                 into.oneOf(event.acceptanceMode, ACCEPTANCE_MODES, "event.taskOffered.acceptanceMode", `${at}.acceptanceMode`);
             }
+            // The mode travels exactly when Omni said tasks may be auto-accepted.
+            if (context.autoAcceptTasks === true) {
+                into.require(event.acceptanceMode !== undefined, "event.taskOffered.acceptanceMode.required", `${at}.acceptanceMode`, "autoAcceptTasks is on, so task-offered carries an acceptanceMode");
+            }
+            else if (context.autoAcceptTasks === false) {
+                into.require(event.acceptanceMode === undefined, "event.taskOffered.acceptanceMode.unexpected", `${at}.acceptanceMode`, "autoAcceptTasks is off, so every task requires agent acceptance and task-offered carries no acceptanceMode");
+            }
             for (const field of ["allocationExpiresAt", "preparationEndsAt"]) {
                 if (event[field] !== undefined)
                     into.timestamp(event[field], `event.taskOffered.${field}`, `${at}.${field}`);
@@ -996,6 +1091,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             validateTeamRosterInto(event.team, `${at}.team`, context, into);
             break;
         case "contacts-updated":
+            into.require(idle.contacts === true, "event.contacts.capability", `${at}.contacts`, "contacts-updated requires the contacts idle capability");
             if (!Array.isArray(event.contacts)) {
                 into.add("event.contacts.shape", `${at}.contacts`, "contacts must be an array");
             }
@@ -1004,11 +1100,20 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             }
             break;
         case "calendar-updated":
+            into.require(idle.calendar === true, "event.calendar.capability", `${at}.scheduledActivities`, "calendar-updated requires the calendar idle capability");
             if (!Array.isArray(event.scheduledActivities)) {
                 into.add("event.calendar.shape", `${at}.scheduledActivities`, "scheduledActivities must be an array");
             }
             else {
-                event.scheduledActivities.forEach((activity, index) => validateScheduledActivityInto(activity, `${at}.scheduledActivities[${index}]`, into));
+                const ids = new Set();
+                event.scheduledActivities.forEach((activity, index) => {
+                    validateScheduledActivityInto(activity, `${at}.scheduledActivities[${index}]`, into);
+                    if (isPlainObject(activity) && isFilled(activity.id)) {
+                        if (ids.has(activity.id))
+                            into.add("activity.id.unique", `${at}.scheduledActivities[${index}].id`, `duplicate activity id: ${activity.id}`);
+                        ids.add(activity.id);
+                    }
+                });
             }
             break;
         default:
@@ -1039,6 +1144,35 @@ function validateFailureInto(value, path, into) {
         into.require(typeof value.retryAfterMs === "number" && Number.isFinite(value.retryAfterMs) && value.retryAfterMs >= 0, "failure.retryAfterMs", `${path}.retryAfterMs`, "retryAfterMs must be a non-negative number when present");
     }
 }
+/**
+ * Validates the host's media state as Omni publishes it to an adapter. This is Omni's output, so
+ * the check belongs to the host's own tests and to the harness, which validates whatever media a
+ * test hands the adapter.
+ */
+export function validateHostMediaState(state, path = "media") {
+    const into = new Collector();
+    if (!isPlainObject(state)) {
+        into.add("media.shape", path, "a host media state must be an object");
+        return into.violations;
+    }
+    if (state.status === "ready") {
+        into.require(typeof state.localAudio === "object" && state.localAudio !== null, "media.localAudio", `${path}.localAudio`, "ready carries the captured microphone");
+        into.require(state.failure === undefined, "media.failure.unexpected", `${path}.failure`, "ready carries no failure");
+    }
+    else if (state.status === "unavailable") {
+        if (state.failure === undefined) {
+            into.add("media.failure.required", `${path}.failure`, "unavailable carries the failure that says why");
+        }
+        else {
+            validateFailureInto(state.failure, `${path}.failure`, into);
+        }
+        into.require(state.localAudio === undefined, "media.localAudio.unexpected", `${path}.localAudio`, "unavailable carries no microphone");
+    }
+    else {
+        into.add("media.status", `${path}.status`, `a host media state is ready or unavailable, not ${String(state.status)}`);
+    }
+    return into.violations;
+}
 // Pinned to the result unions: each method's one success status, and the status that carries a
 // failure. A method added to `Connection` without a row here is a compile error at the call site.
 const RESULT_STATUSES = {
@@ -1155,6 +1289,9 @@ export function validateAuthenticationState(state, path = "authentication") {
     else {
         into.require(state.identity === undefined, "authentication.identity.unexpected", `${path}.identity`, `${state.status} must not carry an identity`);
     }
+    if (state.failure !== undefined) {
+        into.require(state.status === "expired", "authentication.failure.unexpected", `${path}.failure`, "only an expired state may carry a failure");
+    }
     if (state.expiresAt !== undefined) {
         into.require(state.status === "authenticated", "authentication.expiresAt.unexpected", `${path}.expiresAt`, "only an authenticated state may carry an expiry");
         into.timestamp(state.expiresAt, "authentication.expiresAt", `${path}.expiresAt`);

package/guide.md

@@ -245,10 +245,20 @@ type AuthenticationFailure = {
   field?: string;
 };
 
+type HostMediaState =
+  | { status: "ready"; localAudio: MediaStream }
+  | { status: "unavailable"; failure: ProtocolFailure };
+
+type HostMedia = {
+  state(): HostMediaState;
+  subscribe(listener: (state: HostMediaState) => void): Unsubscribe;
+};
+
 type ConnectContext = {
   protocolVersion: number;
   sessionId: string;
   autoAcceptTasks?: boolean;
+  media?: HostMedia;
   signal?: AbortSignal;
   log?: (entry: unknown) => void;
 };
@@ -1491,6 +1501,7 @@ Creates one live provider connection for the signed-in agent.
 | `protocolVersion` | Version negotiated before authentication. Fixed for this login. |
 | `sessionId` | Omni-generated identity for this login. It is the same value passed as `AuthenticationContext.sessionId`, so an adapter can correlate this connection with the session that authenticated it. Stable across transport reconnects and changed only by a new login. |
 | `autoAcceptTasks` | Agent provisioning policy relayed to the provider at login. Treated as `true` when omitted. When `true`, `task-offered` carries an `acceptanceMode`; when `false`, every task requires agent acceptance. |
+| `media` | The host's audio, present on a voice connection: `HostMedia`, observable for the life of the connection. See **Host media**. |
 | `signal` | Optional cancellation signal. Stop startup promptly when aborted and do not begin new work. |
 | `log` | Optional structured logging callback. Never include credentials, tokens, or sensitive contact data. |
 
@@ -1731,7 +1742,7 @@ time. Runtime conformance checks also require the task channel to match its prov
 | `channel` | Channel handling this task. It must equal the source provider's manifest channel. |
 | `taskType` | Required provider-defined source or category of work, such as a voice `Queue Name`, `Mailbox Folder`, `Chat Source`, `Support`, `Billing`, or `Returns`. |
 | `capabilities` | Controls and workspace features available for this specific task. |
-| `browsers` | Named browser definitions for the task workspace; empty when the task does not declare the `browsers` capability. |
+| `browsers` | Named browser definitions for the task workspace: at least one when the task declares the `browsers` capability, empty when it does not. |
 | `contact` | Optional `Contact` for the person or entity on this task. Often a name and one address; a withheld caller ID may leave nothing to send at all. |
 | `phase` | Current canonical task phase: `pending`, `confirmed`, `preparing`, `in-progress`, `paused`, or `completing`. |
 | `reference` | Optional agent-facing reference such as a case, call, conversation, ticket, or message number. It is distinct from the protocol `id`. |
@@ -1789,6 +1800,25 @@ allocation's `acceptanceMode`, moving the task from `pending` to `confirmed`. Th
 subsequent transitions to `preparing` or `in-progress`; Omni does not infer them from the acceptance
 command.
 
+**A task is never its audio.** A voice task is the allocation: the call is offered when it is
+routed to the agent and accepted as `acceptanceMode` dictates, and its presence and phase follow
+the provider's reports about the work — never the audio. Wherever audio moves — an offer, a hold, a
+consult, a conference leg joining or leaving, a transfer, a callback — the media follows
+separately, attaching through `openMedia` and ending with `task-media-ended`. Omni does not ring,
+bridge, or hold a line. How the phone rings, whether it rings at all, and where legs join and leave
+are the adapter's and the platform's, transient, and decide neither when a task exists nor what
+phase it is in.
+
+The line runs between the provider's word and Omni's own senses. `task-media-ended` is the
+provider's report that primary handling ended — a fact about the work, which is why the completion
+allowance starts on it and the callback control appears on it — and Omni follows that report as it
+follows any other. What Omni never does is derive a task's state from its own media session: a
+stream that drops, a track that ends, a transport that disconnects, a microphone that fails, an
+endpoint re-registering change nothing about the task until the provider says so. Structurally:
+`task-media-ended` names a task whose work has begun, what follows it is `completing` or
+`task-ended`, and every task is introduced once — `exerciseAdapter` holds the stream to that from
+the connect snapshot on, and `assertMediaFollowsTheTask` holds any sequence.
+
 #### Completion timing
 
 `completionMode` determines how completion is triggered. With `agent-command`, the provider keeps
@@ -2042,14 +2072,13 @@ browser that used it.
 
 ### Task capabilities
 
-Task capabilities belong to each `Task`. If `hold` is false or omitted on one task, Omni
+Task capabilities belong to each `Task`. If `hold` is omitted on one task, Omni
 must not show or issue hold for that task even if another task from the same provider supports it.
 
 ```ts
 const taskCapabilities = {
   channel: "voice",
   capabilities: {
-    browsers: true,
     hold: true,
     dispositions: true,
   },
@@ -2247,7 +2276,7 @@ nothing while none are being accepted — so they are not published separately.
 | `refusedReason` | Display-ready reason shown when `accepting` is false — a standing gate that applies to everyone. |
 | `decisionReason` | The words whoever decided attached, from `decide.reason`. About one request and one decision, not a standing gate. |
 | `retryAfterMs` | How long until the agent may retry, when the provider can say. |
-| `reasons` | Not-ready codes this provider offers. Omitted when it defines none. |
+| `reasons` | Not-ready codes this provider offers. Omitted when it defines none; an empty list is refused, being a second spelling of the same fact. |
 | `activeReasonId` | The `BreakReason.id` the current break is on. Omitted when there is no break, or when the provider cannot say. |
 | `imposed` | Set when the break was placed on the agent rather than requested. |
 
@@ -2797,26 +2826,50 @@ Omni, and Omni registers the endpoint for it.
 
 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.
+deciding who performs it. 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**.
+
+### Host media
+
+Omni facilitates the microphone and does not take responsibility for its failure. It captures the
+agent's microphone once as the voice connection opens, so the permission prompt lands while the
+agent is signing in rather than over a contact; it prompts, retries on the agent's request, and
+tells the agent what failed. What it does not do is decide for the adapter what a missing
+microphone means. `ConnectContext.media` carries the host's audio as a `HostMedia`, observable for
+the life of the connection the way authentication is:
+
+| State | Contract |
+| --- | --- |
+| `ready` | Omni has the microphone; `localAudio` is it, and the same stream `openMedia` receives. |
+| `unavailable` | Omni does not: permission refused, no device, capture lost. `failure` says which, in words Omni has already shown the agent. |
+
+Omni republishes the state whenever it changes — a permission granted late, a device unplugged —
+and the adapter does what its platform needs. A platform that bridges audio without a host-side
+input carries on; one that needs it may put the agent not-ready with the platform, refuse calls,
+or answer `openMedia` `unavailable` with a failure Omni shows. The choice is the adapter's because
+only the adapter knows where its platform's audio lands.
 
 ### Capacity around setup
 
 Connecting is not the same as being able to take a call. A provider that treats a live connection
-as reachability opens a window where it believes the agent is available and Omni cannot yet carry
-audio — its endpoint unregistered, the microphone permission not yet granted.
+as reachability opens a window where it believes the agent is available and the agent is not yet
+set up — the adapter's own registration incomplete, its credentials not yet renewed.
 
-Nothing closes that window, because nothing opens it: **Omni states no capacity until the agent is
-set up**, and **Work is pulled, never pushed** makes an allocation with none stated a violation. A
-voice connection therefore carries no capacity from the moment it opens until its media is ready,
-and the provider allocates nothing in between.
+Nothing closes that window, because nothing opens it: **Omni states no capacity until the
+connection is established**, and **Work is pulled, never pushed** makes an allocation with none
+stated a violation. Capacity does not wait on the microphone: whether an agent without host audio
+can take calls is the platform's question, answered by the adapter from **Host media**, not by
+Omni withholding capacity for every platform alike.
 
-Capacity follows **automatically** once setup completes; the agent does not press anything to
-become available.
+Capacity follows **automatically** once the connection is established; the agent does not press
+anything to become available.
 
 | Situation | What Omni sends |
 | --- | --- |
-| Connected, media not ready | Nothing. No capacity has been stated, so nothing may be allocated. |
-| Set up and idle | `setCapacity({ count: n })` |
+| Connecting | Nothing. No capacity has been stated, so nothing may be allocated. |
+| Connected and idle | `setCapacity({ count: n })`, and the host media state alongside it. |
 | A task starts or ends | Nothing. The provider counts its own against the ceiling. |
 | The agent's provisioned capacity changes | `setCapacity({ count: n })` |
 | Agent asks for a break | `requestBreak`. Capacity is unchanged and work continues. |
@@ -2842,7 +2895,8 @@ The adapter speaks whatever its platform speaks — SIP over WebSocket, a vendor
 WebRTC — and **none of that appears in this contract**. Registration, signalling, credential
 renewal and reconnect are the adapter's, exactly as its authentication and transport already
 are. Omni owns what belongs to the host: the microphone, the output element, mute, and when a
-session ends.
+session ends — owning the microphone meaning capturing it, prompting, retrying and saying how it
+stands, never deciding for the adapter what a missing one means (see **Host media**).
 
 | Member | Contract |
 | --- | --- |
@@ -2850,9 +2904,10 @@ session ends.
 | `setMuted(muted)` | Mutes the agent's microphone on this session. |
 | `close()` | Releases the session. Omni calls it when the task ends. |
 
-`localAudio` is the agent's microphone, captured once by Omni as the voice connection opens so the
-permission prompt lands while the agent is signing in rather than over a ringing contact. A
-provider that bridges audio without a host-side input may ignore it.
+`localAudio` is the agent's microphone as Omni captured it, the same stream **Host media** reports,
+and absent while that state is `unavailable`. A provider that 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.
 
 **A task-scoped session does not oblige one call per task.** A platform holding a nailed-up
 leg for a whole shift may return the same session for every task and release the underlying
@@ -3182,6 +3237,7 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | `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. |
 | `validateScheduledActivity(activity)` | Required activity fields and start/end ordering. |
+| `validateHostMediaState(state)` | The host's own media state as published to an adapter: `ready` with the microphone, or `unavailable` with the failure that says why. The harness validates whatever media a test hands the adapter. |
 | `validateResult(result, method)` | What a connection method answered: the status it gives, a failure where the status says so and nowhere else, the failure's shape, and that an `omni.` code is one this contract names. |
 | `validateAuthenticationState(state)` | The identity each state must carry, the capabilities a usable login declares, and the expiry that only `authenticated` may. |
 
@@ -3268,6 +3324,7 @@ cannot be established from TypeScript structure alone.
 | `assertReached(result, subjects)` | The exercise met every subject named; throws listing those it did not. Pair it with a clean `exerciseAdapter` result. |
 | `assertAuthenticationRestoreAndExpiry(states)` | A restored authenticated session can refresh and ends in expiry. Every state is validated. |
 | `assertReconnectWithMissedAssignments(before, reconnect, ids)` | A reconnect snapshot restores assignments received while offline. |
+| `assertMediaFollowsTheTask(envelopes, snapshot?)` | The media follows the task and never decides it: every task is introduced once, `task-media-ended` names a task whose work has begun, and what follows it is `completing` or `task-ended`. The harness applies the same rules to every event after the connect snapshot (`stream.*`). |
 | `assertBreakParticipants(candidates, participants)` | A break attempt asks every usable provider holding capacity, `refreshing` included, and nothing of a provider whose login is `expired`. |
 | `assertBreakBeginsAfterTask(steps)` | A break asked for on a task is committed as `starting-after-task` while work remains and reaches `in-effect` only once nothing is outstanding — never beside a task, never later than the step that has none. |
 | `assertDeniedAndRetriedBreak(states)` | A denial transitions directly to `not-requested`; a later request can still be granted. |

package/package.json

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