@xema/omni-protocol 0.1.16 → 0.1.18

package/README.md

@@ -65,6 +65,7 @@ clean result is read for what it covers and not for the whole contract; `assertR
 subjects)` is the paired assertion.
 
 ```ts
+const context = { protocolVersion: OMNI_PROTOCOL_VERSION, sessionId: "session-1", host: stillHost(report) };
 const result = await exerciseAdapter(adapter, context, { collectOnly: true });
 expect(result.violations).toEqual([]);
 expect(result.disconnectWasClean).toBe(true);

package/dist/index.d.ts

@@ -247,12 +247,69 @@ 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 HostAudioInput = 
+/** Omni has the microphone. `flowing` is false while the hardware or OS says no audio moves through it. */
+{
+    status: "ready";
+    localAudio: MediaStream;
+    flowing: boolean;
+}
+/** Omni does not, and `reason` says which fix the agent needs; `failure` is the words Omni showed them. */
+ | {
+    status: "unavailable";
+    reason: HostAudioUnavailableReason;
+    failure: ProtocolFailure;
+};
+/**
+ * Why the host has no microphone, each wanting a different fix from the agent: no device;
+ * permission refused; permission never asked for (a host that asks at connect never says this);
+ * a device present and permitted that another application holds; a capture that ended.
+ */
+export type HostAudioUnavailableReason = "no-device" | "denied" | "not-asked" | "in-use" | "lost";
+/** Why the host has no speaker: no device, or one that was removed. */
+export type HostOutputUnavailableReason = "no-device" | "lost";
+export type HostAudioOutput = {
+    status: "ready";
+} | {
+    status: "unavailable";
+    reason: HostOutputUnavailableReason;
+    failure: ProtocolFailure;
+};
+/**
+ * What only the host can see about the agent's station: the devices, the permissions, the
+ * network. Omni reports it; the adapter decides what any of it means for its platform and what
+ * to relay. `audio` is present on a voice connection.
+ */
+export interface HostReport {
+    /** Whether the host has a network interface up. Not a claim that anything is reachable: the adapter knows its own platform's reachability better than the host does. */
+    online: boolean;
+    audio?: {
+        input: HostAudioInput;
+        output: HostAudioOutput;
+    };
+}
+/** The host, as an adapter may ask it: a report now, and every change for the life of the connection. */
+export interface Host {
+    report(): HostReport;
+    subscribe(listener: (report: HostReport) => 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 report of the agent's station, to consult before declaring the agent ready to the
+     * platform and whenever it changes. Omni reports; the adapter decides.
+     */
+    host: Host;
     signal?: AbortSignal;
     log?: (entry: unknown) => void;
 }
@@ -791,7 +848,8 @@ export interface VoiceMediaSession {
 }
 export interface OpenMediaRequest {
     taskId: TaskId;
-    localAudio: MediaStream;
+    /** The agent's microphone as Omni captured it, `HostReport.audio.input.localAudio`; absent while that input is `unavailable`. */
+    localAudio?: MediaStream;
 }
 export type OpenMediaResult = {
     status: "opened";

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Snapshot, type TaskCompletion, type BreakApproval, type BrowserSessionKeyInput, type Channel, type ConnectContext, type Manifest, type ProviderEvent } from "./index.js";
+import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Snapshot, type TaskCompletion, type BreakApproval, type BrowserSessionKeyInput, type Channel, type ConnectContext, type Host, type HostReport, type Manifest, type ProviderEvent } from "./index.js";
 import { type ProtocolViolation } from "./validation.js";
 export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation } from "./validation.js";
 /**
@@ -95,6 +95,36 @@ 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[];
+}
+/** What a stream has said about the agent's break, and the moves it may not make. */
+export declare class BreakStream {
+    private approval;
+    /** Takes the break state a snapshot carries as the point the stream continues from. */
+    seed(snapshot: unknown): void;
+    /** Applies one envelope and returns the moves it may not make given where the break stood. */
+    apply(envelope: unknown, path?: string): ProtocolViolation[];
+}
+/**
+ * A break follows its requests. Given a provider's stream -- optionally seeded with the snapshot
+ * it began from -- every `break-state` moves the way the guide describes: a commit's states only
+ * after a grant, never backwards, and a break placed on the agent arriving in effect with `imposed`.
+ */
+export declare function assertBreakFollowsItsRequests(envelopes: readonly ProviderEventEnvelope[], snapshot?: Snapshot): void;
+/**
+ * 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;
+/** A host that reports one thing and never changes: what most adapter tests hand `exerciseAdapter`. */
+export declare function stillHost(report?: HostReport): Host;
 /** 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, validateHostReport, 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
@@ -142,6 +142,9 @@ export async function exerciseAdapter(adapter, context, options = {}) {
     const violations = [...validateManifest(adapter.manifest)];
     const events = [];
     const seen = new Set();
+    const stream = new TaskStream();
+    const breaks = new BreakStream();
+    let seeded = false;
     const storedSecrets = new Map();
     const authentication = await adapter.createAuthenticationSession({
         ...context,
@@ -154,6 +157,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
     let connection;
     let unsubscribe;
     let unsubscribeAuthentication;
+    let unsubscribeHost;
     let authenticationState;
     let login;
     let disconnectWasClean = false;
@@ -224,7 +228,28 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                     requireCapabilityMethods(connection, state.capabilities);
             }
         });
-        connection = await adapter.connect(context);
+        // The host's report is Omni's output, and a test that hands the adapter a malformed one is
+        // testing a host that cannot exist. Its first report and every later one are validated, a
+        // voice connection's host reports its audio and no other does, and the host the adapter
+        // receives is wrapped so the harness can tell whether the adapter ever asked.
+        const first = context.host.report();
+        violations.push(...validateHostReport(first, "context.host"));
+        const hasAudio = isRecord(first) && first.audio !== undefined;
+        if (adapter.manifest.channel === "voice" && !hasAudio) {
+            violations.push({ rule: "context.host.audio.required", path: "context.host.audio", message: "a voice connection's host reports its audio" });
+        }
+        if (adapter.manifest.channel !== "voice" && hasAudio) {
+            violations.push({ rule: "context.host.audio.unexpected", path: "context.host.audio", message: `a ${adapter.manifest.channel} connection has no audio for the host to report` });
+        }
+        unsubscribeHost = context.host.subscribe(report => {
+            violations.push(...validateHostReport(report, "context.host"));
+        });
+        let consulted = false;
+        const host = {
+            report: () => { consulted = true; return context.host.report(); },
+            subscribe: listener => { consulted = true; return context.host.subscribe(listener); },
+        };
+        connection = await adapter.connect({ ...context, host });
         const live = connection;
         // Dial is declared by presence: the capability object carries a destination policy rather
         // than an `enabled` flag, so its presence is the declaration.
@@ -239,6 +264,9 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             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), ...breaks.apply(envelope));
             if (typeof envelope?.id === "string") {
                 if (eventIds.has(envelope.id))
                     return;
@@ -249,11 +277,23 @@ 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);
+        breaks.seed(snapshot);
+        seeded = true;
         requireCapabilityMethods(live, current().capabilities);
         if (publishesUserIds(snapshot))
             requireMethod(live, "describeUsers", "the snapshot publishes a UserId");
         // Capacity is stated, not requested: nothing may be allocated until it is, so a connection
         // that will not accept one is a connection nothing can be given to.
+        // The guide's obligation on a voice adapter: consult the host before declaring the agent
+        // ready, and on every change. An adapter that never asked cannot have.
+        if (adapter.manifest.channel === "voice" && !consulted) {
+            violations.push({
+                rule: "connection.host.consulted",
+                path: "connection.host",
+                message: "a voice adapter consults the host's report before declaring the agent ready, and this one never asked",
+            });
+        }
         const capacity = await connection.setCapacity({ count: 1 });
         const malformed = validateResult(capacity, "setCapacity", "connection.setCapacity");
         violations.push(...malformed);
@@ -280,6 +320,12 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         catch {
             clean = false;
         }
+        try {
+            unsubscribeHost?.();
+        }
+        catch {
+            clean = false;
+        }
         try {
             await connection?.disconnect();
         }
@@ -518,6 +564,168 @@ 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;
+    }
+}
+// A request goes not-requested -> awaiting-decision | granted; a commit goes granted ->
+// starting-after-task | in-effect; work ending goes starting-after-task -> in-effect; a denial,
+// a cancel, an end or a release goes back to not-requested; a placed break arrives in-effect
+// with `imposed`. Nothing else is a move the guide describes.
+const COMMITTED = new Set(["starting-after-task", "in-effect"]);
+const BACKWARDS = {
+    "in-effect": ["awaiting-decision", "granted", "starting-after-task"],
+    "starting-after-task": ["awaiting-decision", "granted"],
+    granted: ["awaiting-decision"],
+};
+/** What a stream has said about the agent's break, and the moves it may not make. */
+export class BreakStream {
+    approval;
+    /** Takes the break state a snapshot carries as the point the stream continues from. */
+    seed(snapshot) {
+        const state = isRecord(snapshot) ? snapshot.break : undefined;
+        this.approval = isRecord(state) && typeof state.approval === "string" ? state.approval : undefined;
+    }
+    /** Applies one envelope and returns the moves it may not make given where the break stood. */
+    apply(envelope, path = "event") {
+        const found = [];
+        const event = isRecord(envelope) ? envelope.event : undefined;
+        if (!isRecord(event))
+            return found;
+        if (event.type === "snapshot") {
+            this.seed(event.snapshot);
+            return found;
+        }
+        if (event.type !== "break-state" || !isRecord(event.break) || typeof event.break.approval !== "string")
+            return found;
+        const from = this.approval;
+        const to = event.break.approval;
+        const at = `${path}.event.break.approval`;
+        if (from !== undefined) {
+            // A commit's states need a grant behind them. A placed break is the one arrival in a
+            // committed state that nobody asked for -- in effect at once, or starting-after-task while
+            // the member finishes a call -- and it says so with `imposed`.
+            if (COMMITTED.has(to) && (from === "not-requested" || from === "awaiting-decision") && event.break.imposed === undefined) {
+                found.push({ rule: "stream.breakState.commitBeforeGrant", path: at,
+                    message: `${to} follows a commit, and a commit follows granted; the break stood at ${from}` });
+            }
+            if ((BACKWARDS[from] ?? []).includes(to)) {
+                found.push({ rule: "stream.breakState.backwards", path: at,
+                    message: `a break does not go from ${from} back to ${to}; a new request passes through not-requested` });
+            }
+        }
+        this.approval = to;
+        return found;
+    }
+}
+/**
+ * A break follows its requests. Given a provider's stream -- optionally seeded with the snapshot
+ * it began from -- every `break-state` moves the way the guide describes: a commit's states only
+ * after a grant, never backwards, and a break placed on the agent arriving in effect with `imposed`.
+ */
+export function assertBreakFollowsItsRequests(envelopes, snapshot) {
+    const stream = new BreakStream();
+    if (snapshot !== undefined)
+        stream.seed(snapshot);
+    const found = [];
+    envelopes.forEach((envelope, index) => found.push(...stream.apply(envelope, `envelopes[${index}]`)));
+    assertNoViolations(found, "A break follows its requests");
+}
+/**
+ * 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");
+}
+/** A host that reports one thing and never changes: what most adapter tests hand `exerciseAdapter`. */
+export function stillHost(report = { online: true }) {
+    return { report: () => report, subscribe: () => () => undefined };
+}
 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

@@ -38,6 +38,12 @@ export interface ReaderContext {
 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 report 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 host a test
+ * hands the adapter.
+ */
+export declare function validateHostReport(report: 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

@@ -1144,6 +1144,72 @@ 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");
     }
 }
+const HOST_AUDIO_REASONS = membersOf({ "no-device": true, denied: true, "not-asked": true, "in-use": true, lost: true });
+const HOST_OUTPUT_REASONS = membersOf({ "no-device": true, lost: true });
+function validateUnavailable(value, rule, path, into) {
+    if (value.failure === undefined) {
+        into.add(`${rule}.failure.required`, `${path}.failure`, "unavailable carries the failure that says why");
+    }
+    else {
+        validateFailureInto(value.failure, `${path}.failure`, into);
+    }
+}
+/**
+ * Validates the host's report 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 host a test
+ * hands the adapter.
+ */
+export function validateHostReport(report, path = "host") {
+    const into = new Collector();
+    if (!isPlainObject(report)) {
+        into.add("host.shape", path, "a host report must be an object");
+        return into.violations;
+    }
+    into.require(typeof report.online === "boolean", "host.online", `${path}.online`, "a host report says whether it has a network");
+    if (report.audio === undefined)
+        return into.violations;
+    if (!isPlainObject(report.audio)) {
+        into.add("host.audio.shape", `${path}.audio`, "audio must be an object when present, with input and output");
+        return into.violations;
+    }
+    const input = report.audio.input;
+    const at = `${path}.audio.input`;
+    if (!isPlainObject(input)) {
+        into.add("host.audio.input.shape", at, "audio carries its input");
+    }
+    else if (input.status === "ready") {
+        into.require(typeof input.localAudio === "object" && input.localAudio !== null, "host.audio.input.localAudio", `${at}.localAudio`, "a ready input carries the captured microphone");
+        into.require(typeof input.flowing === "boolean", "host.audio.input.flowing", `${at}.flowing`, "a ready input says whether audio is flowing through it");
+        into.require(input.failure === undefined, "host.audio.input.failure.unexpected", `${at}.failure`, "a ready input carries no failure");
+        into.require(input.reason === undefined, "host.audio.input.reason.unexpected", `${at}.reason`, "a ready input has no reason to be unavailable");
+    }
+    else if (input.status === "unavailable") {
+        into.oneOf(input.reason, HOST_AUDIO_REASONS, "host.audio.input.reason", `${at}.reason`);
+        validateUnavailable(input, "host.audio.input", at, into);
+        into.require(input.localAudio === undefined, "host.audio.input.localAudio.unexpected", `${at}.localAudio`, "an unavailable input carries no microphone");
+        into.require(input.flowing === undefined, "host.audio.input.flowing.unexpected", `${at}.flowing`, "an unavailable input has nothing to flow");
+    }
+    else {
+        into.add("host.audio.input.status", `${at}.status`, `an input is ready or unavailable, not ${String(input.status)}`);
+    }
+    const output = report.audio.output;
+    const out = `${path}.audio.output`;
+    if (!isPlainObject(output)) {
+        into.add("host.audio.output.shape", out, "audio carries its output");
+    }
+    else if (output.status === "ready") {
+        into.require(output.failure === undefined, "host.audio.output.failure.unexpected", `${out}.failure`, "a ready output carries no failure");
+        into.require(output.reason === undefined, "host.audio.output.reason.unexpected", `${out}.reason`, "a ready output has no reason to be unavailable");
+    }
+    else if (output.status === "unavailable") {
+        into.oneOf(output.reason, HOST_OUTPUT_REASONS, "host.audio.output.reason", `${out}.reason`);
+        validateUnavailable(output, "host.audio.output", out, into);
+    }
+    else {
+        into.add("host.audio.output.status", `${out}.status`, `an output is ready or unavailable, not ${String(output.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 = {

package/guide.md

@@ -245,10 +245,35 @@ type AuthenticationFailure = {
   field?: string;
 };
 
+type HostAudioUnavailableReason = "no-device" | "denied" | "not-asked" | "in-use" | "lost";
+type HostOutputUnavailableReason = "no-device" | "lost";
+
+type HostAudioInput =
+  | { status: "ready"; localAudio: MediaStream; flowing: boolean }
+  | { status: "unavailable"; reason: HostAudioUnavailableReason; failure: ProtocolFailure };
+
+type HostAudioOutput =
+  | { status: "ready" }
+  | { status: "unavailable"; reason: HostOutputUnavailableReason; failure: ProtocolFailure };
+
+type HostReport = {
+  online: boolean;
+  audio?: {
+    input: HostAudioInput;
+    output: HostAudioOutput;
+  };
+};
+
+type Host = {
+  report(): HostReport;
+  subscribe(listener: (report: HostReport) => void): Unsubscribe;
+};
+
 type ConnectContext = {
   protocolVersion: number;
   sessionId: string;
   autoAcceptTasks?: boolean;
+  host: Host;
   signal?: AbortSignal;
   log?: (entry: unknown) => void;
 };
@@ -1491,6 +1516,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. |
+| `host` | The host's report of the agent's station — devices, permissions, network — to consult before declaring the agent ready to the platform, and on every change. See **The host reports, the adapter decides**. |
 | `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. |
 
@@ -1671,6 +1697,7 @@ automatic or requires the agent. A provider that requires automatic acceptance s
 declare const task: Task;
 
 const allocation = {
+  type: "task-offered",
   task,
   acceptanceMode: "require-agent-acceptance",
   allocationExpiresAt: "2026-08-25T10:41:07.000Z",
@@ -1789,6 +1816,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
@@ -2796,26 +2842,61 @@ 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**.
+
+### The host reports, the adapter decides
+
+The adapter runs inside Omni and sees nothing of the station for itself: the devices, the
+permissions, the audio element and the network are the host's, and only the host can tell. So
+the host reports, and the adapter asks. **An adapter consults `ConnectContext.host` before it
+declares the agent ready to its platform, and again whenever the report changes**, and it decides
+what any of it means and what to relay upstream — go not-ready, refuse calls, carry on because the
+platform's audio lands elsewhere. Omni facilitates and does not take responsibility: it captures
+the microphone once as the voice connection opens, so the permission prompt lands while the agent
+is signing in rather than over a contact, prompts, retries on the agent's request, tells the agent
+what failed, and reports. It never decides for the adapter what a missing microphone means.
+
+| Field | Contract |
+| --- | --- |
+| `online` | Whether the host has a network interface up. Not a claim that anything is reachable — the adapter knows whether it can reach its own platform far better than the host does — so `false` is a reason not to go ready and `true` is not a reason to. |
+| `audio` | Present on a voice connection, absent where there is no audio. |
+| `audio.input` | `ready` with `localAudio` — the microphone as captured, the same stream `openMedia` receives — and `flowing`, false while the hardware or OS says no audio moves through it (a headset's own mute switch, which Omni's Mute control never touches). `unavailable` with `reason`, since each wants a different fix from the agent: `no-device`; `denied`; `not-asked`, which a host that asks at connect never publishes; `in-use`, a device present and permitted that another application holds — on an agent desktop the commonest of all; `lost`, a capture that ended. `failure` carries the words Omni showed them. |
+| `audio.output` | `ready`, or `unavailable` with `reason` — `no-device`, or `lost` for one removed — and `failure`: an agent who cannot hear is as unable to take a call as one who cannot speak. |
+
+Omni republishes the report whenever it changes — a permission granted late, a headset unplugged,
+a network gone — and it publishes a state, not a flicker: a change that resolves within moments is
+not reported, so an adapter may act on what it reads without debouncing it again. Nothing in the
+report is a task fact or a capacity fact; it is what the station can do, and the adapter's platform
+is the one that knows whether an agent without a microphone, or without a speaker, can work.
+
+The host's own obligations here — asking at connect, never publishing `not-asked` when it does,
+publishing a state and not a flicker — are Omni's tests' to hold. `exerciseAdapter` holds the
+other side: it validates the shape of whatever host a test hands the adapter, requires `audio` on
+a voice connection and none elsewhere (`context.host.audio.required` / `.unexpected`), and
+refuses a voice adapter that never asked the host anything (`connection.host.consulted`).
 
 ### 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 the host's report, 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 })`, with the host's report already available to consult. |
 | 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. |
@@ -2841,7 +2922,9 @@ 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 reporting how
+it stands, never deciding for the adapter what a missing one means (see **The host reports, the
+adapter decides**).
 
 | Member | Contract |
 | --- | --- |
@@ -2849,9 +2932,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 the host's report
+carries as `audio.input.localAudio`, and absent while that input 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
@@ -3064,6 +3148,15 @@ Replaces this provider's complete `break` object. Its `approval` uses the canoni
 `in-effect` states defined under Breaks; the event also carries the corresponding accepting state,
 reasons, retry details, and any imposed break.
 
+Each state is also held to the one before it. A commit's states, `starting-after-task` and
+`in-effect`, follow a grant — the one arrival in a committed state nobody asked for is a placed
+break, which says so with `imposed`: in effect at once, or `starting-after-task` while the member
+finishes the call they are on (`stream.breakState.commitBeforeGrant`); and a break never moves backwards —
+from `in-effect` or `starting-after-task` to a grant or a request, or from `granted` to
+`awaiting-decision` — a new request passes through `not-requested` (`stream.breakState.backwards`).
+`exerciseAdapter` holds the stream to that from the connect snapshot on;
+`assertBreakFollowsItsRequests` holds any sequence.
+
 For a multi-provider attempt, "every provider" is the participant set frozen when the attempt
 entered `requesting-break`. Omni commits only after every participant reports `granted` —
 that one is unconditional, because nothing has stopped yet and waiting costs only time. It enters
@@ -3181,6 +3274,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. |
+| `validateHostReport(report)` | The host's own report as published to an adapter: `online`, and where there is audio, an input that is `ready` with the microphone and `flowing`, or `unavailable` with a reason and the failure that says why, and an output that is `ready` or `unavailable` with its failure. The harness validates whatever host a test hands the adapter; `stillHost(report)` builds one that never changes. |
 | `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. |
 
@@ -3267,6 +3361,10 @@ 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. |
+| `stillHost(report?)` | A host that reports one thing and never changes, for a test context: `{ online: true }` by default, a report with audio for a voice adapter. |
+| `TaskStream`, `BreakStream` | The cross-event models the harness applies after the connect snapshot, exported for a host that wants the same rules at its boundary: `seed(snapshot)`, then `apply(envelope)` returns the violations. |
+| `assertBreakFollowsItsRequests(envelopes, snapshot?)` | A break follows its requests: a commit's states only after a grant, never backwards, and a placed break arriving in effect with `imposed`. The harness applies the same rules after the connect snapshot. |
+| `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.*`). A sequence with no media satisfies it by never testing it — pair it with the assertion that the media end is present. |
 | `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.16",
+  "version": "0.1.18",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",