@memberjunction/realtime-runtime 6.2.0-edge.2 → 6.2.0-edge.4

package/dist/session/RealtimeSessionRuntime.js

@@ -1,13 +1,28 @@
 import { BehaviorSubject, Subject } from 'rxjs';
 import { Metadata } from '@memberjunction/core';
 import { UserInfoEngine } from '@memberjunction/core-entities';
-import { AIEngineBase } from '@memberjunction/ai-engine-base';
-import { MJGlobal } from '@memberjunction/global';
-import { DEFAULT_REALTIME_AUDIO_TRACKS } from '@memberjunction/ai';
-import { BaseRealtimeClient, LoadAssemblyAIRealtimeClient, LoadElevenLabsRealtimeClient, LoadGeminiRealtimeClient, LoadHuggingFaceRealtimeClient, LoadOpenAIRealtimeClient, LoadxAIRealtimeClient } from '@memberjunction/ai-realtime-client';
+import { AddRealtimeUsageRecord, AIEngineBase, HasRealtimeUsage } from '@memberjunction/ai-engine-base';
+import { GraphQLRealtimeSessionClient } from '@memberjunction/graphql-dataprovider';
+import { MJGlobal, UUIDsEqual } from '@memberjunction/global';
+import { DEFAULT_REALTIME_AUDIO_TRACKS, ParseRealtimeAvatarStatus, ParseRealtimeClientTransport } from '@memberjunction/ai';
+import { CompareExposure, DeclaresNativeTools, IsIdentityVerifiedEventPayload, NormalizeChannelKey, ParseRealtimeSessionClientPolicy, ResolveClientTools, SelectNativeChannelTools, UserExposureReason } from '@memberjunction/ai-core-plus';
+import { BaseRealtimeClient, LoadAssemblyAIRealtimeClient, LoadElevenLabsRealtimeClient, LoadGeminiEnterpriseRealtimeClient, LoadGeminiRealtimeClient, LoadHuggingFaceRealtimeClient, LoadOpenAIRealtimeClient, LoadxAIRealtimeClient, VideoSourceArbiter, REQUESTED_TRACKS_SESSION_KEY } from '@memberjunction/ai-realtime-client';
+import { DefaultRealtimeSessionLauncher, HasClientCredential } from './session-launcher.js';
+import { RequestsAgentVideo, ResolveAvatarNotice } from './avatar-notice.js';
+import { ClientSessionDeadline } from './client-session-deadline.js';
+import { RealtimeCaptures, REALTIME_CAPTURES_OFF, REALTIME_CAPTURE_OFFERS_NONE, } from './realtime-captures.js';
+import { REALTIME_MICROPHONE_NONE, ReadMicrophoneState, SameMicrophoneState } from './realtime-microphone.js';
+import { RealtimeSessionEventHub } from './session-event-hub.js';
 import { BuildNarrationInstructions } from '../narration/narration-template.js';
 import { ParseDelegationResultJson, FormatToolName } from './delegation-result-parser.js';
-import { BaseRealtimeChannelClient } from '../channels/base-realtime-channel-client.js';
+import { BaseRealtimeChannelClient, ChannelVideoSourceID } from '../channels/base-realtime-channel-client.js';
+import { DEFAULT_CHANNEL_SURFACE_PLACEMENT, ReadChannelSurfacePlacement } from '../channels/channel-surface-placement.js';
+import { ChannelActionDispatcher } from '../channels/channel-action-dispatcher.js';
+import { BuildChannelCatalogNote } from '../channels/channel-catalog-note.js';
+import { AppClientToolRegistry, DEFAULT_APP_TOOL_OWNER } from './app-client-tool-registry.js';
+import { UserSettingsExposurePreferences } from './channel-exposure-preferences.js';
+import { BuildChannelCandidate, FindPreparedChannel, MergeToolMetadata, PreparedChannelsShowAgentVideo, ReconcileChannelsWithPolicy, ResolveLocalChannelScope, ToolsByChannelKey } from './channel-session-scope.js';
+import { RecordingShardQueue } from './RecordingShardQueue.js';
 /**
  * `MJ: User Settings` key for the per-user "record this voice call" consent toggle. Stored as
  * the literal string `'true'`/`'false'` (read with `=== 'true'`), cross-device via
@@ -15,6 +30,15 @@ import { BaseRealtimeChannelClient } from '../channels/base-realtime-channel-cli
  * default when the caller doesn't pass an explicit consent value.
  */
 export const REALTIME_RECORDING_CONSENT_KEY = 'mj.realtimeVoice.recordingConsent.v1';
+/**
+ * Relays usage onto the co-agent prompt run: token deltas, and the per-modality detail blocks as a
+ * JSON record (sent only when there are any; see `RelayRealtimeUsage` in MJServer).
+ */
+const RELAY_REALTIME_USAGE_MUTATION = `
+  mutation RelayRealtimeUsage($agentSessionId: String!, $inputTokens: Int!, $outputTokens: Int!, $usageDetailsJson: String) {
+    RelayRealtimeUsage(agentSessionId: $agentSessionId, inputTokens: $inputTokens, outputTokens: $outputTokens, usageDetailsJson: $usageDetailsJson)
+  }
+`;
 // Tree-shaking prevention: the OpenAI client is resolved dynamically through the
 // ClassFactory (by the server-reported Provider key), so this static call is what keeps
 // its @RegisterClass side effect from being eliminated by the bundler.
@@ -24,10 +48,37 @@ export const REALTIME_RECORDING_CONSENT_KEY = 'mj.realtimeVoice.recordingConsent
 // and this service stays component-free (it must stay importable in plain-node tests).
 LoadOpenAIRealtimeClient();
 LoadGeminiRealtimeClient();
+LoadGeminiEnterpriseRealtimeClient();
 LoadElevenLabsRealtimeClient();
 LoadAssemblyAIRealtimeClient();
 LoadxAIRealtimeClient();
 LoadHuggingFaceRealtimeClient();
+/**
+ * A registry row's surface placement. A row whose `UIConfig` is not valid JSON places its surface as a row without one
+ * does, so one bad row never costs the session its other channels.
+ */
+function readRowSurfacePlacement(row) {
+    try {
+        return ReadChannelSurfacePlacement(row.UIConfigObject);
+    }
+    catch {
+        console.warn(`[RealtimeSession] Channel '${row.Name}' has a UIConfig that is not valid JSON; its surface starts on its tab.`);
+        return DEFAULT_CHANNEL_SURFACE_PLACEMENT;
+    }
+}
+/** The same, for a row read over GraphQL, whose `UIConfig` arrives as the column's JSON text. */
+function readUIConfigTextSurfacePlacement(name, uiConfig) {
+    if (!uiConfig) {
+        return ReadChannelSurfacePlacement(null);
+    }
+    try {
+        return ReadChannelSurfacePlacement(JSON.parse(uiConfig));
+    }
+    catch {
+        console.warn(`[RealtimeSession] Channel '${name}' has a UIConfig that is not valid JSON; its surface starts on its tab.`);
+        return DEFAULT_CHANNEL_SURFACE_PLACEMENT;
+    }
+}
 /**
  * Converts a {@link RealtimeTrackDescriptor} to its JSON form for the session-config bag.
  *
@@ -67,6 +118,37 @@ function trackKeyFromJSON(raw) {
     }
     return `${direction}:${modality}`;
 }
+/** Whether a surface client tool handler's result is an object whose `Success` is `false`. */
+function reportsFailure(result) {
+    return typeof result === 'object' && result !== null && 'Success' in result && result.Success === false;
+}
+/** The failed result's `ErrorMessage` when it is text that is not blank, else `'Tool failed'`. */
+function failureMessage(result) {
+    const message = result.ErrorMessage;
+    return typeof message === 'string' && message.trim() ? message : 'Tool failed';
+}
+/**
+ * The `DOMException` name for each way the controller can fail to start the microphone, so a host that
+ * tells a denied microphone apart (`error.name === 'NotAllowedError'`) works the same with or without one.
+ */
+const MICROPHONE_ERROR_NAMES = {
+    denied: 'NotAllowedError',
+    'not-found': 'NotFoundError',
+    'in-use': 'NotReadableError',
+    unsupported: 'NotSupportedError',
+    error: 'Error',
+};
+/** What the user is told when the call's policy refuses a capture. */
+const CAPTURE_WORDING = {
+    camera: { NotInCall: 'The camera is not part of this call.', NotAllowed: 'This call cannot show the agent your camera' },
+    screen: { NotInCall: 'Screen sharing is not part of this call.', NotAllowed: 'This call cannot show the agent your screen' },
+};
+/** The error a failed microphone start reports, named as `getUserMedia` would have named it. */
+function microphoneStartError(reason, message) {
+    const error = new Error(message);
+    error.name = MICROPHONE_ERROR_NAMES[reason];
+    return error;
+}
 /**
  * Drives a **client-direct** real-time voice session: the browser mints an ephemeral
  * token from the MJ server, then connects DIRECTLY to the realtime provider. Audio
@@ -100,6 +182,7 @@ export class RealtimeSessionRuntime {
         this.mediaHost = mediaHost;
         // ── Reactive UI state ──────────────────────────────────────────────────────
         this._connectionState$ = new BehaviorSubject('closed');
+        this._resuming$ = new BehaviorSubject(false);
         this._captions$ = new BehaviorSubject([]);
         this._active$ = new BehaviorSubject(false);
         this._delegationProgress$ = new Subject();
@@ -109,6 +192,7 @@ export class RealtimeSessionRuntime {
         this._agentName$ = new BehaviorSubject('Sage');
         this._modelName$ = new BehaviorSubject(null);
         this._minimized$ = new BehaviorSubject(false);
+        this._savingRecording$ = new BehaviorSubject(false);
         this._activeChannels$ = new BehaviorSubject([]);
         this._channelFocus$ = new Subject();
         // ─── Generic session-lifecycle events (consumed by RealtimeSessionsAdapter to
@@ -122,6 +206,16 @@ export class RealtimeSessionRuntime {
         this._channelActivity$ = new Subject();
         /** Current connection / turn state. */
         this.ConnectionState$ = this._connectionState$.asObservable();
+        /**
+         * Whether the call is resuming: moving to a new connection with its provider mid-call. `true` from a `'connecting'` the
+         * driver reports while the call is live, until the call is live again (`'listening'`, `'speaking'` or `'thinking'`),
+         * fails (`'error'`) or ends (`'closed'`). A call's first connect is not a resume, so it is `false` until the call has
+         * been live, and outside a call. Gemini Live resumes when Google ends a connection (`goAway`) and after a dropped
+         * socket, and the agent's video can stop for a few seconds meanwhile: a host can show that as a pause rather than as
+         * the agent leaving. It changes before {@link ConnectionState$} does, so a resume's `'connecting'` arrives with it
+         * already `true`.
+         */
+        this.Resuming$ = this._resuming$.asObservable();
         /** Live captions for both sides of the conversation. */
         this.Captions$ = this._captions$.asObservable();
         /** True while a session is open (mic button active, overlay shown). */
