@xema/omni-protocol 0.1.17 → 0.1.19

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

@@ -253,17 +253,51 @@ export interface AuthenticationSession {
  * 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 = {
+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;
 };
-/** 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;
+/**
+ * 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;
@@ -271,8 +305,11 @@ export interface ConnectContext {
     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;
+    /**
+     * 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;
 }
@@ -811,7 +848,7 @@ export interface VoiceMediaSession {
 }
 export interface OpenMediaRequest {
     taskId: TaskId;
-    /** The agent's microphone as Omni captured it; absent while `HostMediaState` is `unavailable`. */
+    /** The agent's microphone as Omni captured it, `HostReport.audio.input.localAudio`; absent while that input is `unavailable`. */
     localAudio?: MediaStream;
 }
 export type OpenMediaResult = {

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";
 /**
@@ -103,12 +103,28 @@ export declare class TaskStream {
     /** 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, validateHostMediaState, 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
@@ -143,6 +143,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
     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({
@@ -156,7 +157,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
     let connection;
     let unsubscribe;
     let unsubscribeAuthentication;
-    let unsubscribeMedia;
+    let unsubscribeHost;
     let authenticationState;
     let login;
     let disconnectWasClean = false;
@@ -227,15 +228,28 @@ 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"));
-            });
+        // 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` });
         }
-        connection = await adapter.connect(context);
+        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.
@@ -252,7 +266,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                 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));
+                violations.push(...stream.apply(envelope), ...breaks.apply(envelope));
             if (typeof envelope?.id === "string") {
                 if (eventIds.has(envelope.id))
                     return;
@@ -264,12 +278,22 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         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);
@@ -297,7 +321,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             clean = false;
         }
         try {
-            unsubscribeMedia?.();
+            unsubscribeHost?.();
         }
         catch {
             clean = false;
@@ -622,6 +646,69 @@ export class TaskStream {
         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
@@ -635,6 +722,10 @@ export function assertMediaFollowsTheTask(envelopes, snapshot) {
     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

@@ -39,11 +39,11 @@ export declare function validateTeamRoster(roster: unknown, path?: string, conte
 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.
+ * 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 validateHostMediaState(state: unknown, path?: string): ProtocolViolation[];
+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,32 +1144,69 @@ 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 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.
+ * 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 validateHostMediaState(state, path = "media") {
+export function validateHostReport(report, path = "host") {
     const into = new Collector();
-    if (!isPlainObject(state)) {
-        into.add("media.shape", path, "a host media state must be an object");
+    if (!isPlainObject(report)) {
+        into.add("host.shape", path, "a host report 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");
+    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;
     }
-    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");
+    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("media.status", `${path}.status`, `a host media state is ready or unavailable, not ${String(state.status)}`);
+        into.add("host.audio.output.status", `${out}.status`, `an output is ready or unavailable, not ${String(output.status)}`);
     }
     return into.violations;
 }

package/guide.md

@@ -245,25 +245,84 @@ type AuthenticationFailure = {
   field?: string;
 };
 
-type HostMediaState =
-  | { status: "ready"; localAudio: MediaStream }
-  | { status: "unavailable"; failure: ProtocolFailure };
+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 HostMedia = {
-  state(): HostMediaState;
-  subscribe(listener: (state: HostMediaState) => void): Unsubscribe;
+type Host = {
+  report(): HostReport;
+  subscribe(listener: (report: HostReport) => void): Unsubscribe;
 };
 
 type ConnectContext = {
   protocolVersion: number;
   sessionId: string;
   autoAcceptTasks?: boolean;
-  media?: HostMedia;
+  host: Host;
   signal?: AbortSignal;
   log?: (entry: unknown) => void;
 };
 
 type ConnectionStatus = "connecting" | "active" | "error";
+
+type CredentialField = {
+  name: string;
+  label: string;
+  type: "text" | "password";
+  required?: boolean;
+  autocomplete?: string;
+};
+
+type AuthenticationChallenge =
+  | { flowId: string; method: "browser-sso"; authorizationUrl: string; browser: "system" | "omni" }
+  | { flowId: string; method: "credentials"; fields: CredentialField[] };
+
+type StartAuthenticationRequest =
+  | { requestId: string; method: "browser-sso"; callbackUrl: string }
+  | { requestId: string; method: "credentials" };
+
+type StartAuthenticationResult =
+  | { status: "interaction-required"; challenge: AuthenticationChallenge }
+  | { status: "rejected"; failure: AuthenticationFailure };
+
+type CompleteAuthenticationRequest =
+  | { flowId: string; method: "browser-sso"; callbackUrl: string }
+  | { flowId: string; method: "credentials"; values: Readonly<Record<string, string>> };
+
+type CompleteAuthenticationResult =
+  | { status: "authenticated"; identity: User; capabilities: SessionCapabilities; expiresAt?: IsoTimestamp }
+  | { status: "rejected"; failure: AuthenticationFailure };
+
+type AuthenticationActionResult =
+  | { status: "accepted" }
+  | { status: "failed"; failure: AuthenticationFailure };
+
+type Unsubscribe = () => void;
+
+type AuthenticationSession = {
+  state(): AuthenticationState | Promise<AuthenticationState>;
+  subscribe(listener: (state: AuthenticationState) => void): Unsubscribe;
+  start(request: StartAuthenticationRequest): Promise<StartAuthenticationResult>;
+  complete(request: CompleteAuthenticationRequest): Promise<CompleteAuthenticationResult>;
+  cancelAuthentication(flowId: string): Promise<AuthenticationActionResult>;
+  signOut(): Promise<AuthenticationActionResult>;
+  close(): Promise<void>;
+};
 ```
 
 ### Provider state
@@ -282,6 +341,10 @@ type Snapshot = {
 type AgentCapacity = {
   count: number; // absolute ceiling, at least 1
 };
+
+type CapacityResult =
+  | { status: "accepted" }
+  | { status: "failed"; failure: ProtocolFailure };
 ```
 
 ### Idle contributions
@@ -302,6 +365,14 @@ type ScheduledActivity = {
   contact?: Contact;
   attributes?: Attribute[];
 };
+
+type DialRequest = {
+  destination: string;
+};
+
+type DialResult =
+  | { status: "dialled" }
+  | { status: "failed"; failure: ProtocolFailure };
 ```
 
 ### Task capabilities
@@ -378,15 +449,24 @@ const BROWSER_ISOLATION_SCHEMES = {
 type BrowserIsolationScheme =
   (typeof BROWSER_ISOLATION_SCHEMES)[keyof typeof BROWSER_ISOLATION_SCHEMES];
 
-type TaskBrowser = {
+type TaskBrowserBase = {
   id: string;
   name: string;
   purpose: string;
   url: string;
-} & (
+};
+
+type TaskBrowser = TaskBrowserBase & (
   | { reuse: false; isolationScheme?: never }
   | { reuse: true; isolationScheme: BrowserIsolationScheme }
 );
+
+type BrowserSessionKeyInput = {
+  providerId: string;
+  taskId: TaskId;
+  taskType: string;
+  browser: TaskBrowser;
+};
 ```
 
 That union is what makes a reusing browser with no scheme fail to compile rather than inherit a
@@ -559,6 +639,10 @@ type TaskCommandRequest<C extends Channel = Channel> = {
   taskId: TaskId;
   command: TaskCommand<C>;
 };
+
+type TaskCommandResult =
+  | { status: "applied" }
+  | { status: "failed"; failure: ProtocolFailure };
 ```
 
 ### Breaks
@@ -598,6 +682,22 @@ type BreakState = {
   activeReasonId?: string;
   imposed?: ImposedBreak;
 };
+
+type BreakRequestResult =
+  | { status: "requested" }
+  | { status: "failed"; failure: ProtocolFailure };
+
+type BreakCommitResult =
+  | { status: "committed" }
+  | { status: "failed"; failure: ProtocolFailure };
+
+type BreakCancelResult =
+  | { status: "cancelled" }
+  | { status: "failed"; failure: ProtocolFailure };
+
+type BreakEndResult =
+  | { status: "ended" }
+  | { status: "failed"; failure: ProtocolFailure };
 ```
 
 ### Team
@@ -634,6 +734,18 @@ type TeamBreakCommand =
   | { type: "policy"; policy: "ask" | "auto-approve" | "suspended" }
   | { type: "place"; memberId: UserId; reason?: string }
   | { type: "release"; memberId: UserId };
+
+type TeamBreakCommandRequest = {
+  command: TeamBreakCommand;
+};
+
+type TeamConsultCommandRequest = {
+  command: TeamConsultCommand;
+};
+
+type TeamCommandResult =
+  | { status: "applied" }
+  | { status: "failed"; failure: ProtocolFailure };
 ```
 
 ### Media
@@ -648,6 +760,11 @@ type VoiceMediaSession = {
 type OpenMediaResult =
   | { status: "opened"; session: VoiceMediaSession }
   | { status: "unavailable"; failure: ProtocolFailure };
+
+type OpenMediaRequest = {
+  taskId: TaskId;
+  localAudio?: MediaStream;
+};
 ```
 
 ### Events
@@ -695,12 +812,43 @@ type ProviderEventEnvelope = {
 reason rather than a naming one: `Event` is a DOM global, and a bare one would shadow it for every
 adapter compiled against the browser lib.
 
+### Adapter and connection
+
+```ts
+type Connection<C extends Channel = Channel> = {
+  snapshot(): Snapshot<C> | Promise<Snapshot<C>>;
+  subscribe(listener: (envelope: ProviderEventEnvelope<C>) => void): Unsubscribe;
+  setCapacity(capacity: AgentCapacity): Promise<CapacityResult>;
+  execute(request: TaskCommandRequest<C>): Promise<TaskCommandResult>;
+  disconnect(): Promise<void>;
+
+  describeUsers?(ids: UserId[]): Promise<User[]>;
+  dial?(request: DialRequest): Promise<DialResult>;
+
+  requestBreak?(request: BreakRequest): Promise<BreakRequestResult>;
+  commitBreak?(): Promise<BreakCommitResult>;
+  cancelBreak?(): Promise<BreakCancelResult>;
+  endBreak?(): Promise<BreakEndResult>;
+
+  executeTeamBreak?(request: TeamBreakCommandRequest): Promise<TeamCommandResult>;
+  executeTeamConsult?(request: TeamConsultCommandRequest): Promise<TeamCommandResult>;
+  openMedia?(request: OpenMediaRequest): Promise<OpenMediaResult>;
+};
+
+type Adapter<C extends Channel = Channel> = {
+  manifest: Manifest<C>;
+  createAuthenticationSession(context: AuthenticationContext): Promise<AuthenticationSession> | AuthenticationSession;
+  connect(context: ConnectContext): Promise<Connection<C>>;
+};
+```
+
 ### Published constants
 
 ```ts
 const ALLOWED_BROWSER_URL_SCHEMES = ["http:", "https:"] as const;
 
 const IDLE_CAPABILITIES = ["dial", "personalBrowser", "calendar", "contacts"] as const;
+type IdleCapability = (typeof IDLE_CAPABILITIES)[number];
 
 const IDLE_CAPABILITY_UI = {
   dial: "Dialpad",
@@ -743,6 +891,7 @@ const OMNI_FAILURE_CODES = [
   "omni.unavailable",
   "omni.break-already-committed",
 ] as const;
+type OmniFailureCode = (typeof OMNI_FAILURE_CODES)[number];
 ```
 
 `HANDLING_STEPS_WITH_A_PERSON` is every `HandlingStep` except `queued`, which is the one nobody
@@ -1501,7 +1650,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**. |
+| `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. |
 
@@ -1682,6 +1831,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",
@@ -2831,25 +2981,36 @@ phase follow the provider's reports about the work, and the media — attaching,
 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
+### The host reports, the adapter decides
 
-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:
+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.
 
-| State | Contract |
+| Field | 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.
+| `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. A host decides the reason from the devices before the error name: a browser can report a permission error on a machine with no microphone at all, and "grant permission" is the wrong instruction for an agent who needs to plug one in. `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
 
@@ -2860,7 +3021,7 @@ set up — the adapter's own registration incomplete, its credentials not yet re
 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
+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 the connection is established; the agent does not press
@@ -2869,7 +3030,7 @@ anything to become available.
 | Situation | What Omni sends |
 | --- | --- |
 | 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. |
+| 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. |
@@ -2895,8 +3056,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 — 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**).
+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 |
 | --- | --- |
@@ -2904,10 +3066,10 @@ stands, never deciding for the adapter what a missing one means (see **Host medi
 | `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 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.
+`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
@@ -3120,6 +3282,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
@@ -3237,7 +3408,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. |
+| `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. |
 
@@ -3324,7 +3495,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. |
-| `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.*`). |
+| `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.17",
+  "version": "0.1.19",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",