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

package/dist/session/RealtimeSessionRuntime.d.ts

@@ -1,11 +1,20 @@
 import { Observable } from 'rxjs';
 import { IMetadataProvider } from '@memberjunction/core';
-import { ClientRealtimeSessionConfig, RealtimeToolDefinition, RealtimeTrackDirection } from '@memberjunction/ai';
-import { AppContextSnapshot } from '@memberjunction/ai-core-plus';
-import { BaseRealtimeClient, RealtimeAudioActivity } from '@memberjunction/ai-realtime-client';
+import { ClientRealtimeSessionConfig, JSONObject, RealtimeToolDefinition, RealtimeTrackDirection } from '@memberjunction/ai';
+import { AppContextSnapshot, type IdentityVerifiedEventPayload, type RealtimeChannelExposure, type ResolvedRealtimeChannel } from '@memberjunction/ai-core-plus';
+import { BaseRealtimeClient, RealtimeAudioActivity, RealtimeClientError, type DisplayCaptureOptions, type MediaVideoSource, type VideoSourceState } from '@memberjunction/ai-realtime-client';
+import { type IRealtimeSessionLauncher } from './session-launcher.js';
+import { type RealtimeAvatarNotice } from './avatar-notice.js';
+import { type RealtimeCaptureOffers, type RealtimeCaptureState, type RealtimeCaptureStates } from './realtime-captures.js';
+import { type RealtimeMicrophoneState } from './realtime-microphone.js';
+import { type IRealtimeSessionEventSource, type RealtimeSessionStreamEvent } from './session-event-hub.js';
 import { ParsedDelegationArtifact } from './delegation-result-parser.js';
 import { BaseRealtimeChannelClient } from '../channels/base-realtime-channel-client.js';
 import { IRealtimeMediaHost } from '../hosts/IRealtimeMediaHost.js';