@@ -158,6 +252,14 @@ export class RealtimeSessionRuntime {
          * pure presentation state, reset to `false` at session start and teardown.
          */
         this.Minimized$ = this._minimized$.asObservable();
+        /**
+         * True while the end-of-call recording is being saved: from the first statement of a teardown
+         * that holds a recorder until that teardown settles. False at construction and for unrecorded
+         * sessions. Exists for #5195: the page must stay open until the consolidated upload lands, or
+         * the recording is lost. The runtime is platform-free, so hosts own the reaction (a browser
+         * `beforeunload` guard, a "saving" indicator, etc.).
+         */
+        this.SavingRecording$ = this._savingRecording$.asObservable();
         /**
          * The session's ACTIVE interactive-channel plugins, resolved from the `MJ: AI Agent
          * Channels` registry at session start (one instance per session, per channel). Emits
@@ -165,6 +267,57 @@ export class RealtimeSessionRuntime {
          * one surface tab per plugin — it never knows any concrete channel type.
          */
         this.ActiveChannels$ = this._activeChannels$.asObservable();
+        this._videoSources$ = new BehaviorSubject([]);
+        /**
+         * The video sources the agent is perceiving or could perceive right now (a whiteboard, a remote browser, a
+         * shared screen), with whether each is on and whether its frames are reaching the model. Empty when no
+         * session is live or nothing has offered a frame source. This is what the "agent can see" control renders;
+         * toggle one with {@link SetVideoSourceEnabled}.
+         */
+        this.VideoSources$ = this._videoSources$.asObservable();
+        this._captures$ = new BehaviorSubject(REALTIME_CAPTURES_OFF);
+        /**
+         * The user's camera and screen share: off, starting, on (with the stream to show the user) or failed (with the
+         * reason). Both off outside a session. Start and stop them with {@link StartCamera}, {@link StartScreenShare},
+         * {@link StopCamera} and {@link StopScreenShare}; while one is on, it is also a source on {@link VideoSources$}.
+         */
+        this.Captures$ = this._captures$.asObservable();
+        this._captureOffers$ = new BehaviorSubject(REALTIME_CAPTURE_OFFERS_NONE);
+        /**
+         * Which captures the call offers, now and on every change. A capture is offered while the call is connected, the model
+         * takes inbound video, the host can open it (a camera controller; screen sharing) and the call's policy admits it (its
+         * channel is in the call and may show the agent pixels). A host shows its Camera and Share controls from this. Neither
+         * is offered outside a call.
+         */
+        this.CaptureOffers$ = this._captureOffers$.asObservable();
+        this._microphone$ = new BehaviorSubject(REALTIME_MICROPHONE_NONE);
+        /**
+         * The call's microphone, now and on every change: the one in use and the ones the user can move it to with
+         * {@link SwitchMicrophone}, as the host's camera-and-microphone controller lists them. Offered from the moment the call
+         * connects until it ends, and kept current as devices come and go. When the call loses its microphone (the one in use
+         * fails and so does the fallback to the default, or the last one goes away), its `Failure` says why: the agent hears
+         * nothing until the user picks a microphone, which opens it again. {@link REALTIME_MICROPHONE_NONE} outside a call and
+         * on a host without a controller, which opens the microphone itself (`IRealtimeMediaHost.AcquireMicrophone`).
+         */
+        this.Microphone$ = this._microphone$.asObservable();
+        this._agentVideo$ = new BehaviorSubject(null);
+        /**
+         * The agent's video (an avatar) while the model sends it: a live stream, or a player that owns the `<video>` element.
+         * `null` until the video arrives, for a model that sends none, and outside a call. The driver hands it over once it is
+         * live, and a newer one replaces it. A host shows it with `AttachVideoSource`; a channel that sinks outbound video
+         * follows it through its context, and counts as used once it arrives, so the host shows that channel's surface.
+         */
+        this.AgentVideo$ = this._agentVideo$.asObservable();
+        this._avatarNotice$ = new BehaviorSubject(null);
+        /**
+         * Why the call shows no avatar the agent asked for: set once per call, after it connects, when the model renders none,
+         * the persona has no face for it, the app shows no agent video (`host`) or the browser can't play it (`browser`); with
+         * no `Reason` when the mint gave one this version doesn't know, such as a newer server's. `null` when there is nothing
+         * to say (no avatar asked for, the avatar shows, or the mint reported no status) and after the call ends. A provider
+         * resume inside the call does not set it again. A host turns the reason into words once, for example "Audio only: this
+         * voice model can't show an avatar".
+         */
+        this.AvatarNotice$ = this._avatarNotice$.asObservable();
         /**
          * Channel requests to enter / leave the FOCUS layout (see
          * {@link RealtimeChannelFocusEvent}). Fired when a plugin calls its host context's
@@ -208,7 +361,11 @@ export class RealtimeSessionRuntime {
          */
         /** Conversation id the SERVER created for this session (null when the host supplied one). */
         this.createdConversationId = null;
-        /** The session's conversation id (supplied or server-created). */
+        /**
+         * The session's conversation id (supplied or server-created). While a start's mint runs, the
+         * conversation the start asked for; null when it asked the server to create one. Null after
+         * teardown.
+         */
         this.sessionConversationId = null;
         /** First final user utterance of the live session (the naming seed). */
         this.firstUserTranscript = null;
@@ -219,8 +376,28 @@ export class RealtimeSessionRuntime {
         // ── Session internals ──────────────────────────────────────────────────────
         /** The provider-direct realtime client driving the live session (ClassFactory-resolved). */
         this.client = null;
-        /** The mic capture stream — acquired here (permission UX) and handed to the client. */
+        /**
+         * The mic capture stream — acquired here (permission UX) and handed to the client. A microphone the controller opens
+         * again after the call lost one replaces it.
+         */
         this.localStream = null;
+        /**
+         * Whether the user muted the call's microphone, as {@link ToggleMute} last reported it. While the call has no microphone
+         * track there is nothing to mute, and a microphone opened again after the call lost one starts this way.
+         */
+        this.microphoneMuted = false;
+        /** The host's camera-and-microphone controller for this session, when the host offers one. */
+        this.localMedia = null;
+        /** Follows the controller's microphone, so a swapped-in track or a reopened microphone reaches the driver and the recorder. */
+        this.localMediaSubscription = null;
+        /**
+         * Whether the call offers its microphone for switching ({@link Microphone$}, {@link SwitchMicrophone}): from the moment
+         * the client is connected until the call ends. Not before: a driver still connecting may have bound the old track.
+         */
+        this.microphoneOffered = false;
+        /** The live session's camera and screen share; created once the client is connected. */
+        this.captures = null;
+        this.capturesSubscription = null;
         this.agentSessionId = null;
         /**
          * The application the active session runs in (sources the server-side app config cascade +
@@ -254,8 +431,15 @@ export class RealtimeSessionRuntime {
         this.recordingStartedAtIso = null;
         /** Interval that flushes ~15s crash-recovery shards to the server during a recording. */
         this.segmentTimer = null;
-        /** 0-based index of the next recording shard to upload. */
-        this.segmentIndex = 0;
+        /**
+         * Owns shard indexing and retry for the current recording: it assigns each shard its index and
+         * keeps failed shards to resend under that same index. A fresh queue per recording keeps a flush
+         * still in flight from a previous session off this session's indexes. Null when not recording.
+         * A recording that ends discards its queue, and any retained shard with it: the consolidated
+         * end-of-call upload supersedes them, and if that upload is lost too, server-side recovery
+         * (#5196) fills the gap with silence.
+         */
+        this.shardQueue = null;
         // ── Server-side liveness ───────────────────────────────────────────────────
         /**
          * Interval that tells the server this session is still in use, or `null` when no session is
@@ -310,6 +494,11 @@ export class RealtimeSessionRuntime {
         this.pendingUsageInput = 0;
         /** Accumulated output-token delta since the last flush. */
         this.pendingUsageOutput = 0;
+        /**
+         * Accumulated per-modality usage since the last flush (input and output detail blocks, avatar
+         * video seconds included), relayed in full; `null` when no update carried any.
+         */
+        this.pendingUsageDetails = null;
         /** Pending debounced usage flush; also force-flushed at teardown. */
         this.usageFlushTimer = null;
         /** Active push-status subscription that feeds delegation progress; cleared on teardown. */
@@ -352,7 +541,20 @@ export class RealtimeSessionRuntime {
          */
         this.teardownInFlight = null;
         /**
-         * Why the last session start failed, or `null` when none has.
+         * The latest start's opening of the host's microphone, until {@link IRealtimeMediaHost.ReleaseMicrophone} hands it
+         * back; `null` when no opening is owed a release, so a session that ends before asking for the microphone releases
+         * nothing.
+         *
+         * The host gets one release per opening, after the opening returns. A release while the microphone is still
+         * opening undoes nothing: the React Native host puts iOS into the call audio category inside `AcquireMicrophone`,
+         * after the permission prompt. So {@link runTeardown} releases an opening that has returned and leaves one still
+         * opening to its start, which releases it once it returns ({@link unwindAbandonedStart}), unless a newer start has
+         * opened the microphone since; that start's own end releases it. Whoever releases clears this first, so no
+         * opening is released twice.
+         */
+        this.microphoneLease = null;
+        /**
+         * Why the latest session start failed, or `null` when it has not. Each start clears it ({@link beginSessionStart}).
          *
          * The runtime reports failure as `'error'` on {@link ConnectionState$}, which is enough to show
          * *that* something went wrong but not *what* — and the difference matters at exactly one point:
@@ -361,6 +563,11 @@ export class RealtimeSessionRuntime {
          * runtime's own try/catch, so the host never sees that rejection itself.
          */
         this.lastStartError = null;
+        /**
+         * The fatal error the call's client reported, or `null` when it has reported none. Each start clears it
+         * ({@link beginSessionStart}). See {@link LastSessionError}.
+         */
+        this.lastSessionError = null;
         /**
          * Pending DEBOUNCED channel-state saves, keyed by channel name. Each entry keeps the
          * LATEST serialized state plus the session id captured while the session was live —
@@ -377,13 +584,92 @@ export class RealtimeSessionRuntime {
          */
         this.usedChannelNames = new Set();
         this._provider = null;
+        this._launcher = new DefaultRealtimeSessionLauncher();
+        /**
+         * Loads channel code on demand. Called, with the `ClientPluginClass` keys of every channel about to be
+         * resolved (the registry's rows plus the host's declarations), after the registry is read and before any
+         * plugin is built — so a host can register a heavy channel's class only when the session could use it.
+         * It must resolve once the classes it knows are registered; a rejection is logged, never fatal.
+         */
+        this.ChannelClassLoader = null;
+        // ── Session events (server → this session's client) ────────────────────────
+        this._sessionEvents$ = new Subject();
+        /**
+         * Every event the server publishes to THIS session, for the session's life (identity verification
+         * today; apps add their own types). Hot, with no replay — subscribe before the session starts, once,
+         * and it keeps working across sessions. The runtime has already acted on the events it understands
+         * (see {@link handleIdentityVerified}) by the time one reaches here; this stream is for the host UI.
+         *
+         * Silent when the session's provider has no subscription transport (see {@link createSessionEventSource}).
+         */
+        this.SessionEvents$ = this._sessionEvents$.asObservable();
+        /** Keeps the live session's event stream open; null between sessions. */
+        this.sessionEventHub = null;
+        /** Per-type handlers the runtime runs (before publishing on {@link SessionEvents$}) for events it understands. */
+        this.sessionEventHandlers = new Map([
+            ['identity.verified', (event) => this.handleIdentityVerified(event)]
+        ]);
+        /**
+         * What the agent should SAY the moment the user's identity is verified, or `null` (the default) to
+         * say nothing — the agent is still told, silently, through a context note. A string is used as the
+         * instruction verbatim; a function receives the verified payload (e.g. to greet by name) and returns
+         * the instruction, or `null` to stay silent for this verification.
+         */
+        this.IdentityVerifiedSpokenResponse = null;
+        this.clientDeadline = new ClientSessionDeadline();
+        // ── Interactive channels (registry-driven + host-declared plugins) ─────────
+        //
+        // A session's channels come from two places — the `MJ: AI Agent Channels` registry and the channels
+        // the host declares — and pass through three stages:
+        //
+        //   1. PREPARE  (before mint)  construct the plugins, read their descriptors, report them as
+        //                              candidates, and work out the scope the browser can decide alone.
+        //   2. MINT                    the server scopes the candidates with the agent/app cascade and the
+        //                              registry's kill switch, and returns the resolved policy.
+        //   3. ACTIVATE (after mint)   initialize exactly the policy's channels: `open-on-start`/`headless`
+        //                              ones mount now, `on-demand` ones wait to be opened through ContextTool.
+        //
+        // Nothing is initialized before the policy is known, so a channel the server vetoes never runs.
+        /** Whether the channel catalog note still has to be sent (see {@link flushChannelCatalogNote}). */
+        this.catalogNotePending = false;
+        /** Plugins resolved for the current start but not yet initialized. Consumed by {@link activateChannels}. */
+        this.preparedChannels = [];
+        /** The scope the browser resolves on its own — the fallback when no server policy comes back. */
+        this.localChannelScope = null;
+        /** `on-demand` channels that are in the session but not opened yet (initialized only when opened). */
+        this.advertisedChannels = [];
+        /** What the policy resolved for each in-session channel, keyed by normalized channel key. */
+        this.resolvedChannels = new Map();
+        /** The prior session's saved channel states, kept so an `on-demand` channel opened later is restored too. */
+        this.priorChannelStates = {};
+        /** The app/static client-tool tiers the server resolved for this session. */
+        this.sessionClientTools = null;
+        /** Validates and routes channel-addressed `ContextTool` calls. */
+        this.channelDispatcher = new ChannelActionDispatcher({
+            FindChannel: (key) => this.findDispatchableChannel(key),
+            ListChannelKeys: () => this.listAddressableChannelKeys(),
+            ActivateChannel: (plugin) => this.mountAdvertisedChannel(plugin),
+        });
+        /** Where the user's per-channel "how much can the agent see" choices are kept. Replace with {@link SetExposurePreferences}. */
+        this.exposurePreferences = new UserSettingsExposurePreferences(() => this.canPersistUserSettings());
+        /** The channel whose surface the user is looking at, kept so it applies to an arbiter created after it was set. */
+        this.focusedChannelKey = null;
+        this.stopWatchingVideoSources = null;
         /**
          * Host registry of surface CLIENT TOOLS (Name → handler), fed by the host (Explorer) from the
-         * active surface's `SetAgentClientTools`. The headless ClientContextChannel's `ContextTool` proxy
-         * executes against this via {@link executeAppClientTool}. Keys are lower-cased for case-insensitive
-         * model-supplied action names.
+         * active surface's `SetAgentClientTools` and from its always-on globals. The headless
+         * ClientContextChannel's `ContextTool` proxy executes against this via {@link executeAppClientTool}.
+         * Owner-keyed — see {@link AppClientToolRegistry}.
          */
-        this.appClientToolHandlers = new Map();
+        this.appToolRegistry = new AppClientToolRegistry();
+    }
+    /** Synchronous read of {@link SavingRecording$}. */
+    get IsSavingRecording() {
+        return this._savingRecording$.value;
+    }
+    /** Synchronous access to {@link AvatarNotice$}'s current value. */
+    get CurrentAvatarNotice() {
+        return this._avatarNotice$.value;
     }
     /** Synchronous access to the session's active interactive-channel plugins. */
     get ActiveChannels() {
@@ -480,10 +766,113 @@ export class RealtimeSessionRuntime {
     set Provider(value) {
         this._provider = value;
     }
+    /**
+     * How this runtime mints a session — the stock `StartRealtimeClientSession` mutation unless a host
+     * installs its own {@link IRealtimeSessionLauncher} (a guest-session exchange, a deployment-specific
+     * mutation). Everything after the mint — channel scoping, the driver, transcripts, teardown — is
+     * unchanged. Assign `null` to restore the default.
+     */
+    get Launcher() {
+        return this._launcher;
+    }
+    set Launcher(value) {
+        this._launcher = value ?? new DefaultRealtimeSessionLauncher();
+    }
+    /**
+     * The client's copy of the session's absolute deadline (`null` when none is known). A host that
+     * knows the session's cap at start sets it with {@link SetSessionDeadline}; verification extends it
+     * from the server's `identity.verified` payload. The SERVER enforces the real deadline — this exists
+     * so the host can end the call gracefully first and show a countdown. It only ever moves later by
+     * the server's word, so nothing a client does can extend the real one.
+     */
+    get SessionDeadline$() {
+        return this.clientDeadline.Deadline$;
+    }
+    /** Synchronous access to {@link SessionDeadline$}. */
+    get SessionDeadline() {
+        return this.clientDeadline.Value;
+    }
+    /** Sets the baseline deadline a host knows at session start (`null` clears). See {@link SessionDeadline$}. */
+    SetSessionDeadline(deadline) {
+        this.clientDeadline.Set(deadline);
+    }
+    /**
+     * Builds the transport that reads the session's events. The default rides the session's GraphQL
+     * provider; it returns `null` — "no session events here" — for a provider with no subscription
+     * support (a test double, a host on another transport), which the runtime tolerates. Override to
+     * supply another transport.
+     */
+    createSessionEventSource() {
+        const provider = this.Provider;
+        if (!provider || typeof provider.Subscribe !== 'function') {
+            return null;
+        }
+        return new GraphQLRealtimeSessionClient(provider);
+    }
+    /** Opens the live session's event stream. Best-effort: never disturbs the call. */
+    startSessionEvents(agentSessionId) {
+        this.stopSessionEvents();
+        try {
+            const source = this.createSessionEventSource();
+            if (!source) {
+                return;
+            }
+            this.sessionEventHub = new RealtimeSessionEventHub(source, (event) => this.routeSessionEvent(agentSessionId, event));
+            this.sessionEventHub.Start(agentSessionId);
+        }
+        catch (error) {
+            console.error('[RealtimeSession] Could not start the session event stream:', error);
+        }
+    }
+    stopSessionEvents() {
+        this.sessionEventHub?.Stop();
+        this.sessionEventHub = null;
+    }
+    /** Routes one event to its per-type handler, then publishes it. An event for another session is dropped. */
+    routeSessionEvent(expectedSessionId, event) {
+        if (event.AgentSessionID !== expectedSessionId || this.agentSessionId !== expectedSessionId) {
+            console.warn(`[RealtimeSession] Dropped a '${event.Type}' event addressed to another session.`);
+            return;
+        }
+        try {
+            this.sessionEventHandlers.get(event.Type)?.(event);
+        }
+        catch (error) {
+            console.error(`[RealtimeSession] Handling the '${event.Type}' session event failed:`, error);
+        }
+        this._sessionEvents$.next(event);
+    }
+    /**
+     * `identity.verified`: keep the client's deadline in step with the server's, tell the model — as a
+     * silent, structured note — who it is now talking to, and, when the host configured it, have it say
+     * something about that. The payload is validated again here (it crossed a wire); the name rides as
+     * JSON so user-entered text can never break out of the note's frame.
+     */
+    handleIdentityVerified(event) {
+        if (event.Type !== 'identity.verified' || !IsIdentityVerifiedEventPayload(event.Payload)) {
+            console.warn('[RealtimeSession] Ignored a malformed identity.verified event.');
+            return;
+        }
+        const payload = event.Payload;
+        this.clientDeadline.Extend(payload.MaxSessionDeadlineIso);
+        this.SendContextNote(`[identity] verified ${JSON.stringify({ email: payload.VerifiedEmail, name: payload.VerifiedName, method: payload.Method })} ` +
+            '(background context — the user has proven they control this email address; treat them as verified. Do not read this note aloud.)');
+        const spoken = typeof this.IdentityVerifiedSpokenResponse === 'function' ? this.IdentityVerifiedSpokenResponse(payload) : this.IdentityVerifiedSpokenResponse;
+        if (spoken && spoken.trim().length > 0 && this.client && this.isSessionLive()) {
+            this.requestChannelSpokenResponse(spoken.trim());
+        }
+    }
     /** True when a session is currently open. */
     get IsActive() {
         return this._active$.value;
     }
+    /**
+     * True when a session is open or starting for `conversationId`. Ids are compared without
+     * regard to case.
+     */
+    IsActiveFor(conversationId) {
+        return this.IsActive && conversationId != null && UUIDsEqual(this.sessionConversationId, conversationId);
+    }
     /**
      * Start a client-direct voice session fronting `targetAgentId`.
      *
@@ -521,31 +910,55 @@ export class RealtimeSessionRuntime {
      *   the server-side Media channel resolves THIS collection as the agent's media kit for the session,
      *   taking precedence over the agent's `DefaultMediaCollectionID`. The server UUID-validates it
      *   (malformed ⇒ ignored, the agent default applies). Omit/`null` to use the agent default kit.
+     * @param applicationId Optional application the session runs in (sources the app config cascade,
+     *   including `Application.AgentSettings.Realtime.Channels`).
+     * @param appContext Optional live app-context snapshot injected into the companion prompt at mint.
+     * @param options Optional per-start extras — chiefly the channels the HOST brings
+     *   ({@link RealtimeSessionStartOptions.HostChannels}), the way a connect-only embed with no
+     *   registry gets channels at all, and the fork the session starts on
+     *   ({@link RealtimeSessionStartOptions.ConversationBranchID}; omitted is Main, where its transcript is written).
      */
-    async StartRealtimeSession(targetAgentId, conversationId, lastSessionId, agentName, preferredModelId, clientTools, coAgentId, configOverridesJson, recordingConsent, mediaCollectionId, applicationId, appContext) {
+    async StartRealtimeSession(targetAgentId, conversationId, lastSessionId, agentName, preferredModelId, clientTools, coAgentId, configOverridesJson, recordingConsent, mediaCollectionId, applicationId, appContext, options) {
         if (this.IsActive) {
             return; // a session is already running — ignore duplicate starts
         }
         const consent = this.beginSessionStart({ agentName, recordingConsent, applicationId, appContext });
-        // Captured BEFORE startChannels so the mint carries exactly the snapshot the prologue
+        this.sessionConversationId = conversationId ?? null;
+        // A teardown while the channels are prepared or the mint runs bumps this; see the checks below.
+        const generation = this.startGeneration;
+        // Captured BEFORE the channels are prepared so the mint carries exactly the snapshot the prologue
         // resolved, whatever a channel plugin may push in the meantime.
         const effectiveAppContext = this._appContext$.value;
         let session;
         try {
-            // Resolve + initialize the interactive-channel plugins FIRST: their client-executed
-            // tool sets must be declared to the realtime model at session mint.
-            const allClientTools = [...(clientTools ?? []), ...(await this.startChannels())];
-            session = await this.mintSession(targetAgentId, conversationId, lastSessionId, preferredModelId, allClientTools, coAgentId, configOverridesJson, consent, this.recordingStartedAtIso, mediaCollectionId, this.applicationId, effectiveAppContext);
+            // Resolve the interactive-channel plugins FIRST (constructed, not started): the tools of the
+            // channels mounted with the session must be declared to the realtime model at mint, and the
+            // server needs the candidates to scope them. Nothing is initialized until the policy is known.
+            const scope = await this.prepareChannelScope(options?.HostChannels);
+            const allClientTools = [...(clientTools ?? []), ...scope.NativeTools];
+            session = await this.mintSession(targetAgentId, conversationId, lastSessionId, preferredModelId, allClientTools, coAgentId, configOverridesJson, consent, this.recordingStartedAtIso, mediaCollectionId, this.applicationId, effectiveAppContext, scope.CandidatesJson, scope.ShowsAgentVideo, options?.ConversationBranchID ?? null);
         }
         catch (error) {
+            // An ended or replaced start only logs its failure: the error state and the teardown belong
+            // to the session that is current now, which a newer start may own.
+            if (this.startGeneration !== generation) {
+                console.error('[RealtimeSession] A start that was already ended failed:', error);
+                return;
+            }
             await this.failSessionStart(error);
             return;
         }
+        // The host ended the start while the mint ran. That teardown had no session id to close, so
+        // close the minted row here, and touch no shared state: a newer start may already own it.
+        if (this.startGeneration !== generation) {
+            await this.closeServerSession(session.AgentSessionId);
+            return;
+        }
         if (!this.hostCanUseProvider(session.Provider)) {
             await this.abortUnusableSession(session);
             return;
         }
-        await this.runMintedSession(session, conversationId ?? null, consent);
+        await this.runMintedSession(session, conversationId ?? null, consent, options?.CameraCheck === true);
     }
     /**
      * Declares which provider keys this host can actually carry audio for.
@@ -581,7 +994,7 @@ export class RealtimeSessionRuntime {
         // published them on ActiveChannels$; skipping teardown would leave them undisposed, their tool
         // handlers registered, and their subscriptions live until the next start replaced them.
         this.agentSessionId = session.AgentSessionId ?? this.agentSessionId;
-        this._connectionState$.next('error');
+        this.setConnectionState('error');
         await this.teardown(true);
     }
     /**
@@ -600,7 +1013,8 @@ export class RealtimeSessionRuntime {
      * owns that half too.
      *
      * @param result The minted session — the same ten fields the `StartRealtimeClientSession`
-     *   mutation returns. `EphemeralToken` and `Provider` are what actually open the call.
+     *   mutation returns. `EphemeralToken` and `Provider` are what actually open the call; a relay
+     *   session opens with its `Transport` and `RelayUrl` instead, so a host must pass those on.
      * @param options Host-side inputs the result cannot carry; see {@link RealtimeSessionRunOptions}.
      *   Every field defaults exactly as its {@link StartRealtimeSession} counterpart does.
      */
@@ -614,16 +1028,20 @@ export class RealtimeSessionRuntime {
             return;
         }
         const consent = this.beginSessionStart(effectiveOptions);
-        await this.runMintedSession(result, effectiveOptions.conversationId ?? null, consent);
+        await this.runMintedSession(result, effectiveOptions.conversationId ?? null, consent, false);
     }
     /**
-     * Start prologue shared by both entry points: bind the app layer, publish the agent name, reset
-     * per-session state, and flip the session live (which is ALSO what makes the `IsActive` guard
-     * suppress duplicate starts while the mint is still in flight — hence it runs before minting, not
-     * after). Returns the resolved recording consent, which the mint half reports to the server and
-     * the run half uses to decide whether to record.
+     * Start prologue shared by both entry points: clear the last start's failure, bind the app layer,
+     * publish the agent name, reset per-session state, and flip the session live (which is ALSO what
+     * makes the `IsActive` guard suppress duplicate starts while the mint is still in flight — hence it
+     * runs before minting, not after). Returns the resolved recording consent, which the mint half
+     * reports to the server and the run half uses to decide whether to record.
      */
     beginSessionStart(options) {
+        // Before this start publishes anything: hosts read LastStartError as this start's states arrive,
+        // so from the first of them it must describe this start, not an earlier one.
+        this.lastStartError = null;
+        this.lastSessionError = null;
         // App awareness (Move 1/3/4): the application the session runs in (sources the app config
         // cascade + RelevantAgents → allowed-agent union) and the live app-context snapshot injected
         // into the companion prompt at mint. Stored so the ClientContextChannel can stream subsequent
@@ -641,7 +1059,7 @@ export class RealtimeSessionRuntime {
         }
         this.resetState();
         this._active$.next(true);
-        this._connectionState$.next('connecting');
+        this.setConnectionState('connecting');
         // Resolve recording consent for this session: explicit value wins, else the per-user
         // persisted preference. Computed before mint so it can be reported to the server.
         const consent = options.recordingConsent ?? this.readPersistedRecordingConsent();
@@ -651,12 +1069,18 @@ export class RealtimeSessionRuntime {
     /**
      * The RUN half of a session start, shared by both entry points: consume the minted result, open
      * the provider connection, and go live. `inputConversationId` is the conversation the START asked
-     * for (null ⇒ "server, make me one") — the result alone can't distinguish the two.
+     * for (null ⇒ "server, make me one") — the result alone can't distinguish the two. `cameraCheck` is
+     * whether the host shows a camera check ({@link RealtimeSessionStartOptions.CameraCheck}).
      */
-    async runMintedSession(session, inputConversationId, consent) {
+    async runMintedSession(session, inputConversationId, consent, cameraCheck) {
         // Captured up front: every await below is a window in which the host can end the session.
         const generation = this.startGeneration;
         try {
+            // Mount the channels the resolved policy puts in the session. Deliberately BEFORE the session
+            // id is adopted: `ActiveChannels$` consumers (the sessions adapter) treat an emission that
+            // arrives while no session id is set as the INITIAL set, whose opens they synthesize from
+            // `SessionStarted$` — activating after the id is set would announce every channel twice.
+            this.applySessionClientPolicy(session);
             this.agentSessionId = session.AgentSessionId;
             // A null input conversationId means the SERVER created a fresh conversation for
             // this session — track it so the host can fold it into the cached list, select
@@ -671,20 +1095,39 @@ export class RealtimeSessionRuntime {
             this.applyPriorChannelStates(session.PriorChannelStatesJson);
             const client = this.createRealtimeClient(session.Provider);
             this.client = client;
+            this.watchVideoSources(client);
             this.wireClientHandlers(client);
             // Everything past here awaits on hardware and the network, during which the host may end the
-            // session. Each await is followed by a staleness check so an abandoned start releases what it
-            // just acquired instead of leaving a live microphone and a live call behind it.
-            this.localStream = await this.mediaHost.AcquireMicrophone();
+            // session. Each await is followed by a staleness check, before any failure is reported, so an
+            // abandoned start releases what it just acquired instead of leaving a live microphone and a live
+            // call behind it, and reports nothing to a host that has ended the call.
+            const lease = { Opening: true };
+            this.microphoneLease = lease;
+            const microphone = await this.openMicrophone().finally(() => {
+                lease.Opening = false;
+            });
+            this.localStream = microphone.Stream;
             if (this.startGeneration !== generation) {
-                await this.unwindAbandonedStart(session, client);
+                await this.unwindAbandonedStart(session, client, lease);
                 return;
             }
-            await client.Connect(this.BuildClientConfig(session), this.localStream);
+            if (microphone.Error) {
+                throw microphone.Error;
+            }
+            const clientConfig = this.BuildClientConfig(session);
+            const connectError = await this.connectClient(client, clientConfig, microphone.Stream);
             if (this.startGeneration !== generation) {
-                await this.unwindAbandonedStart(session, client);
+                await this.unwindAbandonedStart(session, client, lease);
                 return;
             }
+            if (connectError) {
+                throw connectError;
+            }
+            // Tracks are negotiated now, so a capture can tell whether the model takes video, and the call whether it shows
+            // the avatar its agent asked for. The driver holds the microphone now, so the user may switch it.
+            this.openCaptures(client, cameraCheck);
+            this.offerMicrophone();
+            this.publishAvatarNotice(session, clientConfig, client);
             // Notify active channels that the session client is connected and tracks are established
             for (const channel of this._activeChannels$.value) {
                 try {
@@ -694,6 +1137,10 @@ export class RealtimeSessionRuntime {
                     console.error(`[RealtimeSession] Error in channel '${channel.ChannelName}' OnSessionStarted:`, err);
                 }
             }
+            // Tell the model which channels exist and how to use them, from the channels' own descriptors —
+            // as soon as the control channel is usable (which may be right now, or a moment after Connect).
+            this.catalogNotePending = true;
+            this.flushChannelCatalogNote();
             // Start browser-side recording (mic + agent mix) when consented. Best-effort: an
             // unsupported browser / missing remote stream degrades gracefully (mic-only or off)
             // and never blocks the call. The remote stream may still be null here (the WebRTC
@@ -718,6 +1165,8 @@ export class RealtimeSessionRuntime {
             // SessionsObserver bridge. Emitting AFTER Connect() guarantees both that
             // agentSessionId is set (line ~468) AND the realtime client is connected,
             // so consumers can act on it without re-checking either condition.
+            // The session's own event stream (identity verification, app events) stays open for its life.
+            this.startSessionEvents(this.agentSessionId);
             this._sessionStarted$.next({
                 sessionId: this.agentSessionId,
                 channelNames: this._activeChannels$.value.map(c => c.ChannelName),
@@ -730,18 +1179,42 @@ export class RealtimeSessionRuntime {
             await this.failSessionStart(error);
         }
     }
+    /**
+     * Tells the host, once per call, why it shows no avatar ({@link AvatarNotice$}): from the mint's status, whether this
+     * session asked for the agent's video, and whether that track is live now that the call is connected.
+     */
+    publishAvatarNotice(session, config, client) {
+        const notice = ResolveAvatarNotice(ParseRealtimeAvatarStatus(session.AvatarStatusJson), RequestsAgentVideo(config), client.IsTrackEstablished('video', 'outbound'));
+        if (notice) {
+            this._avatarNotice$.next(notice);
+        }
+    }
     /**
      * Releases everything a start acquired after the host had already ended the session.
      *
      * Reached only when {@link teardown} ran while this start was awaiting the microphone or the
-     * provider connection. Teardown found nothing to release because nothing existed yet, so this
-     * start owns the cleanup: stop the microphone, close the provider connection, and close the
-     * server-side session row that the mint created.
+     * provider connection, whether that wait then succeeded or failed: the host has ended the call,
+     * so a failure there is not reported. Teardown could not release what did not exist yet, so this
+     * start owns the cleanup: stop the microphone, hand it back to the host when teardown left that
+     * to it ({@link microphoneLease}), close the provider connection, and close the server-side
+     * session row that the mint created when no teardown has closed it or is closing it.
+     *
+     * @param lease This start's opening of the microphone.
      */
-    async unwindAbandonedStart(session, client) {
+    async unwindAbandonedStart(session, client, lease) {
         console.warn('[RealtimeSession] Session was ended while starting — releasing the partial session.');
+        this.closeCaptures();
+        this.closeLocalMedia();
         this.localStream?.getTracks().forEach(t => t.stop());
         this.localStream = null;
+        this.microphoneMuted = false;
+        // Teardown left the release to this start when the microphone was still opening. A cleared or
+        // replaced lease means teardown already released it, or a newer start has opened the microphone
+        // since and its own end releases it.
+        if (this.microphoneLease === lease) {
+            this.microphoneLease = null;
+            await this.releaseMicrophone();
+        }
         try {
             await client.Disconnect();
         }
@@ -751,27 +1224,321 @@ export class RealtimeSessionRuntime {
         // Only clear the shared slots when they still point at THIS attempt — a newer start may
         // already have replaced them.
         if (this.client === client) {
+            this.unwatchVideoSources();
+            this.clearAgentVideo();
             this.client = null;
         }
-        // Close the server session only if teardown has NOT already done so. It nulls `agentSessionId`
-        // after closing, so a still-matching id means this attempt still owns the row; a cleared one
-        // means the teardown that invalidated this start already closed it, and closing again would
-        // send a second `CloseAgentSession` for one session.
-        if (session.AgentSessionId && this.agentSessionId === session.AgentSessionId) {
+        // Close the server session only if no teardown has closed it or is closing it. Teardown nulls
+        // `agentSessionId` after closing, so a cleared id means the teardown that invalidated this start
+        // already closed it. A teardown still running closes it itself and then reports the end on
+        // `SessionEnded$`: closing it here as well would send a second `CloseAgentSession` for one
+        // session, and clearing the id would leave that teardown no session to report.
+        if (session.AgentSessionId && this.agentSessionId === session.AgentSessionId && !this.teardownInFlight) {
             this.agentSessionId = null;
             await this.closeServerSession(session.AgentSessionId);
         }
     }
     /**
-     * Why the last session start failed, or `null` when the last start succeeded or none has run.
+     * Opens the user's microphone: through the host's controller when it offers one, otherwise through
+     * {@link IRealtimeMediaHost.AcquireMicrophone}. A failure is returned rather than thrown, so the caller can
+     * first check whether the start was abandoned meanwhile (a teardown disposes the controller, which fails a
+     * start still in flight) and unwind quietly instead of reporting an error nobody is waiting for.
+     */
+    async openMicrophone() {
+        const controller = this.mediaHost.CreateLocalMediaController?.() ?? null;
+        if (!controller) {
+            try {
+                return { Stream: await this.mediaHost.AcquireMicrophone(), Error: null };
+            }
+            catch (error) {
+                return { Stream: null, Error: error instanceof Error ? error : new Error(String(error)) };
+            }
+        }
+        this.localMedia = controller;
+        const started = await controller.Start('microphone');
+        if (started.Status === 'failed') {
+            return { Stream: null, Error: microphoneStartError(started.Reason, started.Message) };
+        }
+        this.followMicrophone(controller, started.Stream);
+        return { Stream: started.Stream, Error: null };
+    }
+    /**
+     * Opens the provider connection. As with {@link openMicrophone}, a failure is returned rather than thrown, so the
+     * caller can first check whether the start was abandoned meanwhile and unwind quietly instead of reporting an error
+     * nobody is waiting for: a teardown disconnects the client, which with most drivers fails a connection still opening.
+     */
+    async connectClient(client, config, microphone) {
+        try {
+            await client.Connect(config, microphone);
+            return null;
+        }
+        catch (error) {
+            return error instanceof Error ? error : new Error(String(error));
+        }
+    }
+    /**
+     * Moves the driver and the recorder onto the call's microphone whenever the controller gives it a new track. A device
+     * switch, or a lost device replaced by the default, swaps a track into the same stream, and the controller carries the
+     * old track's mute over. A microphone opened again after the call lost one comes in a new stream: its track takes the
+     * call's mute, and the stream becomes the one {@link ToggleMute} and the teardown act on. Mid-swap the stream holds no
+     * track, so only a finished swap is followed. Every report also keeps {@link Microphone$} current once the call offers
+     * it.
+     */
+    followMicrophone(controller, stream) {
+        let followedStream = stream;
+        let followedTrack = stream.getAudioTracks()[0] ?? null;
+        this.localMediaSubscription = controller.State$.subscribe((media) => {
+            const current = controller.GetStream('microphone') ?? followedStream;
+            const track = current.getAudioTracks()[0] ?? null;
+            if (track && track !== followedTrack) {
+                if (current !== followedStream) {
+                    track.enabled = !this.microphoneMuted;
+                    this.localStream = current;
+                    followedStream = current;
+                }
+                followedTrack = track;
+                this.recorder?.ReplaceMicrophone?.(current);
+                this.client?.ReplaceMicrophone?.(current)?.catch((error) => {
+                    console.error('[RealtimeSession] The realtime driver could not move to the new microphone:', error);
+                });
+            }
+            this.publishMicrophone(media);
+        });
+    }
+    /** The client is connected: the call offers its microphone on {@link Microphone$}, and {@link SwitchMicrophone} moves it. */
+    offerMicrophone() {
+        if (!this.localMedia) {
+            return;
+        }
+        this.microphoneOffered = true;
+        this.publishMicrophone(this.localMedia.State);
+    }
+    /** Publishes the call's microphone from the controller's state while the call offers it, when it names a change. */
+    publishMicrophone(media) {
+        if (!this.microphoneOffered) {
+            return;
+        }
+        const current = this._microphone$.value;
+        const next = ReadMicrophoneState(media, current);
+        if (!SameMicrophoneState(next, current)) {
+            this._microphone$.next(next);
+        }
+    }
+    /** Stops following the controller and disposes it, which releases its devices; the call no longer offers a microphone. */
+    closeLocalMedia() {
+        this.localMediaSubscription?.unsubscribe();
+        this.localMediaSubscription = null;
+        this.localMedia?.Dispose();
+        this.localMedia = null;
+        this.microphoneOffered = false;
+        if (this._microphone$.value !== REALTIME_MICROPHONE_NONE) {
+            this._microphone$.next(REALTIME_MICROPHONE_NONE);
+        }
+    }
+    /**
+     * Creates the session's camera and screen share and mirrors their state on {@link Captures$}. With `cameraCheck`, the
+     * call's first camera start waits for {@link ConfirmCamera}.
+     */
+    openCaptures(client, cameraCheck) {
+        this.closeCaptures();
+        const captures = new RealtimeCaptures({
+            Client: client,
+            LocalMedia: this.localMedia,
+            Host: this.mediaHost,
+            CreateSampler: this.hostFrameSampler(),
+            Admit: (kind) => this.admitCapture(kind),
+            CameraCheck: cameraCheck,
+        });
+        this.captures = captures;
+        this.capturesSubscription = captures.States$.subscribe((states) => this._captures$.next(states));
+        this.refreshCaptureOffers();
+    }
+    /**
+     * The host's frame sampler for the captures ({@link IRealtimeMediaHost.CreateFrameSampler}), or `undefined` when it offers
+     * none and the captures use the DOM default.
+     */
+    hostFrameSampler() {
+        const host = this.mediaHost;
+        const create = host.CreateFrameSampler;
+        return create ? (stream, options) => create.call(host, stream, options) : undefined;
+    }
+    /** Stops the camera and screen share, if any, and reports both off. */
+    closeCaptures() {
+        this.capturesSubscription?.unsubscribe();
+        this.capturesSubscription = null;
+        this.captures?.Dispose();
+        this.captures = null;
+        if (this._captures$.value !== REALTIME_CAPTURES_OFF) {
+            this._captures$.next(REALTIME_CAPTURES_OFF);
+        }
+        this.refreshCaptureOffers();
+    }
+    /** Works out which captures the call offers ({@link CaptureOffers$}) and publishes a change. */
+    refreshCaptureOffers() {
+        const offers = this.captures && this.client?.SupportsInboundVideo ? { Camera: this.canOffer('camera'), Screen: this.canOffer('screen') } : REALTIME_CAPTURE_OFFERS_NONE;
+        const current = this._captureOffers$.value;
+        if (offers.Camera !== current.Camera || offers.Screen !== current.Screen) {
+            this._captureOffers$.next(offers);
+        }
+    }
+    /** Whether the host can open a capture and the call's policy admits it. */
+    canOffer(kind) {
+        const hostCanOpen = kind === 'camera' ? this.localMedia !== null : typeof this.mediaHost.RequestDisplayCapture === 'function';
+        return hostCanOpen && this.admitCapture(kind).Admitted;
+    }
+    /** What a capture reports when there is no live session to show it to. */
+    noSessionCapture() {
+        return { Status: 'failed', Failure: 'no-session', Message: 'There is no call to share with.' };
+    }
+    /**
+     * The session's policy for a capture. The channel that fronts it (its `CaptureKind`) must be in the session, open or
+     * advertised, and the server's policy must let the agent see pixels through it (the agent's configuration and any
+     * zero-data-retention rule). The user's own "agent can see" choice for the channel does not refuse a start: it decides
+     * whether the frames reach the model.
+     */
+    admitCapture(kind) {
+        const channel = this.findCaptureChannel(kind)?.Plugin;
+        if (!channel) {
+            return { Admitted: false, Message: CAPTURE_WORDING[kind].NotInCall };
+        }
+        const resolved = this.GetResolvedChannel(channel.ChannelName);
+        const allowed = resolved?.Exposure ?? resolved?.MaxExposure ?? channel.GetDescriptor().MaxExposure;
+        if (allowed !== 'pixels') {
+            const reasons = (resolved?.ExposureLimits ?? []).map((limit) => limit.Reason);
+            return { Admitted: false, Message: reasons.length > 0 ? `${CAPTURE_WORDING[kind].NotAllowed}: ${reasons.join('; ')}.` : `${CAPTURE_WORDING[kind].NotAllowed}.` };
+        }
+        return { Admitted: true, ChannelKey: channel.ChannelName, VisibleToAgent: channel.Exposure === 'pixels' };
+    }
+    /** The channel in the session, open or advertised, that fronts a capture. */
+    findCaptureChannel(kind) {
+        const open = this._activeChannels$.value.find((c) => c.CaptureKind === kind);
+        if (open) {
+            return { Plugin: open, IsOpen: true };
+        }
+        const advertised = this.advertisedChannels.find((p) => p.Plugin.CaptureKind === kind);
+        return advertised ? { Plugin: advertised.Plugin, IsOpen: false } : null;
+    }
+    /**
+     * Brings up the channel that fronts a capture once the capture is starting, so the host shows its surface: an advertised
+     * channel is opened (and announces itself to the agent), an open one counts as used.
+     */
+    async revealCaptureChannel(kind) {
+        const state = kind === 'camera' ? this.captures?.States.Camera : this.captures?.States.Screen;
+        const channel = state?.Status === 'starting' ? this.findCaptureChannel(kind) : null;
+        if (!channel) {
+            return;
+        }
+        if (channel.IsOpen) {
+            this.noteChannelActivity(channel.Plugin);
+            return;
+        }
+        const opened = await this.OpenChannel(channel.Plugin.ChannelName);
+        if (!opened.Success) {
+            console.warn(`[RealtimeSession] Could not open channel '${channel.Plugin.ChannelName}' for the ${kind}: ${opened.ErrorMessage ?? opened.ErrorCode}`);
+        }
+    }
+    /**
+     * Starts the user's camera and shows it to the agent. Call it from the user's click: it may ask for camera
+     * permission. Resolves with the camera's state; a failure (no session, a model that takes no video, a refused
+     * permission) is a state with a message, never a throw. While the camera is on, it is a source on
+     * {@link VideoSources$}, and it stops by itself if the device goes away.
+     *
+     * When the host shows a camera check ({@link RealtimeSessionStartOptions.CameraCheck}), the call's first start
+     * resolves still starting, with `Checking` set and the stream for the host to preview. The agent sees the camera
+     * once the host calls {@link ConfirmCamera}; {@link StopCamera} is the user's "not now".
+     *
+     * @param deviceId The camera to open; the system default when absent.
+     */
+    async StartCamera(deviceId) {
+        if (!this.captures) {
+            return this.noSessionCapture();
+        }
+        const started = this.captures.Start('camera', { DeviceID: deviceId });
+        await this.revealCaptureChannel('camera');
+        return started;
+    }
+    /** Stops the user's camera. Safe to call when it is off. */
+    StopCamera() {
+        this.captures?.Stop('camera');
+    }
+    /**
+     * Moves the user's camera to another device while it is open (being checked or on): one of the camera's `Devices` on
+     * {@link Captures$}. The stream stays the same. Resolves with the camera's state; nothing changes while the camera is
+     * off.
+     *
+     * @param deviceId The camera to move to.
+     */
+    async SwitchCamera(deviceId) {
+        return this.captures ? this.captures.SwitchCamera(deviceId) : this.noSessionCapture();
+    }
+    /**
+     * Moves the call's microphone to another device: one of the `Devices` on {@link Microphone$}. The host's controller
+     * swaps the new track into the same stream and carries the mute over, and the driver and the call's recording move to
+     * it, so the agent keeps hearing the user. When the new microphone cannot open, the controller goes back to the one in
+     * use. While the call has no microphone open (it lost the one in use and the default, or the last one went away), the
+     * pick opens one again: the driver and the recording move to it, and it keeps the call's mute. Resolves with the
+     * microphone's state once the switch is over. Nothing changes outside a call or on a host without a controller.
+     *
+     * @param deviceId The microphone to move to.
+     */
+    async SwitchMicrophone(deviceId) {
+        const controller = this.localMedia;
+        if (controller && this.microphoneOffered) {
+            const status = controller.State.Microphone.Status;
+            const live = status === 'on' || status === 'starting';
+            await (live ? controller.SwitchDevice('microphone', deviceId) : controller.Start('microphone', deviceId));
+        }
+        return this._microphone$.value;
+    }
+    /**
+     * The user checked the camera and turned it on: the agent sees it from now on, and later camera starts in this call
+     * skip the check. Returns the camera's state; unless the camera is waiting for its check (see {@link StartCamera}),
+     * nothing changes.
+     */
+    ConfirmCamera() {
+        return this.captures ? this.captures.ConfirmCamera() : this.noSessionCapture();
+    }
+    /**
+     * Asks the user for a screen, window or browser tab (or one panel of the page) and shows it to the agent. Call it
+     * from the user's click: the browser's picker needs one. Resolves with the share's state; a failure (no session,
+     * a model that takes no video, a closed picker, a host that cannot share) is a state with a message. The share
+     * also stops when the user ends it from the browser's own bar.
+     *
+     * @param options What the picker offers first, or the panel to share and its name (`PanelLabel`), which the share's
+     *   state carries and the agent sees as "<name> (shared panel)".
+     */
+    async StartScreenShare(options) {
+        if (!this.captures) {
+            return this.noSessionCapture();
+        }
+        const started = this.captures.Start('screen', options);
+        await this.revealCaptureChannel('screen');
+        return started;
+    }
+    /** Stops the user's screen share. Safe to call when nothing is shared. */
+    StopScreenShare() {
+        this.captures?.Stop('screen');
+    }
+    /**
+     * Why the latest session start failed, or `null` when it has not failed or none has run.
      *
      * Read it when {@link ConnectionState$} reports `'error'`, to tell a denied microphone apart from
-     * a provider or backend failure and show copy the user can act on. Cleared at the start of every
-     * session.
+     * a provider or backend failure and show copy the user can act on. Each start clears it before it
+     * reports `'connecting'`, so it never describes an earlier start.
      */
     get LastStartError() {
         return this.lastStartError;
     }
+    /**
+     * The fatal error the call's client reported, or `null` when it has reported none.
+     *
+     * Read it when {@link ConnectionState$} reports `'error'` on a call that was live, to tell a call that reached its time
+     * limit (`Code` `'time-limit'`; {@link DescribeCallEnd} words it) from a dropped connection. Each start clears it before
+     * it reports `'connecting'`.
+     */
+    get LastSessionError() {
+        return this.lastSessionError;
+    }
     /**
      * The single failure path for a session start (mint half or run half): report it, latch the
      * overlay into 'error', and unwind whatever the half-built session already opened.
@@ -779,7 +1546,7 @@ export class RealtimeSessionRuntime {
     async failSessionStart(error) {
         console.error('[RealtimeSession] Failed to start session:', error);
         this.lastStartError = error instanceof Error ? error : new Error(String(error));
-        this._connectionState$.next('error');
+        this.setConnectionState('error');
         await this.teardown(false);
     }
     /**
@@ -818,14 +1585,19 @@ export class RealtimeSessionRuntime {
         // Relay as a user turn — same path spoken input uses (caption + persisted transcript).
         void this.onUserTranscript(trimmed);
     }
-    /** Mute / unmute the local microphone track. Returns the new muted state. */
+    /**
+     * Mute / unmute the local microphone track. Returns the new muted state. While the call has no microphone track (a
+     * switch is putting a new one in, or the call lost its microphone) there is nothing to mute: nothing changes, and it
+     * returns the call's mute, which the next microphone keeps. Outside a call it returns `false`.
+     */
     ToggleMute() {
         const tracks = this.localStream?.getAudioTracks() ?? [];
         if (tracks.length === 0) {
-            return false;
+            return this.microphoneMuted;
         }
         const muted = tracks[0].enabled; // currently enabled → becomes muted
         this.client?.SetMuted(muted);
+        this.microphoneMuted = muted;
         return muted;
     }
     // ── Client-executed UI tools ───────────────────────────────────────────────
@@ -895,13 +1667,21 @@ export class RealtimeSessionRuntime {
         return this.client;
     }
     /**
-     * Relays a video frame to the underlying realtime client if active.
+     * Relays a video frame straight to the underlying realtime client, if a session is live.
+     *
+     * It bypasses the session's {@link VideoSourceArbiter}: the frame overrides the source the arbiter picked, and the
+     * model is not told what it is looking at. Channels no longer send through it (their context's `SendVideoFrame` goes
+     * through the arbiter); a host that shows the model something registers a source there instead, as
+     * `ChannelInboundVideoBridge` does.
+     *
+     * @returns `true` when the client accepted and sent the frame; `false` when no session is live, the
+     *   client cannot take video frames, or the client dropped the frame.
      */
     SendVideoFrame(base64Image, mimeType) {
         if (!this.client || !this.isSessionLive()) {
-            return;
+            return false;
         }
-        this.client.SendVideoFrame?.(base64Image, mimeType);
+        return this.client.SendVideoFrame?.(base64Image, mimeType) === true;
     }
     /**
      * Checks whether a media track is established on the active realtime client.
@@ -949,9 +1729,11 @@ export class RealtimeSessionRuntime {
             this.currentTurnStartMs = recorder.IsRecording ? 0 : null;
             this.turnAudioStartCaptured = false;
             if (this.recorder) {
-                // The agent's WebRTC audio track usually lands AFTER Connect() resolves, so `remoteStream`
-                // above is typically null and we'd capture mic-only. Attach the agent stream whenever it
-                // arrives (fires immediately if already present) so the recording includes the agent voice.
+                // WebRTC drivers (OpenAI): the agent's track usually lands AFTER Connect() resolves, so
+                // `remoteStream` above is null here and this handler attaches it later. PCM-playback
+                // drivers (Gemini, ElevenLabs, AssemblyAI, xAI, HuggingFace) publish at Connect, so
+                // `remoteStream` is already set and the handler fires immediately with the same stream;
+                // AttachRemoteStream is idempotent, so it is mixed only once.
                 client.OnRemoteMediaStream?.((stream) => this.recorder?.AttachRemoteStream(stream));
                 this.startSegmentFlushing();
             }
@@ -963,7 +1745,7 @@ export class RealtimeSessionRuntime {
     }
     /** Begins flushing ~15s crash-recovery shards to the server for the duration of the recording. */
     startSegmentFlushing() {
-        this.segmentIndex = 0;
+        this.shardQueue = new RecordingShardQueue();
         this.segmentTimer = setInterval(() => { void this.flushRecordingSegment(); }, RealtimeSessionRuntime.segmentFlushMs);
     }
     /** Stops the periodic crash-recovery shard flush. */
@@ -1030,48 +1812,64 @@ export class RealtimeSessionRuntime {
     }
     /**
      * Uploads the chunks captured since the last flush as one crash-recovery shard (durability only;
-     * the canonical file is still the full upload at teardown). Best-effort — never disturbs the call.
+     * the canonical file is still the full upload at teardown). Best-effort — never disturbs the call:
+     * a failed shard is retained by the queue and resent under its own index on later flushes, up to a
+     * bounded number of attempts (#5197).
      */
     async flushRecordingSegment() {
         const recorder = this.recorder;
         const agentSessionId = this.agentSessionId;
-        if (!recorder || !agentSessionId) {
+        const queue = this.shardQueue;
+        if (!recorder || !agentSessionId || !queue) {
             return;
         }
-        try {
-            const audioBase64 = await recorder.SnapshotNewSegmentBase64();
-            if (!audioBase64) {
-                return;
-            }
-            const index = this.segmentIndex++;
-            const mutation = `
-        mutation UploadRealtimeRecordingSegment($agentSessionId: String!, $segmentIndex: Int!, $audioBase64: String!, $mimeType: String!) {
-          UploadRealtimeRecordingSegment(agentSessionId: $agentSessionId, segmentIndex: $segmentIndex, audioBase64: $audioBase64, mimeType: $mimeType)
-        }
-      `;
-            // Shards are HEADER-LESS raw little-endian PCM16 (mime audio/L16 with the capture sample rate),
-            // NOT individually-playable WAV — recovery is concatenate-in-order then WAV-wrap. The canonical
-            // seekable WAV is the consolidated end-of-call upload below.
-            const shardMime = `audio/L16;rate=${recorder.SampleRate}`;
-            await this.gql().ExecuteGQL(mutation, { agentSessionId, segmentIndex: index, audioBase64, mimeType: shardMime });
-        }
-        catch (error) {
-            console.warn('[RealtimeSession] Failed to flush recording shard:', error);
-        }
+        // Read once: a shard's sample rate is fixed at capture, and the recorder may be stopped by the
+        // time a retry of it runs.
+        const sampleRate = recorder.SampleRate;
+        await queue.Flush(() => recorder.SnapshotNewSegmentBase64(), (segmentIndex, audioBase64) => this.uploadRecordingShard(agentSessionId, sampleRate, segmentIndex, audioBase64));
     }
     /**
-     * Stops the active recorder and uploads the captured audio via `UploadRealtimeRecording`.
-     * Fully best-effort and wrapped in try/catch — recording upload must NEVER block teardown.
-     * No-op when nothing was recorded or there's no session id to attach the file to.
+     * Sends one shard and reports whether the server stored it. The resolver reports a failed
+     * ownership load or storage write as `false`, not as an error — that is how #5197 lost a shard
+     * without a single client-side log line — so the typed result must be checked, not just the absence
+     * of a throw.
      */
-    async stopAndUploadRecording(agentSessionId) {
+    async uploadRecordingShard(agentSessionId, sampleRate, segmentIndex, audioBase64) {
+        const mutation = `
+      mutation UploadRealtimeRecordingSegment($agentSessionId: String!, $segmentIndex: Int!, $audioBase64: String!, $mimeType: String!) {
+        UploadRealtimeRecordingSegment(agentSessionId: $agentSessionId, segmentIndex: $segmentIndex, audioBase64: $audioBase64, mimeType: $mimeType)
+      }
+    `;
+        // Shards are HEADER-LESS raw little-endian PCM16 (mime audio/L16 with the capture sample rate),
+        // NOT individually-playable WAV — recovery is concatenate-in-order then WAV-wrap. The canonical
+        // seekable WAV is the consolidated end-of-call upload below.
+        const shardMime = `audio/L16;rate=${sampleRate}`;
+        const result = (await this.gql().ExecuteGQL(mutation, {
+            agentSessionId,
+            segmentIndex,
+            audioBase64,
+            mimeType: shardMime,
+        }));
+        return result?.UploadRealtimeRecordingSegment === true;
+    }
+    /**
+     * Stops the active recorder and encodes the captured audio. Split from the upload so teardown can
+     * close the server session in between (#5195). Best-effort: returns `null` when nothing was
+     * recorded or the stop failed (warned) — it must NEVER block teardown.
+     */
+    async stopRecording() {
         this.stopSegmentFlushing();
+        // Close the queue with the recording: its retained shards (base64 audio) are released now, not at
+        // the next session start, and a flush still in flight stops sending, so no resend lands after the
+        // end-of-call upload below has deleted the shards.
+        this.shardQueue?.Close();
+        this.shardQueue = null;
         const recorder = this.recorder;
         this.recorder = null;
         this.currentTurnStartMs = null;
         this.turnAudioStartCaptured = false;
         if (!recorder) {
-            return;
+            return null;
         }
         try {
             // Capture the recorder MIME (now 'audio/wav') BEFORE Stop() — the getter reads '' once stopped.
@@ -1079,18 +1877,39 @@ export class RealtimeSessionRuntime {
             const audioBase64 = await recorder.StopAndEncode();
             // Read the real waveform peaks computed during capture (survives the stop via the snapshot).
             const peaks = recorder.GetPeaks();
-            if (!audioBase64 || !agentSessionId) {
-                console.warn('[RealtimeSession] ⚠️ recording NOT uploaded — empty recording or no session id.');
-                return;
+            if (!audioBase64) {
+                console.warn('[RealtimeSession] ⚠️ recording NOT uploaded — empty recording.');
+                return null;
             }
-            await this.uploadRecording(agentSessionId, audioBase64, mimeType, peaks);
+            return { MimeType: mimeType, AudioBase64: audioBase64, Peaks: peaks };
+        }
+        catch (error) {
+            console.warn('[RealtimeSession] Failed to stop call recording:', error);
+            return null;
+        }
+    }
+    /**
+     * Uploads a recording returned by {@link stopRecording}. Never throws. No-op when there is
+     * nothing to upload; warns when there is no session id to attach the file to.
+     */
+    async uploadStoppedRecording(agentSessionId, recording) {
+        if (!recording) {
+            return;
+        }
+        if (!agentSessionId) {
+            console.warn('[RealtimeSession] ⚠️ recording NOT uploaded — no session id.');
+            return;
+        }
+        try {
+            await this.uploadRecording(agentSessionId, recording.AudioBase64, recording.MimeType, recording.Peaks);
         }
         catch (error) {
-            console.warn('[RealtimeSession] Failed to stop/upload call recording:', error);
+            console.warn(`[RealtimeSession] Failed to upload call recording for session ${agentSessionId}:`, error);
         }
     }
     /**
-     * Runs the `UploadRealtimeRecording` mutation; failures are logged, never thrown. Sends the
+     * Runs the `UploadRealtimeRecording` mutation. A `Success:false` payload is logged; a transport
+     * rejection propagates to `uploadStoppedRecording`, which catches and logs it. Sends the
      * capture-time waveform `peaks` (max-abs per bucket, normalized 0..1) so the server can persist a
      * `peaks.json` sidecar for fast waveform rendering without re-decoding the audio.
      */
@@ -1116,81 +1935,458 @@ export class RealtimeSessionRuntime {
             console.warn(`[RealtimeSession] ❌ recording upload reported failure: ${payload?.ErrorMessage ?? 'unknown error'} (full result: ${JSON.stringify(result)})`);
         }
     }
-    // ── Interactive channels (registry-driven plugins) ─────────────────────────
     /**
-     * Resolves, instantiates and initializes the session's interactive-channel plugins from
-     * the `MJ: AI Agent Channels` registry, publishes them on {@link ActiveChannels$}, and
-     * returns their aggregated client-executed tool declarations for the session mint.
-     * Tolerant by design: registry/resolution failures degrade to "no channels" — the voice
-     * session itself always proceeds.
+     * The resolved behavior of an in-session channel (display, exposure ceiling, config, what put it
+     * in the session), or `null` when the channel is not in this session. Hosts and overlays read the
+     * resolved display from here rather than from the channel's code default.
+     *
+     * @param channelName The channel's key (case-insensitive).
+     */
+    GetResolvedChannel(channelName) {
+        return this.resolvedChannels.get(NormalizeChannelKey(channelName)) ?? null;
+    }
+    /**
+     * Replaces the store the user's per-channel exposure choices are kept in. The default persists them in
+     * the signed-in user's settings (`mj.realtime.visualPerception.v1`) and keeps them in memory for an
+     * anonymous principal or a connect-only embed; a host that remembers them somewhere else supplies its own.
+     */
+    SetExposurePreferences(preferences) {
+        this.exposurePreferences = preferences;
+    }
+    /** The store the user's per-channel exposure choices are currently kept in (so a host can wrap it). */
+    get ExposurePreferences() {
+        return this.exposurePreferences;
+    }
+    /** Whether user settings can be written: a signed-in user on a provider that has entity metadata. */
+    canPersistUserSettings() {
+        const provider = this.Provider;
+        return Boolean(provider?.CurrentUser?.ID) && (provider?.Entities?.length ?? 0) > 0;
+    }
+    /**
+     * How much of a channel the model may perceive right now: the channel's ceiling, lowered by the server's
+     * policy and the user's choice. `null` when the channel is not in this session.
+     *
+     * @param channelName The channel's key (case-insensitive).
+     */
+    GetChannelExposure(channelName) {
+        return this.findDispatchableChannel(channelName)?.Plugin.Exposure ?? null;
+    }
+    /**
+     * The user's own choice of how much of a channel the agent may perceive. Takes effect immediately
+     * (frames and notes the new level forbids stop, and the model is told), and is remembered per channel key
+     * for next time. The level can only LOWER what the server's policy allows; choosing `'pixels'` for a channel
+     * the agent's policy capped at `'state'` changes nothing.
+     *
+     * @param channelName The channel's key (case-insensitive).
+     * @param level The user's choice; `undefined` clears it (back to what policy allows).
+     * @returns `false` when the channel is not in this session (nothing is applied, but the choice is still remembered).
+     */
+    SetUserChannelExposure(channelName, level) {
+        this.exposurePreferences.Set(channelName, level);
+        const channel = this.findDispatchableChannel(channelName);
+        if (!channel) {
+            return false;
+        }
+        this.applyChannelExposure(channel.Plugin);
+        return true;
+    }
+    /** Pushes a channel's current exposure inputs (server policy, user choice) into the channel. */
+    applyChannelExposure(plugin) {
+        const resolved = this.GetResolvedChannel(plugin.ChannelName);
+        const user = this.exposurePreferences.Get(plugin.ChannelName);
+        const reasons = (resolved?.ExposureLimits ?? []).map((limit) => limit.Reason);
+        // The user's limit binds only when it is lower than what the server allows; otherwise it changes nothing
+        // and the agent should not be told about it.
+        const allowed = resolved?.Exposure ?? plugin.GetDescriptor().MaxExposure;
+        if (user !== undefined && CompareExposure(user, allowed) < 0) {
+            reasons.push(UserExposureReason(user));
+        }
+        plugin.ApplyExposure({ Policy: resolved?.Exposure, User: user, Reasons: reasons });
+        // A capture this channel fronts follows it: the agent sees its frames only while the channel's exposure allows pixels.
+        const kind = plugin.CaptureKind;
+        if (kind) {
+            this.captures?.SetVisibleToAgent(kind, plugin.Exposure === 'pixels');
+        }
+        this.syncChannelVideoSource(plugin);
+    }
+    /**
+     * Sends a frame from a channel's context ({@link RealtimeChannelContext.SendVideoFrame}, deprecated) through the
+     * session's {@link VideoSourceArbiter}, as the channel's own source: it reaches the model only while the arbiter picks
+     * that source, and the arbiter tells the model when it switches. The source registers with the first frame, under the
+     * id the channel's own frame bridge uses, switched on only while the channel's exposure allows pixels.
+     */
+    sendChannelVideoFrame(plugin, base64Image, mimeType) {
+        const client = this.client;
+        if (!client || !this.isSessionLive() || !client.IsTrackEstablished('video', 'inbound')) {
+            return;
+        }
+        const arbiter = VideoSourceArbiter.ForSink(client);
+        const descriptor = plugin.GetDescriptor();
+        const sourceId = ChannelVideoSourceID(descriptor.Key, plugin.InstanceId);
+        if (!arbiter.HasSource(sourceId)) {
+            arbiter.RegisterSource({
+                SourceID: sourceId,
+                Label: descriptor.DisplayName,
+                Kind: 'surface',
+                ChannelKey: descriptor.Key,
+                Enabled: plugin.Exposure === 'pixels',
+            });
+        }
+        arbiter.PushFrame(sourceId, base64Image, mimeType);
+    }
+    /**
+     * Keeps a channel's video source at the arbiter, when it has one, in step with the channel's exposure: on while the
+     * agent may see its pixels, off otherwise. Quiet, because the channel tells the model about its own exposure change.
+     */
+    syncChannelVideoSource(plugin) {
+        if (!this.client) {
+            return;
+        }
+        const arbiter = VideoSourceArbiter.ForSink(this.client);
+        const sourceId = ChannelVideoSourceID(plugin.GetDescriptor().Key, plugin.InstanceId);
+        if (arbiter.HasSource(sourceId)) {
+            arbiter.SetSourceEnabled(sourceId, plugin.Exposure === 'pixels', false);
+        }
+    }
+    /** Follows the session client's video-source arbiter so {@link VideoSources$} reflects it. */
+    watchVideoSources(client) {
+        this.unwatchVideoSources();
+        const arbiter = VideoSourceArbiter.ForSink(client);
+        arbiter.SetFocusedChannel(this.focusedChannelKey);
+        this.stopWatchingVideoSources = arbiter.OnChange(() => this._videoSources$.next(arbiter.GetSources()));
+        this._videoSources$.next(arbiter.GetSources());
+    }
+    /**
+     * Tells the session which channel's surface the user is looking at (`null` for none, e.g. the activity tab).
+     * When the model can see only one video source and several are live, the one the user is looking at is the one
+     * it sees (after an explicit pick, and after a camera or screen share the user started). Safe to call before the
+     * session is live: it applies when the connection comes up.
+     *
+     * @param channelKey The focused channel's key, as it appears on {@link VideoSources$} entries' `ChannelKey`.
+     */
+    SetFocusedChannel(channelKey) {
+        this.focusedChannelKey = channelKey;
+        if (this.client) {
+            VideoSourceArbiter.ForSink(this.client).SetFocusedChannel(channelKey);
+        }
+    }
+    /** Stops following the arbiter and clears {@link VideoSources$}. Safe to call when nothing is watched. */
+    unwatchVideoSources() {
+        this.stopWatchingVideoSources?.();
+        this.stopWatchingVideoSources = null;
+        if (this._videoSources$.value.length > 0) {
+            this._videoSources$.next([]);
+        }
+    }
+    /**
+     * Turns the agent's view of one video source on or off — what the "agent can see" control calls.
+     *
+     * A source that belongs to a channel goes through {@link SetUserChannelExposure}, so the choice is
+     * remembered per channel and the channel itself tells the model. Any other source (a camera or screen
+     * share that is not a channel) is switched at the arbiter, which tells the model.
+     *
+     * @param sourceId The source's id (from {@link VideoSources$}).
+     * @param enabled Whether the agent may see it.
+     * @returns `false` when there is no such source.
      */
-    async startChannels() {
-        const channels = await this.loadActiveChannels();
-        for (const plugin of channels) {
-            this.initializeChannel(plugin);
+    SetVideoSourceEnabled(sourceId, enabled) {
+        const client = this.client;
+        if (!client) {
+            return false;
+        }
+        const arbiter = VideoSourceArbiter.ForSink(client);
+        const source = arbiter.GetSources().find((s) => s.SourceID === sourceId);
+        if (!source) {
+            return false;
         }
-        this._activeChannels$.next(channels);
-        return channels.flatMap(plugin => plugin.GetToolDefinitions());
+        if (source.ChannelKey && this.findDispatchableChannel(source.ChannelKey)) {
+            return this.SetUserChannelExposure(source.ChannelKey, enabled ? undefined : 'state');
+        }
+        return arbiter.SetSourceEnabled(sourceId, enabled);
+    }
+    /**
+     * Picks the video source the agent sees: what the "agent can see" control calls when more sources are on than the
+     * model takes. The pick beats every other rule (a camera or screen share the user started, the surface the user is
+     * looking at) until it is cleared, or its source is turned off or leaves. The pick shows on {@link VideoSources$}
+     * (`Picked`), and the model is told when what it sees changes.
+     *
+     * @param sourceId The source's id (from {@link VideoSources$}), or `null` to let the call decide again.
+     * @returns `false` with no live session, or for a source that is not there or is turned off.
+     */
+    SelectVideoSource(sourceId) {
+        return this.client ? VideoSourceArbiter.ForSink(this.client).SelectSource(sourceId) : false;
+    }
+    /**
+     * The `on-demand` channels that are in the session but not open yet — what the agent can open
+     * through `ContextTool`. A fresh array; empty before a session starts and after teardown.
+     */
+    get AdvertisedChannels() {
+        return this.advertisedChannels.map((p) => p.Plugin);
+    }
+    /**
+     * Resolves, initializes and mounts the session's channels in one step using the scope the browser
+     * can decide alone (code defaults + host declarations), and returns the native tools to declare at
+     * mint. This is the single-step composition of {@link prepareChannelScope} + {@link activateChannels}
+     * that a session start spreads across the mint; it is kept as a unit because it is the cleanest seam
+     * for exercising the plugin plumbing without a mint.
+     */
+    async startChannels(hostChannels) {
+        const scope = await this.prepareChannelScope(hostChannels);
+        this.activateChannels(this.localChannelScope?.Channels ?? []);
+        return scope.NativeTools;
+    }
+    /**
+     * Stage 1: constructs the channel plugins (registry rows and host declarations), reads their
+     * descriptors, resolves the scope the browser can decide alone, and builds what the mint needs —
+     * the native tools to declare and the candidates to report. Starts nothing.
+     *
+     * @param hostChannels Channels the host brings to this session.
+     * @returns The native tools to declare at mint, the candidates as JSON (`null` when there are none,
+     *   so a channel-less session sends exactly the mint it always did), and whether the host could show the agent's
+     *   video ({@link PreparedChannelsShowAgentVideo}).
+     */
+    async prepareChannelScope(hostChannels) {
+        this.discardUnmountedChannels();
+        const prepared = await this.prepareChannels(hostChannels);
+        this.preparedChannels = prepared;
+        const candidates = prepared.map((p) => BuildChannelCandidate(p, p.Plugin.GetDescriptor()));
+        const local = ResolveLocalChannelScope(candidates);
+        this.localChannelScope = local;
+        for (const excluded of local.Excluded) {
+            console.warn(`[RealtimeSession] Channel '${excluded.Key}' is not in this session (${excluded.Reason}).`);
+        }
+        const nativeTools = SelectNativeChannelTools(local.Channels, ToolsByChannelKey(candidates));
+        // `Registry` is the browser's own view and never goes over the wire: the server reads the registry itself.
+        const wire = candidates.map(({ Registry: _registry, ...candidate }) => candidate);
+        return { NativeTools: nativeTools, CandidatesJson: wire.length > 0 ? JSON.stringify(wire) : null, ShowsAgentVideo: PreparedChannelsShowAgentVideo(prepared) };
     }
     /**
-     * Loads the ACTIVE channel definitions from the registry and resolves each row's
-     * `ClientPluginClass` through the MJ ClassFactory into a per-session plugin instance —
-     * the client-side mirror of how realtime-model drivers resolve from `BaseRealtimeModel`
-     * / `BaseRealtimeClient`. Rows whose plugin class isn't registered are skipped (logged),
-     * never fatal.
+     * Constructs a plugin for every active-or-inactive registry row and every host declaration. An
+     * INACTIVE row is constructed too — only to learn its key so the kill switch can name it — and is
+     * never initialized. A plugin whose descriptor cannot be read is skipped (logged), never fatal.
      */
-    async loadActiveChannels() {
+    async prepareChannels(hostChannels) {
         const rows = await this.fetchChannelDefinitions();
-        const channels = [];
+        await this.loadChannelClasses([...rows.map((r) => r.ClientPluginClass), ...(hostChannels ?? []).map((d) => d.ClientPluginClass)]);
+        const prepared = [];
         for (const row of rows) {
             const plugin = this.resolveChannelPlugin(row);
             if (plugin) {
-                channels.push(plugin);
+                plugin.ApplySurfacePlacement(row.SurfacePlacement);
+                prepared.push({ Plugin: plugin, Key: plugin.ChannelName, Registry: row.IsActive ? 'active' : 'inactive' });
             }
         }
-        return channels;
+        for (const declaration of hostChannels ?? []) {
+            const plugin = this.createHostChannelPlugin(declaration);
+            if (!plugin) {
+                continue;
+            }
+            const existing = FindPreparedChannel(prepared, plugin.ChannelName);
+            if (existing) {
+                // The host's instance replaces the registry's (it may carry the host's collaborators); the
+                // registry row's state — notably the kill switch, and where its surface shows — still applies.
+                plugin.ApplySurfacePlacement(existing.Plugin.SurfacePlacement);
+                existing.Plugin = plugin;
+                existing.HostDeclaration = declaration;
+            }
+            else {
+                prepared.push({ Plugin: plugin, Key: plugin.ChannelName, Registry: 'none', HostDeclaration: declaration });
+            }
+        }
+        return prepared.filter((p) => this.canDescribe(p));
     }
     /**
-     * Reads the ACTIVE `MJ: AI Agent Channels` rows from {@link AIEngineBase}'s cached
-     * `AgentChannels` (provider-scoped engine instance, lazy `Config` — no RunView
-     * round-trip; the engine's BaseEntity-event reactivity keeps the registry fresh).
-     * Failures are logged and degrade to an empty list — channel availability must
-     * never block the voice session.
+     * Gives a host that loads channel code on demand (a widget that keeps a heavy channel in its own download)
+     * the chance to load it before the plugins are built. Never fatal: a loader that throws is logged and the
+     * channel simply is not available, exactly as if its class had never been registered.
+     *
+     * @param keys The `ClientPluginClass` keys of every channel about to be resolved (blank/absent ones included).
+     */
+    async loadChannelClasses(keys) {
+        const loader = this.ChannelClassLoader;
+        if (!loader) {
+            return;
+        }
+        const wanted = [...new Set(keys.map((k) => k?.trim() ?? '').filter((k) => k.length > 0))];
+        if (wanted.length === 0) {
+            return;
+        }
+        try {
+            await loader(wanted);
+        }
+        catch (error) {
+            console.error('[RealtimeSession] The channel class loader failed — channels that needed it are left out:', error);
+        }
+    }
+    /** Whether a prepared plugin's descriptor can be read; logs and rejects one that throws. */
+    canDescribe(prepared) {
+        try {
+            prepared.Plugin.GetDescriptor();
+            return true;
+        }
+        catch (error) {
+            console.error(`[RealtimeSession] Channel '${prepared.Key}' has an unreadable descriptor — leaving it out:`, error);
+            return false;
+        }
+    }
+    /** Builds a plugin from a host declaration; `null` (logged) when it names nothing buildable. */
+    createHostChannelPlugin(declaration) {
+        if (declaration.Create) {
+            try {
+                return declaration.Create();
+            }
+            catch (error) {
+                console.error('[RealtimeSession] A host-declared channel factory threw — leaving the channel out:', error);
+                return null;
+            }
+        }
+        const key = declaration.ClientPluginClass?.trim();
+        if (!key) {
+            console.warn('[RealtimeSession] A host-declared channel names neither ClientPluginClass nor Create — ignoring it.');
+            return null;
+        }
+        return this.resolveChannelPlugin({ Name: key, ClientPluginClass: key, IsActive: true });
+    }
+    /**
+     * Stage 3: initializes the channels the resolved policy puts in the session. `open-on-start` and
+     * `headless` channels are mounted and published on {@link ActiveChannels$}; `on-demand` channels
+     * are held until opened. Prepared plugins the policy left out are dropped without ever having run.
+     */
+    activateChannels(channels) {
+        const reconciled = ReconcileChannelsWithPolicy(this.preparedChannels, channels);
+        for (const key of reconciled.Unknown) {
+            console.warn(`[RealtimeSession] The session policy names channel '${key}' but this host has no plugin for it — ignoring it.`);
+        }
+        this.resolvedChannels.clear();
+        this.advertisedChannels = [];
+        const mounted = [];
+        for (const { Prepared, Resolved } of reconciled.InSession) {
+            this.resolvedChannels.set(NormalizeChannelKey(Resolved.Key), Resolved);
+            // Exposure is applied BEFORE the channel initializes, so what it requests of the model (a video
+            // track, in particular) already reflects what policy allows.
+            this.applyChannelExposure(Prepared.Plugin);
+            if (Resolved.DisplayPolicy === 'on-demand') {
+                this.advertisedChannels.push(Prepared);
+            }
+            else {
+                this.mountChannel(Prepared, Resolved);
+                mounted.push(Prepared.Plugin);
+            }
+        }
+        this.preparedChannels = [];
+        this._activeChannels$.next(mounted);
+    }
+    /**
+     * Applies the mint's outcome to the channel set: the server's policy when it sent a usable one,
+     * else the scope the browser resolved on its own. A policy can only SELECT among the plugins this
+     * host prepared — it cannot add one.
+     */
+    applySessionClientPolicy(session) {
+        const policy = ParseRealtimeSessionClientPolicy(session.ClientPolicyJson);
+        if (session.ClientPolicyJson && !policy) {
+            console.warn('[RealtimeSession] The mint returned a client policy this runtime cannot read — resolving channels locally.');
+        }
+        this.sessionClientTools = policy?.ClientTools ?? null;
+        if (this.preparedChannels.length === 0) {
+            this.resolvedChannels.clear();
+            return; // nothing was prepared (a host that mints and runs the session itself) — no channel set to apply
+        }
+        this.activateChannels(policy?.Channels ?? this.localChannelScope?.Channels ?? []);
+    }
+    /** Drops plugins that were prepared for a start that never mounted them. They were never initialized, so there is nothing to release. */
+    discardUnmountedChannels() {
+        this.preparedChannels = [];
+        this.advertisedChannels = [];
+        this.localChannelScope = null;
+    }
+    /**
+     * Loads the `MJ: AI Agent Channels` registry rows (ACTIVE AND INACTIVE — an inactive row is the master
+     * kill switch, so the scope decision has to see it). With entity metadata: from {@link AIEngineBase}'s
+     * cached `AgentChannels` (provider-scoped engine instance, lazy `Config` — no RunView round-trip; the
+     * engine's BaseEntity-event reactivity keeps the registry fresh). On a connect-only provider: one
+     * `RunDynamicView` query ({@link fetchChannelDefinitionsOverGraphQL}). Failures are logged and degrade to an
+     * empty list — channel availability must never block the voice session.
      */
     async fetchChannelDefinitions() {
         // A connect-only provider (ConnectGraphQLClient — anonymous embeds) has no entity metadata,
         // so AIEngineBase cannot load; asking it would only fail with "Entity … not found in
-        // metadata". An embed brings its own channels, so "no registry channels" is the right answer.
+        // metadata". The registry is still the authority, so read it over GraphQL instead — answering
+        // "no channels" here cost an embed every channel tool (Whiteboard, Media) at mint.
         if ((this.Provider?.Entities?.length ?? 0) === 0) {
-            return [];
+            return this.fetchChannelDefinitionsOverGraphQL();
         }
         try {
             const engine = AIEngineBase.GetProviderInstance(this.Provider, AIEngineBase);
             await engine.Config(false, undefined, this.Provider);
-            return (engine.AgentChannels ?? [])
-                .filter(c => c.IsActive)
-                .map(c => ({ ID: c.ID, Name: c.Name, ClientPluginClass: c.ClientPluginClass }));
+            return (engine.AgentChannels ?? []).map((c) => ({
+                ID: c.ID,
+                Name: c.Name,
+                ClientPluginClass: c.ClientPluginClass,
+                IsActive: c.IsActive,
+                SurfacePlacement: readRowSurfacePlacement(c),
+            }));
         }
         catch (error) {
             console.warn('[RealtimeSession] Channel registry unavailable — starting with no channels:', error);
             return [];
         }
     }
+    /**
+     * The connect-only path of {@link fetchChannelDefinitions}: the same `MJ: AI Agent Channels` rows, active
+     * and inactive (an inactive row is the kill switch), read with a dynamic view because a connect-only client
+     * has no entity metadata to build a typed RunView from. Same tolerance as the engine path — a failure is
+     * logged and means "no channels", never a blocked session.
+     */
+    async fetchChannelDefinitionsOverGraphQL() {
+        const query = `query RealtimeChannelRegistry($input: RunDynamicViewInput!) {
+      RunDynamicView(input: $input) { Success ErrorMessage Results { Data } }
+    }`;
+        try {
+            const result = (await this.gql().ExecuteGQL(query, {
+                input: { EntityName: 'MJ: AI Agent Channels', Fields: ['ID', 'Name', 'ClientPluginClass', 'IsActive', 'UIConfig'] },
+            }));
+            const view = result?.RunDynamicView;
+            if (!view?.Success) {
+                console.warn('[RealtimeSession] Channel registry unavailable — starting with no channels:', view?.ErrorMessage ?? 'no result');
+                return [];
+            }
+            return (view.Results ?? [])
+                .map((r) => JSON.parse(r.Data))
+                .map((row) => ({
+                ID: row.ID,
+                Name: row.Name,
+                ClientPluginClass: row.ClientPluginClass,
+                IsActive: row.IsActive === true,
+                SurfacePlacement: readUIConfigTextSurfacePlacement(row.Name, row.UIConfig),
+            }));
+        }
+        catch (error) {
+            console.warn('[RealtimeSession] Channel registry unavailable — starting with no channels:', error instanceof Error ? error.message : String(error));
+            return [];
+        }
+    }
     /**
      * Resolves one registry row's `ClientPluginClass` via the ClassFactory (registration
      * checked first, exactly like the realtime-client drivers) and instantiates a fresh
      * per-session plugin. Returns `null` (logged) when no plugin is registered for the key
      * — e.g. its Load function was never called or the package isn't included client-side.
+     * An inactive row is resolved quietly: it only needs to be named, and a missing plugin for a
+     * channel nobody wants is not worth a warning.
      */
     resolveChannelPlugin(row) {
         const key = row.ClientPluginClass?.trim();
+        const quiet = !row.IsActive;
         if (!key) {
-            console.warn(`[RealtimeSession] Channel '${row.Name}' has no ClientPluginClass — skipping.`);
+            if (!quiet) {
+                console.warn(`[RealtimeSession] Channel '${row.Name}' has no ClientPluginClass — skipping.`);
+            }
             return null;
         }
         const registration = MJGlobal.Instance.ClassFactory.GetRegistration(BaseRealtimeChannelClient, key);
         if (!registration) {
-            console.warn(`[RealtimeSession] No client plugin registered for channel '${row.Name}' (key '${key}') — skipping.`);
+            if (!quiet) {
+                console.warn(`[RealtimeSession] No client plugin registered for channel '${row.Name}' (key '${key}') — skipping.`);
+            }
             return null;
         }
         const plugin = MJGlobal.Instance.ClassFactory.CreateInstance(BaseRealtimeChannelClient, key);
@@ -1201,24 +2397,157 @@ export class RealtimeSessionRuntime {
         return plugin;
     }
     /**
-     * Wires one plugin into the session: hands it its host context and registers its
-     * prefix-routed local tool executor (so `<ToolNamePrefix>*` calls run in the browser
-     * through {@link BaseRealtimeChannelClient.ApplyAgentTool}, never the server relay).
+     * Wires one plugin into the session: hands it its host context (carrying its resolved config) and,
+     * when it has native tools, registers its prefix-routed local tool executor (so `<ToolNamePrefix>*`
+     * calls run in the browser through {@link BaseRealtimeChannelClient.ApplyAgentTool}, never the
+     * server relay). A channel with no tool prefix has no native route — it is reached through
+     * `ContextTool` — and registering an empty prefix would match EVERY tool name.
      */
-    initializeChannel(plugin) {
-        plugin.Initialize(this.buildChannelContext(plugin));
+    mountChannel(prepared, resolved) {
+        const plugin = prepared.Plugin;
+        plugin.Initialize(this.buildChannelContext(plugin, resolved?.Config));
+        if (plugin.ToolNamePrefix.length === 0) {
+            return;
+        }
         this.RegisterClientToolHandler(plugin.ToolNamePrefix, (toolName, argsJson) => {
             // The agent is ACTING on this channel — surface-discovery signal for the overlay
             // (first activity registers + auto-reveals + focuses the channel tab) before the
             // tool applies. Record the channel as USED so the overlay tabs it (channels other
             // than the whiteboard are tab-less until they're first used).
-            this.usedChannelNames.add(plugin.ChannelName);
-            this._channelActivity$.next(plugin);
+            this.noteChannelActivity(plugin);
+            // A native tool whose result would show the agent what exposure policy withholds is refused here, as it is on the
+            // ContextTool route; the legacy tool-result shape carries the reason.
+            const withheld = plugin.FindVerbForNativeTool(toolName);
+            const refusal = withheld ? plugin.RefuseVerbForExposure(withheld) : null;
+            if (refusal) {
+                return JSON.stringify({ success: false, errorCode: 'exposure_restricted', error: refusal });
+            }
             return plugin.ApplyAgentTool(toolName, argsJson);
         });
     }
+    /** Records that the agent acted on a channel (the overlay's first-use reveal signal). */
+    noteChannelActivity(plugin) {
+        this.usedChannelNames.add(plugin.ChannelName);
+        this._channelActivity$.next(plugin);
+    }
+    /**
+     * Mounts an advertised `on-demand` channel when the agent opens it: initializes it, restores its
+     * prior-session state, publishes it on {@link ActiveChannels$} (so the overlay can give it a tab)
+     * and, if the call is already connected, tells it so. If initialization throws the channel goes
+     * back to being advertised, so the agent can retry or move on.
+     */
+    async mountAdvertisedChannel(plugin) {
+        const index = this.advertisedChannels.findIndex((p) => p.Plugin === plugin);
+        if (index < 0) {
+            return; // already mounted (or never advertised) — the dispatcher opens it regardless
+        }
+        const [prepared] = this.advertisedChannels.splice(index, 1);
+        try {
+            this.mountChannel(prepared, this.GetResolvedChannel(prepared.Key) ?? undefined);
+        }
+        catch (error) {
+            this.advertisedChannels.splice(index, 0, prepared);
+            throw error;
+        }
+        this.restorePriorChannelState(plugin);
+        this._activeChannels$.next([...this._activeChannels$.value, plugin]);
+        if (this.isSessionLive()) {
+            this.notifyChannelSessionStarted(plugin);
+        }
+    }
+    /** Tells a channel the session is connected, containing anything it throws. */
+    notifyChannelSessionStarted(channel) {
+        try {
+            channel.OnSessionStarted?.();
+        }
+        catch (err) {
+            console.error(`[RealtimeSession] Error in channel '${channel.ChannelName}' OnSessionStarted:`, err);
+        }
+    }
+    /** Finds a session channel (open or merely advertised) for the dispatcher. */
+    findDispatchableChannel(key) {
+        const id = NormalizeChannelKey(key);
+        const open = this._activeChannels$.value.find((c) => NormalizeChannelKey(c.ChannelName) === id);
+        if (open) {
+            return { Plugin: open, IsOpen: true };
+        }
+        const advertised = this.advertisedChannels.find((p) => NormalizeChannelKey(p.Key) === id);
+        return advertised ? { Plugin: advertised.Plugin, IsOpen: false } : null;
+    }
+    /** The keys the agent can address, for "unknown channel" messages — channels with nothing to address are left out. */
+    listAddressableChannelKeys() {
+        const addressable = (plugin) => {
+            const descriptor = plugin.GetDescriptor();
+            return descriptor.Verbs.length > 0 || descriptor.Inputs !== undefined;
+        };
+        return [
+            ...this._activeChannels$.value.filter(addressable).map((c) => c.ChannelName),
+            ...this.advertisedChannels.filter((p) => addressable(p.Plugin)).map((p) => p.Key),
+        ];
+    }
+    /**
+     * Runs a channel-addressed `ContextTool` call (the {@link RealtimeChannelContext.DispatchContextAction}
+     * implementation): validates it, opens an `on-demand` channel when asked, runs the verb, and on
+     * success records the channel as used so the overlay reveals its tab. Never throws.
+     */
+    async dispatchContextAction(request) {
+        const result = await this.channelDispatcher.Dispatch(request);
+        if (result.Success) {
+            const channel = this.findDispatchableChannel(request.Target.Channel);
+            if (channel) {
+                this.noteChannelActivity(channel.Plugin);
+            }
+        }
+        return result;
+    }
+    /**
+     * Opens (and seeds) a channel from the HOST — the same path the agent's `open` action takes: the channel
+     * is mounted if it was only advertised, its `Inputs` schema validates `inputs`, and it announces itself to
+     * the model. A channel that is already open is re-seeded. Never throws; a refusal is a structured result.
+     *
+     * @param channelKey The channel to open (case-insensitive).
+     * @param inputs Seed inputs, validated against the channel's descriptor.
+     */
+    OpenChannel(channelKey, inputs = {}) {
+        return this.dispatchContextAction({ Target: { Channel: channelKey }, Action: 'open', Params: inputs });
+    }
+    /**
+     * Tells the model which channels exist and how to use them — rendered from the channels' own
+     * descriptors, so a new channel needs no prompt change. Sent ONCE, the first moment the control
+     * channel is usable — a context note sent before then is dropped, and `Connect` can resolve before the
+     * provider reports `listening`, so this runs at start and again on each state change until it has gone.
+     * A session whose only channels describe themselves through native tools sends nothing.
+     */
+    flushChannelCatalogNote() {
+        if (!this.catalogNotePending || !this.isSessionLive()) {
+            return;
+        }
+        this.catalogNotePending = false;
+        const entries = [
+            ...this._activeChannels$.value.map((plugin) => this.catalogEntry(plugin, true)),
+            ...this.advertisedChannels.map((p) => this.catalogEntry(p.Plugin, false)),
+        ];
+        const note = BuildChannelCatalogNote(entries);
+        if (note) {
+            this.SendContextNote(note);
+        }
+    }
+    /** One catalog entry: a channel's descriptor, whether it is open, and whether its tools were declared natively. */
+    catalogEntry(plugin, isOpen) {
+        const display = this.GetResolvedChannel(plugin.ChannelName)?.DisplayPolicy;
+        const descriptor = plugin.GetDescriptor();
+        const entry = {
+            Descriptor: descriptor,
+            IsOpen: isOpen,
+            HasNativeTools: isOpen && display !== undefined && DeclaresNativeTools(display) && plugin.GetToolDefinitions().length > 0,
+        };
+        if (CompareExposure(plugin.Exposure, descriptor.MaxExposure) < 0) {
+            entry.ExposureLimit = { Effective: plugin.Exposure, Ceiling: descriptor.MaxExposure, Reasons: [...plugin.ExposureReasons] };
+        }
+        return entry;
+    }
     /** Builds the host-services context one channel plugin sees (its only line to the session). */
-    buildChannelContext(plugin) {
+    buildChannelContext(plugin, channelConfig) {
         // Capture the service in a local so the AgentSessionID getter reads the SERVICE's live
         // field (not the object literal's `this`) every time it's accessed.
         const service = this;
@@ -1245,55 +2574,107 @@ export class RealtimeSessionRuntime {
             // (Explorer) feeds both; absent on hosts that supply no app context / register no client tools.
             AppContext$: this.AppContext$,
             ExecuteClientTool: (name, params) => this.executeAppClientTool(name, params),
+            // The session's server events (identity verification, app events), for a channel that reacts to them.
+            SessionEvents$: this.SessionEvents$,
+            // Channel-addressed ContextTool calls: validated against the verb's schema, open `on-demand` channels.
+            DispatchContextAction: (request) => this.dispatchContextAction(request),
+            // This channel's resolved configuration (host defaults beneath agent/app config).
+            ChannelConfig: channelConfig ?? {},
             get Client() {
                 return service.client;
             },
-            SendVideoFrame: (base64Image, mimeType) => this.SendVideoFrame(base64Image, mimeType),
-            IsTrackEstablished: (modality, direction) => this.IsTrackEstablished(modality, direction)
+            // Through the arbiter, as this channel's source (deprecated: channels use a ChannelInboundVideoBridge).
+            SendVideoFrame: (base64Image, mimeType) => this.sendChannelVideoFrame(plugin, base64Image, mimeType),
+            IsTrackEstablished: (modality, direction) => this.IsTrackEstablished(modality, direction),
+            // The camera and screen share, for a channel that fronts one: their state, and the user's clicks on its surface.
+            Captures$: this.Captures$,
+            StartCapture: (kind) => (kind === 'camera' ? this.StartCamera() : this.StartScreenShare()),
+            StopCapture: (kind) => (kind === 'camera' ? this.StopCamera() : this.StopScreenShare()),
+            // The video sources and which of them the model is sent, so a capture's channel says the agent sees it only then.
+            VideoSources$: this.VideoSources$,
+            // The agent's video, the call's state and its resumes, for a channel that shows the agent.
+            AgentVideo$: this.AgentVideo$,
+            ConnectionState$: this.ConnectionState$,
+            Resuming$: this.Resuming$
         };
     }
     /**
-     * Replaces the set of host-registered surface client tools the realtime ContextTool can execute.
-     * The host calls this at session start and whenever the active surface's tool set changes (the
-     * continuous-capability half of client-context delivery). Passing `[]` clears them.
+     * Registers the tools ONE source of the host can run for the realtime `ContextTool`, replacing only
+     * that source's previous set — other owners' tools are untouched. A host with two sources (Explorer's
+     * always-available globals and the active surface's tools) registers each under its own owner key, so
+     * refreshing the surface's tools can neither drop the globals nor leave the previous surface's tools
+     * behind. Passing `[]` clears just that owner. When two owners register the same tool name, the
+     * later-registered owner wins.
      *
-     * @param tools The current surface client tools (name + handler). Descriptions/schemas ride the
-     *   app-context manifest separately; only the executable handler is needed here.
-     */
-    RegisterAppClientTools(tools) {
-        this.appClientToolHandlers.clear();
-        for (const tool of tools) {
-            if (tool?.Name && typeof tool.Handler === 'function') {
-                this.appClientToolHandlers.set(tool.Name.trim().toLowerCase(), tool.Handler);
-            }
-        }
+     * Calling it with one argument (the original form) registers under {@link DEFAULT_APP_TOOL_OWNER}, so
+     * a host with a single source behaves exactly as before.
+     *
+     * @param tools The owner's complete current set (name + handler; description/schema optional).
+     * @param owner A stable key naming the source (e.g. `'explorer.surface'`). Defaults to a shared owner.
+     */
+    RegisterAppClientTools(tools, owner = DEFAULT_APP_TOOL_OWNER) {
+        this.appToolRegistry.Register(owner, tools);
+    }
+    /** Removes one owner's tools (and its place in the collision order). No-op when it has none. */
+    UnregisterAppClientTools(owner) {
+        this.appToolRegistry.Unregister(owner);
+    }
+    /** Removes every owner's tools. */
+    ClearAppClientTools() {
+        this.appToolRegistry.Clear();
+    }
+    /**
+     * The client tools in effect right now, resolved through the same unified resolver the server uses
+     * (`override → session → app → static`, first match wins): the host's registered tools (described
+     * by the manifest the host streams when it did not describe them itself) first, then the app and
+     * agent tiers the server resolved at mint. Only the host-registered tools can RUN here; the
+     * other tiers describe what the app declares.
+     */
+    resolveAppClientTools() {
+        const manifest = this._appContext$.value?.Capabilities?.Tools ?? [];
+        return ResolveClientTools({
+            agentId: '',
+            sessionTools: MergeToolMetadata(this.appToolRegistry.ToMetadata(), manifest),
+            appTools: this.sessionClientTools?.App,
+            staticTools: this.sessionClientTools?.Static,
+        });
     }
     /**
      * Executes a host-registered surface client tool by name (the {@link RealtimeChannelContext.ExecuteClientTool}
      * implementation). Tolerant: an unknown tool or a thrown handler resolves to a structured
-     * `Success: false` result the channel narrates — never throws.
+     * `Success: false` result the channel narrates — never throws. A tool the app declares but the host has
+     * not registered a handler for says so, instead of reading like a typo. A handler that returns an object with
+     * `Success: false` also gives `Success: false`, with the handler's `ErrorMessage` and its object as `Result`.
      *
      * @param name The tool name (the model's `action`).
      * @param params The tool parameters.
      * @returns A structured result for the channel to serialize back to the model.
      */
     async executeAppClientTool(name, params) {
-        const handler = this.appClientToolHandlers.get((name ?? '').trim().toLowerCase());
+        const handler = this.appToolRegistry.Find(name)?.Handler;
         if (!handler) {
-            const available = Array.from(this.appClientToolHandlers.keys()).join(', ');
-            return {
-                Success: false,
-                ErrorMessage: `No client tool named "${name}" is available on this surface. Available: ${available || '(none)'}.`
-            };
+            return { Success: false, ErrorMessage: this.describeMissingClientTool(name) };
         }
         try {
             const result = await handler(params ?? {});
-            return { Success: true, Result: result };
+            return reportsFailure(result)
+                ? { Success: false, ErrorMessage: failureMessage(result), Result: result }
+                : { Success: true, Result: result };
         }
         catch (error) {
             return { Success: false, ErrorMessage: error instanceof Error ? error.message : String(error) };
         }
     }
+    /** The model-readable reason a client tool could not run. */
+    describeMissingClientTool(name) {
+        const available = this.appToolRegistry.Names().join(', ');
+        const wanted = (name ?? '').trim().toLowerCase();
+        const declared = this.resolveAppClientTools().find((t) => t.Name.trim().toLowerCase() === wanted);
+        if (declared) {
+            return `The client tool "${name}" is declared for this app but this surface has not registered it, so it cannot run right now. Available: ${available || '(none)'}.`;
+        }
+        return `No client tool named "${name}" is available on this surface. Available: ${available || '(none)'}.`;
+    }
     /**
      * Runs a channel-specific GraphQL operation through the live session's provider (the
      * {@link RealtimeChannelContext.ExecuteServerAction} implementation). Best-effort: any
@@ -1330,35 +2711,39 @@ export class RealtimeSessionRuntime {
      * never affected.
      */
     applyPriorChannelStates(statesJson) {
+        this.priorChannelStates = {};
         if (!statesJson) {
             return;
         }
-        let states;
         try {
             const parsed = JSON.parse(statesJson);
             if (parsed === null || typeof parsed !== 'object') {
                 return;
             }
-            states = parsed;
+            this.priorChannelStates = parsed;
         }
         catch {
             console.warn('[RealtimeSession] PriorChannelStatesJson was malformed — starting channels fresh');
             return;
         }
         for (const plugin of this._activeChannels$.value) {
-            const state = states[plugin.ChannelName];
-            if (typeof state === 'string' && state.length > 0) {
-                try {
-                    const restored = plugin.RestoreState(state);
-                    if (!restored) {
-                        console.warn(`[RealtimeSession] Channel '${plugin.ChannelName}' declined its prior-session state — starting fresh`);
-                    }
-                }
-                catch (error) {
-                    console.warn(`[RealtimeSession] Channel '${plugin.ChannelName}' restore threw — starting fresh`, error);
-                }
+            this.restorePriorChannelState(plugin);
+        }
+    }
+    /** Offers one plugin its prior-session state, if there is one. Rejections and throws are logged, never fatal. */
+    restorePriorChannelState(plugin) {
+        const state = this.priorChannelStates[plugin.ChannelName];
+        if (typeof state !== 'string' || state.length === 0) {
+            return;
+        }
+        try {
+            if (!plugin.RestoreState(state)) {
+                console.warn(`[RealtimeSession] Channel '${plugin.ChannelName}' declined its prior-session state — starting fresh`);
             }
         }
+        catch (error) {
+            console.warn(`[RealtimeSession] Channel '${plugin.ChannelName}' restore threw — starting fresh`, error);
+        }
     }
     /**
      * Persists a channel's state as a first-class versioned artifact (`MJ: Artifacts`) via the
@@ -1448,6 +2833,13 @@ export class RealtimeSessionRuntime {
             this._activeChannels$.next([]);
         }
         this.usedChannelNames.clear();
+        // Channels that were prepared or advertised but never mounted were never initialized, so there is
+        // nothing to dispose — only the bookkeeping to forget.
+        this.discardUnmountedChannels();
+        this.catalogNotePending = false;
+        this.resolvedChannels.clear();
+        this.priorChannelStates = {};
+        this.sessionClientTools = null;
     }
     // ── Realtime client resolution + wiring ────────────────────────────────────
     /**
@@ -1470,20 +2862,22 @@ export class RealtimeSessionRuntime {
     }
     /**
      * Builds the client-direct session config the realtime client connects with.
-     * Aggregates tracks sourced by active channels into `requestedTracks` so the driver
-     * can negotiate them (e.g., establishing inbound video streaming for Whiteboard / RemoteBrowser).
+     * Aggregates the tracks active channels source and sink under {@link REQUESTED_TRACKS_SESSION_KEY} so the
+     * driver can negotiate them (e.g., inbound video for Whiteboard / RemoteBrowser, outbound video for a
+     * channel that shows the agent's video). A track the model does not support resolves to `'unsupported'`.
+     * The session's transport and relay URL go to the driver as minted (an unknown transport is left out: direct).
      */
     BuildClientConfig(session) {
         const sessionConfig = this.parseSessionConfig(session.SessionConfigJson);
-        const channelTracks = this._activeChannels$.value.flatMap((c) => c.GetSourcedTracks());
+        const channelTracks = this._activeChannels$.value.flatMap((c) => [...c.GetSourcedTracks(), ...c.GetSunkTracks()]);
         if (channelTracks.length > 0) {
-            // `requestedTracks` crosses a JSON boundary — the driver reads it back out of the session
+            // The requested tracks cross a JSON boundary — the driver reads them back out of the session
             // config bag (`GeminiRealtimeClient.parseSessionConfig`). A `RealtimeTrackDescriptor` is NOT
             // structurally a `JSONValue`: it has no index signature and `UsageBasis` is readonly, so the
             // conversion is written out rather than asserted. Dedupe key and precedence are unchanged —
             // audio floor first, then anything the mint supplied, then the channels' own tracks.
-            const existing = Array.isArray(sessionConfig['requestedTracks'])
-                ? sessionConfig['requestedTracks']
+            const existing = Array.isArray(sessionConfig[REQUESTED_TRACKS_SESSION_KEY])
+                ? sessionConfig[REQUESTED_TRACKS_SESSION_KEY]
                 : [];
             const trackMap = new Map();
             for (const t of DEFAULT_REALTIME_AUDIO_TRACKS) {
@@ -1498,13 +2892,16 @@ export class RealtimeSessionRuntime {
             for (const t of channelTracks) {
                 trackMap.set(`${t.Direction}:${t.Modality}`, trackDescriptorToJSON(t));
             }
-            sessionConfig['requestedTracks'] = Array.from(trackMap.values());
+            sessionConfig[REQUESTED_TRACKS_SESSION_KEY] = Array.from(trackMap.values());
         }
+        const transport = ParseRealtimeClientTransport(session.Transport);
         return {
             Provider: session.Provider,
             Model: session.Model,
             EphemeralToken: session.EphemeralToken,
             ExpiresAt: session.ExpiresAt,
+            ...(transport ? { Transport: transport } : {}),
+            ...(session.RelayUrl ? { RelayUrl: session.RelayUrl } : {}),
             SessionConfig: sessionConfig
         };
     }
@@ -1540,6 +2937,9 @@ export class RealtimeSessionRuntime {
         });
         client.OnError((error) => {
             console.error('[RealtimeSession] Provider error event:', JSON.stringify(error), error);
+            if (error.Fatal && this.client === client) {
+                this.lastSessionError = error;
+            }
         });
         // Usage telemetry: accumulate the driver's per-response token DELTAS and relay them to
         // the server (onto the co-agent AIPromptRun) debounced + once at teardown. Providers
@@ -1556,12 +2956,36 @@ export class RealtimeSessionRuntime {
         client.OnInterruption(() => {
             this.cancelPendingNarration();
         });
+        client.OnRemoteVideo((video) => this.onAgentVideo(client, video));
+    }
+    /**
+     * The model's video arrived: publish it on {@link AgentVideo$}, and mark each channel that shows it (one that sinks
+     * outbound video) as used, so the host shows its surface. A client the session has already let go of is ignored, so a
+     * late frame cannot bring the video back after the call.
+     */
+    onAgentVideo(client, video) {
+        if (this.client !== client) {
+            return;
+        }
+        this._agentVideo$.next(video);
+        for (const channel of this._activeChannels$.value) {
+            if (channel.ShowsAgentVideo) {
+                this.noteChannelActivity(channel);
+            }
+        }
+    }
+    /** Clears {@link AgentVideo$} when the call's client goes. */
+    clearAgentVideo() {
+        if (this._agentVideo$.value !== null) {
+            this._agentVideo$.next(null);
+        }
     }
     /** Maps a client state event onto the UI connection state. */
     onClientStateChange(state) {
         const mapped = this.mapClientState(state);
         if (mapped) {
-            this._connectionState$.next(mapped);
+            this.setConnectionState(mapped);
+            this.flushChannelCatalogNote();
         }
     }
     /**
@@ -1590,6 +3014,17 @@ export class RealtimeSessionRuntime {
         const state = this._connectionState$.value;
         return state === 'listening' || state === 'speaking' || state === 'thinking';
     }
+    /**
+     * Moves {@link ConnectionState$} to `state`, and {@link Resuming$} first: a `'connecting'` while the call is live, or
+     * already resuming, is a resume; any other state ends one. Every state change goes through here.
+     */
+    setConnectionState(state) {
+        const resuming = state === 'connecting' && (this._resuming$.value || this.isSessionLive());
+        if (resuming !== this._resuming$.value) {
+            this._resuming$.next(resuming);
+        }
+        this._connectionState$.next(state);
+    }
     // ── Transcript policy ──────────────────────────────────────────────────────
     /**
      * Applies transcript policy to client transcript events. Interim deltas don't become
@@ -1779,7 +3214,7 @@ export class RealtimeSessionRuntime {
             void this.relayToolTurn(call.ToolName, call.ArgumentsJson, resultJson);
             return;
         }
-        this._connectionState$.next('thinking');
+        this.setConnectionState('thinking');
         if (this.inFlightCallIds.size === 0) {
             // A fresh delegation burst: anchor the first-update delay and clear the digest
             // buffer. Deliberately NOT reset: lastDelegationNarrationAt (the 8s spacing floor
@@ -1876,6 +3311,40 @@ export class RealtimeSessionRuntime {
             RunID: parsed.RunID,
             Artifacts: parsed.Artifacts
         });
+        if (parsed.Success && parsed.Artifacts && parsed.Artifacts.length > 0) {
+            void this.offerDelegationArtifacts(parsed.Artifacts);
+        }
+    }
+    /**
+     * Offers a delegated run's artifacts to the channels that host artifacts (an Interactive Component channel
+     * shows a component artifact, or swaps in a newer version of one it already shows). Each channel is asked
+     * first whether it wants them; an advertised, unopened channel that does is mounted before it is handed
+     * them. One channel failing never stops the others, and nothing here can fail the delegation result,
+     * which has already been emitted.
+     */
+    async offerDelegationArtifacts(artifacts) {
+        const candidates = [
+            ...this._activeChannels$.value.map((plugin) => ({ Plugin: plugin, IsOpen: true })),
+            ...this.advertisedChannels.map((prepared) => ({ Plugin: prepared.Plugin, IsOpen: false }))
+        ];
+        for (const { Plugin: plugin, IsOpen: isOpen } of candidates) {
+            try {
+                const config = this.GetResolvedChannel(plugin.ChannelName)?.Config ?? {};
+                if (!plugin.AcceptsDelegationArtifacts(artifacts, config)) {
+                    continue;
+                }
+                if (!isOpen) {
+                    await this.mountAdvertisedChannel(plugin);
+                }
+                await plugin.OnDelegationArtifacts(artifacts);
+                if (!isOpen) {
+                    this.noteChannelActivity(plugin); // the channel was mounted for this: reveal its tab
+                }
+            }
+            catch (error) {
+                console.error(`[RealtimeSession] Channel '${plugin.ChannelName}' failed to take a delegated run's artifacts:`, error);
+            }
+        }
     }
     // ── Explicit delegation cancellation (server cancel channel) ───────────────
     /**
@@ -1966,44 +3435,34 @@ export class RealtimeSessionRuntime {
         }
     }
     // ── Session minting (GraphQL) ──────────────────────────────────────────────
-    /** Calls the `StartRealtimeClientSession` mutation to obtain an ephemeral token + config. */
-    async mintSession(targetAgentId, conversationId, lastSessionId, preferredModelId, clientTools, coAgentId, configOverridesJson, recordingConsent, recordingStartedAt, mediaCollectionId, applicationId, appContext) {
-        const mutation = `
-      mutation StartRealtimeClientSession($targetAgentId: String!, $conversationId: String, $lastSessionId: String, $preferredModelId: String, $clientToolsJson: String, $coAgentId: String, $configOverridesJson: String, $recordingConsent: Boolean, $recordingStartedAt: String, $mediaCollectionId: String, $applicationId: String, $appContextJson: String) {
-        StartRealtimeClientSession(targetAgentId: $targetAgentId, conversationId: $conversationId, lastSessionId: $lastSessionId, preferredModelId: $preferredModelId, clientToolsJson: $clientToolsJson, coAgentId: $coAgentId, configOverridesJson: $configOverridesJson, recordingConsent: $recordingConsent, recordingStartedAt: $recordingStartedAt, mediaCollectionId: $mediaCollectionId, applicationId: $applicationId, appContextJson: $appContextJson) {
-          AgentSessionId
-          ConversationId
-          Provider
-          Model
-          EphemeralToken
-          ExpiresAt
-          SessionConfigJson
-          ModelName
-          NarrationInstructionsTemplate
-          PriorChannelStatesJson
-        }
-      }
-    `;
-        const variables = {
-            targetAgentId,
-            conversationId: conversationId ?? null,
-            lastSessionId: lastSessionId ?? null,
-            preferredModelId: preferredModelId ?? null,
-            clientToolsJson: clientTools && clientTools.length > 0 ? JSON.stringify(clientTools) : null,
-            coAgentId: coAgentId ?? null,
-            configOverridesJson: configOverridesJson ?? null,
-            recordingConsent: recordingConsent ?? false,
-            recordingStartedAt: recordingStartedAt ?? null,
-            mediaCollectionId: mediaCollectionId ?? null,
-            applicationId: applicationId ?? null,
-            appContextJson: appContext ? JSON.stringify(appContext) : null
-        };
-        const result = await this.gql().ExecuteGQL(mutation, variables);
-        const payload = result?.StartRealtimeClientSession;
-        if (!payload?.EphemeralToken) {
-            throw new Error('StartRealtimeClientSession returned no ephemeral token');
-        }
-        return payload;
+    /**
+     * Mints a session through the installed {@link Launcher} — by default the stock
+     * `StartRealtimeClientSession` mutation (see {@link DefaultRealtimeSessionLauncher}). `showsAgentVideo` is whether
+     * one of the session's channels could show the agent's video; without one the server asks the model for no avatar.
+     * `conversationBranchId` is the fork the session starts on; `null` is Main.
+     */
+    async mintSession(targetAgentId, conversationId, lastSessionId, preferredModelId, clientTools, coAgentId, configOverridesJson, recordingConsent, recordingStartedAt, mediaCollectionId, applicationId, appContext, channelCandidatesJson, showsAgentVideo, conversationBranchId) {
+        const result = await this._launcher.Launch({
+            TargetAgentId: targetAgentId,
+            ConversationId: conversationId ?? null,
+            LastSessionId: lastSessionId ?? null,
+            PreferredModelId: preferredModelId ?? null,
+            ClientTools: clientTools ?? [],
+            CoAgentId: coAgentId ?? null,
+            ConfigOverridesJson: configOverridesJson ?? null,
+            RecordingConsent: recordingConsent ?? false,
+            RecordingStartedAt: recordingStartedAt ?? null,
+            MediaCollectionId: mediaCollectionId ?? null,
+            ApplicationId: applicationId ?? null,
+            AppContext: appContext ?? null,
+            ChannelCandidatesJson: channelCandidatesJson ?? null,
+            ConversationBranchId: conversationBranchId ?? null,
+            ...(showsAgentVideo === undefined ? {} : { ShowsAgentVideo: showsAgentVideo })
+        }, { Provider: this.Provider });
+        if (!HasClientCredential(result)) {
+            throw new Error('The session launcher returned no ephemeral token (or, for a relay session, no relay URL)');
+        }
+        return result;
     }
     /** Calls the `ExecuteRealtimeSessionTool` mutation; returns the ResultJson string. */
     async executeSessionTool(callId, toolName, argsJson) {
@@ -2142,16 +3601,28 @@ export class RealtimeSessionRuntime {
     /**
      * Accumulates one usage DELTA from the realtime client (per-response token counts —
      * the `OnUsage` contract shape) and schedules the debounced relay. Negative / non-finite
-     * values are clamped to 0; an all-zero delta is dropped without arming the timer.
+     * values are clamped to 0; an all-zero delta is dropped without arming the timer. The
+     * update's input and output detail blocks add into the pending details by the record's
+     * rules (amounts add up, inbound video running totals keep the larger value), so an update
+     * that carries only avatar video seconds still counts.
      */
     onUsageDelta(usage) {
         const input = this.clampUsageDelta(usage.InputTokens);
         const output = this.clampUsageDelta(usage.OutputTokens);
-        if (input === 0 && output === 0) {
+        const details = AddRealtimeUsageRecord(null, { Input: usage.InputTokenDetails, Output: usage.OutputTokenDetails });
+        const hasDetails = HasRealtimeUsage(details);
+        if (input === 0 && output === 0 && !hasDetails) {
             return;
         }
         this.pendingUsageInput += input;
         this.pendingUsageOutput += output;
+        if (hasDetails) {
+            this.pendingUsageDetails = AddRealtimeUsageRecord(this.pendingUsageDetails, details);
+        }
+        this.armUsageFlush();
+    }
+    /** Schedules the debounced usage relay unless one is already pending. */
+    armUsageFlush() {
         if (!this.usageFlushTimer) {
             this.usageFlushTimer = setTimeout(() => {
                 this.usageFlushTimer = null;
@@ -2176,24 +3647,26 @@ export class RealtimeSessionRuntime {
         const sessionId = agentSessionId ?? this.agentSessionId;
         const input = this.pendingUsageInput;
         const output = this.pendingUsageOutput;
-        if (!sessionId || (input === 0 && output === 0)) {
+        const details = this.pendingUsageDetails;
+        if (!sessionId || (input === 0 && output === 0 && !details)) {
             return;
         }
         this.pendingUsageInput = 0;
         this.pendingUsageOutput = 0;
+        this.pendingUsageDetails = null;
         try {
-            const mutation = `
-        mutation RelayRealtimeUsage($agentSessionId: String!, $inputTokens: Int!, $outputTokens: Int!) {
-          RelayRealtimeUsage(agentSessionId: $agentSessionId, inputTokens: $inputTokens, outputTokens: $outputTokens)
-        }
-      `;
-            await this.gql().ExecuteGQL(mutation, { agentSessionId: sessionId, inputTokens: input, outputTokens: output });
+            // The details argument is sent only when there are details, so a token-only relay is unchanged.
+            const variables = { agentSessionId: sessionId, inputTokens: input, outputTokens: output, ...(details ? { usageDetailsJson: JSON.stringify(details) } : {}) };
+            await this.gql().ExecuteGQL(RELAY_REALTIME_USAGE_MUTATION, variables);
         }
         catch (error) {
             console.error('[RealtimeSession] Failed to relay usage telemetry:', error);
             // Re-accumulate so a later debounce / the teardown flush retries the same deltas.
             this.pendingUsageInput += input;
             this.pendingUsageOutput += output;
+            if (details) {
+                this.pendingUsageDetails = AddRealtimeUsageRecord(this.pendingUsageDetails, details);
+            }
         }
     }
     /** Cancels the pending debounced usage flush and zeroes the accumulators (teardown tail). */
@@ -2204,6 +3677,7 @@ export class RealtimeSessionRuntime {
         }
         this.pendingUsageInput = 0;
         this.pendingUsageOutput = 0;
+        this.pendingUsageDetails = null;
     }
     // ── Delegated-run progress streaming ───────────────────────────────────────
     /**
@@ -2483,42 +3957,66 @@ export class RealtimeSessionRuntime {
             return;
         }
         this.teardownInFlight = this.runTeardown(closeServerSession).finally(() => {
+            if (this._savingRecording$.value) {
+                this._savingRecording$.next(false);
+            }
             this.teardownInFlight = null;
         });
         await this.teardownInFlight;
     }
     /** The body of {@link teardown}; never called concurrently with itself. */
     async runTeardown(closeServerSession) {
+        // Arm BEFORE any await so a tab closed in the first milliseconds of teardown is still guarded.
+        if (this.recorder) {
+            this._savingRecording$.next(true);
+        }
         // First: stop asserting liveness. A pulse racing the close would re-stamp LastActiveAt on a
         // session we are deliberately ending, leaving an Idle row the janitor then has to age out.
         this.stopLivenessPulse();
         this.teardownDelegationProgress();
+        this.stopSessionEvents();
+        this.clientDeadline.Clear();
         // Channels first: flush any unsaved channel state WHILE the live session id is still
         // set (the captured per-save id covers the race anyway), then dispose the plugins.
         this.flushAllChannelSaves();
         this.disposeChannels();
+        // The camera and screen share go first: the camera runs on the controller closed next.
+        this.closeCaptures();
         // Defensive: stop the mic even when Connect never ran (the client also stops the
         // tracks it was handed — track.stop() is idempotent).
+        this.closeLocalMedia();
         this.localStream?.getTracks().forEach(t => t.stop());
         this.localStream = null;
-        // Hand the platform back whatever acquiring the microphone changed. Stopping the tracks is not
+        this.microphoneMuted = false;
+        // Hand the platform back whatever opening the microphone changed. Stopping the tracks is not
         // the same thing: iOS, for instance, is put into a record-and-play audio category for the call,
         // and leaving it there changes the route and volume behaviour of every sound the app makes
-        // afterwards. Best-effort by contract — a failure here must never block ending a call.
-        try {
-            await this.mediaHost.ReleaseMicrophone?.();
-        }
-        catch (error) {
-            console.error('[RealtimeSession] Media host failed to release the microphone:', error);
+        // afterwards. A microphone still opening is left to its start, which releases it once the
+        // opening returns ({@link microphoneLease}).
+        const lease = this.microphoneLease;
+        if (lease && !lease.Opening) {
+            this.microphoneLease = null;
+            await this.releaseMicrophone();
         }
         if (this.client) {
-            await this.client.Disconnect();
-            this.client = null;
+            // A stranded Active session is worse than a noisy socket: a driver that throws on Disconnect
+            // (socket already gone) must not stop the server session from being closed below.
+            try {
+                await this.client.Disconnect();
+            }
+            catch (error) {
+                console.error(`[RealtimeSession] Driver failed to disconnect (session ${this.agentSessionId}); continuing teardown:`, error);
+            }
+            finally {
+                this.unwatchVideoSources();
+                this.clearAgentVideo();
+                this.client = null;
+            }
         }
-        // Stop + upload the call recording WHILE the live session id is still set (the file is
-        // attached to it). Best-effort and never blocks teardown — stopAndUploadRecording swallows
-        // its own errors. No-op when nothing was recorded.
-        await this.stopAndUploadRecording(this.agentSessionId);
+        // Stop + encode the call recording now (the recorder must be detached before the session id is
+        // cleared); the upload itself happens after the close below. Best-effort — stopRecording
+        // swallows its own errors. Null when nothing was recorded.
+        const recording = await this.stopRecording();
         this.recordingStartedAtIso = null;
         // Final usage flush WHILE the live session id is still set (the relay mutation also
         // accepts a Closed session, so ordering vs. CloseAgentSession is belt-and-braces).
@@ -2531,18 +4029,27 @@ export class RealtimeSessionRuntime {
         if (closeServerSession && this.agentSessionId) {
             await this.closeServerSession(this.agentSessionId);
         }
+        // Upload AFTER the close. The WAV is tens of MB and takes seconds; a page unload aborts the
+        // request, and nothing after an aborted await ever runs — so the small, critical close goes
+        // first (#5195). The server accepts the upload on a Closed session (loadOwnedSession does not
+        // check status), and uploadStoppedRecording never throws.
+        await this.uploadStoppedRecording(this.agentSessionId, recording);
         // Capture the session id BEFORE we null it so the lifecycle emit carries it.
         // Skip emitting when there was no live session (defensive — teardown is safe
         // to call without an active session).
         const closedSessionId = this.agentSessionId;
         this.agentSessionId = null;
+        this.sessionConversationId = null;
         this.narrationTemplate = null;
         this.clientToolHandlers.clear();
         this._modelName$.next(null);
+        if (this._avatarNotice$.value !== null) {
+            this._avatarNotice$.next(null);
+        }
         this.SetMinimized(false);
         this._active$.next(false);
         if (this._connectionState$.value !== 'error') {
-            this._connectionState$.next('closed');
+            this.setConnectionState('closed');
         }
         // Surface generic session-ended for the conversations runtime bridge.
         // `closeServerSession=true` means the user explicitly called EndRealtimeSession;
@@ -2554,6 +4061,18 @@ export class RealtimeSessionRuntime {
             });
         }
     }
+    /**
+     * Calls the host's {@link IRealtimeMediaHost.ReleaseMicrophone}. Best-effort by contract: a failure
+     * is logged and never thrown, because it must never block ending a call.
+     */
+    async releaseMicrophone() {
+        try {
+            await this.mediaHost.ReleaseMicrophone?.();
+        }
+        catch (error) {
+            console.error('[RealtimeSession] Media host failed to release the microphone:', error);
+        }
+    }
     /** Calls the `CloseAgentSession` mutation (provisioned in P4b). */
     async closeServerSession(agentSessionId) {
         try {
@@ -2580,12 +4099,13 @@ export class RealtimeSessionRuntime {
         this.hasActiveInterimUserCaption = false;
         this.SetMinimized(false);
         this.stopSegmentFlushing();
-        this.segmentIndex = 0;
+        this.shardQueue = null;
         this.recorder = null;
         this.recordingStartedAtIso = null;
         this.currentTurnStartMs = null;
         this.turnAudioStartCaptured = false;
         this.usedChannelNames.clear();
+        this.microphoneMuted = false;
     }
     /** The GraphQL provider used for relay mutations. */
     gql() {