@xema/omni-protocol 0.1.16 → 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
@@ -142,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,
@@ -154,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;
@@ -224,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
@@ -239,6 +250,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));
             if (typeof envelope?.id === "string") {
                 if (eventIds.has(envelope.id))
                     return;
@@ -249,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");
@@ -280,6 +296,12 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         catch {
             clean = false;
         }
+        try {
+            unsubscribeMedia?.();
+        }
+        catch {
+            clean = false;
+        }
         try {
             await connection?.disconnect();
         }
@@ -518,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

@@ -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 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

@@ -1144,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 = {

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. |
 
@@ -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
@@ -2796,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. |
@@ -2841,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 |
 | --- | --- |
@@ -2849,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
@@ -3181,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. |
 
@@ -3267,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.16",
+  "version": "0.1.17",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",