+import type { RealtimeContextActionResult } from '../channels/channel-contract-types.js';
+import { type AppClientToolRegistration } from './app-client-tool-registry.js';
+import { type IChannelExposurePreferences } from './channel-exposure-preferences.js';
+import { type RealtimeSessionStartOptions } from './channel-session-scope.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
@@ -130,6 +139,7 @@ export interface StartRealtimeClientSessionResult {
     ConversationId: string | null;
     Provider: string;
     Model: string;
+    /** The provider credential the client driver presents. Empty on a relay session, which has {@link RelayUrl} instead. */
     EphemeralToken: string;
     ExpiresAt: string;
     /** JSON.stringify of the provider session config (instructions + tools) to apply at connect. */
@@ -150,6 +160,31 @@ export interface StartRealtimeClientSessionResult {
      * last session left off.
      */
     PriorChannelStatesJson: string | null;
+    /**
+     * OPTIONAL — the server's resolved `RealtimeSessionClientPolicy` (from `@memberjunction/ai-core-plus`) as JSON: which of the channel
+     * candidates the client reported at mint are in this session (agent/app scoping and the registry's
+     * kill switch already applied), their resolved display and config, and the app/static client-tool
+     * tiers. Absent from a server that predates channel scoping and from a host that mints through its
+     * own proxy; the runtime then resolves the scope locally from code defaults and host declarations.
+     */
+    ClientPolicyJson?: string | null;
+    /**
+     * OPTIONAL — the session's live-avatar status (`RealtimeAvatarStatus` from `@memberjunction/ai`) as JSON: whether the
+     * voiced agent asked for an avatar, whether the model renders it, and why not. The runtime reads it after connecting
+     * to publish {@link RealtimeSessionRuntime.AvatarNotice$}. Absent from a server that predates it, when the agent asked
+     * for no avatar, and from a host that mints for itself and does not pass it on; the call then shows no notice.
+     */
+    AvatarStatusJson?: string | null;
+    /**
+     * OPTIONAL — how the browser reaches the provider: `'direct'` or `'relay'` (`RealtimeClientTransport` from
+     * `@memberjunction/ai`). Absent, null or unknown means direct: a direct session, or a server that predates it.
+     */
+    Transport?: string | null;
+    /**
+     * OPTIONAL — where a relay session's client driver connects (MJAPI's realtime relay). It carries the session's ticket,
+     * so it is a credential: never log it. A host that mints for itself must pass it on for a relay session.
+     */
+    RelayUrl?: string | null;
 }
 /**
  * Host-supplied inputs that accompany an already-minted session on
@@ -221,6 +256,7 @@ export declare class RealtimeSessionRuntime {
      */
     constructor(mediaHost: IRealtimeMediaHost);
     private _connectionState$;
+    private readonly _resuming$;
     private _captions$;
     private _active$;
     private _delegationProgress$;
@@ -230,6 +266,7 @@ export declare class RealtimeSessionRuntime {
     private _agentName$;
     private _modelName$;
     private _minimized$;
+    private _savingRecording$;
     private _activeChannels$;
     private _channelFocus$;
     private _sessionStarted$;
@@ -237,6 +274,16 @@ export declare class RealtimeSessionRuntime {
     private _channelActivity$;
     /** Current connection / turn state. */
     readonly ConnectionState$: Observable<RealtimeConnectionState>;
+    /**
+     * 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`.
+     */
+    readonly Resuming$: Observable<boolean>;
     /** Live captions for both sides of the conversation. */
     readonly Captions$: Observable<RealtimeCaption[]>;
     /** True while a session is open (mic button active, overlay shown). */
@@ -273,6 +320,16 @@ export declare class RealtimeSessionRuntime {
      * pure presentation state, reset to `false` at session start and teardown.
      */
     readonly Minimized$: Observable<boolean>;
+    /**
+     * 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.).
+     */
+    readonly SavingRecording$: Observable<boolean>;
+    /** Synchronous read of {@link SavingRecording$}. */
+    get IsSavingRecording(): boolean;
     /**
      * 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
@@ -280,6 +337,59 @@ export declare class RealtimeSessionRuntime {
      * one surface tab per plugin — it never knows any concrete channel type.
      */
     readonly ActiveChannels$: Observable<BaseRealtimeChannelClient[]>;
+    private readonly _videoSources$;
+    /**
+     * 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}.
+     */
+    readonly VideoSources$: Observable<readonly VideoSourceState[]>;
+    private readonly _captures$;
+    /**
+     * 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$}.
+     */
+    readonly Captures$: Observable<RealtimeCaptureStates>;
+    private readonly _captureOffers$;
+    /**
+     * 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.
+     */
+    readonly CaptureOffers$: Observable<RealtimeCaptureOffers>;
+    private readonly _microphone$;
+    /**
+     * 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`).
+     */
+    readonly Microphone$: Observable<RealtimeMicrophoneState>;
+    private readonly _agentVideo$;
+    /**
+     * 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.
+     */
+    readonly AgentVideo$: Observable<MediaVideoSource | null>;
+    private readonly _avatarNotice$;
+    /**
+     * 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".
+     */
+    readonly AvatarNotice$: Observable<RealtimeAvatarNotice | null>;
+    /** Synchronous access to {@link AvatarNotice$}'s current value. */
+    get CurrentAvatarNotice(): RealtimeAvatarNotice | null;
     /**
      * Channel requests to enter / leave the FOCUS layout (see
      * {@link RealtimeChannelFocusEvent}). Fired when a plugin calls its host context's
@@ -341,7 +451,11 @@ export declare class RealtimeSessionRuntime {
      */
     /** Conversation id the SERVER created for this session (null when the host supplied one). */
     private createdConversationId;
-    /** 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.
+     */
     private sessionConversationId;
     /** First final user utterance of the live session (the naming seed). */
     private firstUserTranscript;
@@ -367,8 +481,28 @@ export declare class RealtimeSessionRuntime {
     SetMinimized(minimized: boolean): void;
     /** The provider-direct realtime client driving the live session (ClassFactory-resolved). */
     private client;
-    /** 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.
+     */
     private localStream;
+    /**
+     * 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.
+     */
+    private microphoneMuted;
+    /** The host's camera-and-microphone controller for this session, when the host offers one. */
+    private localMedia;
+    /** Follows the controller's microphone, so a swapped-in track or a reopened microphone reaches the driver and the recorder. */
+    private localMediaSubscription;
+    /**
+     * 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.
+     */
+    private microphoneOffered;
+    /** The live session's camera and screen share; created once the client is connected. */
+    private captures;
+    private capturesSubscription;
     private agentSessionId;
     /**
      * The application the active session runs in (sources the server-side app config cascade +
@@ -410,8 +544,15 @@ export declare class RealtimeSessionRuntime {
     private recordingStartedAtIso;
     /** Interval that flushes ~15s crash-recovery shards to the server during a recording. */
     private segmentTimer;
-    /** 0-based index of the next recording shard to upload. */
-    private segmentIndex;
+    /**
+     * 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.
+     */
+    private shardQueue;
     /** How often crash-recovery shards are flushed during a recording. */
     private static readonly segmentFlushMs;
     /**
@@ -486,6 +627,11 @@ export declare class RealtimeSessionRuntime {
     private pendingUsageInput;
     /** Accumulated output-token delta since the last flush. */
     private pendingUsageOutput;
+    /**
+     * 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.
+     */
+    private pendingUsageDetails;
     /** Pending debounced usage flush; also force-flushed at teardown. */
     private usageFlushTimer;
     /** Active push-status subscription that feeds delegation progress; cleared on teardown. */
@@ -528,7 +674,20 @@ export declare class RealtimeSessionRuntime {
      */
     private teardownInFlight;
     /**
-     * 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.
+     */
+    private microphoneLease;
+    /**
+     * 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:
@@ -537,6 +696,11 @@ export declare class RealtimeSessionRuntime {
      * runtime's own try/catch, so the host never sees that rejection itself.
      */
     private lastStartError;
+    /**
+     * The fatal error the call's client reported, or `null` when it has reported none. Each start clears it
+     * ({@link beginSessionStart}). See {@link LastSessionError}.
+     */
+    private lastSessionError;
     /** Debounce window for persisting a channel's state of record after a change burst. */
     private static readonly channelSaveDebounceMs;
     /**
@@ -561,8 +725,82 @@ export declare class RealtimeSessionRuntime {
      */
     get Provider(): IMetadataProvider;
     set Provider(value: IMetadataProvider | null);
+    private _launcher;
+    /**
+     * 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(): IRealtimeSessionLauncher;
+    set Launcher(value: IRealtimeSessionLauncher | null);
+    /**
+     * 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.
+     */
+    ChannelClassLoader: ((clientPluginClasses: readonly string[]) => Promise<void>) | null;
+    private readonly _sessionEvents$;
+    /**
+     * 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}).
+     */
+    readonly SessionEvents$: Observable<RealtimeSessionStreamEvent>;
+    /** Keeps the live session's event stream open; null between sessions. */
+    private sessionEventHub;
+    /** Per-type handlers the runtime runs (before publishing on {@link SessionEvents$}) for events it understands. */
+    private readonly sessionEventHandlers;
+    /**
+     * 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.
+     */
+    IdentityVerifiedSpokenResponse: string | ((payload: IdentityVerifiedEventPayload) => string | null) | null;
+    private readonly clientDeadline;
+    /**
+     * 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$(): Observable<Date | null>;
+    /** Synchronous access to {@link SessionDeadline$}. */
+    get SessionDeadline(): Date | null;
+    /** Sets the baseline deadline a host knows at session start (`null` clears). See {@link SessionDeadline$}. */
+    SetSessionDeadline(deadline: Date | null): void;
+    /**
+     * 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.
+     */
+    protected createSessionEventSource(): IRealtimeSessionEventSource | null;
+    /** Opens the live session's event stream. Best-effort: never disturbs the call. */
+    private startSessionEvents;
+    private stopSessionEvents;
+    /** Routes one event to its per-type handler, then publishes it. An event for another session is dropped. */
+    private routeSessionEvent;
+    /**
+     * `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.
+     */
+    private handleIdentityVerified;
     /** True when a session is currently open. */
     get IsActive(): boolean;
+    /**
+     * True when a session is open or starting for `conversationId`. Ids are compared without
+     * regard to case.
+     */
+    IsActiveFor(conversationId: string | null | undefined): boolean;
     /**
      * Start a client-direct voice session fronting `targetAgentId`.
      *
@@ -600,8 +838,15 @@ export declare 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).
      */
-    StartRealtimeSession(targetAgentId: string, conversationId?: string | null, lastSessionId?: string | null, agentName?: string | null, preferredModelId?: string | null, clientTools?: RealtimeToolDefinition[] | null, coAgentId?: string | null, configOverridesJson?: string | null, recordingConsent?: boolean | null, mediaCollectionId?: string | null, applicationId?: string | null, appContext?: AppContextSnapshot | null): Promise<void>;
+    StartRealtimeSession(targetAgentId: string, conversationId?: string | null, lastSessionId?: string | null, agentName?: string | null, preferredModelId?: string | null, clientTools?: RealtimeToolDefinition[] | null, coAgentId?: string | null, configOverridesJson?: string | null, recordingConsent?: boolean | null, mediaCollectionId?: string | null, applicationId?: string | null, appContext?: AppContextSnapshot | null, options?: RealtimeSessionStartOptions | null): Promise<void>;
     /**
      * Declares which provider keys this host can actually carry audio for.
      *
@@ -641,42 +886,173 @@ export declare 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.
      */
     StartRealtimeSessionFromResult(result: StartRealtimeClientSessionResult, options?: RealtimeSessionRunOptions): Promise<void>;
     /**
-     * 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.
      */
     private beginSessionStart;
     /**
      * 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}).
      */
     private runMintedSession;
+    /**
+     * 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.
+     */
+    private publishAvatarNotice;
     /**
      * 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.
      */
     private unwindAbandonedStart;
     /**
-     * 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.
+     */
+    private openMicrophone;
+    /**
+     * 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.
+     */
+    private connectClient;
+    /**
+     * 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.
+     */
+    private followMicrophone;
+    /** The client is connected: the call offers its microphone on {@link Microphone$}, and {@link SwitchMicrophone} moves it. */
+    private offerMicrophone;
+    /** Publishes the call's microphone from the controller's state while the call offers it, when it names a change. */
+    private publishMicrophone;
+    /** Stops following the controller and disposes it, which releases its devices; the call no longer offers a microphone. */
+    private closeLocalMedia;
+    /**
+     * 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}.
+     */
+    private openCaptures;
+    /**
+     * The host's frame sampler for the captures ({@link IRealtimeMediaHost.CreateFrameSampler}), or `undefined` when it offers
+     * none and the captures use the DOM default.
+     */
+    private hostFrameSampler;
+    /** Stops the camera and screen share, if any, and reports both off. */
+    private closeCaptures;
+    /** Works out which captures the call offers ({@link CaptureOffers$}) and publishes a change. */
+    private refreshCaptureOffers;
+    /** Whether the host can open a capture and the call's policy admits it. */
+    private canOffer;
+    /** What a capture reports when there is no live session to show it to. */
+    private noSessionCapture;
+    /**
+     * 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.
+     */
+    private admitCapture;
+    /** The channel in the session, open or advertised, that fronts a capture. */
+    private findCaptureChannel;
+    /**
+     * 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.
+     */
+    private revealCaptureChannel;
+    /**
+     * 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.
+     */
+    StartCamera(deviceId?: string): Promise<RealtimeCaptureState>;
+    /** Stops the user's camera. Safe to call when it is off. */
+    StopCamera(): void;
+    /**
+     * 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.
+     */
+    SwitchCamera(deviceId: string): Promise<RealtimeCaptureState>;
+    /**
+     * 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.
+     */
+    SwitchMicrophone(deviceId: string): Promise<RealtimeMicrophoneState>;
+    /**
+     * 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(): RealtimeCaptureState;
+    /**
+     * 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)".
+     */
+    StartScreenShare(options?: DisplayCaptureOptions): Promise<RealtimeCaptureState>;
+    /** Stops the user's screen share. Safe to call when nothing is shared. */
+    StopScreenShare(): void;
+    /**
+     * 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(): Error | null;
+    /**
+     * 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(): RealtimeClientError | null;
     /**
      * 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.
@@ -701,7 +1077,11 @@ export declare class RealtimeSessionRuntime {
      * No-op when no session is open / the control channel isn't ready, or when the text is empty.
      */
     SendText(text: string): void;
-    /** 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(): boolean;
     /**
      * Registers a handler for CLIENT-EXECUTED UI tools whose names start with `toolNamePrefix`
@@ -748,9 +1128,17 @@ export declare class RealtimeSessionRuntime {
      */
     get Client(): BaseRealtimeClient | null;
     /**
-     * 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: string, mimeType?: string): void;
+    SendVideoFrame(base64Image: string, mimeType?: string): boolean;
     /**
      * Checks whether a media track is established on the active realtime client.
      */
@@ -803,50 +1191,212 @@ export declare class RealtimeSessionRuntime {
     private pulseLiveness;
     /**
      * 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).
      */
     private flushRecordingSegment;
     /**
-     * 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.
+     */
+    private uploadRecordingShard;
+    /**
+     * 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.
+     */
+    private stopRecording;
+    /**
+     * 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.
      */
-    private stopAndUploadRecording;
+    private uploadStoppedRecording;
     /**
-     * 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.
      */
     private uploadRecording;
+    /** Whether the channel catalog note still has to be sent (see {@link flushChannelCatalogNote}). */
+    private catalogNotePending;
+    /** Plugins resolved for the current start but not yet initialized. Consumed by {@link activateChannels}. */
+    private preparedChannels;
+    /** The scope the browser resolves on its own — the fallback when no server policy comes back. */
+    private localChannelScope;
+    /** `on-demand` channels that are in the session but not opened yet (initialized only when opened). */
+    private advertisedChannels;
+    /** What the policy resolved for each in-session channel, keyed by normalized channel key. */
+    private readonly resolvedChannels;
+    /** The prior session's saved channel states, kept so an `on-demand` channel opened later is restored too. */
+    private priorChannelStates;
+    /** The app/static client-tool tiers the server resolved for this session. */
+    private sessionClientTools;
+    /** Validates and routes channel-addressed `ContextTool` calls. */
+    private readonly channelDispatcher;
+    /**
+     * 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: string): ResolvedRealtimeChannel | null;
+    /** Where the user's per-channel "how much can the agent see" choices are kept. Replace with {@link SetExposurePreferences}. */
+    private exposurePreferences;
+    /**
+     * 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: IChannelExposurePreferences): void;
+    /** The store the user's per-channel exposure choices are currently kept in (so a host can wrap it). */
+    get ExposurePreferences(): IChannelExposurePreferences;
+    /** Whether user settings can be written: a signed-in user on a provider that has entity metadata. */
+    private canPersistUserSettings;
+    /**
+     * 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: string): RealtimeChannelExposure | 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: string, level: RealtimeChannelExposure | undefined): boolean;
+    /** Pushes a channel's current exposure inputs (server policy, user choice) into the channel. */
+    private applyChannelExposure;
+    /**
+     * 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.
+     */
+    private sendChannelVideoFrame;
+    /**
+     * 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.
+     */
+    private syncChannelVideoSource;
+    /** Follows the session client's video-source arbiter so {@link VideoSources$} reflects it. */
+    private watchVideoSources;
+    /** The channel whose surface the user is looking at, kept so it applies to an arbiter created after it was set. */
+    private focusedChannelKey;
+    /**
+     * 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: string | null): void;
+    /** Stops following the arbiter and clears {@link VideoSources$}. Safe to call when nothing is watched. */
+    private unwatchVideoSources;
+    private stopWatchingVideoSources;
+    /**
+     * 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.
+     */
+    SetVideoSourceEnabled(sourceId: string, enabled: boolean): boolean;
     /**
-     * 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.
+     * 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: string | null): boolean;
+    /**
+     * 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(): readonly BaseRealtimeChannelClient[];
+    /**
+     * 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.
      */
     private startChannels;
     /**
-     * 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.
+     * 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}).
+     */
+    private prepareChannelScope;
+    /**
+     * 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.
      */
-    private loadActiveChannels;
+    private prepareChannels;
     /**
-     * Reads the ACTIVE `MJ: AI Agent Channels` rows. 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.
+     * 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).
+     */
+    private loadChannelClasses;
+    /** Whether a prepared plugin's descriptor can be read; logs and rejects one that throws. */
+    private canDescribe;
+    /** Builds a plugin from a host declaration; `null` (logged) when it names nothing buildable. */
+    private createHostChannelPlugin;
+    /**
+     * 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.
+     */
+    private activateChannels;
+    /**
+     * 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.
+     */
+    private applySessionClientPolicy;
+    /** Drops plugins that were prepared for a start that never mounted them. They were never initialized, so there is nothing to release. */
+    private discardUnmountedChannels;
+    /**
+     * 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.
      */
     private fetchChannelDefinitions;
     /**
-     * The connect-only path of {@link fetchChannelDefinitions}: the same ACTIVE `MJ: AI Agent Channels`
-     * rows, 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.
+     * 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.
      */
     private fetchChannelDefinitionsOverGraphQL;
     /**
@@ -854,45 +1404,108 @@ export declare class RealtimeSessionRuntime {
      * 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.
      */
     private resolveChannelPlugin;
     /**
-     * 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.
+     */
+    private mountChannel;
+    /** Records that the agent acted on a channel (the overlay's first-use reveal signal). */
+    private noteChannelActivity;
+    /**
+     * 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.
+     */
+    private mountAdvertisedChannel;
+    /** Tells a channel the session is connected, containing anything it throws. */
+    private notifyChannelSessionStarted;
+    /** Finds a session channel (open or merely advertised) for the dispatcher. */
+    private findDispatchableChannel;
+    /** The keys the agent can address, for "unknown channel" messages — channels with nothing to address are left out. */
+    private listAddressableChannelKeys;
+    /**
+     * 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.
+     */
+    private dispatchContextAction;
+    /**
+     * 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.
      */
-    private initializeChannel;
+    OpenChannel(channelKey: string, inputs?: JSONObject): Promise<RealtimeContextActionResult>;
+    /**
+     * 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.
+     */
+    private flushChannelCatalogNote;
+    /** One catalog entry: a channel's descriptor, whether it is open, and whether its tools were declared natively. */
+    private catalogEntry;
     /** Builds the host-services context one channel plugin sees (its only line to the session). */
     private buildChannelContext;
     /**
      * 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}.
+     */
+    private readonly appToolRegistry;
+    /**
+     * 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.
+     *
+     * 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.
      */
-    private readonly appClientToolHandlers;
+    RegisterAppClientTools(tools: ReadonlyArray<AppClientToolRegistration>, owner?: string): void;
+    /** Removes one owner's tools (and its place in the collision order). No-op when it has none. */
+    UnregisterAppClientTools(owner: string): void;
+    /** Removes every owner's tools. */
+    ClearAppClientTools(): void;
     /**
-     * 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.
-     *
-     * @param tools The current surface client tools (name + handler). Descriptions/schemas ride the
-     *   app-context manifest separately; only the executable handler is needed here.
+     * 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.
      */
-    RegisterAppClientTools(tools: ReadonlyArray<{
-        Name: string;
-        Handler: (params: Record<string, unknown>) => Promise<unknown> | unknown;
-    }>): void;
+    private resolveAppClientTools;
     /**
      * 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.
      */
     private executeAppClientTool;
+    /** The model-readable reason a client tool could not run. */
+    private describeMissingClientTool;
     /**
      * Runs a channel-specific GraphQL operation through the live session's provider (the
      * {@link RealtimeChannelContext.ExecuteServerAction} implementation). Best-effort: any
@@ -914,6 +1527,8 @@ export declare class RealtimeSessionRuntime {
      * never affected.
      */
     private applyPriorChannelStates;
+    /** Offers one plugin its prior-session state, if there is one. Rejections and throws are logged, never fatal. */
+    private restorePriorChannelState;
     /**
      * Persists a channel's state as a first-class versioned artifact (`MJ: Artifacts`) via the
      * `SaveSessionChannelArtifact` mutation — the channel-context capability behind e.g. the
@@ -945,8 +1560,10 @@ export declare class RealtimeSessionRuntime {
     private createRealtimeClient;
     /**
      * Builds the client-direct session config the realtime client connects with.
-     * Aggregates tracks sourced by active channels under {@link REQUESTED_TRACKS_SESSION_KEY} 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: StartRealtimeClientSessionResult): ClientRealtimeSessionConfig;
     /** @deprecated Use {@link BuildClientConfig}. */
@@ -959,6 +1576,14 @@ export declare class RealtimeSessionRuntime {
     private parseSessionConfig;
     /** Subscribes this service's policy handlers to the realtime client's events. */
     private wireClientHandlers;
+    /**
+     * 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.
+     */
+    private onAgentVideo;
+    /** Clears {@link AgentVideo$} when the call's client goes. */
+    private clearAgentVideo;
     /** Maps a client state event onto the UI connection state. */
     private onClientStateChange;
     /**
@@ -969,6 +1594,11 @@ export declare class RealtimeSessionRuntime {
     private mapClientState;
     /** True when the live control channel is usable (open and not torn down / failed). */
     private isSessionLive;
+    /**
+     * 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.
+     */
+    private setConnectionState;
     /**
      * Applies transcript policy to client transcript events. Interim deltas don't become
      * captions/turns (the client already drives the speaking state) but DO mark this turn's
@@ -1040,6 +1670,14 @@ export declare class RealtimeSessionRuntime {
      * for the surface panel's artifact tabs.
      */
     private emitDelegationResult;
+    /**
+     * 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.
+     */
+    private offerDelegationArtifacts;
     /**
      * Cancels ONE in-flight delegated tool call — the overlay's per-card ✕ affordance.
      *
@@ -1073,7 +1711,12 @@ export declare class RealtimeSessionRuntime {
      * 0 on a structured failure or a thrown transport error (both logged, never thrown).
      */
     private cancelSessionTool;
-    /** Calls the `StartRealtimeClientSession` mutation to obtain an ephemeral token + config. */
+    /**
+     * 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.
+     */
     private mintSession;
     /** Calls the `ExecuteRealtimeSessionTool` mutation; returns the ResultJson string. */
     private executeSessionTool;
@@ -1121,9 +1764,14 @@ export declare 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.
      */
     private onUsageDelta;
+    /** Schedules the debounced usage relay unless one is already pending. */
+    private armUsageFlush;
     /** Clamps a driver-reported token delta: undefined / negative / non-finite become 0. */
     private clampUsageDelta;
     /**
@@ -1228,6 +1876,11 @@ export declare class RealtimeSessionRuntime {
     private teardown;
     /** The body of {@link teardown}; never called concurrently with itself. */
     private runTeardown;
+    /**
+     * 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.
+     */
+    private releaseMicrophone;
     /** Calls the `CloseAgentSession` mutation (provisioned in P4b). */
     private closeServerSession;
     /** Pushes a caption onto the live list (immutable update for change detection). */